@lotics/cli 0.321.75 → 0.321.76

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.
package/dist/src/cli.js CHANGED
@@ -1849,7 +1849,7 @@ async function saveSignedLinks(links, dir, timeoutMs) {
1849
1849
  }
1850
1850
 
1851
1851
  // src/version.ts
1852
- var VERSION = "0.321.75";
1852
+ var VERSION = "0.321.76";
1853
1853
 
1854
1854
  // src/timezone.ts
1855
1855
  function machineTimezone() {
@@ -1889,7 +1889,7 @@ var reference_default = '# Tables and apps\n\nThe tables of a workspace and the
1889
1889
  var examples_default = '# Worked examples\n\nEach section is one treatment, cut from a complete workspace of an invented business: the job, the keys to\nread, where the treatment is wrong, and the excerpt \u2014 the app\'s tree, the App node `set_app` takes as `body`,\nwhich the check passes with no finding; the tables it draws as the items of a `set_tables` call, each with its\n`title` and `records`; those tables\' fields it names, by what each holds and how it is drawn; and the templates it makes.\nLeft out, for the page\'s size: a Section or page that carries nothing of the treatment, every `label` and `description` of a table or field, `required`, `min`, `unique`, `default` (a section keeps the ones its **Read** rests on), a link\'s\n`pair`, how a computed field computes, the `tables` and `templates` maps an App adds (ids from the\n`set_tables` answer), and template contents \u2014 a call states each table\'s and field\'s `label`. Choosing\namong them: the `design` reference. Every key: `reference`, at the pages each section names under\n**Keys**. How a record\'s status draws is a choice of its own, made by what the work is (`design`, Stages):\neach section says which its record takes under **Its stages**, so the form is copied with its reason.\n\n## Calendar\n\n**The job.** Book visits on the days they happen, and see a week\'s work at a glance.\n\n**Read.** `layout: "calendar"` on the List; each visit stands from `scheduled_for` over its span to `ends_at`, the two `required` moments of its facts (`ends_at` is ordered after `scheduled_for` by its `min`); a keyed calendar names the date and the end itself.\n\n**Keys.** `reference/calendar`\n\n**Not when.** Rows booked on a resource that two may not share at once \u2014 that is `lanes`. Rows with a date nobody plans by (an invoice\'s date) stay a table.\n\n**Its stages.** `service_visit` states Sections at its stages: its path reads down the page, each stage\'s Section under its step.\n\n```json\n{\n "tables": [\n {\n "ref": "service_visit",\n "title": "customer",\n "fields": {\n "customer": {"required": true, "type": "link", "table": "customer", "multi": false},\n "scheduled_for": {"required": true, "type": "date", "format": "datetime"},\n "ends_at": {"required": true, "type": "date", "format": "datetime", "min": "scheduled_for"},\n "engineer": {"type": "link", "table": "engineer", "multi": false},\n "job": {\n "required": true,\n "type": "select",\n "options": [{"alias": "inspection", "color": "sky"}, {"alias": "repair", "color": "orange"}]\n },\n "stage": {\n "type": "select",\n "options": [\n {"alias": "booked_on", "color": "blue"},\n {"alias": "parts_ready_on", "color": "blue"},\n {"alias": "arrived_on", "color": "blue"},\n {"alias": "completed_on", "color": "green"}\n ]\n },\n "booked_on": {"type": "date"},\n "parts_ready_on": {"type": "date"},\n "arrived_on": {"type": "date"},\n "hours": {"type": "number", "notation": {"style": "unit", "unit": "h"}},\n "report": {"type": "text", "format": "markdown"},\n "completed_on": {"type": "date"}\n },\n "records": {\n "subtitle": ["scheduled_for", "ends_at"],\n "figure": "hours",\n "due": ["scheduled_for"],\n "status": {\n "field": "stage",\n "closed": ["completed_on"],\n "dates": {\n "booked_on": "booked_on",\n "parts_ready_on": "parts_ready_on",\n "arrived_on": "arrived_on",\n "completed_on": "completed_on"\n }\n }\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "visits",\n "name": "Service visits",\n "icon": "calendar",\n "color": "emerald",\n "rows": {\n "customer": {"any": [{"member_of": "sales"}]},\n "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "service_visit": {"any": [{"member_of": "sales"}, {"member_of": "stores"}, {"member_of": "field"}]}\n },\n "children": [\n {\n "type": "List",\n "entity": "service_visit",\n "columns": ["engineer", "job"],\n "filters": ["customer"],\n "sort": {"field": "scheduled_for"},\n "layout": "calendar",\n "create": ["customer", "job", "scheduled_for", "ends_at", "engineer"],\n "children": [\n {"type": "Reading", "key": "register_reading_0", "label": "Repairs", "where": {"job": ["repair"]}},\n {"type": "Reading", "key": "register_reading_1", "value": "hours", "by": "engineer"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "service_visit",\n "children": [\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "visit",\n "title": "Visit",\n "at": ["booked_on", "parts_ready_on"],\n "children": [\n "job",\n "booked_on",\n "parts_ready_on",\n {\n "type": "Act",\n "key": "reschedule",\n "label": "Reschedule",\n "asks": ["scheduled_for", "ends_at"],\n "when": {"stage": ["booked_on", "parts_ready_on"]}\n },\n {\n "type": "Act",\n "key": "to_booked_on",\n "label": "Booked",\n "when": {"stage": {"empty": true}},\n "asks": [{"field": "booked_on", "starts": "today"}],\n "set": {"stage": "booked_on"}\n },\n {\n "type": "Act",\n "key": "to_parts_ready_on",\n "label": "Parts ready",\n "when": {"stage": ["booked_on"], "job": ["repair"]},\n "asks": [{"field": "parts_ready_on", "starts": "today"}],\n "set": {"stage": "parts_ready_on"}\n },\n {\n "type": "Act",\n "key": "to_arrived_on",\n "label": "On site",\n "when": {"stage": ["booked_on"], "job": ["inspection"]},\n "asks": [{"field": "arrived_on", "starts": "today"}],\n "set": {"stage": "arrived_on"}\n },\n {\n "type": "Act",\n "key": "to_arrived_on_2",\n "label": "On site",\n "when": {"stage": ["parts_ready_on"]},\n "asks": [{"field": "arrived_on", "starts": "today"}],\n "set": {"stage": "arrived_on"}\n }\n ]\n },\n {\n "type": "Section",\n "key": "report",\n "title": "Report",\n "at": ["arrived_on"],\n "children": [\n "engineer",\n "arrived_on",\n {"field": "report", "block": false},\n {\n "type": "Act",\n "key": "complete",\n "label": "Complete visit",\n "requires": ["engineer"],\n "asks": [\n "hours",\n {"input": "summary", "label": "What was done", "type": "long_text", "required": true}\n ],\n "set": {"report": {"input": "summary"}, "stage": "completed_on"},\n "when": {"stage": ["arrived_on"]}\n },\n {\n "type": "Act",\n "key": "clear_visit_hours",\n "label": "Clear hours",\n "set": {"hours": null},\n "confirm": true\n }\n ]\n }\n ]\n }\n ]\n },\n {"type": "Record", "entity": "warehouse", "add": ["name", "city"]},\n {"type": "Record", "entity": "engineer", "add": ["name", "base"]},\n {"type": "Record", "entity": "customer", "add": ["name", "credit_limit"]}\n ]\n }\n}\n```\n\n## Lanes\n\n**The job.** Put each service visit on an engineer\'s day by the hour, and see at once who is free between visits.\n\n**Read.** `layout` `lanes` with `by` naming the one-row link to the resource (the engineer); every engineer stands as a lane, empty or not.\n\n**Keys.** `reference/lanes`\n\n**Not when.** The resource is not a row of the model (a free-text room name), or rows never compete for one \u2014 a `calendar` reads them by day.\n\n**Its stages.** `service_visit` states no Section at a stage and its Acts move it: its path draws as a line of steps across the page.\n\n```json\n{\n "tables": [\n {\n "ref": "service_visit",\n "title": "customer",\n "fields": {\n "customer": {"type": "link", "table": "customer", "multi": false},\n "scheduled_for": {"type": "date", "format": "datetime"},\n "ends_at": {"type": "date", "format": "datetime"},\n "engineer": {"type": "link", "table": "engineer", "multi": false},\n "job": {\n "type": "select",\n "options": [{"alias": "inspection", "color": "sky"}, {"alias": "repair", "color": "orange"}]\n },\n "stage": {\n "type": "select",\n "options": [\n {"alias": "booked_on", "color": "blue"},\n {"alias": "parts_ready_on", "color": "blue"},\n {"alias": "arrived_on", "color": "blue"},\n {"alias": "completed_on", "color": "green"}\n ]\n },\n "booked_on": {"type": "date"},\n "parts_ready_on": {"type": "date"},\n "arrived_on": {"type": "date"},\n "hours": {"type": "number", "notation": {"style": "unit", "unit": "h"}},\n "completed_on": {"type": "date"},\n "length": {"type": "formula", "notation": {"style": "unit", "unit": "h"}}\n },\n "records": {\n "subtitle": ["scheduled_for", "ends_at"],\n "figure": "hours",\n "due": ["scheduled_for"],\n "status": {\n "field": "stage",\n "closed": ["completed_on"],\n "dates": {\n "booked_on": "booked_on",\n "parts_ready_on": "parts_ready_on",\n "arrived_on": "arrived_on",\n "completed_on": "completed_on"\n }\n }\n }\n },\n {\n "ref": "engineer",\n "title": "name",\n "fields": {\n "name": {"type": "text"},\n "base": {"type": "link", "table": "warehouse", "multi": false},\n "day_hours": {"type": "number", "notation": {"style": "unit", "unit": "h"}}\n },\n "records": {"subtitle": ["base"], "party": "person"}\n }\n ],\n "body": {\n "type": "App",\n "key": "dispatch",\n "name": "Dispatch",\n "icon": "wrench",\n "color": "sky",\n "rows": {\n "customer": {"any": [{"member_of": "sales"}]},\n "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "service_visit": {"any": [{"member_of": "sales"}, {"member_of": "stores"}, {"member_of": "field"}]}\n },\n "children": [\n {\n "type": "List",\n "entity": "service_visit",\n "columns": ["job"],\n "search": ["customer"],\n "layout": {"lanes": {"by": "engineer", "loads": {"length": "day_hours"}}},\n "create": ["engineer", "scheduled_for", "ends_at", "customer", "job"]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "service_visit",\n "children": [\n {\n "type": "Section",\n "key": "booking",\n "title": "Booking",\n "children": [\n "engineer",\n "job",\n "hours",\n {\n "type": "Act",\n "key": "to_booked_on",\n "label": "Booked",\n "when": {"stage": {"empty": true}},\n "asks": [{"field": "booked_on", "starts": "today"}],\n "set": {"stage": "booked_on"}\n },\n {\n "type": "Act",\n "key": "to_parts_ready_on",\n "label": "Parts ready",\n "when": {"stage": ["booked_on"], "job": ["repair"]},\n "asks": [{"field": "parts_ready_on", "starts": "today"}],\n "set": {"stage": "parts_ready_on"}\n },\n {\n "type": "Act",\n "key": "to_arrived_on",\n "label": "On site",\n "when": {"stage": ["booked_on"], "job": ["inspection"]},\n "asks": [{"field": "arrived_on", "starts": "today"}],\n "set": {"stage": "arrived_on"}\n },\n {\n "type": "Act",\n "key": "to_arrived_on_2",\n "label": "On site",\n "when": {"stage": ["parts_ready_on"]},\n "asks": [{"field": "arrived_on", "starts": "today"}],\n "set": {"stage": "arrived_on"}\n },\n {\n "type": "Act",\n "key": "to_completed_on",\n "label": "Completed",\n "when": {"stage": ["arrived_on"]},\n "asks": [{"field": "completed_on", "starts": "today"}],\n "set": {"stage": "completed_on"}\n }\n ]\n }\n ],\n "row": {\n "subtitle": [{"field": "scheduled_for", "edit": false}, {"field": "ends_at", "edit": false}],\n "figure": false\n }\n },\n {"type": "Record", "entity": "warehouse", "add": ["name", "city"]},\n {"type": "Record", "entity": "engineer", "add": ["name", "base"]},\n {"type": "Record", "entity": "customer", "add": ["name", "credit_limit"]}\n ]\n }\n}\n```\n\n## Gantt\n\n**The job.** Read every hire as a bar from the day the machine goes out to the day it is due back, against today.\n\n**Read.** `layout` `gantt` with its `start`; with no end stated, the bar ends at the entity\'s first `due`. The day a hire comes back (`ngay_tra`) is stamped by the status\'s `dates`, so no act sets it.\n\n**Keys.** `reference/gantt`\n\n**Not when.** Rows that last a day or less (a visit, a shift) \u2014 `calendar` or `lanes`; a plan with no dates set yet.\n\n**Its stages.** `phieu_thue` states Sections at its stages: its path reads down the page, each stage\'s Section under its step.\n\n```json\n{\n "tables": [\n {\n "ref": "phieu_thue",\n "title": "khach_hang",\n "fields": {\n "khach_hang": {"type": "link", "table": "khach_hang", "multi": false},\n "so_phieu": {"type": "text"},\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "moi", "color": "slate"},\n {"alias": "dang_thue", "color": "blue"},\n {"alias": "da_tra", "color": "green"},\n {"alias": "huy", "color": "gray"}\n ]\n },\n "phu_trach": {"type": "member"},\n "ngay_giao": {"type": "date"},\n "han_tra": {"type": "date"},\n "ngay_tra": {"type": "date"},\n "tinh_trang_tra": {\n "type": "select",\n "options": [\n {"alias": "tot", "color": "green"},\n {"alias": "tray_xuoc", "color": "amber"},\n {"alias": "hu_hong", "color": "red"}\n ]\n },\n "so_ngay": {"type": "formula"},\n "tong_tien": {"type": "rollup"}\n },\n "records": {\n "subtitle": ["so_phieu"],\n "figure": "tong_tien",\n "due": ["han_tra"],\n "status": {"field": "trang_thai", "closed": ["da_tra", "huy"], "dates": {"da_tra": "ngay_tra"}}\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "tien_do_thue",\n "name": "Ti\u1EBFn \u0111\u1ED9 cho thu\xEA",\n "icon": "calendar-range",\n "color": "teal",\n "children": [\n {\n "type": "List",\n "entity": "phieu_thue",\n "columns": ["phu_trach"],\n "filters": ["phu_trach", "khach_hang"],\n "layout": {"gantt": {"start": "ngay_giao"}},\n "create": false,\n "remove": false\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "phieu_thue",\n "children": [\n {\n "type": "Section",\n "key": "phieu_thue",\n "title": "Phi\u1EBFu thu\xEA",\n "children": ["ngay_giao", "han_tra"]\n },\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "dang_thue",\n "title": "\u0110ang thu\xEA",\n "at": ["dang_thue"],\n "children": [\n "so_ngay",\n {"field": "ngay_tra", "edit": false},\n {\n "type": "Act",\n "key": "nhan_tra",\n "label": "Nh\u1EADn m\xE1y tr\u1EA3",\n "when": {"trang_thai": ["dang_thue"]},\n "asks": ["tinh_trang_tra"],\n "set": {"trang_thai": "da_tra"},\n "confirm": true\n },\n {\n "type": "Act",\n "key": "mo_lai",\n "label": "M\u1EDF l\u1EA1i",\n "when": {"trang_thai": ["da_tra"]},\n "set": {"trang_thai": "dang_thue"},\n "confirm": true\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n }\n}\n```\n\n## Roster\n\n**The job.** See who works which shift on each day of the week or the month.\n\n**Read.** `layout: "roster"` over the people; the child List (`lich_truc`) is the rows that fill the days \u2014 one link back and a date on its line.\n\n**Keys.** `reference/roster`\n\n**Not when.** Rows that are themselves the bookings (a stay over several days) \u2014 a `calendar` or `lanes` draws them; a roster\'s row is what the days are filled for.\n\n```json\n{\n "tables": [\n {\n "ref": "nha_si",\n "title": "ho_ten",\n "fields": {\n "ho_ten": {"type": "text"},\n "chuyen_mon": {\n "type": "select",\n "options": [\n {"alias": "tong_quat", "color": "blue"},\n {"alias": "chinh_nha", "color": "purple"},\n {"alias": "nha_chu", "color": "green"},\n {"alias": "phuc_hinh", "color": "orange"}\n ]\n },\n "dien_thoai": {"type": "text"},\n "ngay_lam": {\n "type": "select",\n "options": [\n {"alias": "mon", "color": "blue"},\n {"alias": "tue", "color": "blue"},\n {"alias": "wed", "color": "blue"},\n {"alias": "thu", "color": "blue"},\n {"alias": "fri", "color": "blue"},\n {"alias": "sat", "color": "blue"},\n {"alias": "sun", "color": "blue"}\n ],\n "multi": true\n },\n "tu_ngay": {"type": "date"}\n },\n "records": {\n "subtitle": ["chuyen_mon"],\n "party": "person",\n "cadence": [{"entity": "lich_truc", "on": "ngay_lam", "from": "tu_ngay", "planned": "ke_hoach"}]\n }\n },\n {\n "ref": "lich_truc",\n "title": "ca",\n "fields": {\n "nha_si": {"type": "link", "table": "nha_si", "multi": false},\n "ca": {\n "type": "select",\n "options": [\n {"alias": "sang", "color": "blue"},\n {"alias": "chieu", "color": "purple"},\n {"alias": "ca_ngay", "color": "green"},\n {"alias": "nghi", "color": "gray"}\n ]\n },\n "ngay": {"type": "date"},\n "ghe": {"type": "link", "table": "ghe", "multi": false},\n "ke_hoach": {"type": "date"}\n },\n "records": {"subtitle": ["ngay", "ghe"], "mark": "ca"}\n }\n ],\n "body": {\n "type": "App",\n "key": "lich_truc",\n "name": "L\u1ECBch tr\u1EF1c",\n "icon": "users",\n "color": "indigo",\n "children": [\n {\n "type": "List",\n "entity": "nha_si",\n "filters": ["chuyen_mon"],\n "layout": "roster",\n "create": ["ho_ten", "chuyen_mon", "dien_thoai"],\n "children": [\n {"type": "List", "entity": "lich_truc", "create": true, "remove": true},\n {"type": "Act", "key": "tao_ca_truc_ds", "label": "T\u1EA1o ca tr\u1EF1c", "on": "view", "makes": "lich_truc"},\n {\n "type": "Export",\n "key": "lich_truc_thang",\n "label": "L\u1ECBch tr\u1EF1c th\xE1ng",\n "template": "lich_truc_thang"\n }\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "nha_si",\n "children": [\n {\n "type": "Section",\n "key": "lich_tuan",\n "title": "L\u1ECBch tr\u1EF1c m\u1ED7i tu\u1EA7n",\n "children": [\n "ngay_lam",\n "tu_ngay",\n {"type": "Act", "key": "tao_ca_truc", "label": "T\u1EA1o ca tr\u1EF1c", "makes": "lich_truc"}\n ]\n }\n ]\n },\n {"type": "Record", "entity": "lich_truc"},\n {"type": "Record", "entity": "ghe", "add": ["ten", "phong"]}\n ]\n }\n}\n```\n\n## Cards\n\n**The job.** Find an item by its picture, and count what the shelf holds.\n\n**Read.** `layout: "cards"` over rows whose `records.image` is a photo; `scope` keeps the app inside one warehouse at a time.\n\n**Keys.** `reference/cards`, `reference/records`, `reference/app-node`\n\n**Not when.** Rows with no picture \u2014 cards of words are a table drawn worse.\n\n```json\n{\n "tables": [\n {\n "ref": "stock_item",\n "title": "name",\n "fields": {\n "name": {"type": "text"},\n "warehouse": {"type": "link", "table": "warehouse", "multi": false},\n "photo": {"type": "files"},\n "sku": {"type": "text"},\n "category": {\n "type": "select",\n "options": [\n {"alias": "pumps", "color": "blue"},\n {"alias": "valves", "color": "teal"},\n {"alias": "seals", "color": "amber"},\n {"alias": "motors", "color": "violet"}\n ]\n },\n "on_hand": {"type": "number"},\n "minimum": {"type": "number"},\n "price": {"type": "number", "notation": {"style": "currency", "currency": "USD"}},\n "supplier_page": {"type": "text", "format": "link"},\n "last_counted": {"type": "date"},\n "counted_by": {"type": "member"},\n "count_note": {"type": "text"}\n },\n "records": {\n "subtitle": ["sku", "category"],\n "image": "photo",\n "figure": "on_hand",\n "limits": {"on_hand": 400},\n "gates": {"on_hand": "minimum"}\n }\n },\n {\n "ref": "order_line",\n "title": "item",\n "fields": {\n "item": {"type": "link", "table": "stock_item", "multi": false},\n "order": {"type": "link", "table": "order", "multi": false},\n "quantity": {"type": "number"},\n "shipped": {"type": "number"},\n "picked": {"type": "number"},\n "unit_price": {"type": "number", "notation": {"style": "currency", "currency": "USD"}},\n "amount": {"type": "formula", "notation": {"style": "currency", "currency": "USD"}},\n "settled": {"type": "formula"},\n "category": {"type": "lookup"}\n },\n "records": {\n "subtitle": ["order", "unit_price"],\n "figure": "amount",\n "limits": {"shipped": "quantity", "picked": "quantity"}\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "stock",\n "name": "Stock",\n "icon": "boxes",\n "color": "teal",\n "rows": {\n "customer": {"any": [{"member_of": "sales"}]},\n "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]}\n },\n "scope": "warehouse",\n "children": [\n {\n "type": "List",\n "entity": "stock_item",\n "filters": ["on_hand"],\n "search": ["name", "sku"],\n "layout": "cards",\n "children": [\n {"type": "Reading", "key": "register_reading_0", "value": "on_hand", "by": "category"},\n {"type": "Export", "key": "export"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "stock_item",\n "children": [\n {\n "type": "Section",\n "key": "item",\n "title": "Item",\n "children": ["price", "minimum", "supplier_page"]\n },\n {\n "type": "Section",\n "key": "last_count",\n "title": "Last count",\n "children": [\n "last_counted",\n "counted_by",\n "count_note",\n {\n "type": "Act",\n "key": "count",\n "label": "Count stock",\n "asks": [\n {"input": "counted", "label": "Units on the shelf", "type": "number", "required": true},\n {"input": "remark", "label": "Remark", "type": "long_text"}\n ],\n "set": {\n "on_hand": {"input": "counted"},\n "last_counted": {"now": true},\n "counted_by": {"me": true},\n "count_note": {"input": "remark"}\n }\n }\n ]\n },\n {\n "type": "Section",\n "key": "on_order",\n "title": "On order",\n "children": [{"type": "List", "entity": "order_line"}]\n }\n ]\n },\n {\n "type": "Record",\n "entity": "order_line",\n "children": ["quantity", "shipped", {"type": "Check", "field": "settled", "on": ["update"]}]\n },\n {"type": "Record", "entity": "customer", "add": ["name", "credit_limit"]}\n ]\n }\n}\n```\n\n## Party\n\n**The job.** Keep each customer account \u2014 who they are, what they ordered, what was said to them.\n\n**Read.** `records.customer.party: "organization"` and its `image` (the logo); a List with `layout: "timeline"` for the touches, a Reading `by` the day placed for its orders, and its papers `expect`ed by kind.\n\n**Keys.** `reference/records`, `reference/layouts`, `reference/list-node`, `reference/reading-node`\n\n**Not when.** A list of customers is not a job by itself: the customer is a link on the desk whose rows name it, unless the job is the account itself.\n\n**Its stages.** `order` states no Section at a stage and its Acts move it: its path draws as a line of steps across the page.\n\n```json\n{\n "tables": [\n {\n "ref": "customer",\n "title": "name",\n "fields": {\n "name": {"type": "text"},\n "logo": {"type": "files"},\n "code": {"type": "text"},\n "tier": {\n "type": "select",\n "options": [\n {"alias": "key", "color": "violet"},\n {"alias": "standard", "color": "sky"},\n {"alias": "lapsed", "color": "gray"}\n ]\n },\n "phone": {"type": "text"},\n "website": {"type": "text", "format": "link"},\n "account_manager": {"type": "member"},\n "credit_limit": {"type": "number", "notation": {"style": "currency", "currency": "USD"}},\n "orders": {"type": "link", "table": "order", "multi": true},\n "outstanding": {"type": "rollup"},\n "papers_needed": {\n "type": "select",\n "options": [\n {"alias": "credit_application", "color": "blue"},\n {"alias": "trade_reference", "color": "violet"},\n {"alias": "vat_certificate", "color": "teal"}\n ],\n "multi": true\n },\n "notes": {"type": "text", "format": "markdown"}\n },\n "records": {\n "subtitle": ["tier"],\n "image": "logo",\n "party": "organization",\n "figure": "outstanding",\n "limits": {"outstanding": "credit_limit"}\n }\n },\n {\n "ref": "order",\n "title": "reference",\n "fields": {\n "customer": {"type": "link", "table": "customer", "multi": false},\n "reference": {"type": "text"},\n "stage": {\n "type": "select",\n "options": [\n {"alias": "draft", "color": "slate"},\n {"alias": "confirmed", "color": "blue"},\n {"alias": "picking", "color": "amber"},\n {"alias": "shipped", "color": "indigo"},\n {"alias": "received", "color": "green"},\n {"alias": "cancelled", "color": "rose"}\n ]\n },\n "placed": {"type": "date"},\n "due_date": {"type": "date"},\n "handler": {"type": "member"},\n "priority": {"type": "boolean"},\n "lines": {"type": "link", "table": "order_line", "multi": true},\n "payments": {"type": "link", "table": "payment", "multi": true},\n "total": {"type": "rollup"},\n "balance": {"type": "formula", "notation": {"style": "currency", "currency": "USD"}},\n "units_ordered": {"type": "rollup"},\n "units_shipped": {"type": "rollup"},\n "units_picked": {"type": "rollup"},\n "carrier": {"type": "text"},\n "tracking_no": {"type": "text"},\n "shipped_on": {"type": "date"},\n "cancellation_reason": {"type": "text"},\n "cancelled_by": {"type": "member"},\n "replaced_by": {"type": "link", "table": "order", "multi": false},\n "attachments": {"type": "files"},\n "delivery_note": {"type": "files"},\n "notes": {"type": "text", "format": "markdown"},\n "paid_in_full": {"type": "formula"},\n "reminder_ref": {"type": "text"}\n },\n "records": {\n "subtitle": ["customer", "placed"],\n "figure": "total",\n "limits": {"units_shipped": "units_ordered", "units_picked": "units_ordered"},\n "due": ["due_date"],\n "status": {\n "field": "stage",\n "closed": ["received", "cancelled"],\n "dates": {"shipped": "shipped_on"},\n "history": "order_stage"\n }\n }\n },\n {\n "ref": "customer_paper",\n "title": "kind",\n "fields": {\n "kind": {\n "type": "select",\n "options": [\n {"alias": "credit_application", "color": "blue"},\n {"alias": "trade_reference", "color": "violet"},\n {"alias": "vat_certificate", "color": "teal"}\n ]\n },\n "customer": {"type": "link", "table": "customer", "multi": false},\n "received_on": {"type": "date"},\n "file": {"type": "files"}\n },\n "records": {"image": "file"}\n },\n {\n "ref": "touch",\n "title": "said",\n "fields": {\n "said": {"type": "text"},\n "customer": {"type": "link", "table": "customer", "multi": false},\n "on": {"type": "date"},\n "by": {"type": "member"}\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "customers",\n "name": "Customers",\n "icon": "users",\n "color": "violet",\n "rows": {\n "customer": {"any": [{"member_of": "sales"}]},\n "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "touch": {"any": [{"member_of": "sales"}]},\n "customer_paper": {"any": [{"member_of": "sales"}]},\n "service_visit": {"any": [{"member_of": "sales"}, {"member_of": "stores"}, {"member_of": "field"}]}\n },\n "children": [\n {\n "type": "List",\n "entity": "customer",\n "columns": ["phone", "account_manager"],\n "filters": ["account_manager"],\n "sort": {"field": "name"},\n "opens": {"tier": ["key", "standard"]},\n "create": ["name", "code", "credit_limit"],\n "children": [{"type": "Reading", "key": "register_reading_1", "value": "outstanding", "by": "account_manager"}]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "customer",\n "door": "drawer",\n "children": [\n {"type": "Section", "key": "contact", "title": "Contact", "children": ["phone", "website"]},\n {\n "type": "Section",\n "key": "account",\n "title": "Account",\n "children": [\n "code",\n "account_manager",\n "credit_limit",\n {\n "type": "Act",\n "key": "reassign",\n "label": "Reassign",\n "asks": [{"input": "to", "label": "Account manager", "type": "member", "required": true}],\n "set": {"account_manager": {"input": "to"}}\n },\n {\n "type": "Act",\n "key": "lapse",\n "label": "Mark lapsed",\n "when": {"tier": ["key", "standard"]},\n "set": {"tier": "lapsed"},\n "confirm": true\n },\n {\n "type": "Act",\n "key": "reinstate",\n "label": "Reinstate",\n "when": {"tier": ["lapsed"]},\n "asks": [\n {\n "input": "back_to",\n "label": "Back to",\n "type": "select",\n "options": [\n {\n "alias": "key",\n "label": "Key account",\n "color": "violet",\n "mark": {"kind": "icon", "name": "building-2"}\n },\n {"alias": "standard", "label": "Standard", "color": "sky"}\n ],\n "required": true\n }\n ],\n "set": {"tier": {"input": "back_to"}}\n }\n ]\n },\n {\n "type": "Section",\n "key": "orders",\n "title": "Orders",\n "children": [\n {\n "type": "Reading",\n "key": "block_reading_0",\n "label": "Order value",\n "entity": "order",\n "value": "total",\n "where": {"stage": ["confirmed", "picking", "shipped", "received"]},\n "by": "placed"\n },\n {\n "type": "List",\n "entity": "order",\n "where": {"stage": ["draft", "confirmed", "picking", "shipped"]},\n "label": "Open orders",\n "columns": ["due_date"],\n "create": false\n },\n {\n "type": "List",\n "key": "order_2",\n "entity": "order",\n "where": {"stage": ["shipped", "received"], "paid_in_full": false},\n "label": "Shipped, still owed",\n "columns": ["balance"],\n "create": false\n },\n {\n "type": "List",\n "key": "block_reading_3",\n "entity": "service_visit",\n "columns": ["engineer", "job"],\n "edit": false\n }\n ]\n },\n {\n "type": "Section",\n "key": "account_papers",\n "title": "Account papers",\n "children": [\n {\n "type": "List",\n "entity": "customer_paper",\n "expect": {"field": "kind", "of": "papers_needed"},\n "columns": ["received_on"]\n }\n ]\n },\n {\n "type": "Section",\n "key": "contact_log",\n "title": "Contact log",\n "children": [{"type": "List", "entity": "touch", "layout": "timeline"}]\n },\n {"type": "Section", "key": "notes", "title": "Notes", "children": ["notes"]}\n ]\n },\n {\n "type": "Record",\n "entity": "order",\n "children": [\n "due_date",\n "handler",\n {"field": "priority", "edit": false},\n "lines",\n "payments",\n {"field": "carrier", "edit": false},\n {"field": "tracking_no", "edit": false},\n {"field": "shipped_on", "edit": false},\n {"field": "cancellation_reason", "edit": false},\n {"field": "cancelled_by", "edit": false},\n {"field": "replaced_by", "edit": false},\n {"field": "attachments", "edit": false},\n "delivery_note",\n "notes",\n {"field": "reminder_ref", "edit": false},\n {"type": "Check", "field": "paid_in_full", "on": ["update"]}\n ]\n },\n {"type": "Record", "entity": "warehouse", "add": ["name", "city"]},\n {"type": "Record", "entity": "stock_item", "add": ["name", "warehouse", "sku", "category"]},\n {"type": "Record", "entity": "order_line", "add": ["item", "quantity"]}\n ]\n }\n}\n```\n\n## Case\n\n**The job.** Gather an applicant\'s papers into one case, make the forms it needs, and file it on time.\n\n**Read.** Lists with `expect` for the papers brought (one line per kind, the missing ones empty), an Act\'s `templates` for the forms made (ticked and made at once, kept in `into`), and `intake` reading the papers brought.\n\n**Keys.** `reference/list-node`, `reference/act-node`\n\n**Not when.** A record that needs no papers, or one paper made once \u2014 a single `template` act.\n\n**Its stages.** `ho_so` states Sections at its stages: its path reads down the page, each stage\'s Section under its step.\n\n```json\n{\n "tables": [\n {\n "ref": "ho_so",\n "title": "khach_hang",\n "fields": {\n "khach_hang": {"type": "link", "table": "khach_hang", "multi": false},\n "du_an": {"type": "link", "table": "du_an", "multi": false},\n "ma_ho_so": {"type": "autonumber"},\n "dich_vu": {\n "type": "select",\n "options": [{"alias": "tron_goi", "color": "blue"}, {"alias": "lam_ho_so", "color": "violet"}]\n },\n "doi_tuong": {\n "type": "select",\n "options": [\n {"alias": "thu_nhap_thap", "color": "sky"},\n {"alias": "cong_nhan", "color": "teal"},\n {"alias": "can_bo", "color": "indigo"},\n {"alias": "luc_luong", "color": "green"},\n {"alias": "ho_ngheo", "color": "amber"},\n {"alias": "nguoi_co_cong", "color": "rose"}\n ]\n },\n "tinh_trang_nha_o": {\n "type": "select",\n "options": [{"alias": "chua_co_nha", "color": "gray"}, {"alias": "nha_chat", "color": "orange"}]\n },\n "giay_chung_nhan_so": {"type": "text"},\n "dien_tich_nha": {"type": "number"},\n "sale": {"type": "member"},\n "xu_ly": {"type": "member"},\n "can_bo_sung": {"type": "boolean"},\n "phi_dich_vu": {"type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "loai_can": {\n "type": "select",\n "options": [\n {"alias": "studio", "color": "sky"},\n {"alias": "mot_pn", "color": "blue"},\n {"alias": "hai_pn", "color": "indigo"},\n {"alias": "ba_pn", "color": "violet"}\n ]\n },\n "giai_doan": {\n "type": "select",\n "options": [\n {"alias": "ngay_thu_phi", "color": "blue"},\n {"alias": "ngay_nhan_giay_to", "color": "blue"},\n {"alias": "ngay_lap_ho_so", "color": "blue"},\n {"alias": "ngay_nop_cdt", "color": "blue"},\n {"alias": "ngay_cdt_duyet", "color": "blue"},\n {"alias": "ngay_so_xd_duyet", "color": "blue"},\n {"alias": "ngay_boc_tham", "color": "blue"},\n {"alias": "ngay_ky_hdmb", "color": "green"},\n {"alias": "ngay_ban_giao", "color": "green"}\n ]\n },\n "ngay_thu_phi": {"type": "date"},\n "ngay_nhan_giay_to": {"type": "date"},\n "ngay_lap_ho_so": {"type": "date"},\n "ngay_nop_cdt": {"type": "date"},\n "ngay_cdt_duyet": {"type": "date"},\n "ngay_so_xd_duyet": {"type": "date"},\n "ngay_boc_tham": {"type": "date"},\n "ngay_ky_hdmb": {"type": "date"},\n "ngay_ban_giao": {"type": "date"},\n "bo_ho_so": {"type": "files"},\n "giay_to": {"type": "link", "table": "giay_to", "multi": true},\n "thanh_vien": {"type": "link", "table": "thanh_vien", "multi": true},\n "phieu_thu": {"type": "link", "table": "phieu_thu", "multi": true},\n "dien_thoai": {"type": "lookup"},\n "cccd": {"type": "lookup"},\n "ngay_sinh": {"type": "lookup"},\n "da_thu": {"type": "rollup"},\n "chua_thu_phi": {"type": "formula"},\n "da_hoan_tat": {"type": "formula"}\n },\n "records": {\n "subtitle": ["dich_vu"],\n "figure": "phi_dich_vu",\n "status": {\n "field": "giai_doan",\n "closed": ["ngay_ky_hdmb", "ngay_ban_giao"],\n "dates": {\n "ngay_thu_phi": "ngay_thu_phi",\n "ngay_nhan_giay_to": "ngay_nhan_giay_to",\n "ngay_lap_ho_so": "ngay_lap_ho_so",\n "ngay_nop_cdt": "ngay_nop_cdt",\n "ngay_cdt_duyet": "ngay_cdt_duyet",\n "ngay_so_xd_duyet": "ngay_so_xd_duyet",\n "ngay_boc_tham": "ngay_boc_tham",\n "ngay_ky_hdmb": "ngay_ky_hdmb",\n "ngay_ban_giao": "ngay_ban_giao"\n }\n }\n }\n },\n {\n "ref": "thanh_vien",\n "title": "ho_ten",\n "fields": {\n "ho_ten": {"type": "text"},\n "ho_so": {"type": "link", "table": "ho_so", "multi": false},\n "quan_he": {\n "type": "select",\n "options": [\n {"alias": "nguoi_dung_don", "color": "blue"},\n {"alias": "vo_chong", "color": "violet"},\n {"alias": "con", "color": "teal"},\n {"alias": "bo_me", "color": "amber"},\n {"alias": "khac", "color": "gray"}\n ]\n },\n "ngay_sinh": {"type": "date"},\n "cccd": {"type": "text"},\n "thu_nhap": {"type": "number", "notation": {"style": "currency", "currency": "VND"}}\n },\n "records": {"subtitle": ["quan_he", "cccd"], "party": "person", "figure": "thu_nhap"}\n },\n {\n "ref": "giay_to",\n "title": "loai",\n "fields": {\n "loai": {\n "type": "select",\n "options": [\n {"alias": "don_dang_ky", "color": "blue"},\n {"alias": "can_cuoc", "color": "sky"},\n {"alias": "giay_doi_tuong", "color": "violet"},\n {"alias": "xac_nhan_nha_o", "color": "teal"},\n {"alias": "xac_nhan_thu_nhap", "color": "amber"},\n {"alias": "hon_nhan", "color": "indigo"}\n ]\n },\n "ho_so": {"type": "link", "table": "ho_so", "multi": false},\n "ngay_nhan": {"type": "date"},\n "tep": {"type": "files"}\n },\n "records": {"image": "tep", "starts": {"ngay_nhan": "today"}}\n },\n {\n "ref": "phieu_thu",\n "title": "khoan",\n "fields": {\n "khoan": {\n "type": "select",\n "options": [\n {"alias": "dat_coc", "color": "blue"},\n {"alias": "tat_toan", "color": "indigo"},\n {"alias": "phi_ho_so", "color": "violet"}\n ]\n },\n "ho_so": {"type": "link", "table": "ho_so", "multi": false},\n "so_tien": {"type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "hinh_thuc": {\n "type": "select",\n "options": [\n {"alias": "tien_mat", "color": "green", "mark": {"kind": "icon", "name": "banknote"}},\n {"alias": "chuyen_khoan", "color": "blue", "mark": {"kind": "icon", "name": "arrow-right-left"}}\n ]\n },\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "cho_thu", "color": "amber"},\n {"alias": "da_thu", "color": "green"},\n {"alias": "huy", "color": "gray"}\n ]\n },\n "ngay_thu": {"type": "date"}\n },\n "records": {\n "subtitle": ["hinh_thuc", "ngay_thu"],\n "figure": "so_tien",\n "status": {"field": "trang_thai", "closed": ["da_thu", "huy"]}\n }\n }\n ],\n "templates": [\n {"alias": "don_dang_ky", "type": "html", "label": "\u0110\u01A1n \u0111\u0103ng k\xFD mua nh\xE0 \u1EDF x\xE3 h\u1ED9i"},\n {"alias": "mau_02_chua_co_nha", "type": "html", "label": "M\u1EABu 02 \u2014 X\xE1c nh\u1EADn ch\u01B0a c\xF3 nh\xE0 \u1EDF"},\n {"alias": "mau_03_nha_chat", "type": "html", "label": "M\u1EABu 03 \u2014 X\xE1c nh\u1EADn nh\xE0 \u1EDF d\u01B0\u1EDBi 15 m\xB2/ng\u01B0\u1EDDi"},\n {"alias": "mau_05_thu_nhap", "type": "html", "label": "M\u1EABu 05 \u2014 X\xE1c nh\u1EADn thu nh\u1EADp"},\n {"alias": "danh_sach_nop", "type": "html", "label": "Danh s\xE1ch h\u1ED3 s\u01A1 n\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0"}\n ],\n "body": {\n "type": "App",\n "key": "ho_so",\n "name": "H\u1ED3 s\u01A1 nh\xE0 \u1EDF x\xE3 h\u1ED9i",\n "icon": "folder-open",\n "color": "blue",\n "scope": "du_an",\n "folders": "cac_du_an",\n "children": [\n {\n "type": "List",\n "entity": "ho_so",\n "columns": ["can_bo_sung", "doi_tuong", "xu_ly"],\n "filters": ["xu_ly", "can_bo_sung"],\n "search": ["khach_hang", "ma_ho_so", "dien_thoai"],\n "create": ["khach_hang", "dich_vu", "doi_tuong", "tinh_trang_nha_o", "loai_can", "phi_dich_vu", "sale"],\n "children": [\n {\n "type": "Reading",\n "key": "register_reading_0",\n "label": "Ch\u1EDD kh\xE1ch b\u1ED5 sung",\n "where": {"can_bo_sung": true}\n },\n {\n "type": "Reading",\n "key": "register_reading_1",\n "label": "Ph\xED \u0111\xE3 thu",\n "value": "da_thu",\n "over": "ngay_nhan_giay_to"\n },\n {"type": "Reading", "key": "register_reading_2", "by": "doi_tuong"},\n {"type": "Export", "key": "export"},\n {\n "type": "Act",\n "key": "in_danh_sach",\n "label": "In danh s\xE1ch n\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0",\n "on": "view",\n "template": "danh_sach_nop"\n }\n ]\n },\n {\n "type": "List",\n "entity": "du_an",\n "key": "cac_du_an",\n "columns": ["han_nop"],\n "create": false,\n "sort": {"field": "han_nop"},\n "children": [{"type": "Reading", "key": "du_an_theo_trang_thai", "by": "trang_thai"}]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "ho_so",\n "children": [\n {\n "type": "Section",\n "key": "nguoi_dung_don",\n "title": "Ng\u01B0\u1EDDi \u0111\u1EE9ng \u0111\u01A1n",\n "children": [\n "ma_ho_so",\n {"field": "khach_hang", "block": true, "label": "Th\xF4ng tin c\xE1 nh\xE2n"},\n {\n "type": "Fieldset",\n "key": "dieu_kien",\n "label": "\u0110i\u1EC1u ki\u1EC7n mua",\n "children": ["doi_tuong", "tinh_trang_nha_o"]\n },\n {\n "type": "Fieldset",\n "key": "phu_trach",\n "label": "Ph\u1EE5 tr\xE1ch",\n "children": ["sale", "xu_ly", "can_bo_sung", "phi_dich_vu"]\n },\n {\n "type": "List",\n "entity": "thanh_vien",\n "label": "H\u1ED9 gia \u0111\xECnh",\n "columns": ["ngay_sinh"],\n "create": ["ho_ten", "quan_he", "ngay_sinh", "cccd", "thu_nhap"]\n },\n {\n "type": "List",\n "entity": "giay_to",\n "expect": {"field": "loai", "only": ["can_cuoc", "hon_nhan"]},\n "label": "Gi\u1EA5y t\u1EDD c\xE1 nh\xE2n",\n "columns": ["ngay_nhan"]\n },\n {\n "type": "Act",\n "key": "doc_giay_to",\n "label": "\u0110\u1ECDc gi\u1EA5y t\u1EDD",\n "intake": "giay_to",\n "fills": [\n "doi_tuong",\n "tinh_trang_nha_o",\n "giay_chung_nhan_so",\n "dien_tich_nha",\n "khach_hang.ho_ten",\n "khach_hang.cccd",\n "khach_hang.ngay_sinh",\n "khach_hang.dia_chi",\n "thanh_vien"\n ]\n },\n {\n "type": "Act",\n "key": "giao_xu_ly",\n "label": "Giao ng\u01B0\u1EDDi x\u1EED l\xFD",\n "asks": [{"input": "nguoi", "label": "Ng\u01B0\u1EDDi x\u1EED l\xFD", "type": "member", "required": true}],\n "set": {"xu_ly": {"input": "nguoi"}}\n },\n {\n "type": "Act",\n "key": "chuyen_du_an",\n "label": "Chuy\u1EC3n d\u1EF1 \xE1n",\n "asks": [\n {\n "input": "du_an_moi",\n "label": "Sang d\u1EF1 \xE1n",\n "type": "link",\n "entity": "du_an",\n "required": true\n }\n ],\n "set": {"du_an": {"input": "du_an_moi"}},\n "confirm": true\n }\n ]\n },\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "bo_ho_so",\n "title": "B\u1ED9 h\u1ED3 s\u01A1",\n "at": ["ngay_nhan_giay_to", "ngay_lap_ho_so"],\n "children": [\n "ngay_nhan_giay_to",\n "ngay_lap_ho_so",\n {\n "type": "Act",\n "key": "tao_giay_to",\n "label": "T\u1EA1o gi\u1EA5y t\u1EDD",\n "templates": [\n {"template": "don_dang_ky"},\n {"template": "mau_02_chua_co_nha", "when": {"tinh_trang_nha_o": ["chua_co_nha"]}},\n {"template": "mau_03_nha_chat", "when": {"tinh_trang_nha_o": ["nha_chat"]}}\n ],\n "into": "bo_ho_so",\n "when": {"giai_doan": ["ngay_nhan_giay_to", "ngay_lap_ho_so"]}\n },\n {\n "type": "Act",\n "key": "nop_cdt",\n "label": "N\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0",\n "when": {"dich_vu": ["tron_goi"], "giai_doan": ["ngay_lap_ho_so"]},\n "requires": ["bo_ho_so", "loai_can"],\n "asks": ["loai_can"],\n "set": {"giai_doan": "ngay_nop_cdt"},\n "confirm": true\n },\n {\n "type": "Act",\n "key": "to_ngay_nhan_giay_to",\n "label": "\u0110\xE3 nh\u1EADn gi\u1EA5y t\u1EDD",\n "when": {"giai_doan": {"empty": true}, "dich_vu": ["tron_goi"]},\n "asks": [{"field": "ngay_nhan_giay_to", "starts": "today"}],\n "set": {"giai_doan": "ngay_nhan_giay_to"}\n },\n {\n "type": "Act",\n "key": "to_ngay_lap_ho_so",\n "label": "\u0110\xE3 l\u1EADp h\u1ED3 s\u01A1",\n "when": {"giai_doan": ["ngay_nhan_giay_to"], "dich_vu": ["tron_goi"]},\n "asks": [{"field": "ngay_lap_ho_so", "starts": "today"}],\n "set": {"giai_doan": "ngay_lap_ho_so"}\n },\n {\n "type": "Act",\n "key": "to_ngay_ban_giao",\n "label": "\u0110\xE3 b\xE0n giao h\u1ED3 s\u01A1",\n "when": {"giai_doan": ["ngay_nhan_giay_to"], "dich_vu": ["lam_ho_so"]},\n "asks": [{"field": "ngay_ban_giao", "starts": "today"}],\n "set": {"giai_doan": "ngay_ban_giao"}\n }\n ]\n }\n ]\n },\n {\n "type": "Act",\n "key": "lap_mau_05",\n "label": "L\u1EADp m\u1EABu 05",\n "when": {"doi_tuong": ["thu_nhap_thap"]},\n "template": "mau_05_thu_nhap",\n "paper": "giay_to.xac_nhan_thu_nhap"\n },\n {"type": "Check", "field": "chua_thu_phi", "on": ["nop_cdt"]},\n {"type": "Check", "field": "da_hoan_tat", "on": ["doc_giay_to"]}\n ],\n "row": {"figure": false}\n },\n {"type": "Record", "entity": "du_an", "add": ["ten_du_an", "chu_dau_tu", "so_can"]}\n ]\n }\n}\n```\n\n## Calls\n\n**The job.** Call a lead from their record, and keep what was said as a touch on its timeline.\n\n**Read.** An Act\'s `record` (into the `timeline` child: audio, transcript, when and who) and `fills` (the touch\'s fields an agent fills from the transcript).\n\n**Keys.** `reference/act-node`, `reference/layouts`\n\n**Not when.** Calls made and logged elsewhere \u2014 a `timeline` with its own add keeps the note.\n\n**Its stages.** `khach_tiem_nang` states Sections at its stages: its path reads down the page, each stage\'s Section under its step. `buoc_tiep` states no Section at a stage and its Acts move it: its path draws as a line of steps across the page.\n\n```json\n{\n "tables": [\n {\n "ref": "khach_tiem_nang",\n "title": "ho_ten",\n "fields": {\n "ho_ten": {"type": "text"},\n "ten_cong_ty": {"type": "text"},\n "vai_tro": {\n "type": "select",\n "options": [\n {"alias": "chu_doanh_nghiep", "color": "emerald"},\n {"alias": "ke_toan_truong", "color": "blue"},\n {"alias": "quan_ly", "color": "teal"},\n {"alias": "nhan_vien", "color": "sky"},\n {"alias": "chua_ro", "color": "zinc"}\n ]\n },\n "loai_hinh": {\n "type": "select",\n "options": [\n {"alias": "thuong_mai", "color": "blue"},\n {"alias": "san_xuat", "color": "amber"},\n {"alias": "dich_vu", "color": "violet"},\n {"alias": "xay_dung", "color": "orange"},\n {"alias": "ho_kinh_doanh", "color": "teal"},\n {"alias": "chua_ro", "color": "zinc"}\n ]\n },\n "quy_mo": {\n "type": "select",\n "options": [\n {"alias": "q_1_10", "color": "sky"},\n {"alias": "q_11_50", "color": "blue"},\n {"alias": "q_51_200", "color": "indigo"},\n {"alias": "q_200", "color": "violet"},\n {"alias": "chua_ro", "color": "zinc"}\n ]\n },\n "so_dien_thoai": {"type": "text"},\n "zalo": {"type": "text"},\n "email": {"type": "text"},\n "trang_ca_nhan": {"type": "text", "format": "link"},\n "anh": {"type": "files"},\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "moi", "color": "gray"},\n {"alias": "du_dieu_kien", "color": "blue"},\n {"alias": "da_lien_he", "color": "amber"},\n {"alias": "da_chuyen_doi", "color": "emerald"},\n {"alias": "loai", "color": "red"}\n ]\n },\n "ly_do_loai": {\n "type": "select",\n "options": [\n {"alias": "khong_phu_hop", "color": "orange"},\n {"alias": "qua_nho", "color": "amber"},\n {"alias": "chua_co_ngan_sach", "color": "yellow"},\n {"alias": "sai_nguoi", "color": "blue"},\n {"alias": "yeu_cau_dung", "color": "red"},\n {"alias": "trung", "color": "zinc"}\n ]\n },\n "vi_sao_du_dieu_kien": {"type": "text"},\n "phu_trach": {"type": "member"},\n "nguon": {"type": "link", "table": "kenh", "multi": false},\n "lien_he": {"type": "link", "table": "lien_he", "multi": false},\n "cong_ty": {"type": "link", "table": "cong_ty", "multi": false},\n "ngay_chuyen_doi": {"type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n "ghi_chu": {"type": "text", "format": "markdown"},\n "tin_hieu": {"type": "link", "table": "tin_hieu", "multi": true},\n "buoc_tiep": {"type": "link", "table": "buoc_tiep", "multi": true},\n "tuong_tac": {"type": "link", "table": "tuong_tac", "multi": true},\n "do_nong": {\n "type": "formula",\n "options": [\n {"alias": "nong", "label": "N\xF3ng", "color": "orange"},\n {"alias": "nguoi", "label": "Ngu\u1ED9i", "color": "sky"}\n ]\n },\n "han_buoc_tiep": {"type": "rollup"},\n "khong_lien_he": {"type": "formula"}\n },\n "records": {\n "subtitle": ["ten_cong_ty"],\n "image": "anh",\n "party": "person",\n "due": ["han_buoc_tiep"],\n "status": {\n "field": "trang_thai",\n "closed": ["da_chuyen_doi", "loai"],\n "dates": {"da_chuyen_doi": "ngay_chuyen_doi"}\n }\n }\n },\n {\n "ref": "tin_hieu",\n "title": "tom_tat",\n "fields": {\n "tom_tat": {"type": "text"},\n "noi_dung": {"type": "text", "format": "markdown"},\n "anh_chup": {"type": "files"},\n "lien_ket": {"type": "text", "format": "link"},\n "kenh": {"type": "link", "table": "kenh", "multi": false},\n "loai": {\n "type": "select",\n "options": [\n {"alias": "hoi_dich_vu", "color": "emerald"},\n {"alias": "than_phien", "color": "blue"},\n {"alias": "tuyen_ke_toan", "color": "amber"},\n {"alias": "moi_thanh_lap", "color": "violet"},\n {"alias": "gioi_thieu", "color": "teal"},\n {"alias": "danh_ba", "color": "zinc"},\n {"alias": "nhieu", "color": "stone"}\n ]\n },\n "ngay_dang": {"type": "date", "timezone": "Asia/Ho_Chi_Minh"},\n "ngay_xay_ra": {"type": "formula"}\n },\n "records": {"subtitle": ["kenh", "ngay_xay_ra"], "image": "anh_chup"}\n },\n {\n "ref": "buoc_tiep",\n "title": "vi_sao_luc_nay",\n "fields": {\n "vi_sao_luc_nay": {"type": "text"},\n "viec": {\n "type": "select",\n "options": [\n {"alias": "binh_luan", "color": "blue", "mark": {"kind": "icon", "name": "message-square"}},\n {"alias": "nhan_facebook", "color": "violet", "mark": {"kind": "brand", "name": "facebook"}},\n {"alias": "nhan_zalo", "color": "sky", "mark": {"kind": "brand", "name": "zalo"}},\n {"alias": "goi_dien", "color": "teal", "mark": {"kind": "icon", "name": "phone"}},\n {"alias": "gui_email", "color": "indigo", "mark": {"kind": "icon", "name": "mail"}},\n {"alias": "gui_bang_gia", "color": "amber", "mark": {"kind": "icon", "name": "receipt"}}\n ]\n },\n "ban_nhap": {"type": "text", "format": "markdown"},\n "han": {"type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n "tinh_trang": {\n "type": "select",\n "options": [\n {"alias": "cho", "color": "blue"},\n {"alias": "xong", "color": "emerald"},\n {"alias": "bo_qua", "color": "zinc"}\n ]\n }\n },\n "records": {\n "subtitle": ["viec"],\n "mark": "viec",\n "due": ["han"],\n "status": {"field": "tinh_trang", "closed": ["xong", "bo_qua"]}\n }\n },\n {\n "ref": "tuong_tac",\n "title": "tom_tat",\n "fields": {\n "tom_tat": {"type": "text"},\n "thoi_diem": {"type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n "qua": {\n "type": "select",\n "options": [\n {"alias": "goi_dien", "color": "teal", "mark": {"kind": "icon", "name": "phone"}},\n {"alias": "zalo", "color": "sky", "mark": {"kind": "brand", "name": "zalo"}},\n {"alias": "facebook", "color": "blue", "mark": {"kind": "brand", "name": "facebook"}},\n {"alias": "email", "color": "indigo", "mark": {"kind": "icon", "name": "mail"}},\n {"alias": "gap_truc_tiep", "color": "emerald", "mark": {"kind": "icon", "name": "users"}},\n {"alias": "khac", "color": "zinc", "mark": {"kind": "icon", "name": "ellipsis"}}\n ]\n },\n "phan_hoi": {\n "type": "select",\n "options": [\n {"alias": "dang_cho", "color": "blue"},\n {"alias": "da_tra_loi", "color": "green"},\n {"alias": "quan_tam", "color": "amber"},\n {"alias": "khong_phu_hop", "color": "red"},\n {"alias": "khong_phan_hoi", "color": "zinc"},\n {"alias": "sai_so", "color": "stone"}\n ]\n },\n "ghi_am": {"type": "files"},\n "man_hinh": {"type": "files"},\n "nguyen_van": {"type": "text", "format": "markdown"},\n "hen_lai": {"type": "date", "timezone": "Asia/Ho_Chi_Minh"},\n "nguoi_thuc_hien": {"type": "member"}\n },\n "records": {"subtitle": ["qua", "phan_hoi"]}\n }\n ],\n "body": {\n "type": "App",\n "key": "khach_tiem_nang",\n "name": "Kh\xE1ch ti\u1EC1m n\u0103ng",\n "icon": "radar",\n "color": "violet",\n "children": [\n {\n "type": "List",\n "entity": "khach_tiem_nang",\n "columns": ["phu_trach", "han_buoc_tiep"],\n "filters": ["phu_trach"],\n "create": ["ho_ten", "trang_ca_nhan", "so_dien_thoai", "ten_cong_ty", "nguon"],\n "children": [\n {"type": "Reading", "key": "register_reading_0", "by": "phu_trach"},\n {\n "type": "Reading",\n "key": "register_reading_1",\n "label": "Kh\xE1ch chuy\u1EC3n \u0111\u1ED5i",\n "by": "ngay_chuyen_doi"\n }\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "khach_tiem_nang",\n "children": [\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "danh_gia",\n "title": "\u0110\xE1nh gi\xE1",\n "at": ["moi"],\n "children": [\n "vai_tro",\n "loai_hinh",\n "quy_mo",\n "vi_sao_du_dieu_kien",\n "do_nong",\n {\n "type": "List",\n "entity": "tin_hieu",\n "columns": ["loai", "noi_dung"],\n "create": ["tom_tat", "anh_chup", "loai", "noi_dung", "kenh", "lien_ket", "ngay_dang"]\n },\n {\n "type": "Act",\n "key": "danh_gia_dat",\n "label": "\u0110\u1EE7 \u0111i\u1EC1u ki\u1EC7n",\n "when": {"trang_thai": ["moi"]},\n "requires": ["vi_sao_du_dieu_kien"],\n "set": {"trang_thai": "du_dieu_kien"}\n }\n ]\n },\n {\n "type": "Section",\n "key": "lien_he",\n "title": "Li\xEAn h\u1EC7",\n "at": ["du_dieu_kien"],\n "children": [\n "so_dien_thoai",\n "phu_trach",\n "trang_ca_nhan",\n "zalo",\n "email",\n {"field": "ghi_chu", "block": false},\n {\n "type": "List",\n "entity": "buoc_tiep",\n "columns": ["ban_nhap"],\n "create": ["vi_sao_luc_nay", "viec", "han", "ban_nhap"]\n },\n {\n "type": "List",\n "entity": "tuong_tac",\n "layout": "timeline",\n "create": ["tom_tat", "qua", "phan_hoi", "thoi_diem", "hen_lai"]\n },\n {\n "type": "Act",\n "key": "ghi_cuoc_goi",\n "label": "Ghi \xE2m cu\u1ED9c g\u1ECDi",\n "when": {"trang_thai": ["du_dieu_kien"]},\n "fills": ["tom_tat", "phan_hoi"],\n "record": {\n "into": "tuong_tac",\n "audio": "ghi_am",\n "transcript": "nguyen_van",\n "at": "thoi_diem",\n "by": "nguoi_thuc_hien",\n "video": "man_hinh"\n }\n },\n {\n "type": "Act",\n "key": "da_lien_he",\n "label": "\u0110\xE1nh d\u1EA5u \u0111\xE3 li\xEAn h\u1EC7",\n "when": {"trang_thai": ["du_dieu_kien"]},\n "set": {"trang_thai": "da_lien_he"}\n }\n ]\n },\n {\n "type": "Section",\n "key": "chuyen_doi",\n "title": "Chuy\u1EC3n \u0111\u1ED5i",\n "at": ["da_lien_he"],\n "children": [\n "nguon",\n {"field": "lien_he", "edit": false},\n {"field": "cong_ty", "edit": false},\n {\n "type": "Act",\n "key": "chuyen_doi",\n "label": "Chuy\u1EC3n \u0111\u1ED5i",\n "when": {"trang_thai": ["da_lien_he"]},\n "workflow": "chuyen_doi_khach",\n "confirm": true\n }\n ]\n },\n {\n "type": "Section",\n "key": "loai",\n "title": "Lo\u1EA1i",\n "at": ["loai"],\n "children": [\n "ly_do_loai",\n {\n "type": "Act",\n "key": "loai",\n "label": "Lo\u1EA1i",\n "when": {"trang_thai": ["moi", "du_dieu_kien", "da_lien_he"]},\n "asks": ["ly_do_loai"],\n "set": {"trang_thai": "loai"},\n "danger": true\n },\n {\n "type": "Act",\n "key": "mo_lai",\n "label": "M\u1EDF l\u1EA1i",\n "when": {"trang_thai": ["loai"]},\n "set": {"trang_thai": "moi"}\n }\n ]\n }\n ]\n },\n {"type": "Check", "field": "khong_lien_he", "resolve": "da_lien_he"}\n ]\n },\n {"type": "Record", "entity": "kenh", "add": ["ten", "loai"]},\n {\n "type": "Record",\n "entity": "buoc_tiep",\n "children": [\n {\n "type": "Act",\n "key": "lam_xong",\n "label": "\u0110\xE3 l\xE0m",\n "when": {"tinh_trang": ["cho"]},\n "set": {"tinh_trang": "xong"}\n }\n ]\n }\n ]\n }\n}\n```\n\n## Approval\n\n**The job.** Raise a payment request, see it through approval, and read what is waiting at the top of the list.\n\n**Read.** `records.de_nghi.status` with its `history` (each move: when and who), Sections staged by `at`, and the List\'s Readings leading with the headline number. The history stays because the business reads who signed each move; where only the day a stage was reached matters, the status stamps a date on the row instead (the Gantt above).\n\n**Keys.** `reference/status`, `reference/section-node`, `reference/reading-node`\n\n**Not when.** Rows that never move \u2014 a reference list (a price list, a catalog) has no status and no headline number.\n\n**Its stages.** `de_nghi` states Sections at its stages: its path reads down the page, each stage\'s Section under its step.\n\n```json\n{\n "tables": [\n {\n "ref": "de_nghi",\n "title": "noi_dung",\n "fields": {\n "noi_dung": {"type": "text"},\n "so_de_nghi": {"type": "text"},\n "loai": {\n "type": "select",\n "options": [\n {"alias": "thanh_toan_ncc", "color": "violet"},\n {"alias": "nhan_cong", "color": "indigo"},\n {"alias": "chi_phi_cong_truong", "color": "sky"},\n {"alias": "tam_ung", "color": "amber"},\n {"alias": "hoan_ung", "color": "teal"}\n ]\n },\n "du_an": {"type": "link", "table": "du_an", "multi": false},\n "nha_cung_cap": {"type": "link", "table": "nha_cung_cap", "multi": false},\n "so_tien": {"type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "han_thanh_toan": {"type": "date"},\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "nhap", "color": "slate"},\n {"alias": "cho_duyet", "color": "amber"},\n {"alias": "cho_chu_tich", "color": "violet"},\n {"alias": "da_duyet", "color": "blue"},\n {"alias": "da_chi", "color": "green"},\n {"alias": "tu_choi", "color": "rose"}\n ]\n },\n "nguoi_de_nghi": {"type": "member"},\n "chung_tu": {"type": "files"},\n "nguoi_duyet": {"type": "member"},\n "duyet_luc": {"type": "date", "format": "datetime"},\n "ly_do_tu_choi": {"type": "text"},\n "phieu_chi": {"type": "files"},\n "ngan_sach_du_an": {"type": "lookup"},\n "da_duyet_du_an": {"type": "lookup"},\n "da_gui": {"type": "formula"},\n "nhap_at": {"type": "date", "format": "datetime"},\n "cho_duyet_at": {"type": "date", "format": "datetime"},\n "cho_chu_tich_at": {"type": "date", "format": "datetime"},\n "da_duyet_at": {"type": "date", "format": "datetime"}\n },\n "records": {\n "subtitle": ["du_an"],\n "figure": "so_tien",\n "limits": {"da_duyet_du_an": "ngan_sach_du_an"},\n "due": ["han_thanh_toan"],\n "starts": {"nguoi_de_nghi": "me"},\n "status": {\n "field": "trang_thai",\n "closed": ["da_chi", "tu_choi"],\n "dropped": ["tu_choi"],\n "dates": {\n "nhap": "nhap_at",\n "cho_duyet": "cho_duyet_at",\n "cho_chu_tich": "cho_chu_tich_at",\n "da_duyet": "da_duyet_at"\n },\n "history": "lich_su_duyet",\n "stages": {\n "nhap": {"owner": "nguoi_de_nghi"},\n "cho_duyet": {"owner": {"group": "<id of the giam_doc group>"}, "within": 1},\n "cho_chu_tich": {\n "owner": {"group": "<id of the chu_tich group>"},\n "within": 2,\n "when": {"so_tien": {"gt": 200000000}}\n },\n "da_duyet": {"owner": {"group": "<id of the ke_toan group>"}, "within": 2}\n }\n }\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "de_nghi_chi",\n "name": "\u0110\u1EC1 ngh\u1ECB thanh to\xE1n",\n "icon": "hand-coins",\n "color": "amber",\n "children": [\n {\n "type": "List",\n "entity": "de_nghi",\n "filters": ["du_an"],\n "group": "du_an",\n "create": ["noi_dung", "loai", "du_an", "nha_cung_cap", "so_tien", "han_thanh_toan", "nguoi_de_nghi"],\n "children": [\n {\n "type": "Reading",\n "key": "register_reading_0",\n "label": "\u0110\xE3 duy\u1EC7t, ch\u1EDD chi",\n "value": "so_tien",\n "where": {"trang_thai": ["da_duyet"]}\n },\n {"type": "Reading", "key": "register_reading_1", "value": "so_tien", "by": "han_thanh_toan"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "de_nghi",\n "door": "drawer",\n "children": [\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "de_nghi",\n "title": "\u0110\u1EC1 ngh\u1ECB",\n "at": ["nhap"],\n "children": [\n "so_de_nghi",\n "loai",\n "nha_cung_cap",\n "han_thanh_toan",\n "nguoi_de_nghi",\n {"field": "chung_tu"},\n {\n "type": "Act",\n "key": "gui_duyet",\n "label": "G\u1EEDi duy\u1EC7t",\n "when": {"trang_thai": ["nhap"]},\n "requires": ["chung_tu", "nguoi_de_nghi"],\n "set": {"trang_thai": "cho_duyet"}\n }\n ]\n },\n {\n "type": "Section",\n "key": "duyet",\n "title": "Duy\u1EC7t",\n "at": ["cho_duyet", "cho_chu_tich"],\n "children": [\n {"field": "nguoi_duyet", "edit": false},\n {"field": "duyet_luc", "edit": false},\n {"field": "ly_do_tu_choi", "edit": false},\n {\n "type": "Act",\n "key": "rut_lai",\n "label": "R\xFAt l\u1EA1i",\n "when": {"trang_thai": ["cho_duyet", "cho_chu_tich"]},\n "set": {"trang_thai": "nhap"},\n "confirm": true\n }\n ]\n },\n {\n "type": "Section",\n "key": "da_chi",\n "title": "\u0110\xE3 chi",\n "at": ["da_chi"],\n "children": [{"field": "phieu_chi", "edit": false}]\n }\n ]\n },\n {"type": "Check", "field": "da_gui", "on": ["update"]}\n ]\n },\n {"type": "Record", "entity": "du_an", "add": ["ten", "ma_du_an", "chu_dau_tu", "ngan_sach"]}\n ]\n }\n}\n```\n\n## Dashboard\n\n**The job.** The owner\'s question \u2014 what came in, what went out, where it went, and what is still unmatched \u2014 answered over one period.\n\n**Read.** An App of Readings and no List: Readings with `over` (the period windows them), a Reading `by` the day, Readings `by` a field, and a List of rows to act on.\n\n**Keys.** `reference/app-node`, `reference/reading-node`\n\n**Not when.** One job\'s headline numbers \u2014 those lead that job\'s List as its Readings.\n\n```json\n{\n "tables": [\n {\n "ref": "giao_dich",\n "title": "noi_dung",\n "fields": {\n "noi_dung": {"type": "text"},\n "ngay": {"type": "date"},\n "loai": {"type": "select", "options": [{"alias": "thu", "color": "green"}, {"alias": "chi", "color": "rose"}]},\n "so_tien": {"type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "bien_dong": {"type": "formula", "notation": {"style": "currency", "currency": "VND"}},\n "doi_tuong": {"type": "link", "table": "doi_tuong", "multi": false},\n "danh_muc": {\n "type": "select",\n "options": [\n {"alias": "doanh_thu", "color": "green"},\n {"alias": "hang_hoa", "color": "blue"},\n {"alias": "van_chuyen", "color": "indigo"},\n {"alias": "nhan_su", "color": "violet"},\n {"alias": "van_phong", "color": "sky"},\n {"alias": "thue_phi", "color": "slate"},\n {"alias": "ngan_hang", "color": "teal"},\n {"alias": "khac", "color": "gray"}\n ]\n },\n "sao_ke": {"type": "link", "table": "sao_ke", "multi": false},\n "hoa_don": {"type": "link", "table": "hoa_don", "multi": true},\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "chua_khop", "color": "amber"},\n {"alias": "da_khop", "color": "green"},\n {"alias": "khong_can_hd", "color": "slate"}\n ]\n },\n "khop_luc": {"type": "date", "format": "datetime"}\n },\n "records": {\n "subtitle": ["ngay"],\n "figure": "bien_dong",\n "status": {"field": "trang_thai", "closed": ["da_khop", "khong_can_hd"], "dates": {"da_khop": "khop_luc"}}\n }\n },\n {\n "ref": "hoa_don",\n "title": "doi_tuong",\n "fields": {\n "doi_tuong": {"type": "link", "table": "doi_tuong", "multi": false},\n "so_hoa_don": {"type": "text"},\n "ngay_hoa_don": {"type": "date"},\n "so_ngay_qua_han": {"type": "formula", "notation": {"style": "unit", "unit": "day"}},\n "chieu": {\n "type": "select",\n "options": [{"alias": "ban_ra", "color": "green"}, {"alias": "mua_vao", "color": "violet"}]\n },\n "tong_cong": {"type": "formula", "notation": {"style": "currency", "currency": "VND"}},\n "tep": {"type": "files"},\n "giao_dich": {"type": "link", "table": "giao_dich", "multi": true}\n },\n "records": {"subtitle": ["so_hoa_don", "ngay_hoa_don"], "image": "tep", "figure": "tong_cong"}\n }\n ],\n "body": {\n "type": "App",\n "key": "dong_tien",\n "name": "D\xF2ng ti\u1EC1n",\n "icon": "chart-line",\n "color": "emerald",\n "children": [\n {\n "type": "Sheet",\n "key": "dong_tien",\n "label": "D\xF2ng ti\u1EC1n",\n "children": [\n {\n "type": "Reading",\n "key": "dashboard_reading_0",\n "label": "Ti\u1EC1n v\xE0o",\n "entity": "giao_dich",\n "value": "so_tien",\n "where": {"loai": ["thu"]},\n "over": "ngay"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_1",\n "label": "Ti\u1EC1n ra",\n "entity": "giao_dich",\n "value": "so_tien",\n "where": {"loai": ["chi"]},\n "over": "ngay",\n "better": "down"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_2",\n "label": "D\xF2ng ti\u1EC1n r\xF2ng",\n "entity": "giao_dich",\n "value": "bien_dong",\n "by": "ngay"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_3",\n "label": "Chi theo danh m\u1EE5c",\n "entity": "giao_dich",\n "value": "so_tien",\n "where": {"loai": ["chi"]},\n "by": "danh_muc",\n "over": "ngay"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_4",\n "label": "Thu theo kh\xE1ch h\xE0ng",\n "entity": "giao_dich",\n "value": "so_tien",\n "where": {"loai": ["thu"]},\n "by": "doi_tuong",\n "over": "ngay"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_5",\n "label": "C\xF4ng n\u1EE3 b\xE1n ra theo tu\u1ED5i n\u1EE3",\n "entity": "hoa_don",\n "value": "tong_cong",\n "where": {"chieu": ["ban_ra"]},\n "by": "doi_tuong",\n "across": {"field": "so_ngay_qua_han", "tiers": [1, 8, 16, 31]}\n },\n {\n "type": "List",\n "key": "dashboard_reading_8",\n "entity": "giao_dich",\n "where": {"trang_thai": ["chua_khop"]},\n "label": "D\xF2ng ch\u01B0a kh\u1EDBp",\n "columns": ["sao_ke"]\n }\n ]\n }\n ]\n }\n}\n```\n';
1890
1890
 
1891
1891
  // docs/agent_surface.md
1892
- var agent_surface_default = '# An app\'s agent surface\n\nEverything a person reads or does in an app, an agent reads or does through that app\'s **queries** and\n**workflows** \u2014 the same ones its screen runs, under the same permissions and the same rules. Three tools\nreach them, over MCP and as `lotics run <tool>`:\n\n| Tool | Answers |\n|---|---|\n| `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`) \u2014 beside what each table they name holds, in its owner\'s words \u2014 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) |\n| `run_app_query` | The rows, a count or the groups of one query \u2014 or of several in one call |\n| `run_app_workflow` | One write \u2014 or several in order \u2014 or a dry run of it that writes nothing |\n\nAn app generates this surface from its tree; Query and Workflow nodes declare what the screen never\nasks (`agent_surface/declaring-more`). Every root List of an app (a change may add one at any time) is part of it: each List\'s list, its rows by id, its page\'s\nLists and its Acts are queries and workflows of the same app, named by that List\'s table \u2014 `get_app` lists them in the\none roster, and nothing of a root List is another app\'s. Every caller the app is shared with is answered them, its rows narrowed by the app\'s row rules. A custom-code app\'s surface is the queries and workflows bound on it\n(`app_bindings`).\n\n## Finding what an app offers\n\n`get_workspace` maps the workspace. Its `search` matches the keys and descriptions of the Query and Workflow nodes an app declares, and the app\'s line names the matching keys; it never matches the generated `act_`, `create_` or `update_` aliases. `get_app` then gives the contracts. An agent runs a declared node before it falls back to `query_records`.\n\n## What every app generates\n\nA name in angle brackets is the app\'s alias for that thing; an `<entity>` is the alias of a table the app reads. `get_app` lists the ones a given\napp has.\n\n### Queries\n\n<!-- generated:start queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per List `filters` field holding one value \u2014 a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter \u2014 none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter \u2014 none over sources, none for a looked-up link or member, none for a number read in each row\'s own unit or currency | every entity the app draws; the filter params on the app\'s own entity alone; a root List after the first over an entity, whose chips differ from the first\'s, adds one of its own, called by its key |\n| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list\'s; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each Tab of the register, and of each later root List over an entity, called by its key; none over sources, none for a Tab whose period reads a date holding a span |\n| `<entity>_totals_<tab>` | The <child> rows added per <entity> row, by "<link>", over the period from `from` to `to`, dated by "<date>": . | `from`; `to` | each Tab of the register stating `totals`, and of each later root List over an entity, called by its key |\n| `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |\n| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each List of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |\n| `outside_<key>_one` | One row of <entity> by its id. | `record` | each Outside: the record a link opens, projected to the fields the Outside states |\n| `outside_<key>_<child>` | The <child> rows under one <entity>, through "<link>". | `record` | each List of an Outside: the rows under the record a link opens, projected to the List\'s columns |\n| `<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 |\n| `<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`) |\n| `<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 |\n| `<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 a List\'s band, called by its `key` \u2014 but the work against its plan (a Reading stating `planned` and `done`), which reads the List\'s own rows; none over sources |\n| `<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each Reading and List of a Sheet, called by its `key` |\n| `<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a List stating `same`; `record_<field>` per `where` bound to a field of the record | each Reading of a Record page, each List that only reads on it (its `key`, else its entity\'s alias) and each funnel, called by its `key` |\n| `<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 |\n| `<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 |\n| `<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 |\n| `<entity>_export_rows_of_<source>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | an Export over some of a List\'s sources: their rows alone, each source named in turn |\n| `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |\n| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads \u2014 the rows with no <place> counted apart. | | a register laid out as a `plan`: its places\' counts of present rows |\n\n<!-- generated:end queries -->\n\nA reading\'s query returns groups, never the rows it read: one row for all of them, or one per value it\nsplits by, or per day. Each row carries the alias of each field it splits by, `__day` where it splits by\nday, `__count`, and `__sum` where it sums a number; its description states which. An average is `__sum`\nover `__count`, both over the rows holding a value.\n\nA Reading is called by its `key` (`reference/reading-node`), and a List that only reads by its `key`, else its entity\'s alias \u2014 wherever its List stands in the app, so a move in the tree changes no name. Each is its own among the app\'s Readings, Lists that only read and Queries.\n\nA register reading\'s query reads the rows it names, whatever a screen has open: the rows of its `tab` where\nit states one, every tab\'s where it states none \u2014 its description says which. One placed in time (`over`)\nreads every day unless the call states `from` or `to`.\n\n### Queries the screen runs for itself\n\nThey run like any other, and `get_app` leaves them out: each feeds one control, and takes ids\nthe screen already holds.\n\n<!-- generated:start screen-queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<child>_<link>_target` | One <entity> row by its id, where a <child> row\'s "<link>" may point at it. | `<entity>_id` | a List with `pick` whose link a write rule narrows |\n| `<entity>_<field>_values` | Each "<field>" the <entity> rows hold, once, most held first, narrowed by what the reader typed. | `search`? | a text field a write rule offers values to (`suggest`) |\n| `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |\n| `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. | | an app stating `scope` |\n| `<task>_progress_by_<link>` | How many <task> rows each <entity> row handed in holds, at each status. | `<entity>_ids` | rows whose task rows are counted done |\n| `<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 |\n| `<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 |\n| `<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` |\n| `<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`) |\n\n<!-- generated:end screen-queries -->\n\n### Workflows\n\n<!-- generated:start workflows -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `create_<entity>` | Opens one row of <entity>. | every field the add asks, and the link it files the row under; a field the Lists adding the entity hold may be left out | an entity the app adds rows of |\n| `update_<entity>` | Changes one row of <entity>; every input but the row is optional, and one left out is left as it is. | `record_id`, and each field a person edits \u2014 a files field or a link to several rows as `<field>_added` / `<field>_removed` | an entity the app edits |\n| `move_<list>` | Gives rows of <entity> to a <lane> together: every row is judged before any is written, so a refusal leaves them all as they were. `lane` left out leaves the <lane> as it is, `lane` empty clears it; `day` dates only the rows holding none; `order` places each by its number. | `record_ids`, `lane` (left out, the lane stays; empty, none), `day` for the rows holding none, and `order`: each row\'s id and number | a lanes board of days with no hour whose app writes its lane |\n| `remove_<entity>` | Removes one row of <entity>. | `record_id` | an entity the app removes rows of |\n| `restore_<entity>` | Brings back one deleted row of <entity>. | `record_id` | an entity the app removes rows of |\n| `act_<act>` | <label> \u2014 on one row of <entity>, refused where its conditions do not hold. | `record_id` \u2014 `record_ids` on an act over several rows \u2014 and what the act asks | each Act that names no workflow of its own |\n| `archive_<act>` | Hands back every file of <label> on one row of <entity> as one archive. | `record_id` | an Act making a set of papers (`templates`) |\n\n<!-- generated:end workflows -->\n\nA Workflow node is called by its `key`, and every Act by `act_<key>`; an Act that names its own `workflow` is also called by that workflow\'s alias.\n\n## Calling a query\n\n```\nget_app {"app_id":"app_\u2026"}\nrun_app_query {"app_id":"app_\u2026","alias":"order_list","params":{"status_is":"open","due_on_to":"2031-03-14"}}\n```\n\n| Argument | Does |\n|---|---|\n| `params` | The query\'s declared params. A required one is always sent; an optional one left out narrows nothing. A select takes the option\'s alias as `get_app` lists it in `select(label=alias|\u2026)` \u2014 a link a record id, a member a member id, a date `yyyy-mm-dd` |\n| `filters` | Narrows the result further, by the query\'s output columns (`filters`) |\n| `fields` | The output columns to return, in place of all of them; each row then holds them and the id of the record it is |\n| `sort` | An order in place of the query\'s own: `[{ "field_key": "<column>", "order": "asc" }]`, `asc` or `desc`, each `field_key` an output column\'s name |\n| `count` | `true`: `total`, the number of rows, in place of the rows; with `count_by`, `counts` per value of one column, keyed by an option\'s label, a member\'s name or a linked row\'s display; with `count_where` \u2014 a map of name \u2192 filter, never beside `count_by` \u2014 `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |\n| `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), `bands` (a number column of `by` grouped by its breakpoints), or `day` (a date column, answered as `__day`), `sum` (a number column, answered as `__sum`) and `avg` (a number column averaged over the group\'s rows that hold one, answered as `__avg`), each group with its `__count`. Sent with `params` and `filters` alone. Buckets are by day only: a period\'s total is one call per period, with `from` and `to` or a date filter |\n| `limit`, `cursor` | A page \u2014 200 rows at most, 50 where no `limit` is stated \u2014 and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |\n| `runs` | Several reads in one call, 20 at most, each with its own `alias` and arguments, answered in order under `runs`. Never beside an `alias` of the call\'s own |\n\nA query that states its own `limit` lists at most that many rows: `truncated` is `true` where more match, and `total` is\nthe rows the filtered query matches without it. A `count`, `count_by`, `count_where` and an `aggregate` are over every row\nthe query matches, never over the rows its `limit` lists.\n\nThe rows of one call, across its reads, total at most 262,144 bytes: a read past that is refused, naming\n`fields` and `limit` as what narrows it. The names `filters`, `fields`, `sort`, `count_by` and `aggregate`\ntake are the ones on the query\'s `returns` line.\n\nA list\'s params are how a person narrows that register: `search`, the row\'s id on an app that works inside\none row (`scope`), and a param for each filter the register states that one value or a range narrows. A\nfilter with no param \u2014 on a looked-up link or member, on a number read in each row\'s own unit or currency,\non a date holding a span, or on a List of several tables (`sources`) \u2014 is narrowed by `filters`, where a\nnumber condition names the unit its value is in as `unit_option`, an option of the figure\'s select by label\nor key. Each tab of a register is a query of its own, taking the list\'s params and the period its rows are\nread over; a tab\'s totals take the folder\'s id too, in an app that works inside one row.\n\n## Exporting a file\n\n```\nrun_app_query {"app_id":"app_\u2026","export":{"key":"by_carrier","per":"\u2026","tab":"in_yard","status":["\u2026"]}}\n```\n\n`export` makes the file the register\'s Export button makes, from what the caller reads, and answers it under `files` as a workspace\nfile like any other a tool makes: `file_id`, `url`, `filename`, `mime_type`. `key` is the\nkey of an Export of a List in `get_app`\'s tree, at the root or below a row\'s page; it is sent without `alias` or any other argument of a\nread. An option is named by its name or its id, as a read\'s filters name it; a member by its id or its name, for a member\nof the app\'s organization; a row, by its id. The other keys\nnarrow the file as the register\'s own controls do, each absent one leaving the register\'s opening view:\n\n| Key | Takes |\n|---|---|\n| `per` | The option, row id or member id the report is made for \u2014 required by an Export that states `per`, refused by one that does not; a member, here and in a member chip, is an id or a name, found as a filter on a member column finds one |\n| `tab`, `period`, `window` | A Tab\'s key (the first when absent); `{ "from", "to" }` days `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` on a date-and-time field) the tabs read over; a calendar\'s or board\'s days |\n| `status` | Options of the register\'s status that are kept |\n| `filters` | `{ "<field>": <value> }` by the field\'s alias, a value `null` clearing the register\'s opening chip; a value is one of the shapes below |\n| `search`, `overdue`, `waiting` | Words searched, one line each of a pasted list; `true`: only the rows past a deadline; `true`: only the rows waiting on the caller |\n| `sort`, `group`, `folder` | `{ "field", "dir" }`; a field alias; a folder id |\n| `row` | The id of the row whose rows a List below a row\'s page exports: required there and refused on a root View, and the reader must be able to open that row |\n\n| A `filters` value | For a field that is |\n|---|---|\n| `{ "kind": "ids", "ids": [...], "unset"?: true }` | a select (options) or a link to rows (row ids); `unset` also keeps rows holding none |\n| `{ "kind": "members", "mine": false, "ids": [...], "unset"?: true }` | a member; `mine` is the caller |\n| `{ "kind": "dates", "from": "yyyy-MM-dd" \\| null, "to": \u2026 \\| null, "unset"?: true }` | a date; `null` leaves an end open; `unset` also keeps rows holding none |\n| `{ "kind": "yes_no", "value": true }` | a yes/no |\n| `{ "kind": "number", "min": 1 \\| null, "max": \u2026 \\| null, "unit"?: "\u2026" }` | a number; `unit` the option of a unit or currency field |\n| `{ "kind": "bands", "bands": [{ "min", "max" }] }` | a number the register cuts into tiers |\n\nA key the register lacks, a tab it does not hold or a value its field cannot take is refused, naming it.\n\n## Calling a workflow\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"},"dry_run":true}\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"}}\n```\n\n| Argument | Does |\n|---|---|\n| `inputs` | The workflow\'s declared inputs. An update takes the record and only the fields that change |\n| `dry_run` | `true`: the run is made and taken back, so nothing is kept, and the answer is what the run would return, with the calls it would make \u2014 or `status: "not_previewed"` where the workflow cannot be dry-run (`agent_surface/a-dry-run`) |\n| `as_member` | For an organization owner: the run is a dry run, judged as that member would press it \u2014 their stage owners, row rules and app access \u2014 and writes nothing. Anyone else is refused; a record tool takes it the same way, and so do `query_records` and `run_app_query`, which answer what that member would read, and `screenshot_app`, which draws the app as that member sees it |\n| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not dry-run ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run\'s answer at that path. A run states its own `dry_run`, or takes the call\'s. Dry runs one after another share their rows, taken back together, so a run reads what the one before it made; a run reads a dry run\'s answer only from a run dry-run in that stretch |\n\n```\nrun_app_workflow {"app_id":"app_\u2026","runs":[\n {"alias":"create_order","inputs":{"customer":"rec_\u2026","item":"rec_\u2026","due_on":"2031-03-14"}},\n {"alias":"act_hand_over","inputs":{"record_id":{"from_run":0,"path":"data.record_id"}}}\n]}\n```\n\nAn act that reads papers (`intake`) is read by the caller: no platform agent reads for it. Its save `act_<alias>` takes `fields` (what the papers state), `rows` (the child rows listed) and `papers` (`[{"file":"fil_\u2026","kind":"<option>"}]`), and `dry_run` shows the record and rows it would make.\n\n## A dry run\n\nA dry run is the run itself on the real inputs, taken back: it is made in a transaction that is rolled back, so a read after a write reads that write, a branch or a loop walks the values the run would hold, and a call fed by an earlier call\'s answer gets it. No row, number, event, audit entry or table workflow outlives it. A write of the workspace\'s rows is made by its table \u2014 checks, write rules, stage owners \u2014 and the first refusal is the dry run\'s answer. A connected service\'s read-only call is made; a service write, a send, a notification or a button that runs another workflow is not, and is answered as a "would" with its payload. A guard (`when`, `requires`, a check, a lock) refuses it with the press\'s own sentence. A paper it makes is rendered for the answer and its file is removed with the dry run; an act that makes a paper is dry-run like any other, never refused for it. A body that sets the record\'s status also answers `moves`. Its answer carries `status`,\n`message`, `field_errors` and `data` as the run would return them, and under `dry_run`:\n\n| Key | Holds |\n|---|---|\n| `available` | `true` |\n| `writes` | The calls the run would make that are not reads, in order. The app\'s owner and an admin, who may read the workflow\'s body, read each call\'s `step_id`, `tool_name` and `input`. Another member reads each step that would write once: its `step_id` and `tool_name`, and where the step states them outright, the `table_id` it names and how many `records` it lists |\n| `reads` | The reads made for real, in order, each with its `input` and what it `returned` (cut at 2,000 characters, `truncated`), for the app\'s owner and an admin |\n| `papers` | Each paper rendered: its `step_id` and `filename`. The file is not kept |\n| `unpredicted` | The parts of the answer left out \u2014 `message`, `field_errors`, `data` \u2014 because each reads what a call the dry run did not make would answer |\n\nWhat a write sets off once it commits \u2014 a table\'s own workflows, its events \u2014 does not happen in a dry run.\n\nA workflow is not dry-run where its body reads the answer of a call that leaves the workspace, to branch,\nloop, check or feed another call, where it reads or writes rows after such a call (the run would find them as\nthat call left them), where it runs an agent, where it waits, where a step cannot be evaluated, fails\nfor a reason that is no table\'s refusal, or sends its call an input the call refuses, and where the run is past\nwhat one dry run walks \u2014 its steps, the passes of a loop, 50 reads, 50 writes or 20 seconds, which the runs of\none call share and the database holds it to: a lock wait that outlasts them ends the dry run. The\nanswer is then `status: "not_previewed"` with\n`dry_run: { "available": false, "reason" }`, and nothing ran \u2014 within `runs`, it ends the call. The same\nanswers a caller outside the app\'s organization.\n\n## A reviewed act\n\nAn act that states `review` runs a workflow that only proposes: call it with the inputs the act asks and it answers,\nwriting nothing, the changeset its body proposes in `data.review` \u2014 `table_id`, `creates` (each with its `key`) and\n`updates` (each with its `record_id`), each row\'s `data` holding only the fields that change, by field alias, with an\noptional `note` and `ticked` (`false` where the body leaves it for a person to choose), and `unplaced`, what was read\nand matched nothing; the platform adds a `sha` to every row. Call it again with the same inputs and `approved`,\n`{ "updates": [{ "record_id", "sha" }], "creates": [{ "key", "sha" }] }`, listing the rows to write with the `sha` each\ncarries in the proposal, copied as it came \u2014 never computed \u2014 and the platform writes those rows as that second call\nproposes them, each only where it proposes the values read:\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026"}}\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026","approved":{"updates":[{"record_id":"rec_\u2026","sha":"9f2c\u2026"}],"creates":[{"key":"line-4","sha":"41d0\u2026"}]}}}\n```\n\nThe answer\'s `data.applied` names the run (`execution_id`), the records `updated`, what each held before (`previous`), each `created` record by its key,\nand each approved row `left` with its `reason`: `not_proposed` (the second call no longer proposes it), `not_acted`\n(an update of a record the act was not run on), `changed` (the second call proposes other values than were read \u2014 read\nthe proposal again), `empty` (an update changing no field), `missing`, `locked` or `conflict`. Every approved row is\nchecked before any is written, and all are written in one transaction or none; the status history of each row written\nthat moved is recorded by the same run. `applied.previous` holds, for each record in `updated`, what the fields the call wrote held before (null for an empty one): `update_records` with it as `set` puts them back, and `delete_records` of a `created` record takes that row away. An act over every\nrow in view takes no `record_ids`. A `file` input takes the id of a file uploaded to the workspace.\n\nAn Act that `makes` a cadence\'s rows proposes the same way with no body: `creates` are the child rows still owed, each\n`key` `<parent id>|<day>`, a row its write would refuse unticked with the refusal as its `note`, and `unplaced` says what\nstays off the pattern and how many closed days were skipped.\n\n## A refusal\n\nA workflow re-checks on the server what the screen shows of its own act or save: what an act requires, a\nduplicate, whose step it is, a row the caller may not see. Each write it makes also meets the table\'s own\nrules (a bound, a span, a stage\'s owner, its lock), which hold on every path a record is written by. A row its table\nlocked is refused in every app\'s act and save, naming who can change it; an app\'s own Check only makes a row read-only\nin that app. An unlock in an app\'s run is judged as the member it runs for, never the app\'s owner. A run refused\nbefore it writes writes nothing; one whose later write a table\'s rule refuses keeps the writes before it.\nEither answers `status: "error"` with the sentence a person would read as `message`, and under `field_errors`\nthe sentence for each input it was refused over. A value of the wrong type, a missing required input and an unknown\nalias are refused before the body runs: the call itself fails with the sentence, and `field_errors` where\nan input is at fault \u2014 within `runs`, a run refused for its inputs answers `status: "error"` in its place,\nand the runs before it stand. A refused read fails the same way, naming the param or the column; within\n`runs`, it answers its `error` and the other reads are still answered.\n\n## Declaring more\n\nWhat the business asks an agent in the app again and again, and no screen draws, is stated in the app\'s tree as Query and Workflow nodes, beside its\nActs: every figure or list whose definition is the business\'s own (open orders, what a customer owes, low stock) and every recurring operation (close the month, send to the accounting service, chase overdue invoices), each with a `description` written for an agent. A question asked once stays on `query_records` with `aggregate`. A Workflow gets an Act only where a person presses it; work only an agent does has no button. Both are checked and compiled when the tree is written (`set_app`; `reference/query-node`, `reference/workflow-node`).\n\n**What the data decides, the system decides.** Whatever follows from the rows and the rules is stated where it holds for every writer, never left to a caller: a fact of one row in its table (`required`, `unique`, `min` and `max`, `options_where`, a check); a value that follows from others as a formula, a lookup or `default_from`; a step of the work in the status\'s `stages` and its Acts (`when`, `requires`); who reads which rows in the table\'s `read_scope` and the app\'s `rows`; what a write sets off in a table\'s workflow; and a decision over many rows or papers (which papers a household\'s facts call for) in a Workflow that computes it and refuses what breaks it, every call the same. A caller\'s inputs are what only it knows: the facts it read, a judgement it made. An override of what the system computes is an optional input, never the way the work is done. A Workflow refuses only what would leave a row invalid or put a false statement on a paper, naming the fact that fixes it; what leaves room for error but is not wrong (a blank printed for handwriting, an unusual choice) it does and reports as a warning in what it returns.\n\n**A query** \u2014 the rows of one table, or one figure of them, in the app\'s own aliases:\n\n```jsonc\n{\n "type": "Query",\n "key": "orders_overdue",\n "description": "A customer\'s orders still open past the day they were due, longest overdue first.",\n "params": {\n "customer": { "type": "record_link", "entity": "customer", "required": false, "description": "Only this customer\'s orders." },\n "as_of": { "type": "date", "description": "The day an order is overdue on: due before it." }\n },\n "rows": "order",\n "fields": ["customer", "item", "due_on", "price"],\n "where": { "status": ["baking"], "customer": { "param": "customer" }, "due_on": { "to": { "param": "as_of" } } },\n "sort": { "field": "due_on" }\n}\n```\n\nIt 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 \u2014\nso never the table of an app whose List reads `sources`, several tables. A condition reading an\noptional param narrows nothing when the call leaves it out; no param compares a number read in each row\'s\nown unit or currency, or a date holding a span. A Query returns its `fields`; a caller counts, sums or\naverages them with `run_app_query`\'s `aggregate`. A Query, a Workflow and\na Reading\'s `key` take no name the app generates (`reference/app.generated-name`).\n\n**A workflow** \u2014 a write no Act of the record makes, typed in the app\'s tree and its code set on the app:\n\n```jsonc\n{\n "type": "Workflow",\n "key": "import_bookings",\n "description": "Books every order a sheet lists, reusing an order the sheet already booked.",\n "inputs": {\n "sheet": { "type": "file", "description": "The order sheet, one order per row." },\n "booked_by": { "type": "member", "required": false, "description": "Who the orders are taken by; absent, the caller." }\n },\n "outputs": { "added": { "type": "number" }, "reused": { "type": "number" } }\n}\n```\n\n`set_workflow` sets its code (`workflows`). A query the app holds that\nthe tree does not declare is listed by `get_app` as `unstated_queries` and removed by the next write,\nwhose answer notes it; declared as a Query node, it is the tree\'s. A caller sees the description and\neach input\'s `description` and nothing else, so each says what the value is and what leaving it out means;\nthe check notes one that says nothing.\n\n**Shape each for a caller that is not looking at a screen.** One job a person hands an agent \u2014 a paper read,\na message answered, a sheet brought in \u2014 is one declared workflow named for the job, never a chain of the\ngenerated per-row workflows. Take a list where the job covers many rows, a record\'s lines among them. A workflow\'s code\nthat writes more than one row makes them in one `save_record` workflow step, all or nothing, and recognises\nwhat exists by the identity the input itself carries, declared unique on its table, so the same input sent\ntwice updates instead of adding. Return the ids under `outputs`, so the next run can read them. Gate what\ncannot be undone behind an approval step.\n\n## Prove an app as an agent\n\nRun on one of the owner\'s own rows, moved only as far as its stage; a record made for the run takes a number and a stage move nobody asked for.\n\n1. `get_app` \u2014 every job the app\'s `description` names has an alias that does it or reads it.\n2. `run_app_query` the list with no param, then with each param a person would narrow by; `count: true`\n answers how many without the rows.\n3. `run_app_query` `<entity>_record` with one row\'s id, and each `<child>_by_<link>` under it.\n4. `run_app_workflow` an act with `dry_run: true`, then without.\n5. `run_app_workflow` an act its record is not ready for: the answer is `status: "error"` with the sentence\n the screen would show.\n6. `run_app_workflow` the app\'s job workflow with the input a person would hand it \u2014 the paper read, the row:\n it completes in one call. Call it again with the same input: nothing is added.\n';
1892
+ var agent_surface_default = '# An app\'s agent surface\n\nEverything a person reads or does in an app, an agent reads or does through that app\'s **queries** and\n**workflows** \u2014 the same ones its screen runs, under the same permissions and the same rules. Three tools\nreach them, over MCP and as `lotics run <tool>`:\n\n| Tool | Answers |\n|---|---|\n| `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`) \u2014 beside what each table they name holds, in its owner\'s words \u2014 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) |\n| `run_app_query` | The rows, a count or the groups of one query \u2014 or of several in one call |\n| `run_app_workflow` | One write \u2014 or several in order \u2014 or a dry run of it that writes nothing |\n\nAn app generates this surface from its tree; Query and Workflow nodes declare what the screen never\nasks (`agent_surface/declaring-more`). Every root List of an app (a change may add one at any time) is part of it: each List\'s list, its rows by id, its page\'s\nLists and its Acts are queries and workflows of the same app, named by that List\'s table \u2014 `get_app` lists them in the\none roster, and nothing of a root List is another app\'s. Every caller the app is shared with is answered them, its rows narrowed by the app\'s row rules. A custom-code app\'s surface is the queries and workflows bound on it\n(`app_bindings`).\n\n## Finding what an app offers\n\n`get_workspace` maps the workspace. Its `search` matches the keys and descriptions of the Query and Workflow nodes an app declares, and the app\'s line names the matching keys; it never matches the generated `act_`, `create_` or `update_` aliases. `get_app` then gives the contracts. An agent runs a declared node before it falls back to `query_records`.\n\n## What every app generates\n\nA name in angle brackets is the app\'s alias for that thing; an `<entity>` is the alias of a table the app reads. `get_app` lists the ones a given\napp has.\n\n### Queries\n\n<!-- generated:start queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per List `filters` field holding one value \u2014 a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter \u2014 none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter \u2014 none over sources, none for a looked-up link or member, none for a number read in each row\'s own unit or currency | every entity the app draws; the filter params on the app\'s own entity alone; a root List after the first over an entity, whose chips differ from the first\'s, adds one of its own, called by its key |\n| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list\'s; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each Tab of the register, and of each later root List over an entity, called by its key; none over sources, none for a Tab whose period reads a date holding a span |\n| `<entity>_totals_<tab>` | The <child> rows added per <entity> row, by "<link>", over the period from `from` to `to`, dated by "<date>": . | `from`; `to` | each Tab of the register stating `totals`, and of each later root List over an entity, called by its key |\n| `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |\n| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each List of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |\n| `outside_<key>_one` | One row of <entity> by its id. | `record` | each Outside: the record a link opens, projected to the fields the Outside states |\n| `outside_<key>_<child>` | The <child> rows under one <entity>, through "<link>". | `record` | each List of an Outside: the rows under the record a link opens, projected to the List\'s columns |\n| `<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 |\n| `<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`) |\n| `<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 |\n| `<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 a List\'s band, called by its `key` \u2014 but the work against its plan (a Reading stating `planned` and `done`), which reads the List\'s own rows; none over sources |\n| `<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each Reading and List of a Sheet, called by its `key` |\n| `<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a List stating `same`; `record_<field>` per `where` bound to a field of the record | each Reading of a Record page, each List that only reads on it (its `key`, else its entity\'s alias) and each funnel, called by its `key` |\n| `<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 |\n| `<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 |\n| `<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 |\n| `<entity>_export_rows_of_<source>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | an Export over some of a List\'s sources: their rows alone, each source named in turn |\n| `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |\n| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads \u2014 the rows with no <place> counted apart. | | a register laid out as a `plan`: its places\' counts of present rows |\n\n<!-- generated:end queries -->\n\nA reading\'s query returns groups, never the rows it read: one row for all of them, or one per value it\nsplits by, or per day. Each row carries the alias of each field it splits by, `__day` where it splits by\nday, `__count`, and `__sum` where it sums a number; its description states which. An average is `__sum`\nover `__count`, both over the rows holding a value.\n\nA Reading is called by its `key` (`reference/reading-node`), and a List that only reads by its `key`, else its entity\'s alias \u2014 wherever its List stands in the app, so a move in the tree changes no name. Each is its own among the app\'s Readings, Lists that only read and Queries.\n\nA register reading\'s query reads the rows it names, whatever a screen has open: the rows of its `tab` where\nit states one, every tab\'s where it states none \u2014 its description says which. One placed in time (`over`)\nreads every day unless the call states `from` or `to`.\n\n### Queries the screen runs for itself\n\nThey run like any other, and `get_app` leaves them out: each feeds one control, and takes ids\nthe screen already holds.\n\n<!-- generated:start screen-queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<child>_<link>_target` | One <entity> row by its id, where a <child> row\'s "<link>" may point at it. | `<entity>_id` | a List with `pick` whose link a write rule narrows |\n| `<entity>_<field>_values` | Each "<field>" the <entity> rows hold, once, most held first, narrowed by what the reader typed. | `search`? | a text field a write rule offers values to (`suggest`) |\n| `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |\n| `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. | | an app stating `scope` |\n| `<task>_progress_by_<link>` | How many <task> rows each <entity> row handed in holds, at each status. | `<entity>_ids` | rows whose task rows are counted done |\n| `<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 |\n| `<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 |\n| `<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` |\n| `<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`) |\n\n<!-- generated:end screen-queries -->\n\n### Workflows\n\n<!-- generated:start workflows -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `create_<entity>` | Opens one row of <entity>. | every field the add asks, and the link it files the row under; a field the Lists adding the entity hold may be left out | an entity the app adds rows of |\n| `update_<entity>` | Changes one row of <entity>; every input but the row is optional, and one left out is left as it is. | `record_id`, and each field a person edits \u2014 a files field or a link to several rows as `<field>_added` / `<field>_removed` | an entity the app edits |\n| `move_<list>` | Gives rows of <entity> to a <lane> together: every row is judged before any is written, so a refusal leaves them all as they were. `lane` left out leaves the <lane> as it is, `lane` empty clears it; `day` dates only the rows holding none; `order` places each by its number. | `record_ids`, `lane` (left out, the lane stays; empty, none), `day` for the rows holding none, and `order`: each row\'s id and number | a lanes board of days with no hour whose app writes its lane |\n| `remove_<entity>` | Removes one row of <entity>. | `record_id` | an entity the app removes rows of |\n| `restore_<entity>` | Brings back one deleted row of <entity>. | `record_id` | an entity the app removes rows of |\n| `act_<act>` | <label> \u2014 on one row of <entity>, refused where its conditions do not hold. | `record_id` \u2014 `record_ids` on an act over several rows \u2014 and what the act asks | each Act that names no workflow of its own |\n| `archive_<act>` | Hands back every file of <label> on one row of <entity> as one archive. | `record_id` | an Act making a set of papers (`templates`) |\n\n<!-- generated:end workflows -->\n\nA Workflow node is called by its `key`, and every Act by `act_<key>`; an Act that names its own `workflow` is also called by that workflow\'s alias.\n\n## Calling a query\n\n```\nget_app {"app_id":"app_\u2026"}\nrun_app_query {"app_id":"app_\u2026","alias":"order_list","params":{"status_is":"open","due_on_to":"2031-03-14"}}\n```\n\n| Argument | Does |\n|---|---|\n| `params` | The query\'s declared params. A required one is always sent; an optional one left out narrows nothing. A select takes the option\'s alias as `get_app` lists it in `select(label=alias|\u2026)` \u2014 a link a record id, a member a member id, a date `yyyy-mm-dd` |\n| `filters` | Narrows the result further, by the query\'s output columns (`filters`) |\n| `fields` | The output columns to return, in place of all of them; each row then holds them and the id of the record it is |\n| `sort` | An order in place of the query\'s own: `[{ "field_key": "<column>", "order": "asc" }]`, `asc` or `desc`, each `field_key` an output column\'s name |\n| `count` | `true`: `total`, the number of rows, in place of the rows; with `count_by`, `counts` per value of one column, keyed by an option\'s label, a member\'s name or a linked row\'s display; with `count_where` \u2014 a map of name \u2192 filter, never beside `count_by` \u2014 `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |\n| `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), `bands` (a number column of `by` grouped by its breakpoints), or `day` (a date column, answered as `__day`), `sum` (a number column, answered as `__sum`) and `avg` (a number column averaged over the group\'s rows that hold one, answered as `__avg`), each group with its `__count`. Sent with `params` and `filters` alone. Buckets are by day only: a period\'s total is one call per period, with `from` and `to` or a date filter |\n| `limit`, `cursor` | A page \u2014 200 rows at most, 50 where no `limit` is stated \u2014 and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |\n| `runs` | Several reads in one call, 20 at most, each with its own `alias` and arguments, answered in order under `runs`. Never beside an `alias` of the call\'s own |\n\nA query that states its own `limit` lists at most that many rows: `truncated` is `true` where more match, and `total` is\nthe rows the filtered query matches without it. A `count`, `count_by`, `count_where` and an `aggregate` are over every row\nthe query matches, never over the rows its `limit` lists.\n\nThe rows of one call, across its reads, total at most 262,144 bytes: a read past that is refused, naming\n`fields` and `limit` as what narrows it. The names `filters`, `fields`, `sort`, `count_by` and `aggregate`\ntake are the ones on the query\'s `returns` line.\n\nA list\'s params are how a person narrows that register: `search`, the row\'s id on an app that works inside\none row (`scope`), and a param for each filter the register states that one value or a range narrows. A\nfilter with no param \u2014 on a looked-up link or member, on a number read in each row\'s own unit or currency,\non a date holding a span, or on a List of several tables (`sources`) \u2014 is narrowed by `filters`, where a\nnumber condition names the unit its value is in as `unit_option`, an option of the figure\'s select by label\nor key. Each tab of a register is a query of its own, taking the list\'s params and the period its rows are\nread over; a tab\'s totals take the folder\'s id too, in an app that works inside one row.\n\n## Exporting a file\n\n```\nrun_app_query {"app_id":"app_\u2026","export":{"key":"by_carrier","per":"\u2026","tab":"in_yard","status":["\u2026"]}}\n```\n\n`export` makes the file the register\'s Export button makes, from what the caller reads, and answers it under `files` as a workspace\nfile like any other a tool makes: `file_id`, `url`, `filename`, `mime_type`. `key` is the\nkey of an Export of a List in `get_app`\'s tree, at the root or below a row\'s page; it is sent without `alias` or any other argument of a\nread. An option is named by its name or its id, as a read\'s filters name it; a member by its id or its name, for a member\nof the app\'s organization; a row, by its id. The other keys\nnarrow the file as the register\'s own controls do, each absent one leaving the register\'s opening view:\n\n| Key | Takes |\n|---|---|\n| `per` | The option, row id or member id the report is made for \u2014 required by an Export that states `per`, refused by one that does not; a member, here and in a member chip, is an id or a name, found as a filter on a member column finds one |\n| `tab`, `period`, `window` | A Tab\'s key (the first when absent); `{ "from", "to" }` days `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` on a date-and-time field) the tabs read over; a calendar\'s or board\'s days |\n| `status` | Options of the register\'s status that are kept |\n| `filters` | `{ "<field>": <value> }` by the field\'s alias, a value `null` clearing the register\'s opening chip; a value is one of the shapes below |\n| `search`, `overdue`, `waiting` | Words searched, one line each of a pasted list; `true`: only the rows past a deadline; `true`: only the rows waiting on the caller |\n| `sort`, `group`, `folder` | `{ "field", "dir" }`; a field alias; a folder id |\n| `row` | The id of the row whose rows a List below a row\'s page exports: required there and refused on a root View, and the reader must be able to open that row |\n\n| A `filters` value | For a field that is |\n|---|---|\n| `{ "kind": "ids", "ids": [...], "unset"?: true }` | a select (options) or a link to rows (row ids); `unset` also keeps rows holding none |\n| `{ "kind": "members", "mine": false, "ids": [...], "unset"?: true }` | a member; `mine` is the caller |\n| `{ "kind": "dates", "from": "yyyy-MM-dd" \\| null, "to": \u2026 \\| null, "unset"?: true }` | a date; `null` leaves an end open; `unset` also keeps rows holding none |\n| `{ "kind": "yes_no", "value": true }` | a yes/no |\n| `{ "kind": "number", "min": 1 \\| null, "max": \u2026 \\| null, "unit"?: "\u2026" }` | a number; `unit` the option of a unit or currency field |\n| `{ "kind": "bands", "bands": [{ "min", "max" }] }` | a number the register cuts into tiers |\n\nA key the register lacks, a tab it does not hold or a value its field cannot take is refused, naming it.\n\n## Calling a workflow\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"},"dry_run":true}\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"}}\n```\n\n| Argument | Does |\n|---|---|\n| `inputs` | The workflow\'s declared inputs. An update takes the record and only the fields that change |\n| `dry_run` | `true`: the run is made and taken back, so nothing is kept, and the answer is what the run would return, with the calls it would make \u2014 or `status: "not_previewed"` where the workflow cannot be dry-run (`agent_surface/a-dry-run`) |\n| `as_member` | For an organization owner: the run is a dry run, judged as that member would press it \u2014 their stage owners, row rules and app access \u2014 and writes nothing. Anyone else is refused; a record tool takes it the same way, and so do `query_records` and `run_app_query`, which answer what that member would read, and `screenshot_app`, which draws the app as that member sees it |\n| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not dry-run ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run\'s answer at that path. A run states its own `dry_run`, or takes the call\'s. Dry runs one after another share their rows, taken back together, so a run reads what the one before it made; a run reads a dry run\'s answer only from a run dry-run in that stretch |\n\n```\nrun_app_workflow {"app_id":"app_\u2026","runs":[\n {"alias":"create_order","inputs":{"customer":"rec_\u2026","item":"rec_\u2026","due_on":"2031-03-14"}},\n {"alias":"act_hand_over","inputs":{"record_id":{"from_run":0,"path":"data.record_id"}}}\n]}\n```\n\nA run that makes a paper answers it under `files`, as an export does: `file_id`, `url`, `filename`, `mime_type`; a dry run keeps none.\n\nAn act that reads papers (`intake`) is read by the caller: no platform agent reads for it. Its save `act_<alias>` takes `fields` (what the papers state), `rows` (the child rows listed) and `papers` (`[{"file":"fil_\u2026","kind":"<option>"}]`), and `dry_run` shows the record and rows it would make.\n\n## A dry run\n\nA dry run is the run itself on the real inputs, taken back: it is made in a transaction that is rolled back, so a read after a write reads that write, a branch or a loop walks the values the run would hold, and a call fed by an earlier call\'s answer gets it. No row, number, event, audit entry or table workflow outlives it. A write of the workspace\'s rows is made by its table \u2014 checks, write rules, stage owners \u2014 and the first refusal is the dry run\'s answer. A connected service\'s read-only call is made; a service write, a send, a notification or a button that runs another workflow is not, and is answered as a "would" with its payload. A guard (`when`, `requires`, a check, a lock) refuses it with the press\'s own sentence. A paper it makes is rendered for the answer and its file is removed with the dry run; an act that makes a paper is dry-run like any other, never refused for it. A body that sets the record\'s status also answers `moves`. Its answer carries `status`,\n`message`, `field_errors` and `data` as the run would return them, and under `dry_run`:\n\n| Key | Holds |\n|---|---|\n| `available` | `true` |\n| `writes` | The calls the run would make that are not reads, in order. The app\'s owner and an admin, who may read the workflow\'s body, read each call\'s `step_id`, `tool_name` and `input`. Another member reads each step that would write once: its `step_id` and `tool_name`, and where the step states them outright, the `table_id` it names and how many `records` it lists |\n| `reads` | The reads made for real, in order, each with its `input` and what it `returned` (cut at 2,000 characters, `truncated`), for the app\'s owner and an admin |\n| `papers` | Each paper rendered: its `step_id` and `filename`. The file is not kept |\n| `unpredicted` | The parts of the answer left out \u2014 `message`, `field_errors`, `data` \u2014 because each reads what a call the dry run did not make would answer |\n\nWhat a write sets off once it commits \u2014 a table\'s own workflows, its events \u2014 does not happen in a dry run.\n\nA workflow is not dry-run where its body reads the answer of a call that leaves the workspace, to branch,\nloop, check or feed another call, where it reads or writes rows after such a call (the run would find them as\nthat call left them), where it runs an agent, where it waits, where a step cannot be evaluated, fails\nfor a reason that is no table\'s refusal, or sends its call an input the call refuses, and where the run is past\nwhat one dry run walks \u2014 its steps, the passes of a loop, 50 reads, 50 writes or 20 seconds, which the runs of\none call share and the database holds it to: a lock wait that outlasts them ends the dry run. The\nanswer is then `status: "not_previewed"` with\n`dry_run: { "available": false, "reason" }`, and nothing ran \u2014 within `runs`, it ends the call. The same\nanswers a caller outside the app\'s organization.\n\n## A reviewed act\n\nAn act that states `review` runs a workflow that only proposes: call it with the inputs the act asks and it answers,\nwriting nothing, the changeset its body proposes in `data.review` \u2014 `table_id`, `creates` (each with its `key`) and\n`updates` (each with its `record_id`), each row\'s `data` holding only the fields that change, by field alias, with an\noptional `note` and `ticked` (`false` where the body leaves it for a person to choose), and `unplaced`, what was read\nand matched nothing; the platform adds a `sha` to every row. Call it again with the same inputs and `approved`,\n`{ "updates": [{ "record_id", "sha" }], "creates": [{ "key", "sha" }] }`, listing the rows to write with the `sha` each\ncarries in the proposal, copied as it came \u2014 never computed \u2014 and the platform writes those rows as that second call\nproposes them, each only where it proposes the values read:\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026"}}\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026","approved":{"updates":[{"record_id":"rec_\u2026","sha":"9f2c\u2026"}],"creates":[{"key":"line-4","sha":"41d0\u2026"}]}}}\n```\n\nThe answer\'s `data.applied` names the run (`execution_id`), the records `updated`, what each held before (`previous`), each `created` record by its key,\nand each approved row `left` with its `reason`: `not_proposed` (the second call no longer proposes it), `not_acted`\n(an update of a record the act was not run on), `changed` (the second call proposes other values than were read \u2014 read\nthe proposal again), `empty` (an update changing no field), `missing`, `locked` or `conflict`. Every approved row is\nchecked before any is written, and all are written in one transaction or none; the status history of each row written\nthat moved is recorded by the same run. `applied.previous` holds, for each record in `updated`, what the fields the call wrote held before (null for an empty one): `update_records` with it as `set` puts them back, and `delete_records` of a `created` record takes that row away. An act over every\nrow in view takes no `record_ids`. A `file` input takes the id of a file uploaded to the workspace.\n\nAn Act that `makes` a cadence\'s rows proposes the same way with no body: `creates` are the child rows still owed, each\n`key` `<parent id>|<day>`, a row its write would refuse unticked with the refusal as its `note`, and `unplaced` says what\nstays off the pattern and how many closed days were skipped.\n\n## A refusal\n\nA workflow re-checks on the server what the screen shows of its own act or save: what an act requires, a\nduplicate, whose step it is, a row the caller may not see. Each write it makes also meets the table\'s own\nrules (a bound, a span, a stage\'s owner, its lock), which hold on every path a record is written by. A row its table\nlocked is refused in every app\'s act and save, naming who can change it; an app\'s own Check only makes a row read-only\nin that app. An unlock in an app\'s run is judged as the member it runs for, never the app\'s owner. A run refused\nbefore it writes writes nothing; one whose later write a table\'s rule refuses keeps the writes before it.\nEither answers `status: "error"` with the sentence a person would read as `message`, and under `field_errors`\nthe sentence for each input it was refused over. A value of the wrong type, a missing required input and an unknown\nalias are refused before the body runs: the call itself fails with the sentence, and `field_errors` where\nan input is at fault \u2014 within `runs`, a run refused for its inputs answers `status: "error"` in its place,\nand the runs before it stand. A refused read fails the same way, naming the param or the column; within\n`runs`, it answers its `error` and the other reads are still answered.\n\n## Declaring more\n\nWhat the business asks an agent in the app again and again, and no screen draws, is stated in the app\'s tree as Query and Workflow nodes, beside its\nActs: every figure or list whose definition is the business\'s own (open orders, what a customer owes, low stock) and every recurring operation (close the month, send to the accounting service, chase overdue invoices), each with a `description` written for an agent. A question asked once stays on `query_records` with `aggregate`. A Workflow gets an Act only where a person presses it; work only an agent does has no button. Both are checked and compiled when the tree is written (`set_app`; `reference/query-node`, `reference/workflow-node`).\n\n**What the data decides, the system decides.** Whatever follows from the rows and the rules is stated where it holds for every writer, never left to a caller: a fact of one row in its table (`required`, `unique`, `min` and `max`, `options_where`, a check); a value that follows from others as a formula, a lookup or `default_from`; a step of the work in the status\'s `stages` and its Acts (`when`, `requires`); who reads which rows in the table\'s `read_scope` and the app\'s `rows`; what a write sets off in a table\'s workflow; and a decision over many rows or papers (which papers a household\'s facts call for) in a Workflow that computes it and refuses what breaks it, every call the same. A caller\'s inputs are what only it knows: the facts it read, a judgement it made. An override of what the system computes is an optional input, never the way the work is done. A Workflow refuses only what would leave a row invalid or put a false statement on a paper, naming the fact that fixes it; what leaves room for error but is not wrong (a blank printed for handwriting, an unusual choice) it does and reports as a warning in what it returns.\n\n**A query** \u2014 the rows of one table, or one figure of them, in the app\'s own aliases:\n\n```jsonc\n{\n "type": "Query",\n "key": "orders_overdue",\n "description": "A customer\'s orders still open past the day they were due, longest overdue first.",\n "params": {\n "customer": { "type": "record_link", "entity": "customer", "required": false, "description": "Only this customer\'s orders." },\n "as_of": { "type": "date", "description": "The day an order is overdue on: due before it." }\n },\n "rows": "order",\n "fields": ["customer", "item", "due_on", "price"],\n "where": { "status": ["baking"], "customer": { "param": "customer" }, "due_on": { "to": { "param": "as_of" } } },\n "sort": { "field": "due_on" }\n}\n```\n\nIt 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 \u2014\nso never the table of an app whose List reads `sources`, several tables. A condition reading an\noptional param narrows nothing when the call leaves it out; no param compares a number read in each row\'s\nown unit or currency, or a date holding a span. A Query returns its `fields`; a caller counts, sums or\naverages them with `run_app_query`\'s `aggregate`. A Query, a Workflow and\na Reading\'s `key` take no name the app generates (`reference/app.generated-name`).\n\n**A workflow** \u2014 a write no Act of the record makes, typed in the app\'s tree and its code set on the app:\n\n```jsonc\n{\n "type": "Workflow",\n "key": "import_bookings",\n "description": "Books every order a sheet lists, reusing an order the sheet already booked.",\n "inputs": {\n "sheet": { "type": "file", "description": "The order sheet, one order per row." },\n "booked_by": { "type": "member", "required": false, "description": "Who the orders are taken by; absent, the caller." }\n },\n "outputs": { "added": { "type": "number" }, "reused": { "type": "number" } }\n}\n```\n\n`set_workflow` sets its code (`workflows`). A query the app holds that\nthe tree does not declare is listed by `get_app` as `unstated_queries` and removed by the next write,\nwhose answer notes it; declared as a Query node, it is the tree\'s. A caller sees the description and\neach input\'s `description` and nothing else, so each says what the value is and what leaving it out means;\nthe check notes one that says nothing.\n\n**Shape each for a caller that is not looking at a screen.** One job a person hands an agent \u2014 a paper read,\na message answered, a sheet brought in \u2014 is one declared workflow named for the job, never a chain of the\ngenerated per-row workflows. Take a list where the job covers many rows, a record\'s lines among them. A workflow\'s code\nthat writes more than one row makes them in one `save_record` workflow step, all or nothing, and recognises\nwhat exists by the identity the input itself carries, declared unique on its table, so the same input sent\ntwice updates instead of adding. Return the ids under `outputs`, so the next run can read them. Gate what\ncannot be undone behind an approval step.\n\n## Prove an app as an agent\n\nRun on one of the owner\'s own rows, moved only as far as its stage; a record made for the run takes a number and a stage move nobody asked for.\n\n1. `get_app` \u2014 every job the app\'s `description` names has an alias that does it or reads it.\n2. `run_app_query` the list with no param, then with each param a person would narrow by; `count: true`\n answers how many without the rows.\n3. `run_app_query` `<entity>_record` with one row\'s id, and each `<child>_by_<link>` under it.\n4. `run_app_workflow` an act with `dry_run: true`, then without.\n5. `run_app_workflow` an act its record is not ready for: the answer is `status: "error"` with the sentence\n the screen would show.\n6. `run_app_workflow` the app\'s job workflow with the input a person would hand it \u2014 the paper read, the row:\n it completes in one call. Call it again with the same input: nothing is added.\n';
1893
1893
 
1894
1894
  // AGENTS.md
1895
1895
  var AGENTS_default = "# @lotics/cli \u2014 agent index\n\nThe model an agent needs before driving this CLI: which surface answers which question, what the\nconventions are, and where the traps are.\n\n| Read | For |\n|---|---|\n| `lotics --help` | The verb inventory (\xA7 COMMANDS) and global flags. The verb LIST is generated and never stale; the prose beside each verb is hand-written, so where it disagrees with `docs/cli_reference.md`, the reference wins. |\n| `lotics tools` \xB7 `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |\n| `lotics docs` \xB7 `lotics docs <area>[/<section>]` \xB7 `lotics docs [<area>] --grep <text>` | This CLI's references, carried inside it so each describes the binary answering. Capped at a page: a doc that does not fit hands back its opening and the addresses into it, so the next call is smaller than the last. A page the copy lacks \u2014 one the server added since this binary was built, which a refusal can cite \u2014 is read from the server's `docs` tool with this machine's credential, and so is every `--grep`, over the references the server serves. A custom-code app's SDK reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the app. |\n| `lotics docs reference` \xB7 `lotics docs reference/<section>` | The keys of a table document and the components of an app tree: a table's fields keyed by alias, how a row of each table is recognised (`records`), and the apps stated over them. Every key, every field type with the config it needs, the rules, and a worked example. |\n| `lotics docs design` \xB7 `lotics docs design/<section>` | Designing an app \u2014 the treatment each kind of row takes with the `reference` page stating its keys, the visual bar, looking at what a write built, and the rubric a build answers. Opens on the visual bar; a finding names its section. |\n| `lotics docs examples` \xB7 `lotics docs examples/<treatment>` | Each treatment worked through in an app of a complete workspace: the job, the props to read, where it is the wrong one, and the excerpt. |\n| [docs/getting_started.md](./docs/getting_started.md) | What a workspace holds, and the one page to open for each job: building a workspace, changing an app, a rule on a table, a document, data and questions, a connected service, sharing. The first page an agent outside the product reads. |\n| [docs/build.md](./docs/build.md) | A workspace or an app built call by call \u2014 tables with a check, the paper, the app, what the owner will ask an agent, the owner's rows, pressing it \u2014 in one worked example, at any time: an app added or changed weeks later starts there too. |\n| [docs/app_architecture.md](./docs/app_architecture.md) | Which apps a business needs, one per main entity, with a worked split; who gets each, and which rows each person reads. |\n| [docs/working_in_a_workspace.md](./docs/working_in_a_workspace.md) | The right means for each job once the apps exist: an app's act for a business operation, a record write for data entry, a query for a figure the business defines, a count for the rest. |\n| [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas \u2014 the detail `--help` compresses. |\n| [docs/data_model.md](./docs/data_model.md) | Tables, their fields, and how they relate \u2014 one fact per column, one table per kind of thing and the NAME-OVERLAP probe that says when a split has broken, one vocabulary wherever values are copied, a copy boundary that accounts for every source field, provenance as a link, a declared natural key, history as rows, and why derived DEPTH costs more than row count; then the choices around a field's type, and how a field is changed (a list replaces whole, what refuses a deletion, what `force` consents to). Separate from build because every workspace starts with tables and many never get an app. |\n| [docs/filters.md](./docs/filters.md) | The one filter grammar every filter-taking tool, view and rollup reads \u2014 conditions, groups, and the operators per field type. |\n| [docs/field_values.md](./docs/field_values.md) | The value each field type takes in a write. |\n| [docs/workflows.md](./docs/workflows.md) | Writing a workflow body \u2014 triggers, steps, what an expression reads, the helpers, approvals and agent steps, and table checks. |\n| [docs/app_bindings.md](./docs/app_bindings.md) | The queries, workflows and agents an app binds \u2014 the query tree, typed inputs and outputs, and an agent's declaration. |\n| [docs/document_templates.md](./docs/document_templates.md) | Generating PDF/Excel/Word/email from reusable templates, and what a template an app's Act makes is handed. |\n| [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the procedures, policies and glossary an agent can't guess with `set_knowledge`; who can read a doc; searching and reading it line by line. |\n| [docs/migration.md](./docs/migration.md) | What to DO when something an earlier CLI wrote to disk no longer matches what it does \u2014 local app projects are gone, and each verb that read one has a replacement. |\n| [README.md](./README.md) | Install, auth, and worked examples. |\n\n## Two surfaces, and the trap between them\n\n**`lotics tools` is not the CLI's capability list.** There are two disjoint surfaces:\n\n- **Tools** (`lotics tools`, `lotics run <tool>`) \u2014 the *agent tool registry*: what an agent, workflow,\n or automation may call. Workspace data, templates, knowledge, admin.\n- **Commands** (`lotics --help` \xA7 COMMANDS) \u2014 the CLI's *own verbs*: auth and org/workspace scoping,\n file upload and download, and those that touch a local file for an app \u2014 `app apply`,\n `app create --custom`, `app pull` and `app deploy`.\n\nSeveral capabilities exist **only** as commands and appear nowhere in `lotics tools` \u2014 downloading a\nfile is the one most often mistaken for missing. Concluding \"the platform can't do X\" from the tool\nlist alone is a mistake; check both.\n\n**`lotics <verb> --help` prints that verb's entries from \xA7 COMMANDS** (`lotics app --help`,\n`lotics file download --help`); `lotics report --help` prints the report frame. To find out whether\nsomething exists, read `lotics --help` \xA7 COMMANDS \u2014 the whole section, not a narrow grep.\n\n## Conventions that hold across every command\n\n- **Scope is resolved per invocation.** `LOTICS_ORG` / `LOTICS_WORKSPACE` (or `LOTICS_API_KEY`) scope a\n single call without changing the active org or a directory pin \u2014 the safe way to touch one tenant\n from a shell serving many. Every command that resolves a workspace echoes its target to **stderr**\n (`lotics \u2192 <org> / <workspace>`); read it back before trusting a write. Resolution precedence is\n in README \xA7 Organizations.\n- **A machine with no key can still sign in, and the sign-in never blocks you.** `lotics auth\n login` takes no argument and sends no mail: it prints the page a person opens and the code that page must show,\n records the request, and EXITS. They press Confirm whenever they get to it; the next command that\n NEEDS a credential collects the key before doing its own work, so \"sign in\" costs you one command\n and then re-running what you wanted. Never wrap it in a timeout waiting for a human \u2014 `--wait`\n exists if you really want one blocking command, and killing that one is safe too (the request\n survives and the next command claims it). A command run before Confirm exits 1 naming the page and\n code again; once the 15 minutes are up it says to ask again. `lotics auth signup <email>` for an email that\n already has an account creates nothing and names `auth login`.\n- **A credential is either a SIGN-IN or an API KEY, and `logout` treats them differently.** A profile\n from `auth login` / `auth signup` acts as the person who confirmed it and is theirs \u2014 `lotics auth\n logout` revokes it server-side, and it lapses on its own after 90 idle days (each use pushes that\n out). A profile from `auth api-key` holds a key an ADMIN issued. A key created in Settings carries\n its OWN access \u2014 every app and table, or only the ones chosen on the key, so a listing that comes\n back short is the key's reach, not a bug \u2014 while an older key created FOR a person carries that\n person's access and dies with their membership. Either is routinely also on a server and on\n other machines, so logout only forgets it locally and says so; only an admin revokes it. A profile that states no kind (saved before the field existed) is resolved against the SERVER\n and revoked only if the answer is a sign-in; a bare `--api-key` / `LOTICS_API_KEY` names no\n profile to remove at all. Nothing is ever revoked on a guess \u2014 between two, the destructive one is\n wrong. `lotics auth whoami` prints the kind, asking the server when the store cannot say.\n- **A key created in Settings never administers the organization, whatever its access.** The verbs\n `docs/cli_reference.md` reserves to an organization owner or a workspace admin split in two under a key: `workspace doctor`, which only\n reads inside a workspace the key reaches, runs as before, while managing people, sharing or\n ownership, creating or deleting a workspace, changing workspace settings, setting credit limits,\n reading the access log and publishing an app's API answer `403` and name the remedy: an admin signed in, so\n `lotics auth login` and run it again. A sign-in acts as that person and is refused none of\n them. Do not retry a `403` with the same credential and do not ask for a wider key \u2014 no answer on\n the key's own screen grants this.\n- **A 401 names its remedy \u2014 act on the hint, do not retry.** \"This credential expired / was\n revoked / belongs to a member who is no longer active\" carries the one remedy that ends this\n credential: run `lotics auth login` for a sign-in, or ask the admin who issued it for a\n new key. A credential minted before that was recorded carries BOTH, because nothing on the row\n tells them apart \u2014 so on a box with no browser, take the second. Only an UNRECOGNIZED key gets\n the generic \"Invalid or disabled API key\", and that one is generic on purpose, so re-sending it\n teaches nothing. A `reason` rides on the body for a script to branch on, since the code stays\n `unauthorized` for every 401.\n- **Large payloads bypass `ARG_MAX`** \u2014 `lotics run <tool> @args.json`, or piped stdin behind `-`. A leading `@` is\n unambiguously a file path (JSON args start with `{`).\n- **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to\n stderr; the result goes to stdout, so piping stays clean. `--json` switches stdout from the\n agent-readable summary to the full structured object.\n- **Every tool is invoked one way \u2014 `lotics run <tool>`.** Including the ones that RUN something\n (`run_app_workflow`, `run_app_query`) and every one that builds\n (`set_tables`, `set_app`, `set_workflow`). A command\n exists only for work that touches a local file.\n- **Building is two tools, each a writer that creates without an id and edits with one.** `set_tables`\n takes `{ \"tables\": [...] }` \u2014 always a list, one or many, all or nothing \u2014 each table a document keyed\n by alias (fields keyed by alias; a link names its table by id, or by the `ref` of another table of the\n same call, and states `multi`; a two-way link states `pair` on both tables), edited by an RFC 7396\n merge patch of that document, where `null` deletes. A call carries at most 50 tables, 200 first rows a table,\n and 2000 rows and 2000 documents in all. `set_app` takes ONE app: `{ \"body\": <the App tree> }` to create, the app's\n `name`, `description`, `icon` and `color` being props of the App node; `{ \"app_id\": \u2026, \"nodes\": { \"<address>\": <patch> } }`\n to change a node, refused with `base_version_id` when the app has moved past the version you read. `dry_run` checks\n without writing, a refusal lists everything wrong in the call, and every answer states the permissions the write\n granted and removed. The answer shows what the platform drew where the tree is silent (nothing is stored for it) and says what it placed or folded in what the tree states; a placement is stored. A new workspace: one `set_tables` call with\n the tables, then every `set_app` call, then fixes.\n- **Every change to an app mints a version of it, and applying the earlier tree again is the undo.** An apply, a\n deploy, a single `set_app_*`: each is a new version. Applying the earlier tree again restores the app \u2014 never a table change or a row a workflow wrote,\n so try a write on a throwaway record.\n- **Exit codes are assertable, and they report the WORK rather than the call.** `lotics run` exits\n non-zero when a `run_app_workflow` result's own envelope carries a failed\n `status` (`error`/`failed`/`cancelled`, or `not_previewed`: a dry run asked for and not given) \u2014 any other tool's top-level status is data and exits 0 \u2014\n so `lotics run \u2026 && next-step` cannot walk past a refused run; `workspace doctor` exits non-zero on\n findings. An unrecognized status exits 0 \u2014 the list is an allowlist of failure, so a status added\n later never turns a working script red \u2014 and a parked run (`awaiting_input`) is not a failure.\n- **An app that PUBLISHES an API turns every later binding write into a release.** Publishing\n snapshots what the app's queries, workflows and agents promise to callers outside it \u2014 a\n customer's own site or server, which nobody here can redeploy. From then on an additive change\n re-snapshots silently and a breaking one is REFUSED, naming each change; the tool's\n `acknowledge_breaking_api_change` carries it out and snapshots the break as a new contract version.\n- **Exposure is per app, all or nothing** \u2014 a public share or a key reaches every alias an app\n declares, so what outsiders may call is a second app over the same tables\n ([docs/app_architecture.md](./docs/app_architecture.md)).\n- **`--print-created` / `--cleanup` on any call that reports `side_effects`.** The first prints the\n records created plus a paste-ready cleanup plan and what cannot be auto-undone; the second runs\n those deletes (records only \u2014 never files, integrations or notifications). Neither is a rollback.\n- **Text output is the default and is built for reading**; reach for `--json` only when a field is\n needed programmatically.\n- **`lotics report '<json>'` is the channel for what nothing else records.** Reach for it\n when the platform is genuinely missing something (a capability that does not exist \u2014 no\n command ran), when a success was wrong (exited 0, wrong effect), or when an error did\n not name the remedy \u2014 not for your own mistakes, which the logs already show.\n **It is a frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, because a log\n reconstructs what you RAN and never what you WANTED, and that gap is the report. `goal` and\n `actual` are required; there is no severity or category to pick. The\n session's commands attach themselves \u2014 do not retype them. Run it bare for the full prompt; a\n long one rides `@file.json` or an explicit `-` for stdin (bare NEVER reads stdin).\n- **`LOTICS_TELEMETRY=1` correlates a whole session** so the authoring loop's rough edges can be\n found and fixed. Off by default; set it in the shell profile, not per command (each invocation is\n its own process). It sends no arguments, no file contents, and no record data \u2014 see README\n \xA7 Diagnostics.\n\n## Where this CLI is not the answer\n\n- **Editing an app in a local directory.** An app stated as a tree is changed by applying the\n tree again; its bindings through their `set_app_*` tools; a custom-code app's code by deploying\n its directory again. Nothing reads a local copy of a live app back.\n- **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.\n";
@@ -1916,7 +1916,7 @@ var workflow_steps_default = '<!-- Generated by backend/scripts/generate_workflo
1916
1916
  var app_bindings_default = "# App bindings \u2014 the queries and workflows an app calls\n\nA custom-code app reaches workspace data through two kinds of binding, each declared on the app\nunder an alias \u2014 a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):\n\n| Binding | Declared with | The app calls it with | An agent calls it with |\n|---|---|---|---|\n| Query | `set_app`, a `Query` node | `useQuery(\"<alias>\", params?)` | `run_app_query` |\n| Workflow | `set_workflow` | `useWorkflow(\"<alias>\")({ ...inputs })` | `run_app_workflow` |\n\nEach runs under the app's authority (`{ type: \"app\", app_id }`), the app owner's reach \u2014 never the\ncalling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next\ncall uses it. `get_app` lists an app's aliases with their params and inputs.\n\nEach reader returns a fingerprint of what it read, and a write built on that read passes it back:\n`get_workflow`'s `version` as `set_workflow`'s `expected_version`, and `get_app`'s version as `set_app`'s\n`base_version_id`. The write is refused, and writes nothing, when it changed since; omit it for an unconditional write.\n\n## API apps\n\nAn API app is one a customer's own server calls. It holds only `Query` and `Workflow` nodes, so no address serves it, and it cannot be shared publicly.\n\n1. `set_app` with a tree of those nodes, naming the tables they read in `uses`. The answer carries the link where an admin creates its key, and `get_app` states it again.\n2. `set_workflow` sets each workflow's code.\n3. An admin opens the link and creates an app key (`lak_\u2026`). It reaches this app alone and only calls it; no other route and no tool answers it, and that can never be widened. Its secret is shown once, so it goes straight into the server's secrets, and no tool creates or reads one.\n4. To promise the shape to that server, an admin's `set_app` states `{ \"app_id\": \"\u2026\", \"api_published\": true }`: a numbered contract and an OpenAPI document, and a later write that would break it is refused.\n\nThe server sends `Authorization: Bearer lak_\u2026` to `POST /v1/apps/{app_id}/queries/{alias}` and `POST /v1/apps/{app_id}/workflows/{alias}/execute`. The answer holds what the app declares, with each row's own id and timestamps: no member's email, no field id, and a failed run a generic message beside its `execution_id`. A browser cannot call them, and a key never goes in a page.\n\nA `Query` node reads one table or List with `rows` or `list`. A wider read states the whole query as `ast`, below.\n\n## Queries\n\nA query declaration is `{ ast, params?, description?, templates? }`:\n\n- `ast` \u2014 a query template (a QueryNode, below). It fixes the tables, filters and columns the alias\n reads, so a caller cannot widen it.\n- `params` \u2014 the typed value holes the caller fills, each an input declaration (see **Inputs**),\n named in the ast as `{{params.<name>}}`. A param fills a VALUE position only \u2014 a filter value, a\n `search` \u2014 never a `table_id` or a field key. Every token the ast names is declared. An optional\n param left unset drops the conditions that read it; a required param that arrives empty is\n refused where a filter reads it.\n- `description` \u2014 one line saying what the query returns, for an agent choosing between aliases.\n- `templates` \u2014 the document templates an export of its rows may fill, by name:\n `{ <name>: { template_id: \"dtl_\u2026\", rows: \"<key the template lists the rows under>\" } }`.\n\nA save checks what a deploy checks: every table is in this workspace and within the owner's reach,\nevery projected, filtered and sorted field resolves, every param token is declared, and a key a\nnode's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.\n\n`set_app` states one as a `Query` node: `{ \"type\": \"Query\", \"key\": \"<alias>\", \"ast\": { \u2026 } }`, beside `params`,\n`description` and `templates`. On an app made from a tree it stands among the tree's `children`, and a `nodes` patch\nreplaces its `ast`, `params` or `templates` whole. On an app that serves\ncode, `nodes` takes `{ \"<alias>\": { \u2026 } }` and merges each: send only the fields you change, `null` clears `params`,\n`description` or `templates` (never `ast`), a new alias needs an `ast`, and an alias set to `null` is unbound. Its\n`children` state the list whole, each query entire, and an alias they omit is unbound. Any other field is refused by\nname, and `get_app`'s `body` reads them back by alias.\n\n### The query tree\n\nEvery node has a `kind`; all but `from_table` read the node under `from` (`join`: `left`/`right`,\n`union`: `sources`).\n\n| `kind` | Keys |\n|---|---|\n| `from_table` | `table_id`, `filter?`, `search?`, `sort?`, `limit?` |\n| `project` | `columns` \u2014 the output columns |\n| `filter` | `predicate` \u2014 a filter tree over the input's columns |\n| `join` | `left`, `right`, `on: { left_column, right_column }`, `type: \"inner\" \\| \"left\"` |\n| `union` | `sources` (at least two, columns aligned by name and type) |\n| `group` | `by` (columns, `{ bucket: { source, granularity, output } }`, or `{ band: { source, tiers, output } }`), `aggregates` |\n| `window` | `partition_by`, `order_by`, `frame?`, `aggregates?`, `functions?` |\n| `sort` | `by: [{ field_key, order }]` |\n| `limit` | `n`, `offset?` or `keyset?` |\n| `unpivot` | `passthrough`, `row_columns`, `rows` \u2014 one source row into several |\n| `unnest` | `source`, `output`, `display_output?`, `keep_empty?` \u2014 one row per element of a multi-value cell |\n\nFilters (`from_table.filter`, `filter.predicate`, an aggregate's `filter`) are the filter grammar \u2014 the\n`filters` reference \u2014 over the input's columns, taking `{{params.x}}` as values. `search` matches\nevery text-bearing field of the row, accent- and case-insensitive.\n\nA query names a table's fields by the alias its document states, wherever a node reads the table directly (a\n`from_table`'s filter and sort, the `project`, `filter`, `group`, `window`, `unnest` or `unpivot` over it) and a select\ncondition's values by the option's alias. A column a `project` writes answers under the alias it was written with; every\nname past a `project` or an aggregate is that column's own. A `union` whose arms read one alias from different tables\nprojects each arm's columns under one name first. The query is stored by key and read back by alias.\n\nA `project` column is a field's alias as a bare string (output name and type come from the field), or\n`{ output?, type?, source, writable_target?, limit? }` to rename, compute or bound one. A computed\n`source` is a field's alias, `{ literal }`, `{ eq: [a, b] }`, `{ neq: [a, b] }`, `{ isEmpty }`,\n`{ isNotEmpty }`, `{ coalesce: [...] }`, `{ concat: [...] }`, `{ record_id: true }`,\n`{ link: { source, field } }` (a field of the first linked record),\n`{ link_agg: { source, field, operation } }` (`sum`, `avg`, `min`, `max`, `count`, `string_agg`\nover every linked record), or `{ expression }`. A computed column states its `type`: `text`,\n`number`, `boolean`, `date`, `datetime`, `select`, `select_record_link`, `select_member`, `files`\nor `json`. `limit` (1\u201310) bounds a `files` column's entries per cell.\n\nAn aggregate column is `{ output, type, operation, input_column?, filter? }` \u2014 `string_agg` also\ntakes `separator`, `distinct` and `max_values`. A `window` function is\n`{ output, fn }` for `row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`, plus\n`buckets` for `ntile` and `input_column`, `offset?`, `default?` for `lag` / `lead`; functions need\na non-empty `order_by`.\n\n## Inputs\n\nA query's `params`, a workflow's `inputs` and an agent's `inputs` are one vocabulary: a map of\nname \u2192 `{ type, required?, description?, field?, \u2026per type }`. An entry is required unless it states\n`required: false`. `field: \"<table id>.<alias>\"` names the table field the entry is a value of: the field's own\ndescription is read with the entry, as the table states it when read. The inputs an app's own adds, saves and acts\ndeclare name theirs.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email` | \u2014 |\n| `record_link` | `table_id`; `multi?`; `max?` (with `multi`, the most ids one call carries) |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"<table id>.<alias>\"` (a select field whose CURRENT options back it); `multi?` |\n| `date_range` | `include_time?` |\n| `member` | `multi?`; `group?` (a member group the value must belong to) |\n| `file` | `multi?` \u2014 an uploaded `fil_\u2026` id, for a files field |\n| `json` | \u2014 any value |\n| `object` | `fields` \u2014 a nested map of entries |\n| `array` | `items` \u2014 one entry |\n\nA `record_link`'s `table_id`, in inputs and outputs, takes the table's id or alias and is stored as its id. Nesting stops at\ndepth 8. A `field`-form select tracks the field's options as they change, and `only: [\"<option key or alias>\", \u2026]` beside `field` keeps it to those options of the field (inputs and outputs of an app workflow, an app agent or a notification action, not a query's params); an\ninline `options` set is a fixed list. A query's select param takes an option by alias, label or key, each condition reading it by its own field's options, and a value that is none of them is refused naming the options.\n\n## Outputs\n\nA workflow's and an agent's `outputs` declare the structured data handed back: a map of\nname \u2192 `{ type, required?, description?, \u2026per type }`, every entry present unless it states\n`required: false`.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email`, `json` | \u2014 |\n| `record_link` | `table_id`, `multi?` |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"<table id>.<alias>\"`; `multi?` |\n| `object` | `fields` |\n| `array` | `items` |\n\nThe returned value is checked against it, and the app reads it typed. An inline `options` set is\nalso enforced on the value returned, so the producer is told the legal keys; a `field`-form select\nkeeps the type tracking the live field.\n\n## Workflows\n\n`set_workflow` binds a workflow body to an alias: `{ workflow_id?, name?, description?, source }`, the `source`\nopening with `on({ type: \"app\", app_id, alias, inputs?, outputs? })`. Without a `workflow_id` it binds the alias; with\nthe one `get_app` lists for it, it replaces the body. On an app written as a tree the alias is one the tree names \u2014 a Workflow node's\n`key` or an Act's `workflow` \u2014 and the node states `inputs`, `outputs` and `description`\n(`reference/workflow-node`, whose value shapes differ from the **Inputs** below): a call stating any of\nthem for it is refused, and outputs the node leaves out are derived from the body. An alias the tree\nnames nowhere is archived by the next `set_app`. `set_app`'s `workflows` takes the same sources and saves them in the\nsame write as the tree: a change to what a workflow takes or hands back that its saved body no longer meets is refused\nunless the write carries the new body. A Workflow node runs only for someone who holds the\napp: on an app shared by a public link, a visitor's call of it is refused as an alias the app does\nnot have. This page's `inputs` and `outputs` are for a custom-code app.\n\n- `source` is the header, then the body; the app is the trigger. The body reads each declared\n input as `trigger.app_workflow.inputs.<name>`; no record is in scope, so it reads each one by id\n with `query_records` and `record_ids`.\n The body's steps are the `workflows` reference.\n- `inputs` in the header is the payload the call site passes (see **Inputs**). Omitted, an existing workflow keeps\n its inputs; on a first bind it takes an untyped payload. `{}` clears them.\n- `outputs` in the header is what `return({ data })` hands back (see **Outputs**). Usually omit it: the type is\n derived from the body's `return({ data })`, and the result echoes the bound `outputs`. Declared,\n the body does not save unless its return matches.\n- A save checks the body \u2014 parse, type-check against the declared inputs, names, lint, structure \u2014\n and answers with `[source/code] location: message` lines. `dry_run: true` makes every check\n and writes nothing. A call naming a live alias replaces its body in place, keeping its run history.\n- A call whose payload does not match `inputs` is refused before the body runs.\n\n`get_workflow` reads the source back; `set_workflow` with `dry_run` and `record_id` or `preview_inputs`\nrehearses a draft before binding; `set_workflow` with `delete: true` and the `workflow_id` unbinds it. An unbind is refused\nwhile the deployed version of the app calls the alias or an agent of the app declares it (`even_if_invoked` overrides it for a\nworkflow that has run, only when the caller that ran it is gone).\n";
1917
1917
 
1918
1918
  // docs/document_templates.md
1919
- var document_templates_default = '# Document Templates\n\nTurn workspace data into finished documents \u2014 invoices, contracts, reports, letters,\nlabels, emails \u2014 by filling a reusable template instead of writing a file from scratch.\nYou register a template once, then generate a filled file (or a rendered email) from it as\nmany times as you like, feeding it data from records, a workflow, or an agent run.\n\nThis is a **capability + usage** guide. A tool\'s exact input schema is in its own description.\n\n## The five template types\n\n`set_template` writes all five. Its `type` names which one a new template is.\n\n| Type | What it fills | Output | `type` |\n|---|---|---|---|\n| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `"pdf-form"` |\n| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `"html"` |\n| `excel` | an **uploaded `.xlsx` or `.xlsm`** with `{{marker}}` cells | `.xlsx` | `"excel"` |\n| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `"word"` |\n| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `"email"` |\n\nTwo shapes underneath: **file-backed** (`pdf-form`, `excel`, `word`) clone an uploaded\noffice file and mark it up; **inline** (`html`, `email`) store the markup you author directly.\n\n## The lifecycle: create \u2192 generate \u2192 chain\n\n1. **Create** a template \u2014 register the file (or inline markup) and declare a `variables`\n map (the named slots the template fills). This returns a template id (`dtl_\u2026`).\n2. **Generate** a filled file \u2014 call `generate_document` with the\n template id, a `filename` (no extension), and a `data` map keyed by your variable names.\n It substitutes the markers and returns a **generated file** (with a `file_id`).\n3. **Chain** the result \u2014 generation only *produces* the file. Attaching it to a record,\n sending it, or saving it is a separate step: `update_records` with `add_to` on a files field\n files the `file_id` on a record (`remove_made`, a template id, takes out the paper that template\n made earlier); over MCP and on the CLI, `download_file` fetches it; inside a workflow, pass the `file_id` to the next\n step. A paper an app makes is its Act\'s `template`, which files it on the record itself\n (below).\n\nEmail is the exception: `generate_document` refuses an email template. An email template is\nrendered to a subject + body **at send time** from the template and the data the send step\nsupplies \u2014 so you author it with `set_template` and a workflow/app send step (or the\nweb composer) does the rendering and delivery. External agents send their own email directly.\n\n## Creating and changing a template\n\nA paper prints the owner\'s own terms only: the clauses, wording and fields of the sample they sent, never a term the owner did not state.\n\n`set_template` creates a template when it is given no `template_id`, and changes the named one\nwhen it is given one. Creating takes `type` and `name`, and the fields of its type; changing takes\n`expected_version` \u2014 the `current_version` that `get_template` returned, so a concurrent edit is\nrefused rather than overwritten \u2014 and only the fields to change. A field the type does not take is\nrefused rather than dropped. `description` (one line on what the template produces) is on every type. A template\'s\nalias is made from its name when it is created and stays when the template is renamed. A change is\nbuilt into every app whose Acts make the template; one an app can no longer be built with is refused, naming the app and\nthe marker, and nothing is written.\n\n### Getting a file in\n\nA file-backed template starts from a file in the workspace: over MCP and on the CLI, `upload_file` takes a public URL,\nor bytes you hold, and returns a `file_id`. When the person has the file and your host shows you its content but not its\nbytes, `upload_file` with `person: true` returns a `drop_url` for them to open and a `ticket_id` per file; once they say\nthey dropped it, `upload_file` with that `ticket_id` returns the `file_id`.\n\nA new Word or Excel paper is a file you build yourself, in your own filesystem or sandbox, with its markers typed where\nthe values go, then, over MCP or on the CLI, send it with `upload_file` `files` and register with `set_template`. Where your sandbox cannot reach\nthis host, give the person the file and a `person` drop link.\n\n### By type\n\n- **`html`** \u2014 a full HTML document with inline CSS and `{{variable}}` placeholders, rendered to PDF; anything whose layout\n you control. `variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (a named page size:\n A0\u2013A6, Letter, Legal, Tabloid, Ledger) and `orientation` are optional; any other size is the page\'s own CSS,\n `@page { size: 50mm 30mm }`. A change may send `patch_ops`, exact search-and-replace edits of the stored markup, in place\n of the whole `template`.\n- **`pdf-form`** \u2014 an existing PDF filled in place. `set_template` with the uploaded `template_file_id`\n answers `page_count` and `pages` (each page\'s `page_index`, unrotated MediaBox `width` and `height`, `origin_x`, `origin_y`\n and its `labels`, the text with its position and font size; `get_template` returns the same); `set_template` again with\n `expected_version` and the positioned `variables` (`text` / `checkbox` / `image`, each with a page and x/y/size). Data is one scalar per field. A field whose `page` is past `page_count`, or whose box lies outside that page\'s MediaBox,\n is refused. The answer holds at most 50 pages and 400 labels a page; `pages_omitted` and each page\'s `labels_omitted`\n count the rest, and `pages_unavailable` says why a template\'s pages could not be read.\n A positioned text field prints in Arimo, which covers Vietnamese; a PDF\'s own field keeps its font while its value is\n ASCII and switches to Arimo past it.\n- **`excel`** \u2014 a `.xlsx` or `.xlsm` with `{{marker}}`s in the cells to fill, and a `variables` map. `sheet` names the sheet\n that is the paper in a workbook holding others, and the template leaves the rest out; a formula reading a sheet left out\n is refused. A macro workbook is kept without its macros and the buttons that run them. Markers are validated at create\n time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables`\n (skipped). `set_template` with `dry_run: true` runs every check and stores nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass\n raw numbers, ISO dates and booleans at generate time; the cell\'s number format shows them. A cell\'s format also decides\n what text becomes: text that reads as a number (`5%`) is written as one, unless the cell is formatted as text (`@`).\n- **`word`** \u2014 a `.docx` with `{{marker}}`s. `variables` is optional: every marker is derived (`{{name}}` string,\n `{{FOR \u2026 IN name}}` array, `{{IF name}}` boolean), and a marker you did not declare is still added\n (`derived_variables`). At generate time `data` needs a key for **every** marker, `""` for a blank one. A marker may run\n across formatting runs and is still read whole. In a table, the row holding `{{FOR line IN lines}}` and the row holding\n `{{END-FOR line}}` enclose the row that repeats. A newline in a value prints as a line break and a tab as a tab;\n a tab the paper prints only when a blank is empty is written `{{IF !name}}{{"\\t"}}\u2026\u2026{{END-IF}}`, since the\n form\'s own tab stays put inside an `{{IF}}` on the same line.\n- **`email`** \u2014 inline HTML + Handlebars, with `template` and `variables`; optionally a default `subject` (it takes\n `{{variable}}` too) and `default_to`, `default_cc`, `default_bcc`. Body and subject render from the data at send time.\n\n## Markers, at a usage level\n\nEvery type supports three shapes of substitution. The exact syntax differs per engine \u2014 read\nthe `set_template` description for the reference; here is the capability:\n\n- **Scalar** \u2014 a single value in one spot: `{{name}}`, `{{total}}`. Whole-cell scalars in\n Excel preserve their type via the cell\'s number format.\n- **Repeating rows / line items** \u2014 one template row rendered once per item in a list, for\n invoice lines, order rows, tables. Excel and the HTML/email engines use a Handlebars-style\n `{{#each items}}\u2026{{/each}}`; Word uses `{{FOR item IN items}}\u2026{{$item.field}}\u2026{{END-FOR item}}`. The HTML and email types\n also offer an auto-rendered `table` variable \u2014 declare its columns and pass an array, no\n hand-written loop. Excel marks the rows that repeat with `{{#each items}}` and `{{/each}}`, each alone in a row above and\n below them, or inline in the paper\'s own rows: `{{#each items}}` opens the first repeated row\'s first cell holding text\n and `{{/each}}` closes the last one\'s last (a formula cell is passed over), so a one-row body reads `{{#each lines}}{{@ordinal}}` \u2026 `{{amount}}{{/each}}`. A row repeats for one loop: two loops side by side in the same rows are refused, so put them in separate row bands or on separate sheets.\n (Excel has no auto-rendered `table` type; its variable types are string/number/date/boolean/array.) Inside a loop the row\'s number counted from 1\n is `{{@ordinal}}` (Excel, HTML, email) or `{{$ordinal}}` (Word), the innermost loop\'s: an STT column is a cell holding\n `{{@ordinal}}` beside the row\'s other markers. `{{@index}}` counts from 0.\n- **Columns across** \u2014 a column per item of a list, for a grid of rows by days or by kinds. HTML/email nest a\n `{{#each}}` inside a table row\'s; Excel repeats the columns between `{{#each-col columns}}` and `{{/each-col}}`, each\n marker alone in its column, and a row\'s cell under the column is `{{cells | lookup:@index}}`, its list\'s item at that\n column\'s place; Word repeats a table cell between a cell holding `{{FOR c IN columns}}` and one holding\n `{{END-FOR c}}`, and a row\'s cells the same way inside its loop, `{{FOR k IN $r.cells}}` `{{$k}}` `{{END-FOR k}}`.\n- **Conditional sections** \u2014 a block shown only when a condition holds (a "paid" stamp, an\n optional notes block). Excel/HTML/email use `{{#if}}\u2026{{else}}\u2026{{/if}}`; Word uses `{{IF name}}\u2026{{END-IF name}}`.\n\nThe `html` and `email` types print a raw value through a helper in the template\'s `locale` (`vi` or `en`; none prints in the organization\'s language): `{{money total "VND"}}`, `{{number qty item_unit}}` (the figure, then its unit), `{{date issued_on}}`, `{{words total "USD"}}` (`reference/groups-and-templates` lists what each prints). `{{date (add_days issued_on -1)}}` prints the day before, `add_days` shifting a date by whole days. A value a helper cannot read fails the render, and a template calling a helper the engine lacks (`{{eq a b}}`) is refused when saved, naming the ones it has.\n\nA field can also print as a **QR code** or a **Code 128 barcode** (a picture a phone\'s camera or a scanner reads back): `{{qr link}}` or `{{code128 position 6}}` in html (never email: mail clients do not show the picture, and a save refuses it), `{{position | qr}}` or `{{position | code128:6}}` as a whole Excel cell (its row grows to the picture), `{{IMAGE qr(position)}}` or `{{IMAGE code128(position, 6)}}` in Word. The optional number is the picture\'s width in centimetres. Without it the width follows the value\'s length \u2014 each module prints 0.5 mm in a QR code and 0.33 mm in a barcode, so a longer value prints wider; a width that would shrink a module below what a scanner reads (0.3 mm, 0.19 mm) is refused, naming the least width that scans. An empty field draws nothing.\n\nA cell merged in an Excel template over the rows of a loop covers the rows that loop becomes; inside an outer loop, each of its items its own rows (a group\'s name merged beside its lines). An Excel cell\'s text can stand in parts, some of them bold: `{{goods | rich}}` as the whole cell takes a list of `{ text, bold }` and writes the parts as one text, a bold part in the cell\'s own font made bold. Excel shows a row at most 409 points tall and cuts a cell\'s text past it, so a long text is laid over several rows.\n\nA record\'s **photos** (a files field, or a lookup of one through its links, an act\'s paper hands each as a file cell `{id, name, mime, url}`) print too, and only for a file whoever makes the paper may read \u2014 the same rule the file proxy applies; any other file is never drawn. html: `{{#each photos}}<img src="{{url}}">{{/each}}` (only the data\'s file cells are inlined; a url typed into a text field stays a link). Word: `{{IMAGE picture(cover, 8)}}`, and `{{FOR p IN photos}}{{IMAGE picture($p, 8)}}{{END-FOR p}}` for several. Excel: `{{cover | picture:6}}` as the whole cell, or `{{this | picture}}` inside `{{#each photos}}` (each row grows to its picture). The number is the width in centimetres (8, or 6 in Excel, by default). `picture` takes one image file: a list (loop over it), a file that is no image or one that cannot be read is refused by name. Photos are embedded at most 1600 pixels across, about 200 dpi at 20 cm.\n\nA Word command (`{{ \u2026 }}`) reads the data and calls, by name, a Word helper (`picture`, `qr`, `code128`) or one of these text\nand number functions: `trim`, `trimStart`, `trimEnd`, `lower`, `upper`, `capitalize`, `replace`, `replaceAll`, `removeChars`, `removeSpaces`,\n`startsWith`, `endsWith`, `contains`, `substring`, `padStart`, `padEnd`, `length`, `join`, `split`, `repeat`, `formatNumber`,\n`formatDecimal`, `numberToWords`. It holds no JavaScript method or regular-expression literal: `{{upper(name)}}`,\n`{{formatDecimal(total, 0, "vi-VN")}}`, and `{{removeSpaces(removeChars(cccd || "", ".\u2026"))}}` for the text without its dots,\nellipses and spaces. `removeChars(text, chars)` removes every character of `text` that occurs in `chars` (a set of characters,\nnever a pattern); `removeSpaces(text)` removes every whitespace character of `text`, anywhere in it, the set `trim` trims.\n\nA field named like a function is read as the field, and calling the function then fails.\n\n`set_template`\'s description holds each type\'s exact marker grammar and helper list.\n\n## Generating a filled file\n\n```\nget_template {"template_id": "dtl_\u2026"} # its declared variables\ngenerate_document {"document_template_id": "dtl_\u2026", "filename": "invoice-1042",\n "data": {"company_name": "Acme", "total": 1042, "items": [...]}}\n```\n\n- `data` is a map keyed by your variable names. Scalars for scalar/form fields; arrays for\n `table`/`list`/loop variables. `filename` excludes the extension (the type sets it). Pass a select, a\n member or a link as `query_records`\' `display` words, a number and a date raw.\n- `generate_document` renders the template\'s own type and returns a generated file object; take\n its `file_id` onward.\n- A PDF no template is wanted for takes `html`, a `filename` and its `data` in place of `document_template_id`: the markup is\n rendered as an `html` template is (the same markup rules, markers and helpers) and the PDF is stored as a workspace file. Name one of the two.\n- In a workflow, a **generate step** calls the same tool and hands the `file_id` to the next\n step (attach to a record, send as an attachment, etc.).\n\n## A template an app\'s Act makes\n\nAn Act with `template` (or `templates`) fills an `html`, `excel` or `word` template from its record and files the result\n(a PDF, an `.xlsx` or a `.docx`) in the record\'s files field `into`; `run_app_workflow` on `act_<key>` presses it. The Act hands the template the record\'s fields by their\nalias, so name each variable after one: `{{customer}}`, `{{total}}`. A select, a member and a link arrive as their words\n(a link as the linked row\'s title); a number and a date arrive raw, for `{{money total "VND"}}` and `{{date issued_on}}`.\nA loop over a link of the record whose partner the table pairs, or over the alias of a table that links to the record\nonce, receives those rows with their fields, read under the app\'s row rules:\n\n```html\n<h1>Quote {{code}}</h1>\n<p>{{customer}} \u2014 {{money total "VND"}}</p>\n{{#each lines}}<p>{{description}} \xD7 {{quantity}}</p>{{/each}}\n```\n\nHere `code`, `customer` and `total` are fields of the record and `lines` is its link to the child table, so\n`{{#each quote_line}}`, the child table\'s alias, fills as well; a Word template loops the same rows with `{{FOR line IN lines}}` \u2026\n`{{$line.description}}` \u2026 `{{END-FOR line}}`. A link whose partner is not paired reaches no rows from the record, and\na loop printing a field of each of its items is refused, naming `pair`.\n\nEvery List the record draws and the template names (an html template\'s variables, a Word template\'s markers) hands its\nrows, each List\'s `where` applied; a List the template does not name is not read. A List that only reads hands them under its\n`key` (the table\'s alias where it states none), and a List that sums a number hands the sums under `<name>_totals`, one\nentry per number the List draws as a column or as the table\'s figure. A `where` bound may be `{ "record": "<field>" }`,\na date or number the record itself holds, so a record can print a window of its own days. A service plan row (customer,\n`period_start`, `period_end`) draws the customer\'s visits within its period:\n\n```\n{ "type": "List", "key": "visits", "entity": "visit", "same": "customer", "label": "Visits", "columns": ["visited_on", "hours"],\n "where": { "visited_on": { "gte": { "record": "period_start" }, "lte": { "record": "period_end" } } } }\n```\n\n```html\n{{#each visits}}<p>{{visited_on}} \u2014 {{hours}} h</p>{{/each}}\n<p>Total {{visits_totals.hours}} h</p>\n```\n\nA bound the record leaves blank, or holds as anything but one whole day (`2026-05`) or one figure, keeps no row:\n`visits` is empty and `visits_totals.hours` is `0`. The sums add a number as the List\'s foot does: a cell holding a\nfigure adds it, any other cell (blank, an errored formula, a lookup\'s list) adds nothing. A Word template loops\n`{{FOR v IN visits}}` and prints `{{visits_totals.hours}}` the same way. A template that names a List narrowed to the\nreader (`"me"`) is refused, and so is a name a rows List and a `list` List both reach: give the `list` a `key`. A record\nbound narrows what is listed and is never an access bound; the table\'s row rules are.\n\nA List that reads by a path (`via: "<link>.<link>"`) hands its rows the same way. A List the screen draws as an outline (a record\'s own\nsub-rows, in a table whose rows nest, with no `where`, total, group, long-text column or other narrowing) hands every sub-row, depth first, each after the row it is filed under and its\nsiblings in the List\'s order, with its depth as `level` (1 for the rows filed under the record): `{{#each tasks}}{{level}} {{name}}{{/each}}`.\nA paper that lists an outline whose table has a field named `level` is refused. Inside a listed row a link arrives as the\ntitles of its rows (`{{#each marks}}{{this}}{{/each}}` prints them), so a loop there printing a field of each item is\nrefused, naming the key a List hands those rows under; so is one drawing a table cell per title, which lines up with no\ncolumn \u2014 a grid of rows by days is a roster\'s Export (below). A Word template is read for this when it is next saved.\n\nA paper made over several rows (`on: "ticked"` or `"view"`, at most 200) is one file of them all: the rows arrive under the entity\'s alias. An html paper hands each row the child rows the record\'s paper would be handed, under the same names, with their `_totals`; an Excel or Word paper is handed the rows alone. The page the rows open draws those Lists:\n\n```html\n{{#each supplier_order}}<h2>{{code}}</h2>{{#each sources}}<p>{{description}} \xD7 {{quantity}}</p>{{/each}}{{/each}}\n```\n\nA paper over many rows (a client\'s month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act\'s `template`; or a List `Export` with `template` and `per` (`reference/export-node`).\n`reference/groups-and-templates` has the rest.\n\nA roster\'s `Export` (an html or Excel `template`) is handed its grid over the window in view: `columns`, the days\nholding a row in the file (with `expect`, every option), each a `label`, its `date` and `weekday`; and on each row (under the List\'s entity alias, `student` here)\n`cells`, a word per column \u2014 each of its rows\' mark, the option\'s `short` else its label (a row with no state, its title), joined by `, ` \u2014\n`counts`, how many of its rows stand at each option by alias (`held`, at none), and `total`, as the roster reads it (its owed or expected ratio, else the sum of the row\'s figure, else the count of the cells it holds):\n\n```html\n<tr><th>Student</th>{{#each columns}}<th>{{label}}</th>{{/each}}<th>Absent</th></tr>\n{{#each student}}<tr><td>{{name}}</td>{{#each cells}}<td>{{this}}</td>{{/each}}<td>{{counts.absent}}</td></tr>{{/each}}\n```\n\n| | A | B | C | D | E |\n|---|---|---|---|---|---|\n| 1 | Student | `{{#each-col columns}}` | `{{label}}` | `{{/each-col}}` | Absent |\n| 2 | `{{#each student}}` | | | | |\n| 3 | `{{name}}` | | `{{cells \\| lookup:@index}}` | | `{{counts.absent}}` |\n| 4 | `{{/each}}` | | | | |\n\n## Discovering and managing templates\n\nThese tools work across all five types:\n\n| Tool | Does |\n|---|---|\n| `get_workspace` | list the workspace\'s templates (`kind: "template"`), each with its id, type and one line |\n| `get_template` | one template\'s full definition, incl. the `variables` it expects and the `current_version` a change needs |\n| `set_template` | create a template, change one, delete it (`delete: true` with `template_id`) or bring it back (`restore: true`); `dry_run: true` checks the call and stores nothing; a copy is `get_template` then `set_template` |\n\nCall `get_template` before generating when you don\'t already know a template\'s variable names.\n';
1919
+ var document_templates_default = '# Document Templates\n\nTurn workspace data into finished documents \u2014 invoices, contracts, reports, letters,\nlabels, emails \u2014 by filling a reusable template instead of writing a file from scratch.\nYou register a template once, then generate a filled file (or a rendered email) from it as\nmany times as you like, feeding it data from records, a workflow, or an agent run.\n\nThis is a **capability + usage** guide. A tool\'s exact input schema is in its own description.\n\n## The five template types\n\n`set_template` writes all five. Its `type` names which one a new template is.\n\n| Type | What it fills | Output | `type` |\n|---|---|---|---|\n| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `"pdf-form"` |\n| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `"html"` |\n| `excel` | an **uploaded `.xlsx` or `.xlsm`** with `{{marker}}` cells | `.xlsx` | `"excel"` |\n| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `"word"` |\n| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `"email"` |\n\nTwo shapes underneath: **file-backed** (`pdf-form`, `excel`, `word`) clone an uploaded\noffice file and mark it up; **inline** (`html`, `email`) store the markup you author directly.\n\n## The lifecycle: create \u2192 generate \u2192 chain\n\n1. **Create** a template \u2014 register the file (or inline markup) and declare a `variables`\n map (the named slots the template fills). This returns a template id (`dtl_\u2026`).\n2. **Generate** a filled file \u2014 call `generate_document` with the\n template id, a `filename` (no extension), and a `data` map keyed by your variable names.\n It substitutes the markers and returns a **generated file** (with a `file_id`).\n3. **Chain** the result \u2014 generation only *produces* the file. Attaching it to a record,\n sending it, or saving it is a separate step: `update_records` with `add_to` on a files field\n files the `file_id` on a record (`remove_made`, a template\'s id or alias, takes out the paper that template\n made earlier); over MCP and on the CLI, `download_file` fetches it; inside a workflow, pass the `file_id` to the next\n step. A paper an app makes is its Act\'s `template`, which files it on the record itself\n (below).\n\nEmail is the exception: `generate_document` refuses an email template. An email template is\nrendered to a subject + body **at send time** from the template and the data the send step\nsupplies \u2014 so you author it with `set_template` and a workflow/app send step (or the\nweb composer) does the rendering and delivery. External agents send their own email directly.\n\n## Creating and changing a template\n\nA paper prints the owner\'s own terms only: the clauses, wording and fields of the sample they sent, never a term the owner did not state.\n\n`set_template` creates a template when it is given no `template_id`, and changes the named one\nwhen it is given one. Creating takes `type` and `name`, and the fields of its type; changing takes\n`expected_version` \u2014 the `current_version` that `get_template` returned, so a concurrent edit is\nrefused rather than overwritten \u2014 and only the fields to change. A field the type does not take is\nrefused rather than dropped. `description` (one line on what the template produces) is on every type. A template\'s\nalias is made from its name when it is created and stays when the template is renamed. A change is\nbuilt into every app whose Acts make the template; one an app can no longer be built with is refused, naming the app and\nthe marker, and nothing is written.\n\n### Getting a file in\n\nA file-backed template starts from a file in the workspace: over MCP and on the CLI, `upload_file` takes a public URL,\nor bytes you hold, and returns a `file_id`. When the person has the file and your host shows you its content but not its\nbytes, `upload_file` with `person: true` returns a `drop_url` for them to open and a `ticket_id` per file; once they say\nthey dropped it, `upload_file` with that `ticket_id` returns the `file_id`.\n\nA new Word or Excel paper is a file you build yourself, in your own filesystem or sandbox, with its markers typed where\nthe values go, then, over MCP or on the CLI, send it with `upload_file` `files` and register with `set_template`. Where your sandbox cannot reach\nthis host, give the person the file and a `person` drop link.\n\n### By type\n\n- **`html`** \u2014 a full HTML document with inline CSS and `{{variable}}` placeholders, rendered to PDF; anything whose layout\n you control. `variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (a named page size:\n A0\u2013A6, Letter, Legal, Tabloid, Ledger) and `orientation` are optional; any other size is the page\'s own CSS,\n `@page { size: 50mm 30mm }`. A change may send `patch_ops`, exact search-and-replace edits of the stored markup, in place\n of the whole `template`.\n- **`pdf-form`** \u2014 an existing PDF filled in place. `set_template` with the uploaded `template_file_id`\n answers `page_count` and `pages` (each page\'s `page_index`, unrotated MediaBox `width` and `height`, `origin_x`, `origin_y`\n and its `labels`, the text with its position and font size; `get_template` returns the same); `set_template` again with\n `expected_version` and the positioned `variables` (`text` / `checkbox` / `image`, each with a page and x/y/size). Data is one scalar per field. A field whose `page` is past `page_count`, or whose box lies outside that page\'s MediaBox,\n is refused. The answer holds at most 50 pages and 400 labels a page; `pages_omitted` and each page\'s `labels_omitted`\n count the rest, and `pages_unavailable` says why a template\'s pages could not be read.\n A positioned text field prints in Arimo, which covers Vietnamese; a PDF\'s own field keeps its font while its value is\n ASCII and switches to Arimo past it.\n- **`excel`** \u2014 a `.xlsx` or `.xlsm` with `{{marker}}`s in the cells to fill, and a `variables` map. `sheet` names the sheet\n that is the paper in a workbook holding others, and the template leaves the rest out; a formula reading a sheet left out\n is refused. A macro workbook is kept without its macros and the buttons that run them. Markers are validated at create\n time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables`\n (skipped). `set_template` with `dry_run: true` runs every check and stores nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass\n raw numbers, ISO dates and booleans at generate time; the cell\'s number format shows them. A cell\'s format also decides\n what text becomes: text that reads as a number (`5%`) is written as one, unless the cell is formatted as text (`@`).\n- **`word`** \u2014 a `.docx` with `{{marker}}`s. `variables` is optional: every marker is derived (`{{name}}` string,\n `{{FOR \u2026 IN name}}` array, `{{IF name}}` boolean), and a marker you did not declare is still added\n (`derived_variables`). At generate time `data` needs a key for **every** marker, `""` for a blank one. A marker may run\n across formatting runs and is still read whole. In a table, the row holding `{{FOR line IN lines}}` and the row holding\n `{{END-FOR line}}` enclose the row that repeats. A newline in a value prints as a line break and a tab as a tab;\n a tab the paper prints only when a blank is empty is written `{{IF !name}}{{"\\t"}}\u2026\u2026{{END-IF}}`, since the\n form\'s own tab stays put inside an `{{IF}}` on the same line.\n- **`email`** \u2014 inline HTML + Handlebars, with `template` and `variables`; optionally a default `subject` (it takes\n `{{variable}}` too) and `default_to`, `default_cc`, `default_bcc`. Body and subject render from the data at send time.\n\n## Markers, at a usage level\n\nEvery type supports three shapes of substitution. The exact syntax differs per engine \u2014 read\nthe `set_template` description for the reference; here is the capability:\n\n- **Scalar** \u2014 a single value in one spot: `{{name}}`, `{{total}}`. Whole-cell scalars in\n Excel preserve their type via the cell\'s number format.\n- **Repeating rows / line items** \u2014 one template row rendered once per item in a list, for\n invoice lines, order rows, tables. Excel and the HTML/email engines use a Handlebars-style\n `{{#each items}}\u2026{{/each}}`; Word uses `{{FOR item IN items}}\u2026{{$item.field}}\u2026{{END-FOR item}}`. The HTML and email types\n also offer an auto-rendered `table` variable \u2014 declare its columns and pass an array, no\n hand-written loop. Excel marks the rows that repeat with `{{#each items}}` and `{{/each}}`, each alone in a row above and\n below them, or inline in the paper\'s own rows: `{{#each items}}` opens the first repeated row\'s first cell holding text\n and `{{/each}}` closes the last one\'s last (a formula cell is passed over), so a one-row body reads `{{#each lines}}{{@ordinal}}` \u2026 `{{amount}}{{/each}}`. A row repeats for one loop: two loops side by side in the same rows are refused, so put them in separate row bands or on separate sheets.\n (Excel has no auto-rendered `table` type; its variable types are string/number/date/boolean/array.) Inside a loop the row\'s number counted from 1\n is `{{@ordinal}}` (Excel, HTML, email) or `{{$ordinal}}` (Word), the innermost loop\'s: an STT column is a cell holding\n `{{@ordinal}}` beside the row\'s other markers. `{{@index}}` counts from 0.\n- **Columns across** \u2014 a column per item of a list, for a grid of rows by days or by kinds. HTML/email nest a\n `{{#each}}` inside a table row\'s; Excel repeats the columns between `{{#each-col columns}}` and `{{/each-col}}`, each\n marker alone in its column, and a row\'s cell under the column is `{{cells | lookup:@index}}`, its list\'s item at that\n column\'s place; Word repeats a table cell between a cell holding `{{FOR c IN columns}}` and one holding\n `{{END-FOR c}}`, and a row\'s cells the same way inside its loop, `{{FOR k IN $r.cells}}` `{{$k}}` `{{END-FOR k}}`.\n- **Conditional sections** \u2014 a block shown only when a condition holds (a "paid" stamp, an\n optional notes block). Excel/HTML/email use `{{#if}}\u2026{{else}}\u2026{{/if}}`; Word uses `{{IF name}}\u2026{{END-IF name}}`.\n\nThe `html` and `email` types print a raw value through a helper in the template\'s `locale` (`vi` or `en`; none prints in the organization\'s language): `{{money total "VND"}}`, `{{number qty item_unit}}` (the figure, then its unit), `{{date issued_on}}`, `{{words total "USD"}}` (`reference/groups-and-templates` lists what each prints). `{{date (add_days issued_on -1)}}` prints the day before, `add_days` shifting a date by whole days. A value a helper cannot read fails the render, and a template calling a helper the engine lacks (`{{eq a b}}`) is refused when saved, naming the ones it has.\n\nA field can also print as a **QR code** or a **Code 128 barcode** (a picture a phone\'s camera or a scanner reads back): `{{qr link}}` or `{{code128 position 6}}` in html (never email: mail clients do not show the picture, and a save refuses it), `{{position | qr}}` or `{{position | code128:6}}` as a whole Excel cell (its row grows to the picture), `{{IMAGE qr(position)}}` or `{{IMAGE code128(position, 6)}}` in Word. The optional number is the picture\'s width in centimetres. Without it the width follows the value\'s length \u2014 each module prints 0.5 mm in a QR code and 0.33 mm in a barcode, so a longer value prints wider; a width that would shrink a module below what a scanner reads (0.3 mm, 0.19 mm) is refused, naming the least width that scans. An empty field draws nothing.\n\nA cell merged in an Excel template over the rows of a loop covers the rows that loop becomes; inside an outer loop, each of its items its own rows (a group\'s name merged beside its lines). An Excel cell\'s text can stand in parts, some of them bold: `{{goods | rich}}` as the whole cell takes a list of `{ text, bold }` and writes the parts as one text, a bold part in the cell\'s own font made bold. Excel shows a row at most 409 points tall and cuts a cell\'s text past it, so a long text is laid over several rows.\n\nA record\'s **photos** (a files field, or a lookup of one through its links, an act\'s paper hands each as a file cell `{id, name, mime, url}`) print too, and only for a file whoever makes the paper may read \u2014 the same rule the file proxy applies; any other file is never drawn. html: `{{#each photos}}<img src="{{url}}">{{/each}}` (only the data\'s file cells are inlined; a url typed into a text field stays a link). Word: `{{IMAGE picture(cover, 8)}}`, and `{{FOR p IN photos}}{{IMAGE picture($p, 8)}}{{END-FOR p}}` for several. Excel: `{{cover | picture:6}}` as the whole cell, or `{{this | picture}}` inside `{{#each photos}}` (each row grows to its picture). The number is the width in centimetres (8, or 6 in Excel, by default). `picture` takes one image file: a list (loop over it), a file that is no image or one that cannot be read is refused by name. Photos are embedded at most 1600 pixels across, about 200 dpi at 20 cm.\n\nA Word command (`{{ \u2026 }}`) reads the data and calls, by name, a Word helper (`picture`, `qr`, `code128`) or one of these text\nand number functions: `trim`, `trimStart`, `trimEnd`, `lower`, `upper`, `capitalize`, `replace`, `replaceAll`, `removeChars`, `removeSpaces`,\n`startsWith`, `endsWith`, `contains`, `substring`, `padStart`, `padEnd`, `length`, `join`, `split`, `repeat`, `formatNumber`,\n`formatDecimal`, `numberToWords`. It holds no JavaScript method or regular-expression literal: `{{upper(name)}}`,\n`{{formatDecimal(total, 0, "vi-VN")}}`, and `{{removeSpaces(removeChars(cccd || "", ".\u2026"))}}` for the text without its dots,\nellipses and spaces. `removeChars(text, chars)` removes every character of `text` that occurs in `chars` (a set of characters,\nnever a pattern); `removeSpaces(text)` removes every whitespace character of `text`, anywhere in it, the set `trim` trims.\n\nA field named like a function is read as the field, and calling the function then fails.\n\n`set_template`\'s description holds each type\'s exact marker grammar and helper list.\n\n## Generating a filled file\n\n```\nget_template {"template_id": "dtl_\u2026"} # its declared variables\ngenerate_document {"document_template_id": "dtl_\u2026", "filename": "invoice-1042",\n "data": {"company_name": "Acme", "total": 1042, "items": [...]}}\n```\n\n- `data` is a map keyed by your variable names. Scalars for scalar/form fields; arrays for\n `table`/`list`/loop variables. `filename` excludes the extension (the type sets it). Pass a select, a\n member or a link as `query_records`\' `display` words, a number and a date raw.\n- `generate_document` renders the template\'s own type and returns a generated file object; take\n its `file_id` onward.\n- A PDF no template is wanted for takes `html`, a `filename` and its `data` in place of `document_template_id`: the markup is\n rendered as an `html` template is (the same markup rules, markers and helpers) and the PDF is stored as a workspace file. Name one of the two.\n- In a workflow, a **generate step** calls the same tool and hands the `file_id` to the next\n step (attach to a record, send as an attachment, etc.).\n\n## A template an app\'s Act makes\n\nAn Act with `template` (or `templates`) fills an `html`, `excel` or `word` template from its record and files the result\n(a PDF, an `.xlsx` or a `.docx`) in the record\'s files field `into`; `run_app_workflow` on `act_<key>` presses it. The Act hands the template the record\'s fields by their\nalias, so name each variable after one: `{{customer}}`, `{{total}}`. A select, a member and a link arrive as their words\n(a link as the linked row\'s title); a number and a date arrive raw, for `{{money total "VND"}}` and `{{date issued_on}}`.\nA loop over a link of the record whose partner the table pairs, or over the alias of a table that links to the record\nonce, receives those rows with their fields, read under the app\'s row rules:\n\n```html\n<h1>Quote {{code}}</h1>\n<p>{{customer}} \u2014 {{money total "VND"}}</p>\n{{#each lines}}<p>{{description}} \xD7 {{quantity}}</p>{{/each}}\n```\n\nHere `code`, `customer` and `total` are fields of the record and `lines` is its link to the child table, so\n`{{#each quote_line}}`, the child table\'s alias, fills as well; a Word template loops the same rows with `{{FOR line IN lines}}` \u2026\n`{{$line.description}}` \u2026 `{{END-FOR line}}`. A link whose partner is not paired reaches no rows from the record, and\na loop printing a field of each of its items is refused, naming `pair`.\n\nEvery List the record draws and the template names (an html template\'s variables, a Word template\'s markers) hands its\nrows, each List\'s `where` applied; a List the template does not name is not read. A List that only reads hands them under its\n`key` (the table\'s alias where it states none), and a List that sums a number hands the sums under `<name>_totals`, one\nentry per number the List draws as a column or as the table\'s figure. A `where` bound may be `{ "record": "<field>" }`,\na date or number the record itself holds, so a record can print a window of its own days. A service plan row (customer,\n`period_start`, `period_end`) draws the customer\'s visits within its period:\n\n```\n{ "type": "List", "key": "visits", "entity": "visit", "same": "customer", "label": "Visits", "columns": ["visited_on", "hours"],\n "where": { "visited_on": { "gte": { "record": "period_start" }, "lte": { "record": "period_end" } } } }\n```\n\n```html\n{{#each visits}}<p>{{visited_on}} \u2014 {{hours}} h</p>{{/each}}\n<p>Total {{visits_totals.hours}} h</p>\n```\n\nA bound the record leaves blank, or holds as anything but one whole day (`2026-05`) or one figure, keeps no row:\n`visits` is empty and `visits_totals.hours` is `0`. The sums add a number as the List\'s foot does: a cell holding a\nfigure adds it, any other cell (blank, an errored formula, a lookup\'s list) adds nothing. A Word template loops\n`{{FOR v IN visits}}` and prints `{{visits_totals.hours}}` the same way. A template that names a List narrowed to the\nreader (`"me"`) is refused, and so is a name a rows List and a `list` List both reach: give the `list` a `key`. A record\nbound narrows what is listed and is never an access bound; the table\'s row rules are.\n\nA List that reads by a path (`via: "<link>.<link>"`) hands its rows the same way. A List the screen draws as an outline (a record\'s own\nsub-rows, in a table whose rows nest, with no `where`, total, group, long-text column or other narrowing) hands every sub-row, depth first, each after the row it is filed under and its\nsiblings in the List\'s order, with its depth as `level` (1 for the rows filed under the record): `{{#each tasks}}{{level}} {{name}}{{/each}}`.\nA paper that lists an outline whose table has a field named `level` is refused. Inside a listed row a link arrives as the\ntitles of its rows (`{{#each marks}}{{this}}{{/each}}` prints them), so a loop there printing a field of each item is\nrefused, naming the key a List hands those rows under; so is one drawing a table cell per title, which lines up with no\ncolumn \u2014 a grid of rows by days is a roster\'s Export (below). A Word template is read for this when it is next saved.\n\nA paper made over several rows (`on: "ticked"` or `"view"`, at most 200) is one file of them all: the rows arrive under the entity\'s alias. An html paper hands each row the child rows the record\'s paper would be handed, under the same names, with their `_totals`; an Excel or Word paper is handed the rows alone. The page the rows open draws those Lists:\n\n```html\n{{#each supplier_order}}<h2>{{code}}</h2>{{#each sources}}<p>{{description}} \xD7 {{quantity}}</p>{{/each}}{{/each}}\n```\n\nA paper over many rows (a client\'s month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act\'s `template`; or a List `Export` with `template` and `per` (`reference/export-node`).\n`reference/groups-and-templates` has the rest.\n\nA roster\'s `Export` (an html or Excel `template`) is handed its grid over the window in view: `columns`, the days\nholding a row in the file (with `expect`, every option), each a `label`, its `date` and `weekday`; and on each row (under the List\'s entity alias, `student` here)\n`cells`, a word per column \u2014 each of its rows\' mark, the option\'s `short` else its label (a row with no state, its title), joined by `, ` \u2014\n`counts`, how many of its rows stand at each option by alias (`held`, at none), and `total`, as the roster reads it (its owed or expected ratio, else the sum of the row\'s figure, else the count of the cells it holds):\n\n```html\n<tr><th>Student</th>{{#each columns}}<th>{{label}}</th>{{/each}}<th>Absent</th></tr>\n{{#each student}}<tr><td>{{name}}</td>{{#each cells}}<td>{{this}}</td>{{/each}}<td>{{counts.absent}}</td></tr>{{/each}}\n```\n\n| | A | B | C | D | E |\n|---|---|---|---|---|---|\n| 1 | Student | `{{#each-col columns}}` | `{{label}}` | `{{/each-col}}` | Absent |\n| 2 | `{{#each student}}` | | | | |\n| 3 | `{{name}}` | | `{{cells \\| lookup:@index}}` | | `{{counts.absent}}` |\n| 4 | `{{/each}}` | | | | |\n\n## Discovering and managing templates\n\nThese tools work across all five types:\n\n| Tool | Does |\n|---|---|\n| `get_workspace` | list the workspace\'s templates (`kind: "template"`), each with its id, type and one line |\n| `get_template` | one template\'s full definition, incl. the `variables` it expects and the `current_version` a change needs |\n| `set_template` | create a template, change one, delete it (`delete: true` with `template_id`) or bring it back (`restore: true`); `dry_run: true` checks the call and stores nothing; a copy is `get_template` then `set_template` |\n\nCall `get_template` before generating when you don\'t already know a template\'s variable names.\n';
1920
1920
 
1921
1921
  // docs/knowledge_docs.md
1922
1922
  var knowledge_docs_default = '# Knowledge Docs\n\nKnowledge docs are the workspace\'s **rulebook layer** \u2014 the facts and rules an agent can\'t know on its own: a\nprocedure, a policy, a glossary of in-house terms, a tariff book. You write them once; the agent **searches and reads\nthem on demand** while it works, pulling in only the lines it needs. They are not injected wholesale, so a 10,000-line\ntariff costs nothing until a question touches it.\n\nA menu with its prices, the customer list and the open orders are not knowledge: they are rows of tables, so apps, queries and documents\ncan use them.\n\n## Rulebook, not methodology\n\nPut in a knowledge doc the things the model **cannot guess**: your specific numbers, codes, names, exceptions and\npolicies. Do **not** put in it general skills the model already has ("how to write a polite email"). If the agent would\nget it right without the doc, the doc is noise.\n\n## Writing a doc \u2014 `set_knowledge`\n\n`set_knowledge` creates a doc when it is given no `knowledge_doc_id` and changes the named one when it is given one:\n\n- `name` \u2014 what it is. Just the name: **grouping belongs in `tags`, not in a prefix baked into every title.**\n- `description` \u2014 what the doc is **and what to grep it for**: its vocabulary and the synonyms an ambiguous query would\n use. Surfaced in the listing before any body is read, and truncated at 200 characters.\n- `content` \u2014 Markdown.\n- `tags` *(optional)* \u2014 the labels someone would filter by, e.g. `["H\u1ED3 s\u01A1 NOXH", "Kho\u1EA3n 13"]`. Give **every** one that is\n true of the doc: a corpus is narrowed by intersecting tags, so a doc carrying one label is found down one path only.\n On a change the array **replaces** what is stored, so resend the labels it should keep.\n- `files` *(optional)* \u2014 file ids of the source `.docx`/`.pdf`/`.xlsx`, stored alongside so a reader can open the original.\n\nA change sends only the fields it changes. `edits` (anchored replace, insert, append) makes a surgical change to the\nbody. Refine structure as you learn what users ask: add the synonym that failed to match, split a line that was too\ncoarse, restate a term the heading was carrying.\n\nA new doc is **owned by you and private**. `set_access` shares it: `resources[]` with `resource_type` `knowledge_doc`, and `principals[]` (a\nmember, a member group, or `organization` for everyone), each with a `role` of `user` or `manager`; a principal without a `role` has\nits access taken away. A doc reaches an agent when the member can `use` it. An organization admin can use any doc, and their agent searches what they list unless it passes `all: true`.\n\n## How an agent uses a doc\n\nRetrieval works like a filesystem, and respects access: only docs the caller may use ever surface.\n\n1. **List and search** \u2014 `get_workspace` kind `knowledge` lists the corpus (id, name, tags, a truncated\n description); a search term matches a doc\'s name, description and tags. `get_workspace` with `search` finds where something is said: it\n matches across every readable doc and returns the **doc, line number and matching line**;\n `knowledge_doc_id` or `tag` confines the lines to one doc or to the docs carrying that tag.\n2. **Read** \u2014 `read_knowledge`, a doc whole or by line range, to see the context around a hit.\n\nMatching is **not ranked**: the *agent* does the narrowing. A distinctive phrase is sharply selective, a whole question\nmatches everything. A search always reports `total_matches`, so "too broad" is visible and cheap to fix.\n\nThe `search` is **literal text** \u2014 every character matches itself. Set `regex: true` to read it as a POSIX regular\nexpression (a word boundary is `\\y`, not `\\b`):\n\n```\n{ "search": "C/O (Form E)", "kind": "knowledge" }\n{ "search": "\\\\yNK\\\\y", "kind": "knowledge", "regex": true, "case_sensitive": true }\n```\n\nAs an expression `C/O (Form E)` would search for `C/O Form E`, which is not in the document, and return a confident\nzero; the literal default has no such failure. With `regex` omitted, a literal search that finds nothing while the\npattern, read as an expression, matches (`a|b`, the commonest) returns those lines under a note saying how they were\nread. `regex: false` keeps the literal zero; a search that finds nothing either\nway says so.\n\n- **Tone marks match exactly by default.** `diacritic_insensitive: true` folds them (`ca phe` matches `c\xE0 ph\xEA`); use it\n when the pattern was typed without them, since folding lets a short word match inside unrelated ones.\n- **Case folds by default.** `case_sensitive: true` matches exactly, for an acronym (`NK` vs `nk`).\n- **Whitespace is normalized on both sides.** Non-breaking spaces, soft hyphens and padded runs from PDF, Word or Excel\n bodies fold to single spaces before matching.\n\nA search shows at most 16,000 characters, shared by what it finds in knowledge, in structure and in records. Matched\nlines are admitted first and context fills what remains; anything cut is reported, with the true number of matching\nlines. Lines longer than 600 characters are clipped and marked; `read_knowledge` gives the rest.\n\n## Write for grep\n\nRetrieval addresses **lines**. Every rule follows from that one fact.\n\n- **One self-contained fact per line.** A hit returns *that line*. For dense or tabular data \u2014 a price row, a tariff\n code \u2014 put the whole record on one line.\n- **Repeat the searchable terms on every line; headings do not carry down.** A line reading `Rate: 15%` under a heading\n `Roasted coffee` will never match a search for `coffee`. Restate the identifying terms inline, even when it reads\n redundantly to a human. This is the rule most often got wrong.\n- **Keep a line under ~600 characters,** the identifying terms early and the long tail late.\n- **Put synonyms and translations on the line itself.** A bilingual row (`C\xE0 ph\xEA, \u0111\xE3 rang / Coffee, roasted`) matches\n queries in either language.\n- **For prose, keep a rule and its exception close.** A rule on line 40 and its exception on line 90 can be retrieved apart.\n\nMarkdown headings carry no retrieval weight of their own; a doc\'s `##` headings outside its blocks, two or more, are\nlisted on its page as its sections.\n\nThe **description is the discovery hint**: it is the only clue for *what term to grep for* before a body is read. Name\nthe doc\'s vocabulary in a sentence.\n\n## Classifying a corpus \u2014 tags\n\nA doc carries a SET of labels, not a folder. Order does not matter, a doc can wear several, and the vocabulary is\nwhatever the docs themselves use. `tags` on `set_knowledge` states one doc\'s complete set.\n\n## Deleting and restoring\n\n`set_knowledge` with a `knowledge_doc_id` and `delete: true` deletes a doc: it leaves every listing, search and read. **Its sharing and version history are\nkept**, so a deleted doc is recoverable. `get_workspace` kind `knowledge` with `include_archived: true` lists the deleted\ndocs you manage, and `set_knowledge` with `restore: true` brings one back with the access it had. Each call takes one doc,\nwhich must be one you manage. A doc with no owner is restored only by an admin, who\nbecomes its owner. A doc that an app or workflow still names cannot be deleted.\n\n## Formatting \u2014 what a doc draws\n\nA doc is markdown with GFM tables. Beyond that it draws a few blocks, each in syntax you already write; the platform draws them in its own style, so every doc looks alike.\n\n| Write | Draws |\n|---|---|\n| `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` opening a blockquote | a callout in that tone |\n| `<Note>`, `<Info>`, `<Tip>`, `<Check>`, `<Warning>`, `<Danger>` | the same callouts |\n| a ```mermaid fence | a diagram: flowchart, sequence, timeline, gantt, `pie`, `xychart-beta`, `quadrantChart` (a 2x2; quadrant-1, top right, is drawn as the target), in the platform\'s theme; a flowchart\'s or a 2x2\'s own colour statements are dropped |\n| `<Steps>` holding `<Step title="\u2026">` | a numbered walk |\n| `<Tabs>` holding `<Tab title="\u2026">` | switchable panels |\n| `<Columns cols={2}>` (or `<CardGroup>`) holding `<Card title="\u2026" href="\u2026" icon="\u2026">` | side-by-side cards that stack on a phone; `icon` is a glyph from the model reference (a select option\'s mark), and a name it lacks is refused with the nearest |\n| a table whose header cells are all empty | a table with no header row (a key/value table) |\n| `<Accordion title="\u2026">`, `<AccordionGroup>`, or `<details>` with a one-line `<summary>\u2026</summary>` | a section that opens on press |\n\nEach tag stands on a line of its own, and a tag line inside a fenced code block is code. Attributes are text in double quotes or a number in braces; nothing in a tag runs. A write that adds a tag that does not close, nests wrongly, carries an attribute the tag does not take, or names a component this list lacks (`<Frame>`, `<CodeGroup>`) is refused with the lines to fix; lowercase HTML (`<br>`) stays text.\n\nA chart\'s numbers live in its mermaid source, which agents read and grep like any text: write them there once, not again in a table.\n';
@@ -192,6 +192,8 @@ run_app_workflow {"app_id":"app_…","runs":[
192
192
  ]}
193
193
  ```
194
194
 
195
+ A run that makes a paper answers it under `files`, as an export does: `file_id`, `url`, `filename`, `mime_type`; a dry run keeps none.
196
+
195
197
  An act that reads papers (`intake`) is read by the caller: no platform agent reads for it. Its save `act_<alias>` takes `fields` (what the papers state), `rows` (the child rows listed) and `papers` (`[{"file":"fil_…","kind":"<option>"}]`), and `dry_run` shows the record and rows it would make.
196
198
 
197
199
  ## A dry run
@@ -31,7 +31,7 @@ office file and mark it up; **inline** (`html`, `email`) store the markup you au
31
31
  It substitutes the markers and returns a **generated file** (with a `file_id`).
32
32
  3. **Chain** the result — generation only *produces* the file. Attaching it to a record,
33
33
  sending it, or saving it is a separate step: `update_records` with `add_to` on a files field
34
- files the `file_id` on a record (`remove_made`, a template id, takes out the paper that template
34
+ files the `file_id` on a record (`remove_made`, a template's id or alias, takes out the paper that template
35
35
  made earlier); over MCP and on the CLI, `download_file` fetches it; inside a workflow, pass the `file_id` to the next
36
36
  step. A paper an app makes is its Act's `template`, which files it on the record itself
37
37
  (below).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.321.75",
3
+ "version": "0.321.76",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {