@dforge-core/dforge-mcp 0.2.42 → 0.2.44

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.2.44 — 2026-10-21
+
+**Schemas follow metadata 0.0.44.** `dforge://schema/translations` describes `storedProcedures`
+(result-column headers of a stored procedure, shared by every report bound to it) and a report's
+`desc`. `dforge://schema/reports` accepts `fieldTypeCd`, `format` and `baseDatatypeCd` on a dataset's
+`columnsDef`. `dforge://schema/entity` accepts a trait declared in the module's own `traits.json`.
+
+**DSL builtins.** `printPdf(entityCd, key, templateCd)` renders a print template to a PDF as the current
+user; `sendEmail()` takes a fourth `attachments` argument (a `printPdf()` result or an array of them);
+`downloadText()` / `downloadBase64()` hand the user a file the script built, in any code page.
+
+**Needs `@dforge-core/dforge-cli` 0.2.35**, which compiles the above, requires a translation per
+stored-procedure column on `dforge_module_pack` / `dforge_module_validate`, refuses a request filter
+with an unknown operator instead of dropping it, and reads and generates every module file with LF
+line endings on every platform.
+
+## 0.2.43 — 2026-10-19
+
+**Schemas follow metadata 0.0.43.** `dforge://schema/registers` describes `analyticTotals` (an
+accounting register's cache keyed by analytics as well, for the accounts its chart flags), and
+`dforge://schema/entity` describes `lineDateField` (an `A` column dating each line's movement by a
+line column instead of `dateField`).
+
+**Print-forms reference.** `references/print-templates.md` now covers what the platform does:
+a child set loads wherever the template names it (`sort`, `.size`, `.first`), with the recipe for
+sorting by one or several columns; formula columns are read from SQL like `data.get`, so `TODAY()`
+works and a reference-navigating formula prints; and an amount or quantity written in words with the
+`common-words` module (`common-words.money` / `common-words.quantity`, languages `uk`, `en`, `de`, the
+inputs, the engine pitfalls). The two mistakes the old text taught (a set loads only from a `for`;
+`TODAY()` is skipped in print) are removed.
+
+**Registers reference.** `references/registers.md` describes `analyticTotals` and `lineDateField`.
+
+**Needs `@dforge-core/dforge-cli` 0.2.33**, which installs both, adds `register rebuild-totals --cache`
+and `module install --allow-rewrite` (a type change that rewrites a table over 1 GB is refused
+without it).
+
 ## 0.2.41 — 2026-10-15
 
 **Schemas follow metadata 0.0.42.** `dforge://schema/entity` describes `periodGuards` (a closed-period

package/dist/server.js

@@ -31002,7 +31002,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.32/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.35/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31290,7 +31290,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.42/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.44/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -34622,7 +34622,7 @@ var path10 = __toESM(require("path"));
 var fs7 = __toESM(require("fs"));
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.42/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.44/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -35474,9 +35474,9 @@ var BUILTINS = [
   },
   {
     name: "sendEmail",
-    signature: "sendEmail(to, subjectOrTemplate, dataOrBody?)",
+    signature: "sendEmail(to, subjectOrTemplate, dataOrBody?, attachments?)",
     returns: "void",
-    doc: "Queue an outbound email. Three arguments, and the **second** picks the mode: `sendEmail(to, 'order.shipped', { ref: [code] })` sends a template, `sendEmail(to, 'Your order shipped', '<p>\u2026</p>')` sends raw HTML. A second argument with no spaces that contains `.` or `_` is read as a template code \u2014 so a raw subject like `'Shipped.'` silently becomes one; give a raw subject spaces. There is no fourth argument."
+    doc: "Queue an outbound email. Three arguments, and the **second** picks the mode: `sendEmail(to, 'order.shipped', { ref: [code] })` sends a template, `sendEmail(to, 'Your order shipped', '<p>\u2026</p>')` sends raw HTML. A second argument with no spaces that contains `.` or `_` is read as a template code \u2014 so a raw subject like `'Shipped.'` silently becomes one; give a raw subject spaces. The optional **fourth** argument attaches files: a `printPdf()` result, or an array of them (`[a, b]`; pass a single file as itself, because a one-name `[a]` reads as a field reference in the DSL). Only a `printPdf()` result can be attached, and only by the user who generated it (or a workspace admin); at most 5 files and 10 MB in all per email (`Email:MaxAttachments`, `Email:MaxAttachmentBytes`). A file the sender may not attach fails the action. Not available in a scheduled job, whose emails with attachments are not queued."
   },
   // External calls
   {
@@ -35515,7 +35515,19 @@ var BUILTINS = [
     name: "download",
     signature: "download(url, fileName?)",
     returns: "void",
-    doc: "Set a download URL on the action result; the browser opens it when the action returns. It fetches nothing and stores nothing \u2014 the URL must already serve the bytes, e.g. the `/api/temp-file/{token}` a service handed back. To put a remote file INTO storage, fetch it with `callApi()` and write it to a file column."
+    doc: "Set a download URL on the action result; the browser opens it when the action returns. It fetches nothing and stores nothing \u2014 the URL must already serve the bytes, e.g. the `/api/temp-file/{token}` a service handed back. To hand over a file the script builds, use `downloadText()` / `downloadBase64()`. To put a remote file INTO storage, fetch it with `callApi()` and write it to a file column."
+  },
+  {
+    name: "downloadText",
+    signature: "downloadText(content, fileName, encoding?, mimeType?)",
+    returns: "string",
+    doc: "Hand the user a text file the script built: encodes `content` in `encoding` (`utf-8` by default; `windows-1251`, `cp866`, `koi8-u`\u2026 also work), stores it in temp storage and sets it as the action's download. Line endings are written as given (join with `'\\r\\n'` for CR LF), no BOM. Returns the signed `/api/temp-file/{token}` URL, valid for an hour (`FileStorage:TempTokenExpirationMinutes`). An action has one download: a later call replaces the earlier. In a background or scheduled run nobody receives the download, so pass the URL on in `notify()`. Max 10 MB per file, 10 files per run."
+  },
+  {
+    name: "downloadBase64",
+    signature: "downloadBase64(base64, fileName, mimeType?)",
+    returns: "string",
+    doc: "`downloadText()` for bytes: decodes `base64` and hands it to the user as `fileName` (`application/octet-stream` unless `mimeType` says otherwise). Returns the signed download URL."
   },
   {
     name: "getSetting",
@@ -35568,6 +35580,13 @@ var BUILTINS = [
     returns: "link",
     entityArg: 0,
     doc: "Build a clickable link to a record, for an `entitylink` column. Always pass a **qualified** code \u2014 `entity_cd` is only unique per module."
+  },
+  {
+    name: "printPdf",
+    signature: "printPdf(entityCd, key, templateCd)",
+    returns: "object",
+    entityArg: 0,
+    doc: "Render a print template to a PDF **as the current user** and return the stored file as `{ fileId, fileName, mimeType, size, checksum }` \u2014 a descriptor, never the bytes. `key` is the record's `{ column: value }` key (or a scalar for a single-column key); `templateCd` is the template's code on that entity. The record is read under the user's rights and the folder's row filter, as the Generate PDF button reads it. Always pass a **qualified** entity code. Not available in a scheduled job or a background action (no signed-in user), refused in a computing-only run, and limited to 10 per execution; each render holds the action's transaction open while it works."
   }
 ];
 var BUILTIN_BY_NAME = new Map(BUILTINS.map((b) => [b.name, b]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.42",
+  "version": "0.2.44",
   "description": "MCP server for dForge module authoring. Exposes 35 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
   "license": "MIT",
   "homepage": "https://github.com/iash44/dForge-core",
@@ -26,8 +26,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@dforge-core/dforge-cli": "^0.2.32",
-    "@dforge-core/metadata": "^0.0.42",
+    "@dforge-core/dforge-cli": "^0.2.35",
+    "@dforge-core/metadata": "^0.0.44",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },

package/resources/docs/dsl-reference.md

@@ -503,8 +503,8 @@ Send a notification to a specific user's inbox.
 notify([approver_id], 'New purchase request from ' + [requester_name] + ' awaiting approval')
 ```
 
-#### `sendEmail(to, subjectOrTemplateCd, bodyOrData?)`
-Two modes:
+#### `sendEmail(to, subjectOrTemplateCd, bodyOrData?, attachments?)`
+Two modes (a second argument with no spaces that contains `.` or `_` is read as a template code, so give a raw subject spaces). The optional fourth argument attaches files: a `printPdf()` result, or an array of them (a single file as itself, not `[a]`). Max 5 files and 10 MB; only the user who generated a PDF, or a workspace admin, can attach it; not in a scheduled job.
 
 ```dsl
 // Raw mode: (to, subject, body)
@@ -567,8 +567,25 @@ if (info.fileSize > 5 * 1024 * 1024) { error('Receipt larger than 5 MB') }
 if (info.mimeType != 'application/pdf') { error('Receipt must be PDF') }
 ```
 
+#### `printPdf(entityCd, key, templateCd)`
+Render a print template to a PDF as the current user and return the archived file as `{ fileId, fileName, mimeType, size, checksum }`; attach it with `sendEmail()`. Pass a qualified entity code. Not in a scheduled job or a background action; max 10 per run.
+
+```dsl
+execute:
+    var pdf = printPdf('fin.invoice', { invoice_id: [invoice_id] }, 'invoice')
+    sendEmail([customer_id].[email], 'Your invoice ' + [number], '<p>Attached.</p>', pdf)
+```
+
+#### `downloadText(content, fileName, encoding?, mimeType?)` / `downloadBase64(base64, fileName, mimeType?)`
+Hand the user a file the script built. `encoding` defaults to `utf-8`; code pages such as `windows-1251` and `cp866` work; line endings are written as given, no BOM. Both return the signed download URL, which a background or scheduled run can pass on in `notify()`. One download per action (a later call replaces the earlier); max 10 MB per file, 10 files per run.
+
+```dsl
+execute:
+    downloadText(csv, 'payments.txt', 'windows-1251')
+```
+
 #### `download(url, fileName?)`
-Set HTTP download response. Only valid in UI-triggered actions; the user's browser receives the file.
+Set HTTP download response. Only valid in UI-triggered actions; the user's browser receives the file. It fetches nothing: the URL must already serve the bytes.
 
 ```dsl
 execute:
@@ -1180,7 +1197,8 @@ The `audit` trait auto-maintains `last_updated` on INSERT/UPDATE if the column e
 | Run SQL | `query('SELECT ... WHERE c = @v', { v: value })` |
 | Get setting | `getSetting('setting_cd')` |
 | Send toast | `info('msg')`, `warn('msg')` |
-| Send email | `sendEmail(to, subj, body)` or `sendEmail(to, templateCd, dataObj)` |
+| Send email | `sendEmail(to, subj, body)` or `sendEmail(to, templateCd, dataObj)`; add a `printPdf()` result as the 4th argument to attach |
+| Give the user a built file | `downloadText(content, 'f.txt', 'windows-1251')` |
 | Send inbox notification | `notify(userId, 'msg')` |
 | Call a shared helper | `round2([amount])` from `logic/functions/*.dsl` |
 | Call another module's helper | `cdy_accounting.roleOf(...)`, imported in `deps/<module>.json` |

package/resources/schemas/entity.schema.json

@@ -108,10 +108,20 @@
 		},
 		"traits": {
 			"type": "array",
-			"description": "Entity traits expanded during module install (authoring shortcut). Trait definitions loaded from DB (seeded by metadata module).",
+			"description": "Entity traits expanded during module install (authoring shortcut): a platform trait, or one the module declares in its own traits.json. Pack and install refuse a name that is neither; the schema cannot see traits.json, so it accepts any trait-shaped name and lists only the platform traits.",
 			"items": {
-				"type": "string",
-				"enum": ["identity", "audit", "audit-full", "soft-delete", "sorting", "postable", "accumulation", "ledger", "period", "file-library"]
+				"anyOf": [
+					{
+						"type": "string",
+						"enum": ["identity", "audit", "audit-full", "soft-delete", "sorting", "postable", "accumulation", "ledger", "period", "file-library"],
+						"description": "Platform trait."
+					},
+					{
+						"type": "string",
+						"pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
+						"description": "A trait declared in the module's own traits.json."
+					}
+				]
 			},
 			"uniqueItems": true
 		},
@@ -359,6 +369,7 @@
 				"map": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "required": ["debit", "credit"], "additionalProperties": false, "properties": { "debit": { "type": "string" }, "credit": { "type": "string" } } } ] }, "description": "Register dimension or resource name -> this document's column carrying it. On an accounting (L) column a resource or dimension the register splits by side maps to { \"debit\": \"<line column>\", \"credit\": \"<line column>\" } instead of one column. Every resource the register declares must be mapped (install refuses otherwise); a dimension left out binds to a column of the same name. Only meaningful with 'register'. On an accumulation (A) column a value may be a one-hop reference path, '<reference column>.<target column>', read through the reference at posting time (off the line when the binding posts from lines), or an expression: a string starting with '=' holding an F-column formula over the same row with one-hop reference reads — \"=COALESCE([transit_warehouse_id], [dest_warehouse_id])\"." },
 				"headerMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this DOCUMENT's column carrying it, for a binding that posts from LINES. A line binding reads every other value off the line, and a dimension that belongs to the document (a dealer, an organisation, a date) cannot be put on the line: a G column is a same-row expression or an aggregate over a child set, so it cannot read a parent. Explicit rather than a fallback, because 'not on the line, try the header' turns a typo into a silent read of an unrelated header column with the same name. Install refuses: a name on neither table, a field also named in 'map', a column also read off the line by 'map', a column that is part of the line's key, a column 'lockedFields' does not freeze (the posting is keyed by it, so it has to hold still while the document is posted), and a RESOURCE unless the register is 'info' (a quantity from the document would be added once per line; an information register's records replace rather than add). A value may be a one-hop reference path off the document, whose reference key column 'lockedFields' must then freeze, or an expression over the document ('=...', see 'map')." },
 				"groupLinesBy": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true, "description": "Line columns whose distinct values each post ONE movement, instead of one per line — a production report posting 'this unit worked today' once per unit with a count of 1. 'map' is then read over a group row: the grouped line columns, every column of the document, and one-hop reads through a reference of either, so an expression may mix the document and the group key. A quoted constant is stamped once per group; a numeric line column mapped to a resource is summed over the group. Install refuses: a binding that posts from the document, an L column, a grouped column the line does not store or 'lockedLineFields' does not freeze, a line column read that is neither grouped nor a summed resource, a non-numeric summed resource, a column both grouped and summed, an ungrouped line resource on an 'info' register, a name both the line and the document carry, and a document column read that 'lockedFields' does not freeze. Accumulation (A) columns only." },
