@dforge-core/dforge-mcp 0.2.44 → 0.2.46-next

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
@@ -319,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 |
@@ -348,7 +353,7 @@ error('Insufficient stock. Available: {available}, requested: {requested}',
 |---|---|
 | `sendEmail(to, subject, htmlBody)` | Send a raw email. `to` is an email address string. |
 | `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. |
+| `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
 
@@ -356,6 +361,8 @@ error('Insufficient stock. Available: {available}, requested: {requested}',
 |---|---|---|
 | `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
@@ -700,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.
@@ -746,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.
 
@@ -809,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.
@@ -825,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/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

@@ -94,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
 
@@ -176,7 +178,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`.
+- **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).

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.

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

@@ -162,8 +162,10 @@ $$;
 - `paramCd` is capped at 50 characters, and a declared `fieldTypeCd` must be a real one —
   both are checked at install, because binding the SP in the report editor copies them
   into report params.
-- `RETURNS TABLE (...)`.
+- `RETURNS TABLE (...)`. In `LANGUAGE plpgsql` with `RETURN QUERY`, each selected column must match its declared type exactly: a `varchar` column returned as `text` fails with "structure of query does not match function result type". Cast in the select (`c.account_name::text`).
 - Use the module's schema prefix (`crm.rpt_*`) and `STABLE` volatility.
+- **A function that returns one row: declare `ROWS 1`.** Install adds `SET search_path` to the function, which stops Postgres from inlining it, so the planner falls back to its default estimate of 1000 rows and a join on the function can turn a 5-second report into a 20-minute one. `ROWS 1` (or a realistic estimate) on each table function the report calls restores the plan.
+- **Every `logic/reports/*.sql` runs at every install**, as the install's database user. Don't create or replace the function by hand under another user while experimenting: the next install fails with "must be owner of function". Try SQL in a transaction you roll back, and let install own the functions.
 - **Security is your responsibility, and the function has no context to work from**: it is not
   told the folder or the user, so an SP dataset cannot be row-level scoped the way a `"Q"`
   dataset is. Use `"Q"` for anything that must be filtered per user, and keep `"S"` for
@@ -197,6 +199,7 @@ granted on. Keyed by stored-procedure code, which may not contain a dot.
 - **`params`** is the call signature, in order — omit it for a zero-argument function.
 - **`columns`** is optional; without it install derives the result columns from the
   function's `RETURNS TABLE (…)`.
+- A result column's `baseDatatypeCd` is a platform base type code: `string`, `number`, `bool`, `date`, `timestamp`, `time`, `guid`, `json`, `link`, `set`, `binary`, `xml`, `culture`. Not `datetime`, `boolean`, `integer` or `text`: an unknown code fails install with a bare foreign-key error on `sp_column`, which validate does not catch yet.
 - A result column may name a **`domain`** (`domain_cd` or `module_cd.domain_cd`) instead of
   `fieldTypeCd` / `baseDatatypeCd` / `params`: a status the function returns then shows its
   labels without restating the entity's option list. Naming a domain and restating any of

package/skills/dforge-mcp-author/references/schema-import.md

@@ -111,7 +111,7 @@ Using the converted entities, generate the full module package:
 4. **`ui/menus.json`** — grouped logically (group related entities under section nodes)
 5. **`ui/folders.json`** — root folder with all entities listed
 6. **`security/roles.json`** — at least `module.admin` (SIUDC on everything) and `module.user` (SIU on main entities)
-7. **`translations/en-US.json`** — labels for all entities, fields, views, menus, actions, roles, folders
+7. **English labels in the definitions** — a short `description` on every entity, field and role, a `label` on every view, menu and action. No `translations/en-US.json`: install skips it. Translation files only for the locales in `supportedLocales` (`dforge_translation_sync`)
 8. **`seed-data/`** — if the source had enum/lookup tables converted to entities, generate seed data for them
 
 ### Step 8: Generate IMPORT_NOTES.md

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

@@ -16,7 +16,7 @@ Lives in: `security/roles.json`
 
 Role codes use a `module.role` naming pattern (e.g. `crm.admin`, `crm.sales-rep`).
 
-> **Role display name & translations.** Each role has exactly two keys: `description` and `rights` (`roles.schema.json` is `additionalProperties: false` — **do not** add a `label` here). `description` is the English fallback display name. The **localized** display name lives in the translation files as `roles.<code>.label`, keyed by the module-qualified role code, and is **completeness-enforced**: every role must have a `roles.<code>.label` in every `translations/<locale>.json` (including the `en-US` base) or install fails. See `translations.md`.
+> **Role display name & translations.** Each role has exactly two keys: `description` and `rights` (`roles.schema.json` is `additionalProperties: false` — **do not** add a `label` here). `description` is the English display name — keep it a short label ("Storekeeper"), not an explanation, since it is what the English UI shows. The **localized** display name lives in the translation files as `roles.<code>.label`, keyed by the module-qualified role code, and is **completeness-enforced**: every role must have a `roles.<code>.label` in every non-English `translations/<locale>.json` or install fails. There is no English translation file. See `translations.md`.
 
 Example:
 

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

@@ -2,9 +2,33 @@
 
 dForge modules support multi-language translations for user-facing labels — entity names, field labels, view titles, folder names, menu items, action labels and params, and report params/dataset captions.
 
-Lives in: `translations/<locale>.json` (e.g. `translations/en-US.json`, `translations/de-DE.json`)
+Lives in: `translations/<locale>.json` for each **non-English** locale (e.g. `translations/de-DE.json`, `translations/uk-UA.json`)
 
-Locale codes use the `ll-CC` format (language-country): `en-US`, `de-DE`, `fr-FR`, `es-ES`, etc.
+Locale codes use the `ll-CC` format (language-country): `de-DE`, `uk-UA`, `fr-FR`, `es-ES`, etc.
+
+## English is the base — and it lives in the definitions
+
+Install **never reads** `translations/en.json` or `translations/en-*.json` (`ModulePackage.ReadTranslationFiles` skips them). The English UI shows the text written in the definitions themselves, so an English-only module ships **no** `translations/` folder, and a translated module ships one file per locale in `supportedLocales` and nothing for English. An `en-US.json` is dead weight: its labels are never applied, and the English UI keeps showing whatever the definitions say — which is how a module ends up displaying long service descriptions as labels. `dforge_module_validate` warns about such a file; `dforge_translation_sync` refuses to write one.
+
+Where each object's English text lives (what install shows, `label ?? description ?? code` where both exist):
+
+| Object | English text | Notes |
+|---|---|---|
+| Entity | `description` in `entities/<e>.json` | |
+| Field | `description` on the field | trait columns take theirs from the trait |
+| Data view | `label`, else `description` | with both, `description` is the tooltip |
+| Folder | `label`, else `description` | |
+| Menu / menu item | `label`, else `description` | |
+| Action | `label`, else `description` | an action param: its `description` |
+| Report | `label`, else `description` | |
+| Stored procedure | `description`; a result column: its `label` | |
+| Print template | `description` | `label` is rejected by the schema |
+| Setting | `description` | |
+| Role | `description` | `label` is rejected by the schema |
+| Column domain | `description` | |
+| Register | `label` | |
+
+Keep these short **labels** — "Product", "Storekeeper" — not explanations. Notes such as a legacy table name or "(in Ukrainian)" belong in docs or comments: whatever the field holds is the UI text.
 
 ## Structure
 
@@ -111,7 +135,7 @@ A check/unique constraint declares a user-facing `message` in the entity JSON (`
 
 ### Dropdown option labels ARE translatable (opt-in)
 
-The `options` on a `dropdown`/`radio`/`flags` column are the **base (fallback) labels**. To translate the labels a user actually sees, add an `options` map next to the field's `label`, keyed by the option's **value** (the stored code):
+The `options` on a `dropdown`/`radio`/`flags` column are the **base (fallback) labels**, and they are the English UI — write plain English there (`"Active"`), never a bilingual `"Active (Актив)"`. To translate the labels a user actually sees, add an `options` map next to the field's `label`, keyed by the option's **value** (the stored code). Prefer the **string** form (`"active": "Активний"`): the `{ label, … }` form is valid, but the VS Code extension's translation panel counts it as missing, and `module validate` does not check option translations at all. An option list several columns share belongs in a column domain, translated once under `domains.<code>.options`.
 
 ```json
 "entities": {
@@ -204,15 +228,14 @@ Role labels are **required and localized** (this changed — older docs said rol
 ```
 
 - **Keys are the role codes** from `security/roles.json` — already module-qualified (e.g. `crm.admin`, `crm.sales-rep`). They match `module_role.name`.
-- **Value is `{ "label": ... }`** — the localized display name. It supersedes the `description` from `roles.json` at runtime; `description` remains the English fallback if a role has no translation entry.
-- **Completeness is enforced.** `TranslationCompletenessValidator` requires `roles.<code>.label` for **every** role in `security/roles.json`, in **every** translation file — including the `en-US` base. A missing role label fails install with `Label for role '<code>'.` So ship a `roles` block with a label for each role in **each** `translations/<locale>.json` (en-US + every locale in `supportedLocales`).
+- **Value is `{ "label": ... }`** — the localized display name. It supersedes the `description` from `roles.json` in that locale; `description` is the English text.
+- **Completeness is enforced.** `TranslationCompletenessValidator` requires `roles.<code>.label` for **every** role in `security/roles.json`, in **every** translation file install reads — each locale in `supportedLocales`. A missing role label fails install with `Label for role '<code>'.` English needs nothing here: it is the role's `description`.
 
 ### Sections that are NOT translated (write-time only)
 
-- `settings` — completeness *is* checked by the validator when listed in `manifest.supportedLocales` (so you'll be forced to ship `settings.<cd>.label` for each declared locale), but the registrar doesn't display those translated labels at runtime. The English `label` in `settings.json` is what users see today.
-- `print_templates` — not currently consumed by the registrar. Template labels come from `ui/print_templates.json`.
+- `print_templates` — not consumed by the registrar: a template row has no translatable resource. Its name is the `description` in `ui/print_templates.json` in every language. If you include the section, install succeeds and ignores it.
 
-If you include these sections, the install succeeds (they're silently ignored) — but you won't see localized output for them, so don't expect it.
+`settings` **is** translated: completeness is checked for each declared locale (ship `settings.<cd>.label`), and the setting's English text is its `description` in `settings.json` — the registrar never reads a `label` there.
 
 ## German example (de-DE)
 
@@ -262,7 +285,7 @@ If you include these sections, the install succeeds (they're silently ignored)
 
 ## Manifest declaration
 
-Non-English locales are declared in `supportedLocales` (an array of `ll-CC` tags) — **not** a `translations` object. The manifest schema has no `translations` key and rejects it (`additionalProperties: false`). Translation files are auto-discovered at `translations/<locale>.json`. Ship `translations/en-US.json` as the English base, but do **not** list `en`/`en-US` in `supportedLocales` — it covers the non-English locales only (the schema rejects `en`/`en-US` entries).
+Non-English locales are declared in `supportedLocales` (an array of `ll-CC` tags) — **not** a `translations` object. The manifest schema has no `translations` key and rejects it (`additionalProperties: false`). Translation files are auto-discovered at `translations/<locale>.json`. Do **not** list `en`/`en-US` in `supportedLocales` and do not ship an English file — English is the definitions' own text (see above); the schema rejects `en`/`en-US` entries.
 
 ```json
 "supportedLocales": ["de-DE", "fr-FR"]
@@ -276,18 +299,18 @@ A result column's header belongs to the procedure, not to a report. `module pack
 
 ## Rules
 
-1. **Always provide `en-US`** as the base language. Other languages fall back to it for missing keys.
-2. **Locale format is `ll-CC`** (e.g. `en-US`, `de-DE`, `fr-FR`) — language code + country code, hyphen-separated.
-3. **Translate everything user-visible**: entity labels, every field label (including trait-provided fields like `created_date`, `last_updated`), view names, menu items, action labels, **role labels (required — completeness-enforced, `roles.<code>.label` for every role in every locale incl. en-US)**, setting labels, folder names.
+1. **English is the definitions' text** — no `en-US.json`. Write a short English label into each definition (see the table above); other languages fall back to it for missing keys.
+2. **Locale format is `ll-CC`** (e.g. `de-DE`, `uk-UA`, `fr-FR`) — language code + country code, hyphen-separated.
+3. **Translate everything user-visible**: entity labels, every field label (including trait-provided fields like `created_date`, `last_updated`), view names, menu items, action labels, **role labels (required — completeness-enforced, `roles.<code>.label` for every role in every declared locale)**, setting labels, folder names.
 4. **Include virtual columns** (references, sets, formulas) in field translations — they appear in the UI just like physical columns.
 5. **Menu translations mirror the `ui/menus.json` structure** — root key → `items` → nested items.
-6. **Missing keys fall back** to the `en-US` value, then to the raw code name. So it's safe to ship partial translations — untranslated items show in English rather than breaking.
+6. **Missing keys fall back** to the definition's English text, then to the raw code name. So it's safe to ship partial translations — untranslated items show in English rather than breaking.
 7. **Don't translate column codes** — only the `label` values. Codes stay as-is in all languages.
 8. **File naming**: `translations/<locale>.json` (e.g. `de-DE.json`) — each non-English file must match a locale listed in `supportedLocales`.
 9. **Constraint messages are opt-in** — localize them under `entities.<e>.constraints.<c>.message` when you want a per-locale violation message; otherwise the base `message` from the entity JSON is used. Missing overrides warn (non-fatal), they don't fail install. See "Constraint violation messages ARE translatable" above.
 
 ## When to create translations
 
-- **Always** create `translations/en-US.json` — even for English-only modules. It ensures all labels are explicitly declared rather than derived from column codes.
-- **On request** create additional languages. The LLM can generate translations from the `en-US` file — the structure is identical, only `label` and `desc` values change.
+- **Never** create `translations/en-US.json` — install skips it. Give every definition a short English label instead, so nothing falls back to a column code.
+- **On request** create additional languages: declare them in `supportedLocales` and run `dforge_translation_sync`, which seeds each file from the definitions' English text for you to translate in place.
 - **Include all fields** in each language file, including trait-provided fields (`created_date`, `last_updated`, `created_by`, etc.) — users see these columns and they need labels.

package/skills/dforge-mcp-author/references/validation-checklist.md

@@ -162,8 +162,8 @@ For each action:
 
 ## Translations
 
-- [ ] `translations/en-US.json` exists
-- [ ] Has `entities` section with `label`, `desc`, and `fields` for every entity
+- [ ] **No** `translations/en.json` / `en-*.json` — install skips them. English is each definition's own short label (entity/field/role/setting `description`, view/menu/action/report `label`)
+- [ ] Each `translations/<locale>.json` (one per `supportedLocales` entry) has an `entities` section with `label`, `desc`, and `fields` for every entity
 - [ ] Every field (including trait-provided: `created_date`, `last_updated`, etc.) has a `label`
 - [ ] Has `views` section with labels for every data view
 - [ ] Has `menus` section matching the `ui/menus.json` structure
@@ -172,7 +172,6 @@ For each action:
 - [ ] (Optional) Constraint messages localized under `entities.<e>.constraints.<c>.message` — opt-in; a missing override for a declared `supportedLocales` entry warns (surfaced by `dforge_module_validate` and at install) but does not fail install
 - [ ] Has `settings` section with labels for every setting (if settings exist)
 - [ ] Has `folders` section with label for the root folder
-- [ ] Additional language files (if any) have the same structure as `en-US.json`
 - [ ] Manifest `supportedLocales` lists every non-English locale that has a `translations/<locale>.json` file (English is not listed)
 
 ## Versioning

package/skills/dforge-module-build/SKILL.md

@@ -36,12 +36,15 @@ flags, or column patterns.
 | Suggest a value when another field is edited (a reaction), incl. from a bridge module | `dforge://reference/reactions` | `dforge://schema/entity`, `dforge://schema/deps` |
 | Add a trait | `dforge://reference/traits` | — |
 | Add a number sequence | `dforge://reference/number-sequences` | — |
+| Add an accumulation register (`A` column, `registers.json`) | `dforge://reference/registers` | `dforge://schema/registers` |
+| Edit the manifest (version, `supportedLocales`, dependencies, `entities` map) | `dforge://reference/manifest` | `dforge://schema/manifest` |
 | Add a grid / list view | `dforge://reference/data-views`, `dforge://example/ui/data_views.json` | — |
 | Add a matrix (pivot) view | `dforge://reference/data-views` (§Matrix), `dforge://example/matrix-budget/ui/data_views.json`, `dforge://example/matrix-budget/entities/budget_line.json` | — |
 | Add kanban / calendar / tree-grid / master-detail | `dforge://reference/data-views` | `dforge://schema/data-views` |
 | Hide columns from a user type (column-level security) | `dforge://reference/security` (§Column-level security), `dforge://example/column-security/entities/product.json`, `dforge://example/column-security/ui/folders.json` | — |
 | Add a menu | `dforge://reference/menus`, `dforge://example/ui/menus.json` | — |
 | Add an action | `dforge://reference/action-dsl`, `dforge://example/logic/actions/mark_done.dsl`, `dforge://example/ui/actions.json` | `dforge://docs/dsl` |
+| Email a file the script builds, or ship saved values / a PDF preview for an action's dialog | `dforge://reference/action-dsl` (§Email and §PDF and file output: `sendEmail` attachments, `attachText`, `attachBase64`; §Registering the action: `paramSets`, `previewTemplate`) | `dforge://docs/dsl` |
 | Share helpers between actions, or call another module's functions | `dforge://reference/action-dsl` (§Function libraries): `logic/functions/*.dsl`, imports in `deps/<module>.json` | `dforge://schema/deps` |
 | Add a trigger | — | `dforge://schema/triggers`; condition syntax in `dforge://docs/dsl` |
 | Add a scheduled job | `dforge://reference/jobs` | `dforge://schema/jobs` |
@@ -115,6 +118,10 @@ Enough to author inline; load the linked reference for the full detail.
 - **Manifest:** non-English locales go in `supportedLocales` (`ll-CC`, never
   `en`/`en-US`); there is no `translations` manifest key. `security` has both
   `roles` and `folders`. → `manifest`
+- **English is the definitions' text:** install skips `translations/en*.json`, so
+  never create one. Give every entity, field, role and setting a short
+  `description` and every view, menu, action and report a short `label` — that
+  is what the English UI shows. → `translations`
 - **Seed data:** explicit numeric PKs under `{entity}_id`; parents before
   children via the `NN-` prefix. Use `dforge_seed_add`.
 
@@ -160,6 +167,7 @@ approval, then patch. Reach for the **composite tools first**:
 - roll-up total → `dforge_entity_rollup_add`
 - status column → `dforge_entity_status_add`
 - plain scalar → `dforge_entity_field_add`
+- change an existing field (label, flags, type, …) → `dforge_entity_field_modify`
 
 **Field batching rule** — the only Phase 1 exception to one-at-a-time. A field
 is batchable only if ALL of: scalar primitive (string/integer/decimal/boolean/
@@ -285,7 +293,8 @@ stated trigger; every report's params sit on a dataset.
 ## Phase 4 — Polish (mostly optional)
 
 - **Settings** — `dforge_setting_add` per configurable value the user asked for.
-- **Translations** — run **`dforge_translation_sync`**. It generates every
+- **Translations** — only for the locales in `supportedLocales`; English needs
+  no file. Run **`dforge_translation_sync`**. It generates every
   required key from the module's own contents, never overwrites existing
   translated text, and fills the **role labels that are completeness-enforced at
   install**. Run it after any entity/view/role change, and always before Phase 6.

package/skills/dforge-module-ship/SKILL.md

@@ -78,9 +78,9 @@ formula column shape; flags letters (`V I E M H` only); every entity has a
 default grid and `dataSources` at root with `"order"` as a string array; menu
 leaves use `dataViewCode` and bare icon names; every entity in at least one
 role's rights; action `script` values are bare filenames; seed PKs numeric with
-parents first; a `translations/<locale>.json` for every `supportedLocales` entry
-**plus** the `en-US` base, each carrying a label for every trait-provided field
-and every role.
+parents first; a `translations/<locale>.json` for every `supportedLocales` entry,
+each carrying a label for every trait-provided field and every role. No English
+file — install skips `en*.json`; English is the definitions' own short labels.
 
 If translations are thin, run **`dforge_translation_sync`** now rather than
 hand-patching — it fills exactly the keys install requires.
@@ -156,6 +156,34 @@ package — fix the referenced files, report what changed, and immediately re-ru
 validate → pack → install. Keep sign-off for product/design choices or genuinely
 ambiguous fixes.
 
+**If install hangs, or fails with a bare HTTP 500 or 400 "deadlock":** look for
+a lock before touching the module. An install's `ALTER TABLE` waits behind any
+open transaction on the module's tables — an idle `psql` session, an ad hoc
+read left open, a script that never commits — and waits without a message,
+for an hour or more. Check `pg_stat_activity` for a blocked `ALTER` and the
+session holding it. Never install while scripts hold transactions on the
+module's tables; run ad hoc scripts in autocommit.
+
+**If install times out on the client while rebuilding a register cache:** the
+server goes on and finishes (an analytic cache over 1.5 million postings took
+about 18 minutes). Check the server log or the cache before installing again.
+
+**Same version installed "successfully" but nothing changed:** a re-install of
+the same `version` is skipped (`isEmpty: true`). Bump the version, or pass
+`--force` on a dev tenant.
+
+**Local dev stack pitfalls:**
+- After installing into a local docker setup, restart `dforge-api` if the UI
+  still shows the old metadata; its cache can stay stale.
+- The tenant URL is `http://<tenant>._.localhost:5179`. `<tenant>.localhost`
+  and `<tenant>_.localhost` sign into **another** tenant.
+- "no token for tenant X": the CLI session expired (a token lasts about an
+  hour). Run `dforge-cli auth login --url <tenant url>`.
+- "tenant at db_schema_version … is ahead of this binary" after rebuilding the
+  platform: install through the server with `--url`.
+- Don't keep scaffold copies of a module (same `code`, another `moduleId`)
+  anywhere a folder publish can pick them up.
+
 **If install fails on auth (401/403) or connectivity (refused):** that is
 credentials/connectivity, NOT a module defect. Tell the user to verify
 `DFORGE_URL` and `DFORGE_TOKEN`. **Do not backtrack** to earlier phases.

package/skills/dforge-mcp-author/examples/column-security/translations/en-US.json

@@ -1,35 +0,0 @@
-{
-	"entities": {
-		"product": {
-			"label": "Product",
-			"fields": {
-				"name": { "label": "Product Name" },
-				"sku": { "label": "SKU" },
-				"quantity": { "label": "Quantity On Hand" },
-				"cost_price": { "label": "Cost Price" },
-				"sale_price": { "label": "Sale Price" },
-				"margin": { "label": "Margin" }
-			}
-		}
-	},
-	"folders": {
-		"warehouse": { "label": "Warehouse" },
-		"finance": { "label": "Finance" }
-	},
-	"roles": {
-		"column_security.storekeeper": { "label": "Storekeeper" },
-		"column_security.accountant": { "label": "Accountant" }
-	},
-	"views": {
-		"product_grid": { "label": "Products" }
-	},
-	"menus": {
-		"product_menu": {
-			"label": "Products",
-			"items": {
-				"catalog": { "label": "Catalog" },
-				"all_products": { "label": "Products" }
-			}
-		}
-	}
-}