@lotics/cli 0.318.21 → 0.318.23

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.
@@ -1,26 +1,28 @@
1
1
  # App architecture — a worked split
2
2
 
3
- The questions that split a business into apps are in `first_build`, § 3. This is one split they produce, settled before any tree is written because the split decides who sees what and where each table's rows are worked.
3
+ The rule that splits a business into apps is in `first_build`, § 3: one app per main entity, and everything that belongs to a row on that row's page. This is one split it produces, settled before any tree is written, since it decides who sees what.
4
4
 
5
- One furniture factory, six people, five apps and a dashboard:
5
+ One furniture factory, five people, seven apps:
6
6
 
7
- | App (the job's sentence) | Person | Register | Inside it |
8
- |---|---|---|---|
9
- | Sales desk: takes an order from quote to dispatch | Sales rep | Orders | Lines, the price book, the quote paper (an Act), the customer as a picker |
10
- | Production board: runs each work order through its stages | Foreman | Work orders | Steps, machines as lanes, the Acts that move a stage |
11
- | Purchasing: orders material against shortages | Buyer | Purchase orders | Lines, goods received, the supplier as a picker |
12
- | Warehouse: receives, issues and counts | Storekeeper | Stock items | Receive and Issue Acts, the log of movements |
13
- | Quality: inspects each finished lot | Inspector | Inspections | Checklist, photos, a pass or fail Act |
14
- | Owner's review: the week across jobs | Owner | none (Readings) | Orders late, stock short, margin by month |
7
+ | App (its list) | Opened by | On a row's page |
8
+ |---|---|---|
9
+ | Customers | Sales rep, owner | Their prices, orders and unpaid invoices |
10
+ | Products | Sales rep, foreman | Price breaks, bill of materials, stock on hand |
11
+ | Orders | Sales rep, foreman, owner | Lines, the quote paper (an Act), the work orders it starts |
12
+ | Work orders | Foreman | Steps, the Acts that move a stage, the inspection |
13
+ | Suppliers | Buyer | Their price list and purchase orders |
14
+ | Purchase orders | Buyer, storekeeper | Lines, goods received |
15
+ | Materials | Storekeeper, buyer | Movements in and out, the Receive and Issue Acts |
15
16
 
16
- Customers, suppliers, machines and the price book are tables with a `records` entry, never apps: each is picked,
17
- looked up or opened inside the job that uses it. Each app's `name` and `description` is its job's sentence:
17
+ An order's lines, a work order's steps and a customer's prices make sense only under their parent: each is a child
18
+ List on that row's page, never an app or a Tab. An order stands in the Orders app and on its customer's page: one
19
+ record, one page. The owner reads the figures each register leads with. Each app's `name` is its list and its `description` says what is worked there:
18
20
 
19
21
  ```json
20
22
  {
21
23
  "type": "App",
22
- "key": "sales_desk",
23
- "name": "Sales desk",
24
+ "key": "orders",
25
+ "name": "Orders",
24
26
  "description": "Takes a customer's order from quote to dispatch.",
25
27
  "children": [{ "type": "List", "entity": "order" }]
26
28
  }
@@ -29,11 +31,11 @@ looked up or opened inside the job that uses it. Each app's `name` and `descript
29
31
  ```json
30
32
  {
31
33
  "type": "App",
32
- "key": "production_board",
33
- "name": "Production board",
34
- "description": "Runs each work order through cutting, assembly and finishing.",
35
- "children": [{ "type": "List", "entity": "work_order" }]
34
+ "key": "customers",
35
+ "name": "Customers",
36
+ "description": "Each customer's prices, orders and what they owe.",
37
+ "children": [{ "type": "List", "entity": "customer" }]
36
38
  }
37
39
  ```
38
40
 
39
- Then `set_access` gives the sales desk to the sales group and the production board to the foreman's (`first_build`, § 3). How each tree is composed is `design`.
41
+ Then `set_access` gives each person only the apps beside their name (`first_build`, § 3). How each tree is composed is `design`.
@@ -218,7 +218,7 @@ you registered once (`lotics docs document_templates`).
218
218
  ## 7 — Look at it, then name it
219
219
 
220
220
  Look at every app you apply, at a desktop width and at a phone's — every check above reads the
221
- definition, none of them the pixels:
221
+ definition, none of them the pixels — and judge each shot against the visual bar `design` opens on:
222
222
 
223
223
  ```
224
224
  lotics run screenshot_app '{"app_id":"app_…"}' -o ./shots
package/docs/design.md CHANGED
@@ -1,31 +1,61 @@
1
1
  # Designing an app
2
2
 
3
- 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 `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`.
3
+ An app is a tree of components: a List of one table, the Record a row opens, its Sections, the Acts that move it. The
4
+ tree states COMPOSITION — which fields, lists and acts each job's screen holds; how each piece looks is the platform's,
5
+ one way per concept. A node the tree leaves out draws its default, from the table's facts (`records`, the stage, the
6
+ write rules): a List's Readings band, the stage buttons, the picture, a Record's Sections. State a node to change it,
7
+ or `false` at it to turn it off (`"readings": false`, `"row": { "image": false }`). A drawn Field is a control unless it
8
+ or its entity is read-only (`edit: false`); a stepped status never is, since Acts move it. Each prop's keys are in `reference`, a treatment
9
+ worked in a whole workspace is `examples/<treatment>`, and which apps a business needs is `first_build`, § 3.
10
+
11
+ **The visual bar.** Every screen is judged against it; a miss is a change to the tree.
12
+
13
+ - Each app looks like its own rows: the view its kind of row takes (`design/treatments`) — cards for things found by
14
+ their photo, a calendar or lanes for dated work, faces for people and organisations. A List left as a table is drawn
15
+ as one, the most common failure of an app; the answer of `set_app` notes what the rows call for that no default draws.
16
+ - What needs attention leads the row: `records.mark` on a select or a computed category (a formula stating its options;
17
+ where it is empty, its seat is blank). A yes that needs attention (papers still owed) is a `Check` of its List over a
18
+ yes/no formula, in the warning tone on the row's line; every other yes reads in the success tone.
19
+ - A list's columns: the name and its lead, the status, then the one or two columns the job reads on every row. Each
20
+ fact once: no column repeats the mark, status, subtitle or title.
21
+ - A list worked by a date states `sort` on that date's column, newest first; without one, a register reads newest made
22
+ first and a record's child List in the order its rows were added.
23
+ - Someone is a face wherever they are read: a link to a table stating `records.party` draws its row's face; a member
24
+ field is one already; select options naming people or organisations who are neither each take the `mark`
25
+ `{"kind": "avatar", "name": "person"}`, never a colour dot.
26
+ - A thing shows its picture, a file its preview, a plan its days on a time axis, a quantity a meter (`records.limits`) or
27
+ a chart, a register its Readings, and long text reads whole (a markdown Field; `block: true` on plain long text).
28
+ - Every category the job reads is coloured: each option's `color`, and a `mark` where a brand or glyph names it, on
29
+ every option of a select read down a column (how it was paid, the channel).
30
+ - Every app states its tile's `color`, apart from the workspace's other apps where it can be.
31
+ - The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the
32
+ carrier, the authority) in the Section where that work happens, kept visible after its stage, and the source of a
33
+ figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere.
34
+
35
+ **Each shot answers:** can the person find their row? Is what needs doing first, on the row's lead? Is anything
36
+ repeated or empty? Is anyone shown without their face? Is every paper visible? Across the workspace: can each app be
37
+ told apart by its own screen, and does any app hold a second entity behind tabs? A failed answer is a change to the tree.
4
38
 
5
- The common treatments are the chooser in `first_build`, § 3; every treatment is listed at `design/treatments`.
39
+ ## Look at it
6
40
 
7
- 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
8
- tree states COMPOSITION — which fields, lists and acts each job's screen holds. How each piece looks is the platform's,
9
- one way per concept, and no prop changes it. A component bound to a table draws well with no props, because its defaults
10
- come from the table's facts (`records`, the stage, the write rules): a node the tree leaves out draws that default — a
11
- List's Readings band, the stage buttons, the picture, a Record's designed Sections, a head kept to its budget. State a
12
- node to change its default, or `false` at it to turn it off (`"readings": false`, `"row": { "status": { "edit": false } }`,
13
- `"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
14
- answer the reader at a glance, and that is the most common failure of an app: the answer of `set_app` notes what the
15
- rows call for that no default draws (rows in time, a template's Act, a timeline), and the tree states the ones the job
16
- needs.
41
+ After an apply, `screenshot_app` draws each app as its people see it — the register, and a record by its `path` (`screen`
42
+ for a later screen of a long one) — at a desk's width and a phone's, naming the columns a table left off at each width;
43
+ `-o <dir>` saves the shots from the CLI. Beside them, `verdict` is what a write of the stored tree would be refused for
44
+ now, and its notes. Answer the questions of the visual bar, change the tree with `nodes`, and write again. To go back,
45
+ send the tree saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,
46
+ `period`, `icon`); tables and rows stay as they are.
17
47
 
18
48
  ## Treatments
19
49
 
20
- A treatment named in a section below is one the answer of `set_app` notes when the rows call for it and neither the
21
- tree nor a platform default draws it, naming the node that would state it. Nothing is written into the tree for the
22
- author: state the ones the job needs. A note refuses nothing.
50
+ A treatment named below is one the answer of `set_app` notes when the rows call for it and nothing draws it, naming the
51
+ node that would state it; a note refuses nothing. Each kind of row's view is chosen before its List is written:
23
52
 
24
53
  | The rows are | The treatment | Its props |
25
54
  |---|---|---|
26
55
  | People or organisations | `records.party`, with a photo or logo as its `image` | `reference/records` |
27
56
  | Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/records`, `reference/cards` |
28
57
  | Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `reference/calendar`, `reference/layouts` |
58
+ | Ranked by a figure, or worked by a date | List `sort: {"field": …, "desc": true}` on that column | `reference/list-node` |
29
59
  | Booked on a resource | List `layout: {"lanes": {"by": …}}`, and the table's `no_overlap` | `reference/lanes`, `reference/write-rules` |
30
60
  | A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |
31
61
  | 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 | `reference/section-node` |
@@ -283,35 +313,3 @@ through its own declared workflows. It stands alone with `label` and `when`, on
283
313
  in a Record's section, or a compose `Act` piece naming it). The target must be an app of the workspace that reaches the
284
314
  record's table — a register over it, or custom code declaring no table or declaring it; anything else is refused at
285
315
  save. A reader without `use` on the target meets that app's own "cannot open" state.
286
-
287
- ## The visual bar
288
-
289
- - A person shows a face, a thing its picture, a file its preview, a plan its days on a time axis, a
290
- quantity a meter (`records.limits`) or a chart, a register its Readings under its title, and long text
291
- reads whole (a markdown Field is a prose block; `block: true` makes a plain long text one).
292
- - Every app states its tile's colour (the App's `color`), apart from the workspace's other apps where it can be,
293
- so the launcher tells the desks apart before their names are read.
294
- - Every category the job reads is coloured: each select option's `color`, and a `mark` where a brand or a
295
- glyph names it — on every option of a select read down a column (how it was paid, the channel, the mode).
296
- - A yes that needs attention (papers the customer still owes) is a `Check` of its List over a yes/no formula, so it
297
- reads in the warning tone on the row's line; every other yes reads in the success tone.
298
- - Someone is a face wherever they are read. A person is a member field and a party a row of a table stating
299
- `party`; where a select's options name people or organisations who are neither, every option's `mark` is
300
- its face (`{"kind": "avatar", "name": "person"}`), never a colour dot.
301
- - Every files field is drawn somewhere — a Section's Fields, a Field of the Record, the `image`, or where the
302
- Act making it stands.
303
- - The paperwork is the proof of the work, so every paper the job takes in and every document it issues has a
304
- place on the record, in the Section where that work happens: a files field per purpose (what arrived, what
305
- was issued to the customer, to the carrier, to the authority), each kept visible after the stage that made it,
306
- and a source — a screenshot, an email, a sheet — on the row whose figure came from it.
307
- - A screen with none of these is bland, and bland is a finding: text drawn where a treatment above exists
308
- is a change to the tree.
309
-
310
- ## Look at it
311
-
312
- After an apply, the `screenshot_app` tool draws each app as its people see it — the register, and a record
313
- by its `path` — at a desk's width and a phone's, one screen a shot, naming the columns a table left off at
314
- 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
315
- the notes on it. Judge each shot against § The visual bar, change the tree with `nodes`, and write again. To go back,
316
- send the tree you saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,
317
- `period`, `icon`); the tables and rows stay as they are.
@@ -80,26 +80,9 @@ Every paper the owner sends is made, one template each. A slot is named after a
80
80
 
81
81
  ## 3. The app and its acts: `set_app`
82
82
 
83
- **Which apps.** One per role's work, shaped to the requirement: the list that role opens, and everything about each row on its page whatever its rhythm. One HR person's app holds the people and, on each, their contracts, payslips and leave; a business where payroll and hiring are different people's work may want an app each. A related row's value on the list (the newest contract's end)? A lookup column. Work over many rows (a month's payroll)? An Act on the list's rows. Used only inside another job (the rates a quote is priced from)? A picker on its lines, price copied by `default_from`. Never an app per table.
84
-
85
- **The view per kind of row**, chosen before writing the List (a plain register needs none):
86
-
87
- | The rows are | The treatment | Keys |
88
- |---|---|---|
89
- | People or organisations | `records.party`, photo or logo as `image` | `reference/records` |
90
- | Photos people look at | `records.image`; List `layout: "cards"` | `reference/cards` |
91
- | Held on a day people schedule by | List `layout: "calendar"` | `reference/calendar` |
92
- | Booked on a resource over time | List `layout: {"lanes": {"by": …}}`, table `no_overlap` | `reference/lanes` |
93
- | Standing at places on a floor or yard | List `layout: {"plan": …}` | `reference/plan` |
94
- | People across days | List `layout: "roster"`, the cells' List inside | `reference/roster` |
95
- | Expected against counted, before against after | a List with `compare: {"before": …, "after": …}` | `reference/list-node` |
96
- | Ranked by a figure | List `sort: {"field": …, "desc": true}` | `reference/list-node` |
97
- | Moved through a status (stages) | an Act per move, `status.dates`, Readings | `reference/act-node` |
98
- | Each belonging to another row | a child List on its page | `reference/list-node` |
99
- | Counted over a period | Tabs over one `period`; Readings | `reference/tab-node` |
100
- | Papers a case gathers | a List with `expect`; an Act's `template` | `reference/list-node` |
101
-
102
- Any other screen: `design/treatments`.
83
+ **Which apps.** One app per main entity, and everything that belongs to a row on that row's page. A main entity is a thing people work from its own list (customers, items, orders, suppliers, employees), each its own app, people and organisations included. What belongs to one row (an employee's contracts, payslips and leave; an order's lines; a customer's prices and balance) is a child List on that row's page, never another app or a Tab. The test: a row that stands alone and is picked from its own list is an app; a row that makes sense only under one parent is on the parent's page. One record may stand in both, an order in the orders app and on its customer's page: one record, one page. A second root List is rare: one job working two unrelated entities side by side. Each person is given only the few apps their job uses. A related row's value on the list (the newest contract's end)? A lookup column. Work over many rows (a month's payroll)? An Act on the list's rows. Here: the counter (orders), the menu and the customers; the counter is built below.
84
+
85
+ **The view per kind of row** is chosen before writing the List, from `design/treatments`: cards for things found by their photo, a calendar or lanes for dated work, faces for people and organisations, `sort` on the date a list is worked by. Every screen is judged against the visual bar `design` opens on.
103
86
 
104
87
  **Start from one root List.** `{"type": "List", "entity": "cake_order"}` in the App's `children` is a whole app: the platform draws the page every row opens (a Section per stage with its moves, the cakes as a child List), the add and the Delete. `set_app` answers with what it drew and what it placed or folded in what you stated; state only the difference. The tree below states this counter's choices.
105
88
 
@@ -132,7 +115,7 @@ One app, the counter's job, over the tables and template above. The register lis
132
115
  }
133
116
  ```
134
117
 
135
- `set_app` answers with a note for what the rows call for that the tree leaves out. It places what has one fix and stores the placed tree: a reader's `where` moved to `opens`, a `row.subtitle` made `columns`, Acts alike but for their key made one. These fold with one note: a read-only copy of a placed Field, `create`/`remove: false` on a read-only List, its `app` where one app is over its table, a lone text field's `unique`, a patch address unlike the node's `key`. **What the check refuses**, each with its id (`reference/<id>` is its page; some show a wrong → right):
118
+ `set_app` answers with a note for what the rows call for that the tree leaves out. It places what has one fix and stores the placed tree: a reader's `where` moved to `opens` and a `row.subtitle` made `columns`. These fold with one note: a read-only copy of a placed Field, `create`/`remove: false` on a read-only List, its `app` where one app is over its table, a lone text field's `unique`, a patch address unlike the node's `key`. **What the check refuses**, each with its id (`reference/<id>` is its page; some show a wrong → right):
136
119
 
137
120
  - `record.placed-once`: a Field, child List, Reading, Statement or Act stands once in a Record, whose head draws the title, subtitle, image, status, figure; a read-only repeat is left out and said.
138
121
  - `list.filter-unshown`: a `filters` entry (at most 3) is a select, member, link, date, yes/no or number the rows show, or a formula of such; never text, and the status is the chips already.
@@ -166,7 +149,7 @@ create_records {"table_id": "cake_line", "field_keys": ["order", "item", "quanti
166
149
 
167
150
  ## 6. Verify: `run_app_workflow`, `screenshot_app`
168
151
 
169
- Move the owner's own rows through the app as their person would, in stage order. An Act runs as `act_<key>` (or under the alias of the `workflow` it names), handed what it asks; dry-run first, then press. To prove a rule, send the write with `dry_run: true`; never make a test row or switch a check off. A row ends at the stage the owner says it is at, so press each only that far; where the owner gave no rows, ask for a few.
152
+ Move the owner's own rows through the app as their person would, in stage order, and judge each shot against the visual bar `design` opens on. An Act runs as `act_<key>` (or under the alias of the `workflow` it names), handed what it asks; dry-run first, then press. To prove a rule, send the write with `dry_run: true`; never make a test row or switch a check off. A row ends at the stage the owner says it is at, so press each only that far; where the owner gave no rows, ask for a few.
170
153
 
171
154
  ```
172
155
  run_app_workflow {"app_id": "app_…", "alias": "act_start_baking", "inputs": {"record_id": "rec_…", "prepaid": 20}, "dry_run": true}
@@ -1,6 +1,6 @@
1
1
  # Getting started
2
2
 
3
- A workspace is where one business keeps what it knows and does its daily work. **Records** are what it tracks, one table per kind of thing and one row per entry. **Apps** are the screens a team works in, one per person's job, drawn over the tables. **Documents** are the quotes, invoices and slips it sends, each a template filled from a record, or from the many rows of a period or a statement. A paper is the workspace's once it is made from a template or uploaded and filed on its record; a file left on the host's own disk, the user's included, reaches no one in the workspace. A procedure or policy no table holds is a **knowledge doc**; a price list, a customer list or the open orders are rows.
3
+ A workspace is where one business keeps what it knows and does its daily work. **Records** are what it tracks, one table per kind of thing and one row per entry. **Apps** are the screens a team works in, one per main kind of record, each person given the few their job uses. **Documents** are the quotes, invoices and slips it sends, each a template filled from a record, or from the many rows of a period or a statement. A paper is the workspace's once it is made from a template or uploaded and filed on its record; a file left on the host's own disk, the user's included, reaches no one in the workspace. A procedure or policy no table holds is a **knowledge doc**; a price list, a customer list or the open orders are rows.
4
4
 
5
5
  Open the one page for the job. Pages are read with the `docs` tool (`docs path="design"`; `lotics docs design` on the CLI).
6
6
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.318.21",
3
+ "version": "0.318.23",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {