@dforge-core/dforge-mcp 0.2.43 → 0.2.45

package/resources/docs/dsl-reference.md

@@ -145,6 +145,7 @@ A param declared with a text field type (`text`, `textarea`, ...) stays a string
 
 - `[fieldName]` — read or write a field on the current record
 - `[refField].[targetField]` — navigate via a Reference (FK) column to a field on the linked entity. `[refField].targetField` (bare target) is accepted as an equivalent spelling. **Single-hop only** — `[a].[b].[c]` is a compile error; use `getRecord()` / `select()` to reach past one reference
+- `[userField].[email]` — a column of `fieldTypeCd: "user"` (an `owner_id`, an approver) is not a Reference column but navigates the same way, to the platform user: `[owner_id].[email]`, `[owner_id].[full_name]`. This is the only way to read a user's name or e-mail — `getRecord()`, `select()` and `query()` cannot reach the user table. Needs a platform with #1499 (v1.28.8+)
 - `old[fieldName]` — the field's value *before* the change, in an action invoked by an event trigger. Read-only; reads `null` on `insert` events and outside triggers
 
 ```dsl
@@ -503,8 +504,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()`, `attachText()` or `attachBase64()` 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 `printPdf()` file, or a workspace admin, can attach it, and a scheduled job cannot; a file built with `attachText()` / `attachBase64()` has no owner and works in a scheduled job too.
 
 ```dsl
 // Raw mode: (to, subject, body)
@@ -567,8 +568,34 @@ 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 (shared with `attachText()` / `attachBase64()`).
+
+```dsl
+execute:
+    downloadText(csv, 'payments.txt', 'windows-1251')
+```
+
+#### `attachText(content, fileName, encoding?, mimeType?)` / `attachBase64(base64, fileName, mimeType?)`
+Build a file to attach to an email: pass the result as `sendEmail()`'s fourth argument. Encodings as `downloadText()`; the file keeps its `mimeType` (`text/plain` for `attachText()` by default, `application/octet-stream` for `attachBase64()`). Returns a descriptor, not a URL, and only the emails of the same run can name it. Works in a scheduled job. Max 10 MB per file; the 10-files-per-run limit is shared with the download functions.
+
+```dsl
+execute:
+    sendEmail([candidate_email], 'Interview for ' + [job_title], '<p>See you.</p>',
+        attachText(ics, 'invite.ics', 'utf-8', 'text/calendar'))
+```
+
 #### `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:
