@lotics/cli 0.321.125 → 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.
@@ -137,6 +137,8 @@ export interface ToolExecuteResult {
137
137
  breaking_changes?: readonly ToolBreakingChange[];
138
138
  /** Every row of the write the table refused, where `error` names a few per reason. */
139
139
  refused?: readonly ToolRefusedRow[];
140
+ /** The id a refused write's body is held under for an hour: `lotics run <tool>` with `held_id` and only what changes. Absent from a server older than it. */
141
+ held_id?: string;
140
142
  }
141
143
  export interface ToolInfo {
142
144
  name: string;
@@ -6,7 +6,7 @@ reach them, over MCP and as `lotics run <tool>`:
6
6
 
7
7
  | Tool | Answers |
8
8
  |---|---|
9
- | `get_app` | The app's `catalog`: its queries and workflows by alias, each one's description, its params or inputs with their types and legal values, and under a query's line its output columns (`returns`) — beside what each table they name holds, in its owner's words — and, for the app's author, `notes`: what its stored tree compiles with, each at its address under its rule id (`list.layout-call`, a root List drawing a table over rows a board layout would draw, with the layouts to state; `list.filter-unshown`, a filter no row draws, which the app leaves out) |
9
+ | `get_app` | The app's `catalog`: its queries and workflows by alias, each one's description, its params or inputs with their types and legal values, and under a query's line its output columns (`returns`) — beside what each table they name holds, in its owner's words — and, for the app's author, `notes`: what its stored tree compiles with, each at its address under its rule id (`list.layout-call`, a root List drawing a table over rows a board layout would draw, with the layouts to state; `list.column-drawn`, a column the row already draws, which the app shows once) |
10
10
  | `run_app_query` | The rows, a count or the groups of one query — or of several in one call |
11
11
  | `run_app_workflow` | One write — or several in order — or a dry run of it that writes nothing |
12
12
 
@@ -80,6 +80,7 @@ the screen already holds.
80
80
  | `<entity>_sub_counts_by_<link>` | How many <entity> rows stand under each <entity> row handed in, through <link>, at each status. | `<entity>_ids` | a record's rows block over a hierarchy (`nests`), for the rows it draws |
81
81
  | `<entity>_plan_places` | Every <place> the <entity> rows stand at, with what the plan draws of each. | | a register laid out as a `plan`: the places its rows stand at |
82
82
  | `<lane>_lanes` | The <lane> rows of one <scope entity>, each a lane of the board. | `<scope entity>_id` | a lanes board inside an app stating `scope` |
83
+ | `<lane>_<link>_holds` | The <entity> rows the capacity rule counts for each <lane>, whose span meets the days in view. | `from`; `to` | what a lanes board's heads count as held: a lanes board over a capacity rule (`no_overlap` by the lanes' link with a `quantity` or a `limit`) |
83
84
  | `<entity>_same_<link>` | The <entity> rows naming one "<link>". | `same`; `before` where its line reads rows before a moment | a statement line that carries rows (`parts`) |
84
85
 
85
86
  <!-- generated:end screen-queries -->
@@ -1,8 +1,8 @@
1
1
  # App architecture — which apps, and who gets each
2
2
 
3
- **Which apps.** One app per main entity, a thing the owner's words give its own list. A row that makes sense only under one parent (an employee's contracts, an order's lines) is a child List on the parent's page, never another app or a Tab. A second root List is rare: one job working two unrelated entities side by side. A related row's value on the list is a lookup column; work over many rows (a month's payroll) an Act on the list's rows. A person's part of the work doesn't make an app; a different job may.
3
+ **Which apps.** One app per job. Most jobs are about one thing the owner's words give its own list, so most apps hold one List. A job that works several things in the same sitting (a front desk booking visits, checking guests in and ringing back results) is one app holding those Lists: the test is the same person needing both in one sitting, never one role using both. An app draws a full page only for the tables its Lists and Records name; a row of any other table opens as its name and line. A row that makes sense only under one parent (an employee's contracts, an order's lines) is a child List on the parent's page, never another app or a Tab. A related row's value on the list is a lookup column; work over many rows (a month's payroll) an Act on the list's rows. A person's part of the work doesn't make an app; a different job may.
4
4
 
5
- One bakery's wholesale arm, five people, seven apps:
5
+ One bakery's wholesale arm, five people, seven apps, each job about one thing:
6
6
 
7
7
  | App (its list) | Opened by | On a row's page |
8
8
  |---|---|---|
@@ -32,7 +32,7 @@ How each tree is composed is `design`.
32
32
 
33
33
  ## Who gets each
34
34
 
35
- Who does which job is asked in `build`'s one message before the first write. An app stays with admins until the answer comes, and sharing waits on it. `set_access` then gives each app to everyone who works its rows (ids from `get_workspace` kind `member`, which lists the people in this workspace); none loses access. Someone who works its rows and is not in the workspace is added first by an admin of the workspace (`set_members`, `role: "member"`), since a share reaches only people in the workspace. They need no
35
+ Who does which job comes from the request, the owner's answer where you asked, or your assumption named in the report (`build` step 0). An app nobody shares opens for admins alone, so `set_access` gives each app to everyone who works its rows (ids from `get_workspace` kind `member`, which lists the people in this workspace); none loses access. Someone who works its rows and is not in the workspace is added first by an admin of the workspace (`set_members`, `role: "member"`), since a share reaches only people in the workspace. They need no
36
36
  table access: an app runs as its owner. With no `rows` on the App they read every row; where people differ, `rows`