+				"lineDateField": { "type": "string", "description": "A line column dating that line's movement instead of 'dateField' — for lines that happen on days of their own under one document date (a limit card issuing through the month and dated at its end). A line that leaves it empty moves on 'dateField'. With 'periodEntity', each line's period must exist and be open, at posting and unposting and at every write to the line, judged by the date the movement is stamped with (the line's or the document's, after 'dateTrunc'). On an information register that records changes only, two lines may not write one key: post one line per key. Install refuses: a register that keeps no date, a binding that posts from the document, a column that is not a stored 'date' or 'timestamp' without time zone, one 'lockedLineFields' does not freeze, one 'groupLinesBy' omits when lines are grouped, and a binding with 'periodDimField'. Accumulation (A) columns only." },
 				"dateField": { "type": "string", "description": "This document's date column, supplying the date the register stamps on each journal row. Required once the register declares a 'journalDate' — one writer that supplied none would make every balance read as of a date quietly short, across all writers. On an accumulation (A) column it may be a one-hop reference path, '<reference column>.<target column>', or an expression over the document ('=...', see 'map')." },
 				"dateTrunc": { "type": "string", "enum": ["day", "month", "year"], "description": "Takes the date 'dateField' supplies back to the start of its day, month or year before the register stamps it — for a document that carries a time while the register's records sit on whole days. The calendar is the value's as stored; no time zone is applied. Needs 'dateField'. Accumulation (A) columns only." },
 				"skipPostingWhenEmpty": { "type": "array", "items": { "type": "string" }, "description": "THE EXCEPTION, not the normal way to model this — read the guide before declaring it. Register dimensions (by the register's names) whose empty value means THIS POSTING records nothing: the line, or the document when the binding posts from the document. One posting is skipped, never the register and never the document. When that is all the document would have recorded it is left unposted to this register, and the flag is per binding, so its other registers post as usual. An empty dimension NOT listed refuses the posting, naming the row and the dimension. It leaves a document fully posted while some of its lines produced no movement, which usually means the document is modelling two kinds of line in one table: since 'lineEntity' is declared per BINDING, prefer giving each register its own line table (goods lines post to stock, service lines do not) so that every line of each table posts. Declare this only when the distinction is not structural but lives in the data — a batch or serial number filled on some rows and not others — so there is no second table to put those rows in. Accumulation (A) columns only. Formerly skipWhenNull: a package using the old name is refused at install, while a tenant's already-stored params keep being read under it." },
@@ -381,6 +392,7 @@
 			"dependencies": {
 				"headerMap": ["lineEntity"],
 				"groupLinesBy": ["lineEntity"],
+				"lineDateField": ["lineEntity", "dateField"],
 				"dateTrunc": ["dateField"],
 				"lineEntity": ["lineField", "lockedLineFields"],
 				"lineField": ["lineEntity"],

package/resources/schemas/registers.schema.json

@@ -24,7 +24,7 @@
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
 						"debitAnalyticFields": false, "creditAnalyticFields": false,
-						"sideDimensions": false
+						"sideDimensions": false, "analyticTotals": false
 					},
 					"description": "A balance register keeps state, so it needs the entity that holds it. It dates its movements on the journal row under 'journalDate'; 'period' belongs to an information register, whose records ARE the dated thing. Its writer is recorded on the journal row, which is what 'recorder' names for an information register that has no journal."
 				}
@@ -41,7 +41,7 @@
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
 						"debitAnalyticFields": false, "creditAnalyticFields": false,
-						"sideDimensions": false,
+						"sideDimensions": false, "analyticTotals": false,
 						"allowNegative": false,
 						"autoCreate": false
 					},
@@ -60,7 +60,7 @@
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
 						"debitAnalyticFields": false, "creditAnalyticFields": false,
-						"sideDimensions": false,
+						"sideDimensions": false, "analyticTotals": false,
 						"totals": false,
 						"allowNegative": false,
 						"autoCreate": false
@@ -241,6 +241,63 @@
 					}
 				}
 			},
+			"analyticTotals": {
+				"type": "object",
+				"description": "An 'accounting' register's per-period cache keyed by the analytics as well: a cached row is keyed by (account, cached dimensions, analytic slots, period), for the accounts the chart flags. It is what makes a balance READ BY AN ANALYTIC cheap - stock by item and warehouse, settlements by counterparty and contract - which 'totals' leaves to the postings because over a whole ledger the analytics are where the rows are. getAccountBalance / getAccountTurnover read whole periods from it and the part-period at the edge from the postings. Beside 'totals', never instead of it, and in an entity of its own. Like 'totals' it caches the turnover within each period, so a backdated posting touches one row; a write to the journal that was not a posting, or a change to an account's flag, marks it stale until it is rebuilt.",
+				"required": ["entity", "period", "periodField", "accountField", "accountFlag", "analyticFields", "resources"],
+				"additionalProperties": false,
+				"properties": {
+					"entity": {
+						"type": "string",
+						"description": "Entity holding the cached rows. Keyed by ONE surrogate column the platform mints (the 'identity' trait), because a slot or a dimension may be empty and a PRIMARY KEY holds no NULL; the platform keeps a unique index over the cache's own key, NULLS NOT DISTINCT, and merges on it. It carries the account column, a column per cached dimension, the jsonb slot columns, the period column and both columns of every resource."
+					},
+					"period": {
+						"type": "string",
+						"enum": ["day", "month", "quarter", "year"],
+						"description": "How much one cached row covers, as for 'totals'."
+					},
+					"periodField": {
+						"type": "string",
+						"pattern": "^[a-z_][a-z0-9_]*$",
+						"description": "Column holding the FIRST date of the period a row covers."
+					},
+					"accountField": {
+						"type": "string",
+						"pattern": "^[a-z_][a-z0-9_]*$",
+						"description": "Column holding the account a cached row belongs to. A compound posting folds into two rows, one per side, each with that side's analytics."
+					},
+					"accountFlag": {
+						"type": "string",
+						"pattern": "^[a-z_][a-z0-9_]*$",
+						"description": "A bool column of the register's chart: the accounts where it is true are cached, and no other. Changing it on an account marks the cache stale until it is rebuilt (install, or dforge register rebuild-totals --cache analytic)."
+					},
+					"dimensions": {
+						"type": "array",
+						"items": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
+						"description": "Which of the register's dimensions the cache is grouped by; omitted, it is all of them. Unlike 'totals' a nullable one may be cached: an empty value is a key value of its own."
+					},
+					"analyticFields": {
+						"type": "array",
+						"minItems": 1,
+						"items": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
+						"description": "The cache's jsonb columns holding the analytic slots, slot N in the Nth, one per slot a posting side carries (the wider side's count on a compound register). Each holds the analytic's entity and key, which is what a read filters and groups by."
+					},
+					"resources": {
+						"type": "object",
+						"description": "Every resource the register declares, each with its 'debitField' and 'creditField' columns, as for an accounting register's 'totals'.",
+						"minProperties": 1,
+						"additionalProperties": {
+							"type": "object",
+							"required": ["debitField", "creditField"],
+							"additionalProperties": false,
+							"properties": {
+								"debitField": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
+								"creditField": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" }
+							}
+						}
+					}
+				}
+			},
 			"period": {
 				"type": "string",
 				"pattern": "^[a-z_][a-z0-9_]*$",

package/resources/schemas/reports.schema.json

@@ -401,9 +401,13 @@
 
 		"columnDef": {
 			"type": "object",
+			"description": "Override of one column the dataset already projects (from the entity, the stored procedure's result columns, or the register). Name only what differs: each key replaces the projected value. A label here is a literal and wins over a translated header.",
 			"properties": {
-				"label": { "type": "string" },
-				"visible": { "type": "boolean" },
+				"label": { "type": "string", "description": "Column header. Not translated: leave it out to keep the entity's or the procedure's translated header." },
+				"fieldTypeCd": { "type": "string", "description": "Control the value renders with, replacing the projected one." },
+				"format": { "type": "string", "description": "Display format, replacing the column's display format." },
+				"baseDatatypeCd": { "type": "string", "description": "Read only where the dataset projects no columns of its own (a stored procedure with no result columns), when columnsDef is the column list. Ignored as an override: the projected column's datatype stands." },
+				"visible": { "type": "boolean", "description": "Accepted, but neither report.run nor the client reads it: it has no effect." },
 				"width": { "type": "integer", "minimum": 1 }
 			},
 			"additionalProperties": false

package/resources/schemas/translations.schema.json

@@ -84,6 +84,23 @@
 				"$ref": "#/$defs/report"
 			}
 		},
+		"storedProcedures": {
+			"type": "object",
+			"description": "Stored-procedure code (logic/stored_procedures.json) → result-column headers. A header belongs to the procedure, not to a report: every dataset bound to the procedure shows the same translation. A dataset's columnsDef label overrides it with a literal, so leave the label out of columnsDef to keep the column translated. Required, per declared column, by `module pack` / `module validate` for each non-English supported locale; install only warns.",
+			"additionalProperties": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"columns": {
+						"type": "object",
+						"description": "Result column code → header.",
+						"additionalProperties": {
+							"$ref": "#/$defs/labelOnly"
+						}
+					}
+				}
+			}
+		},
 		"actions": {
 			"type": "object",
 			"description": "Action code (ui/actions.json) → label, tooltip and parameter labels.",
@@ -248,6 +265,10 @@
 				"label": {
 					"$ref": "#/$defs/label"
 				},
+				"desc": {
+					"type": "string",
+					"description": "Translated report description."
+				},
 				"datasets": {
 					"type": "object",
 					"description": "Dataset code → caption.",

package/skills/dforge-mcp-author/references/action-dsl.md

@@ -249,6 +249,14 @@ var note = params[note]             // no quotes around param name in this DSL
 > `null` key **throws** (a `col = NULL` predicate can never match), and array keys are rejected —
 > loop and mutate per id instead.
 
+> **Posting state.** `update()` setting a register posting state (the `A` / `L` column) posts or unposts
+> the document through the register engine, in a trigger action and in a background run alike; a refused
+> posting rolls the caller's write back. A background run holds no transaction, so such a call opens its
+> own: atomic per call, not per run. A scheduled run cannot post with `update()`.
+
+> **Keys of any type.** A field saved with `[field] = value` binds the record key by the key column's own
+> type, so a `uuid` or a digits-only `varchar` key works.
+
 > **These writes raise no events.** `insert()`, `update()`, `delete()` and `query()` are the raw
 > write layer: by design they skip folder row-filters, closed-period checks and registry state, and
 > they raise no trigger or webhook events either. Only the **acted-on record's own**
@@ -339,7 +347,16 @@ error('Insufficient stock. Available: {available}, requested: {requested}',
 | Function | Description |
 |---|---|
 | `sendEmail(to, subject, htmlBody)` | Send a raw email. `to` is an email address string. |
-| `sendEmail(to, subject, htmlBody, templateCode)` | Send a templated email (if email templates are configured). |
+| `sendEmail(to, templateCode, dataObj)` | Send a templated email. The **second** argument picks the mode: one with no spaces that contains `.` or `_` is read as a template code, so give a raw subject spaces. |
+| `sendEmail(to, subjectOrTemplate, dataOrBody, attachments)` | The optional fourth argument attaches files: a `printPdf()` result, or an array of them (`[a, b]`; pass a single file as itself, because a one-name `[a]` reads as a field reference). Only a `printPdf()` result can be attached, and only by the user who generated it or a workspace admin. At most 5 files and 10 MB per email. A file the sender may not attach fails the action. A scheduled job's email with attachments fails and rolls back. |
+
+### PDF and file output
+
+| Function | Returns | Description |
+|---|---|---|
+| `printPdf('module.entity', key, templateCd)` | `{ fileId, fileName, mimeType, size, checksum }` | Render a print template to a PDF **as the current user** (the record is read under their rights and the folder's row filter) and archive it. A descriptor, never the bytes: attach it with `sendEmail()`. Always pass a qualified entity code. Not available in a scheduled job or a background action, refused in a computing-only run, max 10 per run; each render holds the action's transaction open. |
+| `downloadText(content, fileName, encoding?, mimeType?)` | URL string | Hand the user a text file the script built. `encoding` is `utf-8` by default; `windows-1251`, `cp866`, `koi8-u` and other code pages work, and a character the encoding cannot represent is an error. Line endings are written as given (join with `'\r\n'` for CR LF), no BOM. Returns the signed download URL (valid an hour). An action has one download: a later call replaces the earlier. In a background or scheduled run nobody receives it, so pass the URL on in `notify()`. Max 10 MB per file, 10 files per run. |
+| `downloadBase64(base64, fileName, mimeType?)` | URL string | `downloadText()` for bytes; `application/octet-stream` unless `mimeType` says otherwise. |
 
 ### External API Calls
 
@@ -350,7 +367,7 @@ error('Insufficient stock. Available: {available}, requested: {requested}',
 | `getFileUrl(fileFieldValue)` | String | Generate a temporary signed download URL (relative path) for a file field. Use in email templates or notifications — not for `callApi()`. |
 | `getSecret('secret_cd')` | String | Retrieve a decrypted secret value (API keys, tokens). Secrets are managed in the admin UI. |
 | `getFileInfo(fileFieldValue)` | Object \| null | File metadata for a file field. |
-| `download(url, fileName?)` | — | Fetch a URL into tenant storage. |
+| `download(url, fileName?)` | — | Set a download URL on the action result; the browser opens it when the action returns. It fetches and stores nothing: the URL must already serve the bytes. To hand over a file the script builds, use `downloadText()` / `downloadBase64()`. |
 | `callService('name', { args })` | Any | Invoke a registered host service. |
 
 ### Files, settings, document extraction

package/skills/dforge-mcp-author/references/filters.md

@@ -311,6 +311,7 @@ The user never sees a record unless it passes **all** layers. You don't need to
 
 - **`null` filter** (or omitted) means no filtering — show everything the user has access to.
 - **Single condition** is valid without a group wrapper.
+- **An unknown operator is refused**, not dropped: a request filter (`data.get`, export, reports, a view's query, DSL `select()`) with an unknown operator, an unknown group combinator or an item that is neither condition nor group fails with `INVALID_REQUEST` naming the operator, its column and the valid set. `like` is not an operator: `mask` is SQL `LIKE`, `start` a case-insensitive prefix. A condition on a column the entity does not have is still dropped.
 - Use **short operators** (`=`, `!=`, `>`) or **enum keys** (`eq`, `notEq`, `gr`) — both work.
 - For folder `rowFilter` in module packages, prefer the short compact form: `{ "c": "...", "o": "eq", "v": ... }`.
 - Dates are ISO strings: `"2026-01-01"`.
@@ -320,6 +321,7 @@ The user never sees a record unless it passes **all** layers. You don't need to
 
 - Using the JSON filter format inside `query()` in DSL actions — **wrong**. `query()` uses raw SQL.
 - Wrapping a single condition in a group unnecessarily — **valid but noisy**. A bare condition is fine.
+- Using `"o": "like"` — **wrong**, refused. Use `"o": "mask"` with `%`.
 - Using `"operator": "equals"` — **wrong**. Use `"o": "="` or `"o": "eq"`.
 - Using `"column": "status"` — **wrong**. Use `"c": "status"`.
 - Forgetting that `null` means "no filter" (not "filter by null") — to filter for null values, use `{ "c": "field", "o": "null" }`.

package/skills/dforge-mcp-author/references/print-templates.md

@@ -8,7 +8,7 @@ Lives in: `ui/print_templates.json` + HTML/CSS files under `print_templates/`. S
 
 | Path        | Engine          | Used by                                                  |
 | ----------- | --------------- | -------------------------------------------------------- |
-| **Server**  | Scriban (Liquid) | `print.render` RPC — final print / save-as-PDF           |
+| **Server**  | Scriban (Liquid) | `print.render` RPC; `print.renderPdf` (Generate PDF, headless Chromium); `printPdf()` in a DSL action |
 | **Client**  | LiquidJS         | Editor preview — fast iteration                          |
 
 Filters are mirrored on both sides so the preview matches the print.
@@ -62,11 +62,29 @@ Every column on the entity is a top-level variable. Display formatting is pre-ap
 | `{{ _color.<column> }}` | Option color hex for single-value dropdown/radio columns                                                |
 | `{{ _settings.<cd> }}`  | Folder-resolved module setting. Image/file settings come as base64 data URIs (drop into `<img src>`).   |
 | `{{ _today }}`          | Typed `DateTimeOffset` (UTC); `{{ _fmt._today }}` is the pre-formatted string                          |
-| `{{ <set_name> }}`      | Child set — array. Iterate with `{% for x in <set_name> %}`. Only loaded if the template iterates it.   |
+| `{{ <set_name> }}`      | Child set — array, in primary-key order. Loaded wherever the template's Liquid code names it (see below) |
 | `{{ _css }}`            | The CSS string attached to the template (rarely needed in template body)                                |
 
 Inside a child-set loop, the same shape applies per row: `line._fmt.<col>`, `line._raw.<col>`, `line._color.<col>`.
 
+A loop over a document's set can read a set of the line's own entity off each line (`{% for l in lines %}{% for a in l.attributes %}`): detected by the template reading it, loaded for every line in one query under the same rights and row filter, one level deep. The editor preview does not fill it.
+
+A printed set, nested or not, needs **Select** on its entity in the folder, as `data.get` does; one the user cannot read prints empty. `print.render` and `print.renderPdf` check Select on the printed entity.
+
+A currency column prints its glyph for the common codes (`EUR` → `€`, `USD` → `$`, `GBP` → `£`, `UAH` → `₴`, `PLN` → `zł`); other codes print as the code. `format_currency` follows the same mapping.
+
+Formula columns (`F`) are read in the same SQL as the record, as `data.get` does, so a formula that navigates references or calls a SQL function prints what the grid shows, and `TODAY()` / `NOW()` work. A formula the SQL translator cannot express prints empty and the response carries a warning naming the column.
+
+**Sets: loading and order.** A set is loaded when the template's Liquid code (`{% … %}` or `{{ … }}`) mentions its name anywhere: a `for`, a filter, a condition, `.size`, `.first`. Plain text, `{% comment %}` / `{% raw %}` blocks, string literals and the member of a path (`rec.lines`) do not count, and a snippet's code is not scanned (mention the set in the host template). Rows come in primary-key order; sort in the template:
+
+```liquid
+{% assign sorted = doc_lines | sort: 'doc_date' %}            {# ascending #}
+{% assign sorted = doc_lines | sort: 'doc_date' | reverse %}  {# descending #}
+{% assign s = doc_lines | sort: 'doc_num' | sort: 'doc_date' %} {# date, then number: sort is stable, last key first #}
+```
+
+`sort` takes a column code and sorts the value as the template sees it (a dropdown or reference sorts by its label). Text order follows the engine, not the database collation. `{# … #}` after an expression in examples is a note for the reader, not syntax: write a real comment as `{% comment %} … {% endcomment %}`.
+
 ## Custom filters
 
 | Filter                                          | Example                                                | Output                       |
@@ -91,6 +109,21 @@ Declare a snippet with `"type": "snippet"`. No `entityCd`. The `template_cd` mus
 
 Full mechanics + an EPC SEPA QR worked example: [`docs/ui/print-qr-codes.md`](../../../docs/ui/print-qr-codes.md).
 
+### Amount in words
+
+The platform has no number-to-words filter. The `common-words` module (`modules/common-words`, a dependency to declare) ships snippets that write an amount or a plain quantity out in Ukrainian, English or German. Set the inputs, then include:
+
+```liquid
+{% assign words_amount = total %}
+{% assign words_currency = currency_cd %}
+{% assign words_lang = 'de' %}
+{% include 'common-words.money' %}
+```
+
+1234.56 EUR prints «eintausendzweihundertvierunddreißig Euro 56 Cent». `words_amount` must be a numeric field, not text. `words_currency` is an ISO 4217 code in any case; an unlisted currency prints its code. `words_lang` is `uk` (default), `en` or `de`; an unknown code prints `[common-words: unknown language xx]`. `words_cap = true` capitalises the first letter. `common-words.money` only picks the language; `money_uk` / `money_en` / `money_de` can be included directly, and `common-words.quantity` writes a count of things («двадцять одна штука», «twenty-one pieces»): `words_number` (numeric, a fraction rounds half up), optional `words_unit` (forms joined by `|`: three for Ukrainian, two for English and German) and `words_gender` (`m` / `f` / `n`), plus `words_lang` and `words_cap` as above. The text lives in the module, so a fix or a new currency is a module update; a new language is a new `money_xx.html` plus a line in `money.html`.
+
+Snippets run on Scriban (print) and LiquidJS (preview), so write them for both: no `floor` on big numbers, no number taken from `split` / `slice`, plain `{% comment %}` without trim dashes.
+
 ## Module package layout
 
 ```
@@ -142,10 +175,13 @@ my_module/
 - **Using `_fmt` in a predicate.** `{% if _fmt.amount_paid > 0 %}` compares strings. Use the bare reference: `{% if amount_paid > 0 %}`.
 - **Forgetting `_raw` for codes.** Direct `{{ status }}` is the label (`"Partially Paid"`). For CSS classes / wire-format payloads / predicates against codes, use `{{ _raw.status }}` (`"P"`).
 - **Manually formatting dates/currency.** Don't reach for `format_currency` when the column is already `fieldTypeCd: "currency"` — `_fmt.<col>` already matches the form. Use the filter only for derived values.
-- **Referencing a child set outside a `{% for %}`.** The platform only loads sets that appear in a `for` loop. `{{ lines.size }}` won't trigger the load.
+- **Expecting a set to load only from a `for`.** It loads wherever the template names it (`sort`, `.size`, `.first`). A set read only inside a snippet is not seen: mention it in the host template.
+- **Testing emptiness with `blank` / `empty`.** LiquidJS (preview) knows them, Scriban (print) does not, so the comparison is always false on the server for an unset field. Use `{% unless x %}`, `{% if x and x != '' %}` or `x != nil`.
+- **Dashed comment tags.** The server cuts every `{%- comment -%}` block before parsing, but keep snippets to plain `{% comment %}` so both engines agree.
 - **Snippet `template_cd` with a dot.** `{% include 'my_module.foo.bar' %}` — the resolver splits on the last dot only, so `my_module.foo` becomes the module name and breaks. No dots in snippet codes.
 - **Dropping CSS in `<style>` blocks inline.** The renderer wires `<style>` for you; declare CSS in the separate `.css` file (or inline string via the `css` field).
-- **Trying to use `TODAY()` / `NOW()` in a formula column expecting it to render in print.** The print-time formula evaluator skips those. Pre-compute via a formula column at insert time, or use `{{ _today | format_date: '...' }}` directly in Liquid.
+- **Printing an unsorted set.** Rows come in primary-key order; use `| sort: 'col'` (and `| reverse`) in the template.
+- **Writing an amount in words by hand.** Include `common-words.money` instead of a custom filter or lookup table.
 - **Module-installed template renamed in editor.** The editor preserves the original `template_cd` so `{% include %}` references stay intact — don't try to work around it.
 
 Module-installed print-template rows can't be deleted from the editor — uninstall the owning module to remove them.
@@ -155,5 +191,6 @@ Module-installed print-template rows can't be deleted from the editor — uninst
 - Full developer guide: [`docs/ui/print-templates.md`](../../../docs/ui/print-templates.md)
 - QR codes + snippets guide: [`docs/ui/print-qr-codes.md`](../../../docs/ui/print-qr-codes.md)
 - JSON Schema: [`docs/schemas/print_templates.schema.json`](../../../docs/schemas/print_templates.schema.json)
+- Amount in words: [`modules/common-words/`](../../../modules/common-words/) (README lists the inputs)
 - Reference modules: [`modules/fin/`](../../../modules/fin/), [`modules/fin-ch/`](../../../modules/fin-ch/) (Swiss QR-bill), [`modules/crm/`](../../../modules/crm/), [`modules/wms/`](../../../modules/wms/), [`modules/hr/`](../../../modules/hr/)
 - Source: `server/src/dForge.Api/Services/PrintTemplateService.cs`, `server/src/dForge.Admin/Services/ModuleInstall/PrintTemplateRegistrar.cs`

package/skills/dforge-mcp-author/references/registers.md

@@ -183,6 +183,7 @@ A register column is a `bool` state column. `A` writes `balance`, `turnover` and
 | `lineEntity` + `lineField` | Post from lines: one movement per line. Declared per binding. Needs `lockedLineFields`. |
 | `headerMap` | On a line posting, register name to a **document** column. A resource may come from the document only on an `info` register. Every column must be in `lockedFields`. |
 | `groupLinesBy` | One movement per distinct value of these line columns. `map` is read over a group row; numeric resources are summed. |
+| `lineDateField` | On a line posting, a line column dating that line's movement instead of `dateField`; an empty one falls back to `dateField`. With `periodEntity` each line's period must be open, judged by the movement's stamped date (line's or document's, after `dateTrunc`); lines skipped by `skipPostingWhenEmpty` don't count. On a `recordChangesOnly` info register, one line per key (several dates on a key are refused). A `date` or zoneless `timestamp`, in `lockedLineFields` (and `groupLinesBy` when grouped), not with `periodDimField`. |
 | `skipPostingWhenEmpty` | Dimensions whose emptiness means "this row posts nothing". The exception, see below. |
 | `lockedFields` / `lockedLineFields` | Columns frozen while posted. `["*"]` freezes the whole row. |
 | `movementMapping` | Journal attribute column to document or line column. |
@@ -199,7 +200,7 @@ A register column is a `bool` state column. `A` writes `balance`, `turnover` and
 
 The per-side object shape was missing from the entity schema until metadata 0.0.39. Validate with metadata 0.0.39 or later.
 
-Paths, expressions, `dateTrunc`, `headerMap`, `groupLinesBy` and `skipPostingWhenEmpty` are `A`-only. An `L` column refuses them.
+Paths, expressions, `dateTrunc`, `headerMap`, `groupLinesBy`, `lineDateField` and `skipPostingWhenEmpty` are `A`-only. An `L` column refuses them.
 
 ### `L` column (`acc-registry.gl_corr`)
 
@@ -262,6 +263,8 @@ execute:
 
 `totals` caches the turnover inside each `day`/`month`/`quarter`/`year`, never a closing balance, so a backdated posting touches one row. Declare an `entity` whose PRIMARY KEY is exactly (dimensions, `periodField`), with `inField`/`outField` per resource (`debitField`/`creditField` and an `accountField` on accounting). Posting maintains it; install rebuilds it when its shape changes. Not available on `info`. Details: registers.md section 8.4.
 
+An `accounting` register may also declare `analyticTotals`, a second cache keyed by the analytic slots as well: (account, cached dimensions, analytic slots, period). It covers the accounts whose chart flag `accountFlag` is true, lives in an entity of its own beside `totals` (a surrogate key, since a slot or dimension may be empty), and holds `analyticFields` (one jsonb column per slot), `accountField`, `periodField`, `period`, optional `dimensions` and `debitField`/`creditField` per resource. `getAccountBalance` / `getAccountTurnover` read it for a flagged account when every filter and grouping is a cached dimension or an analytic of the account, and take the rest from the postings. A write to the journal around posting, or a changed account flag, marks it stale until `dforge register rebuild-totals --cache analytic` (or a module install) rebuilds it. Not available on `balance`, `turnover` or `info`.
+
 ## Common mistakes
 
 - **Undeclared or unqualified register.** `params.register` must be `module_cd.register_cd` and exist. Install fails, not the first posting.

package/skills/dforge-mcp-author/references/reports.md

@@ -78,7 +78,7 @@ A report has a `label`, a `description`, a `datasets` map, a `layout` object (`{
 - `query.columns` — column codes; supports dot navigation (`customer.name`).
 - `query.filter` — canonical filter (`{c,o,v}` or `{g,i:[...]}`); use `@param_code` to reference a parameter.
 - `query.sort` — `[{ c, d }]` where `d` ∈ `asc | desc`.
-- `columnsDef` — optional per-column display overrides (`{ label, visible, width }`).
+- `columnsDef` — optional per-column display overrides (`{ label, fieldTypeCd, format, width }`; each key replaces the projected value). `label` is a literal and wins over a translated header. `visible` is accepted but read by nothing. `baseDatatypeCd` is read only where the dataset projects no columns of its own.
 
 ### Stored procedure dataset (developer path)
 
@@ -110,6 +110,9 @@ Key differences from entity datasets:
   **override** — `report.run` projects `dForge.sp_column`, and `columnsDef` only restyles it.
   A function returning an unnamed `SETOF <composite>` or a bare scalar declares no column
   names, so that one needs an explicit `columns` block in `logic/stored_procedures.json`.
+  Leave `label` out of `columnsDef` to keep the column's translated header: result-column headers
+  translate under the procedure, `storedProcedures.<sp_cd>.columns.<column_cd>.label`
+  (see `references/translations.md`), and every dataset bound to the procedure shows it.
 - Params work exactly as they do for an entity dataset, and `datasetType` makes no difference: declare them at report level (`parameters`) or on the dataset (`params`). Report level wins on a code collision.
 - **The parameter code must match the procedure's declared `paramCd` exactly.** `report.run`
   resolves each argument by that code alone — no prefix is added or stripped — so a report

package/skills/dforge-mcp-author/references/translations.md

@@ -83,7 +83,8 @@ Translation files mirror the module's content structure. Each translatable objec
 | `views` | Data view labels and descriptions (`label`, `desc`) | View codes (keys from `ui/data_views.json`) → `{ label, desc }` |
 | `menus` | Menu node labels (root + nested items) | Menu root key → `{ label, items: { item_code: { label } } }` matching `ui/menus.json` structure |
 | `actions` | Action labels, descriptions, param labels **and param dropdown option labels** | Action codes (keys from `ui/actions.json`) → `{ label, desc, params: { param_cd: { label, options: { value: … } } } }` |
-| `reports` | Report dataset captions, param labels **and param dropdown option labels** | Report codes → `{ datasets: { ds_cd: { caption } }, params: { param_cd: { label, options: { value: … } } } }` |
+| `reports` | Report `label`, `desc`, dataset captions, param labels **and param dropdown option labels** | Report codes → `{ datasets: { ds_cd: { caption } }, params: { param_cd: { label, options: { value: … } } } }` |
+| `storedProcedures` | Result-column headers of a stored procedure (`logic/stored_procedures.json`), shared by every report bound to it | Procedure codes → `{ columns: { column_cd: { label } } }` |
 | `entities.<e>.constraints` | Check/unique constraint violation messages (opt-in — warned, not enforced) | Constraint codes → `{ message }` under the owning entity |
 | `messages` | DSL `info` / `warn` / `error` / `exit` texts (opt-in — warned, not enforced) | Exact English text → translated text |
 | `entities.<e>.fields.<f>.options` | Dropdown/radio/flags **option labels** (opt-in) | Option `value` → localized label (string) or `{ label, icon, color }` |
@@ -269,6 +270,10 @@ Non-English locales are declared in `supportedLocales` (an array of `ll-CC` tags
 
 Every listed locale MUST have a matching `translations/<locale>.json` with a label for each translatable resource, or install fails completeness validation.
 
+### Stored-procedure column headers
+
+A result column's header belongs to the procedure, not to a report. `module pack` / `module validate` require one `storedProcedures.<sp_cd>.columns.<column_cd>.label` per declared column for each non-English supported locale; install only warns (also when a translation names a column the module lacks). A dataset's `columnsDef` label is a literal and overrides it, so leave the label out to keep the column translated.
+
 ## Rules
 
 1. **Always provide `en-US`** as the base language. Other languages fall back to it for missing keys.