@@ -722,8 +749,8 @@ The first argument names a **register** (`module_cd.register_cd`, as declared in
 | `getBalance('module.register', dims?, asOf?)` | Object, per resource | Balance of an accumulation register. A dimension left out of `dims` is summed over. |
 | `getTurnover('module.register', dims, from, to)` | Object, `{in, out, net}` per resource | Movement over an interval. `dims` may be `null`; `from` and `to` are required. |
 | `getSlice('module.register', dims, onDate?, mode?)` | Object or `null` | One record of an information register, the latest on or before `onDate`, plus `_period`. No dimension may be omitted. |
-| `getAccountBalance('module.register', account, filter?, asOf?)` | Object, `{debit, credit, net}` per resource | Balance of one account of an accounting register. |
-| `getAccountTurnover('module.register', account, filter, from, to)` | Object, `{debit, credit, net}` per resource | Movement of one account over an interval. |
+| `getAccountBalance('module.register', account, filter?, asOf?, options?)` | Object, `{debit, credit, net}` per resource; an array of rows with `groupBy` | Balance of one account of an accounting register. `options`: `groupBy` (a name or array — a row per combination, zero balances left out), `exclude: { entity: 'module.document', key }` (one, or an array of them; not that document's postings), `before` (a moment, exclusive, in place of `asOf`). |
+| `getAccountTurnover('module.register', account, filter, from, to, options?)` | Object, `{debit, credit, net}` per resource; an array of rows with `groupBy` | Movement of one account over an interval. `options` takes `groupBy` and `exclude`. |
 | `getCorrespondence('module.register', debitAccount, creditAccount, filter, from, to)` | Object, per resource | Movement between two accounts. Needs `lineMode: "compound"`; refuses an analytic filter. |
 
 An analytic filter is the key alone (`{ cost_center: 42 }`) or `{ entity, value }` to name one entity of a union kind.
@@ -1180,7 +1207,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()`, `attachText()` or `attachBase64()` 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
 		},
@@ -418,7 +428,7 @@
 				"fieldTypeCd": {
 					"type": "string",
 					"enum": [
-						"text", "avatar", "email", "phone", "url", "textarea", "number", "currency", "percent",
+						"text", "avatar", "email", "phone", "url", "textarea", "number", "currency", "percent", "filesize",
 						"checkbox", "date", "datetime", "time",
 						"dropdown", "flags", "tags", "json", "hidden", "color", "image", "file",
 						"markdown", "richtext", "lookup", "user", "grid", "list", "entitylink", "code"

package/resources/schemas/registers.schema.json

@@ -24,7 +24,7 @@
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
 						"debitAnalyticFields": false, "creditAnalyticFields": false,
-						"sideDimensions": false, "analyticTotals": false
+						"sideDimensions": false, "analyticTotals": false, "importedKeyField": 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, "analyticTotals": false,
+						"sideDimensions": false, "analyticTotals": false, "importedKeyField": false,
 						"allowNegative": false,
 						"autoCreate": false
 					},
@@ -60,7 +60,7 @@
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
 						"debitAnalyticFields": false, "creditAnalyticFields": false,
-						"sideDimensions": false, "analyticTotals": false,
+						"sideDimensions": false, "analyticTotals": false, "importedKeyField": false,
 						"totals": false,
 						"allowNegative": false,
 						"autoCreate": false
@@ -375,6 +375,11 @@
 				"items": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
 				"description": "Analytic slot columns for the CREDITED account, in slot order and capped independently of the debit side. Only valid on a compound register."
 			},
+			"importedKeyField": {
+				"type": "string",
+				"pattern": "^[a-z_][a-z0-9_]*$",
+				"description": "Accounting only. The posting column holding the document's key on a posting LOADED beside a document posted in another system — one with no 'source' stamp. getAccountBalance / getAccountTurnover 'exclude' then leaves such postings out by that key as well as the stamped ones. Matches documents with a one-column key."
+			},
 			"sideDimensions": {
 				"type": "object",
 				"minProperties": 1,

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/SKILL.md

@@ -147,12 +147,13 @@ Load these by URI, one per step, at the step that needs them.
 `data-views`, `menus`, `action-dsl`, `filters`, `security`, `reports`,
 `settings`, `jobs`, `number-sequences`, `registers`, `reactions`, `document-extraction`,
 `print-templates`, `translations`, `queries`, `schema-import`, `excel-import`,
-`data-migration`, `manifest`, `validation-checklist`, `conventions`.
+`data-migration`, `manifest`, `conventions`, `validation-checklist`.
 
 **Schemas** (fallback, when a reference points at one) — `dforge://schema/<name>`:
 `manifest`, `entity`, `domains`, `data-views`, `folders`, `menus`, `roles`,
 `jobs`, `seed-data`, `traits`, `webhooks`, `triggers`, `print-templates`,
-`settings`, `reports`.
+`settings`, `reports`, `deps`, `registers`, `translations`, `diagram`,
+`stored-procedures`, `card-layouts`, `demo-vars`.
 
 **Docs**: `dforge://docs/dsl` (full DSL grammar + built-ins),
 `dforge://docs/conventions` (cross-module extension work — §1b only).

package/skills/dforge-mcp-author/examples/column-security/entities/product.json

@@ -1,5 +1,5 @@
 {
-	"description": "Products, with stock and pricing on one record",
+	"description": "Product",
 	"dbObject": "product",
 	"toString": "{name}",
 	"traits": ["identity", "audit"],

package/skills/dforge-mcp-author/examples/column-security/manifest.json

@@ -14,7 +14,6 @@
 	"dependencies": {
 		"admin": ">=0.0.1"
 	},
-	"supportedLocales": ["en-US"],
 	"created": "2026-08-19",
 	"updated": "2026-08-19",
 	"entities": {

package/skills/dforge-mcp-author/examples/column-security/security/roles.json

@@ -1,13 +1,13 @@
 {
 	"column_security.storekeeper": {
-		"description": "Counts stock; never sees cost or price",
+		"description": "Storekeeper",
 		"rights": {
 			"product": "SIU",
 			"folder:warehouse": "E"
 		}
 	},
 	"column_security.accountant": {
-		"description": "Owns costing and pricing",
+		"description": "Accountant",
 		"rights": {
 			"product": "SIU",
 			"folder:finance": "E"

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

@@ -238,9 +238,12 @@ var note = params[note]             // no quotes around param name in this DSL
 | `preloadRef('fk_column')` | Row object | Load the referenced record for a FK column. Access its fields with `ref.get('field')`. |
 
 > **Entity codes: always qualify.** Every data built-in (`select`, `insert`, `update`, `delete`,
-> `getRecord`, `nextNumber`) accepts a qualified `module.entity` code — write `update('comm.message', …)`,
-> not `update('message', …)`, even inside the owning module. It reads unambiguously and keeps the
-> script correct if it's ever moved to a bridge module.
+> `getRecord`, `nextNumber`) takes `module.entity` — write `update('comm.message', …)`, not
+> `update('message', …)`, even inside the owning module. It reads unambiguously and keeps the script
+> correct if it's ever moved to a bridge module. The part before the dot is looked up first as a module
+> code, hyphen included (`insert('cdy-tax.invoice', …)`), and otherwise taken as a schema
+> (`insert('cdy_tax.invoice', …)`); both work, also for a hyphenated module with no `schemaName`
+> (platform #1543). Prefer the module code, as a `ref` param writes it.
 
 > **Keys: scalar or object.** In `update()` / `delete()` / `getRecord()` / `getRecordOrNull()`,
 > `key` is either a scalar PK value (`update('task', 42, {…})` — single-column PK only) or an
@@ -249,6 +252,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**
@@ -311,12 +322,14 @@ The first argument names a **register** (`module_cd.register_cd`, as declared in
 | `getBalance('module.register', dims?, asOf?)` | Object, per resource | Balance of an accumulation register. A dimension left out of `dims` is summed over. |
 | `getTurnover('module.register', dims, from, to)` | Object, `{in, out, net}` per resource | Movement over an interval. `dims` may be `null`; `from` and `to` are required. |
 | `getSlice('module.register', dims, onDate?, mode?)` | Object or `null` | One record of an information register, the latest on or before `onDate`, plus `_period`. No dimension may be omitted. |
-| `getAccountBalance('module.register', account, filter?, asOf?)` | Object, `{debit, credit, net}` per resource | Balance of one account of an accounting register. |
-| `getAccountTurnover('module.register', account, filter, from, to)` | Object, `{debit, credit, net}` per resource | Movement of one account over an interval. |
+| `getAccountBalance('module.register', account, filter?, asOf?, options?)` | Object, `{debit, credit, net}` per resource; an array of rows with `groupBy` | Balance of one account of an accounting register. `options`: `groupBy` (a name or array — a row per combination, zero balances left out), `exclude: { entity: 'module.document', key }` (not that document's postings), `before` (a moment, exclusive, in place of `asOf`). |
+| `getAccountTurnover('module.register', account, filter, from, to, options?)` | Object, `{debit, credit, net}` per resource; an array of rows with `groupBy` | Movement of one account over an interval. `options` takes `groupBy` and `exclude`. |
 | `getCorrespondence('module.register', debitAccount, creditAccount, filter, from, to)` | Object, per resource | Movement between two accounts. Needs `lineMode: "compound"`; refuses an analytic filter. |
 
 An analytic filter is the key alone (`{ cost_center: 42 }`) or `{ entity, value }` to name one entity of a union kind.
 
+`getAccountBalance` / `getAccountTurnover` take `exclude` as one `{ entity, key }` or an array of them, of any entities. A register that declares `importedKeyField` (see the registers reference) also leaves out postings *loaded* beside a document, matched by that document's key.
+
 ### Messaging
 
 | Function | Description |
@@ -339,7 +352,18 @@ 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()`, `attachText()` or `attachBase64()` result, or an array of them (`[a, b]`; pass a single file as itself, because a one-name `[a]` reads as a field reference). A `printPdf()` file can be attached only by the user who generated it or a workspace admin, and a scheduled job's email carrying one fails and rolls back; a file built with `attachText()` / `attachBase64()` has no owner and works in a scheduled job too. At most 5 files and 10 MB per email. A file the sender may not attach fails the action. |
+
+### 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. |
+| `attachText(content, fileName, encoding?, mimeType?)` | descriptor | Build a text file for `sendEmail()`'s fourth argument, keeping its `mimeType` (e.g. an `.ics` as `text/calendar`). Same encodings as `downloadText()`; max 10 MB per file, 10 files per run shared with the download functions. Works in a scheduled job. |
+| `attachBase64(base64, fileName, mimeType?)` | descriptor | `attachText()` for bytes. |
+| `downloadBase64(base64, fileName, mimeType?)` | URL string | `downloadText()` for bytes; `application/octet-stream` unless `mimeType` says otherwise. |
 
 ### External API Calls
 
@@ -350,7 +374,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
@@ -683,6 +707,8 @@ In `batch` mode, access individual records with `__records.get(i)`, the count wi
 
 ## Async actions
 
+An inline run stops after **10 seconds** (`Dsl:Limits:ScriptTimeoutSeconds`) with "The operation has timed out.", rolling its transaction back. Work that imports or posts many documents belongs in a background run; a caller that needs the outcome waits for the records' state (a posting flag) rather than for the call.
+
 For long-running actions, set `"isAsync": true` in `ui/actions.json`. That **permits** background execution: the call is queued as a `background_action` row and picked up by `BackgroundActionService` (a hosted `BackgroundService` polling every ~10s — there is no Hangfire in dForge), and the user gets a completion notification via SSE. The DSL syntax is the same.
 
 `isAsync` does not force it. `action.execute` carries its own `async` argument and the server branches on that, so a parameterless action is queued directly while one with parameters is offered to the user as both "Run" (inline) and "Run in Background". Note that a queued run has **no wrapping transaction** — see *Atomicity* below.
@@ -729,6 +755,8 @@ In `ui/actions.json`:
 | `isTransacted` | Recommended | `true` = the whole run is **one transaction**: the first failure aborts it *and* rolls back everything already written. `false` = no transaction, and what happens next depends on the mode — `single`/`each` report the failure and carry on with the next record, keeping what succeeded; a `batch` script is one invocation, so a failure just ends the run there with its earlier writes committed and its `[field]` assignments never flushed. **Defaults to `true`** when omitted — see *Atomicity* below |
 | `orderNum` | Recommended | Display order in the action menu |
 | `isAsync` | Optional | `true` **permits** background execution — it does not force it. A parameterless action is queued directly; one with params is offered to the user as both "Run" and "Run in Background". Queued runs get a completion notification |
+| `previewTemplate` | Optional | Code of a print template of the action's entity (`ui/print_templates.json`). The run dialog opened on one record renders it as a PDF beside the params, so the user reads what the action sends before running it. Each preview renders and archives a PDF |
+| `paramSets` | Optional | Saved parameter sets the module ships, keyed by set name: `{ "default": { "description": "…", "values": { "subject": "…" } } }`. Read-only for users and refreshed on every install; a `values` key the action does not declare fails the install. A set named `default` is applied when the dialog opens. A value starting with `=` is a formula over the record (`=[customer].[email]`) and one containing `{{ }}` is a print-style template, both evaluated when the dialog opens on one record. A user's own set of the same name overrides it for that user, and a set an admin saved under a shipped name is left alone with a warning |
 
 **Definitions are cached.** The server reads an action's definition through a per-tenant cache (5 minutes), cleared on module install, uninstall and Studio publish. A CLI install is noticed only through a connected browser, so without one a changed action can run stale for up to 5 minutes.
 
@@ -792,7 +820,7 @@ be either.
 > and `ON COMMIT DROP` on any temp table. Only `query()` can do any of this — the
 > structured built-ins emit plain DML — and nothing checks it statically.
 
-1. **Bare table names are qualified automatically** with the current module's schema after `FROM` / `JOIN` / `USING`, and as the target of `INSERT INTO`, `MERGE INTO` and `UPDATE`. A name already qualified (`wms.stock_movement`) is left as written, so qualify only another module's table. Left alone: words that name no table (`IS DISTINCT FROM`, `EXTRACT(year FROM d)`, `FOR UPDATE`, `DO UPDATE SET`, `SELECT ... INTO var`), built-in set functions (`generate_series`, `unnest`), literals and comments. A CTE name is a source only inside the query that declares its `WITH` (and in its own body only under `RECURSIVE`); a write target is always the real table, so `WITH t AS (...) UPDATE t ...` updates the module's `t`. `;`-separated statements are each qualified. (Module codes with a hyphen, e.g. `crm-fin`, cannot be schema-qualified by hand in raw SQL; use the structured built-ins, which accept `module.entity`.)
+1. **Bare table names are qualified automatically** with the current module's schema after `FROM` / `JOIN` / `USING`, and as the target of `INSERT INTO`, `MERGE INTO` and `UPDATE`. A name already qualified (`wms.stock_movement`) is left as written, so qualify only another module's table. Left alone: words that name no table (`IS DISTINCT FROM`, `EXTRACT(year FROM d)`, `FOR UPDATE`, `DO UPDATE SET`, `SELECT ... INTO var`), built-in set functions (`generate_series`, `unnest`), literals and comments. A CTE name is a source only inside the query that declares its `WITH` (and in its own body only under `RECURSIVE`); a write target is always the real table, so `WITH t AS (...) UPDATE t ...` updates the module's `t`. `;`-separated statements are each qualified. (A module whose code has a hyphen and that declares no `schemaName` lives in a hyphenated schema, which raw SQL cannot name as written — the structured built-ins reach it by module code; give such a module a `schemaName` with underscores if its tables are queried in SQL.)
 2. **Use `@param` placeholders** for values — NEVER concatenate user input into SQL strings. The engine auto-parameterizes.
 3. **SELECT, INSERT, UPDATE, DELETE all work** via `query()`. For reads, it returns row arrays. For writes, it executes the statement.
 4. **`insert()` is preferred over `query('INSERT ...')`**, `update()`/`delete()` over `query('UPDATE/DELETE ...')`, and `select()` over `query('SELECT ...')` for module entities — raw SQL skips auto-fill (PKs, audit, number sequences) and metadata validation.
@@ -808,6 +836,8 @@ be either.
 - Passing an **array of ids** as the `key` of `update()`/`delete()` — **rejected**. Loop over the ids and mutate one at a time.
 - Selecting or string-filtering a plain reference (`R`) column in `select()` — **throws**. Use the FK column or a nav path (`'customer.company_name'`).
 - Unqualified entity codes (`update('message', …)`) — works inside the owning module but **always prefer the qualified form** (`update('comm.message', …)`).
+- An assignment inside a one-line block, `if (x) { [field] = y }` -- fails at run time with "not a valid reference". Put `[field] = y` on a line of its own.
+- Indexing straight after a call or an index, `query(sql)[0]` or `rows[0][name]` -- read as a field reference `[0]` / `[name]` before platform #1537 (2026-10-24). On an older platform, assign the result to a variable first. `rows [name]`, with a space, is still a field read.
 - Forgetting `var` in loops — `for (i = 0; ...)` creates a global. Always `for (var i = 0; ...)`.
 - Using ES6 syntax (`const`, `let`, `=>`, template literals) — **may not work**. Jint supports ES5.1 primarily. Stick to `var`, `function`, string concatenation with `+`.
 - Calling `TODAY()` or `NOW()` (uppercase) inside `execute:` — **wrong**, they're undefined there and install fails with `'TODAY' is not defined`. Use lowercase **`now()`** in `execute:`; `TODAY()`/`NOW()` are formula-only (`canExecute:`, formula columns).

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

@@ -114,6 +114,10 @@ Use explicit **numeric** PKs in seed data so cross-file references work. The `id
 
 **Common mistake**: using UUID strings like `"10000000-0000-0000-0000-000000000001"` — **wrong**. The `cuid` datatype is a numeric `int8`, not a UUID string. Seed data PKs must be numbers. Use a numbering scheme that avoids collisions (e.g. 1001-1099 for countries, 2001-2099 for regions, etc.).
 
+**Seed data is re-applied on every install.** Reinstalling writes the seed rows back over rows a user changed and brings back rows a user deleted. Seed only reference data the module owns outright; a table users or a migration fill must not be seeded, or each install undoes their work.
+
+**Seed data and settings ship in the package.** Both go into the `.dforge` file and the marketplace listing. Put only fictional or public reference data there — never a real company name, tax id, address or brand.
+
 ## Demo data
 
 Sample records live in `demo-data/`, not `seed-data/`. `seed-data/` holds reference tables every install needs; `demo-data/` is loaded only on request, so a workspace for real work does not start full of fake customers and invoices.
@@ -129,6 +133,8 @@ Sample records live in `demo-data/`, not `seed-data/`. `seed-data/` holds refere
 
 Depth: the platform changelog entry "Demo data: its own folder, formulas, and a checkbox at install".
 
+**`demo-data/` inserts rows; it does not post them.** For an accounting or stock module the demo must show posted documents — balances, postings, a closed month — so a demo built only from files shows documents and empty registers. Load such a demo through the API instead: insert the documents, then run the module's own actions (post, import, close) on them, waiting for a background action by its record's state flag. Make it idempotent (fixed `DEMO-` codes, skip what exists) so it can run again.
+
 ## Translations
 
 Translation files live in `translations/` and are named after the **IETF locale tag** (`de-DE.json`, `uk-UA.json`, etc.). Filenames are auto-discovered; declare which ones you ship in `manifest.supportedLocales`. English is the default — labels and descriptions live in entity/view JSON, so **don't** create `en.json` or `en-US.json` (they're skipped by the installer).
@@ -163,7 +169,7 @@ Both use **semver** (`MAJOR.MINOR.PATCH`).
 - If you changed translations only → bump `version` only.
 - The installer uses `dbSchemaVersion` to decide whether to apply schema changes. Wrong version = skipped DDL.
 - Data a new version reshapes (backfill, move rows, drop a table it no longer declares) goes in `migrations/<version>.sql`, named by `version`, run once on an upgrade from below it. See `manifest.md` § Upgrade migrations.
-- **Never ship a package without bumping at least `version`** from the previous release. The installer may reject or silently skip a re-install with the same version.
+- **Never ship a package without bumping at least `version`** from the previous release. A re-install of the same version is **skipped and reported as a success** (`isEmpty: true`; only the server log says so), so a smoke test then runs against the old code. Bump the version, or pass `--force` while developing.
 - For brand-new modules, start at `version: "0.1.0"` and `dbSchemaVersion: "0.0.1"`.
 
 ## `orderNum` — always set it

package/skills/dforge-mcp-author/references/field-types.md

@@ -52,7 +52,7 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
 |---|---|---|---|---|
 | `date` | `date` | Calendar date only. | `date` | `min`, `max` (ISO strings or `TODAY()`) |
-| `datetime` | `timestamp` | Date + time with timezone. | `timestamptz` | `min`, `max` |
+| `datetime` | `timestamp` | Date + time with timezone. Shown in the viewer's zone, unless `timeZone` pins one. | `timestamptz` | `min`, `max`, `timeZone` (an IANA name or `"UTC"`: show and edit on that zone's wall clock — a meeting, a check-in at a place; the stored value stays the UTC instant; an unknown zone is ignored) |
 | `time` | `time` | Time of day. | `time` | — |
 
 ## Binary / file
@@ -89,7 +89,8 @@ validation (`entity.schema.json` is `additionalProperties: false`). To give a co
 
 | Need | Do this |
 |---|---|
-| Literal / computed default (`'draft'`, `TODAY()`) | Carry a `formula` on the column (formula context — uppercase `TODAY()`/`NOW()`), e.g. `"formula": "'draft'"` or `"formula": "TODAY()"`. |
+| Literal / computed default (`'draft'`, `TODAY()`) | Carry a `formula` on the column (formula context — uppercase `TODAY()`/`NOW()`), e.g. `"formula": "'draft'"` or `"formula": "TODAY()"`. A number literal (`"0.25"`, an FK id `"50002"`) becomes the column's database `DEFAULT` when the column can hold it (never on a primary key or identity column). |
+| A module setting's value (`$[default_vat]`) | `"formula": "$[default_vat]"` — exactly the reference, nothing around it. An insert or import that leaves the column out takes the setting's value (folder overrides first, then the module's), and an upgrade backfills a new required column from it. No trigger needed. |
 | Document number (PO-2026-0001) | Declare a `numberSequence` on the entity — auto-fills on insert. |
 | Anything set at create time | Set it in an action/trigger DSL (`execute:` uses lowercase `now()`). |
 

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/formulas.md

@@ -104,8 +104,10 @@ FORMAT([created_date], 'yyyy-MM-dd')
 
 ### Date functions
 
-- `TODAY()` — current date
+- `TODAY()` — current date, in the request's time zone
 - `NOW()` — current datetime with timezone
+
+The request's zone is the browser's (sent on every call), else the user's profile zone, else the workspace's, else UTC. Before platform 2026-10-25 both were always UTC, so `TODAY()` was a day off around midnight for a viewer far from UTC. Scheduled jobs still run on UTC.
 - `YEAR(d)`, `MONTH(d)`, `DAY(d)` — date parts (`MONTH` is 1-based)
 - `HOUR(dt)`, `MINUTE(dt)`, `SECOND(dt)` — time parts
 - `WEEKDAY(d)` — day of week, `0` = Sunday
@@ -380,6 +382,8 @@ An `F` column is virtual: not stored, not editable. To fill a **stored, editable
 
 ## Common mistakes
 
+- Dividing by a column that can be zero (`[a] / [b]`) — wherever the formula runs in SQL (a stored `G` column, a filter, a sort, a report) a zero divisor fails the statement with `division by zero`. Guard it (`CASE([b] = 0, 0, [a] / [b])`) or store the result from an action.
+
 - Using `column_name` without brackets — **wrong**. Always `[column_name]`.
 - Inventing functions like `HAS_PERMISSION()`, `IS_ADMIN()`, `GET_USER()` — **do not exist**. Do not use unless confirmed to exist in the actual dForge engine.
 - Using JavaScript syntax like `row.field` or `this.field` — **wrong**. Only `[field]`.

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:
@@ -88,7 +94,9 @@ Formula columns (`F`) are read in the same SQL as the record, as `data.get` does
 | `format_date: <strftime>`                       | `{{ invoice_date | format_date: '%B %d, %Y' }}`        | `"May 22, 2026"`             |
 | `qr_code: <size?>, <ecc?>, <margin?>, <format?>`| `{{ payment_url | qr_code: 200, 'M' }}`                | `data:image/png;base64,…`    |
 
-`format_date` supports strftime: `%Y %m %d %B %b %H %M %S %I %p %A %a %e`.
+`format_date` supports strftime: `%Y %m %d %B %b %H %M %S %I %p %A %a %e`. `%B` / `%b` / `%A` / `%a` print **English** names whatever the user's language; for a month in another language keep a small snippet that maps `%m` to the name. `format_date` returns a **string**: arithmetic on its result fails ("Operator - not supported on string"), so compute on the raw value and format last.
+
+**Time zones.** A timestamp in `_fmt` and `format_date` on an instant render in the column's `params.timeZone`, else the request's zone (before platform 2026-10-25, always UTC). A bare date or a timestamp without a zone prints as written.
 
 ## Snippets
 
@@ -170,6 +178,9 @@ 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: on the server `x == blank` is false for nil and `''`, and true for a date. Use `{% unless x %}`, `{% if x and x != '' %}` or `x != nil`.
+- **Joining text across an empty reference.** A formula that glues several navigated parts (`[frp].[employee].[full_name]`) yields stray spaces when a hop is empty; `| strip` the result. Every role that prints needs Select on each entity of the path, or the value prints empty with a warning.
+- **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/queries.md

@@ -198,7 +198,7 @@ Queries are not in menu and not integrated into menu, they have separate section
 
 ## Translations
 
-Query names and descriptions are translated in `translations/en-US.json`:
+Query names and descriptions are translated in each non-English `translations/<locale>.json` (English is the query's own text — install skips an English file). For example `de-DE.json`:
 
 ```json
 {

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

@@ -17,6 +17,8 @@ Lives in: `registers.json` at the module root (a keyed dictionary, like `logic/j
 
 A register earns its place when something must be guarded or cached by its key: a negative-stock check, a unique slice, a period lock. Posting and unposting are then the platform's job, not a DSL's.
 
+Only a `balance` register folds movements into **one row per dimension tuple** (its state entity). A `turnover` register keeps every movement as a journal row and sums at read time; an `info` register keeps one record per key and `period`. So "how much is there now, per key" is `balance`; "how much moved" is `turnover`; "what was the value on a date" is `info`.
+
 ## The kinds
 
 | `kind` | Keeps | Written by | Read by | Key rules |
@@ -243,8 +245,8 @@ Paths, expressions, `dateTrunc`, `headerMap`, `groupLinesBy`, `lineDateField` an
 | `getBalance(register, dims?, asOf?)` | `balance` | `{ resource: value }`, zeros when empty |
 | `getTurnover(register, dims, from, to)` | `balance`, `turnover` | `{ resource: { in, out, net } }` |
 | `getSlice(register, dims, onDate?, mode?)` | `info` | Record plus `_period`, or `null`. `mode` is `last` (default) or `first`. |
-| `getAccountBalance(register, account, filter?, asOf?)` | `accounting` | `{ resource: { debit, credit, net } }` |
-| `getAccountTurnover(register, account, filter, from, to)` | `accounting` | Same shape |
+| `getAccountBalance(register, account, filter?, asOf?, options?)` | `accounting` | `{ resource: { debit, credit, net } }`; with `options.groupBy`, an array of rows |
+| `getAccountTurnover(register, account, filter, from, to, options?)` | `accounting` | Same shape |
 | `getCorrespondence(register, debitAccount, creditAccount, filter, from, to)` | compound | Same shape |
 
 ```
@@ -257,6 +259,8 @@ execute:
 - As-of reads and `getTurnover` need a journal with both stamps.
 - A read of the wrong kind is refused, naming the right one.
 - DSL reads are gated by the action's Execute right, not Select on the register tables.
+- **Account read options:** `groupBy` (a name or array; a row per combination, zero balances left out), `exclude` (one `{ entity, key }` or an array of them, of any entities, left out together; an empty array leaves nothing out; a refusal names the entry, `exclude[1]`), and on a balance `before` (up to that moment, exclusive and to the precision of the journal's date column, in place of `asOf`'s end of day; giving both is refused).
+- **Balance at a document's moment.** The platform keeps no order between movements stamped in the same second, so "the balance just before this document" is the caller's decision: read `before` the end of that second and `exclude` the document itself plus every document of that second the caller orders after it (1C's МоментВремени orders by date, then reference). `exclude` matches the postings each document wrote by its `source` stamp; postings loaded from another system carry no stamp and are kept unless the register declares `importedKeyField` (below).
 - **Reports:** a dataset with `"datasetType": "R"` reads an accounting register over an interval. It returns one row per chart account with `opening_*`, `turnover_*` and `closing_*` debit and credit for one resource. See [`reports.md`](reports.md) and [`docs/business-logic/gl-ledger-to-declared-register.md`](../../../docs/business-logic/gl-ledger-to-declared-register.md).
 
 ## Totals cache
@@ -265,11 +269,22 @@ execute:
 
 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`.
 
+For a history loaded from another system, an `accounting` register may declare `importedKeyField`: the posting column in which a posting **loaded** beside a document posted in another system (one with no `source` stamp) keeps that document's key. `getAccountBalance` / `getAccountTurnover` then leave such postings out when `exclude` names the document, matched on that key alone, as exact text and without telling entities apart — so declare it on a text column. A document with a key of several columns cannot be matched this way and is refused. A document of an entity that posts nothing to the register is accepted and matched by the key alone. Postings the engine wrote are still matched by their stamp only. Install refuses a name that is no posting column. New in metadata 0.0.46; no shipped module uses it yet.
+
+**Loading postings yourself.** The engine writes an analytic slot as `{ entityId, entity, entityLabel, description, pk, value }` with `entity` the qualified `module.entity` (`acc-registry.cost_center`), and the caches copy it as is. A loader writes the same qualified name. A `{ entity, value }` filter accepts either spelling: a qualified name matches its own module's slots and older bare ones, a bare name matches that code in any module. `groupBy` returns a slot as stored, so a journal still holding bare slots (written before platform #1544) beside qualified ones groups them into two rows — until a module migration rewrites the old slots and `rebuild-totals` runs.
+
+**Rebuild time.** Install rebuilds a cache whose shape or account flags changed, in the install's transaction. On a large journal this takes minutes (about 18 minutes for an analytic cache over 1.5 million postings), and the CLI can give up waiting while the server goes on and finishes. Check the cache before installing again.
+
+
 ## Common mistakes
 
 - **Undeclared or unqualified register.** `params.register` must be `module_cd.register_cd` and exist. Install fails, not the first posting.
 - **Unmapped required resource.** Map it, or mark the resource `"required": false` when only some writers supply it.
-- **Empty dimension.** An empty dimension refuses the posting. `skipPostingWhenEmpty` is the exception: it leaves a document posted while some lines moved nothing. Prefer one line table per binding. Use it only when the distinction lives in the data, such as a serial number filled on some rows.
+- **Empty dimension.** An empty (NULL) dimension refuses the posting; there is no `allowEmpty`, on any kind. Two ways out: map the dimension through an expression with a placeholder, `"=COALESCE([frp_id], 0)"` (`A` column only), or list it in `skipPostingWhenEmpty`, which leaves the document posted while those rows move nothing. Prefer one line table per binding. Use `skipPostingWhenEmpty` only when the distinction lives in the data, such as a serial number filled on some rows. Data loaded from another system often has such rows (a movement with no warehouse), so decide this before the load.
+- **`headerMap` takes columns only.** It maps a register name to a **document** column; it does not take a constant or an expression. Every column it names must be in `lockedFields`: a line movement copies the header value at posting, and unposting takes back exactly what was posted, so a header value edited while posted would leave the register out of step. For a constant on every line, use a quoted constant in `map`.
+- **One constant for two resources.** Two resources mapped to the same constant read as two resources storing into one column and are refused.
+- **Period missing from the calendar.** With `periodEntity`, a month that has no row in the period entity counts as **closed**, and posting into it fails (`DF003: Period 1999-04 does not exist`). Seed or load the periods before the documents that post into them.
+- **A summed column that isn't a number.** A resource of a `balance`, `turnover` or `accounting` register, and a `totals` cache's columns, must be a scalar number. The editor and language server warn (`registers/column-not-numeric`, metadata 0.0.46) on `varchar`, `integer[]` and the like. An `info` register's resources are returned, not summed, and may be any type.
 - **Missing or unlocked `dateField`.** Required once the register has `journalDate` or `period`, and it must be in `lockedFields`.
 - **Key over dimensions.** The journal, a subordinate `info` register's records and an `autoCreate` state table are written by the platform. Each needs **one** surrogate primary key of type `bigint` (`identity`/`cuid`) or `uuid`. A key over dimensions, a multi-column key, a text key and `int4` are refused.
 - **State column narrower than the journal column.** It must hold the journal's value exactly, or unposting cannot take back what posting added.