37
37
  states one rule per table (`reference/read-scope`):
38
38
 
package/docs/build.md CHANGED
@@ -2,11 +2,17 @@
2
2
 
3
3
  Build from this page, `design` and the treatment the rows call for; a refusal names the `reference/<id>` page for the rest. The worked business: a bakery takes cake orders at the counter, a customer and one line per cake from the menu, moving taken, baking, ready, collected, with a slip printed when ready.
4
4
 
5
- `get_workspace` shows what already exists and `get_app` an app's tree: an app added or changed later starts there and states only the difference (`reference/changing-an-app`). Each write to an app makes a new version of it, and the live app is the only copy; sending an earlier tree restores the app, never a table or a row a write made, so try a write on a throwaway row. Before the first write, send the person who asked one message covering: the jobs and lists this business runs beyond those named, the trade's usual ones stated as defaults that stand; who does each job (`get_workspace` kind `member` lists the organization's people, not who works in this business or what each does); and the lists and papers they already keep, attached. A busy owner answers what comes first, so the message's first line is its first question, and it asks only what their papers and your defaults cannot settle, among them the papers they keep, asked by what they hold, and what else they keep track of; the defaults come after. "Go ahead" is a full answer. No second round: build from the answer, and a paper or list that does not come with it is never waited for — build from your defaults now and say in your report which papers would sharpen it. A short request names a business, not everything it runs on, so the workspace holds what that kind of business can't run without, such as what must never happen, what people are paid for and the papers it sends; your report names what you assumed, for them to change. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).
5
+ `get_workspace` shows what already exists and `get_app` an app's tree: an app added or changed later starts there and states only the difference (`reference/changing-an-app`). Each write to an app makes a new version; sending an earlier tree restores the app, never a table or a row a write made, so try a write on a throwaway row. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).
6
+
7
+ Before the first table, `set_workspace` states the business's `timezone` (how every date buckets and what "today" is), `default_currency` (what an amount with no stated currency means) and `organization_language` (the language its papers, invitations and members default to, `vi` until set): every row and paper made after reads them.
8
+
9
+ ## 0. The day's work
10
+
11
+ Before the first table, ask the person who asked for the papers and lists the business keeps, as the files themselves (its sheets, forms, slips), unless they are attached or the person said to go ahead without them: they name the day's work and hold rules no assumption reaches. Then name the jobs done most often and first in the day, the ones the request names and the rest a business of its kind does daily (what comes in, what goes out, what is counted or billed), and the exceptions each meets (the common ones: going back a step, correcting a locked record, work in parts or split, data late or out of order, a cancel, closing only once the work before is done; build those this work meets, not the list). Build every one of those jobs first, each from the screen it starts on, from the papers and, where they are silent, from how this kind of business runs; name each assumption in your report for the owner to change. Who does a job matters where the work says so: a step another person approves, data not everyone may see, and who each app is given to (`get_workspace` kind `member` lists the organization's people, not who does what here). Whether to ask more than the papers is your call; two questions usually settle the rest: what work happens most often, and what must never go wrong.
6
12
 
7
13
  ## 1. Tables and their checks: `set_tables`
8
14
 
9
- Linked tables go in one call, since they name each other by `ref`; `records` and checks may follow in the next call, so a refusal costs a patch rather than the whole document. A new table is named by its `ref`, which becomes its alias. One table per kind of thing, one column per fact, a link wherever one record points at another (`data_model`). A status is the stage of the work; a touch ("called") is a log row, a money fact ("paid in full") a formula, a quantity a number with its unit in `notation`. Read `design` before stating `records`, since a row's face, picture and mark are stated there, and so is what goes wrong on a row and needs someone to act: an issue (`design/issues`). Over rows already there, read a sample before building on a field: one mostly empty holds up no screen. A table people work states `title` (who or what a row is; a code only where nothing else names it), `records` (an app over a table without it is refused) and `singular` (so is an Add over a table lacking it).
15
+ Linked tables go in one call, since they name each other by `ref`, which becomes the table's alias; `records` and checks may follow in the next call, so a refusal costs a patch. One table per kind of thing, one column per fact, a link wherever one record points at another (`data_model`). A view can ask a shape of the rows (a floor plan: the places as rows of their own; a roster: one row per person per day; lanes: the day or the hours on the row), so choose each job's view in `design/treatments` before its tables. A status is the stage of the work; a touch ("called") is a log row, a money fact ("paid in full") a formula, a quantity a number with its unit in `notation`. Read `design` before stating `records`, since a row's face, picture and mark are stated there, and so is what goes wrong on a row and needs someone to act: an issue (`design/issues`). Over rows already there, read a sample before building on a field: one mostly empty holds up no screen. A table people work states `title` (who or what a row is; a code only where nothing else names it), `records` (an app over a table without it is refused) and `singular` (so is an Add over a table lacking it).
10
16
 
11
17
  ```json
12
18
  {
@@ -44,7 +50,10 @@ Linked tables go in one call, since they name each other by `ref`; `records` and
44
50
  "records": {"subtitle": ["customer"], "figure": "total", "due": ["pay_by"], "settled": "paid", "status": {"field": "stage", "closed": ["collected"]}},
45
51
  "checks": {"pay_by_before_pickup": {"on": ["create", "update"], "field": "pay_by",
46
52
  "when": "!isNull(record.pay_by) && !isNull(record.due_on)", "fail_when": "record.pay_by > record.due_on",
47
- "message": "\"Pay by the pickup day, \" + formatDate(record.due_on)"}}
53
+ "message": "\"Pay by the pickup day, \" + formatDate(record.due_on)"},
54
+ "baking_has_a_pickup_day": {"on": ["create", "update"], "field": "due_on",
55
+ "fail_when": "record.stage != \"taken\" && isNull(record.due_on)",
56
+ "message": "\"A cake past Taken has its pickup day\""}}
48
57
  },
49
58
  {
50
59
  "ref": "cake_line", "label": "Cakes on orders", "singular": "Cake", "title": "item",
@@ -62,27 +71,27 @@ Linked tables go in one call, since they name each other by `ref`; `records` and
62
71
  }
63
72
  ```
64
73
 
65
- `default_from` copies the menu's price when a line is made, so a later change leaves taken orders alone. `min`, `unique` and a check hold on every write; a check's language is `workflows/table-checks`, an effect after a write a table workflow (`workflows/table-workflows`). A check at its smallest, under an alias in the table's `checks`: `{"on": ["create"], "fail_when": "record.quantity < 1", "message": "\"Quantity is at least 1\""}`; `message` is an expression, so fixed text is a quoted string. A check refuses the write, a table workflow's too, so it states only what the business says must never happen; a fact going out of line (stock short of what lines take, totals that do not match) is an issue the row keeps (`design/issues`).
74
+ `default_from` copies the menu's price when a line is made, so a later change leaves taken orders alone. `min`, `unique` and a check hold on every write, where an Act's `when` and `requires` hold only its own press: what a stage needs is a check (`baking_has_a_pickup_day`); a check's language is `workflows/table-checks`, an effect after a write a table workflow (`workflows/table-workflows`). A check's `message` is an expression, so fixed text is a quoted string. A check refuses the write, a table workflow's too, so it states what must never happen in this kind of business, said or not (paid above the invoice, stock below zero); a fact going out of line (stock short of what lines take, totals that do not match) is an issue the row keeps (`design/issues`).
66
75
 
67
- A `date` field is a day, or a moment with `"format": "datetime"`; a time of day is a `text` field with `"format": "time"`. Days between two dates in a formula is `differenceInCalendarDays(later, earlier)`; the helpers are named exactly (`reference/formula`). Two rows that must not hold one resource at once are the table's `no_overlap`: `{"from": "start_at", "to": "end_at", "by": "room"}`, a list where a row holds two resources (`reference/no-overlap`).
76
+ A `date` field is a day, a moment with `"format": "datetime"` or a month (a period) with `"format": "month"`; a time of day is a `text` field with `"format": "time"`. Days between two dates in a formula is `differenceInCalendarDays(later, earlier)`; the helpers are named exactly (`reference/formula`). Two rows that must not hold one resource at once are the table's `no_overlap`: `{"from": "start_at", "to": "end_at", "by": "room"}`, a list where a row holds two resources (`reference/no-overlap`).
68
77
 
69
78
  ## 2. The paper: `set_template`
70
79
 
71
- An Act names a template by its alias, made from its name (`order_slip`), so the paper comes first.
80
+ An Act names a template by its alias, made from its name (`order_slip`), so the paper comes first. A paper the owner hands over as a Word or Excel file becomes a template of that type; an html template is for a paper with no file of its own, and prints to the sheet's edge unless it states `@page { margin }`.
72
81
 
73
82
  ```
74
83
  set_template {"type": "html", "name": "Order slip",
75
- "template": "<h1>{{reference}}</h1><p>{{customer}}, {{date due_on}}</p>{{#each lines}}<p>{{item}} × {{quantity}}</p>{{/each}}<p>{{money total \"USD\"}}</p>",
84
+ "template": "<style>@page { margin: 15mm }</style><h1>{{organization.name}}</h1><h2>{{reference}}</h2><p>{{customer}}, {{date due_on}}</p>{{#each lines}}<p>{{item}} × {{quantity}}</p>{{/each}}<p>{{money total \"USD\"}}</p>",
76
85
  "variables": {"reference": "string", "customer": "string", "due_on": "string", "lines": "array", "total": "string"}}
77
86
  ```
78
87
 
79
- One template per paper the owner sends. A slot is named after a field of the record; the cakes loop under the name of the link to them (`lines`). More: `document_templates`.
88
+ One template per paper the owner sends. A slot is named after a field of the record, and `{{organization.name}}` prints the business's name, never passed; the cakes loop under their link's name (`lines`). More: `document_templates`.
80
89
 
81
90
  ## 3. The app and its acts: `set_app`
82
91
 
