@lotics/cli 0.317.1 → 0.318.2

package/docs/agent_surface.md

@@ -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

@@ -142,7 +142,7 @@ One app, the counter's job, over the tables and template above. The register lis
 - `app.names-declared`: each alias a key names exists (a table, field, option, Act `key`, template).
 - A workflow writes a link as ids, `[x.id]`; a whole record or bare value is refused.
 
-Then `set_access` gives the app to the people whose job it is: a `principal_type` of `member` (id from `get_workspace`, `kind: "member"`), `member_group` (an admin lists them: `kind: "group"`) or `organization`, a `role` of `user` or `manager`; none loses access.
+Then `set_access` gives the app to the people whose job it is: a `principal_type` of `member` (id from `get_workspace`, `kind: "member"`), `member_group` (an admin lists them: `kind: "group"`) or `organization`, a `role` of `user` or `manager`; none loses access. They need no table access; with no `rows` on the App, they read every row.
 
 ```
 set_access {"resources": [{"resource_type": "app", "resource_id": "app_…"}], "principals": [{"principal_type": "member", "principal_id": "<member id>", "role": "user"}]}

package/package.json

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