@dforge-core/dforge-mcp 0.2.43 → 0.2.44

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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

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.33/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.43/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.43/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.43",
+  "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.33",
-    "@dforge-core/metadata": "^0.0.43",
+    "@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
 		},

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.
@@ -67,6 +67,12 @@ Every column on the entity is a top-level variable. Display formatting is pre-ap
 
 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:
@@ -170,6 +176,8 @@ my_module/
 - **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.
 - **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).
 - **Printing an unsorted set.** Rows come in primary-key order; use `| sort: 'col'` (and `| reverse`) in the template.

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.