83
92
  **Which apps**, and who gets each, is `app_architecture`. **How each row reads** comes before the first List: `design/treatments` names the view per kind of row.
84
93
 
85
- **Start from one root List.** `{"type": "List", "entity": "cake_order"}` in the App's `children` is a whole app: the platform composes the page every row opens, the add and the Delete, and stores them. State only the difference from what it composes.
94
+ **Start from one root List.** `{"type": "List", "entity": "cake_order"}` in the App's `children` is a whole app: the platform composes the page every row opens, the add and the Delete. State only the difference.
86
95
 
87
96
  ```json
88
97
  {
@@ -95,40 +104,39 @@ One template per paper the owner sends. A slot is named after a field of the rec
95
104
  ],
96
105
  "pages": [
97
106
  {"type": "Record", "entity": "cake_order", "children": [
98
- {"type": "Steps", "children": [
99
- {"type": "Section", "title": "Order", "at": ["taken", "baking"], "children": [
100
- "due_on",
101
- "pay_by",
102
- {"type": "List", "entity": "cake_line", "create": ["item", "quantity"]},
103
- {"type": "Act", "key": "start_baking", "label": "Start baking", "when": {"stage": ["taken"]}, "requires": ["due_on"], "asks": ["prepaid"], "set": {"stage": "baking"}},
104
- {"type": "Act", "key": "ready", "label": "Ready", "when": {"stage": ["baking"]}, "set": {"stage": "ready"}, "template": "order_slip", "into": "slip"}
105
- ]},
106
- {"type": "Section", "title": "Pickup", "at": ["ready"], "children": [
107
- {"field": "slip", "edit": false},
108
- {"type": "Act", "key": "collect", "label": "Collected", "when": {"stage": ["ready"], "paid": true}, "set": {"stage": "collected"}}
109
- ]}
110
- ]}
107
+ {"type": "Steps"}, "due_on", "pay_by", "slip",
108
+ {"type": "List", "entity": "cake_line", "create": ["item", "quantity"]},
109
+ {"type": "Act", "key": "start_baking", "label": "Start baking", "when": {"stage": ["taken"]}, "requires": ["due_on"], "asks": ["prepaid"], "set": {"stage": "baking"}},
110
+ {"type": "Act", "key": "ready", "label": "Ready", "when": {"stage": ["baking"]}, "set": {"stage": "ready"}, "template": "order_slip", "into": "slip"},
111
+ {"type": "Act", "key": "collect", "label": "Collected", "when": {"stage": ["ready"], "paid": true}, "set": {"stage": "collected"}}
111
112
  ]}
112
113
  ]
113
114
  }
114
115
  }
115
116
  ```
116
117
 
117
- **How a status draws follows the work, never this example.** The order states `Steps` because its stages hold something of their own: the lines it bakes from, the slip its Act files. A status whose Acts only move the row on states no `Steps` and draws as a line of steps. One a person sets by hand, closing nothing or moved by no Act, draws as its select (`design`, Stages).
118
+ **A status the work walks in order states `Steps`.** Bare where no stage has a form, it draws as the line of steps (the counter's); a state a row moves between (active, paused, ended) states none (`design`, Stages). Where a stage has its own form, `Steps` replaces the page's fields and Lists, a Section per stage that has its own form or list, the Acts beside it; an Act asking a value or filing a paper needs no Section:
119
+
120
+ ```json
121
+ {"type": "Steps", "children": [
122
+ {"type": "Section", "at": ["taken"], "children": ["due_on", "pay_by", {"type": "List", "entity": "cake_line", "create": ["item", "quantity"]}]},
123
+ {"type": "Section", "at": ["ready"], "children": ["slip"]}
124
+ ]}
125
+ ```
118
126
 
119
- **Give each main List a band** of what its person watches, a figure or a chart in its `children`, never a bare count.
127
+ **Give each main List a band** of what its person watches, a figure or a chart in its `children`; a count is already the summary line's.
120
128
 
121
- **A press can be a mistake.** An Act also moves a row back (`when` the later stage, `set` the earlier), at the foot of the Section of the stage it leaves. **Someone with no seat** who signs or approves one record, a customer or a supplier, gets a Record's `Outside`: a link a member makes of that record.
129
+ **A press can be a mistake.** An Act also moves a row back (`when` the later stage, `set` the earlier), standing beside the Act that moves it on. A close whose work can be left unfinished waits on it (`when`, a Check), and work that can be abandoned (a cancelled order) closes at an option `dropped` names. **Someone with no seat** who signs or approves one record, a customer or a supplier, gets a Record's `Outside`: a link a member makes of that record.
122
130
 
123
- `dry_run` checks a body and writes nothing; then share each app (`app_architecture`). An Act's or stage's `owner` decides who presses.
131
+ A refused write writes nothing and lists every finding of the step it reached, the tree's form before the rest; the body it judged, and a dry run's, is held for an hour under the `held_id` the answer states, so send only what changes: `held_id` with `body` and `nodes` (`tables` for `set_tables`, `edits` for `set_workflow`) merges into the held call, so a key left out stays and `null` removes it; `held_id` alone writes it as held, with the `force` it was judged under. `dry_run` answers what a change to an app in use would grant and take away. Then share each app (`app_architecture`). An Act's or stage's `owner` decides who presses.
124
132
 
125
- ## 4. What the owner will ask an agent: Query and Workflow nodes
133
+ ## 4. What the owner's assistant may read and do: Query and Workflow nodes
126
134
 
127
- What the business asks its assistant again and again (orders waiting for pickup) is a Query or Workflow node of the app, with a `description` for an agent that has not seen the screen (`agent_surface/declaring-more`). A figure's name is not its definition: which rows count, by which field, now or over a window, is the owner's; where no field holds it, say so rather than total a near one. The App's `description` heads what a member's chat agent reads every turn, so a standing process the app expects of it goes there. A connected service is reached by a Workflow node's step (`workflows`).
135
+ What the owner's agent is asked and no screen draws is a Query or Workflow node beside the Lists (`agent_surface/declaring-more`). A node's `description` is written for an agent that has not seen the screen (orders waiting for pickup). A figure's name is not its definition: which rows count, by which field, now or over a window, is the owner's; where no field holds it, say so rather than total a near one. The App's `description` heads what a member's chat agent reads every turn, so a standing process the app expects of it goes there. A connected service is reached by a Workflow node's step (`workflows`). Only a List or Record of a table draws it; a table its Query or Workflow nodes only read is named in the App's `uses`, never drawn.
128
136
 
129
137
  ## 5. The owner's rows: `create_records`
130
138
 
131
- Batch the owner's rows: the customers and menu, then the orders, linked by the ids those calls return, then each order's cakes (`field_values` has the value each type takes). Load as an admin: a row past the first stage is refused unless that stage's owner or an admin makes it, and a row loaded at a later stage states each earlier stage's date field (`<option>_at`). Example rows the papers ask for and do not list come from the owner's lists, each at the stage it should show, written like the owner's own rows (no flag field, no "Example" in a name) and listed in your report for the owner to keep or delete. An owner who sent no lists opens what you leave, so a few example rows, listed the same way, show them the app working.
139
+ Batch the owner's rows: the customers and menu, then the orders, linked by the ids those calls return, then each order's cakes (`field_values` has the value each type takes). Load as an admin: a row past the first stage is refused unless that stage's owner or an admin makes it, and a row loaded at a later stage states each earlier stage's date field (`<option>_at`). Leave some rows in before handing over: the owner's own where they gave them, and a few example rows where a list or a board would otherwise stand empty (the coming rows of anything that recurs among them), written like the owner's own at the stages the work passes through. An example never changes an owner's row (its stage, its stock, what it holds) nor takes a number the business's papers are numbered by. They show you and the owner each screen with something on it. Say in the handover which rows are examples and that you will clear them whenever the owner asks; the owner's rows for one table leave another's examples standing.
132
140
 
133
141
  ```
134
142
  create_records {"table_id": "cake_line", "field_keys": ["order", "item", "quantity"],
@@ -137,7 +145,7 @@ create_records {"table_id": "cake_line", "field_keys": ["order", "item", "quanti
137
145
 
138
146
  ## 6. Verify: `run_app_workflow`, `screenshot_app`
139
147
 
140
- Move the owner's rows through the app as their person would, each only as far as the stage the owner says it is at. Every Act runs as `act_<key>`, the one name, handed what it asks. A dry run walks the moves and files nothing; then press each paper Act for real, on one row the owner's stage allows or on an example row left at its last stage: what is left on a row is what the owner opens. Prove a rule by sending the write with `dry_run: true`; never switch a check off. Only an admin passes `as_member`: it shows a member's view and reads, which is how each person's screen is checked. What the shots and runs must show is `design/the-rubric`.
148
+ Move the owner's rows through the app as their person would, each only as far as the owner's stage for it. Every Act runs as `act_<key>`, the one name, handed what it asks. A dry run walks the moves and files nothing; then press for real each paper Act you may press, on one row the owner's stage allows or on an example row left at its last stage: what is left on a row is what the owner opens. A press is made by the member who makes it, so an Act another member owns is proved by a dry run as that member (`as_member`), which renders its paper and keeps the file; an example row at a later step is created there with that file in its files field, and the owner's rows move only by their Acts. Prove a rule by sending the write with `dry_run: true`; never switch a check off. Only an admin passes `as_member`. What the shots and runs must show is `design/the-rubric`.
141
149
  ```
142
150
  run_app_workflow {"app_id": "app_…", "alias": "act_start_baking", "inputs": {"record_id": "rec_…", "prepaid": 20}, "dry_run": true}
143
151
  screenshot_app {"app_id": "app_…", "as_member": "<member id>", "pages": [{}, {"record_id": "rec_…"}]}
@@ -145,6 +153,6 @@ screenshot_app {"app_id": "app_…", "as_member": "<member id>", "pages": [{}, {
145
153
 
146
154
  ## 7. Hand over
147
155
 
148
- Name the workspace and its organization after the business with `set_workspace` (`name`, `organization_name`, and `organization_language`: the language its papers, invitations and members default to, `vi` until set), and leave standing instructions there (`instructions`, one entry per rule, keyed by the job it serves): who the business is, its people's words, and what the rows cannot tell an agent (the day its records begin). As an admin, invite the people named with `set_members` (`members` keyed by email, role `member` or `admin`), else say whom to invite.
156
+ Name the workspace and its organization after the business with `set_workspace` (`name`, `organization_name`), and leave standing instructions there (`instructions`, one entry per rule, keyed by the job it serves): who the business is, its people's words, and what the rows cannot tell an agent (the day its records begin). As an admin, invite the people named with `set_members` (`members` keyed by email, role `member` or `admin`), else say whom to invite.
149
157
 
150
- Before you report, answer each question of `design/the-rubric` with a call, and put right or name each gap. Then show the owner what you built, job by job, each paper and what makes it, with the choices you made for them to change.
158
+ Before you report, answer each question of `design/the-rubric` with a call, and put right or name each gap. Then show the owner what you built, job by job, each paper and what makes it; only what no daily job needs is named as not built.
@@ -7,7 +7,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
7
7
  | `lotics` / `lotics --help` | Show full help: capabilities, the verb list (§ COMMANDS), flags, config. `lotics <verb> --help` prints that verb's entries alone (`lotics app --help`, `lotics file download --help`); `lotics report --help` prints the report frame. |
8
8
  | `lotics auth login` | Sign this terminal in, on a machine holding no key; a person with no account creates one on the page it opens. It takes no argument and sends no mail. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>` — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code, pick the organization and press Confirm. A person with no account creates one there, by email and a password or with Google: the page shows the code beside the button, and one press creates the account and its first workspace and signs the terminal in; creating the account accepts the Terms and Privacy Policy. A signed-in account with no workspace gets one button that creates the workspace and signs the terminal in. On a private instance, whose people arrive by invitation, the page sends a signed-out person to sign in. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `docs` among them — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
9
9
  | — | **A flag is refused on a verb that does not read it**, naming the verbs that do, before any request or credential: `--check` on `lotics run` would otherwise be parsed and ignored, and the write it was meant to stop would run. `--json`, `--workspace`, `--api-key` and `--timeout` are read by every verb. |
10
- | — | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: "outcome_unknown"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code`, `request_id`, `field_errors`, `breaking_changes` and `refused` where the error has them; `refused` is every row a write of several had refused, where `error` names five per reason: `{record_id, message, field_key?}` for a row named by the id the call passed, `{row, message, field_key?}` (`records[3]`) for one named by its place. |
10
+ | — | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: "outcome_unknown"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code`, `request_id`, `field_errors`, `breaking_changes`, `refused` and `held_id` (the id a refused write's body is held under for an hour: run the tool again with `held_id` and only what changes) where the error has them; `refused` is every row a write of several had refused, where `error` names five per reason: `{record_id, message, field_key?}` for a row named by the id the call passed, `{row, message, field_key?}` (`records[3]`) for one named by its place. |
11
11
  | `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
12
12
  | `lotics auth web` | Send a magic link email to access the web app (requires auth) |
13
13
  | `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key — read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |
@@ -49,7 +49,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
49
49
  | `lotics knowledge restore <id...>` | Bring deleted docs back via `set_knowledge` (`{ knowledge_doc_id, restore: true }`), one call per id: each must be a deleted doc you manage, and the command reports which succeeded and which failed. Refuses the no-argument form. |
50
50
  | `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`) and links `[path]` (default `./<name>`, made when absent) to it by writing `package.json#lotics` (the app and its workspace, which is how `app deploy` in that directory finds both) — into the project's own `package.json` when it has one, every other key kept, otherwise a `package.json` holding the link alone. Nothing else is written and nothing is installed: the project is yours. `app deploy` needs `@lotics/app-sdk` (React 19) and an `npm run build` that writes a static `dist/` with an `index.html`. A directory already linked to an app is refused before the app row exists. The app has no version until the first `lotics app deploy`. `--custom` is required: a JSON app is made by `lotics app apply` (the tool `set_app`). The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` once the project installs it. |
51
51
  | `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (its identity and Query nodes) as its source; an app whose stored tree does not read in this release is pulled as it is stored, with a warning giving the reason `get_app` gives (where the stored value is not a JSON object, nothing is pulled and the reason is the error); an app that shows the caller no body (the caller does not author it, or it has no version) is refused. **A JSON app**: the tree is written as JSON to `[path]` (a directory receives `./<name>.app.json`; default `./<name>.app.json`), and the app's id and current version beside it in `<file>.lotics.json` (`{ "app_id": "…", "version_id": "…", "digest": "…" }`, the digest being the file as the CLI last left it; a record without all three is refused by `app apply`, naming `lotics app pull`) — a custom-code project records both in `package.json#lotics`, a single file has no such place — so the next `lotics app apply <file>` edits that app, and is refused if the app has since moved past that version. An existing file is overwritten only when its `.lotics.json` names this same app and the file is unchanged since it was last pulled or applied; a file with edits, or whose record names the app but no digest, is refused, naming `--force`, which overwrites it. `--force` is a flag of `app pull` alone. `--json` prints `{workspace_id, app_id, path, outcome}`. **A custom-code app**: its live source, as a project ready to deploy on it. The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** — but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`GET /v1/apps/{id}/types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). |
52
- | `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ "body": … }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` — a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `"type": "App"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour) and, where the file states `children`, its Query nodes, which replace every query it holds; a file stating none leaves its queries alone and no `<file>.lotics.json` records it, since an identity write makes no version — its source deploys with `app deploy`. **The file is never rewritten**: a node the tree leaves out draws as the rows call for it and is stored nowhere (`lotics docs design`). It prints what `set_app` answered and reports its `outcome`: its notes and findings, every finding at once, and the saves, adds and Deletes the write grants and removes. **`--check` sends `dry_run`** (a flag of `app apply` alone, as is `--app`) — what would refuse the tree, and what it would grant and remove — and writes nothing, the file and its sibling included; an `outcome` of `refused` exits 1. A tree the app already has, or one `set_app` answers `unchanged`, records the version the app stays at in the sibling. **To go back to an earlier version, apply the earlier tree again.** Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, app_id, outcome, write}`, `outcome` being `set_app`'s: `created`, `updated`, `unchanged` or `refused` (with `--check`, what it would be). |
52
+ | `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ "body": … }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` — a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `"type": "App"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour) and, where the file states `children`, its Query nodes, which replace every query it holds; a file stating none leaves its queries alone and no `<file>.lotics.json` records it, since an identity write makes no version — its source deploys with `app deploy`. **The file is never rewritten**: a node the tree leaves out draws as the rows call for it and is stored nowhere (`lotics docs design`). It prints what `set_app` answered and reports its `outcome`: its findings, every one at once, its notes under the heading of their kind (`Stated, and drawn differently:`, `Suggestions:`, `About this write:`), and the saves, adds and Deletes the write grants and removes. **`--check` sends `dry_run`** (a flag of `app apply` alone, as is `--app`) — what would refuse the tree, and what it would grant and remove — and writes nothing, the file and its sibling included; an `outcome` of `refused` exits 1. A tree the app already has, or one `set_app` answers `unchanged`, records the version the app stays at in the sibling. **To go back to an earlier version, apply the earlier tree again.** Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, app_id, outcome, write}`, `outcome` being `set_app`'s: `created`, `updated`, `unchanged` or `refused` (with `--check`, what it would be). |
53
53
  | `lotics app deploy [-m <message>]` | **Build this directory and upload it as a new version of the live app.** Rewrites `.lotics/` with the declarations of the app's live bindings (`GET /v1/apps/{id}/types`, replacing each file there), then runs the project's `npm run typecheck` (warned about when absent; a type error in the app's own files stops the deploy, one inside an installed package is reported and does not) and `npm run build`, tars the source (without `node_modules`, `dist`, `.git`, `*.tsbuildinfo`) and `dist/`, and posts both to `POST /v1/apps/{id}/versions` on the version `package.json#lotics.current_version_id` names, then stamps the new one there. The version carries the app's queries, workflows, agents and capabilities forward unchanged — those are written through their tools. A project with no `build` script, or whose `package.json#lotics` still declares `queries`, `workflows`, `agents` or `capabilities`, is refused before anything is built; the refusal names the tool that sets each. **A 409 because another version went live since this directory's last deploy** (a deploy from elsewhere, a rollback) prints the server's sentence and the version that is live, and names `lotics app pull`: run in this directory, it brings an unedited project up to date, and lists the files a project with edits changed, to carry over into a fresh pull. `-m` (or a bare positional) is the version's message, optional. The workspace comes from `package.json#lotics.workspace_id` unless `--workspace` / `LOTICS_WORKSPACE` names another. |
54
54
  | `lotics docs` \| `lotics docs <area>[/<section>]` \| `lotics docs [<area>[/<section>]] --grep <text>` | **This CLI's own references, carried inside the binary** — the model reference, this index, and every doc under `docs/` — so the doc a reader opens describes the binary answering, listed by the job a reader comes to do. Capped at ONE PAGE: a doc that does not fit prints its opening and the addresses of what it holds (`lotics docs <area>/<section>`, each section's size beside it, or a table's row names), and every address prints within a page. **A reference the binary's copy lacks, or a part of one the server serves, is read from the server's `docs` tool** with this machine's credential, after the copy's refusal — a page the server added since this binary was built, which a server refusal can cite. A name matching more than one reference, or a part missing from a guide to this CLI, is answered by the copy alone. **`--grep` searches the references the server serves** (not this CLI's own guides, which it refuses), with this machine's credential, narrowed to the area or section named: literal text unless `--regex`; a literal search that finds nothing while the pattern read as an expression matches (`a|b`) returns those lines under a note saying so, and `--literal` keeps the literal zero; with `--case-sensitive`, `--diacritic-insensitive`, `--context-lines <n>` and `--limit <n>` — the dialect the knowledge lines of `get_workspace` with `search` are read in — each hit under the address that opens its page; any of those options without `--grep` is refused. A custom-code app's SDK reference ships inside `@lotics/app-sdk` in the app's `node_modules`. |
55
55
  | `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script — the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe — a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |
@@ -22,6 +22,10 @@ it runs.
22
22
 
23
23
  - **Prefer the link, the select, or the formula.** Text is a RENDERING of a record; compose it when
24
24
  you read, rather than storing it a second time.
25
+ - **A fact another row owns (a supplier's rating, an item's unit) is read through the link** by a `lookup` or a
26
+ `rollup`, which the platform keeps in step with that row; a copy a workflow writes holds it as it stood when the
27
+ workflow ran, and nothing reports when the two differ. A value meant to stay as it was when the row was made (a price
28
+ quoted) is a `default_from` copy.
25
29
  - **Renaming, retyping or re-pointing the existing field beats adding another.** A field's key is
26
30
  stable, so a rename breaks nothing that addresses it by key.
27
31
  - **Superseding a field means DELETING it**, not leaving it beside its replacement with a
@@ -147,6 +151,7 @@ or a `notation` on another type, never a `type`:
147
151
  | Markdown | `{ type: "text", format: "markdown" }` |
148
152
  | Checkbox | `{ type: "boolean" }` |
149
153
  | Money | `{ type: "number", notation: { style: "currency", currency: "USD" } }` |
154
+ | Money whose currency differs by row | `{ type: "number", notation: { style: "currency", currency: { per_row: "<a single select of the row whose labels are ISO 4217 codes>" } } }` |
150
155
  | Quantity | `{ type: "number", notation: { style: "unit", unit: "kg" } }` |
151
156
  | Percentage | `{ type: "number", notation: { style: "unit", unit: "percent" } }` |
152
157
  | Datetime | `{ type: "date", format: "datetime" }` |
@@ -192,7 +197,7 @@ A table is named by its alias wherever a call names one (`table_id`, a link's `t
192
197
  The partner may stand on a table the call does not name: `pair: "<alias>"` makes it there, or pairs the one-way link that table
193
198
  already holds under that alias, and the answer lists that table among the call's. Only someone who manages that table may.
194
199
  - A formula's `output_type` is inferred from its expression; state it only to override.
195
- - **A call's removals are judged together, on what the call leaves.** A table and the links and lookups naming it, removed in one call, pass; every reader left outside the call is named in one answer, not one per retry. An app reading a field or an option that leaves is rebuilt in the same call, and the answer (a dry run too) lists each node of its tree that changed: a column, a filter, a sort key, a field of a part that only drew the field, a child List the platform composed is dropped when its link leaves, with the part left holding nothing by that and the page the platform composed for its rows; a step the platform composed is dropped when every option it stands at leaves; a filter whose field the rows no longer draw is left out; and an option leaves every list of options it stood in. What has no meaning without it refuses the call, naming the node: an act that sets a removed option, a part or step holding content you stated that is left with nothing, a child List you stated more of whose link leaves, a list that held only the removed option. An app drawing a field that is retyped, or a link pointed at another table, is rebuilt too, its tree unchanged: where the field no longer lets the tree draw what it drew, the call refuses, naming the node, and a field that became a formula, rollup, lookup or autonumber leaves the app's allowlist of saves. A workflow body its author wrote is never rewritten: it is checked again against the tables as the call leaves them, and the call refuses, naming the workflow, only if it no longer checks. A table's check or workflow that reads a retyped field or a link pointed elsewhere is judged the same way and refuses, naming it, only if it no longer holds. Deleting one field through the table's field route drops no node: an app whose tree draws the field refuses it, naming the node.
200
+ - **A call's removals are judged together, on what the call leaves.** A table and the links and lookups naming it, removed in one call, pass; every reader left outside the call is named in one answer, not one per retry. An app reading a field or an option that leaves is rebuilt in the same call, and the answer (a dry run too) lists each node of its tree that changed: a column, a filter, a sort key, a field of a part that only drew the field, a child List the platform composed is dropped when its link leaves, with the part left holding nothing by that and the page the platform composed for its rows; a step the platform composed is dropped when every option it stands at leaves; and an option leaves every list of options it stood in. What has no meaning without it refuses the call, naming the node: an act that sets a removed option, a part or step holding content you stated that is left with nothing, a child List you stated more of whose link leaves, a list that held only the removed option. An app drawing a field that is retyped, or a link pointed at another table, is rebuilt too, its tree unchanged: where the field no longer lets the tree draw what it drew, the call refuses, naming the node, and a field that became a formula, rollup, lookup or autonumber leaves the app's allowlist of saves. A workflow body its author wrote is never rewritten: it is checked again against the tables as the call leaves them, and the call refuses, naming the workflow, only if it no longer checks. A table's check or workflow that reads a retyped field or a link pointed elsewhere is judged the same way and refuses, naming it, only if it no longer holds. Deleting one field through the table's field route drops no node: an app whose tree draws the field refuses it, naming the node.
196
201
  - **A field something reads cannot go.** A query, a workflow, a check, an app only its owner can rebuild, or another
197
202
  table's formula, rollup, lookup or copy that reads the field refuses its deletion, naming the reader. Change or remove
198
203
  the reader first, or in the same call.
@@ -242,6 +247,8 @@ what rows hold.
242
247
  }
243
248
  ```
244
249
 
250
+ A select's options either all carry a `color` or none does: where some state one, each of the rest takes the next free colour.
251
+
245
252
  Splitting `queued` into waiting and underway is one call of the same shape:
246
253
 
247
254
  ```json5