@lotics/cli 0.317.0 → 0.318.1

package/docs/agent_surface.md

@@ -41,11 +41,11 @@ app has.
 | `<child>_by_<link>_days` | The <child> rows of the <entity> rows handed in whose "<day>" falls from one day to another. | `<entity>_ids`; `from`; `to` | a roster List: the List of its cells |
 | `<entity>_<link>_pick` | The <target> rows "<link>" may point at, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a written link a write rule narrows (`options_where`, `same`) |
 | `<child>_by_<link>_picks` | The <child> rows no <entity> holds through "<link>" yet, that one <entity> may pick, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a List with `pick`: it picks existing rows into the record |
-| `<reading key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list's; `from`? / `to`? where the reading states `over`, or its `tab` is dated `in` a period; `to` where its `tab` is of rows `open` on a day | each Reading of the register List, called by its `key` (`register_reading_<n>`, n counted from 0, only for an app stored before trees) — but the work against its plan (Progress), which reads the list's own rows; none over Books |
-| `<reading key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each Reading of a dashboard, called by its `key` (`dashboard_reading_<n>` only for an app stored before trees) |
-| `<reading key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each Reading of the record and each List or funnel on it, called by its `key` (`block_reading_<n>` only for an app stored before trees) |
-| `<entity>_<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list's; `from`? / `to`? where the reading states `over` | each Reading of a log's List, called `<entity>_<key>` (`<entity>_register_reading_<n>` only for an app stored before trees) |
-| `<entity>_<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each Reading of the record a row of a Book or of a log opens and each List or funnel on it, called `<entity>_<key>` by the Book's or the log's entity (`<entity>_block_reading_<n>` only for an app stored before trees) |
+| `<reading key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list's; `from`? / `to`? where the reading states `over`, or its `tab` is dated `in` a period; `to` where its `tab` is of rows `open` on a day | each Reading of the register List, called by its `key` — but the work against its plan (Progress), which reads the list's own rows; none over Books |
+| `<reading key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each Reading of a dashboard, called by its `key` |
+| `<reading key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each Reading of the record and each List or funnel on it, called by its `key` |
+| `<entity>_<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list's; `from`? / `to`? where the reading states `over` | each Reading of a log's List, called `<entity>_<key>` |
+| `<entity>_<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each Reading of the record a row of a Book or of a log opens and each List or funnel on it, called `<entity>_<key>` by the Book's or the log's entity |
 | `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading's | a Reading whose value `records.limits` bounds: the bound's sum, beside the Reading's own |
 | `<reading>_on_hand` | <label> / <on-hand entity>: how many <on-hand entity> rows there are, per "<field>". Each row carries `<field>`, `__count`. | none: every row of its entity its `where` keeps, whatever the place | a Reading with `on_hand` (a shortfall): the on-hand rows' groups, beside the Reading's own |
 | `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list's | an Export of the register that fills a template |
@@ -281,7 +281,7 @@ Acts: every figure or list whose definition is the business's own (open orders,
 }
 ```
 
-It reads under the table's read scope and, on the app's own table, exactly the rows its list reads —
+It reads under the app's `rows` (every row, where the app states none of the table) and, on the app's own table, exactly the rows its list reads —
 so never the table of an app that states Books, whose list reads several tables. A condition reading an
 optional param narrows nothing when the call leaves it out; no param compares a number read in each row's
 own unit or currency, or a date holding a span. `"reading"` in place of `"fields"` returns a count or a sum —

package/docs/building_an_app.md

@@ -93,7 +93,8 @@ nothing; a refusal lists everything wrong in it at once.
 
 The App node is the app: its `name`, `description`, `icon` and `color` are props of it, and no other input of
 `set_app` states them. It names the tables and templates it uses by their aliases (an entity is a table's alias, a `template` a template's alias);
-`set_app` fills the `tables` and `templates` maps by id from them and `get_app` shows aliases (`lotics docs reference/app-node`). A call that creates
+`set_app` fills the `tables` and `templates` maps by id from them and `get_app` shows aliases (`lotics docs reference/app-node`).
+Who reads which rows is the app's `rows` (§ Who reads which rows, below). A call that creates
 is `{"body": <the App tree>}`; one that changes a part is `{"app_id": "app_…", "nodes": {"<address>": <patch>}}`,
 each address a node's path of keys (`get_app` prints every one), a patch a JSON merge patch of that node's props
 and `null` removing the node; the App's own props change through `body`. A call stating `base_version_id` — the
@@ -135,6 +136,29 @@ family and how it is called. A question the screen never asks is a Query node th
 (`lotics docs reference/query-node`), beside its Workflow nodes. Both are part of the design: `lotics docs
 agent_surface`, § Declaring more.
 
+### Who reads which rows
+
+An app runs with its owner's access, and the people it is shared with need the app alone, never its tables. Who of them
+reads which rows is the app's `rows`, one rule per table in the grammar of a table's `read_scope` (`lotics docs reference/read-scope`); it narrows
+the app's screens, its queries and workflows called through it (`run_app_query`, `run_app_workflow`), its acts and its
+workflow bodies alike, and a record id a caller passes is refused where the rule hides the row. State a rule only where
+people differ; a table with none is read whole by everyone the app is shared with.
+
+| The business says | The app states |
+|---|---|
+| Everyone on the team sees every order | nothing |
+| Each rep sees only their own deals | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }] } }` |
+| Reps see their own deals; managers see all | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }, { "member_of": "<managers group id>" }] } }` |
+| Each branch manager sees their branch's orders | `"rows": { "order": { "any": [{ "through": ["branch"], "field": "manager", "is": "self" }] } }` |
+| Each employee sees only their own payslips; HR sees all | two apps: one stating `"payslip": { "any": [{ "field": "employee", "is": "self" }] }`, one for HR stating none |
+| Team leads see people, not salaries | an app that draws no salary field — what it does not show, no one reads through it |
+
+A child read under a ruled row states its own rule, through its link to the parent; only a status history inherits.
+Admins are not narrowed in an app; someone on a public link, signed in as no one, reads no row a `self` clause would
+choose. An app never reads past its owner's own access. A table's own `read_scope` governs opening the table directly.
+Working inside one row of a folder (`scope`) narrows the view, not who may read: a branch app shared with every manager
+still states the branch rule.
+
 ## 5 — A custom-code app
 
 ```

package/docs/examples.md

@@ -75,6 +75,14 @@ among them: the `design` reference. Every key: the `model` reference, at the pag
     "name": "Service visits",
     "icon": "calendar",
     "color": "emerald",
+    "rows": {
+      "customer": {"any": [{"member_of": "sales"}]},
+      "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "order_stage": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "service_visit": {"any": [{"member_of": "sales"}, {"member_of": "stores"}, {"member_of": "field"}]}
+    },
     "children": [
       {
         "type": "List",
@@ -258,6 +266,14 @@ among them: the `design` reference. Every key: the `model` reference, at the pag
     "name": "Dispatch",
     "icon": "wrench",
     "color": "sky",
+    "rows": {
+      "customer": {"any": [{"member_of": "sales"}]},
+      "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "order_stage": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "service_visit": {"any": [{"member_of": "sales"}, {"member_of": "stores"}, {"member_of": "field"}]}
+    },
     "children": [
       {
         "type": "List",
@@ -613,6 +629,13 @@ among them: the `design` reference. Every key: the `model` reference, at the pag
     "name": "Stock",
     "icon": "boxes",
     "color": "teal",
+    "rows": {
+      "customer": {"any": [{"member_of": "sales"}]},
+      "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "order_stage": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]}
+    },
     "scope": "warehouse",
     "children": [
       {
@@ -841,6 +864,16 @@ among them: the `design` reference. Every key: the `model` reference, at the pag
     "name": "Customers",
     "icon": "users",
     "color": "violet",
+    "rows": {
+      "customer": {"any": [{"member_of": "sales"}]},
+      "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "order_stage": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},
+      "touch": {"any": [{"member_of": "sales"}]},
+      "customer_paper": {"any": [{"member_of": "sales"}]},
+      "service_visit": {"any": [{"member_of": "sales"}, {"member_of": "stores"}, {"member_of": "field"}]}
+    },
     "children": [
       {
         "type": "List",

package/docs/first_build.md

@@ -2,7 +2,7 @@
 
 A bakery takes custom-cake orders at the counter. An order is a customer and the cakes on it, one line per cake from the menu; it moves taken, baking, ready, collected, and a slip of the cakes prints when it is ready. Six steps, in the order every workspace is built.
 
-Step 0, before the first write: ask the owner once, in one message, only what you cannot settle yourself. Usually: their papers and lists — a photo, a spreadsheet or a file is fine; they answer most questions (what they send and receive, customers, items, prices) — and what no paper tells you that would change the tables or who does which step. The owner answers by hand, so every question costs them time: ask nothing they gave already or a paper settles. Each question is one sentence, no sub-questions or bullets under it; nothing else in that message. Wait for the answer, then build; never build first and ask after. Never ask about stages or design: take a default for everything else and list it in your report so the owner can correct it. Load the owner's own rows. `get_workspace` shows what already exists; what no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).
+Step 0, before the first write: ask the owner once, in one message, only what you cannot settle yourself. Usually: their papers and lists — a photo, a spreadsheet or a file is fine; they answer most questions (what they send and receive, customers, items, prices) — and what no paper tells you that would change the tables or who does which step. The owner answers by hand, so every question costs them time: ask nothing they gave already or a paper settles. Each question is one sentence, no sub-questions or bullets under it; nothing else in that message. Wait for the answer, then build; never build first and ask after. Never ask about stages or design: take a default for everything else and list it in your report so the owner can correct it. Who reads which rows of an app is stated on the app (`rows`), only where people differ; absent, everyone the app is shared with sees every row, and members need the app shared with them, never table access. Load the owner's own rows. `get_workspace` shows what already exists; what no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).
 
 ## 1. Tables and their checks: `set_tables`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.317.0",
+  "version": "0.318.1",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {