@lotics/cli 0.315.18 → 0.316.1

package/docs/document_templates.md

@@ -5,18 +5,19 @@ labels, emails — by filling a reusable template instead of writing a file from
 You register a template once, then generate a filled file (or a rendered email) from it as
 many times as you like, feeding it data from records, a workflow, or an agent run.
 
-This is a **capability + usage** guide. For the exact input schema of any tool named here,
-run `lotics tools <tool_name>` — that is always the source of truth for arguments.
+This is a **capability + usage** guide. A tool's exact input schema is in its own description.
 
 ## The five template types
 
-| Type | What it fills | Output | Create with |
+`set_template` writes all five. Its `type` names which one a new template is.
+
+| Type | What it fills | Output | `type` |
 |---|---|---|---|
-| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `create_pdf_template` (mode `form`), on the CLI or in chat |
-| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `create_pdf_template` (mode `html`), on the CLI or in chat |
-| `excel` | an **uploaded `.xlsx`** with `{{marker}}` cells | `.xlsx` | `create_excel_template` |
-| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `create_word_template` |
-| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `create_email_template`, on the CLI or in chat |
+| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `"pdf-form"` |
+| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `"html"` |
+| `excel` | an **uploaded `.xlsx`** with `{{marker}}` cells | `.xlsx` | `"excel"` |
+| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `"word"` |
+| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `"email"` |
 
 Two shapes underneath: **file-backed** (`pdf-form`, `excel`, `word`) clone an uploaded
 office file and mark it up; **inline** (`html`, `email`) store the markup you author directly.
@@ -29,71 +30,63 @@ office file and mark it up; **inline** (`html`, `email`) store the markup you au
    template id, a `filename` (no extension), and a `data` map keyed by your variable names.
    It substitutes the markers and returns a **generated file** (with a `file_id`).
 3. **Chain** the result — generation only *produces* the file. Attaching it to a record,
-   sending it, or saving it locally is a separate step: inside a workflow, pass the returned
-   `file_id` to the next step; from the CLI, `lotics download <file_id>` fetches it.
+   sending it, or saving it is a separate step: `update_records` with `add_to` on a files field
+   files the `file_id` on a record (`remove_made`, a template id, takes out the paper that template
+   made earlier); over MCP and on the CLI, `download_file` fetches it; inside a workflow, pass the `file_id` to the next
+   step. A paper an app makes is its Act's `template`, which files it on the record itself
+   (below).
 
 Email is the exception: `generate_document` refuses an email template. An email template is
 rendered to a subject + body **at send time** from the template and the data the send step
