@lotics/cli 0.302.0 → 0.303.1

package/docs/app_bindings.md

@@ -55,7 +55,7 @@ Every node has a `kind`; all but `from_table` read the node under `from` (`join`
 | `filter` | `predicate` — a filter tree over the input's columns |
 | `join` | `left`, `right`, `on: { left_column, right_column }`, `type: "inner" \| "left"` |
 | `union` | `sources` (at least two, columns aligned by name and type) |
-| `group` | `by` (columns, or `{ bucket: { source, granularity, output } }`), `aggregates` |
+| `group` | `by` (columns, `{ bucket: { source, granularity, output } }`, or `{ band: { source, tiers, output } }`), `aggregates` |
 | `window` | `partition_by`, `order_by`, `frame?`, `aggregates?`, `functions?` |
 | `sort` | `by: [{ field_key, order }]` |
 | `limit` | `n`, `offset?` or `keyset?` |
@@ -124,7 +124,12 @@ keeps the type tracking the live field.
 ## Workflows
 
 `set_app_workflow` binds a workflow body to an alias: `{ app_id, alias, source, inputs?, outputs?,
-name?, description? }`.
+name?, description? }`. On an app built from a model, the alias is one the model names — an act's own
+`workflow`, or an entry of the app's `workflows`, which states `inputs`, `outputs` and `description`:
+a call stating any of them for it is refused, and outputs the entry leaves out are derived from the
+body. An alias the model names nowhere is archived by the next apply. An entry of `workflows` runs
+only for someone who holds the app: on an app shared by a public link, a visitor's call of it is
+refused as an alias the app does not have.
 
 - `source` is the body with no `on({...})` trigger — the app is the trigger. It reads each declared
   input as `trigger.app_workflow.inputs.<name>`; no record is in scope, so it reads each one by id

package/docs/building_an_app.md

@@ -102,7 +102,11 @@ decisions beside the workspace's rows, and with `--json` gives each app as the p
 
 **The model changes after the app exists, and applying it again is how it lands.** Edit the file,
 apply it. An act whose write the model cannot say names its own `workflow`; that workflow's body is
-the live one, and `lotics run set_app_workflow` changes it. An act that reads papers runs an agent
+the live one, and `lotics run set_app_workflow` changes it. A job no press starts — an agent or a
+service handing the app a file or a list of rows — is a workflow the app declares in `workflows`
+(`lotics docs model/apps`): the model states what it takes and hands back, `lotics run
+set_app_workflow` sets its body with `inputs` and `outputs` left out, and every apply keeps that
+body. A workflow set on the app that its model declares nowhere is archived by the next apply. An act that reads papers runs an agent
 apply owns: made, replaced and removed with the act, and an agent of that alias apply did not make
 is refused, never rewritten.
 
@@ -181,7 +185,9 @@ model finds of that app now, beside its rows — what the next apply would refus
 on it, the `patch` adopting the decisions among them, and the app's body as the patch
 leaves it (`draft`). `verdict_unread` says why none was read.
 
-Then set the icon, the colour and the app's own `description` through `lotics run update_app`. The
+The app's `name`, `icon`, `theme` and `description` are keys of the app in the model, and each apply
+writes them onto the app; one the model leaves out is cleared. `lotics run update_app` changes them on
+the app, and `lotics model pull` reads them back as the app holds them. The
 `description` heads the capability listing the member's chat agent reads on **every** turn, so a
 standing process the app expects that agent to carry out belongs there and nowhere else.
 

package/docs/workflow_steps.md

@@ -980,6 +980,37 @@ above. A provider's refusal carries the provider's own words.
 | `truncated_cells[].cell` | string | yes | Cell address |
 | `truncated_cells[].original_length` | number | yes | Original text length |
 
+### excel_get_rows (workflow step)
+
+- Read every row of a sheet in an .xlsx, .xls or .csv file as a list of objects keyed by the header row's text.
+- A cell is its typed value: a number, true or false, text, a date as ISO text ("2026-03-02", "2026-03-02T09:30:00", or "09:30:00" for a time alone), null when blank.
+- A formula cell is the value the file last computed; an error cell is its code as text ("#N/A").
+- Every CSV cell is text or null.
+- A header cell inside a merge takes the merge's text; a blank header is keyed by its column letter ("C"), and a header text that repeats gets its column letter added ("Amount (F)"). headers lists the keys in sheet order.
+- Rows above header_row and rows blank in every column are left out.
+- One call reads a sheet of at most 10000 rows, its header counted, and returns at most 250000 cells (rows × kept columns); a sheet past either is refused with its row count, never cut short.
+- Read-only.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `worksheet` | string \\| number |  | Sheet name, or 0-based index. |
+| `header_row` | number |  | 1-based row holding the headers. |
+| `columns` | string[] |  | Keys to keep, as headers lists them. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `worksheet_name` | string | yes |  |
+| `header_row` | number | yes |  |
+| `headers` | string[] | yes | The key of each returned column, in sheet order |
+| `row_count` | number | yes |  |
+| `rows` | object[] | yes |  |
+
 ### excel_update_range (workflow step)
 
 - Write cell values into a range in an Excel worksheet. range format is always "START:END" — single cell: "B2:B2", multi-cell: "A1:C3".

package/docs/workflows.md

@@ -24,11 +24,6 @@ on({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });
 Every source below is typed, so a misspelled member is refused at save rather than read as nothing.
 All three carry `trigger.trigger_id`.
 
-An automation that brings rows in — on a schedule, or a webhook an outside system calls — is marked
-as importing into their table with `imports_into` (a table id) when it is created or edited. Its
-runs are then the imports log of a register over that table that keeps one (`register.imports`);
-on the CLI, `get_automation` and `query_automations` read the mark back.
-
 | trigger | required config | what the body reads |
 |---|---|---|
 | `recurring_schedule` | `cron_expression` | `runtime.timezone`; the current time is `now()` |
@@ -288,6 +283,46 @@ if (customer && includes(record["fld_customer"], customer.id)) {
 }
 ```
 
