@lotics/cli 0.284.2 → 0.284.3

package/AGENTS.md

@@ -30,8 +30,8 @@ conventions are, and where the traps are.
 - **Tools** (`lotics tools`, `lotics run <tool>`) — the *agent tool registry*: what an agent, workflow,
   or automation may call. Workspace data, templates, knowledge, admin.
 - **Commands** (`lotics --help` § COMMANDS) — the CLI's *own verbs*: auth and org/workspace scoping,
-  file upload and download, and the four that touch a local file for an app — `model apply`,
-  `model pull`, `app create --custom` and `app deploy`.
+  file upload and download, and the five that touch a local file for an app — `model apply`,
+  `model pull`, `app create --custom`, `app pull` and `app deploy`.
 
 Several capabilities exist **only** as commands and appear nowhere in `lotics tools` — downloading a
 file is the one most often mistaken for missing. Concluding "the platform can't do X" from the tool

package/README.md

@@ -305,6 +305,7 @@ lotics app create "Sales Desk" --custom    # the app, plus a Vite + React + TS p
 cd "Sales Desk"
 npm run typecheck && npm run lint && npm test
 lotics app deploy -m "Add quote drawer"    # build + upload a new version of the live app
+lotics app pull                            # in the project: bring it up to the live version (refused while it has edits)
 
 # What the app reads and writes is bound on the app, and each change mints a version:
 lotics run set_app_queries '{"app_id":"app_...","queries":{"openInvoices":{...}}}'

package/dist/src/cli.js

@@ -22011,13 +22011,13 @@ var fileUploadResponseSchema = zod_default.object({
 var fileFieldValueSchema = zod_default.object({
   id: zod_default.string().describe("Unique identifier for the file"),
   /**
-   * Present on a STORED cell and on its way off responses.
+   * Present on a cell drawn from its `files` row and on its way off responses.
    *
    * Optional here because this schema types both, and a response is the half
    * that loses it — no client reads it, and one that required it would reject
    * the first response without it. Nothing weakens at write time: a file cell
-   * is written from file IDS and `resolveFileFieldIds` mints this from the
-   * `files` row, so a caller never supplies it and a stored cell always has it.
+   * stores ids alone and `toWireFileCell` mints this from the `files` row, so a
+   * caller never supplies it.
    * Code that derives a serving URL guards for it (`file_url_resolver.ts`).
    */
   file_storage_key: zod_default.string().optional().describe("Storage key for the file"),
@@ -41636,8 +41636,8 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.284.2";
-var APP_SDK_VERSION = "0.111.3";
+var VERSION = "0.284.3";
+var APP_SDK_VERSION = "0.111.4";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -41662,13 +41662,13 @@ var model_reference_default = '# The Lotics workspace model (`model.json`)\n\nOn
 var examples_default = '# Worked examples\n\nEach section is one treatment, cut from a complete model of an invented business: the job, the keys to\nread, where the treatment is wrong, and the excerpt \u2014 an app the check passes with no finding, as stated;\nthe `records` of every entity it draws; those entities\' fields it names, by what each holds and how it is\ndrawn; and the templates it makes. Left out: labels, descriptions, `required`, `unique`, `default`, a link\'s\npairing, how a computed field computes, and template contents. Choosing among them: the `design` reference.\nEvery key: the `model` reference, at the pages each section names under **Keys**.\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.** `register.layout: "calendar"`; each visit stands over its span because its `records` line holds two dates (`scheduled_for`, `ends_at`).\n\n**Keys.** `model/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```json\n{\n  "entities": [\n    {\n      "alias": "service_visit",\n      "fields": [\n        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "scheduled_for", "type": "date", "format": "datetime"},\n        {"alias": "ends_at", "type": "date", "format": "datetime"},\n        {"alias": "engineer", "type": "select_record_link", "target_entity": "engineer", "cardinality": "one"},\n        {\n          "alias": "job",\n          "type": "select",\n          "options": [{"alias": "inspection", "color": "sky"}, {"alias": "repair", "color": "orange"}]\n        },\n        {"alias": "booked_on", "type": "date"},\n        {"alias": "parts_ready_on", "type": "date"},\n        {"alias": "arrived_on", "type": "date"},\n        {"alias": "hours", "type": "number", "format": "number", "unit": "h"},\n        {"alias": "report", "type": "text", "format": "markdown"},\n        {"alias": "completed_on", "type": "date"}\n      ]\n    }\n  ],\n  "records": {\n    "service_visit": {\n      "title": "customer",\n      "subtitle": ["scheduled_for", "ends_at"],\n      "status": {\n        "milestones": ["booked_on", {"field": "parts_ready_on", "when": {"job": ["repair"]}}, "arrived_on", "completed_on"],\n        "closed": ["completed_on"]\n      },\n      "figure": "hours",\n      "due": ["scheduled_for"]\n    }\n  },\n  "apps": [\n    {\n      "alias": "visits",\n      "name": "Service visits",\n      "description": "Engineers\' visits to customers on site, booked and completed by the day.",\n      "icon": "calendar",\n      "entity": "service_visit",\n      "register": {\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        "readings": [\n          {"metric": "service_visit", "where": {"job": ["repair"]}, "label": "Repairs"},\n          {"breakdown": "service_visit", "by": "engineer", "value": "hours"}\n        ]\n      },\n      "record": {\n        "sections": [\n          {"title": "Visit", "at": ["booked_on", "parts_ready_on"], "fields": ["job"], "acts": ["reschedule"]},\n          {"title": "Report", "at": ["arrived_on"], "fields": ["engineer", "report"], "acts": ["complete"]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "complete",\n          "label": "Complete visit",\n          "requires": ["engineer"],\n          "asks": ["hours", {"input": "summary", "label": "What was done", "type": "long_text", "required": true}],\n          "set": {"report": "input:summary", "completed_on": "now"}\n        },\n        {"alias": "reschedule", "label": "Reschedule", "asks": ["scheduled_for", "ends_at"]}\n      ]\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.** `register.layout: "lanes"` with `lanes` naming the one-row link to the resource (the engineer); every engineer stands as a lane, empty or not.\n\n**Keys.** `model/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```json\n{\n  "entities": [\n    {\n      "alias": "service_visit",\n      "fields": [\n        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "scheduled_for", "type": "date", "format": "datetime"},\n        {"alias": "ends_at", "type": "date", "format": "datetime"},\n        {"alias": "engineer", "type": "select_record_link", "target_entity": "engineer", "cardinality": "one"},\n        {\n          "alias": "job",\n          "type": "select",\n          "options": [{"alias": "inspection", "color": "sky"}, {"alias": "repair", "color": "orange"}]\n        },\n        {"alias": "booked_on", "type": "date"},\n        {"alias": "parts_ready_on", "type": "date"},\n        {"alias": "arrived_on", "type": "date"},\n        {"alias": "hours", "type": "number", "format": "number", "unit": "h"},\n        {"alias": "completed_on", "type": "date"}\n      ]\n    },\n    {\n      "alias": "engineer",\n      "fields": [\n        {"alias": "name", "type": "text"},\n        {"alias": "base", "type": "select_record_link", "target_entity": "warehouse", "cardinality": "one"}\n      ]\n    }\n  ],\n  "records": {\n    "service_visit": {\n      "title": "customer",\n      "subtitle": ["scheduled_for", "ends_at"],\n      "status": {\n        "milestones": ["booked_on", {"field": "parts_ready_on", "when": {"job": ["repair"]}}, "arrived_on", "completed_on"],\n        "closed": ["completed_on"]\n      },\n      "figure": "hours",\n      "due": ["scheduled_for"]\n    },\n    "engineer": {"title": "name", "subtitle": ["base"], "party": "person"}\n  },\n  "apps": [\n    {\n      "alias": "dispatch",\n      "name": "Dispatch",\n      "description": "Each engineer\'s visits across the day, and the free time between them to book into.",\n      "icon": "wrench",\n      "entity": "service_visit",\n      "register": {\n        "columns": ["job"],\n        "search": ["customer"],\n        "layout": "lanes",\n        "lanes": "engineer",\n        "create": ["customer", "job"]\n      },\n      "record": {"door": "drawer", "sections": [{"title": "Booking", "fields": ["engineer", "job"]}]}\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.** `register.layout: "gantt"` and `register.gantt.start`; with no end stated, the bar ends at the entity\'s first `due`.\n\n**Keys.** `model/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```json\n{\n  "entities": [\n    {\n      "alias": "phieu_thue",\n      "fields": [\n        {\n          "alias": "khach_hang",\n          "type": "select_record_link",\n          "target_entity": "khach_hang",\n          "cardinality": "one"\n        },\n        {"alias": "so_phieu", "type": "text"},\n        {\n          "alias": "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        {"alias": "phu_trach", "type": "select_member"},\n        {"alias": "ngay_giao", "type": "date"},\n        {"alias": "han_tra", "type": "date"},\n        {"alias": "ngay_tra", "type": "date"},\n        {\n          "alias": "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        {"alias": "so_ngay", "type": "formula"},\n        {"alias": "tong_tien", "type": "rollup"}\n      ]\n    }\n  ],\n  "records": {\n    "phieu_thue": {\n      "title": "khach_hang",\n      "subtitle": ["so_phieu"],\n      "status": {"field": "trang_thai", "closed": ["da_tra", "huy"], "history": "lich_su_phieu"},\n      "figure": "tong_tien",\n      "due": ["han_tra"]\n    }\n  },\n  "apps": [\n    {\n      "alias": "tien_do_thue",\n      "name": "Ti\u1EBFn \u0111\u1ED9 cho thu\xEA",\n      "description": "M\u1ED7i phi\u1EBFu thu\xEA m\u1ED9t thanh t\u1EEB ng\xE0y giao m\xE1y \u0111\u1EBFn h\u1EA1n tr\u1EA3, \u0111\u1ECDc theo h\xF4m nay: phi\u1EBFu n\xE0o s\u1EAFp \u0111\u1EBFn h\u1EA1n, phi\u1EBFu n\xE0o qu\xE1 h\u1EA1n; k\xE9o thanh \u0111\u1EC3 d\u1EDDi ng\xE0y giao ho\u1EB7c gia h\u1EA1n tr\u1EA3, v\xE0 nh\u1EADn m\xE1y v\u1EC1 khi kh\xE1ch tr\u1EA3.",\n      "icon": "calendar-range",\n      "theme": {"color": "teal"},\n      "entity": "phieu_thue",\n      "register": {\n        "columns": ["phu_trach"],\n        "filters": ["phu_trach", "khach_hang"],\n        "layout": "gantt",\n        "gantt": {"start": "ngay_giao"},\n        "remove": false,\n        "create": false,\n        "readings": [\n          {"metric": "phieu_thue", "where": {"trang_thai": ["dang_thue"]}, "label": "Phi\u1EBFu \u0111ang cho thu\xEA"},\n          {\n            "metric": "phieu_thue",\n            "value": "tong_tien",\n            "where": {"trang_thai": ["dang_thue"]},\n            "label": "Ti\u1EC1n thu\xEA \u0111ang ch\u1EA1y"\n          }\n        ]\n      },\n      "record": {\n        "sections": [\n          {"title": "Phi\u1EBFu thu\xEA", "fields": ["ngay_giao", "han_tra"]},\n          {"title": "\u0110ang thu\xEA", "at": ["dang_thue"], "fields": ["so_ngay", "ngay_tra"], "acts": ["nhan_tra"]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "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", "ngay_tra": "now"},\n          "confirm": true\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.** `register.layout: "roster"` over the people; `register.roster` names the child whose rows fill the days \u2014 one link back and a date on its line.\n\n**Keys.** `model/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  "entities": [\n    {\n      "alias": "nha_si",\n      "fields": [\n        {"alias": "ho_ten", "type": "text"},\n        {\n          "alias": "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        {"alias": "dien_thoai", "type": "text"}\n      ]\n    },\n    {\n      "alias": "lich_truc",\n      "fields": [\n        {"alias": "nha_si", "type": "select_record_link", "target_entity": "nha_si", "cardinality": "one"},\n        {\n          "alias": "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        {"alias": "ngay", "type": "date"},\n        {"alias": "ghe", "type": "select_record_link", "target_entity": "ghe", "cardinality": "one"}\n      ]\n    }\n  ],\n  "records": {\n    "nha_si": {"title": "ho_ten", "subtitle": ["chuyen_mon"], "party": "person"},\n    "lich_truc": {"title": "ca", "subtitle": ["ngay", "ghe"]}\n  },\n  "apps": [\n    {\n      "alias": "lich_truc",\n      "name": "L\u1ECBch tr\u1EF1c",\n      "description": "Ai tr\u1EF1c ca n\xE0o, \u1EDF gh\u1EBF n\xE0o, trong tu\u1EA7n v\xE0 trong th\xE1ng.",\n      "icon": "users",\n      "entity": "nha_si",\n      "register": {\n        "filters": ["chuyen_mon"],\n        "layout": "roster",\n        "roster": "lich_truc",\n        "create": ["ho_ten", "chuyen_mon", "dien_thoai"]\n      }\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.** `register.layout: "cards"` over rows whose `records.image` is a photo; `scope` keeps the app inside one warehouse at a time.\n\n**Keys.** `model/cards`, `model/records`, `model/apps`\n\n**Not when.** Rows with no picture \u2014 cards of words are a table drawn worse.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "stock_item",\n      "fields": [\n        {"alias": "name", "type": "text"},\n        {\n          "alias": "warehouse",\n          "type": "select_record_link",\n          "target_entity": "warehouse",\n          "cardinality": "one"\n        },\n        {"alias": "photo", "type": "files"},\n        {"alias": "sku", "type": "text"},\n        {\n          "alias": "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        {"alias": "on_hand", "type": "number"},\n        {"alias": "minimum", "type": "number"},\n        {"alias": "price", "type": "number", "format": "currency", "currency": "USD"},\n        {"alias": "supplier_page", "type": "text", "format": "link"},\n        {"alias": "last_counted", "type": "date"},\n        {"alias": "counted_by", "type": "select_member"},\n        {"alias": "count_note", "type": "text"}\n      ]\n    },\n    {\n      "alias": "order_line",\n      "fields": [\n        {"alias": "item", "type": "select_record_link", "target_entity": "stock_item", "cardinality": "one"},\n        {"alias": "order", "type": "select_record_link", "target_entity": "order", "cardinality": "one"},\n        {"alias": "quantity", "type": "number"},\n        {"alias": "shipped", "type": "number"},\n        {"alias": "picked", "type": "number"},\n        {"alias": "unit_price", "type": "number", "format": "currency", "currency": "USD"},\n        {"alias": "amount", "type": "formula"},\n        {"alias": "category", "type": "lookup"}\n      ]\n    }\n  ],\n  "records": {\n    "stock_item": {\n      "title": "name",\n      "subtitle": ["sku", "category"],\n      "image": "photo",\n      "figure": "on_hand",\n      "limits": {"on_hand": 400},\n      "gates": {"on_hand": "minimum"}\n    },\n    "order_line": {\n      "title": "item",\n      "subtitle": ["order", "unit_price"],\n      "figure": "amount",\n      "limits": {"shipped": "quantity", "picked": "quantity"}\n    }\n  },\n  "apps": [\n    {\n      "alias": "stock",\n      "name": "Stock",\n      "description": "What the store holds of each item, against its shelf and its minimum.",\n      "icon": "boxes",\n      "theme": {"color": "teal"},\n      "entity": "stock_item",\n      "scope": "warehouse",\n      "register": {\n        "columns": ["price"],\n        "filters": ["on_hand"],\n        "search": ["name", "sku"],\n        "layout": "cards",\n        "create": false,\n        "export": true,\n        "readings": [{"breakdown": "stock_item", "by": "category", "value": "on_hand"}]\n      },\n      "record": {\n        "sections": [\n          {"title": "Item", "fields": ["price", "minimum", "supplier_page"]},\n          {"title": "Last count", "fields": ["last_counted", "counted_by", "count_note"], "acts": ["count"]},\n          {"title": "On order", "blocks": [{"rows": "order_line", "columns": ["quantity"]}]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "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",\n            "counted_by": "me",\n            "count_note": "input:remark"\n          }\n        }\n      ]\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 `timeline` of touches, a `trend` of its orders, and its papers `expect`ed by kind.\n\n**Keys.** `model/records`, `model/blocks`, `model/reading-blocks`\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```json\n{\n  "entities": [\n    {\n      "alias": "customer",\n      "fields": [\n        {"alias": "name", "type": "text"},\n        {"alias": "logo", "type": "files"},\n        {"alias": "code", "type": "text"},\n        {\n          "alias": "tier",\n          "type": "select",\n          "options": [\n            {"alias": "key", "color": "violet"},\n            {"alias": "standard", "color": "sky"},\n            {"alias": "lapsed", "color": "gray"}\n          ]\n        },\n        {"alias": "phone", "type": "text"},\n        {"alias": "website", "type": "text", "format": "link"},\n        {"alias": "account_manager", "type": "select_member"},\n        {"alias": "credit_limit", "type": "number", "format": "currency", "currency": "USD"},\n        {"alias": "outstanding", "type": "rollup"},\n        {"alias": "over_limit", "type": "formula"},\n        {\n          "alias": "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        {"alias": "notes", "type": "text", "format": "markdown"}\n      ]\n    },\n    {\n      "alias": "order",\n      "fields": [\n        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "reference", "type": "text"},\n        {\n          "alias": "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": "delivered", "color": "green"},\n            {"alias": "cancelled", "color": "rose"}\n          ]\n        },\n        {"alias": "placed", "type": "date"},\n        {"alias": "due_date", "type": "date"},\n        {"alias": "total", "type": "rollup"},\n        {"alias": "units_ordered", "type": "rollup"},\n        {"alias": "units_shipped", "type": "rollup"},\n        {"alias": "units_picked", "type": "rollup"},\n        {"alias": "notes", "type": "text", "format": "markdown"}\n      ]\n    },\n    {\n      "alias": "customer_paper",\n      "fields": [\n        {\n          "alias": "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        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "received_on", "type": "date"},\n        {"alias": "file", "type": "files"}\n      ]\n    },\n    {\n      "alias": "touch",\n      "fields": [\n        {"alias": "said", "type": "text"},\n        {"alias": "customer", "type": "select_record_link", "target_entity": "customer", "cardinality": "one"},\n        {"alias": "by", "type": "select_member"}\n      ]\n    }\n  ],\n  "records": {\n    "customer": {\n      "title": "name",\n      "subtitle": ["tier"],\n      "image": "logo",\n      "party": "organization",\n      "figure": "outstanding",\n      "limits": {"outstanding": "credit_limit"}\n    },\n    "order": {\n      "title": "reference",\n      "subtitle": ["customer", "placed"],\n      "status": {"field": "stage", "closed": ["delivered", "cancelled"], "history": "order_stage"},\n      "figure": "total",\n      "limits": {"units_shipped": "units_ordered", "units_picked": "units_ordered"},\n      "due": ["due_date"]\n    },\n    "customer_paper": {"title": "kind", "image": "file"},\n    "touch": {"title": "said"}\n  },\n  "apps": [\n    {\n      "alias": "customers",\n      "name": "Customers",\n      "description": "Who we sell to, what they owe, and what was said.",\n      "icon": "users",\n      "theme": {"color": "violet"},\n      "entity": "customer",\n      "reads": "shared",\n      "register": {\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        "readings": [\n          {"breakdown": "customer", "by": "tier", "value": "outstanding"},\n          {"breakdown": "customer", "by": "account_manager", "value": "outstanding"}\n        ]\n      },\n      "record": {\n        "door": "drawer",\n        "sections": [\n          {"title": "Contact", "fields": ["phone", "website"]},\n          {\n            "title": "Account",\n            "fields": ["code", "account_manager", "credit_limit"],\n            "acts": ["reassign", "lapse", "reinstate"]\n          },\n          {\n            "title": "Orders",\n            "blocks": [\n              {\n                "trend": "order",\n                "over": "placed",\n                "value": "total",\n                "where": {"stage": ["confirmed", "picking", "shipped", "delivered"]},\n                "label": "Order value"\n              },\n              {\n                "rows": "order",\n                "via": "customer",\n                "title": "Open orders",\n                "columns": ["due_date"],\n                "create": false,\n                "where": {"stage": ["draft", "confirmed", "picking", "shipped"]}\n              }\n            ]\n          },\n          {\n            "title": "Account papers",\n            "blocks": [\n              {\n                "rows": "customer_paper",\n                "via": "customer",\n                "columns": ["received_on"],\n                "expect": "kind",\n                "of": "papers_needed"\n              }\n            ]\n          },\n          {"title": "Contact log", "blocks": [{"timeline": "touch", "via": "customer"}]},\n          {"title": "Notes", "blocks": [{"text": "notes"}]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "lapse",\n          "label": "Mark lapsed",\n          "when": {"tier": ["key", "standard"]},\n          "set": {"tier": "lapsed"},\n          "confirm": true\n        },\n        {\n          "alias": "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                {"alias": "key", "label": "Key account", "color": "violet"},\n                {"alias": "standard", "label": "Standard", "color": "sky"}\n              ],\n              "required": true\n            }\n          ],\n          "set": {"tier": "input:back_to"}\n        },\n        {\n          "alias": "reassign",\n          "label": "Reassign",\n          "asks": [{"input": "to", "label": "Account manager", "type": "member", "required": true}],\n          "set": {"account_manager": "input:to"}\n        }\n      ],\n      "checks": [{"field": "over_limit"}]\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.** `expect` blocks 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.** `model/blocks`, `model/acts`\n\n**Not when.** A record that needs no papers, or one paper made once \u2014 a single `template` act.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "ho_so",\n      "fields": [\n        {\n          "alias": "khach_hang",\n          "type": "select_record_link",\n          "target_entity": "khach_hang",\n          "cardinality": "one"\n        },\n        {"alias": "du_an", "type": "select_record_link", "target_entity": "du_an", "cardinality": "one"},\n        {"alias": "ma_ho_so", "type": "autonumber"},\n        {\n          "alias": "dich_vu",\n          "type": "select",\n          "options": [{"alias": "tron_goi", "color": "blue"}, {"alias": "lam_ho_so", "color": "violet"}]\n        },\n        {\n          "alias": "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        {\n          "alias": "tinh_trang_nha_o",\n          "type": "select",\n          "options": [{"alias": "chua_co_nha", "color": "gray"}, {"alias": "nha_chat", "color": "orange"}]\n        },\n        {"alias": "giay_chung_nhan_so", "type": "text"},\n        {"alias": "dien_tich_nha", "type": "number"},\n        {"alias": "sale", "type": "select_member"},\n        {"alias": "xu_ly", "type": "select_member"},\n        {"alias": "can_bo_sung", "type": "boolean"},\n        {"alias": "phi_dich_vu", "type": "number", "format": "currency", "currency": "VND"},\n        {\n          "alias": "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        {"alias": "can_boc", "type": "text"},\n        {"alias": "hoa_hong_sale", "type": "number", "format": "currency", "currency": "VND"},\n        {"alias": "ngay_thu_phi", "type": "date"},\n        {"alias": "ngay_nhan_giay_to", "type": "date"},\n        {"alias": "ngay_lap_ho_so", "type": "date"},\n        {"alias": "ngay_nop_cdt", "type": "date"},\n        {"alias": "ngay_cdt_duyet", "type": "date"},\n        {"alias": "ngay_so_xd_duyet", "type": "date"},\n        {"alias": "ngay_boc_tham", "type": "date"},\n        {"alias": "ngay_ky_hdmb", "type": "date"},\n        {"alias": "ngay_ban_giao", "type": "date"},\n        {"alias": "bo_ho_so", "type": "files"},\n        {"alias": "hop_dong_mua_ban", "type": "files"},\n        {"alias": "giay_to", "type": "select_record_link", "target_entity": "giay_to", "cardinality": "many"},\n        {\n          "alias": "thanh_vien",\n          "type": "select_record_link",\n          "target_entity": "thanh_vien",\n          "cardinality": "many"\n        },\n        {\n          "alias": "phieu_thu",\n          "type": "select_record_link",\n          "target_entity": "phieu_thu",\n          "cardinality": "many"\n        },\n        {"alias": "dien_thoai", "type": "lookup"},\n        {"alias": "cccd", "type": "lookup"},\n        {"alias": "ngay_sinh", "type": "lookup"},\n        {"alias": "dia_chi", "type": "lookup"},\n        {"alias": "da_thu", "type": "rollup"},\n        {"alias": "chua_thu_phi", "type": "formula"},\n        {"alias": "con_no_phi", "type": "formula"},\n        {"alias": "vuot_thu_nhap", "type": "formula"},\n        {"alias": "da_hoan_tat", "type": "formula"}\n      ]\n    },\n    {\n      "alias": "thanh_vien",\n      "fields": [\n        {"alias": "ho_ten", "type": "text"},\n        {"alias": "ho_so", "type": "select_record_link", "target_entity": "ho_so", "cardinality": "one"},\n        {\n          "alias": "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        {"alias": "ngay_sinh", "type": "date"},\n        {"alias": "cccd", "type": "text"},\n        {"alias": "thu_nhap", "type": "number", "format": "currency", "currency": "VND"}\n      ]\n    },\n    {\n      "alias": "phieu_thu",\n      "fields": [\n        {\n          "alias": "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        {"alias": "ho_so", "type": "select_record_link", "target_entity": "ho_so", "cardinality": "one"},\n        {"alias": "so_tien", "type": "number", "format": "currency", "currency": "VND"},\n        {\n          "alias": "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        {\n          "alias": "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        {"alias": "ngay_thu", "type": "date"},\n        {"alias": "nguoi_thu", "type": "select_member"},\n        {"alias": "da_chot", "type": "formula"}\n      ]\n    },\n    {\n      "alias": "giay_to",\n      "fields": [\n        {\n          "alias": "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        {"alias": "ho_so", "type": "select_record_link", "target_entity": "ho_so", "cardinality": "one"},\n        {"alias": "ngay_nhan", "type": "date"},\n        {"alias": "can_sua", "type": "text"},\n        {"alias": "tep", "type": "files"},\n        {"alias": "phai_sua", "type": "formula"}\n      ]\n    }\n  ],\n  "records": {\n    "ho_so": {\n      "title": "khach_hang",\n      "subtitle": ["dich_vu"],\n      "status": {\n        "milestones": [\n          {"field": "ngay_thu_phi", "when": {"dich_vu": ["lam_ho_so"]}},\n          "ngay_nhan_giay_to",\n          {"field": "ngay_lap_ho_so", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_nop_cdt", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_cdt_duyet", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_so_xd_duyet", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_boc_tham", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_ky_hdmb", "when": {"dich_vu": ["tron_goi"]}},\n          {"field": "ngay_ban_giao", "when": {"dich_vu": ["lam_ho_so"]}}\n        ],\n        "closed": ["ngay_ky_hdmb", "ngay_ban_giao"]\n      },\n      "figure": "phi_dich_vu"\n    },\n    "thanh_vien": {"title": "ho_ten", "subtitle": ["quan_he", "cccd"], "party": "person", "figure": "thu_nhap"},\n    "phieu_thu": {\n      "title": "khoan",\n      "subtitle": ["hinh_thuc", "ngay_thu"],\n      "status": {"field": "trang_thai", "closed": ["da_thu", "huy"]},\n      "figure": "so_tien"\n    },\n    "giay_to": {"title": "loai", "image": "tep", "starts": {"ngay_nhan": "today"}}\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  "apps": [\n    {\n      "alias": "ho_so",\n      "name": "H\u1ED3 s\u01A1 nh\xE0 \u1EDF x\xE3 h\u1ED9i",\n      "description": "B\xE0n l\xE0m h\u1ED3 s\u01A1 c\u1EE7a t\u1EEBng d\u1EF1 \xE1n: nh\u1EADn gi\u1EA5y t\u1EDD, l\u1EADp v\xE0 n\u1ED9p h\u1ED3 s\u01A1 cho ch\u1EE7 \u0111\u1EA7u t\u01B0, theo t\u1EEBng kh\xE2u duy\u1EC7t t\u1EDBi b\u1ED1c th\u0103m v\xE0 k\xFD h\u1EE3p \u0111\u1ED3ng \u2014 ho\u1EB7c l\xE0m h\u1ED3 s\u01A1 r\u1ED3i b\xE0n giao cho kh\xE1ch t\u1EF1 n\u1ED9p.",\n      "icon": "folder-open",\n      "theme": {"color": "blue"},\n      "entity": "ho_so",\n      "scope": "du_an",\n      "register": {\n        "columns": ["xu_ly", "can_bo_sung", "doi_tuong"],\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        "export": true,\n        "readings": [\n          {"metric": "ho_so", "where": {"can_bo_sung": true}, "label": "Ch\u1EDD kh\xE1ch b\u1ED5 sung"},\n          {"metric": "ho_so", "value": "da_thu", "over": "ngay_nhan_giay_to", "label": "Ph\xED \u0111\xE3 thu"},\n          {"breakdown": "ho_so", "by": "doi_tuong"}\n        ]\n      },\n      "record": {\n        "sections": [\n          {\n            "title": "Ng\u01B0\u1EDDi \u0111\u1EE9ng \u0111\u01A1n",\n            "fields": [\n              "ma_ho_so",\n              "dien_thoai",\n              "cccd",\n              "ngay_sinh",\n              "dia_chi",\n              "doi_tuong",\n              "tinh_trang_nha_o",\n              "sale",\n              "xu_ly",\n              "can_bo_sung"\n            ],\n            "blocks": [\n              {\n                "rows": "thanh_vien",\n                "title": "H\u1ED9 gia \u0111\xECnh",\n                "columns": ["ngay_sinh"],\n                "create": ["ho_ten", "quan_he", "ngay_sinh", "cccd", "thu_nhap"]\n              }\n            ],\n            "acts": ["doc_giay_to", "giao_xu_ly", "chuyen_du_an"]\n          },\n          {\n            "title": "Nh\xE0 hi\u1EC7n c\xF3",\n            "fields": ["giay_chung_nhan_so", "dien_tich_nha"],\n            "when": {"tinh_trang_nha_o": ["nha_chat"]}\n          },\n          {\n            "title": "Ph\xED d\u1ECBch v\u1EE5",\n            "blocks": [\n              {\n                "rows": "phieu_thu",\n                "title": "Phi\u1EBFu thu",\n                "columns": ["so_tien"],\n                "create": ["khoan", "so_tien", "hinh_thuc"],\n                "where": {"khoan": ["dat_coc", "tat_toan"]},\n                "expect": "khoan",\n                "when": {"dich_vu": ["tron_goi"]}\n              },\n              {\n                "rows": "phieu_thu",\n                "title": "Phi\u1EBFu thu",\n                "columns": ["so_tien"],\n                "create": ["khoan", "so_tien", "hinh_thuc"],\n                "where": {"khoan": ["phi_ho_so"]},\n                "expect": "khoan",\n                "when": {"dich_vu": ["lam_ho_so"]}\n              }\n            ]\n          },\n          {\n            "title": "Gi\u1EA5y t\u1EDD",\n            "at": ["ngay_thu_phi"],\n            "blocks": [\n              {\n                "rows": "giay_to",\n                "title": "Gi\u1EA5y t\u1EDD",\n                "columns": ["ngay_nhan"],\n                "create": ["loai", "ngay_nhan", "can_sua", "tep"],\n                "expect": "loai"\n              }\n            ]\n          },\n          {\n            "title": "B\u1ED9 h\u1ED3 s\u01A1",\n            "description": "C\xE1c m\u1EABu \u0111\u01A1n in t\u1EEB th\xF4ng tin c\u1EE7a h\u1ED3 s\u01A1.",\n            "at": ["ngay_nhan_giay_to", "ngay_lap_ho_so"],\n            "acts": ["tao_giay_to", "nop_cdt"]\n          },\n          {\n            "title": "Ch\u1EE7 \u0111\u1EA7u t\u01B0",\n            "description": "H\u1ED3 s\u01A1 tr\u1ECDn g\xF3i n\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0, ch\u1EDD ch\u1EE7 \u0111\u1EA7u t\u01B0 r\u1ED3i S\u1EDF X\xE2y d\u1EF1ng duy\u1EC7t tr\u01B0\u1EDBc ng\xE0y b\u1ED1c th\u0103m.",\n            "at": ["ngay_nop_cdt", "ngay_cdt_duyet", "ngay_so_xd_duyet"],\n            "fields": ["loai_can"],\n            "when": {"dich_vu": ["tron_goi"]}\n          },\n          {\n            "title": "C\u0103n h\u1ED9",\n            "at": ["ngay_boc_tham"],\n            "fields": ["can_boc", "hoa_hong_sale"],\n            "blocks": [{"files": ["hop_dong_mua_ban"]}],\n            "when": {"dich_vu": ["tron_goi"]}\n          }\n        ]\n      },\n      "acts": [\n        {\n          "alias": "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          "alias": "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            {"template": "mau_05_thu_nhap", "when": {"doi_tuong": ["thu_nhap_thap"]}}\n          ],\n          "into": "bo_ho_so"\n        },\n        {\n          "alias": "nop_cdt",\n          "label": "N\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0",\n          "when": {"dich_vu": ["tron_goi"]},\n          "requires": ["bo_ho_so", "loai_can"],\n          "asks": ["loai_can"],\n          "set": {"ngay_nop_cdt": "now"},\n          "confirm": true\n        },\n        {\n          "alias": "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          "alias": "chuyen_du_an",\n          "label": "Chuy\u1EC3n d\u1EF1 \xE1n",\n          "asks": [{"input": "du_an_moi", "label": "Sang d\u1EF1 \xE1n", "type": "link", "entity": "du_an", "required": true}],\n          "set": {"du_an": "input:du_an_moi"},\n          "confirm": true\n        },\n        {\n          "alias": "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          "alias": "xac_nhan_thu",\n          "label": "X\xE1c nh\u1EADn \u0111\xE3 thu",\n          "of": "phieu_thu",\n          "when": {"trang_thai": ["cho_thu"]},\n          "asks": ["hinh_thuc"],\n          "set": {"trang_thai": "da_thu", "ngay_thu": "now", "nguoi_thu": "me"},\n          "confirm": true\n        },\n        {\n          "alias": "huy_phieu",\n          "label": "H\u1EE7y phi\u1EBFu",\n          "of": "phieu_thu",\n          "when": {"trang_thai": ["cho_thu"]},\n          "set": {"trang_thai": "huy"},\n          "danger": true\n        }\n      ],\n      "checks": [\n        {"field": "chua_thu_phi", "blocks": ["nop_cdt"]},\n        {"field": "con_no_phi"},\n        {"field": "vuot_thu_nhap"},\n        {"field": "da_hoan_tat", "blocks": ["delete", "doc_giay_to"]},\n        {"field": "da_chot", "of": "phieu_thu", "blocks": ["edit"]},\n        {"field": "phai_sua", "of": "giay_to"}\n      ]\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.** `model/acts`, `model/blocks`\n\n**Not when.** Calls made and logged elsewhere \u2014 a `timeline` with its own add keeps the note.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "khach_tiem_nang",\n      "fields": [\n        {"alias": "ho_ten", "type": "text"},\n        {"alias": "ten_cong_ty", "type": "text"},\n        {\n          "alias": "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        {\n          "alias": "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        {\n          "alias": "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        {"alias": "so_dien_thoai", "type": "text"},\n        {"alias": "zalo", "type": "text"},\n        {"alias": "email", "type": "text"},\n        {"alias": "trang_ca_nhan", "type": "text", "format": "link"},\n        {"alias": "anh", "type": "files"},\n        {\n          "alias": "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        {\n          "alias": "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        {"alias": "vi_sao_du_dieu_kien", "type": "text"},\n        {"alias": "phu_trach", "type": "select_member"},\n        {"alias": "nguon", "type": "select_record_link", "target_entity": "kenh", "cardinality": "one"},\n        {"alias": "lien_he", "type": "select_record_link", "target_entity": "lien_he", "cardinality": "one"},\n        {"alias": "cong_ty", "type": "select_record_link", "target_entity": "cong_ty", "cardinality": "one"},\n        {"alias": "ngay_chuyen_doi", "type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n        {"alias": "ghi_chu", "type": "text", "format": "markdown"},\n        {"alias": "tin_hieu", "type": "select_record_link", "target_entity": "tin_hieu"},\n        {"alias": "buoc_tiep", "type": "select_record_link", "target_entity": "buoc_tiep"},\n        {"alias": "tuong_tac", "type": "select_record_link", "target_entity": "tuong_tac"},\n        {"alias": "tin_hieu_moi", "type": "lookup"},\n        {"alias": "do_nong", "type": "formula"},\n        {"alias": "han_buoc_tiep", "type": "rollup"},\n        {"alias": "khong_lien_he", "type": "formula"}\n      ]\n    },\n    {\n      "alias": "tin_hieu",\n      "fields": [\n        {"alias": "tom_tat", "type": "text"},\n        {"alias": "noi_dung", "type": "text", "format": "markdown"},\n        {"alias": "anh_chup", "type": "files"},\n        {"alias": "lien_ket", "type": "text", "format": "link"},\n        {"alias": "kenh", "type": "select_record_link", "target_entity": "kenh", "cardinality": "one"},\n        {\n          "alias": "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        {"alias": "ngay_dang", "type": "date", "timezone": "Asia/Ho_Chi_Minh"},\n        {"alias": "ngay_xay_ra", "type": "formula"}\n      ]\n    },\n    {\n      "alias": "buoc_tiep",\n      "fields": [\n        {"alias": "vi_sao_luc_nay", "type": "text"},\n        {\n          "alias": "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        {"alias": "ban_nhap", "type": "text", "format": "markdown"},\n        {"alias": "han", "type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n        {\n          "alias": "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    },\n    {\n      "alias": "tuong_tac",\n      "fields": [\n        {"alias": "tom_tat", "type": "text"},\n        {"alias": "thoi_diem", "type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n        {\n          "alias": "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        {\n          "alias": "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        {"alias": "ghi_am", "type": "files"},\n        {"alias": "nguyen_van", "type": "text", "format": "markdown"},\n        {"alias": "hen_lai", "type": "date", "timezone": "Asia/Ho_Chi_Minh"},\n        {"alias": "nguoi_thuc_hien", "type": "select_member"}\n      ]\n    }\n  ],\n  "records": {\n    "khach_tiem_nang": {\n      "title": "ho_ten",\n      "subtitle": ["ten_cong_ty"],\n      "image": "anh",\n      "party": "person",\n      "status": {"field": "trang_thai", "closed": ["da_chuyen_doi", "loai"], "history": "lich_su_trang_thai"},\n      "due": ["han_buoc_tiep"]\n    },\n    "tin_hieu": {"title": "tom_tat", "subtitle": ["kenh", "ngay_xay_ra"], "image": "anh_chup"},\n    "buoc_tiep": {\n      "title": "vi_sao_luc_nay",\n      "subtitle": ["viec"],\n      "status": {"field": "tinh_trang", "closed": ["xong", "bo_qua"]},\n      "due": ["han"]\n    },\n    "tuong_tac": {"title": "tom_tat", "subtitle": ["qua", "phan_hoi"]}\n  },\n  "apps": [\n    {\n      "alias": "khach_tiem_nang",\n      "name": "Kh\xE1ch ti\u1EC1m n\u0103ng",\n      "description": "M\u1ECDi ng\u01B0\u1EDDi m\xECnh c\xF3 th\u1EC3 b\xE1n d\u1ECBch v\u1EE5, t\u1EEB t\xEDn hi\u1EC7u \u0111\u1EA7u ti\xEAn \u0111\u1EBFn khi chuy\u1EC3n v\xE0o CRM: m\u1EDF m\u1ED9t kh\xE1ch \u0111\u1EC3 \u0111\u1ECDc v\xEC sao n\xEAn g\u1ECDi l\xFAc n\xE0y, li\xEAn h\u1EC7 ngay, ghi l\u1EA1i l\u1EA7n ch\u1EA1m, x\u1EBFp b\u01B0\u1EDBc ti\u1EBFp theo, v\xE0 chuy\u1EC3n \u0111\u1ED5i khi \u0111\xE3 c\xF3 cu\u1ED9c tr\xF2 chuy\u1EC7n.",\n      "icon": "radar",\n      "theme": {"color": "violet"},\n      "entity": "khach_tiem_nang",\n      "register": {\n        "columns": ["phu_trach", "han_buoc_tiep", "tin_hieu_moi"],\n        "filters": ["phu_trach", "tin_hieu_moi"],\n        "create": ["ho_ten", "trang_ca_nhan", "so_dien_thoai", "ten_cong_ty", "nguon"],\n        "readings": [\n          {"breakdown": "khach_tiem_nang", "by": "phu_trach"},\n          {"trend": "khach_tiem_nang", "over": "ngay_chuyen_doi", "label": "Kh\xE1ch chuy\u1EC3n \u0111\u1ED5i"}\n        ]\n      },\n      "record": {\n        "sections": [\n          {\n            "title": "\u0110\xE1nh gi\xE1",\n            "at": ["moi"],\n            "fields": ["vai_tro", "loai_hinh", "quy_mo", "vi_sao_du_dieu_kien", "do_nong"],\n            "blocks": [\n              {\n                "rows": "tin_hieu",\n                "title": "T\xEDn hi\u1EC7u",\n                "columns": ["loai", "noi_dung"],\n                "create": ["tom_tat", "anh_chup", "loai", "noi_dung", "kenh", "lien_ket", "ngay_dang"]\n              }\n            ],\n            "acts": ["danh_gia_dat"]\n          },\n          {\n            "title": "Li\xEAn h\u1EC7",\n            "at": ["du_dieu_kien"],\n            "fields": ["so_dien_thoai", "phu_trach", "trang_ca_nhan", "zalo", "email", "ghi_chu"],\n            "blocks": [\n              {\n                "rows": "buoc_tiep",\n                "title": "B\u01B0\u1EDBc ti\u1EBFp theo",\n                "columns": ["ban_nhap"],\n                "create": ["vi_sao_luc_nay", "viec", "han", "ban_nhap"]\n              },\n              {\n                "timeline": "tuong_tac",\n                "title": "T\u01B0\u01A1ng t\xE1c",\n                "create": ["tom_tat", "qua", "phan_hoi", "thoi_diem", "hen_lai"]\n              }\n            ],\n            "acts": ["ghi_cuoc_goi", "da_lien_he"]\n          },\n          {\n            "title": "Chuy\u1EC3n \u0111\u1ED5i",\n            "description": "Kh\xE1ch \u0111\xE3 tr\u1EA3 l\u1EDDi v\xE0 mu\u1ED1n \u0111i ti\u1EBFp: chuy\u1EC3n \u0111\u1ED5i t\u1EA1o li\xEAn h\u1EC7 v\xE0 c\xF4ng ty trong s\u1ED5 kh\xE1ch h\xE0ng.",\n            "at": ["da_lien_he"],\n            "fields": ["nguon", "lien_he", "cong_ty"],\n            "acts": ["chuyen_doi"]\n          },\n          {\n            "title": "Lo\u1EA1i",\n            "description": "Kh\xE1ch kh\xF4ng \u0111i ti\u1EBFp: ghi l\xFD do \u0111\u1EC3 l\u1EA7n sau kh\xF4ng t\xECm l\u1EA1i.",\n            "at": ["loai"],\n            "fields": ["ly_do_loai"],\n            "acts": ["loai"]\n          }\n        ]\n      },\n      "acts": [\n        {\n          "alias": "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          "alias": "ghi_cuoc_goi",\n          "label": "Ghi \xE2m cu\u1ED9c g\u1ECDi",\n          "when": {"trang_thai": ["du_dieu_kien"]},\n          "record": {\n            "into": "tuong_tac",\n            "audio": "ghi_am",\n            "transcript": "nguyen_van",\n            "at": "thoi_diem",\n            "by": "nguoi_thuc_hien"\n          },\n          "fills": ["tom_tat", "phan_hoi"]\n        },\n        {\n          "alias": "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          "alias": "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          "alias": "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          "alias": "lam_xong",\n          "label": "\u0110\xE3 l\xE0m",\n          "of": "buoc_tiep",\n          "when": {"tinh_trang": ["cho"]},\n          "set": {"tinh_trang": "xong"}\n        }\n      ],\n      "checks": [{"field": "khong_lien_he", "resolve": "da_lien_he"}]\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 `register.readings` leading with the headline number.\n\n**Keys.** `model/records`, `model/record-page`, `model/readings`\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```json\n{\n  "entities": [\n    {\n      "alias": "de_nghi",\n      "fields": [\n        {"alias": "noi_dung", "type": "text"},\n        {"alias": "so_de_nghi", "type": "text"},\n        {\n          "alias": "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        {"alias": "du_an", "type": "select_record_link", "target_entity": "du_an", "cardinality": "one"},\n        {\n          "alias": "nha_cung_cap",\n          "type": "select_record_link",\n          "target_entity": "nha_cung_cap",\n          "cardinality": "one"\n        },\n        {"alias": "so_tien", "type": "number", "format": "currency", "currency": "VND"},\n        {"alias": "han_thanh_toan", "type": "date"},\n        {\n          "alias": "trang_thai",\n          "type": "select",\n          "options": [\n            {"alias": "nhap", "color": "slate"},\n            {"alias": "cho_duyet", "color": "amber"},\n            {"alias": "da_duyet", "color": "blue"},\n            {"alias": "da_chi", "color": "green"},\n            {"alias": "tu_choi", "color": "rose"}\n          ]\n        },\n        {"alias": "nguoi_de_nghi", "type": "select_member"},\n        {"alias": "chung_tu", "type": "files"},\n        {"alias": "nguoi_duyet", "type": "select_member"},\n        {"alias": "duyet_luc", "type": "date", "format": "datetime"},\n        {"alias": "ly_do_tu_choi", "type": "text"},\n        {"alias": "phieu_chi", "type": "files"},\n        {"alias": "ngan_sach_du_an", "type": "lookup"},\n        {"alias": "da_duyet_du_an", "type": "lookup"},\n        {"alias": "vuot_ngan_sach", "type": "formula"},\n        {"alias": "sat_ngan_sach", "type": "formula"},\n        {"alias": "da_gui", "type": "formula"}\n      ]\n    }\n  ],\n  "records": {\n    "de_nghi": {\n      "title": "noi_dung",\n      "subtitle": ["du_an"],\n      "status": {"field": "trang_thai", "closed": ["da_chi", "tu_choi"], "history": "lich_su_duyet"},\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    }\n  },\n  "apps": [\n    {\n      "alias": "de_nghi_chi",\n      "name": "\u0110\u1EC1 ngh\u1ECB thanh to\xE1n",\n      "description": "Ch\u1EC9 huy tr\u01B0\u1EDFng l\u1EADp \u0111\u1EC1 ngh\u1ECB chi cho d\u1EF1 \xE1n c\u1EE7a m\xECnh, k\xE8m ch\u1EE9ng t\u1EEB, r\u1ED3i g\u1EEDi gi\xE1m \u0111\u1ED1c duy\u1EC7t.",\n      "icon": "hand-coins",\n      "theme": {"color": "amber"},\n      "entity": "de_nghi",\n      "register": {\n        "columns": ["nguoi_de_nghi"],\n        "filters": ["nguoi_de_nghi", "du_an"],\n        "create": ["noi_dung", "loai", "du_an", "nha_cung_cap", "so_tien", "han_thanh_toan", "nguoi_de_nghi"],\n        "readings": [\n          {\n            "metric": "de_nghi",\n            "value": "so_tien",\n            "where": {"trang_thai": ["da_duyet"]},\n            "label": "\u0110\xE3 duy\u1EC7t, ch\u1EDD chi"\n          },\n          {"trend": "de_nghi", "over": "han_thanh_toan", "value": "so_tien"}\n        ]\n      },\n      "record": {\n        "door": "drawer",\n        "sections": [\n          {\n            "title": "\u0110\u1EC1 ngh\u1ECB",\n            "at": ["nhap"],\n            "fields": ["so_de_nghi", "loai", "nha_cung_cap", "han_thanh_toan", "nguoi_de_nghi"],\n            "blocks": [{"files": ["chung_tu"], "title": "Ch\u1EE9ng t\u1EEB k\xE8m"}],\n            "acts": ["gui_duyet"]\n          },\n          {\n            "title": "Duy\u1EC7t",\n            "at": ["cho_duyet"],\n            "fields": ["nguoi_duyet", "duyet_luc", "ly_do_tu_choi"],\n            "acts": ["rut_lai"]\n          },\n          {"title": "\u0110\xE3 chi", "at": ["da_chi"], "blocks": [{"files": ["phieu_chi"], "title": "Phi\u1EBFu chi"}]}\n        ]\n      },\n      "acts": [\n        {\n          "alias": "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          "alias": "rut_lai",\n          "label": "R\xFAt l\u1EA1i",\n          "when": {"trang_thai": ["cho_duyet"]},\n          "set": {"trang_thai": "nhap"},\n          "confirm": true\n        }\n      ],\n      "checks": [{"field": "da_gui", "blocks": ["edit"]}, {"field": "vuot_ngan_sach"}, {"field": "sat_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.** `dashboard`: `metric`s with `over` (the period windows them), a `trend`, `breakdown`s, and a `list` of rows to act on opening in their app.\n\n**Keys.** `model/dashboards`, `model/readings`\n\n**Not when.** One job\'s headline numbers \u2014 those lead that job\'s register as its `readings`.\n\n```json\n{\n  "entities": [\n    {\n      "alias": "giao_dich",\n      "fields": [\n        {"alias": "noi_dung", "type": "text"},\n        {"alias": "ngay", "type": "date"},\n        {\n          "alias": "loai",\n          "type": "select",\n          "options": [{"alias": "thu", "color": "green"}, {"alias": "chi", "color": "rose"}]\n        },\n        {"alias": "so_tien", "type": "number", "format": "currency", "currency": "VND"},\n        {"alias": "bien_dong", "type": "formula"},\n        {\n          "alias": "doi_tuong",\n          "type": "select_record_link",\n          "target_entity": "doi_tuong",\n          "cardinality": "one"\n        },\n        {\n          "alias": "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        {"alias": "sao_ke", "type": "select_record_link", "target_entity": "sao_ke", "cardinality": "one"},\n        {\n          "alias": "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      ]\n    }\n  ],\n  "records": {\n    "giao_dich": {\n      "title": "noi_dung",\n      "subtitle": ["ngay"],\n      "status": {"field": "trang_thai", "closed": ["da_khop", "khong_can_hd"], "history": "lich_su_khop"},\n      "figure": "bien_dong"\n    }\n  },\n  "apps": [\n    {\n      "alias": "dong_tien",\n      "name": "D\xF2ng ti\u1EC1n",\n      "description": "Gi\xE1m \u0111\u1ED1c xem trong k\u1EF3: ti\u1EC1n v\xE0o, ti\u1EC1n ra, d\xF2ng ti\u1EC1n r\xF2ng qua c\xE1c k\u1EF3, chi v\xE0o \u0111\xE2u, thu t\u1EEB ai, v\xE0 nh\u1EEFng d\xF2ng sao k\xEA c\xF2n ch\u01B0a kh\u1EDBp.",\n      "icon": "chart-line",\n      "theme": {"color": "emerald"},\n      "dashboard": [\n        {\n          "metric": "giao_dich",\n          "value": "so_tien",\n          "where": {"loai": ["thu"]},\n          "over": "ngay",\n          "label": "Ti\u1EC1n v\xE0o"\n        },\n        {\n          "metric": "giao_dich",\n          "value": "so_tien",\n          "where": {"loai": ["chi"]},\n          "over": "ngay",\n          "better": "down",\n          "label": "Ti\u1EC1n ra"\n        },\n        {"trend": "giao_dich", "over": "ngay", "value": "bien_dong", "label": "D\xF2ng ti\u1EC1n r\xF2ng"},\n        {\n          "breakdown": "giao_dich",\n          "by": "danh_muc",\n          "value": "so_tien",\n          "where": {"loai": ["chi"]},\n          "over": "ngay",\n          "label": "Chi theo danh m\u1EE5c"\n        },\n        {\n          "breakdown": "giao_dich",\n          "by": "doi_tuong",\n          "value": "so_tien",\n          "where": {"loai": ["thu"]},\n          "over": "ngay",\n          "label": "Thu theo kh\xE1ch h\xE0ng"\n        },\n        {\n          "list": "giao_dich",\n          "where": {"trang_thai": ["chua_khop"]},\n          "columns": ["sao_ke"],\n          "app": "doi_chieu",\n          "label": "D\xF2ng ch\u01B0a kh\u1EDBp"\n        }\n      ]\n    }\n  ]\n}\n```\n';
 
 // AGENTS.md
-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 model` \xB7 `lotics docs model/<section>` | How to write a `model.json` \u2014 the file a workspace is built from: its tables, how a row of each is recognised (`records`), and the apps stated over them. Every top-level key, every field type with the config it needs, the row format, the rules, and a worked example; complete example models of several trades are listed at `https://lotics.ai/presets/index.json`. `lotics model apply` checks the file (every problem in one run), applies its tables and mints a version of each app; the WORKSPACE remembers what each alias became, so every later apply binds by id and a relabel on either side is a rename it reports rather than a second table it adds. `lotics model pull` goes the other way \u2014 the workspace's model, rebuilt from what owns each part. |\n| `lotics docs design` \xB7 `lotics docs design/<section>` | Designing an app \u2014 where an app starts: the method, the treatment each kind of row takes with the `model` page stating its keys, the visual bar, and looking at what an apply built. A finding of the apply names its section. |\n| `lotics docs examples` \xB7 `lotics docs examples/<treatment>` | Each treatment worked through in an app of a complete model: the job, the keys to read, where it is the wrong one, and the excerpt. |\n| [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE \u2014 clarify, model, apply or build, prove, look \u2014 for an app stated in a model and for a custom-code app. Read it once before starting an app. Looking is `lotics run screenshot_app`, then `lotics download` for each PNG. |\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 entity per table 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 every field type, its properties, computed fields, and what `update_fields` takes. Separate from building_an_app 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 lifecycle workflows. |\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. |\n| [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the workspace facts an agent can't guess; who can read a doc; catalog-then-stage retrieval. |\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 the four that touch a local file for an app \u2014 `model apply`,\n  `model pull`, `app create --custom` 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 model --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 <email>` prints the page a person opens (also mailed) 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 setup` falls into the same\n  flow by itself when the email it was given already has an account: it stops having created\n  nothing, and the SAME command run again carries on.\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 a 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` marks *admin only* split in two under a key: `workspace doctor`, which only\n  reads inside a workspace the key reaches, runs as before, while applying or pulling a model\n  (`model apply`, `model pull`, `setup`), 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 <email>` 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 <email>` 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_agent`, `run_app_query`) and every one that changes an app\n  (`set_app_queries`, `set_app_workflow`, `set_app_agent`, `update_app`, `rollback_app`). A command\n  exists only for work that touches a local file.\n- **Every change to an app mints a version of it, and rolling back is the undo.** An apply, a\n  deploy, a single `set_app_*` or `remove_app_binding`: each is a new version, and `rollback_app` makes an\n  earlier one current again. It 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` or `run_app_agent` result's own envelope carries a failed\n  `status` (`error`/`failed`/`cancelled`) \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/building_an_app.md](./docs/building_an_app.md) \xA7 7).\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 in a model is changed by applying the\n  model 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";
+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 model` \xB7 `lotics docs model/<section>` | How to write a `model.json` \u2014 the file a workspace is built from: its tables, how a row of each is recognised (`records`), and the apps stated over them. Every top-level key, every field type with the config it needs, the row format, the rules, and a worked example; complete example models of several trades are listed at `https://lotics.ai/presets/index.json`. `lotics model apply` checks the file (every problem in one run), applies its tables and mints a version of each app; the WORKSPACE remembers what each alias became, so every later apply binds by id and a relabel on either side is a rename it reports rather than a second table it adds. `lotics model pull` goes the other way \u2014 the workspace's model, rebuilt from what owns each part. |\n| `lotics docs design` \xB7 `lotics docs design/<section>` | Designing an app \u2014 where an app starts: the method, the treatment each kind of row takes with the `model` page stating its keys, the visual bar, and looking at what an apply built. A finding of the apply names its section. |\n| `lotics docs examples` \xB7 `lotics docs examples/<treatment>` | Each treatment worked through in an app of a complete model: the job, the keys to read, where it is the wrong one, and the excerpt. |\n| [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE \u2014 clarify, model, apply or build, prove, look \u2014 for an app stated in a model and for a custom-code app. Read it once before starting an app. Looking is `lotics run screenshot_app`, then `lotics download` for each PNG. |\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 entity per table 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 every field type, its properties, computed fields, and what `update_fields` takes. Separate from building_an_app 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 lifecycle workflows. |\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. |\n| [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the workspace facts an agent can't guess; who can read a doc; catalog-then-stage retrieval. |\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 the five that touch a local file for an app \u2014 `model apply`,\n  `model pull`, `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 model --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 <email>` prints the page a person opens (also mailed) 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 setup` falls into the same\n  flow by itself when the email it was given already has an account: it stops having created\n  nothing, and the SAME command run again carries on.\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 a 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` marks *admin only* split in two under a key: `workspace doctor`, which only\n  reads inside a workspace the key reaches, runs as before, while applying or pulling a model\n  (`model apply`, `model pull`, `setup`), 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 <email>` 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 <email>` 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_agent`, `run_app_query`) and every one that changes an app\n  (`set_app_queries`, `set_app_workflow`, `set_app_agent`, `update_app`, `rollback_app`). A command\n  exists only for work that touches a local file.\n- **Every change to an app mints a version of it, and rolling back is the undo.** An apply, a\n  deploy, a single `set_app_*` or `remove_app_binding`: each is a new version, and `rollback_app` makes an\n  earlier one current again. It 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` or `run_app_agent` result's own envelope carries a failed\n  `status` (`error`/`failed`/`cancelled`) \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/building_an_app.md](./docs/building_an_app.md) \xA7 7).\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 in a model is changed by applying the\n  model 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";
 
 // docs/building_an_app.md
-var building_an_app_default = '# Building an app, end to end\n\nThe other references here describe **contracts** \u2014 what a model may state, what a tool takes. This\none describes the **sequence**: the order the steps go in, and why. Read it once for the shape, then\nreach for the area doc (`lotics docs`) whenever you need the detail.\n\n**The live app is the only edit surface.** Every change to an app \u2014 applying a model, deploying a\nbuild, setting one query or workflow \u2014 mints a new version of it, and rolling back to an earlier\nversion is the undo. Nothing about an app lives in a local directory the platform reads back, so\nthere is no project to keep in sync and no deploy to find out whether something works.\n\n**Rolling back restores the app, not the data.** A table change the model made, and every row a\nworkflow wrote while you tried it, stay where they are. Try a write on a throwaway record.\n\n---\n\n## 1 \u2014 Two kinds of app\n\n- **An app stated in a model** \u2014 the default, and the right one for almost every job. `model.json`\n  says how a row of each entity is recognised (`records`) and, in `apps`, one register over one\n  entity and the record its rows open: its columns and filters, its sections in the order its work\n  reaches them, its acts and the checks that guard them (`lotics docs model/register`,\n  `model/record-page`, `model/acts`, `model/checks`). The platform\n  compiles each app and draws it with the runtime every such app shares, so how each piece looks is\n  the platform\'s, one way per concept, and no key changes it. Every write the app makes is a\n  generated workflow that re-checks on the server what the model states.\n- **A custom-code app** \u2014 React you write, for a surface the model\'s vocabulary cannot state. It\n  reads and writes through `@lotics/app-sdk` (queries, workflows, files, AI) and draws with whatever\n  React you choose.\n\n## 2 \u2014 Clarify what is being asked, before modelling it\n\n**A metric name is not a definition.** "Revenue", "in stock", "active", "overdue" \u2014 each is a\nbusiness rule the person asking owns, and the cost of guessing is a screen that is confidently\nwrong. Ask until there is no ambiguity left:\n\n- Which rows count, keyed off which field \u2014 a date, a status, a flag?\n- Does the same metric need a **different rule per table**? One table may key off a date and\n  another off a status; one rule rarely covers both.\n- Snapshot or flow? "Current stock" is as-of-now; "revenue this month" is a window. They compile\n  to different filters.\n- If the data cannot support the definition asked for \u2014 the field simply is not there \u2014 **say so\n  and show the options.** Silently substituting a near-miss produces a number nobody can trace.\n\nThis is the step that gets skipped under time pressure, and it is the only one whose mistakes are\ninvisible in review: every later artifact is correct with respect to the wrong definition.\n\n## 3 \u2014 The data model, before any app\n\nGet this wrong and nothing above it can be precise. Each entity is its own table with links into\nthe spine; attributes and evidence are fields on their owner. A single table with a `type` column\nstanding in for three entities collapses the distinctions every later query needs.\n\n**Verify real VALUES, never just that a field exists.** `lotics run query_records` a sample and\nlook at fill rates \u2014 a field that is present and empty on 90% of rows will not support the screen\nyou are about to design.\n\n**That includes imagery.** If the entity has a likeness \u2014 a product, a property, a vehicle, a\nperson \u2014 its picture is the strongest identifier a register row can carry, and an empty image field\nis a data gap to fill before you design around it: `lotics file upload`, then `update_records`.\n\n**One fact, one column \u2014 and check before you add one.** Read the table\'s existing fields before\nadding any, because the fact is often already there in another shape: a place written as text\nbeside a link to the place record, a status word beside the select that decides it, a total beside\nthe formula that computes it. Two columns for one fact never stay equal. Prefer the link, the\nselect, or the formula, and compose the text when you READ.\n\n**Match on ids and option keys, never on rendered text.** Resolve a name to its `rec_\u2026` or `opt_\u2026`\nonce, at the boundary, and compare those. Treat an unresolved name as UNKNOWN, never as a wildcard.\n\n**How the tables RELATE is `lotics docs data_model`** \u2014 read it before designing a schema; those\ndecisions outlive any one app.\n\n**Empty is not the same as redundant.** A field nothing fills may still be the only home for a real\ndistinction. Read what a field MEANS before you remove it.\n\n## 4 \u2014 An app stated in a model\n\n```\nlotics docs model                       # how to write model.json, with a worked example\nlotics docs design                      # how to design each app: the method, a treatment per kind of row\nlotics model apply model.json           # check it, apply the tables, mint a version of every app\nlotics model apply model.json --app orders   # only the apps named; the tables are applied whole\nlotics model apply model.json --plan    # what the apply would change, writing nothing\nlotics model pull -o model.json         # the workspace\'s model, as the file apply reads\n```\n\n`model apply` checks the whole file first \u2014 every problem in one run, before anything is uploaded\nor written. It then adopts or creates each table (the table this workspace bound it to, else one of the same\nlabel, is adopted and given what it lacks; no stored value changes), writes the first rows only where every bound\ntable is empty, and mints one version per app, printing each app\'s id, the version minted\n(`unchanged` when there was nothing to mint) and its address. Applying the same file again mints nothing.\nA table change is not undone by rolling an app back, so `--plan` first says what the apply would\ncreate or change in the tables and which apps it would create, update or refuse \u2014 writing nothing.\n\n**An app leaving out a treatment its rows call for is refused** \u2014 readings over its rows, a record\'s\nsections, an act per status move, a picture where its rows hold photos (`lotics docs design`). Each\nrefusal names the rule, and beside them comes each refused app\'s patch adopting its decisions: merge\nthe patches into the file in the order given, or state why the app stays as it is under the\n`declines` key the refusal names (`lotics docs model/declines`), then apply again. `--plan` reads the\ndecisions beside the workspace\'s rows, and with `--json` gives each app as the patches leave it, its\n`draft`.\n\n**The model changes after the app exists, and applying it again is how it lands.** Edit the file,\napply it. An act whose write the model cannot say names its own `workflow`; that workflow\'s body is\nthe live one, and `lotics run set_app_workflow` changes it. An act that reads papers runs an agent\napply owns: made, replaced and removed with the act, and an agent of that alias apply did not make\nis refused, never rewritten.\n\n## 5 \u2014 A custom-code app\n\n```\nlotics app create "<name>" --custom     # the app, plus a Vite + React + TS project using @lotics/app-sdk\ncd <dir>\n# edit src/App.tsx \u2014 node_modules/@lotics/app-sdk/AGENTS.md is the reference\nnpm run typecheck && npm run lint && npm test\nlotics app deploy -m "<what changed>"   # build, upload, a new version live\n```\n\nWhat the app reads and writes is bound on the app, never in the project: `lotics run\nset_app_queries` binds named queries, `lotics run set_app_workflow` a workflow body, and each mints a\nversion. `useQuery("<alias>")` and `useWorkflow("<alias>")` call them. A deploy uploads the build\nand carries every binding forward unchanged.\n\n**Named queries.** Author them as `kind: "project"` with a `filter`, naming each projected column\n(`{ "source": "fld_\u2026", "output": "total" }`), so a row reads as `r.total`. Scope per-user reads with\n`is_current_member` **inside the query** \u2014 a member id passed from the client is chosen by the\ncaller. Write one `description` per alias: it is the line a chat or MCP caller chooses by.\n\n**Workflows are the only way an app writes.** Every workflow bound to an app is also the chat\nagent\'s write surface, so its shape is an agent-facing decision: take a list where one job covers\nmany records, say in an optional input\'s `description` what omitting it means, make the write\nsurvive running twice, and gate anything irreversible with `wait_for_approval`.\n\n## 6 \u2014 Prove it, without a screen\n\nStatic checks prove parse, types and names \u2014 they evaluate nothing. Rehearse a write first:\n\n```\nlotics run dry_run_workflow \'{"trigger_type":"app_workflow","trigger_payload":{\u2026},"live_reads":true}\'\n```\n\nIt walks the real step tree and returns the resolved plan plus expression and tool-input errors,\ndispatching no write. **`live_reads: true` matters whenever the body reads anything**: without it\nevery read returns a stub, and every data-gated branch takes the empty path.\n\nThen run it end to end, on a throwaway record:\n\n```\nlotics run run_app_query \'{"app_id":"app_\u2026","alias":"\u2026","params":{\u2026}}\'\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"\u2026","inputs":{\u2026}}\'\n# exits non-zero when the run failed, so it is assertable\n```\n\nA workflow is also how an app **produces a document** \u2014 `generate_document` fills a template\nyou registered once (`lotics docs document_templates`).\n\n## 7 \u2014 Look at it, then name it\n\nLook at every app you apply, at a desktop width and at a phone\'s \u2014 every check above reads the\ndefinition, none of them the pixels:\n\n```\nlotics run screenshot_app \'{"app_id":"app_\u2026"}\'\n# one PNG per width, saved as a workspace file; "path":"/rec_\u2026" opens a screen inside the app\nlotics download <file_id>\n```\n\nEach shot is one screen, as a member sees it; `"full_page":true` grows it to the list scrolling\ninside the app. Beside each image comes its `snapshot`, the screen\'s accessibility tree as text \u2014\nread it to check labels and values without opening the picture.\n\nThe app is drawn live, as you, read-only: a screen that writes when it opens shows that write\nrefused, and `errors` lists what failed on the page. A version that looks wrong is one\n`lotics run rollback_app` away from the one before.\n\nFor an app a model applied, `verdict` comes beside the images: what a `--plan` of the workspace\'s\nmodel finds of that app now, beside its rows \u2014 what the next apply would refuse it for and the notes\non it, the `patch` adopting the decisions among them, and the app\'s body as the patch\nleaves it (`draft`). `verdict_unread` says why none was read.\n\nThen set the icon, the colour and the app\'s own `description` through `lotics run update_app`. The\n`description` heads the capability listing the member\'s chat agent reads on **every** turn, so a\nstanding process the app expects that agent to carry out belongs there and nowhere else.\n\n**A caller outside the team gets its own app.** Sharing an app publicly, or giving an API key\naccess to it, reaches every alias the app declares; no alias can be held back. So whatever\noutsiders may call is a SECOND app over the same tables: only the queries they may read and the\nworkflows they may run. The desk the team works in stays a separate, private app.\n';
+var building_an_app_default = '# Building an app, end to end\n\nThe other references here describe **contracts** \u2014 what a model may state, what a tool takes. This\none describes the **sequence**: the order the steps go in, and why. Read it once for the shape, then\nreach for the area doc (`lotics docs`) whenever you need the detail.\n\n**The live app is the only edit surface.** Every change to an app \u2014 applying a model, deploying a\nbuild, setting one query or workflow \u2014 mints a new version of it, and rolling back to an earlier\nversion is the undo. Nothing about an app lives in a local directory the platform reads back.\n\n**Rolling back restores the app, not the data.** A table change the model made, and every row a\nworkflow wrote while you tried it, stay where they are. Try a write on a throwaway record.\n\n---\n\n## 1 \u2014 Two kinds of app\n\n- **An app stated in a model** \u2014 the default, and the right one for almost every job. `model.json`\n  says how a row of each entity is recognised (`records`) and, in `apps`, one register over one\n  entity and the record its rows open: its columns and filters, its sections in the order its work\n  reaches them, its acts and the checks that guard them (`lotics docs model/register`,\n  `model/record-page`, `model/acts`, `model/checks`). The platform\n  compiles each app and draws it with the runtime every such app shares, so how each piece looks is\n  the platform\'s, one way per concept, and no key changes it. Every write the app makes is a\n  generated workflow that re-checks on the server what the model states.\n- **A custom-code app** \u2014 React you write, for a surface the model\'s vocabulary cannot state. It\n  reads and writes through `@lotics/app-sdk` (queries, workflows, files, AI) and draws with whatever\n  React you choose.\n\n## 2 \u2014 Clarify what is being asked, before modelling it\n\n**A metric name is not a definition.** "Revenue", "in stock", "active", "overdue" \u2014 each is a\nbusiness rule the person asking owns, and the cost of guessing is a screen that is confidently\nwrong. Ask until there is no ambiguity left:\n\n- Which rows count, keyed off which field \u2014 a date, a status, a flag?\n- Does the same metric need a **different rule per table**? One table may key off a date and\n  another off a status; one rule rarely covers both.\n- Snapshot or flow? "Current stock" is as-of-now; "revenue this month" is a window. They compile\n  to different filters.\n- If the data cannot support the definition asked for \u2014 the field simply is not there \u2014 **say so\n  and show the options.** Silently substituting a near-miss produces a number nobody can trace.\n\nThis is the step that gets skipped under time pressure, and it is the only one whose mistakes are\ninvisible in review: every later artifact is correct with respect to the wrong definition.\n\n## 3 \u2014 The data model, before any app\n\nGet this wrong and nothing above it can be precise. Each entity is its own table with links into\nthe spine; attributes and evidence are fields on their owner. A single table with a `type` column\nstanding in for three entities collapses the distinctions every later query needs.\n\n**Verify real VALUES, never just that a field exists.** `lotics run query_records` a sample and\nlook at fill rates \u2014 a field that is present and empty on 90% of rows will not support the screen\nyou are about to design.\n\n**That includes imagery.** If the entity has a likeness \u2014 a product, a property, a vehicle, a\nperson \u2014 its picture is the strongest identifier a register row can carry, and an empty image field\nis a data gap to fill before you design around it: `lotics file upload`, then `update_records`.\n\n**One fact, one column \u2014 and check before you add one.** Read the table\'s existing fields before\nadding any, because the fact is often already there in another shape: a place written as text\nbeside a link to the place record, a status word beside the select that decides it, a total beside\nthe formula that computes it. Two columns for one fact never stay equal. Prefer the link, the\nselect, or the formula, and compose the text when you READ.\n\n**Match on ids and option keys, never on rendered text.** Resolve a name to its `rec_\u2026` or `opt_\u2026`\nonce, at the boundary, and compare those. Treat an unresolved name as UNKNOWN, never as a wildcard.\n\n**How the tables RELATE is `lotics docs data_model`** \u2014 read it before designing a schema; those\ndecisions outlive any one app.\n\n**Empty is not the same as redundant.** A field nothing fills may still be the only home for a real\ndistinction. Read what a field MEANS before you remove it.\n\n## 4 \u2014 An app stated in a model\n\n```\nlotics docs model                       # how to write model.json, with a worked example\nlotics docs design                      # how to design each app: the method, a treatment per kind of row\nlotics model apply model.json           # check it, apply the tables, mint a version of every app\nlotics model apply model.json --app orders   # only the apps named; the tables are applied whole\nlotics model apply model.json --plan    # what the apply would change, writing nothing\nlotics model pull -o model.json         # the workspace\'s model, as the file apply reads\n```\n\n`model apply` checks the whole file first \u2014 every problem in one run, before anything is uploaded\nor written. It then adopts or creates each table (the table this workspace bound it to, else one of the same\nlabel, is adopted and given what it lacks; no stored value changes), writes the first rows only where every bound\ntable is empty, and mints one version per app, printing each app\'s id, the version minted\n(`unchanged` when there was nothing to mint) and its address. Applying the same file again mints nothing.\nA table change is not undone by rolling an app back, so `--plan` first says what the apply would\ncreate or change in the tables and which apps it would create, update or refuse \u2014 writing nothing.\n\n**An app leaving out a treatment its rows call for is refused** \u2014 readings over its rows, a record\'s\nsections, an act per status move, a picture where its rows hold photos (`lotics docs design`). Each\nrefusal names the rule, and beside them comes each refused app\'s patch adopting its decisions: merge\nthe patches into the file in the order given, or state why the app stays as it is under the\n`declines` key the refusal names (`lotics docs model/declines`), then apply again. `--plan` reads the\ndecisions beside the workspace\'s rows, and with `--json` gives each app as the patches leave it, its\n`draft`.\n\n**The model changes after the app exists, and applying it again is how it lands.** Edit the file,\napply it. An act whose write the model cannot say names its own `workflow`; that workflow\'s body is\nthe live one, and `lotics run set_app_workflow` changes it. An act that reads papers runs an agent\napply owns: made, replaced and removed with the act, and an agent of that alias apply did not make\nis refused, never rewritten.\n\n## 5 \u2014 A custom-code app\n\n```\nlotics app create "<name>" --custom     # the app, plus a Vite + React + TS project using @lotics/app-sdk\ncd <dir>\n# edit src/App.tsx \u2014 node_modules/@lotics/app-sdk/AGENTS.md is the reference\nnpm run typecheck && npm run lint && npm test\nlotics app deploy -m "<what changed>"   # build, upload, a new version live\nlotics app pull <app_id>                # the live version\'s source, on a machine without the project or after another deploy\n```\n\nWhat the app reads and writes is bound on the app, never in the project: `lotics run\nset_app_queries` binds named queries, `lotics run set_app_workflow` a workflow body, and each mints a\nversion. `useQuery("<alias>")` and `useWorkflow("<alias>")` call them. A deploy uploads the build\nand carries every binding forward unchanged.\n\n**Named queries.** Author them as `kind: "project"` with a `filter`, naming each projected column\n(`{ "source": "fld_\u2026", "output": "total" }`), so a row reads as `r.total`. Scope per-user reads with\n`is_current_member` **inside the query** \u2014 a member id passed from the client is chosen by the\ncaller. Write one `description` per alias: it is the line a chat or MCP caller chooses by.\n\n**Workflows are the only way an app writes.** Every workflow bound to an app is also the chat\nagent\'s write surface, so its shape is an agent-facing decision: take a list where one job covers\nmany records, say in an optional input\'s `description` what omitting it means, make the write\nsurvive running twice, and gate anything irreversible with `wait_for_approval`.\n\n## 6 \u2014 Prove it, without a screen\n\nStatic checks prove parse, types and names \u2014 they evaluate nothing. Rehearse a write first:\n\n```\nlotics run dry_run_workflow \'{"trigger_type":"app_workflow","trigger_payload":{\u2026},"live_reads":true}\'\n```\n\nIt walks the real step tree and returns the resolved plan plus expression and tool-input errors,\ndispatching no write. **`live_reads: true` matters whenever the body reads anything**: without it\nevery read returns a stub, and every data-gated branch takes the empty path.\n\nThen run it end to end, on a throwaway record:\n\n```\nlotics run run_app_query \'{"app_id":"app_\u2026","alias":"\u2026","params":{\u2026}}\'\nlotics run run_app_workflow \'{"app_id":"app_\u2026","alias":"\u2026","inputs":{\u2026}}\'\n# exits non-zero when the run failed, so it is assertable\n```\n\nA workflow is also how an app **produces a document** \u2014 `generate_document` fills a template\nyou registered once (`lotics docs document_templates`).\n\n## 7 \u2014 Look at it, then name it\n\nLook at every app you apply, at a desktop width and at a phone\'s \u2014 every check above reads the\ndefinition, none of them the pixels:\n\n```\nlotics run screenshot_app \'{"app_id":"app_\u2026"}\'\n# one PNG per width, saved as a workspace file; "path":"/rec_\u2026" opens a screen inside the app\nlotics download <file_id>\n```\n\nEach shot is one screen, as a member sees it; `"full_page":true` grows it to the list scrolling\ninside the app. Beside each image comes its `snapshot`, the screen\'s accessibility tree as text \u2014\nread it to check labels and values without opening the picture.\n\nThe app is drawn live, as you, read-only: a screen that writes when it opens shows that write\nrefused, and `errors` lists what failed on the page. A version that looks wrong is one\n`lotics run rollback_app` away from the one before.\n\nFor an app a model applied, `verdict` comes beside the images: what a `--plan` of the workspace\'s\nmodel finds of that app now, beside its rows \u2014 what the next apply would refuse it for and the notes\non it, the `patch` adopting the decisions among them, and the app\'s body as the patch\nleaves it (`draft`). `verdict_unread` says why none was read.\n\nThen set the icon, the colour and the app\'s own `description` through `lotics run update_app`. The\n`description` heads the capability listing the member\'s chat agent reads on **every** turn, so a\nstanding process the app expects that agent to carry out belongs there and nowhere else.\n\n**A caller outside the team gets its own app.** Sharing an app publicly, or giving an API key\naccess to it, reaches every alias the app declares; no alias can be held back. So whatever\noutsiders may call is a SECOND app over the same tables: only the queries they may read and the\nworkflows they may run. The desk the team works in stays a separate, private app.\n';
 
 // docs/cli_reference.md
-var cli_reference_default = "# @lotics/cli \u2014 CLI Command Reference\n\nPer-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. Start at [AGENTS.md](../AGENTS.md) for the model this reference assumes; `lotics --help` is the authoritative, always-current verb list.\n\n| Command | What it does |\n|---|---|\n| `lotics` / `lotics --help` | Show full help: capabilities, the verb list (\xA7 COMMANDS), flags, config. `lotics <verb> --help` prints that verb's entries alone (`lotics model --help`, `lotics file download --help`); `lotics report --help` prints the report frame. |\n| `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |\n| `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open \u2014 `https://lotics.ai/cli_login/<request_id>`, also mailed \u2014 and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential \u2014 `docs` among them \u2014 claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |\n| `lotics auth api-key [key]` | `whoami` \u2192 **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |\n| `lotics auth web` | Send a magic link email to access the web app (requires auth) |\n| `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key \u2014 read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |\n| `lotics auth logout [<name\\|id>]` | In a pinned dir: delete the local pin. Else: remove the profile (default the active org), `--all` for every one. What happens server-side depends on which KIND of credential it is. A **sign-in** (`auth login` / `auth signup`) is revoked \u2014 logging that terminal out ends its credential rather than leaving a live one behind; a server that cannot be reached, or a credential already dead, never blocks the local forget, and one line names the org and Settings \u2192 Security \u2192 *Keys and terminals*. An **API key** (`auth api-key`) is only forgotten here \u2014 an admin issued it and it is routinely on a server and on other machines, so one terminal signing out must not kill it for everyone; the line says it is still active and names both pages, because Settings \u2192 API keys is admin-only and the credential may well be the holder's own sign-in, which they revoke themselves at Settings \u2192 Security \u2192 *Keys and terminals*. A profile saved before the kind was recorded states nothing, so the SERVER is asked (`auth whoami`) and it is revoked only if the answer is a sign-in: an older server, a credential minted before the column, and a request that fails all leave it alone. |\n| \u2014 | **A refused credential says which of three ways it is dead, and names the remedy that ends its kind.** `This credential expired.` / `was revoked.` / `belongs to a member who is no longer active in this organization.` carries `Run \\`lotics auth login <email>\\` to sign in again.` for a sign-in and `Ask an admin for a new API key (Settings \u2192 API keys).` for an issued key. A credential minted before that was recorded still gets BOTH in one sentence, because nothing on the row tells them apart \u2014 so a headless box is never sent looking for a browser alone. A key the server does not recognize at all gets one flat `Invalid or disabled API key.` \u2014 deliberately, so a guessed key learns nothing, not even that it named a row. The body carries `reason` for a script to branch on, since the code stays `unauthorized` for every 401. |\n| `lotics org` | List saved orgs (profiles) from the global store with the instance each belongs to, marks active for this directory (a local pin wins over the global default). |\n| `LOTICS_ORG=<name\\|id>` | Scope every command in this shell to one saved org. **Resolved once, before any command dispatches**, so a value matching no saved credential refuses every verb with one sentence \u2014 a read, a write, and a local check that needs no credential alike \u2014 and refuses it before the first byte is written. It refuses even when a credential arrives another way, because `--api-key` / `LOTICS_API_KEY` outrank it in the precedence chain and a write must never fall through to whatever THOSE name while the variable says otherwise; when the variable resolves and a key is also given, the key decides and the command says so. The refusal lists the orgs this machine holds, so it is answerable without another command (`lotics org` is refused by the same rule). A name is whatever the credential was SAVED under \u2014 a server-side rename never moves it, and the new name resolves too, so both keep working and `lotics org` prints the pair. |\n| `lotics org use <name\\|id> [--local]` | Switch the active org by org name (case-insensitive, ambiguous \u2192 error) or id. No flag \u2192 global `active_org`; `--local` \u2192 a `.lotics/config.json` pointer in the current dir. |\n| `lotics workspace` | List workspaces in the active org, marks current with `(current)` |\n| `lotics workspace select <id>` | Set the workspace in the **active scope** \u2014 a local pin if the dir has one, else the active org's global profile. Records the workspace's NAME beside its id, which is what the `lotics \u2192 <org> / <workspace>` echo prints; `workspace list`, `workspace create`, `workspace rename` and `org use` record it too, so a target is named rather than identified. Until one command has listed it, the echo prints the id and says the name is not known yet. |\n| `lotics workspace create <name> [--timezone <Area/City>] [--currency <ISO>]` | Create a new workspace (admin only), auto-switches to it. Neither flag is defaulted from THIS machine, unlike signup: an extra workspace is routinely created by an operator for somebody else. Without `--timezone` the new workspace inherits the zone of the org's OLDEST workspace; without `--currency` it takes the org's default. Both ride the create, so the workspace is never briefly denominated in a currency nobody asked for. `--currency` takes an ISO-4217 code (case-insensitive; anything else is refused). |\n| `lotics workspace rename <name>` | Rename the **current** workspace (admin only) \u2014 the endpoint takes its target from the request's workspace, never a path id, so switch with `workspace select <id>` first and read the `lotics \u2192 <org> / <workspace>` echo before trusting it \u2014 both halves are names, and the rename moves the cached one in the same act. Carries the workspace's existing `default_currency` and `timezone` through unchanged: the endpoint takes the whole settings triple, so sending only a name would blank the other two. |\n| `lotics workspace settings [--name <n>] [--currency <ISO>] [--timezone <Area/City>]` | Change the CURRENT workspace's name, default currency or timezone \u2014 `PATCH /v1/workspace`, admin only. Only what you name changes; the endpoint takes the whole triple, so the CLI carries the two you did not. `rename` is this verb with the name alone, which is why it can never forget the other two. Both values are invisible once they are wrong: the currency decides how every money field RENDERS and the zone decides how every date BUCKETS, on a workspace whose whole purpose may be to look like the customer's own. `--json` prints the updated workspace. |\n| `lotics workspace delete <id> --yes` | Delete a workspace by id (admin only). **Soft delete** \u2014 `archived_at` is set, so it drops out of listings, can no longer be selected, and its tables/records go dark, while the data is retained and recoverable. Its **apps are cascade-archived** too \u2014 every app entry point (embedded, public link, standalone subdomain, incl. anonymous public links) stops serving. Refuses the org's **only** active workspace (400) and any workspace outside the caller's org (404). Requires `--yes` to confirm (destructive; the CLI is used non-interactively). |\n| `lotics workspace doctor` | Report workspace-wide dangling schema references via `GET /v1/workspaces/dangling-references` \u2014 every active app/workflow artifact whose prefixed schema id no longer resolves, printed as `<referent.kind> \"<name>\" (<id>) \u2192 <namespace> <id> (missing)`; healthy prints a one-line all-clear. **Exits non-zero (exit 1) on findings** so scripts can gate on it. Resolves the first workspace like every data command (runs before the global workspace resolution). Admin-only. |\n| `lotics tools` | List tools by category with descriptions |\n| `lotics tools <name>` | Full description + JSON Schema for one tool |\n| `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or stdin behind the `-` sentinel (`cat args.json \\| lotics run <tool> -`) \u2014 both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). **Stdin is asked for, never guessed.** `lotics run <tool>` with no payload runs the tool with no arguments and returns at once. `lotics report` takes the same sentinel. In PowerShell use `@file`: quotes inside an inline argument are consumed by the shell, and the CLI reports the JSON it received with its quotes gone \u2014 the error names both escapes. |\n| `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |\n| `lotics run <tool>` \u2014 **file cells** | A file in a tool's result carries its `fil_\u2026` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file \u2014 this surface resolves no URL for a cell. Reach the bytes with `lotics file download <file_id>`, which takes the id straight from the cell; the text output says so whenever a result carries one. |\n| \u2014 | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_agent`, `run_app_query`) and every one that changes an app (`set_app_queries`, `set_app_workflow`, `set_app_agent`, `update_app`, `rollback_app`). A command exists only for work that touches a local file: `model apply`, `model pull`, `app create --custom`, `app pull`, `app deploy`. |\n| \u2014 | **The exit code reports the WORK, not just the call \u2014 for the two tools that RUN one.** `run_app_workflow` and `run_app_agent` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`) exit non-zero and print `<tool> \u2192 <status>: <message>` to stderr, so `lotics run \u2026 && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE \u2014 an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` is data, and exits 0. |\n| `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |\n| `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes \u2014 harvested records **only**, never files / external calls / notifications. **Not a rollback**; a rollback is structurally impossible here. A partial cleanup exits non-zero so a script cannot read it as success. |\n| `lotics file upload <file\\|dir...>` (alias `lotics upload`) \xB7 `--stdin` \xB7 `--base64` \xB7 `--url <url>` | Upload files/directories. **The transport is chosen by size and is not a flag**: under 8 MiB the file is POSTed to `/v1/files` in one request, and several such files go in the same one; at or above it the CLI takes presigned part URLs and PUTs the bytes straight to object storage, so they never pass through the API. That threshold matches the AWS CLI's own `multipart_threshold`, and the number matters less than there being nothing to choose \u2014 one verb, any size, up to the 2 GiB a workspace may store. A large upload reads one part at a time, so memory stays flat regardless of file size, and a failure part-way abandons the parts already sent rather than leaving them billable and invisible. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** \u2014 an attachment decoded in memory, a generated document, a signed download link \u2014 each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY \u2014 `Buffer.from(s, \"base64\")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |\n| `lotics file download <file_id> [<path>]` \xB7 `-o <dir>` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` \u2192 fetch the presigned URL and write it where you asked. **The two spellings mean two different things, and neither is read by shape: the positional `<path>` is the FILE to write, `-o <dir>` is the DIRECTORY to save into.** That is `cp` and `curl -o`, so nothing here consults an extension. A named file is written as named, its parent created, overwriting what is there \u2014 the point of naming it is that the next command opens that exact path. A directory is created if missing and written into under the stored filename (the response's `Content-Disposition`), taking a free spelling beside a file of that name already there so a repeat download never clobbers the first; with no destination at all, that filename lands in cwd. Give the destination once \u2014 a positional and `-o` together is refused, as is a positional that names an existing directory or ends in a separator (`a directory goes in -o`). The first argument is a **file id**, so a path in that slot is refused rather than sent as an id. The written path goes to **stdout** (under `--json`, `{file_id, path, filename, stored_filename}`) and the narration to stderr, so a download pipes into whatever opens it. `lotics file download record <record_id> <field_key> [-o <dir>]` spreads every file on a record's file field over a DIRECTORY \u2014 there is no single file for N files to be. |\n| `lotics file list [--limit <n>] [--cursor <token>]` | The workspace's files, newest first \u2014 id, upload time, bytes, MIME type, filename on stdout, one per line (`--json` for the object). `GET /v1/files` with no `file_ids`. A file holding the content of a knowledge doc or template you cannot use is left out. **A page, not a dump**: the store only ever grows, so the last line prints the command for the next page and `next_cursor` is null on the last one. The cursor is opaque and keyset \u2014 pass it back as given \u2014 so an upload landing mid-sweep cannot make a walk skip or repeat a row. Every other file verb takes an id, so this is the only answer to \"what is in here\" short of reading Postgres. |\n| `lotics file delete <file_id>` | Archive a stored file, over the `delete_file` tool. **Refused while a record cell, a comment, a knowledge doc, a document template or a voice session still references it** \u2014 the refusal names the referents, so this is safe to try. The bytes are left in object storage; the row no longer serves them, which is what \"deleted\" means here. There is no `lotics delete`: the verb needs its noun. |\n| `lotics knowledge list [--include-hidden]` | `GET /v1/knowledge_docs` \u2014 a table of id, name, tags, description (`--json` for the docs). **REST, not the `list_knowledge` tool**: the tool answers what the ASSISTANT may browse, and a hidden doc is out of that corpus by definition, so a tool-backed listing could never show one and the person who hid it would have no way back to it. Hidden docs are left out unless `--include-hidden` asks; those rows are marked `(hidden)`. |\n| `lotics knowledge create --name <n> [--description <d>] [--tags <a,b>] (--from <file.md> \\| --content <str>)` | Read the body client-side (a file XOR an inline string \u2014 exactly one required), then call `create_knowledge` with `{ name, description, content, tags? }` (description defaults to `\"\"`). `--tags` files the doc as it is made, which is the only moment a corpus reliably gets labelled. Prints the new id to stdout. Large files ride the POST body fine. |\n| `lotics knowledge get <id> [-o <file.md>]` | `GET /v1/knowledge_docs/{id}` (`getKnowledgeDoc`) \u2192 the doc with its **hydrated `content`** (the one content-read path for a non-sandbox client). `-o` writes the body via `writeFileAtomic`; else the body goes to stdout. `--json` prints the full doc instead. |\n| `lotics knowledge update <id> [--from <file.md> \\| --content <str>] [--name <n>] [--description <d>] [--tags <a,b>]` | Call `update_knowledge` with **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). `--tags` REPLACES the doc's label set \u2014 the single-doc form, where the caller is looking at one doc and can state what it should carry. At least one field required; --from and --content are mutually exclusive. |\n| `lotics knowledge tag <id...> [--add <a,b>] [--remove <c,d>]` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, add_tags?, remove_tags? }` \u2014 one transaction over the whole set. A **DIFF applied to each doc's own labels**, never a replacement: the docs named on one command line carry different labels, so one array across them would strip whatever the others were filed under. Removal matches case-insensitively; adding a label a doc already carries writes nothing. Ids may be separate arguments or comma-separated. At least one of --add/--remove required. |\n| `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** \u2014 the Library's list, `list_knowledge`, and the corpus `grep_knowledge` searches \u2014 while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as \"everything\". |\n| `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |\n| `lotics setup <model.json> [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes \u2014 `--name` and `--timezone` apply), then applies the model to its workspace, then prints the one-time sign-in link. **When that email already has an account it hands over to the `lotics auth login` flow** \u2014 it prints the sign-in page to open and the code it must show, and **exits 1 having created nothing**; the person presses Confirm and runs the same command again, which collects the key and carries on into the model. (`--wait` holds the terminal through the Confirm instead, finishing in one command.) The re-run is not refused for naming an `--email` it is now signed in as \u2014 that address IS the account it holds, not a second one. The file is a workspace MODEL, and it is read and checked before an account is created \u2014 the design decisions an apply would refuse it for too (`lotics docs design`), since a new workspace holds no rows to change them \u2014 because a file with a typo in it must not leave an organization behind. Then it is `lotics model apply` run on the new workspace: its tables, rows and apps; the sign-in link lands on its app when it has one, else on the workspace's app list. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently writes into an org the caller did not name \u2014 the message says how to do each thing on purpose. Without it, `setup` applies the model to the account you already have. A path positional after the file is accepted and IGNORED with a warning \u2014 `setup` writes nothing to disk \u2014 so a prompt that passes one still runs. **`--json` prints one object on stdout and nothing else** \u2014 what `lotics model apply --json` does (`tables`; `apps`, each with `alias`, `app_id`, `version_id`, `origin`, `address` and `findings`; and `findings`) plus `organization_id`, `workspace_id` and `signin_url`, and a `warnings` array carrying everything the prose form would have said out of band, such as a sign-in link that could not be minted. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. Reachable with no install: `npx -y @lotics/cli setup \u2026`. |\n| `lotics model apply <model.json> [--app <alias> ...] [--plan] [--json]` | **The model, applied to this workspace, through the `apply_model` tool.** The file is read and checked against the model's own rules with the validator the server runs, every problem in one run, before anything is uploaded. **The apply refuses an app leaving out a treatment its rows call for** (`lotics docs design`) \u2014 judged by the server beside the workspace's rows, before it writes anything \u2014 until the app adopts it or states why not under the `declines` key the refusal names; the refusal carries each refused app's patch adopting its decisions, to merge in the order printed. Documents a row attaches by a path beside the file are uploaded first and the rows sent with their `fil_` ids; a path this workspace already recorded keeps its id, so a re-apply uploads nothing twice. **Where the file was pulled (`-o`) or applied in this workspace before, only what it changed since is sent**, as a `patch`: what changed in the workspace since and the file does not touch stays. What the file takes out is sent as a removal: it goes where an apply rebuilds it (an app's acts and columns, a write rule) and is refused, naming the tool that deletes it, where an apply never deletes it (a table, a field, an option, an app). A file that reorders items named by their `alias` sends the whole model, said on stderr. The copy each change is read against is kept per workspace and file under `~/.lotics/model_bases`: an apply narrowed by `--app` leaves in it the other apps as they were, so the next apply sends their edits again, and an apply that fails \u2014 refused, or cut off \u2014 leaves none, so the next sends the whole model. Then the tool adopts or creates every table (the table this workspace bound the entity to, else an existing table of the same label, is ADOPTED and given the fields, options and views it lacks; no stored value changes), writes first rows only where every bound table is empty, and mints a new version of each app the model declares \u2014 `--app` (repeatable, comma-separated) narrows which apps, while the tables are applied whole. Prints one line per app \u2014 alias, `app_id`, `created`/`updated` with the version minted or `unchanged`, and the address it is served at \u2014 then the model's notes once, as the server states them. **`--plan` writes nothing and uploads nothing**: it prints what the apply would do to the tables (what it would create, what it leaves as the workspace has it, what the two disagree about), which apps it would create or update, and what it would refuse an app for \u2014 the decisions among its findings, read beside the workspace's rows, with each refused app's patch \u2014 exiting 1 when it would refuse one; workflow bodies are checked only at apply, since they name fields a plan has not created. **A rollback restores an app's earlier version** (`lotics run rollback_app`); table changes and data writes stay. Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, tables, apps, findings}` on stdout (with `--plan`, each table and app is what the apply would do, an app the patches change carrying its body as they leave it as `draft`, and `designs` each refused app's patch in merge order), or `{ok: false, findings}` when the file does not check. |\n| `lotics model pull [-o <model.json>]` | **This workspace's model, rebuilt from what owns each part** \u2014 the tables, fields, options, templates and roles the workspace holds, how rows are recognised, and each app's body from its current version \u2014 through the `get_model` tool, as the file `model apply` reads: to stdout, or to the file `-o` names. What the workspace holds that a model cannot state is printed on stderr, never written into the file. Applying what it wrote changes nothing. With `-o`, what it wrote is the copy the next `model apply` of that file reads its changes against. |\n| `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`), scaffolds a Vite + React + TypeScript project into `[path]` (default `./<name>`, refused when not empty \u2014 before the app row exists) that depends on `@lotics/app-sdk` alone and draws with plain React, and installs it (`npm install --ignore-scripts`), then writes the declarations of the app's live bindings (`get_app_types`) into `.lotics/`, which the project's `tsconfig.json` includes. `package.json#lotics` names the app and its workspace, which is how `app deploy` in that directory finds both. The app has no version until the first `lotics app deploy`. `--custom` is required: an app the runtime draws from a model is made by `lotics model apply`. The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the project. |\n| `lotics app pull [app_id] [path]` | **A custom-code app's live source, as a project ready to deploy on it.** The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** \u2014 but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`get_app_types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). A JSON app has no source tree: the server's refusal names `get_model`, and `lotics model pull` is its pull. |\n| `lotics app deploy [-m <message>]` | **Build this directory and upload it as a new version of the live app.** Rewrites `.lotics/` with the declarations of the app's live bindings (`get_app_types`, replacing each file there), then runs the project's `npm run typecheck` (warned about when absent) and `npm run build`, tars the source (without `node_modules`, `dist`, `.git`, `*.tsbuildinfo`) and `dist/`, and posts both to `POST /v1/apps/{id}/versions` on the version `package.json#lotics.current_version_id` names, then stamps the new one there. The version carries the app's queries, workflows, agents and capabilities forward unchanged \u2014 those are written through their tools. A project with no `build` script, or whose `package.json#lotics` still declares `queries`, `workflows`, `agents` or `capabilities`, is refused before anything is built; the refusal names the tool that sets each. **A 409 because another version went live since this directory's last deploy** (a deploy from elsewhere, a rollback) prints the server's sentence and the version that is live, and names `lotics app pull`: run in this directory, it brings an unedited project up to date, and lists the files a project with edits changed, to carry over into a fresh pull. `-m` (or a bare positional) is the version's message, optional. The workspace comes from `package.json#lotics.workspace_id` unless `--workspace` / `LOTICS_WORKSPACE` names another. |\n| `lotics docs` \\| `lotics docs <area>[/<section>]` \\| `lotics docs [<area>[/<section>]] --grep <text>` | **This CLI's own references, carried inside the binary** \u2014 the model reference, this index, and every doc under `docs/` \u2014 so the doc a reader opens describes the binary answering, listed by the job a reader comes to do. Capped at ONE PAGE: a doc that does not fit prints its opening and the addresses of what it holds (`lotics docs <area>/<section>`, each section's size beside it, or a table's row names), and every address prints within a page. **A reference the binary's copy lacks, or a part of one the server serves, is read from the server's `docs` tool** with this machine's credential, after the copy's refusal \u2014 a page the server added since this binary was built, which a server refusal can cite. A name matching more than one reference, or a part missing from a guide to this CLI, is answered by the copy alone. **`--grep` searches the references the server serves** (not this CLI's own guides, which it refuses), with this machine's credential, narrowed to the area or section named: literal text unless `--regex`, with `--case-sensitive`, `--diacritic-insensitive`, `--context-lines <n>` and `--limit <n>` \u2014 the dialect `grep_knowledge` reads \u2014 each hit under the address that opens its page; any of those options without `--grep` is refused. A custom-code app's SDK reference ships inside `@lotics/app-sdk` in the app's `node_modules`. |\n| `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script \u2014 the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe \u2014 a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |\n| `lotics docs model` \\| `lotics docs model/<section>[/\u2026]` | **The model reference, from inside the binary** \u2014 it describes this CLI's own model checker, at this CLI's version; `lotics docs` lists it under \"Build an app\", after `design`. Its first page is what a model composes with, the working order (jobs \u2192 entities and fields \u2192 `records` \u2192 one app per job \u2192 `model apply`) and the section addresses; every page of it is whole. Every top-level key of a `model.json`, every field `type` the contract admits with the config each one needs, the option / view / role / inline-template shapes, `records` (how a row of each entity is recognised), `write_rules`, `apps` (each register, record, act and check), the row format (relative dates `@today` / `@month-start` with whole-day offsets; links as `\"<entity-alias>:<ref>\"`), the rules, and one complete worked example; it points at `https://lotics.ai/presets/index.json` for complete example models of several trades. **Offline, no account.** |\n| `lotics report '<json>'` \\| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. **No severity or category.** Ingest is inline JSON, `@file`, or `-` for stdin. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` \u2014 invoking it IS the consent that passive collection needs an opt-in for \u2014 but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. **Prints the id of each frame filed** \u2014 a filing nobody can cite cannot be answered about. The ids come from the server, so an instance that only logs the frames prints the count alone; the CLI never mints one of its own, which would hand back a token that resolves to nothing. |\n\n";
+var cli_reference_default = "# @lotics/cli \u2014 CLI Command Reference\n\nPer-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. Start at [AGENTS.md](../AGENTS.md) for the model this reference assumes; `lotics --help` is the authoritative, always-current verb list.\n\n| Command | What it does |\n|---|---|\n| `lotics` / `lotics --help` | Show full help: capabilities, the verb list (\xA7 COMMANDS), flags, config. `lotics <verb> --help` prints that verb's entries alone (`lotics model --help`, `lotics file download --help`); `lotics report --help` prints the report frame. |\n| `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |\n| `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open \u2014 `https://lotics.ai/cli_login/<request_id>`, also mailed \u2014 and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential \u2014 `docs` among them \u2014 claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |\n| `lotics auth api-key [key]` | `whoami` \u2192 **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |\n| `lotics auth web` | Send a magic link email to access the web app (requires auth) |\n| `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key \u2014 read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |\n| `lotics auth logout [<name\\|id>]` | In a pinned dir: delete the local pin. Else: remove the profile (default the active org), `--all` for every one. What happens server-side depends on which KIND of credential it is. A **sign-in** (`auth login` / `auth signup`) is revoked \u2014 logging that terminal out ends its credential rather than leaving a live one behind; a server that cannot be reached, or a credential already dead, never blocks the local forget, and one line names the org and Settings \u2192 Security \u2192 *Keys and terminals*. An **API key** (`auth api-key`) is only forgotten here \u2014 an admin issued it and it is routinely on a server and on other machines, so one terminal signing out must not kill it for everyone; the line says it is still active and names both pages, because Settings \u2192 API keys is admin-only and the credential may well be the holder's own sign-in, which they revoke themselves at Settings \u2192 Security \u2192 *Keys and terminals*. A profile saved before the kind was recorded states nothing, so the SERVER is asked (`auth whoami`) and it is revoked only if the answer is a sign-in: an older server, a credential minted before the column, and a request that fails all leave it alone. |\n| \u2014 | **A refused credential says which of three ways it is dead, and names the remedy that ends its kind.** `This credential expired.` / `was revoked.` / `belongs to a member who is no longer active in this organization.` carries `Run \\`lotics auth login <email>\\` to sign in again.` for a sign-in and `Ask an admin for a new API key (Settings \u2192 API keys).` for an issued key. A credential minted before that was recorded still gets BOTH in one sentence, because nothing on the row tells them apart \u2014 so a headless box is never sent looking for a browser alone. A key the server does not recognize at all gets one flat `Invalid or disabled API key.` \u2014 deliberately, so a guessed key learns nothing, not even that it named a row. The body carries `reason` for a script to branch on, since the code stays `unauthorized` for every 401. |\n| `lotics org` | List saved orgs (profiles) from the global store with the instance each belongs to, marks active for this directory (a local pin wins over the global default). |\n| `LOTICS_ORG=<name\\|id>` | Scope every command in this shell to one saved org. **Resolved once, before any command dispatches**, so a value matching no saved credential refuses every verb with one sentence \u2014 a read, a write, and a local check that needs no credential alike \u2014 and refuses it before the first byte is written. It refuses even when a credential arrives another way, because `--api-key` / `LOTICS_API_KEY` outrank it in the precedence chain and a write must never fall through to whatever THOSE name while the variable says otherwise; when the variable resolves and a key is also given, the key decides and the command says so. The refusal lists the orgs this machine holds, so it is answerable without another command (`lotics org` is refused by the same rule). A name is whatever the credential was SAVED under \u2014 a server-side rename never moves it, and the new name resolves too, so both keep working and `lotics org` prints the pair. |\n| `lotics org use <name\\|id> [--local]` | Switch the active org by org name (case-insensitive, ambiguous \u2192 error) or id. No flag \u2192 global `active_org`; `--local` \u2192 a `.lotics/config.json` pointer in the current dir. |\n| `lotics workspace` | List workspaces in the active org, marks current with `(current)` |\n| `lotics workspace select <id>` | Set the workspace in the **active scope** \u2014 a local pin if the dir has one, else the active org's global profile. Records the workspace's NAME beside its id, which is what the `lotics \u2192 <org> / <workspace>` echo prints; `workspace list`, `workspace create`, `workspace rename` and `org use` record it too, so a target is named rather than identified. Until one command has listed it, the echo prints the id and says the name is not known yet. |\n| `lotics workspace create <name> [--timezone <Area/City>] [--currency <ISO>]` | Create a new workspace (admin only), auto-switches to it. Neither flag is defaulted from THIS machine, unlike signup: an extra workspace is routinely created by an operator for somebody else. Without `--timezone` the new workspace inherits the zone of the org's OLDEST workspace; without `--currency` it takes the org's default. Both ride the create, so the workspace is never briefly denominated in a currency nobody asked for. `--currency` takes an ISO-4217 code (case-insensitive; anything else is refused). |\n| `lotics workspace rename <name>` | Rename the **current** workspace (admin only) \u2014 the endpoint takes its target from the request's workspace, never a path id, so switch with `workspace select <id>` first and read the `lotics \u2192 <org> / <workspace>` echo before trusting it \u2014 both halves are names, and the rename moves the cached one in the same act. Carries the workspace's existing `default_currency` and `timezone` through unchanged: the endpoint takes the whole settings triple, so sending only a name would blank the other two. |\n| `lotics workspace settings [--name <n>] [--currency <ISO>] [--timezone <Area/City>]` | Change the CURRENT workspace's name, default currency or timezone \u2014 `PATCH /v1/workspace`, admin only. Only what you name changes; the endpoint takes the whole triple, so the CLI carries the two you did not. `rename` is this verb with the name alone, which is why it can never forget the other two. Both values are invisible once they are wrong: the currency decides how every money field RENDERS and the zone decides how every date BUCKETS, on a workspace whose whole purpose may be to look like the customer's own. `--json` prints the updated workspace. |\n| `lotics workspace delete <id> --yes` | Delete a workspace by id (admin only). **Soft delete** \u2014 `archived_at` is set, so it drops out of listings, can no longer be selected, and its tables/records go dark, while the data is retained and recoverable. Its **apps are cascade-archived** too \u2014 every app entry point (embedded, public link, standalone subdomain, incl. anonymous public links) stops serving. Refuses the org's **only** active workspace (400) and any workspace outside the caller's org (404). Requires `--yes` to confirm (destructive; the CLI is used non-interactively). |\n| `lotics workspace doctor` | Report workspace-wide dangling schema references via `GET /v1/workspaces/dangling-references` \u2014 every active app/workflow artifact whose prefixed schema id no longer resolves, printed as `<referent.kind> \"<name>\" (<id>) \u2192 <namespace> <id> (missing)`; healthy prints a one-line all-clear. **Exits non-zero (exit 1) on findings** so scripts can gate on it. Resolves the first workspace like every data command (runs before the global workspace resolution). Admin-only. |\n| `lotics tools` | List tools by category with descriptions |\n| `lotics tools <name>` | Full description + JSON Schema for one tool |\n| `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or stdin behind the `-` sentinel (`cat args.json \\| lotics run <tool> -`) \u2014 both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). **Stdin is asked for, never guessed.** `lotics run <tool>` with no payload runs the tool with no arguments and returns at once. `lotics report` takes the same sentinel. In PowerShell use `@file`: quotes inside an inline argument are consumed by the shell, and the CLI reports the JSON it received with its quotes gone \u2014 the error names both escapes. |\n| `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |\n| `lotics run <tool>` \u2014 **file cells** | A file in a tool's result carries its `fil_\u2026` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file \u2014 this surface resolves no URL for a cell. Reach the bytes with `lotics file download <file_id>`, which takes the id straight from the cell; the text output says so whenever a result carries one. |\n| \u2014 | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_agent`, `run_app_query`) and every one that changes an app (`set_app_queries`, `set_app_workflow`, `set_app_agent`, `update_app`, `rollback_app`). A command exists only for work that touches a local file: `model apply`, `model pull`, `app create --custom`, `app pull`, `app deploy`. |\n| \u2014 | **The exit code reports the WORK, not just the call \u2014 for the two tools that RUN one.** `run_app_workflow` and `run_app_agent` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`) exit non-zero and print `<tool> \u2192 <status>: <message>` to stderr, so `lotics run \u2026 && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE \u2014 an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` is data, and exits 0. |\n| `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |\n| `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes \u2014 harvested records **only**, never files / external calls / notifications. **Not a rollback**; a rollback is structurally impossible here. A partial cleanup exits non-zero so a script cannot read it as success. |\n| `lotics file upload <file\\|dir...>` (alias `lotics upload`) \xB7 `--stdin` \xB7 `--base64` \xB7 `--url <url>` | Upload files/directories. **The transport is chosen by size and is not a flag**: under 8 MiB the file is POSTed to `/v1/files` in one request, and several such files go in the same one; at or above it the CLI takes presigned part URLs and PUTs the bytes straight to object storage, so they never pass through the API. That threshold matches the AWS CLI's own `multipart_threshold`, and the number matters less than there being nothing to choose \u2014 one verb, any size, up to the 2 GiB a workspace may store. A large upload reads one part at a time, so memory stays flat regardless of file size, and a failure part-way abandons the parts already sent rather than leaving them billable and invisible. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** \u2014 an attachment decoded in memory, a generated document, a signed download link \u2014 each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY \u2014 `Buffer.from(s, \"base64\")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |\n| `lotics file download <file_id> [<path>]` \xB7 `-o <dir>` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` \u2192 fetch the presigned URL and write it where you asked. **The two spellings mean two different things, and neither is read by shape: the positional `<path>` is the FILE to write, `-o <dir>` is the DIRECTORY to save into.** That is `cp` and `curl -o`, so nothing here consults an extension. A named file is written as named, its parent created, overwriting what is there \u2014 the point of naming it is that the next command opens that exact path. A directory is created if missing and written into under the stored filename (the response's `Content-Disposition`), taking a free spelling beside a file of that name already there so a repeat download never clobbers the first; with no destination at all, that filename lands in cwd. Give the destination once \u2014 a positional and `-o` together is refused, as is a positional that names an existing directory or ends in a separator (`a directory goes in -o`). The first argument is a **file id**, so a path in that slot is refused rather than sent as an id. The written path goes to **stdout** (under `--json`, `{file_id, path, filename, stored_filename}`) and the narration to stderr, so a download pipes into whatever opens it. `lotics file download record <record_id> <field_key> [-o <dir>]` spreads every file on a record's file field over a DIRECTORY \u2014 there is no single file for N files to be. |\n| `lotics file list [--limit <n>] [--cursor <token>]` | The workspace's files, newest first \u2014 id, upload time, bytes, MIME type, filename on stdout, one per line (`--json` for the object). `GET /v1/files` with no `file_ids`. A file holding the content of a knowledge doc or template you cannot use is left out. **A page, not a dump**: the store only ever grows, so the last line prints the command for the next page and `next_cursor` is null on the last one. The cursor is opaque and keyset \u2014 pass it back as given \u2014 so an upload landing mid-sweep cannot make a walk skip or repeat a row. Every other file verb takes an id, so this is the only answer to \"what is in here\" short of reading Postgres. |\n| `lotics file delete <file_id>` | Archive a stored file, over the `delete_file` tool. **Refused while a record cell, a comment, a knowledge doc, a document template or a voice session still references it** \u2014 the refusal names the referents, so this is safe to try. The bytes are left in object storage; the row no longer serves them, which is what \"deleted\" means here. There is no `lotics delete`: the verb needs its noun. |\n| `lotics knowledge list [--include-hidden]` | `GET /v1/knowledge_docs` \u2014 a table of id, name, tags, description (`--json` for the docs). **REST, not the `list_knowledge` tool**: the tool answers what the ASSISTANT may browse, and a hidden doc is out of that corpus by definition, so a tool-backed listing could never show one and the person who hid it would have no way back to it. Hidden docs are left out unless `--include-hidden` asks; those rows are marked `(hidden)`. |\n| `lotics knowledge create --name <n> [--description <d>] [--tags <a,b>] (--from <file.md> \\| --content <str>)` | Read the body client-side (a file XOR an inline string \u2014 exactly one required), then call `create_knowledge` with `{ name, description, content, tags? }` (description defaults to `\"\"`). `--tags` files the doc as it is made, which is the only moment a corpus reliably gets labelled. Prints the new id to stdout. Large files ride the POST body fine. |\n| `lotics knowledge get <id> [-o <file.md>]` | `GET /v1/knowledge_docs/{id}` (`getKnowledgeDoc`) \u2192 the doc with its **hydrated `content`** (the one content-read path for a non-sandbox client). `-o` writes the body via `writeFileAtomic`; else the body goes to stdout. `--json` prints the full doc instead. |\n| `lotics knowledge update <id> [--from <file.md> \\| --content <str>] [--name <n>] [--description <d>] [--tags <a,b>]` | Call `update_knowledge` with **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). `--tags` REPLACES the doc's label set \u2014 the single-doc form, where the caller is looking at one doc and can state what it should carry. At least one field required; --from and --content are mutually exclusive. |\n| `lotics knowledge tag <id...> [--add <a,b>] [--remove <c,d>]` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, add_tags?, remove_tags? }` \u2014 one transaction over the whole set. A **DIFF applied to each doc's own labels**, never a replacement: the docs named on one command line carry different labels, so one array across them would strip whatever the others were filed under. Removal matches case-insensitively; adding a label a doc already carries writes nothing. Ids may be separate arguments or comma-separated. At least one of --add/--remove required. |\n| `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** \u2014 the Library's list, `list_knowledge`, and the corpus `grep_knowledge` searches \u2014 while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as \"everything\". |\n| `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |\n| `lotics setup <model.json> [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes \u2014 `--name` and `--timezone` apply), then applies the model to its workspace, then prints the one-time sign-in link. **When that email already has an account it hands over to the `lotics auth login` flow** \u2014 it prints the sign-in page to open and the code it must show, and **exits 1 having created nothing**; the person presses Confirm and runs the same command again, which collects the key and carries on into the model. (`--wait` holds the terminal through the Confirm instead, finishing in one command.) The re-run is not refused for naming an `--email` it is now signed in as \u2014 that address IS the account it holds, not a second one. The file is a workspace MODEL, and it is read and checked before an account is created \u2014 the design decisions an apply would refuse it for too (`lotics docs design`), since a new workspace holds no rows to change them \u2014 because a file with a typo in it must not leave an organization behind. Then it is `lotics model apply` run on the new workspace: its tables, rows and apps; the sign-in link lands on its app when it has one, else on the workspace's app list. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently writes into an org the caller did not name \u2014 the message says how to do each thing on purpose. Without it, `setup` applies the model to the account you already have. A path positional after the file is accepted and IGNORED with a warning \u2014 `setup` writes nothing to disk \u2014 so a prompt that passes one still runs. **`--json` prints one object on stdout and nothing else** \u2014 what `lotics model apply --json` does (`tables`; `apps`, each with `alias`, `app_id`, `version_id`, `origin`, `address` and `findings`; and `findings`) plus `organization_id`, `workspace_id` and `signin_url`, and a `warnings` array carrying everything the prose form would have said out of band, such as a sign-in link that could not be minted. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. Reachable with no install: `npx -y @lotics/cli setup \u2026`. |\n| `lotics model apply <model.json> [--app <alias> ...] [--plan] [--json]` | **The model, applied to this workspace, through the `apply_model` tool.** The file is read and checked against the model's own rules with the validator the server runs, every problem in one run, before anything is uploaded. **The apply refuses an app leaving out a treatment its rows call for** (`lotics docs design`) \u2014 judged by the server beside the workspace's rows, before it writes anything \u2014 until the app adopts it or states why not under the `declines` key the refusal names; the refusal carries each refused app's patch adopting its decisions, to merge in the order printed. Documents a row attaches by a path beside the file are uploaded first and the rows sent with their `fil_` ids; a path this workspace already recorded keeps its id, so a re-apply uploads nothing twice. **Where the file was pulled (`-o`) or applied in this workspace before, only what it changed since is sent**, as a `patch`: what changed in the workspace since and the file does not touch stays. What the file takes out is sent as a removal: it goes where an apply rebuilds it (an app's acts and columns, a write rule) and is refused, naming the tool that deletes it, where an apply never deletes it (a table, a field, an option, an app). A file that reorders items named by their `alias`, or states a `null` a patch would read as a removal, sends the whole model, said on stderr. The copy each change is read against is kept per workspace and file under `~/.lotics/model_bases`: an apply narrowed by `--app` leaves in it the other apps as they were, so the next apply sends their edits again, and an apply that fails \u2014 refused, or cut off \u2014 leaves none, so the next sends the whole model. Then the tool adopts or creates every table (the table this workspace bound the entity to, else an existing table of the same label, is ADOPTED and given the fields, options and views it lacks; no stored value changes), writes first rows only where every bound table is empty, and mints a new version of each app the model declares \u2014 `--app` (repeatable, comma-separated) narrows which apps, while the tables are applied whole. Prints one line per app \u2014 alias, `app_id`, `created`/`updated` with the version minted or `unchanged`, and the address it is served at \u2014 then the model's notes once, as the server states them. **`--plan` writes nothing and uploads nothing**: it prints what the apply would do to the tables (what it would create, what it leaves as the workspace has it, what the two disagree about), which apps it would create or update, and what it would refuse an app for \u2014 the decisions among its findings, read beside the workspace's rows, with each refused app's patch \u2014 exiting 1 when it would refuse one; workflow bodies are checked only at apply, since they name fields a plan has not created. **A rollback restores an app's earlier version** (`lotics run rollback_app`); table changes and data writes stay. Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, tables, apps, findings}` on stdout (with `--plan`, each table and app is what the apply would do, an app the patches change carrying its body as they leave it as `draft`, and `designs` each refused app's patch in merge order), or `{ok: false, findings}` when the file does not check. |\n| `lotics model pull [-o <model.json>]` | **This workspace's model, rebuilt from what owns each part** \u2014 the tables, fields, options, templates and roles the workspace holds, how rows are recognised, and each app's body from its current version \u2014 through the `get_model` tool, as the file `model apply` reads: to stdout, or to the file `-o` names. What the workspace holds that a model cannot state is printed on stderr, never written into the file. Applying what it wrote changes nothing. With `-o`, what it wrote is the copy the next `model apply` of that file reads its changes against. |\n| `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`), scaffolds a Vite + React + TypeScript project into `[path]` (default `./<name>`, refused when not empty \u2014 before the app row exists) that depends on `@lotics/app-sdk` alone and draws with plain React, and installs it (`npm install --ignore-scripts`), then writes the declarations of the app's live bindings (`get_app_types`) into `.lotics/`, which the project's `tsconfig.json` includes. `package.json#lotics` names the app and its workspace, which is how `app deploy` in that directory finds both. The app has no version until the first `lotics app deploy`. `--custom` is required: an app the runtime draws from a model is made by `lotics model apply`. The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the project. |\n| `lotics app pull [app_id] [path]` | **A custom-code app's live source, as a project ready to deploy on it.** The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** \u2014 but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`get_app_types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). A JSON app has no source tree: the server's refusal names `get_model`, and `lotics model pull` is its pull. |\n| `lotics app deploy [-m <message>]` | **Build this directory and upload it as a new version of the live app.** Rewrites `.lotics/` with the declarations of the app's live bindings (`get_app_types`, replacing each file there), then runs the project's `npm run typecheck` (warned about when absent) and `npm run build`, tars the source (without `node_modules`, `dist`, `.git`, `*.tsbuildinfo`) and `dist/`, and posts both to `POST /v1/apps/{id}/versions` on the version `package.json#lotics.current_version_id` names, then stamps the new one there. The version carries the app's queries, workflows, agents and capabilities forward unchanged \u2014 those are written through their tools. A project with no `build` script, or whose `package.json#lotics` still declares `queries`, `workflows`, `agents` or `capabilities`, is refused before anything is built; the refusal names the tool that sets each. **A 409 because another version went live since this directory's last deploy** (a deploy from elsewhere, a rollback) prints the server's sentence and the version that is live, and names `lotics app pull`: run in this directory, it brings an unedited project up to date, and lists the files a project with edits changed, to carry over into a fresh pull. `-m` (or a bare positional) is the version's message, optional. The workspace comes from `package.json#lotics.workspace_id` unless `--workspace` / `LOTICS_WORKSPACE` names another. |\n| `lotics docs` \\| `lotics docs <area>[/<section>]` \\| `lotics docs [<area>[/<section>]] --grep <text>` | **This CLI's own references, carried inside the binary** \u2014 the model reference, this index, and every doc under `docs/` \u2014 so the doc a reader opens describes the binary answering, listed by the job a reader comes to do. Capped at ONE PAGE: a doc that does not fit prints its opening and the addresses of what it holds (`lotics docs <area>/<section>`, each section's size beside it, or a table's row names), and every address prints within a page. **A reference the binary's copy lacks, or a part of one the server serves, is read from the server's `docs` tool** with this machine's credential, after the copy's refusal \u2014 a page the server added since this binary was built, which a server refusal can cite. A name matching more than one reference, or a part missing from a guide to this CLI, is answered by the copy alone. **`--grep` searches the references the server serves** (not this CLI's own guides, which it refuses), with this machine's credential, narrowed to the area or section named: literal text unless `--regex`, with `--case-sensitive`, `--diacritic-insensitive`, `--context-lines <n>` and `--limit <n>` \u2014 the dialect `grep_knowledge` reads \u2014 each hit under the address that opens its page; any of those options without `--grep` is refused. A custom-code app's SDK reference ships inside `@lotics/app-sdk` in the app's `node_modules`. |\n| `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script \u2014 the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe \u2014 a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |\n| `lotics docs model` \\| `lotics docs model/<section>[/\u2026]` | **The model reference, from inside the binary** \u2014 it describes this CLI's own model checker, at this CLI's version; `lotics docs` lists it under \"Build an app\", after `design`. Its first page is what a model composes with, the working order (jobs \u2192 entities and fields \u2192 `records` \u2192 one app per job \u2192 `model apply`) and the section addresses; every page of it is whole. Every top-level key of a `model.json`, every field `type` the contract admits with the config each one needs, the option / view / role / inline-template shapes, `records` (how a row of each entity is recognised), `write_rules`, `apps` (each register, record, act and check), the row format (relative dates `@today` / `@month-start` with whole-day offsets; links as `\"<entity-alias>:<ref>\"`), the rules, and one complete worked example; it points at `https://lotics.ai/presets/index.json` for complete example models of several trades. **Offline, no account.** |\n| `lotics report '<json>'` \\| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. **No severity or category.** Ingest is inline JSON, `@file`, or `-` for stdin. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` \u2014 invoking it IS the consent that passive collection needs an opt-in for \u2014 but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. **Prints the id of each frame filed** \u2014 a filing nobody can cite cannot be answered about. The ids come from the server, so an instance that only logs the frames prints the count alone; the CLI never mints one of its own, which would hand back a token that resolves to nothing. |\n\n";
 
 // docs/data_model.md
 var data_model_default = '# The data model \u2014 tables, their fields, and how they relate\n\nThe decisions here outlive any one app, and most become expensive the moment a second screen depends\non them. They stand apart from building an app on purpose: **every workspace starts with tables\nand many never get an app**, so schema design is not a chapter of app building.\n\nThe rules below share one signature. **Both sides read correctly on their own**, so nothing reports\nthe problem \u2014 no error, no empty column, no failing query. Each is found by looking for it. Then,\nunder **Fields**, what each field type takes.\n\n## One fact, one column\n\n**Read the table\'s existing fields first, and add nothing that stores a fact the table already\nstores.** A value written as text and the same value held as a `select_record_link` are one fact in\ntwo columns \u2014 a customer\'s city typed into a text box beside a link to the city record, a status\nword beside the select that decides it, a total beside the formula that computes it.\n\nTwo columns for one fact do not stay equal. Some writer sets only one of them, and nothing reports\nthe divergence: both rows still look correct on their own. A reader that then matches on the text\nhalf treats "Acme" and "Acme Ltd" as different records, so an import creates a duplicate every time\nit runs.\n\n- **Prefer the link, the select, or the formula.** Text is a RENDERING of a record; compose it when\n  you read, rather than storing it a second time.\n- **Renaming, retyping or re-pointing the existing field beats adding another.** A field\'s key is\n  stable, so a rename breaks nothing that addresses it by key.\n- **Superseding a field means DELETING it**, not leaving it beside its replacement with a\n  description that says which one is real.\n- **Empty is not the same as redundant.** A field nothing fills may still be the only home for a\n  real distinction \u2014 read what it MEANS before removing it.\n\n## One entity, one table \u2014 and the test is measurable\n\nVariation belongs in a column \u2014 a multi-select role, a kind, a stage \u2014 not in a second table. Two\ntables for one kind of thing give the same real-world entity two rows, two ids and two halves of its\nhistory, and each screen shows whichever half it happens to link to.\n\nSplit tables are often right. A supplier book beside a customer book is a normal shape, and merging\non suspicion is a large repoint bought for nothing. So do not argue it in the abstract:\n\n> **List both tables\' names and look for one that appears in both.**\n\nNone means the split is holding. One means it has broken \u2014 the usual cause is a party you begin to\ninvoice as well as buy from \u2014 and the fix is to merge before a second screen depends on the copy.\n\nWorth writing as a test rather than a note, because a note about a condition nobody re-checks goes\nstale in silence.\n\n## One vocabulary wherever values are COPIED between tables\n\nTwo `select` fields for one concept carry DIFFERENT option keys even when their labels match \u2014 keys\nare minted per field. So anything moving a value between them needs a hand-written key map.\n\nThat map is code. Put it in one named module with a test; written inline at the copy it is invisible,\nuntested, and silently wrong the first time somebody renames an option, because a rename leaves the\nkey intact and the map still compiling. Prefer a link to a shared reference table where the set is\nopen or growing; keep a map only for a small closed set.\n\nWhere one side genuinely holds MORE values than the other, that is not drift \u2014 it is the model\ntelling the truth. The wider side must **refuse** what the narrower one cannot express rather than\nquietly picking the nearest value.\n\n## A copy boundary accounts for EVERY source field\n\nEach field on the source gets a column on the destination, a deliberate drop with the reason written\ndown, or a refusal.\n\nA field with nowhere to land is data destroyed at the boundary, and it is invisible afterwards: the\ndestination is not empty and not obviously wrong \u2014 just a number that no longer agrees with where it\ncame from.\n\n## Provenance is a LINK, not a flag and not a copy\n\nA row created BY another row carries a link to it.\n\nThat link is what makes "is this the estimate or the actual", "where did this come from" and "have we\nalready imported this" answerable at all. A boolean records that something was true once; a link\nstays true, survives a rename, and lets the next write UPDATE the original instead of adding a second\nrow beside it.\n\n## Say what makes two rows the SAME row\n\nDeclare the natural key in the table\'s description.\n\nAnything that imports, reconciles or de-duplicates has to decide identity, and with no declared key\nit falls back to comparing displayed text \u2014 which is how one company arrives three times under three\nspellings. Name the key: a reference number, a tax id, a link plus a period. Then match on `rec_\u2026`\nand `opt_\u2026`, never on rendered labels.\n\n## A state\'s HISTORY is rows, not columns\n\nA `changed at` column says only how long a row has been where it is now \u2014 the next move overwrites\nit \u2014 and a date column per state holds until something re-enters a state it already left.\n\nMeasuring time-in-state or conversion needs one ROW per move: a link to the subject, the state left,\nthe state entered, when. Hold those states as the source field\'s own `opt_` keys so the log carries\nno second vocabulary, and write the rows from that table\'s own lifecycle workflows, which covers\nevery writer rather than one app\'s.\n\n## Keep derived chains shallow\n\nFormulas and rollups are computed and STORED when a row is written, and one that reads another\nrecomputes with it. A rollup over a formula over a formula is paid three times on every touch, and\nagain for every row upstream of it.\n\n**Depth costs more than row count.** This is the optimisation lever that actually exists here; row\nscanning is the platform\'s problem, chain depth is yours.\n\n## Changing a money formula on a live table\n\nFormula edits recompute every row, so the only honest proof that one changed nothing it should not is\nthe numbers themselves:\n\n1. Snapshot the affected totals to a file.\n2. Make the change.\n3. Diff. Identical is the pass.\n\nAnd when a formula gains a new field, **test that the value IS the one you want, never that it\ndiffers from it** \u2014 an empty cell reads as `""`, which differs from every option key, so the inverted\nspelling silently zeroes every row written before the field existed.\n\n## Fields\n\nWhat `create_table` (on the CLI or in chat) and `update_table` take in `add_fields`, and `update_table` in `update_fields`.\n\n### Types and formats\n\n`type` is one of `text`, `number`, `date`, `boolean`, `select`, `select_member`,\n`select_record_link`, `files`, `formula`, `rollup`, `lookup`, `autonumber`. `button` is retired: an\nexisting button field keeps running, but none is created, converted to or edited.\n\nA URL, an email, markdown, a checkbox, a datetime, a currency or a percentage is a `format` on\nanother type, never a `type`:\n\n| Wanted | Field |\n|---|---|\n| URL or external link | `{ type: "text", format: "link" }` |\n| Email or phone | `{ type: "text" }` |\n| Markdown | `{ type: "text", format: "markdown" }` |\n| Checkbox | `{ type: "boolean" }` |\n| Money | `{ type: "number", format: "currency", currency: "USD" }` |\n| Percentage | `{ type: "number", format: "percentage" }` |\n| Datetime | `{ type: "date", format: "datetime" }` |\n| Date range | `{ type: "date", format: "date_range" }` |\n\n### Properties\n\nA type\'s properties sit **directly on the field object** \u2014 there is no `config` wrapper. A property\nmay itself hold an object (`formula`, `aggregate_option`, `filter`, `order_by`); its inner keys stay\ninside it. Each type takes only its own:\n\n- **text** \u2014 `format?` (`"text"` | `"link"` | `"markdown"`), `unique?`, `default_value?` (a string).\n- **number** \u2014 `format?` (`"number"` | `"currency"` | `"percentage"`), `currency?` (an ISO 4217\n  code), `unit?`, `unit_field?`, `currency_field?`, `default_value?` (a number). On `update_fields`,\n  null clears `currency`, `unit`, `unit_field` or `currency_field`.\n  - `unit`, beside format `"number"`: a measured code \u2014 g, kg, t, l, m3, cbm, mm, cm, m, km, m2,\n    min, h, day \u2014 or a counted noun such as `ki\u1EC7n`. A change between two units of one dimension\n    converts every stored figure; any other change relabels.\n  - `unit_field`: A single select on the same row, or a lookup of one through a one-link, whose chosen option is that row\'s unit: every option label is a unit as `unit` takes one. In place of `unit`; only beside format "number".\n  - `currency_field`: A single select on the same row, or a lookup of one through a one-link, whose chosen option is that row\'s currency: every option label is an ISO 4217 code. In place of `currency`; only beside format "currency".\n- **date** \u2014 `format?` (`"date"` | `"datetime"` | `"date_range"` | `"datetime_range"`), `timezone?`,\n  `derive_from?`, `default_value?` (a date string). `derive_from: "created_at"` stamps the row\'s\n  creation once, `"updated_at"` re-stamps on every update; the field is then read-only, takes no\n  `default_value`, and holds only the `date` and `datetime` formats.\n- **boolean** \u2014 `default_value?` (`true` | `false`).\n- **select** \u2014 `options` `[{ name, color?, mark? }]`, `multi?`, `default_value?`.\n- **select_member** \u2014 `multi?`, `default_value?` (member ids).\n- **select_record_link** \u2014 `table_id`, `display_field_keys?`, `sync_both_ways?`, `cardinality?`,\n  `paired_field_name?`, `paired_field_display_field_keys?`. Without `display_field_keys` a link shows\n  the target\'s autonumber, else its first text field. `sync_both_ways: true` on an existing one-way\n  link makes it two-way \u2014 never add a second link for that. `cardinality: "one"` marks the child\n  side of a parent-child pair (the linked record is this one\'s parent); two paired sides cannot both\n  be `"one"`. The `paired_*` keys name and label the back-reference the target gets.\n- **files** \u2014 no properties.\n- **autonumber** \u2014 `template` (`"INV-{YEAR}-{N:4}"`; tokens `{N}`, `{N:W}` zero-padded to W,\n  `{YEAR}`, `{YEAR:2}`, `{MONTH}`, `{DAY}`), or `prefix` + `padding` (1\u201320) for `PREFIX-0001`.\n- **any type**, at create \u2014 `confirm_before_update?`: a person confirms each later edit.\n\n`default_value` fills the field on a NEW record that states no value; existing records are never\nbackfilled, and null clears it. A select\'s or a member field\'s default is an ARRAY even when the\nfield holds one (`["Unread"]`, never `"Unread"`) \u2014 option names in `add_fields`, where the keys do\nnot exist yet, and option keys (`opt_\u2026`) in `update_fields`.\n\n### Computed fields\n\nRead-only in records. `formula` is one key holding an object; a rollup\'s and a lookup\'s properties\nare separate keys on the field \u2014 `rollup: {\u2026}` and `lookup: {\u2026}` are refused as unrecognized.\n\nformula: { expression, format?, currency?, unit?, unit_field?, currency_field? }\n\n- `{Field Name}` or `{fld_key}` names a field of the same table, stored as its key, so a rename never\n  breaks the formula. A reference to no field, or a call to something that is no helper, is refused.\n- A select reads as an ARRAY of option keys: `{Status}[0]` for a single select,\n  `includes({Tags}, "opt_\u2026")` for a multi.\n- The operators, the helpers and how an empty cell reads are the `model` reference, section `formula` \u2014 a model\n  names fields by alias where a table tool names them by name or key; the language is the same.\n- On `update_fields` a key left out keeps its stored value, and null clears `currency`, `unit`,\n  `unit_field` or `currency_field`. `get_table` marks a formula that is null when every field it\n  reads is empty.\n\nrollup \u2014 `source_field_key`, `aggregate_option: { field_key?, operation }`, `filter?`\n\n- `source_field_key` is a `select_record_link` of this table; `aggregate_option.field_key` is a\n  field of the linked table, required by every operation but `count`, which counts linked records.\n- Operations by the aggregated field\'s type \u2014 none: `count`; any: `empty`, `filled`,\n  `percent_empty`, `percent_filled`, `unique`, `percent_unique`; number: `sum`, `avg`, `median`,\n  `min`, `max`, `range`; date: `earliest`, `latest`, `date_range`.\n- The cell\'s type comes from the OPERATION: `earliest` and `latest` hold a date, every other\n  operation a number (`date_range` counts days). A "most recent linked date" is `latest` \u2014 `min` and\n  `max` are numeric and refuse a date. A rollup takes no format, currency or unit of its own: `sum`\n  over money carries the aggregated field\'s currency, over a weight its unit.\n- Over a figure read in each row\'s own unit or currency (`unit_field` / `currency_field`), `sum`,\n  `avg`, `median`, `min`, `max` and `range` hold only where that select is a lookup, through the\n  link paired with `source_field_key`, of a single select on this table \u2014 the total reads in this\n  row\'s option of it. A lookup of such a field has no unit.\n- `filter` aggregates only the linked records it matches: a full group over the LINKED table\'s\n  fields \u2014 `{ node_type: "group", logic, children: [{ node_type: "condition", type, field_key,\n  operator, value }] }`, a select condition using `has_any_of` with an ARRAY value.\n\nlookup \u2014 `source_field_key`, `lookup_field_key`, `order_by?`\n\n- `lookup_field_key` is a field of the linked table. Without `order_by` the cell holds every linked\n  record\'s value; with `order_by: { field_key, direction }` (`desc` latest, `asc` earliest) it holds\n  the picked field of the single extreme record \u2014 a "latest linked X" that maintains itself.\n  Ordered lookups sharing one `order_by` resolve to the SAME record.\n\n### Examples\n\n```\n{ name: "Gi\xE1 b\xE1n", type: "number", format: "currency", currency: "VND" }\n{ name: "Tr\u1ECDng l\u01B0\u1EE3ng", type: "number", unit: "kg" }\n{ name: "S\u1ED1 l\u01B0\u1EE3ng", type: "number", unit_field: "\u0110VT" }\n{ name: "Tr\u1EA1ng th\xE1i", type: "select", options: [{ name: "M\u1EDBi" }, { name: "Xong" }] }\n{ name: "M\xE3 \u0111\u01A1n", type: "autonumber", template: "SR-{YEAR}-{N:4}" }\n{ name: "Kh\xE1ch h\xE0ng", type: "select_record_link", table_id: "tbl_x", sync_both_ways: true }\n{ name: "Total", type: "formula", formula: { expression: "{Price} * {Qty}", format: "currency", currency: "VND" } }\n{ name: "SL \u0111\xE3 giao", type: "rollup", source_field_key: "Giao h\xE0ng", aggregate_option: { operation: "sum", field_key: "S\u1ED1 l\u01B0\u1EE3ng" } }\n{ name: "Customer Name", type: "lookup", source_field_key: "Customer", lookup_field_key: "Name" }\n{ name: "Latest note", type: "lookup", source_field_key: "Calls", lookup_field_key: "Note", order_by: { field_key: "At", direction: "desc" } }\n```\n\n### Changing a field\n\nA field added by `update_table` shows in a view only when `add_to_views` names it, at the view\'s far\nright; on the CLI or in chat, `update_view` with `move_field` places it beside the columns it belongs with.\n\nAn `update_fields` entry is `{ field_key, name?, description?, convert_to?, \u2026 }` with the same flat\nproperties as `add_fields`, plus what only an update does:\n\n- A select\'s options change through `add_options` `[{ name, color?, mark? }]`, `update_options`\n  `[{ key, name?, color?, mark? }]`, `remove_option_keys` and `reorder_options` (every existing\n  option once, in order; options added in the same call follow). An option is named by its `opt_\u2026`\n  key (its name also resolves); a rename keeps every record\'s value. `mark` is the option\'s brand\n  (`{ kind: "brand", name: "tiktok" }`) or kit glyph (`{ kind: "icon", name: "wrench" }`), drawn in\n  place of its colour dot \u2014 every option of a field has one or none does, so marking sets them all\n  in one call and `mark: null` on each clears them.\n- A link\'s `sync_both_ways: false` disconnects the pair; a new `table_id` re-points it and clears its\n  record data; `cardinality` is `"one"` for the child side of a parent-child pair, `"many"` for peers.\n';
@@ -41677,7 +41677,7 @@ var data_model_default = '# The data model \u2014 tables, their fields, and how
 var filters_default = '# Filters \u2014 choosing records by their fields\n\nOne grammar for every tool that takes a filter: `query_records`, `aggregate_records`, `update_records`\nand `delete_records` by filter, a view\'s filter, a rollup\'s filter, and the filters a caller passes\nto an app\'s query.\n\n## The shape\n\nA filter is a single condition, or a group of conditions.\n\n```\n{ "node_type": "condition", "field_key": "Status", "operator": "has_any_of", "value": ["Done"] }\n{ "node_type": "group", "logic": "and" | "or", "children": [ \u2026conditions or groups ] }\n```\n\nGroups nest up to 4 levels. AND(OR(status = A, status = B), age > 40):\n\n```\n{ "node_type": "group", "logic": "and", "children": [\n  { "node_type": "group", "logic": "or", "children": [cond1, cond2] },\n  cond3\n] }\n```\n\nEvery `field_key` resolves against the table being filtered \u2014 read each table\'s fields (`get_table`)\nand carry no name across tables: sibling tables holding the same concept routinely name it\ndifferently. A field is named by its `fld_\u2026` key or by its name (`"Status"`).\n\n## Text\n\n| Operators | Value |\n|---|---|\n| `equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with` | a string |\n| `is_any_of`, `is_none_of` | a string array \u2014 exact, case-insensitive |\n| `contains_any_of` | a string array \u2014 the cell contains any of them, case- and accent-insensitive |\n| `is_empty`, `is_not_empty` | none |\n\n```\n{ "node_type": "condition", "field_key": "Title", "operator": "is_any_of", "value": ["hello", "world"] }\n```\n\nA text value is a string, never an array; `is_any_of` matches several. Its array has no length cap \u2014\npass the whole list in one condition rather than splitting it across calls.\n\n## Number\n\n| Operators | Value |\n|---|---|\n| `equals`, `not_equals`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to` | a number |\n| `is_empty`, `is_not_empty` | none |\n\nA number whose field states `unit_field` or `currency_field` is read in each row\'s own unit or\ncurrency, so a comparison on it states `unit_option`: the option of that select its value is in.\nRows holding another option are out; measured units of one dimension convert.\n\n```\n{ "node_type": "condition", "field_key": "Amount", "operator": "greater_than", "value": 100, "unit_option": "USD" }\n```\n\n## Boolean\n\n`equals` with `true` or `false`.\n\n## Select\n\n| Operators | Value |\n|---|---|\n| `has_any_of` (any of them \u2014 "A or B"), `has_none_of`, `has_all_of` (a multi-select only) | an ARRAY of option names, even for one |\n| `is_empty`, `is_not_empty` | none |\n\n```\n{ "node_type": "condition", "field_key": "Status", "operator": "has_any_of", "value": ["Done", "In Progress"] }\n```\n\n## Member\n\n| Operators | Value |\n|---|---|\n| `has_any_of`, `has_none_of`, `has_all_of` | an array of member ids |\n| `is_current_member`, `is_not_current_member`, `is_empty`, `is_not_empty` | none |\n\n## Date\n\n| Operators | Value |\n|---|---|\n| `before`, `after`, `on_or_before`, `on_or_after`, `on`, `starts_before`, `starts_after`, `ends_before`, `ends_after` | a point |\n| `between`, `overlaps`, `contains`, `within` | `{ start: point \\| null, end: point \\| null }` |\n| `time_of_day` | `{ start_time: "HH:mm" \\| null, end_time: "HH:mm" \\| null }` |\n| `duration_equals`, `duration_greater_than`, `duration_less_than` | `{ amount, unit: "minutes" \\| "hours" \\| "days" }` |\n| `is_empty`, `is_not_empty` | none |\n\nA point is one of:\n\n```\n{ "type": "exact", "date": "2025-03-14", "time": "09:00" }                       time optional\n{ "type": "relative", "offset": -7, "unit": "minutes" | "hours" | "days" | "weeks" | "months" | "years" }\n{ "type": "period", "period": "day" | "week" | "month" | "quarter" | "year", "boundary": "start" | "end", "offset": 0 }\n```\n\n## Link\n\n| Operators | Value |\n|---|---|\n| `has_any_of` (linked to any \u2014 filters by record identity), `has_none_of`, `has_all_of` (a multi-link only) | an array of record ids (`rec_\u2026`) |\n| `contains`, `not_contains`, `starts_with`, `ends_with` | a string, matched against the linked record\'s display text |\n| `is_empty`, `is_not_empty` | none |\n\n```\n{ "node_type": "condition", "field_key": "Customer", "operator": "has_any_of", "value": ["rec_abc123"] }\n```\n\n## Sort\n\nA view\'s sort is a list, applied in order: `[{ "field_key": "Due", "order": "asc" | "desc" }]`.\n';
 
 // docs/field_values.md
-var field_values_default = '# Field values \u2014 what a write takes for each field type\n\nThe value `create_records` and `update_records` take for a field.\n\n## Values by type\n\n| Type | Value |\n|---|---|\n| `text` | `"hello"` |\n| `number` | `42` |\n| `boolean` | `true` |\n| `date` | `"2025-03-14"`, or a month `"2025-03"` or a year `"2025"`, stored as written and compared as its first day |\n| `datetime` | a `date` of this format: `"2025-03-14T09:00"`, never a month or a year |\n| `date_range` | a `date` of this format: `"2025-03-01/2025-03-15"`, both halves full dates |\n| `datetime_range` | a `date` of this format: `"2025-03-01T09:00/2025-03-15T17:00"`, both halves full |\n| `select` | `["opt_\u2026"]` |\n| `select_member` | `["mbr_\u2026"]` |\n| `select_record_link` | `["rec_\u2026"]` |\n| `files` | `["fil_\u2026"]`, ids of uploaded files |\n| `formula`, `rollup`, `lookup`, `autonumber`, a `date` with `derive_from` | none \u2014 the platform writes them, and a write naming one is refused |\n\n## Lists\n\n`select`, `select_member`, `select_record_link` and `files` store an ARRAY, even where the field holds\none value.\n\n- A single-select is a ONE-element array; a bare `"opt_\u2026"` is accepted and wrapped. A single\n  `select_member` takes a bare `"mbr_\u2026"` the same way.\n- `select_record_link` and `files` take an array only.\n- Two options on a single-select, or two members on a single `select_member`, are refused.\n- `update_records`\' `add_to`, `remove_from` and `replace` take arrays of the same items: `opt_` keys\n  for a select, member ids for a `select_member`, record ids for a `select_record_link`, file ids for\n  `files`.\n';
+var field_values_default = '# Field values \u2014 what a write takes for each field type\n\nThe value `create_records` and `update_records` take for a field.\n\n## Values by type\n\n| Type | Value |\n|---|---|\n| `text` | `"hello"` |\n| `number` | `42` |\n| `boolean` | `true` |\n| `date` | `"2025-03-14"`, or a month `"2025-03"` or a year `"2025"`, stored as written and compared as its first day |\n| `datetime` | a `date` of this format: `"2025-03-14T09:00"`, never a month or a year |\n| `date_range` | a `date` of this format: `"2025-03-01/2025-03-15"`, both halves full dates |\n| `datetime_range` | a `date` of this format: `"2025-03-01T09:00/2025-03-15T17:00"`, both halves full |\n| `select` | `["opt_\u2026"]` |\n| `select_member` | `["mbr_\u2026"]` |\n| `select_record_link` | `["rec_\u2026"]` |\n| `files` | `["fil_\u2026"]`, ids of uploaded files |\n| `formula`, `rollup`, `lookup`, `autonumber`, a `date` with `derive_from` | none \u2014 the platform writes them, and a write naming one is refused |\n\n## Lists\n\n`select`, `select_member`, `select_record_link` and `files` store an ARRAY, even where the field holds\none value.\n\n- A single-select is a ONE-element array; a bare `"opt_\u2026"` is accepted and wrapped. A single\n  `select_member` takes a bare `"mbr_\u2026"` the same way.\n- `select_record_link` and `files` take an array only.\n- A `files` id the write adds must name a live file of this workspace, or the whole write is refused;\n  an id that cell already holds stays, though its file was archived since.\n- Two options on a single-select, or two members on a single `select_member`, are refused.\n- `update_records`\' `add_to`, `remove_from` and `replace` take arrays of the same items: `opt_` keys\n  for a select, member ids for a `select_member`, record ids for a `select_record_link`, file ids for\n  `files`.\n';
 
 // docs/workflows.md
 var workflows_default = '# Workflows \u2014 the steps a workflow runs\n\nA workflow is written as a strict subset of JavaScript. The source is never run as JavaScript: a\nsave parses it into steps, type-checks it against what its trigger supplies, and stores the steps.\nOnly the forms below are accepted; anything else is refused at save with the line, the column and\nwhat to write instead. A save that succeeds may still return `warnings` \u2014 advisory hints such as a\nloop that may never end. Read them.\n\nThe same grammar serves an automation, a table\'s lifecycle workflow and an app\'s workflow. Only an\nautomation\'s source opens with a trigger declaration; a lifecycle workflow takes its trigger from its\ntable and event, an app workflow from the app that calls it.\n\n## Triggers\n\nAn automation answers an event outside the records: a schedule, a webhook, an inbound email. A\nreaction to a record being created, updated or deleted is a table lifecycle workflow (see\n**Table lifecycle workflows**).\n\n```\non({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });\n```\n\nEvery source below is typed, so a misspelled member is refused at save rather than read as nothing.\nAll three carry `trigger.trigger_id`.\n\n| trigger | required config | what the body reads |\n|---|---|---|\n| `recurring_schedule` | `cron_expression` | `runtime.timezone`; the current time is `now()` |\n| `receive_webhook` | `secret`? | `trigger.method`, `trigger.headers[...]`, `trigger.query[...]`, `trigger.body` (any JSON, or raw text when the request is not JSON), `trigger.received_at` |\n| `receive_gmail_email` / `receive_outlook_email` | `connected_account_id`, `filter` | `trigger.email_id`, `trigger.from`, `trigger.to`, `trigger.cc`, `trigger.bcc`, `trigger.subject`, `trigger.date`, `trigger.body` (plain text), `trigger.reply_to`, `trigger.in_reply_to`, `trigger.attachments` (file refs \u2014 assign them straight to a files field). One type serves both providers, so `labels`, `thread_id`, `importance` and `conversation_id` are not readable. |\n\nA whole automation:\n\n```\non({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });\n\nconst open = await query_records({\n  table_id: "tbl_tickets",\n  filters: { node_type: "condition", field_key: "fld_status", operator: "has_any_of", value: ["opt_open"] },\n});\nawait send_email({\n  to: "team@example.com",\n  subject: "Weekly digest",\n  body: `${size(open.records)} tickets open as of ${formatDate(now(), "YYYY-MM-DD")}.`,\n});\n```\n\n## Steps\n\n| step | syntax |\n|---|---|\n| tool call, kept | `const <id> = await <tool>({ ...inputs });` \u2014 also `let x = await \u2026` and `x = await \u2026` |\n| tool call | `await <tool>({ ...inputs });` |\n| agent | `const <id> = await agent({ instructions, input, tools, model, output });` \u2014 see **An agent step** |\n| app agent | `const <id> = await app_agent({ alias: "<agent alias>", input: { ... } });` \u2014 runs one of the app\'s declared agents, in an app workflow only, and resolves to its declared outputs or its final text. `wait: false` only starts the run and resolves to `{ run_id }`; the run\'s failure is then its own, not the workflow\'s. Refused in a run an agent started. |\n| bind | `const <id> = <expression>;` \u2014 evaluated once; later steps read `<id>`. Bind any expression used twice. |\n| if / else | `if (<expr>) { ... } else { ... }` \u2014 `else` optional, `else if` chains allowed |\n| switch | `switch (<expr>) { case "X": { ... } default: { ... } }` \u2014 string cases only, no fallthrough |\n| for | `for (const <name> of <expr>) { ... }` |\n| wait | `await wait({ duration_in_minutes: 5 });` |\n| wait for an event | `await wait_for_event({ event_type: "webhook", event_ref: <expr>, timeout_in_minutes: 60 });` |\n| wait for an approval | `await wait_for_approval({ approvers: <expr>, prompt: <expr> });` \u2014 see **Waiting for an approval** |\n| return | `return({ status: "success" \\| "error", message: <expr>, field_errors: { ... }? });` |\n| validate | `validate({ checks: [{ fail_when: <expr>, field_key: "...", message: <expr> }, ...] });` |\n\n`return` is a call, not a JavaScript `return` statement. `validate` refuses the write when a check\'s\n`fail_when` is truthy; the check\'s `field_key` names the control its message lands on \u2014 a field of the\ntrigger table in a lifecycle workflow; in an app workflow a declared input, or the `fld_` key of a\nfield on a table the body names; in an automation it is not checked.\n\nThe name in `const x = await tool({...})` is the step\'s id; later expressions read its output as\n`x.records`, `x.id` and so on. A `// id: my_step` comment directly above a statement sets an explicit\nid; any other `//` comment there becomes the step\'s description.\n\n**`await` inside a statement** runs the call as its own step first, then reads its output where it is\nwritten: `size((await query_records({...})).records)`, an `if` test, a `return` value, a `for-of`\niterable, a tool input. `const x = c ? await t({...}) : null;` is stored as the `if` it means. An\n`await` that would run on some paths only \u2014 inside `&&`, `||`, `??`, `?.`, a nested ternary, a loop\ntest, a `validate` check \u2014 is refused; write the `if`.\n\n**Names are block-scoped, as in JavaScript** \u2014 `const`, `let`, loop items and `catch (e)`: sibling\nblocks may reuse a name and an inner block may shadow an outer one. A local may take a helper\'s name\n(`const size = 3;`), but calling `size(...)` while it is in scope is refused. Tool names, the reserved\nroots, `linked` and `_s` followed by digits cannot be bound.\n\n### Waiting for an approval\n\n`wait_for_approval` is the wait worth binding \u2014 `wait` and `wait_for_event` carry nothing to read.\nBind it to branch on the decision:\n\n```\nconst approval = await wait_for_approval({\n  approvers: record["fld_approvers"],\n  prompt: `Approve the quote for ${record["fld_name"]}?`,\n});\n\nif (approval.status == "approved") {\n  // the approved path\n} else {\n  // the rejected or timed-out path; approval.decision_comment says why\n}\n```\n\nIt resolves to `{ status: "approved" | "rejected" | "timed_out", decided_by: MemberId | null,\ndecided_at: ISO string, decision_comment: string | null }`.\n\n`approvers` takes a bare member id (`"mbr_\u2026"`), a bare group id (`"grp_\u2026"`) or a full principal\n(`{ type: "member_group", id: "grp_x" }`), alone or in a list \u2014 so a member field\'s value passes as it\nis.\n\n### An agent step\n\n`const x = await agent({ instructions, input, tools, model, output });` runs a model with tools as one\nstep \u2014 summarize a record, classify, draft text.\n\n- `instructions` \u2014 a fixed string.\n- `input` \u2014 an object literal; its fields are expressions, evaluated and handed to the model (`{}` for\n  none). It is the ONLY workflow data the agent sees: read `record`, prior steps, `runtime` or the loop\n  item here, never inside `instructions` or `tools`, which are fixed literals and read no binding.\n- `tools` \u2014 the names of the tools it may call.\n- `model` \u2014 optional; omit it to follow the platform\'s default model.\n- `output` \u2014 `{ mode: "text" }` resolves to a string; `{ mode: "object", schema }` to a typed object.\n\nOnly `x` comes back: in text mode `x` is the string itself, in object mode `x.field` reads a field the\n`schema` declares. The agent\'s own tool calls are not readable. An agent step cannot give a\nsynchronous verdict, so a `before_*` lifecycle workflow refuses it.\n\n## Keys, not names\n\n1. **Fields and options are named by key.** A field reads as `record["fld_status"]`, an option as\n   `"opt_done"`, a linked field as `linked(record["fld_customer"])[0]["fld_name"]`. `get_table` lists\n   each field\'s `key` and each option\'s `key`; a display name is refused at save with the key to use.\n2. **`==` against a multi-select means "includes".** `record["fld_tags"] == "opt_urgent"` on a\n   multi-select is stored as `includes(record["fld_tags"], "opt_urgent")`; either spelling works.\n3. **Text renders labels.** Inside a template or a text tool input, a select, member or link value\n   renders its display text: `` `${record["fld_status"]}` `` writes "Done", not `opt_done`.\n\n## What an expression reads\n\n- `record` \u2014 the trigger record (on an update, the record as it now stands).\n- `prev_record` \u2014 the record before the change, same shape (updates and deletes only).\n- `changes` \u2014 the fields an update changed, a PARTIAL map: `changes["fld_x"]?.next_value` and\n  `?.prev_value`, the `?.` required (updates only).\n- `trigger` \u2014 what a non-record trigger carries (see **Triggers**). `trigger.data`,\n  `trigger.prev_data` and `trigger.changes` are the same three roots spelled long; a saved body reads\n  back in the short form.\n- a loop\'s item name, and `index`, the iteration\'s 0-based index.\n- `<step id>` \u2014 an earlier step\'s output (`dup.records`).\n- `runtime.timezone`, `runtime.workflow_id`, `runtime.execution_id`, `runtime.workspace_id`,\n  `runtime.organization_id`, `runtime.change_origin`, `runtime.triggered_by_member_id`. The current\n  time is `now()`.\n\n## Paths\n\n- `record.fld_x` and `record["fld_x"]` read a field; `[n]` reads a list\'s n-th item.\n- A path may start at an awaited call: `(await get_record({...})).data["fld_x"]`. It may not start at a\n  helper\'s result \u2014 `first(found.records).id` is refused; bind `first(found.records)`, then read it.\n- A record reads in its declared shape wherever it comes from \u2014 the trigger, a tool result, a `let`, a\n  callback parameter: a single select or member as its key or null, a link as its ids. (The record\n  tools called outside a workflow return the stored arrays instead.)\n- `linked(record["fld_link"])[n]["fld_x"]` fetches the n-th linked row and reads a field of it; bare\n  `linked(record["fld_link"])` is every linked row, one fetch per row. Its argument is a path ending on\n  a link field and carries the guard: `linked(record?.["fld_link"])[0]`.\n- `changes["fld_link"]?.next_value` is the same list of ids; `linked()` over a change is refused \u2014\n  read `linked(record["fld_link"])` or `linked(prev_record["fld_link"])`.\n\n## Operators and statements\n\nOperators in JavaScript precedence: `? :`, `||`, `??`, `&&`, `== !=`, `< <= > >=`, `+ -`, `* /`, prefix\n`! -`.\n\n- `??` is `coalesce(left, right)`; `?.` reads through a null (`a?.b`, `a?.[0]`, and `s?.trim()` for the\n  method names listed under **Helpers**). `x?.()` is refused: helpers and tools are not values.\n- Templates use backticks and `${...}`.\n- Destructuring \u2014 `const { fld_status, fld_name } = record;` binds each name. Renames\n  (`{ fld_status: s }`), quoted keys (`{ "fld_ref": ref }`), array patterns with holes\n  (`const [first, , third] = xs;`) and defaults (`{ fld_note = "" }`, which apply on null too) work on\n  `const`, `let` and `for (const { id } of rows)`. A tool result destructures directly:\n  `const { records } = await query_records({...});`. `const a = 1, b = 2;` declares both. Nested\n  patterns and rest are refused.\n- Spread \u2014 `[...a, b]` and `{ ...a, b: 1 }` (later keys win). Refused inside a tool input: bind the\n  merged value first and pass the binding.\n- Shorthand \u2014 `{ table_id }` is `{ table_id: table_id }`.\n- `xs.push(a, b);` appends, also on a key (`o.items.push(v)`); `o.a.b = v;` sets a nested key;\n  `x ??= v`, `x ||= v` and `x &&= v` assign. A `const` may be pushed to or have a key set, as in\n  JavaScript; a loop item is read-only.\n- `undefined` is the same value as `null`. `=== undefined` and `!== undefined` are refused, since they\n  cannot tell a missing key from null: test `isNull(x)`, or `includes(keys(o), "k")` for whether a key\n  was sent.\n- A filter node may leave out `node_type` when its keys say which it is: `field_key` / `operator` /\n  `value` a condition, `logic` / `children` a group, `path` / `condition` a traversal.\n- `function name(p = <default>) { return <expr>; }` \u2014 top level only, expanded at every call (a call\n  may come before it). Every parameter needs a default, which gives it its type; the body is one\n  `return <expr>;` reading only its parameters, helpers and the reserved roots \u2014 never the caller\'s\n  names, nor `index`. No recursion; a function never called is refused. A body read back shows the\n  expression at each call, not the `function`.\n\n**try / catch.** `try { ... } catch (e) { ... }` catches a tool error or an expression error inside the\nbody; `e` is `{ message, type, step_id?, detail? }`. A failed `validate` and a `return` are not\nerrors \u2014 they end the workflow \u2014 and a step that runs after a wait inside the `try` is outside it.\n`finally` is refused: put always-run steps after the `try`.\n\n**Loops.** `for-of`, `while (cond) { ... }`, `do { ... } while (cond);` and\n`for (let i = 0; i < n; i++) { ... }`, each capped at 10,000 iterations. `break;` and `continue;` act\non the innermost loop; labels and `for-in` are refused.\n\n**`let`.** `let x = <expr>;` declares a block-scoped variable; the initializer is required\n(`let x = null;`). Reassign with `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `??=`, `++` and `--`. Re-declaring in\nthe same block is refused; shadowing in a nested block is allowed. A `let` keeps its value across a\n`wait`, `wait_for_event` or `wait_for_approval`.\n\n**Refused:** regex, `new`, `typeof`, `instanceof`, `in`, `delete`, `void`, rest elements, computed keys,\nclasses, `throw`, `import`, `export`, and a function as a value (`const f = (x) => ...`).\n\n## Helpers\n\nCalled as `size(arr)`. The method form works only where the name is also a JavaScript method \u2014\n`x.trim()`, `arr.includes(v)`, `arr.at(-1)`, `arr.map(fn)`, `s.split(",")`; `arr.size()` is refused.\n\n- **Null and type**: `isNull`, `isNotNull`, `isEmpty`, `isString`, `isNumber`, `isBoolean`, `isArray`,\n  `isObject`, `coalesce`, `get`, `toNumber`, `toString`, `typeOf`, `parseJson`, `toJson`\n- **Lists**: `size`, `first`, `requireFirst` (the first item, refusing an empty list \u2014 after a\n  `validate` on the size it saves an `if`), `last`, `nth`, `at` (`at(arr, -1)` counts from the end),\n  `includes`, `filter`, `find`, `some`, `every`, `pluck`, `sortBy`, `groupBy`, `countBy`, `unique`,\n  `uniqueBy`, `compact` (drops falsy items), `flatten`, `reverse`, `slice`, `concat`, `difference`,\n  `differenceBy`, `intersection`, `intersectionBy`, `list`, `reduce(arr, (acc, x) => ..., initial)`,\n  `range(end)` / `range(start, end)`\n- **Math**: `sum`, `sumBy`, `mean`, `meanBy`, `minBy`, `maxBy`, `round`, `ceil`, `floor`, `min`, `max`,\n  `abs`, `mod`, `pow`, `sqrt`, `clamp`, `percentage`\n- **Text**: `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`,\n  `replaceAll`, `substring`, `length`, `split`, `join`, `padStart(str, length, char)`,\n  `padEnd(str, length, char)`, `formatNumber(x, decimals)` (ungrouped, as `x.toFixed`),\n  `formatDecimal(x, decimals, locale)` (grouped: `formatDecimal(151000, 0, "vi-VN")` is `151.000`),\n  `numberToWords(x, lang?)` (an integer in words: Vietnamese, or English with `"en"`)\n- **Objects**: `keys`, `values`, `entries`, `nonNullKeys`, `pick`, `omit`, `merge`\n- **Dates**, in the workspace\'s timezone: `now`, `formatDate`, `parseDate`, `addDays`, `subDays`,\n  `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`,\n  `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`,\n  `isSameDay`, `isToday`, `isWithinRange`\n- **Other**: `formatCurrency(amount, locale, currency)`, `randomNumber(len)`,\n  `randomAlphaNumeric(len)`, `sample(items)` (a random item)\n\nA date helper given a null or empty date returns null, so guard its result before comparing or\nwriting it: `differenceInCalendarDays(a, b) ?? 0`.\n\n`filter`, `find`, `some`, `every`, `sortBy`, `pluck`, `sumBy`, `meanBy`, `minBy`, `maxBy`, `groupBy`,\n`countBy`, `uniqueBy`, `differenceBy` and `intersectionBy` take a path string\n(`filter(record.items, "Status", "open")`) or a callback\n(`filter(record.items, x => x.Status == "open" && x.Amount > 100)`); `reduce` takes a callback and an\ninitial value. A callback gets `(item, idx)` (`reduce`: `(acc, item, idx)`) and reads `record`,\n`runtime`, the names in scope, loop items and an enclosing callback\'s parameters. Its body is one\nexpression \u2014 `(x) => <expr>`, `(x) => { return <expr>; }` or `function (x) { return <expr>; }`;\nseveral statements, `async` and named function expressions are refused.\n\n## Writing a field: null and undefined\n\nIn `update_records`\' `set` and `create_records`\' `records`:\n\n- `null` clears the field.\n- `undefined`, or leaving the key out, leaves the field as it is.\n\nSo passing a read that may be null (`record["fld_x"]`) keeps a value when there is one and clears the\nfield when there is none. Use `coalesce(x, fallback)` only for a real fallback value.\n\n## Examples\n\nRefuse a duplicate before it is created (a `before_create` lifecycle workflow; the keys come from\n`get_table`):\n\n```\nconst dup = await query_records({\n  table_id: "tbl_orders",\n  filters: { node_type: "group", logic: "and", children: [\n    { node_type: "condition", field_key: "fld_ref", operator: "equals", value: record["fld_ref"] },\n    { node_type: "condition", field_key: "fld_closed_at", operator: "is_empty" },\n  ]},\n});\n\nvalidate({ checks: [{\n  fail_when: size(dup.records) > 0,\n  field_key: "fld_ref",\n  message: "An open order already has this reference.",\n}]});\n```\n\nCompare a link by id. Display text is not unique, and a link reads as a list of ids \u2014 `==` against a\nstring is a type error:\n\n```\nconst found = await query_records({\n  table_id: "tbl_customers",\n  filters: { node_type: "condition", field_key: "fld_name", operator: "equals", value: "ACME Corp" },\n});\nconst customer = first(found.records);\n\nif (customer && includes(record["fld_customer"], customer.id)) {\n  // \u2026\n}\n```\n\n## Table lifecycle workflows\n\nA lifecycle workflow is bound to one table and one event, and its source has no `on({...})` line:\n\n- `before_create` / `after_create` \u2014 a create, and a draft\'s submit (the moment it becomes a record).\n- `before_update` / `after_update` \u2014 every field edit, a draft\'s included: a `before_update` check\n  runs while someone fills in a draft, not only once it is submitted.\n- `before_delete` / `after_delete`.\n\nA `before_*` workflow runs before the write commits and may refuse it, with `validate` or\n`return({ status: "error", ... })`; its errors come back as field errors on the write. It cannot\n`wait`, `wait_for_event`, `wait_for_approval` or run an `agent` step. An `after_*` workflow runs after\nthe commit, with every step; its errors are logged and never fail the write. An `after_update`\nworkflow that writes its own table saves with a `loop_potential` warning: its write fires it again.\n\n| reads | on |\n|---|---|\n| `record` | every event \u2014 the new record on create, the record as it now stands on update, the deleted record on delete |\n| `prev_record` | updates and deletes \u2014 the record before |\n| `changes["fld_x"]?.next_value` / `?.prev_value` | updates \u2014 the fields that changed |\n\n### Gating with `if_source`\n\n`if_source` is one JavaScript expression, reading what the body reads, tested before the workflow\nruns. When it is falsy the workflow does not run at all \u2014 no execution, no log. Use it so a workflow\nthat cares about some events only skips the rest:\n\n- a status reaching an option: `changes["fld_status"]?.next_value == "opt_done"`\n- a field cleared: `isNull(record["fld_assignee"])`\n- a direct write, not a workflow\'s cascade:\n  `includes(["member", "chat_agent", "api_client"], runtime.change_origin.type)` \u2014 name every\n  direct-write origin rather than testing for one: `member` is a person in the browser, and the same\n  edit over MCP, the CLI or the API arrives as `api_client`.\n\nIn `if_source`, `runtime.change_origin` is the origin of the write that fired it; in the body, it is\nthe workflow\'s own.\n';
@@ -41686,13 +41686,13 @@ var workflows_default = '# Workflows \u2014 the steps a workflow runs\n\nA workf
 var app_bindings_default = "# App bindings \u2014 the queries, workflows and agents an app calls\n\nA custom-code app reaches workspace data through three 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_queries` | `useQuery(\"<alias>\", params?)` | `run_app_query` |\n| Workflow | `set_app_workflow` | `useWorkflow(\"<alias>\")({ ...inputs })` | `run_app_workflow` |\n| Agent | `set_app_agent` | `useAgentRun(\"<alias>\")({ ...inputs })` | \u2014 |\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_capabilities` lists an app's aliases with their params and inputs.\n\nEach reader returns a fingerprint of what it read \u2014 `get_app_query`'s `sha`, `get_app_workflow`'s\n`body_sha`, `get_app_agent`'s `instructions_sha` \u2014 and a write built on that read passes it back:\n`set_app_queries`' `expected_shas` (alias \u2192 `sha`), `set_app_workflow`'s `expected_body_sha`,\n`set_app_agent`'s `expected_instructions_sha`, `remove_app_binding`'s `expected_sha`. The write is\nrefused, and writes nothing, when the binding changed since; omit it for an unconditional write.\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_queries` takes `{ <alias>: <declaration> }`, one alias or several, and merges each: send\nonly the fields you change, `null` clears `params`, `description` or `templates` (never `ast`), and a\nnew alias needs an `ast`. Any other field is refused by name. An alias it omits is kept.\n`remove_app_binding` with `kind: \"query\"` deletes one; `get_app_query` reads one back.\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, or `{ bucket: { source, granularity, 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 `project` column is a field key 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 key, `{ 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?, \u2026per type }`. An entry is required unless it states\n`required: false`.\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: \"fld_\u2026\"` (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\nNesting stops at depth 8. A `field`-form select tracks the field's options as they change; an\ninline `options` set is a fixed list.\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: \"fld_\u2026\"`; `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_app_workflow` binds a workflow body to an alias: `{ app_id, alias, source, inputs?, outputs?,\nname?, description? }`.\n\n- `source` is the body with no `on({...})` trigger \u2014 the app is the trigger. It 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 `get_record`.\n  The body's steps are the `workflows` reference.\n- `inputs` 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` 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. `verify_only: 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_app_workflow` reads the body back; `dry_run_workflow` with `trigger_type: \"app_workflow\"`\nruns it against sample inputs before binding; `remove_app_binding` with `kind: \"workflow\"` unbinds\nit.\n\n## Agents\n\n`set_app_agent` binds a streaming tool-loop agent to an alias. A run streams its work to the app,\nreturns a typed result and keeps a run history per session. The declaration:\n\n- `instructions` \u2014 the task, every run. A new alias needs it.\n- `tool_names` \u2014 the tools it may call, from these and no other: `analyze_pdf_template`,\n  `code_edit_file`, `code_exec`, `code_read_file`, `code_write_file`, `excel_create_file`,\n  `excel_find_cells`, `excel_format_range`, `excel_get_range`, `excel_update_range`,\n  `generate_bank_qr_code`, `generate_document`, `generate_image`, `generate_qr_code`, `get_template`,\n  `grep_knowledge`, `list_banks`, `list_knowledge`, `lookup_business`, `query_templates`,\n  `read_knowledge`, `run_app_query`, `run_app_workflow`, `validate_excel_template`,\n  `vietcombank_convert_currency`, `view_files`, `word_create_document`, `word_find_text`,\n  `word_get_content`, `word_get_table_data`, `word_insert_conditional`, `word_insert_loop`,\n  `word_replace_text`. `[]` is a reasoning-only agent. A few fields of a document read well through\n  the `excel_*` / `word_*` tools; a cross-check, reconciliation or transform a decision rests on\n  belongs in the code tools.\n- `query_aliases` / `workflow_aliases` \u2014 the app's own queries and workflows it may call through\n  `run_app_query` / `run_app_workflow`. They are its whole reach over records: no agent tool takes a\n  `table_id`, so a read is bounded by the query's tables, rows and columns, and a write goes through\n  the app's own workflow.\n- `knowledge_doc_ids` \u2014 knowledge docs it may read with `grep_knowledge` / `read_knowledge`\n  (declare them in `tool_names`). Each must be one the app owner and you can use. Nothing is\n  inlined and size does not matter. The list is the agent's whole reach \u2014 `list_knowledge` finds no\n  doc outside it \u2014 so name a doc's id in `instructions` to point it there. `code_exec` computes\n  across a corpus (counting, cross-referencing); reading needs only the knowledge tools.\n- `model_tier` \u2014 `haiku`, `sonnet` or `opus`. Omitted, the run follows the platform's default tier\n  and moves with new models; pin one only as a tested choice, and never `haiku`, a utility tier.\n- `effort_level` \u2014 `low`, `medium`, `high`, `xhigh` or `max`, one the pinned tier supports; it\n  needs `model_tier`.\n- `prefix_cache_ttl` \u2014 `5m` (the default) or `1h`. `1h` doubles the cache write price and pays only\n  when runs land 5 to 60 minutes apart, as a scheduled sweep does.\n- `inputs` \u2014 the per-run payload (see **Inputs**); omitted, the payload is untyped.\n- `outputs` \u2014 the structured result (see **Outputs**), checked before the run is saved and typed\n  as `run.output` in the app; omitted, the result is the final message.\n- `writes` \u2014 where the outputs land: `{ table_id, row, fields }`, `row` naming a single\n  `record_link` input to `table_id` and `fields` mapping each output name to a field key of that\n  table. A result that validates is written to that row under the app's authority.\n\nSend only what you change: an omitted field keeps its stored value, `null` clears an optional one.\n`get_app_agent` reads one back; `remove_app_binding` with `kind: \"agent\"` deletes it.\n";
 
 // docs/document_templates.md
-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. For the exact input schema of any tool named here,\nrun `lotics tools <tool_name>` \u2014 that is always the source of truth for arguments.\n\n## The five template types\n\n| Type | What it fills | Output | Create with |\n|---|---|---|---|\n| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `create_pdf_template` (mode `form`), on the CLI or in chat |\n| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `create_pdf_template` (mode `html`), on the CLI or in chat |\n| `excel` | an **uploaded `.xlsx`** with `{{marker}}` cells | `.xlsx` | `create_excel_template` |\n| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `create_word_template` |\n| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `create_email_template`, on the CLI or in chat |\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 locally is a separate step: inside a workflow, pass the returned\n   `file_id` to the next step; from the CLI, `lotics download <file_id>` fetches it.\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 `create_email_template` (on the CLI or in chat) 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 each type\n\n### PDF from HTML\n\nWrite a full HTML document with inline CSS and `{{variable}}` placeholders, as `create_pdf_template`\nwith mode `html` on the CLI or in chat; it renders to PDF via a headless browser. Good for invoices, reports, letters, certificates \u2014 anything whose\nlayout you control. Declare `variables` (plain text, rich `html`, an auto-rendered `table`,\nor a `list`), and optionally `format` (page size) and `orientation`. See\n`lotics tools create_pdf_template` for the exact variable shapes.\n\n### PDF form\n\nFor an existing PDF you must fill in place (a government form, a printed contract), on the CLI or in chat:\n\n1. `lotics upload ./form.pdf` \u2192 a `file_id`.\n2. `create_pdf_template` with mode `form` and that `file_id`.\n3. `analyze_pdf_template` \u2014 extracts the labels and their positions off the page.\n4. `update_pdf_template` \u2014 define the positioned fields (`text` / `checkbox` / `image`, each\n   with a page + x/y/size) in `variables`.\n\nForm-mode data is scalar-only (text, numbers, checkboxes) \u2014 one value per positioned field.\n\n### Excel\n\n1. Build a `.xlsx` in Excel (or with any spreadsheet library) and put `{{marker}}`s in the cells that\n   should be filled. `lotics upload ./template.xlsx` \u2192 a `file_id`.\n2. `create_excel_template` with that `template_file_id` and a `variables` map. Markers are\n   **validated at create time** \u2014 a structural error (mismatched loop, unknown helper, bad\n   placement) blocks the save, and declared variables with no matching marker come back in\n   `unmarked_variables` (skipped, not filled).\n\nOn the CLI, `validate_excel_template` checks an uploaded file\'s markers without creating a template. Pass\nraw numbers / ISO dates / booleans at generate time \u2014 the cell\'s number format handles display.\n\n### Word\n\n1. Build a `.docx` with `{{marker}}`s where values go. `lotics upload ./template.docx`.\n2. `create_word_template` with the `template_file_id`. `variables` is optional \u2014 every\n   marker in the document is derived automatically (`{{name}}` \u2192 string,\n   `{{FOR \u2026 IN name}}` \u2192 array, `{{IF name}}` \u2192 boolean). When you do declare, an unmarked\n   declaration comes back in `unmarked_variables` and is skipped, and markers you didn\'t\n   declare are still auto-added (`derived_variables`) \u2014 the stored contract always covers\n   every marker in the document.\n\nAt generate time, `data` must provide a key for **every** marker \u2014 pass `""` for fields\nthat should render blank; a missing key fails with the full list of missing markers.\n\n### Email\n\nInline HTML + Handlebars, no uploaded file \u2014 `create_email_template`, on the CLI or in chat. Declare `variables`, and optionally a default\n`subject` (which itself supports `{{variable}}` expressions) and default to/cc/bcc. The body\nand 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 create-tool 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 always uses the `{{#each}}` marker rows \u2014 it has no auto-rendered\n  `table` type; its variable types are string/number/date/boolean/array.)\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 format a raw value with a helper, in the template\'s `locale` (`vi` or `en`, set at\ncreate or update; none prints in the organization\'s language); an empty value prints `""`:\n`{{money total "VND"}}` \u2192 `28.000.000 \u20AB` (`en`: `\u20AB28,000,000`), `{{number qty}}` \u2192 grouped, up to 2 decimals,\n`{{date issued_on}}` \u2192 `14/09/2026` (a moment on the workspace\'s timezone; a date-fns pattern as the second argument,\nliteral text quoted: `"\'Ng\xE0y\' dd"`), and `{{words total "USD"}}` \u2192 `M\u1ED9t ngh\xECn \u0111\xF4 la M\u1EF9 n\u0103m m\u01B0\u01A1i xu` (`en`: `One\nthousand US dollars and fifty cents`; no code reads VND). A value the helper cannot read fails the render.\n\nRun `lotics tools create_excel_template`, `create_word_template`, `create_pdf_template`, or\n`create_email_template` for each engine\'s exact marker grammar and helper list \u2014 don\'t guess it.\n\n## Generating a filled file\n\n```bash\n# See what a template expects, then fill it\nlotics tools generate_document\nlotics run get_template \'{"template_id":"dtl_..."}\'          # its declared variables\nlotics run generate_document \'{"document_template_id":"dtl_...","filename":"invoice-1042","data":{"company_name":"Acme","total":1042,"items":[...]}}\'\nlotics download <file_id> -o ./out/\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).\n- `generate_document` renders the template\'s own type and returns a generated file object; take\n  its `file_id` onward.\n- In a workflow, a **generate step** calls the same tools and hands the `file_id` to the next\n  step (attach to a record, send as an attachment, etc.).\n\n## Discovering and managing templates\n\nFour unified tools work across all five types:\n\n| Tool | Does |\n|---|---|\n| `query_templates` | list templates (optionally filter by type: excel/word/pdf/email) |\n| `get_template` | one template\'s full definition, incl. the `variables` it expects |\n| `clone_template` | copy a template to iterate on, on the CLI or in chat |\n| `delete_template` | remove a template, on the CLI or in chat |\n\nCall `get_template` before generating when you don\'t already know a template\'s variable names.\n\n## Reaching the tools\n\n```bash\nlotics tools                              # all categories\nlotics tools create_word_template         # one tool: full description + input schema\nlotics run <tool> \'<json-args>\'           # execute (inline JSON, @file.json, or `-` for piped stdin)\n```\n\nThe template tools live in the categories **PDF Templates**, **Excel Templates**,\n**Word Templates**, **Email Templates**, and **Templates** (the unified query/get/clone/delete).\nUploading the source file for a file-backed template is `lotics upload <file>`; fetching a\ngenerated file is `lotics download <file_id>`.\n';
+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. For the exact input schema of any tool named here,\nrun `lotics tools <tool_name>` \u2014 that is always the source of truth for arguments.\n\n## The five template types\n\n| Type | What it fills | Output | Create with |\n|---|---|---|---|\n| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `create_pdf_template` (mode `form`), on the CLI or in chat |\n| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `create_pdf_template` (mode `html`), on the CLI or in chat |\n| `excel` | an **uploaded `.xlsx`** with `{{marker}}` cells | `.xlsx` | `create_excel_template` |\n| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `create_word_template` |\n| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `create_email_template`, on the CLI or in chat |\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 locally is a separate step: inside a workflow, pass the returned\n   `file_id` to the next step; from the CLI, `lotics download <file_id>` fetches it.\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 `create_email_template` (on the CLI or in chat) 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 each type\n\n### PDF from HTML\n\nWrite a full HTML document with inline CSS and `{{variable}}` placeholders, as `create_pdf_template`\nwith mode `html` on the CLI or in chat; it renders to PDF via a headless browser. Good for invoices, reports, letters, certificates \u2014 anything whose\nlayout you control. Declare `variables` (plain text, rich `html`, an auto-rendered `table`,\nor a `list`), and optionally `format` (page size) and `orientation`. See\n`lotics tools create_pdf_template` for the exact variable shapes.\n\n### PDF form\n\nFor an existing PDF you must fill in place (a government form, a printed contract), on the CLI or in chat:\n\n1. `lotics upload ./form.pdf` \u2192 a `file_id`.\n2. `create_pdf_template` with mode `form` and that `file_id`.\n3. `analyze_pdf_template` \u2014 extracts the labels and their positions off the page.\n4. `update_pdf_template` \u2014 define the positioned fields (`text` / `checkbox` / `image`, each\n   with a page + x/y/size) in `variables`.\n\nForm-mode data is scalar-only (text, numbers, checkboxes) \u2014 one value per positioned field.\n\n### Excel\n\n1. Build a `.xlsx` in Excel (or with any spreadsheet library) and put `{{marker}}`s in the cells that\n   should be filled. `lotics upload ./template.xlsx` \u2192 a `file_id`.\n2. `create_excel_template` with that `template_file_id` and a `variables` map. Markers are\n   **validated at create time** \u2014 a structural error (mismatched loop, unknown helper, bad\n   placement) blocks the save, and declared variables with no matching marker come back in\n   `unmarked_variables` (skipped, not filled).\n\nOn the CLI, `validate_excel_template` checks an uploaded file\'s markers without creating a template. Pass\nraw numbers / ISO dates / booleans at generate time \u2014 the cell\'s number format handles display.\n\n### Word\n\n1. Build a `.docx` with `{{marker}}`s where values go. `lotics upload ./template.docx`.\n2. `create_word_template` with the `template_file_id`. `variables` is optional \u2014 every\n   marker in the document is derived automatically (`{{name}}` \u2192 string,\n   `{{FOR \u2026 IN name}}` \u2192 array, `{{IF name}}` \u2192 boolean). When you do declare, an unmarked\n   declaration comes back in `unmarked_variables` and is skipped, and markers you didn\'t\n   declare are still auto-added (`derived_variables`) \u2014 the stored contract always covers\n   every marker in the document.\n\nAt generate time, `data` must provide a key for **every** marker \u2014 pass `""` for fields\nthat should render blank; a missing key fails with the full list of missing markers.\n\n### Email\n\nInline HTML + Handlebars, no uploaded file \u2014 `create_email_template`, on the CLI or in chat. Declare `variables`, and optionally a default\n`subject` (which itself supports `{{variable}}` expressions) and default to/cc/bcc. The body\nand 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 create-tool 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 always uses the `{{#each}}` marker rows \u2014 it has no auto-rendered\n  `table` type; its variable types are string/number/date/boolean/array.)\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 format a raw value with a helper, in the template\'s `locale` (`vi` or `en`, set at\ncreate or update; none prints in the organization\'s language); an empty value prints `""`:\n`{{money total "VND"}}` \u2192 `28.000.000 \u20AB` (`en`: `\u20AB28,000,000`), `{{number qty}}` \u2192 grouped, up to 2 decimals,\n`{{date issued_on}}` \u2192 `14/09/2026` (a moment on the workspace\'s timezone; a date-fns pattern as the second argument,\nliteral text quoted: `"\'Ng\xE0y\' dd"`), and `{{words total "USD"}}` \u2192 `M\u1ED9t ngh\xECn \u0111\xF4 la M\u1EF9 n\u0103m m\u01B0\u01A1i xu` (`en`: `One\nthousand US dollars and fifty cents`; no code reads VND). A value the helper cannot read fails the render.\n\nRun `lotics tools create_excel_template`, `create_word_template`, `create_pdf_template`, or\n`create_email_template` for each engine\'s exact marker grammar and helper list \u2014 don\'t guess it.\n\n## Generating a filled file\n\n```bash\n# See what a template expects, then fill it\nlotics tools generate_document\nlotics run get_template \'{"template_id":"dtl_..."}\'          # its declared variables\nlotics run generate_document \'{"document_template_id":"dtl_...","filename":"invoice-1042","data":{"company_name":"Acme","total":1042,"items":[...]}}\'\nlotics download <file_id> -o ./out/\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).\n- `generate_document` renders the template\'s own type and returns a generated file object; take\n  its `file_id` onward.\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## Discovering and managing templates\n\nFour unified tools work across all five types:\n\n| Tool | Does |\n|---|---|\n| `query_templates` | list templates (optionally filter by type: excel/word/pdf/email) |\n| `get_template` | one template\'s full definition, incl. the `variables` it expects |\n| `clone_template` | copy a template to iterate on, on the CLI or in chat |\n| `delete_template` | remove a template, on the CLI or in chat |\n\nCall `get_template` before generating when you don\'t already know a template\'s variable names.\n\n## Reaching the tools\n\n```bash\nlotics tools                              # all categories\nlotics tools create_word_template         # one tool: full description + input schema\nlotics run <tool> \'<json-args>\'           # execute (inline JSON, @file.json, or `-` for piped stdin)\n```\n\nThe template tools live in the categories **PDF Templates**, **Excel Templates**,\n**Word Templates**, **Email Templates**, and **Templates** (the unified query/get/clone/delete).\nUploading the source file for a file-backed template is `lotics upload <file>`; fetching a\ngenerated file is `lotics download <file_id>`.\n';
 
 // docs/knowledge_docs.md
 var knowledge_docs_default = '# Knowledge Docs\n\nKnowledge docs are the AI\'s **rulebook layer** \u2014 the workspace-specific facts and rules an\nagent can\'t know on its own: your price list, your product codes, your SOPs, your shipping\ntariffs, your glossary of in-house terms. You write them once; the agent **searches and reads\nthem on demand** while it works, pulling in only the lines it needs.\n\nThey are deliberately **not** injected into the agent wholesale. Instead the agent retrieves\nfrom them line by line \u2014 grep, then read \u2014 so a 10,000-line tariff book costs nothing until a\nquestion actually touches it, and a 10MB one is no different.\n\nThis is a **capability + usage** guide. For the exact input schema of any tool named here, run\n`lotics tools <tool_name>`.\n\n## Rulebook, not methodology\n\nPut in a knowledge doc the things the model **cannot guess**: your specific numbers, codes,\nnames, exceptions, and policies. Do **not** put in it general skills the model already has\n("how to write a polite email", "how to summarize"). If the agent would get it right without\nthe doc, the doc is noise.\n\n## Creating a doc \u2014 `lotics knowledge create`\n\n```bash\nlotics knowledge create --name "Shipping tariffs" \\\n  --description "HS-coded rates; searchable by lane and code" \\\n  --tags "HS,nh\u1EADp kh\u1EA9u" \\        # file it as you make it \u2014 see Classifying, below\n  --from ./tariffs.md            # the body is a Markdown file; or --content \'<inline>\'\n```\n\nThis reads the body from your filesystem and creates the doc through `create_knowledge`\n(prints the new id). A raw `lotics run create_knowledge @doc.json` works too \u2014 read a large\n`content` from a file or stdin. `create_knowledge` takes five fields, three of them required:\n\n- `name` \u2014 what it is. Just the name: **grouping belongs in `tags`, not in a prefix baked into\n  every title.**\n- `description` \u2014 what the doc is **and what to grep it for**: its vocabulary and the synonyms\n  an ambiguous query would use. Surfaced in the tree before any body is read, and truncated at\n  200 characters. See *Write for grep* below.\n- `content` \u2014 Markdown.\n- `tags` *(optional)* \u2014 the labels someone would filter by, e.g. `["H\u1ED3 s\u01A1 NOXH", "Kho\u1EA3n 13"]`.\n  Give **every** one that is true of the doc, not just the main one \u2014 a corpus is narrowed by\n  intersecting tags, so a doc carrying one label can only ever be found down one path. On\n  `update_knowledge` 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` the doc was built from,\n  stored alongside it so a reader can open the original. The body stays the searchable text.\n\nA new doc is created **owned by you, active in your own agent context, and private** \u2014 no one\nelse can see it yet. Changing a doc\'s default-active state is done through the web app / REST\nsurface, not this tool.\n\n## Access\n\nA knowledge doc reaches an agent only when the member can `use` the doc. New docs are private\nto the owner; share them with other members or groups using the IAM tool `share_resource` on the CLI or in chat\n(category **Admin**; `unshare_resource` to revoke). An organization admin who is a person is no\nexception: they read a doc only once it is shared with them, or once they share it with\nthemselves, which the audit log records. An API key acting as itself keeps the access set on the\nkey.\n\n## How an agent uses a doc \u2014 ls, grep, cat\n\nDocs are not injected wholesale. The agent works the corpus like a filesystem, and all three\nverbs respect access, so only docs the caller may use ever surface.\n\n1. **`list_knowledge`** \u2014 `ls`. The corpus as a flat list: id, name, tags, and a truncated\n   description; `tag` narrows it. No bodies.\n2. **`grep_knowledge`** \u2014 `grep -rn`. Match across every readable doc (or one doc, or one\n   tag), returning **doc, line number, and the matching line**. It runs inside Postgres,\n   so only matching lines cross the wire.\n3. **`read_knowledge`** \u2014 `cat` / `sed -n \'X,Yp\'`. Read a doc whole or by line range, to see\n   the context around a hit.\n\nMatching is **not ranked** \u2014 there is no index and no tokenizer, which is why a corpus in any\nscript works and why nothing goes stale. The consequence is that the *agent* does the\nnarrowing: a distinctive phrase is sharply selective, a whole question matches everything.\n`grep_knowledge` always reports `total_matches`, so "too broad" is visible and cheap to fix.\n\n### Literal by default, expression on request\n\n`pattern` is **literal text** \u2014 every character matches itself. Set `regex: true` to read it as\na POSIX regular expression instead.\n\n```\ngrep_knowledge({ pattern: "C/O (Form E)" })\ngrep_knowledge({ pattern: "\\\\yNK\\\\y", regex: true, case_sensitive: true })\n```\n\nThe default is the safe one rather than the conventional one, and the asymmetry is worth\nknowing. As an expression, `C/O (Form E)` searches for `C/O Form E` \u2014 not in the document \u2014 and\nreturns a confident zero; `[C\u0168]` becomes a one-character class and matches every `C` in the\ncorpus. Both look like ordinary answers. A literal search has no such failure: the worst case\nis an expression sent without the flag, which finds nothing and says so, naming the search that\nran and what to pass instead. That last part is **measured, not guessed** \u2014 an empty result tells\nyou whether reading the pattern as an expression would have matched, so an alternation sent without\nthe flag (`phrase A|phrase B`) comes back naming `regex: true` rather than advising you to shorten a\npattern that was never too broad.\n\n### Matching options\n\n- **Tone marks match exactly by default.** `diacritic_insensitive: true` folds them, so `ca phe`\n  matches `c\xE0 ph\xEA` \u2014 reach for it when the pattern was typed without them, not by habit: folding\n  strips the pattern to ASCII, where a short Vietnamese word matches inside unrelated words\n  (`m\xE3` finds `manifest`). An empty result tells you when folding would have matched.\n- **Case folds by default**, independently of diacritics. `case_sensitive: true` matches case\n  exactly \u2014 useful for an acronym (`NK` vs `nk`) that a folded search would blur.\n- **Whitespace is normalized on both sides.** A body converted from PDF, Word or Excel carries\n  non-breaking spaces, soft hyphens, zero-width marks and padded runs that nobody types into a\n  query; those fold to ordinary single spaces before matching, so a correct search does not return\n  a silent zero on text that is present. A literal pattern is normalized the same way; an\n  expression is left byte-exact, since collapsing its whitespace would rewrite it.\n- **What `regex: true` supports**: quantifiers, character classes, alternation, anchors,\n  backreferences, non-greedy forms, `(?i)`, and both lookahead and lookbehind. A word boundary\n  is **`\\y`**, not `\\b` \u2014 Postgres spells it differently, and `\\b` is rewritten for you rather\n  than silently matching nothing. Named groups and `\\p{\u2026}` are likewise rewritten to their POSIX\n  equivalents. A `\\p{\u2026}` with no POSIX equivalent, and a malformed expression, are both refused\n  with the reason.\n\nWhere an expression cannot express the question at all \u2014 a value that must be computed, a\nlayout matching cannot address \u2014 stage the doc into a code run instead (`code_exec`, in chat or an app agent, with\n`knowledge_doc_ids` puts it at `inputs/knowledge/<id>.md` as a real file).\n\n### What a result is bounded by\n\nA result carries at most 40.000 characters. Matched lines are admitted first and context fills\nwhat remains, so an answer is never dropped to make room for a neighbouring line. Anything the\nbudget cut is REPORTED \u2014 `chars_elided_matches` (an answer was dropped) and\n`context_omitted_matches` (an answer was kept without the context you asked for) mean different\nthings and call for different fixes: narrow the pattern, or ask for fewer `context_lines`.\nIndividual lines longer than 600 characters are clipped and marked, with `read_knowledge` giving\nthe rest.\n\n`total_matches` is always the true total, even when fewer are shown.\n\n## Write for grep \u2014 the rules that decide whether an answer is findable\n\nRetrieval addresses **lines**. Every rule below follows from that one fact.\n\n- **One self-contained fact per line.** A grep hit returns *that line*. For dense or tabular\n  data \u2014 a price row, a tariff code, a charge entry \u2014 put the whole record on one line.\n- **Repeat the searchable terms on every line; headings do not carry down.** A line reading\n  `Rate: 15%` under a heading `Roasted coffee` will never match a search for `coffee`. Restate\n  the identifying terms inline, even when it reads redundantly to a human. This is the single\n  rule most often got wrong.\n- **Keep a line under ~600 characters.** Past that the line is truncated in the agent\'s view\n  and marked as cut; the agent can still `read_knowledge` for the rest, but it costs a round\n  trip. Put 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 /\n  Coffee, roasted`) matches queries in either language for free. The same trick carries\n  colloquial terms next to official ones.\n- **For prose, keep a rule and its exception close.** A hit returns one line, so a rule on line\n  40 and its exception on line 90 can be retrieved apart. Use `context_lines` when reading, and\n  keep related clauses adjacent when writing.\n\nMarkdown headings are ordinary text \u2014 useful for a human and for orienting a `read_knowledge`,\nbut they carry no retrieval weight of their own.\n\n**The description is the discovery hint.** It is what the agent sees in the tree before it has\nread a byte of the body, so it is the only clue for *what term to grep for*. Write it to name\nthe doc\'s vocabulary \u2014 the words that actually appear inside it. Keep it to a sentence: it is\ntruncated at 200 characters, and a keyword-stuffed description is cut, not rewarded.\n\n## Updating a doc \u2014 `lotics knowledge update`\n\n```bash\nlotics knowledge update kdc_... --from ./tariffs.md   # replace the body (--name / --description too)\n```\n\nSend only the fields you\'re changing. `--from` / `--content` replaces the body; `--name` /\n`--description` / `--tags` change metadata. `update_knowledge` resolves concurrency **internally** \u2014 it\nre-reads the current content pointer and version-chains the new body \u2014 so there is no version\ntoken to pass from the CLI. (The chat agent may instead send an `edits` array \u2014 anchored\nreplace / insert / append \u2014 for a surgical change; see `lotics tools update_knowledge`.) Refine\nstructure as you learn what users actually ask: add the synonym that failed to match, split a\nline that was too coarse, restate a term the heading was carrying.\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\nthe vocabulary is whatever the docs themselves use \u2014 a tag stops existing the moment nothing\ncarries it.\n\n```bash\nlotics knowledge update kdc_... --tags "HS,nh\u1EADp kh\u1EA9u"    # ONE doc: state its complete set\nlotics knowledge tag kdc_a kdc_b --add HS --remove draft # MANY docs: a diff applied to each\n```\n\nThe split is deliberate. Looking at one doc you know what it should carry, so `--tags` replaces.\nAcross a set you do not \u2014 the docs carry different labels \u2014 so `tag` adds and removes against\neach doc\'s own set, and never states one classification for all of them. Removal ignores case;\nadding a label a doc already carries changes nothing.\n\nAn agent narrows by tag rather than reading the whole corpus:\n\n```bash\nlotics tools list_knowledge   # takes an optional tag\nlotics tools grep_knowledge   # same\n```\n\n## Taking a doc out of circulation \u2014 `hide`\n\n```bash\nlotics knowledge hide kdc_...              # superseded, draft, source material\nlotics knowledge list --include-hidden     # find it again\nlotics knowledge unhide kdc_...            # put it back\n```\n\nA hidden doc is out of every **listing**: it is gone from the Library\'s list, from\n`list_knowledge`, and from the corpus `grep_knowledge` searches, so nothing finds it by browsing.\nIt is not deleted, not unshared, and still **reads when addressed by id** \u2014 `read_knowledge` with\nits id, a code run staging it, an app agent that declares it. That is the point: hiding is a\nstatement about discovery, so it cannot silently break an app that depends on a doc by name.\n\nReach for it instead of `rm` whenever the material still matters: last year\'s tariff schedule, a\nhandbook a newer one replaced, the raw source a curated doc was written from.\n\n## Reaching the tools\n\n```bash\nlotics knowledge list                   # catalog: id, name, tags, description\nlotics knowledge get kdc_... -o doc.md  # read a body to a file (omit -o for stdout)\nlotics tools update_knowledge           # full input schema for any knowledge tool\n```\n\nThe Knowledge category covers `list_knowledge`, `create_knowledge`, `update_knowledge`, and\n`delete_knowledge` \u2014 fronted by the `lotics knowledge list | create | get | update | tag | hide |\nunhide | rm` commands, and all but `delete_knowledge` reachable over MCP as well, so a corpus can be\nauthored from whichever surface you already work in. `list`, `tag`, `hide` and `unhide` go over REST rather than a tool, because\nthey are a person\'s view of the corpus: the tools answer what the ASSISTANT may browse, and a\nhidden doc is out of that set by definition. Sharing a doc to other members is `share_resource` / `unshare_resource` on the\nCLI or in chat (category **Admin**).\n';
 
 // docs/migration.md
-var migration_default = "# @lotics/cli \u2014 migration notes\n\nWhat to DO when a release changes the shape of something the CLI once wrote to disk. Every other\ncontract is `docs/cli_reference.md`; this file is the one a reader opens once, because something\nalready on disk no longer matches what the CLI does.\n\n## Local app projects are gone\n\nAn app built from a model no longer lives in a directory. The live app is the only edit surface:\neach change mints a new version of it, and rolling back to an earlier version is the undo. What\nthe app is \u2014 its screens (`app.json`), its queries, workflows, agents and capabilities, and the\nmodel body it was compiled from \u2014 is held by that version, and the model's tables, fields, options,\ntemplates and roles are the workspace's own.\n\n| What you ran | What replaces it |\n|---|---|\n| `lotics scaffold check` + `scaffold apply` | `lotics model apply <model.json>` \u2014 checks the file, applies the tables and rows, then mints a version of every app it declares |\n| `lotics workspace build <model.json>` | `lotics model apply <model.json>` |\n| `lotics app create --from <model.json>#<app>` | `lotics model apply <model.json> --app <app>` |\n| `lotics app regenerate` | change the model file, then `lotics model apply` |\n| `lotics scaffold diff` | `lotics model apply <model.json> --plan` \u2014 what the apply would change, writing nothing |\n| `lotics scaffold export` | `lotics model pull [-o <model.json>]` \u2014 the workspace's model, rebuilt from what owns each part |\n| `lotics app pull`, `app codegen`, `app check`, `app dev`, `app preview` | nothing local: read an app with `lotics run get_app`, and change it through its tools |\n| `lotics app workflow set` / `app query set` / `app agent set` | `lotics run set_app_workflow` / `set_app_queries` / `set_app_agent` \u2014 each mints a version |\n| `lotics app versions` + a redeploy of an old tree | `lotics run query_app_versions`, then `lotics run rollback_app` \u2014 restores the app's earlier version; table changes and data writes stay |\n| `lotics app rename`, `app subdomain`, `package.json#lotics.capabilities` | `lotics run update_app` (`name`, `public_subdomain`, `capabilities`) |\n| `lotics app api publish` / `unpublish` | `lotics run publish_app_api` / `unpublish_app_api` |\n| `lotics field rename` | `lotics run update_table`, then the same label in the model file |\n| `lotics app kit` | nothing: a custom-code app depends on `@lotics/app-sdk` (below) |\n| `@lotics/xlsx` / `@lotics/docx` to build a template's file | any `.xlsx` / `.docx` library, then `lotics upload` (`lotics docs document_templates`) |\n| `lotics file preview` | `lotics file download <fil_id>`, then open it |\n| `model.json#apply` (`[{package, bind}]`) | state the tables under `entities` \u2014 a model carrying `apply` is refused |\n| `lotics library list` / `library show <slug>`, `lotics preset list` / `preset show <slug>` | the example models at `https://lotics.ai/presets/index.json`, each a complete `model.json` to adapt |\n| `model.json#from` (with `variants`, `rename`) | state every table under `entities` \u2014 a model carrying `from` is refused |\n| `lotics library init <apg_id>`, `lotics setup <apg_id>`, `lotics app upgrade`, `lotics library fixtures` | nothing copies a package any more: write a `model.json` (`lotics docs model`), then `lotics setup model.json` or `lotics model apply model.json` |\n\n`lotics tools` lists every tool, and `lotics tools <name>` prints its input.\n\n**An existing JSON app moves on the first `lotics model apply`** of the model it came from: that\napply binds each app alias to the app it already became and mints its next version from the file.\nA directory an earlier CLI wrote (`app.json`, `src/workflows/`, `.lotics/`, `package.json#lotics`\nwith `plan`, `queries` or `workflows`) is no longer read by anything; keep the model file, delete the\nrest.\n\n**Authored workflow bodies** an act names (`workflow` on an act) are the live workflow's own body:\nthe apply keeps it, and `lotics run set_app_workflow` changes it.\n\n**A model written before `party`** draws its people and organisations as things \u2014 a row with no\npicture shows no initials: state `party` (`person` or `organization`) on those entities' `records`.\n\n## Custom-code apps use `@lotics/app-sdk`\n\nA hand-written app depends on `@lotics/app-sdk` alone \u2014 the hooks (`useQuery`, `useWorkflow`, \u2026),\n`mount`, and `AppRouter` from `@lotics/app-sdk/router` \u2014 and draws with its own React.\n`@lotics/app-runtime` and `@lotics/ui` are no longer published: the runtime is what the platform\ndraws a model's app with, and it ships with the platform.\n\nAn app that listed `@lotics/app-runtime`:\n\n1. **The dependency.** `@lotics/app-sdk` replaces `@lotics/app-runtime` in `package.json`.\n2. **The import specifiers.** `@lotics/app-runtime/sdk` becomes `@lotics/app-sdk`, and\n   `@lotics/app-runtime/router` becomes `@lotics/app-sdk/router` \u2014 in `src/` and in\n   `vite.config.ts`.\n3. **The kit.** An app that imports `@lotics/ui` keeps the version it already installed; no newer one\n   is published. Its screens can stay on it, or move to plain React (or any library) one screen at a\n   time.\n4. **`package.json#lotics`** needs only `app_id`, `workspace_id` and `current_version_id`. The live\n   app owns its `queries`, `workflows`, `agents` and `capabilities`, and `lotics app deploy` refuses\n   a directory that still declares any of them; delete them, and the unread `synced` block.\n5. `lotics app deploy` builds the directory and uploads it as a new version.\n\nA deployed app keeps running on the bundle it shipped until it is deployed again.\n";
+var migration_default = "# @lotics/cli \u2014 migration notes\n\nWhat to DO when a release changes the shape of something the CLI once wrote to disk. Every other\ncontract is `docs/cli_reference.md`; this file is the one a reader opens once, because something\nalready on disk no longer matches what the CLI does.\n\n## Local app projects are gone\n\nAn app built from a model no longer lives in a directory. The live app is the only edit surface:\neach change mints a new version of it, and rolling back to an earlier version is the undo. What\nthe app is \u2014 its screens (`app.json`), its queries, workflows, agents and capabilities, and the\nmodel body it was compiled from \u2014 is held by that version, and the model's tables, fields, options,\ntemplates and roles are the workspace's own.\n\n| What you ran | What replaces it |\n|---|---|\n| `lotics scaffold check` + `scaffold apply` | `lotics model apply <model.json>` \u2014 checks the file, applies the tables and rows, then mints a version of every app it declares |\n| `lotics workspace build <model.json>` | `lotics model apply <model.json>` |\n| `lotics app create --from <model.json>#<app>` | `lotics model apply <model.json> --app <app>` |\n| `lotics app regenerate` | change the model file, then `lotics model apply` |\n| `lotics scaffold diff` | `lotics model apply <model.json> --plan` \u2014 what the apply would change, writing nothing |\n| `lotics scaffold export` | `lotics model pull [-o <model.json>]` \u2014 the workspace's model, rebuilt from what owns each part |\n| `lotics app codegen`, `app check`, `app dev`, `app preview` | nothing local: read an app with `lotics run get_app`, and change it through its tools |\n| `lotics app workflow set` / `app query set` / `app agent set` | `lotics run set_app_workflow` / `set_app_queries` / `set_app_agent` \u2014 each mints a version |\n| `lotics app versions` + a redeploy of an old tree | `lotics run query_app_versions`, then `lotics run rollback_app` \u2014 restores the app's earlier version; table changes and data writes stay |\n| `lotics app rename`, `app subdomain`, `package.json#lotics.capabilities` | `lotics run update_app` (`name`, `public_subdomain`, `capabilities`) |\n| `lotics app api publish` / `unpublish` | `lotics run publish_app_api` / `unpublish_app_api` |\n| `lotics field rename` | `lotics run update_table`, then the same label in the model file |\n| `lotics app kit` | nothing: a custom-code app depends on `@lotics/app-sdk` (below) |\n| `@lotics/xlsx` / `@lotics/docx` to build a template's file | any `.xlsx` / `.docx` library, then `lotics upload` (`lotics docs document_templates`) |\n| `lotics file preview` | `lotics file download <fil_id>`, then open it |\n| `model.json#apply` (`[{package, bind}]`) | state the tables under `entities` \u2014 a model carrying `apply` is refused |\n| `lotics library list` / `library show <slug>`, `lotics preset list` / `preset show <slug>` | the example models at `https://lotics.ai/presets/index.json`, each a complete `model.json` to adapt |\n| `model.json#from` (with `variants`, `rename`) | state every table under `entities` \u2014 a model carrying `from` is refused |\n| `lotics library init <apg_id>`, `lotics setup <apg_id>`, `lotics app upgrade`, `lotics library fixtures` | nothing copies a package any more: write a `model.json` (`lotics docs model`), then `lotics setup model.json` or `lotics model apply model.json` |\n\n`lotics tools` lists every tool, and `lotics tools <name>` prints its input.\n\n**An existing JSON app moves on the first `lotics model apply`** of the model it came from: that\napply binds each app alias to the app it already became and mints its next version from the file.\nA directory an earlier CLI wrote (`app.json`, `src/workflows/`, `.lotics/`, `package.json#lotics`\nwith `plan`, `queries` or `workflows`) is no longer read by anything; keep the model file, delete the\nrest.\n\n**Authored workflow bodies** an act names (`workflow` on an act) are the live workflow's own body:\nthe apply keeps it, and `lotics run set_app_workflow` changes it.\n\n**A model written before `party`** draws its people and organisations as things \u2014 a row with no\npicture shows no initials: state `party` (`person` or `organization`) on those entities' `records`.\n\n## Custom-code apps use `@lotics/app-sdk`\n\nA hand-written app depends on `@lotics/app-sdk` alone \u2014 the hooks (`useQuery`, `useWorkflow`, \u2026),\n`mount`, and `AppRouter` from `@lotics/app-sdk/router` \u2014 and draws with its own React.\n`@lotics/app-runtime` and `@lotics/ui` are no longer published: the runtime is what the platform\ndraws a model's app with, and it ships with the platform.\n\nAn app that listed `@lotics/app-runtime`:\n\n1. **The dependency.** `@lotics/app-sdk` replaces `@lotics/app-runtime` in `package.json`.\n2. **The import specifiers.** `@lotics/app-runtime/sdk` becomes `@lotics/app-sdk`, and\n   `@lotics/app-runtime/router` becomes `@lotics/app-sdk/router` \u2014 in `src/` and in\n   `vite.config.ts`.\n3. **The kit.** An app that imports `@lotics/ui` keeps the version it already installed; no newer one\n   is published. Its screens can stay on it, or move to plain React (or any library) one screen at a\n   time.\n4. **`package.json#lotics`** needs only `app_id`, `workspace_id` and `current_version_id`. The live\n   app owns its `queries`, `workflows`, `agents` and `capabilities`, and `lotics app deploy` refuses\n   a directory that still declares any of them; delete them, and the unread `synced` block.\n5. `lotics app deploy` builds the directory and uploads it as a new version.\n\nA deployed app keeps running on the bundle it shipped until it is deployed again.\n";
 
 // ../shared/src/cli_run.ts
 var cliRun = (tool, args) => `lotics run ${tool} '${JSON.stringify(args)}'`;

package/docs/building_an_app.md

@@ -6,8 +6,7 @@ reach for the area doc (`lotics docs`) whenever you need the detail.
 
 **The live app is the only edit surface.** Every change to an app — applying a model, deploying a
 build, setting one query or workflow — mints a new version of it, and rolling back to an earlier
-version is the undo. Nothing about an app lives in a local directory the platform reads back, so
-there is no project to keep in sync and no deploy to find out whether something works.
+version is the undo. Nothing about an app lives in a local directory the platform reads back.
 
 **Rolling back restores the app, not the data.** A table change the model made, and every row a
 workflow wrote while you tried it, stay where they are. Try a write on a throwaway record.
@@ -115,6 +114,7 @@ cd <dir>
 # edit src/App.tsx — node_modules/@lotics/app-sdk/AGENTS.md is the reference
 npm run typecheck && npm run lint && npm test
 lotics app deploy -m "<what changed>"   # build, upload, a new version live
+lotics app pull <app_id>                # the live version's source, on a machine without the project or after another deploy
 ```
 
 What the app reads and writes is bound on the app, never in the project: `lotics run

package/docs/cli_reference.md

@@ -43,7 +43,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** — the Library's list, `list_knowledge`, and the corpus `grep_knowledge` searches — while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as "everything". |
 | `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |
 | `lotics setup <model.json> [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then applies the model to its workspace, then prints the one-time sign-in link. **When that email already has an account it hands over to the `lotics auth login` flow** — it prints the sign-in page to open and the code it must show, and **exits 1 having created nothing**; the person presses Confirm and runs the same command again, which collects the key and carries on into the model. (`--wait` holds the terminal through the Confirm instead, finishing in one command.) The re-run is not refused for naming an `--email` it is now signed in as — that address IS the account it holds, not a second one. The file is a workspace MODEL, and it is read and checked before an account is created — the design decisions an apply would refuse it for too (`lotics docs design`), since a new workspace holds no rows to change them — because a file with a typo in it must not leave an organization behind. Then it is `lotics model apply` run on the new workspace: its tables, rows and apps; the sign-in link lands on its app when it has one, else on the workspace's app list. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently writes into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` applies the model to the account you already have. A path positional after the file is accepted and IGNORED with a warning — `setup` writes nothing to disk — so a prompt that passes one still runs. **`--json` prints one object on stdout and nothing else** — what `lotics model apply --json` does (`tables`; `apps`, each with `alias`, `app_id`, `version_id`, `origin`, `address` and `findings`; and `findings`) plus `organization_id`, `workspace_id` and `signin_url`, and a `warnings` array carrying everything the prose form would have said out of band, such as a sign-in link that could not be minted. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. Reachable with no install: `npx -y @lotics/cli setup …`. |
-| `lotics model apply <model.json> [--app <alias> ...] [--plan] [--json]` | **The model, applied to this workspace, through the `apply_model` tool.** The file is read and checked against the model's own rules with the validator the server runs, every problem in one run, before anything is uploaded. **The apply refuses an app leaving out a treatment its rows call for** (`lotics docs design`) — judged by the server beside the workspace's rows, before it writes anything — until the app adopts it or states why not under the `declines` key the refusal names; the refusal carries each refused app's patch adopting its decisions, to merge in the order printed. Documents a row attaches by a path beside the file are uploaded first and the rows sent with their `fil_` ids; a path this workspace already recorded keeps its id, so a re-apply uploads nothing twice. **Where the file was pulled (`-o`) or applied in this workspace before, only what it changed since is sent**, as a `patch`: what changed in the workspace since and the file does not touch stays. What the file takes out is sent as a removal: it goes where an apply rebuilds it (an app's acts and columns, a write rule) and is refused, naming the tool that deletes it, where an apply never deletes it (a table, a field, an option, an app). A file that reorders items named by their `alias` sends the whole model, said on stderr. The copy each change is read against is kept per workspace and file under `~/.lotics/model_bases`: an apply narrowed by `--app` leaves in it the other apps as they were, so the next apply sends their edits again, and an apply that fails — refused, or cut off — leaves none, so the next sends the whole model. Then the tool adopts or creates every table (the table this workspace bound the entity to, else an existing table of the same label, is ADOPTED and given the fields, options and views it lacks; no stored value changes), writes first rows only where every bound table is empty, and mints a new version of each app the model declares — `--app` (repeatable, comma-separated) narrows which apps, while the tables are applied whole. Prints one line per app — alias, `app_id`, `created`/`updated` with the version minted or `unchanged`, and the address it is served at — then the model's notes once, as the server states them. **`--plan` writes nothing and uploads nothing**: it prints what the apply would do to the tables (what it would create, what it leaves as the workspace has it, what the two disagree about), which apps it would create or update, and what it would refuse an app for — the decisions among its findings, read beside the workspace's rows, with each refused app's patch — exiting 1 when it would refuse one; workflow bodies are checked only at apply, since they name fields a plan has not created. **A rollback restores an app's earlier version** (`lotics run rollback_app`); table changes and data writes stay. Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, tables, apps, findings}` on stdout (with `--plan`, each table and app is what the apply would do, an app the patches change carrying its body as they leave it as `draft`, and `designs` each refused app's patch in merge order), or `{ok: false, findings}` when the file does not check. |
+| `lotics model apply <model.json> [--app <alias> ...] [--plan] [--json]` | **The model, applied to this workspace, through the `apply_model` tool.** The file is read and checked against the model's own rules with the validator the server runs, every problem in one run, before anything is uploaded. **The apply refuses an app leaving out a treatment its rows call for** (`lotics docs design`) — judged by the server beside the workspace's rows, before it writes anything — until the app adopts it or states why not under the `declines` key the refusal names; the refusal carries each refused app's patch adopting its decisions, to merge in the order printed. Documents a row attaches by a path beside the file are uploaded first and the rows sent with their `fil_` ids; a path this workspace already recorded keeps its id, so a re-apply uploads nothing twice. **Where the file was pulled (`-o`) or applied in this workspace before, only what it changed since is sent**, as a `patch`: what changed in the workspace since and the file does not touch stays. What the file takes out is sent as a removal: it goes where an apply rebuilds it (an app's acts and columns, a write rule) and is refused, naming the tool that deletes it, where an apply never deletes it (a table, a field, an option, an app). A file that reorders items named by their `alias`, or states a `null` a patch would read as a removal, sends the whole model, said on stderr. The copy each change is read against is kept per workspace and file under `~/.lotics/model_bases`: an apply narrowed by `--app` leaves in it the other apps as they were, so the next apply sends their edits again, and an apply that fails — refused, or cut off — leaves none, so the next sends the whole model. Then the tool adopts or creates every table (the table this workspace bound the entity to, else an existing table of the same label, is ADOPTED and given the fields, options and views it lacks; no stored value changes), writes first rows only where every bound table is empty, and mints a new version of each app the model declares — `--app` (repeatable, comma-separated) narrows which apps, while the tables are applied whole. Prints one line per app — alias, `app_id`, `created`/`updated` with the version minted or `unchanged`, and the address it is served at — then the model's notes once, as the server states them. **`--plan` writes nothing and uploads nothing**: it prints what the apply would do to the tables (what it would create, what it leaves as the workspace has it, what the two disagree about), which apps it would create or update, and what it would refuse an app for — the decisions among its findings, read beside the workspace's rows, with each refused app's patch — exiting 1 when it would refuse one; workflow bodies are checked only at apply, since they name fields a plan has not created. **A rollback restores an app's earlier version** (`lotics run rollback_app`); table changes and data writes stay. Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, tables, apps, findings}` on stdout (with `--plan`, each table and app is what the apply would do, an app the patches change carrying its body as they leave it as `draft`, and `designs` each refused app's patch in merge order), or `{ok: false, findings}` when the file does not check. |
 | `lotics model pull [-o <model.json>]` | **This workspace's model, rebuilt from what owns each part** — the tables, fields, options, templates and roles the workspace holds, how rows are recognised, and each app's body from its current version — through the `get_model` tool, as the file `model apply` reads: to stdout, or to the file `-o` names. What the workspace holds that a model cannot state is printed on stderr, never written into the file. Applying what it wrote changes nothing. With `-o`, what it wrote is the copy the next `model apply` of that file reads its changes against. |
 | `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`), scaffolds a Vite + React + TypeScript project into `[path]` (default `./<name>`, refused when not empty — before the app row exists) that depends on `@lotics/app-sdk` alone and draws with plain React, and installs it (`npm install --ignore-scripts`), then writes the declarations of the app's live bindings (`get_app_types`) into `.lotics/`, which the project's `tsconfig.json` includes. `package.json#lotics` names the app and its workspace, which is how `app deploy` in that directory finds both. The app has no version until the first `lotics app deploy`. `--custom` is required: an app the runtime draws from a model is made by `lotics model apply`. The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the project. |
 | `lotics app pull [app_id] [path]` | **A custom-code app's live source, as a project ready to deploy on it.** The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** — but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`get_app_types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). A JSON app has no source tree: the server's refusal names `get_model`, and `lotics model pull` is its pull. |

package/docs/document_templates.md

@@ -130,7 +130,7 @@ lotics download <file_id> -o ./out/
   `table`/`list`/loop variables. `filename` excludes the extension (the type sets it).
 - `generate_document` renders the template's own type and returns a generated file object; take
   its `file_id` onward.
-- In a workflow, a **generate step** calls the same tools and hands the `file_id` to the next
+- In a workflow, a **generate step** calls the same tool and hands the `file_id` to the next
   step (attach to a record, send as an attachment, etc.).
 
 ## Discovering and managing templates

package/docs/field_values.md

@@ -27,6 +27,8 @@ one value.
 - A single-select is a ONE-element array; a bare `"opt_…"` is accepted and wrapped. A single
   `select_member` takes a bare `"mbr_…"` the same way.
 - `select_record_link` and `files` take an array only.
+- A `files` id the write adds must name a live file of this workspace, or the whole write is refused;
+  an id that cell already holds stays, though its file was archived since.
 - Two options on a single-select, or two members on a single `select_member`, are refused.
 - `update_records`' `add_to`, `remove_from` and `replace` take arrays of the same items: `opt_` keys
   for a select, member ids for a `select_member`, record ids for a `select_record_link`, file ids for

package/docs/migration.md

@@ -20,7 +20,7 @@ templates and roles are the workspace's own.
 | `lotics app regenerate` | change the model file, then `lotics model apply` |
 | `lotics scaffold diff` | `lotics model apply <model.json> --plan` — what the apply would change, writing nothing |
 | `lotics scaffold export` | `lotics model pull [-o <model.json>]` — the workspace's model, rebuilt from what owns each part |
-| `lotics app pull`, `app codegen`, `app check`, `app dev`, `app preview` | nothing local: read an app with `lotics run get_app`, and change it through its tools |
+| `lotics app codegen`, `app check`, `app dev`, `app preview` | nothing local: read an app with `lotics run get_app`, and change it through its tools |
 | `lotics app workflow set` / `app query set` / `app agent set` | `lotics run set_app_workflow` / `set_app_queries` / `set_app_agent` — each mints a version |
 | `lotics app versions` + a redeploy of an old tree | `lotics run query_app_versions`, then `lotics run rollback_app` — restores the app's earlier version; table changes and data writes stay |
 | `lotics app rename`, `app subdomain`, `package.json#lotics.capabilities` | `lotics run update_app` (`name`, `public_subdomain`, `capabilities`) |

package/package.json

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