-supplies — so you author it with `create_email_template` (on the CLI or in chat) and a workflow/app send step (or the
+supplies — so you author it with `set_template` and a workflow/app send step (or the
 web composer) does the rendering and delivery. External agents send their own email directly.
 
-## Creating each type
-
-### PDF from HTML
-
-Write a full HTML document with inline CSS and `{{variable}}` placeholders, as `create_pdf_template`
-with mode `html` on the CLI or in chat; it renders to PDF via a headless browser. Good for invoices, reports, letters, certificates — anything whose
-layout you control. Declare `variables` (plain text, rich `html`, an auto-rendered `table`,
-or a `list`), and optionally `format` (page size) and `orientation`. See
-`lotics tools create_pdf_template` for the exact variable shapes.
-
-### PDF form
-
-For an existing PDF you must fill in place (a government form, a printed contract), on the CLI or in chat:
-
-1. `lotics upload ./form.pdf` → a `file_id`.
-2. `create_pdf_template` with mode `form` and that `file_id`.
-3. `analyze_pdf_template` — extracts the labels and their positions off the page.
-4. `update_pdf_template` — define the positioned fields (`text` / `checkbox` / `image`, each
-   with a page + x/y/size) in `variables`.
-
-Form-mode data is scalar-only (text, numbers, checkboxes) — one value per positioned field.
-
-### Excel
-
-1. Build a `.xlsx` in Excel (or with any spreadsheet library) and put `{{marker}}`s in the cells that
-   should be filled. `lotics upload ./template.xlsx` → a `file_id`.
-2. `create_excel_template` with that `template_file_id` and a `variables` map. Markers are
-   **validated at create time** — a structural error (mismatched loop, unknown helper, bad
-   placement) blocks the save, and declared variables with no matching marker come back in
-   `unmarked_variables` (skipped, not filled).
-
-On the CLI, `validate_excel_template` checks an uploaded file's markers without creating a template. Pass
-raw numbers / ISO dates / booleans at generate time — the cell's number format handles display.
-
-### Word
-
-1. Build a `.docx` with `{{marker}}`s where values go. `lotics upload ./template.docx`.
-2. `create_word_template` with the `template_file_id`. `variables` is optional — every
-   marker in the document is derived automatically (`{{name}}` → string,
-   `{{FOR … IN name}}` → array, `{{IF name}}` → boolean). When you do declare, an unmarked
-   declaration comes back in `unmarked_variables` and is skipped, and markers you didn't
-   declare are still auto-added (`derived_variables`) — the stored contract always covers
-   every marker in the document.
-
-At generate time, `data` must provide a key for **every** marker — pass `""` for fields
-that should render blank; a missing key fails with the full list of missing markers.
-
-### Email
-
-Inline HTML + Handlebars, no uploaded file — `create_email_template`, on the CLI or in chat. Declare `variables`, and optionally a default
-`subject` (which itself supports `{{variable}}` expressions) and default to/cc/bcc. The body
-and subject render from the data at send time.
+## Creating and changing a template
+
+A paper prints the owner's own terms only: the clauses, wording and fields of the sample they sent, never a term the owner did not state.
+
+`set_template` creates a template when it is given no `template_id`, and changes the named one
+when it is given one. Creating takes `type` and `name`, and the fields of its type; changing takes
+`expected_version` — the `current_version` that `get_template` returned, so a concurrent edit is
+refused rather than overwritten — and only the fields to change. A field the type does not take is
+refused rather than dropped. `description` (one line on what the template produces) is on every type.
+
+### Getting a file in
+
+A file-backed template starts from a file in the workspace: over MCP and on the CLI, `upload_file` takes a public URL,
+or bytes you hold, and returns a `file_id`. When the person has the file and your host shows you its content but not its
+bytes, `upload_file` with `person: true` returns a `drop_url` for them to open and a `ticket_id` per file; once they say
+they dropped it, `upload_file` with that `ticket_id` returns the `file_id`.
+
+A new Word or Excel paper is a file you build yourself, in your own filesystem or sandbox, with its markers typed where
+the values go, then, over MCP or on the CLI, send it with `upload_file` `files` and register with `set_template`. Where your sandbox cannot reach
+this host, give the person the file and a `person` drop link.
+
+### By type
+
+- **`html`** — a full HTML document with inline CSS and `{{variable}}` placeholders, rendered to PDF; anything whose layout
+  you control. `variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (page size) and
+  `orientation` are optional. A change may send `patch_ops`, exact search-and-replace edits of the stored markup, in place
+  of the whole `template`.
+- **`pdf-form`** — an existing PDF filled in place. `set_template` with the uploaded `template_file_id`;
+  `analyze_pdf_template` reads the labels and positions off the page; `set_template` again with `expected_version` and the
+  positioned `variables` (`text` / `checkbox` / `image`, each with a page and x/y/size). Data is one scalar per field.
+- **`excel`** — a `.xlsx` with `{{marker}}`s in the cells to fill, and a `variables` map. Markers are validated at create
+  time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables`
+  (skipped). Over MCP and on the CLI, `validate_excel_template` checks a file's markers without creating a template. Pass
+  raw numbers, ISO dates and booleans at generate time; the cell's number format shows them.
+- **`word`** — a `.docx` with `{{marker}}`s. `variables` is optional: every marker is derived (`{{name}}` string,
+  `{{FOR … IN name}}` array, `{{IF name}}` boolean), and a marker you did not declare is still added
+  (`derived_variables`). At generate time `data` needs a key for **every** marker, `""` for a blank one. A marker may run
+  across formatting runs and is still read whole. In a table, the row holding `{{FOR line IN lines}}` and the row holding
+  `{{END-FOR line}}` enclose the row that repeats.
+- **`email`** — inline HTML + Handlebars, with `template` and `variables`; optionally a default `subject` (it takes
+  `{{variable}}` too) and `default_to`, `default_cc`, `default_bcc`. Body and subject render from the data at send time.
 
 ## Markers, at a usage level
 
 Every type supports three shapes of substitution. The exact syntax differs per engine — read
-the create-tool description for the reference; here is the capability:
+the `set_template` description for the reference; here is the capability:
 
 - **Scalar** — a single value in one spot: `{{name}}`, `{{total}}`. Whole-cell scalars in
   Excel preserve their type via the cell's number format.
@@ -102,60 +95,103 @@ the create-tool description for the reference; here is the capability:
   `{{#each items}}…{{/each}}`; Word uses `{{FOR item IN items}}…{{$item.field}}…{{END-FOR item}}`. The HTML and email types
   also offer an auto-rendered `table` variable — declare its columns and pass an array, no
   hand-written loop. (Excel always uses the `{{#each}}` marker rows — it has no auto-rendered
-  `table` type; its variable types are string/number/date/boolean/array.)
+  `table` type; its variable types are string/number/date/boolean/array.) Inside a loop the row's number counted from 1
+  is `{{@ordinal}}` (Excel, HTML, email) or `{{$ordinal}}` (Word), the innermost loop's: an STT column is a cell holding
+  `{{@ordinal}}` beside the row's other markers. `{{@index}}` counts from 0.
 - **Conditional sections** — a block shown only when a condition holds (a "paid" stamp, an
   optional notes block). Excel/HTML/email use `{{#if}}…{{else}}…{{/if}}`; Word uses `{{IF name}}…{{END-IF name}}`.
 
-The `html` and `email` types format a raw value with a helper, in the template's `locale` (`vi` or `en`, set at
-create or update; none prints in the organization's language); an empty value prints `""`:
-`{{money total "VND"}}` → `28.000.000 ₫` (`en`: `₫28,000,000`), `{{number qty}}` → grouped, up to 2 decimals,
-`{{date issued_on}}` → `14/09/2026` (a moment on the workspace's timezone; a date-fns pattern as the second argument,
-literal text quoted: `"'Ngày' dd"`), and `{{words total "USD"}}` → `Một nghìn đô la Mỹ năm mươi xu` (`en`: `One
-thousand US dollars and fifty cents`; no code reads VND); `{{date (add_days issued_on -1)}}` prints the day before, `add_days`
-shifting a date by whole days. A value the helper cannot read fails the render.
+The `html` and `email` types print a raw value through a helper in the template's `locale` (`vi` or `en`; none prints in the organization's language): `{{money total "VND"}}`, `{{number qty}}`, `{{date issued_on}}`, `{{words total "USD"}}` (`model/groups-and-templates` lists what each prints). `{{date (add_days issued_on -1)}}` prints the day before, `add_days` shifting a date by whole days. A value a helper cannot read fails the render.
+
+A field can also print as a **QR code** or a **Code 128 barcode** (a picture a phone's camera or a scanner reads back): `{{qr link}}` or `{{code128 position 6}}` in html (never email: mail clients do not show the picture, and a save refuses it), `{{position | qr}}` or `{{position | code128:6}}` as a whole Excel cell (its row grows to the picture), `{{IMAGE qr(position)}}` or `{{IMAGE code128(position, 6)}}` in Word. The optional number is the picture's width in centimetres. Without it the width follows the value's length — each module prints 0.5 mm in a QR code and 0.33 mm in a barcode, so a longer value prints wider; a width that would shrink a module below what a scanner reads (0.3 mm, 0.19 mm) is refused, naming the least width that scans. An empty field draws nothing.
+
+A record's **photos** (a files field, an act's paper hands each as a file cell `{id, name, mime, url}`) print too, and only for a file whoever makes the paper may read — the same rule the file proxy applies; any other file is never drawn. html: `{{#each photos}}<img src="{{url}}">{{/each}}` (only the data's file cells are inlined; a url typed into a text field stays a link). Word: `{{IMAGE picture(cover, 8)}}`, and `{{FOR p IN photos}}{{IMAGE picture($p, 8)}}{{END-FOR p}}` for several. Excel: `{{cover | picture:6}}` as the whole cell, or `{{this | picture}}` inside `{{#each photos}}` (each row grows to its picture). The number is the width in centimetres (8, or 6 in Excel, by default). `picture` takes one image file: a list (loop over it), a file that is no image or one that cannot be read is refused by name. Photos are embedded at most 1600 pixels across, about 200 dpi at 20 cm.
+
+A Word command (`{{ … }}`) reads the data and calls, by name, a Word helper (`picture`, `qr`, `code128`) or one of these text
+and number functions: `trim`, `trimStart`, `trimEnd`, `lower`, `upper`, `capitalize`, `replace`, `replaceAll`, `removeChars`, `removeSpaces`,
+`startsWith`, `endsWith`, `contains`, `substring`, `padStart`, `padEnd`, `length`, `join`, `split`, `repeat`, `formatNumber`,
+`formatDecimal`, `numberToWords`. It holds no JavaScript method or regular-expression literal: `{{upper(name)}}`,
+`{{formatDecimal(total, 0, "vi-VN")}}`, and `{{removeSpaces(removeChars(cccd || "", ".…"))}}` for the text without its dots,
+ellipses and spaces. `removeChars(text, chars)` removes every character of `text` that occurs in `chars` (a set of characters,
+never a pattern); `removeSpaces(text)` removes every whitespace character of `text`, anywhere in it, the set `trim` trims.
+
+A field named like a function is read as the field, and calling the function then fails.
 
-Run `lotics tools create_excel_template`, `create_word_template`, `create_pdf_template`, or
-`create_email_template` for each engine's exact marker grammar and helper list — don't guess it.
+`set_template`'s description holds each type's exact marker grammar and helper list.
 
 ## Generating a filled file
 
-```bash
-# See what a template expects, then fill it
-lotics tools generate_document
-lotics run get_template '{"template_id":"dtl_..."}'          # its declared variables
-lotics run generate_document '{"document_template_id":"dtl_...","filename":"invoice-1042","data":{"company_name":"Acme","total":1042,"items":[...]}}'
-lotics download <file_id> -o ./out/
+```
+get_template        {"template_id": "dtl_…"}                       # its declared variables
+generate_document   {"document_template_id": "dtl_…", "filename": "invoice-1042",
+                     "data": {"company_name": "Acme", "total": 1042, "items": [...]}}
 ```
 
 - `data` is a map keyed by your variable names. Scalars for scalar/form fields; arrays for
-  `table`/`list`/loop variables. `filename` excludes the extension (the type sets it).
+  `table`/`list`/loop variables. `filename` excludes the extension (the type sets it). Pass a select, a
+  member or a link as `get_record`'s `display` words, a number and a date raw.
 - `generate_document` renders the template's own type and returns a generated file object; take
   its `file_id` onward.
+- A PDF no template is wanted for takes `html`, a `filename` and its `data` in place of `document_template_id`: the markup is
+  rendered as an `html` template is (the same markup rules, markers and helpers) and the PDF is stored as a workspace file. Name one of the two.
 - 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
+## A template an app's Act makes
 
-Four unified tools work across all five types:
+An Act with `template` (or `templates`) fills an `html`, `excel` or `word` template from its record and files the result
+(a PDF, an `.xlsx` or a `.docx`) in the record's files field `into`; `run_app_workflow` on `act_<key>` (or the `workflow` the Act names) presses it. The Act hands the template the record's fields by their
+alias, so name each variable after one: `{{customer}}`, `{{total}}`. A select, a member and a link arrive as their words
+(a link as the linked row's title); a number and a date arrive raw, for `{{money total "VND"}}` and `{{date issued_on}}`.
+The rows of each child the record draws arrive under the name of the record's own link to them, for a loop:
 
-| Tool | Does |
-|---|---|
-| `query_templates` | list templates (optionally filter by type: excel/word/pdf/email) |
-| `get_template` | one template's full definition, incl. the `variables` it expects |
-| `clone_template` | copy a template to iterate on, on the CLI or in chat |
-| `delete_template` | remove a template, on the CLI or in chat |
+```html
+<h1>Quote {{code}}</h1>
+<p>{{customer}} — {{money total "VND"}}</p>
+{{#each lines}}<p>{{description}} × {{quantity}}</p>{{/each}}
+```
 
-Call `get_template` before generating when you don't already know a template's variable names.
+Here `code`, `customer` and `total` are fields of the record and `lines` is its link to the child table. The rows
+also arrive under the child table's `ref` (`quote_line`), so `{{#each quote_line}}` fills as well; a Word template loops the same rows with `{{FOR line IN lines}}` …
+`{{$line.description}}` … `{{END-FOR line}}`.
+
+Every List the record draws and the template names (an html template's variables, a Word template's markers) hands its
+rows, each List's `where` applied; a List the template does not name is not read. A List that only reads hands them under its
+`key` (the table's alias where it states none), and a List that sums a number hands the sums under `<name>_totals`, one
+entry per number the List draws as a column or as the table's figure. A `where` bound may be `{ "record": "<field>" }`,
+a date or number the record itself holds, so a record can print a window of its own days. A service plan row (customer,
+`period_start`, `period_end`) draws the customer's visits within its period:
 
-## Reaching the tools
+```
+{ "type": "List", "key": "visits", "entity": "visit", "same": "customer", "label": "Visits", "columns": ["visited_on", "hours"],
+  "where": { "visited_on": { "gte": { "record": "period_start" }, "lte": { "record": "period_end" } } } }
+```
 
-```bash
-lotics tools                              # all categories
-lotics tools create_word_template         # one tool: full description + input schema
-lotics run <tool> '<json-args>'           # execute (inline JSON, @file.json, or `-` for piped stdin)
+```html
+{{#each visits}}<p>{{visited_on}} — {{hours}} h</p>{{/each}}
+<p>Total {{visits_totals.hours}} h</p>
 ```
 
-The template tools live in the categories **PDF Templates**, **Excel Templates**,
-**Word Templates**, **Email Templates**, and **Templates** (the unified query/get/clone/delete).
-Uploading the source file for a file-backed template is `lotics upload <file>`; fetching a
-generated file is `lotics download <file_id>`.
+A bound the record leaves blank, or holds as anything but one whole day (`2026-05`) or one figure, keeps no row:
+`visits` is empty and `visits_totals.hours` is `0`. The sums add a number as the List's foot does: a cell holding a
+figure adds it, any other cell (blank, an errored formula, a lookup's list) adds nothing. A Word template loops
+`{{FOR v IN visits}}` and prints `{{visits_totals.hours}}` the same way. A template that names a List narrowed to the
+reader (`"me"`) is refused, and so is a name a rows List and a `list` List both reach: give the `list` a `key`. A record
+bound narrows what is listed and is never an access bound; the table's row rules are.
+
+A paper over many rows (a client's month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act's `template`; or a List `Export` with `template` and `per` (`model/export-node`).
+`model/groups-and-templates` has the rest.
+
+## Discovering and managing templates
+
+These tools work across all five types:
+
+| Tool | Does |
+|---|---|
+| `get_workspace` | list the workspace's templates (`kind: "template"`), each with its id, type and one line |
+| `get_template` | one template's full definition, incl. the `variables` it expects and the `current_version` a change needs |
+| `set_template` | create a template, or change one |
+| `clone_template` | copy a template to iterate on, in chat |
+| `delete_template` | remove a template |
+
+Call `get_template` before generating when you don't already know a template's variable names.