+Read an uploaded sheet and add the rows a table lacks. `excel_get_rows`, a workflow step, answers every
+row of an `.xlsx`, `.xls` or `.csv` sheet in one call, each an object keyed by the header row's text. A cell is a number,
+`true` or `false`, text, a date as ISO text, or null when blank, so `row["Header"]` is typed
+`string | number | boolean | null` and a helper narrows it: `toString` for text, `toNumber` for a number,
+`isString` before a date. Every cell of a `.csv` is text. `columns` keeps only the ones the body reads.
+A sheet past what one call reads is refused with its size, never cut short: the step's entry in
+`workflow_steps` states the bounds.
+
+A table can hold more rows than one page of `query_records` answers, so the body never reads "the
+table" to see what it lacks. It takes the sheet fifty rows at a time — what one `create_records` call
+writes — asks the table for those rows' codes alone, and writes the rest in one call:
+
+```
+const sheet = await excel_get_rows({ // a workflow step
+  file_id: trigger.app_workflow.inputs.file,
+  columns: ["Code", "Filed", "Amount"],
+});
+
+for (let start = 0; start < sheet.row_count; start += 50) {
+  const rows = uniqueBy(slice(sheet.rows, start, start + 50), (row) => toString(row["Code"]));
+  const held = await query_records({
+    table_id: "tbl_declarations",
+    filters: { field_key: "fld_code", operator: "is_any_of", value: rows.map((row) => toString(row["Code"])) },
+    pagination: { offset: 0, limit: 1000 },
+  });
+  const known = held.records.map((r) => toString(r.data["fld_code"]));
+  const fresh = filter(rows, (row) => !includes(known, toString(row["Code"])));
+  if (size(fresh) > 0) {
+    await create_records({
+      table_id: "tbl_declarations",
+      records: fresh.map((row) => ({
+        fld_code: toString(row["Code"]),
+        fld_filed: isString(row["Filed"]) ? row["Filed"] : null,
+        fld_amount: toNumber(row["Amount"]),
+      })),
+    });
+  }
+}
+```
+
 ## Table lifecycle workflows
 
 A lifecycle workflow is bound to one table and one event, and its source has no `on({...})` line:

package/package.json

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