@dforge-core/dforge-mcp 0.2.31 → 0.2.33

package/package.json

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

package/resources/docs/conventions.md

@@ -512,7 +512,7 @@ Two halves, both required:
 
 **`"default"` is the one exempt name** and means "no view" (full column set). It is what the ~100 shipped folder entries write, what `FolderExporter` writes back for a NULL `view_name`, and what the runtime auto-creates (column-less) for an entity reached without a folder binding — so rejecting it would fail every install. A module that really declares a view named `default` still gets it bound.
 
-Don't confuse the three things called "view": an **entity view** (`views`, this section) is column security; a **data view** (`ui/data_views.json`, referenced by a menu's `dataViewCode`) is a grid/kanban/calendar; `isView` + `viewSql` on an entity means it is backed by a SQL view. `folders.json`'s `viewName` binds the first.
+Don't confuse the two things called "view": an **entity view** (`views`, this section) is column security; a **data view** (`ui/data_views.json`, referenced by a menu's `dataViewCode`) is a grid/kanban/calendar. `folders.json`'s `viewName` binds the first. An entity is never backed by a SQL view — `isView` / `viewSql` are rejected; use a data view, a report or a stored procedure instead.
 
 ## Column Domains (`domains.json`)
 

package/resources/docs/dsl-reference.md

@@ -472,14 +472,16 @@ scalar; denormalise instead of navigating; put the rest in `execute:` behind
 
 ### Messaging & notifications
 
-#### `info(message, opts?)`, `warn(message, opts?)`
-Queue user-facing toast. `opts.links: [{entity, id}]` adds "open record" buttons.
+#### `info(message, values?, opts?)`, `warn(message, values?, opts?)`
+Queue user-facing toast. `values` fills the message's `{name}` placeholders; `opts.links: [{ label, entity, record }]` makes `label` in the text a link to that record (`pk:` instead of `record:` takes a key value or object). A link label must be data — a record number — never a word, since it is found in the text after translation.
+
+**Translatable.** The message text is looked up by its exact English wording in the module's `messages` translations (`dforge://reference/translations`), in the user's language; no entry shows the English. Put varying values in `{name}` placeholders, filled from `values` — never join them into the string, which leaves no fixed text to translate. `links` is not a placeholder name.
 
 A message is a **receipt for work the action did**, not a way to publish a computed value. An action whose only output is `info('<some computed number>')` stores nothing — it can't be audited, re-read or reported on, and the value arrives unformatted. Build a **record report** (a report with an `entities` attachment: it lands on the same record toolbar, but shows the numbers *and* the rows behind them, re-read live on every open), a formula column, or an action that writes a result record instead. Do not compute in DSL what a report dataset already aggregates. See `dforge://reference/action-dsl`, *When an action is the wrong tool*, and `dforge://reference/reports`.
 
 ```dsl
-info('Created PO ' + po.po_number, {
-    links: [{ entity: 'purchase_order', id: po.purchase_order_id }]
+info('Created PO {po}', { po: po.po_number }, {
+    links: [{ label: po.po_number, entity: 'purchase_order', record: po }]
 })
 warn('Stock below reorder point — review supplier')
 ```
@@ -506,7 +508,7 @@ sendEmail([customer_id].[email], 'order_confirmation', {
 })
 ```
 
-#### `error(message)`
+#### `error(message, values?)`
 **Throw** — aborts execution immediately. Use for validation failures. Whether
 prior `insert()` / writes in this `execute:` block are rolled back **depends on the
 execution path** and is not something to rely on — validate before writing
@@ -516,10 +518,13 @@ anything (see the anti-pattern near the end of this document).
 if ([rating] == null || [rating] < 1 || [rating] > 5) {
     error('Rating must be 1-5')
 }
+if (available < params[quantity]) {
+    error('Only {n} left', { n: available })
+}
 ```
 
-#### `exit(message?, level?)`
-Successful early exit — **commits** work done so far. `level`: `"info"` (default) | `"warning"` | `"danger"` | `"success"`.
+#### `exit(message?, level?, values?)`
+Successful early exit — **commits** work done so far. `level`: `"info"` (default) | `"warning"` | `"danger"` | `"success"`. `values` fills the message's placeholders, as for `info()`.
 
 ```dsl
 if ([status] == 'closed') { exit('Already closed — nothing to do', 'info') }

package/resources/schemas/diagram.schema.json

@@ -21,7 +21,7 @@
 			"type": "object",
 			"description": "Entity key → placement. A key is the entity code as the module's manifest names it, or `module.entity` for an entity of a dependency — the same form a field link's `entity` takes. A key no entity has yet is a planned entity, drawn as a name only. An empty object places the entity automatically.",
 			"propertyNames": {
-				"minLength": 1
+				"$ref": "#/$defs/entityKey"
 			},
 			"additionalProperties": {
 				"$ref": "#/$defs/diagramEntity"
@@ -46,6 +46,11 @@
 	},
 	"additionalProperties": false,
 	"$defs": {
+		"entityKey": {
+			"type": "string",
+			"pattern": "^([a-zA-Z_][a-zA-Z0-9_-]*\\.)*[a-zA-Z_][a-zA-Z0-9_-]*$",
+			"description": "An entity code, optionally qualified by its module's code: `entity`, `module.entity`. Each part is an identifier the installer accepts: `[a-zA-Z_][a-zA-Z0-9_-]*`."
+		},
 		"diagramEntity": {
 			"type": "object",
 			"properties": {
@@ -77,13 +82,11 @@
 			"required": ["from", "to"],
 			"properties": {
 				"from": {
-					"type": "string",
-					"minLength": 1,
+					"$ref": "#/$defs/entityKey",
 					"description": "Entity key of the many side — the entity that will carry the foreign key."
 				},
 				"to": {
-					"type": "string",
-					"minLength": 1,
+					"$ref": "#/$defs/entityKey",
 					"description": "Entity key of the one side — the entity referenced."
 				},
 				"label": {

package/resources/schemas/entity.schema.json

@@ -2,7 +2,7 @@
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "https://dforge.dev/schemas/entity.schema.json",
 	"title": "dForge Entity Definition",
-	"description": "Defines an entity (table/view mapping) for a dForge module",
+	"description": "Defines an entity (a table) for a dForge module",
 	"type": "object",
 	"anyOf": [
 		{ "required": ["fields"] },
@@ -24,16 +24,7 @@
 		},
 		"dbObject": {
 			"type": "string",
-			"description": "Database table or view name (defaults to entity code)"
-		},
-		"isView": {
-			"type": "boolean",
-			"description": "When true, entity maps to a SQL view (read-only, no DDL generation). Default: false (table-backed).",
-			"default": false
-		},
-		"viewSql": {
-			"type": "string",
-			"description": "SQL SELECT statement for view-backed entities (isView=true). Executed as CREATE OR REPLACE VIEW during module install."
+			"description": "Database table name (defaults to entity code)"
 		},
 		"toString": {
 			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\" — the caption of a record wherever it is referenced. Every `{placeholder}` must name a field of the entity (trait columns included) and not a set; pack and install fail otherwise. Omitted, the install generates one from the fields and warns. Not declared on extension entities (with `extends`). No `type` constraint here because `toString` collides with Object.prototype.toString in JSON validators — they read the inherited function and reject it, even when the property is absent from the JSON."
@@ -42,6 +33,11 @@
 			"type": "boolean",
 			"description": "Records of this entity accept comments \u2014 the composer and thread appear on the record card, beside the audit history. Opt-in per entity; `comments` in the manifest sets a module-wide default that this overrides in both directions."
 		},
+		"auditHistory": {
+			"type": "string",
+			"enum": ["basic", "fields", "full"],
+			"description": "Audit history level for this entity, overriding the manifest's `auditHistory`: 'basic' logs each insert/update/delete without field details; 'fields' adds old/new values of changed fields; 'full' also stores display values (reference and user names). Omit to disable."
+		},
 		"traits": {
 			"type": "array",
 			"description": "Entity traits expanded during module install (authoring shortcut). Trait definitions loaded from DB (seeded by metadata module).",
@@ -146,7 +142,7 @@
 		},
 		"views": {
 			"type": "object",
-			"description": "Entity views keyed by view name — column-level security. Unrelated to 'isView'/'viewSql' (a SQL-view-backed entity) and to ui/data_views.json (grids, kanban, calendars). A folder binds one view per entity via ui/folders.json (entities.<code>.viewName); users working in that folder see ONLY the columns the view lists. Entities without views show the entity's full column set; a folder naming a view that isn't declared here FAILS the install, since resolving it to nothing would show every column \u2014 the opposite of what naming a view asks for. A view can only be declared by the entity's own module: an extension ('extends') declaring 'views' is rejected, because a view lists the complete column set and an extension knows only the columns it adds.",
+			"description": "Entity views keyed by view name — column-level security. Unrelated to ui/data_views.json (grids, kanban, calendars). A folder binds one view per entity via ui/folders.json (entities.<code>.viewName); users working in that folder see ONLY the columns the view lists. Entities without views show the entity's full column set; a folder naming a view that isn't declared here FAILS the install, since resolving it to nothing would show every column \u2014 the opposite of what naming a view asks for. A view can only be declared by the entity's own module: an extension ('extends') declaring 'views' is rejected, because a view lists the complete column set and an extension knows only the columns it adds.",
 			"propertyNames": {
 				"pattern": "^[a-zA-Z_][a-zA-Z0-9_-]*$",
 				"maxLength": 100
@@ -364,6 +360,14 @@
 						"serverDefault": {
 							"$ref": "#/$defs/serverDefault"
 						},
+						"currency": {
+							"type": "string",
+							"description": "currency field type: fixed ISO 4217 code (e.g. 'USD') the value is formatted in. With currencyColumn, the code used for a record whose currencyColumn is empty."
+						},
+						"currencyColumn": {
+							"type": "string",
+							"description": "currency field type: a scalar column of the same entity holding the ISO 4217 code per record, e.g. a 'currency' dropdown. Each value is formatted in its own record's currency; a total over rows in different currencies shows no symbol. A line reads its header's code through a formula column ([invoice].[currency]). Display only — nothing converts between currencies."
+						},
 						"pattern": {
 							"type": "string",
 							"description": "Format rule for this column, as an ECMAScript regex source. Overrides the field type's own pattern (field_type.def_params.pattern, which is what makes email/phone/url reject a malformed value). Enforced in the browser and again on data.insert / data.update, so keep to constructs both engines read alike: [0-9] and \\d are the same there, \\s is normalized to JavaScript's set, and a pattern that will not compile is skipped by both rather than enforced by one."
@@ -388,7 +392,7 @@
 					"description": "Reference to a reusable column domain, qualified as 'module_cd.domain_cd' (unqualified resolves within this module, then tenant-created domains). The domain supplies dbDatatype, baseDatatypeCd, fieldTypeCd, maxLen, precision and params; declaring any of those alongside 'domain' is rejected at install. The column keeps its own description, flags, orderNum, isNullable and isPk."
 				},
 				"refFilter": {
-					"description": "Filter criteria for reference lookups. Condition values support @[field] placeholders resolved against the current record at lookup time (e.g. {\"c\":\"channel\",\"o\":\"eq\",\"v\":\"@[channel]\"} narrows options to rows matching the record's own channel); a condition whose placeholder is unset is dropped rather than matching nothing."
+					"description": "Filter criteria for reference lookups. Condition values support @[field] placeholders resolved against the current record at lookup time (e.g. {\"c\":\"channel\",\"o\":\"eq\",\"v\":\"@[channel]\"} narrows options to rows matching the record's own channel), and @[ref].[field] nav placeholders that read through a Reference column, as a formula does (e.g. @[purchase_order].[supplier_id] on an order line narrows to the order's supplier, also in the New dialog of the order's Lines set). A condition whose placeholder is unset is dropped rather than matching nothing."
 				}
 			},
 			"oneOf": [

package/resources/schemas/manifest.schema.json

@@ -104,8 +104,8 @@
 		},
 		"auditHistory": {
 			"type": "string",
-			"enum": ["none", "minimal", "full"],
-			"description": "Default audit history mode for entities in this module ('full' captures every field change; 'minimal' captures only inserts/deletes; 'none' disables). Individual entities can override."
+			"enum": ["basic", "fields", "full"],
+			"description": "Default audit history level for entities in this module: 'basic' logs each insert/update/delete without field details; 'fields' adds old/new values of changed fields; 'full' also stores display values (reference and user names). Omit to disable. Individual entities can override."
 		},
 		"comments": {
 			"type": "boolean",

package/resources/schemas/traits.schema.json

@@ -56,6 +56,11 @@
 				"formula": { "type": "string" },
 				"orderNum": { "type": "integer" },
 				"description": { "type": "string", "description": "Supports {entity}/{Entity} placeholders" },
+				"labels": {
+					"type": "object",
+					"description": "Translated labels keyed by culture code (e.g. de-DE). Applied to every entity that takes the field from this trait; the module's translations/<locale>.json overrides them per entity. Supports {entity}/{Entity} placeholders.",
+					"additionalProperties": { "type": "string" }
+				},
 				"maxLen": { "type": "integer" },
 				"link": {
 					"type": "object",

package/resources/schemas/translations.schema.json

@@ -0,0 +1,267 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/translations.schema.json",
+	"title": "dForge Translations",
+	"description": "A module's translations/<locale>.json, e.g. de-DE.json. English is the base text authored in the other module files, so an en-* file is not applied at install. Every key is optional: a missing entry falls back to the base text. Labels are required only for the locales the manifest lists in supportedLocales (constraint messages and DSL messages are warned about, never required).",
+	"type": "object",
+	"additionalProperties": false,
+	"properties": {
+		"$schema": {
+			"type": "string"
+		},
+		"entities": {
+			"type": "object",
+			"description": "Entity code → labels for the entity, its fields, card sections and constraint messages.",
+			"additionalProperties": {
+				"$ref": "#/$defs/entity"
+			}
+		},
+		"domains": {
+			"type": "object",
+			"description": "Column domain code (domains.json) → label and option labels, translated once for every column that uses the domain.",
+			"additionalProperties": {
+				"$ref": "#/$defs/withOptions"
+			}
+		},
+		"folders": {
+			"type": "object",
+			"description": "Folder code → label. A sub-folder is keyed by its own flat code, not its path.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"views": {
+			"type": "object",
+			"description": "Data view code → label and description (the subtitle under the view title).",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelDesc"
+			}
+		},
+		"menus": {
+			"type": "object",
+			"description": "Menu code → label and item labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/menu"
+			}
+		},
+		"settings": {
+			"type": "object",
+			"description": "Setting code (settings.json) → label and description.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelDesc"
+			}
+		},
+		"roles": {
+			"type": "object",
+			"description": "Module-qualified role code (e.g. \"crm.admin\") → label.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"reports": {
+			"type": "object",
+			"description": "Report code → label, dataset captions and parameter labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/report"
+			}
+		},
+		"actions": {
+			"type": "object",
+			"description": "Action code (ui/actions.json) → label, tooltip and parameter labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/action"
+			}
+		},
+		"print_templates": {
+			"type": "object",
+			"description": "Print template code → label. Accepted, but not applied at install yet.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"messages": {
+			"type": "object",
+			"description": "Text of a DSL info() / warn() / error() / exit() call, exactly as written in the .dsl file → its translation. {name} placeholders are filled from the call's values and may be reordered. See docs/business-logic/message-localization.md.",
+			"propertyNames": {
+				"minLength": 1
+			},
+			"additionalProperties": {
+				"type": "string",
+				"minLength": 1
+			}
+		}
+	},
+	"$defs": {
+		"label": {
+			"type": "string",
+			"description": "Translated display label."
+		},
+		"labelOnly": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				}
+			}
+		},
+		"labelDesc": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"desc": {
+					"type": "string",
+					"description": "Translated description or tooltip."
+				}
+			}
+		},
+		"option": {
+			"description": "A translated option: the label alone, or the label with an icon and color override.",
+			"oneOf": [
+				{
+					"type": "string"
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"properties": {
+						"label": {
+							"type": "string"
+						},
+						"icon": {
+							"type": "string"
+						},
+						"color": {
+							"type": "string"
+						}
+					}
+				}
+			]
+		},
+		"options": {
+			"type": "object",
+			"description": "Option value (the stored code) → its translation.",
+			"additionalProperties": {
+				"$ref": "#/$defs/option"
+			}
+		},
+		"withOptions": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"options": {
+					"$ref": "#/$defs/options"
+				}
+			}
+		},
+		"entity": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"desc": {
+					"type": "string"
+				},
+				"fields": {
+					"type": "object",
+					"description": "Column code → label and, for dropdown / radio / flags columns, option labels.",
+					"additionalProperties": {
+						"$ref": "#/$defs/withOptions"
+					}
+				},
+				"columnGroups": {
+					"type": "object",
+					"description": "Card-layout section code → heading.",
+					"additionalProperties": {
+						"$ref": "#/$defs/labelOnly"
+					}
+				},
+				"constraints": {
+					"type": "object",
+					"description": "Check / unique constraint name → violation message.",
+					"additionalProperties": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"message": {
+								"type": "string"
+							}
+						}
+					}
+				}
+			}
+		},
+		"menu": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"items": {
+					"type": "object",
+					"description": "Menu item code → label. Flat even when ui/menus.json nests items under children: a group and its children are siblings here.",
+					"additionalProperties": {
+						"$ref": "#/$defs/labelOnly"
+					}
+				}
+			}
+		},
+		"params": {
+			"type": "object",
+			"description": "Parameter code → label and dropdown option labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/withOptions"
+			}
+		},
+		"report": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"datasets": {
+					"type": "object",
+					"description": "Dataset code → caption.",
+					"additionalProperties": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"caption": {
+								"type": "string"
+							}
+						}
+					}
+				},
+				"params": {
+					"$ref": "#/$defs/params"
+				}
+			}
+		},
+		"action": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"desc": {
+					"type": "string",
+					"description": "Translated tooltip."
+				},
+				"params": {
+					"$ref": "#/$defs/params"
+				}
+			}
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/README.md

@@ -60,8 +60,7 @@ correct: a data view describes the presentation, and the folder's entity view de
 what a user in that folder is allowed to see of it. The grid renders whichever
 columns survive the view — you do not maintain one data view per role.
 
-Entity views are also unrelated to the two other things called "view" here: a *data
-view* (`ui/data_views.json`) is a grid/kanban/calendar, and `isView` + `viewSql` on an
-entity means it is backed by a SQL view.
+Entity views are also unrelated to the other thing called "view" here: a *data view*
+(`ui/data_views.json`) is a grid/kanban/calendar.
 
 See `dforge://reference/security` → Column-level security for the full rules.

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

@@ -302,12 +302,19 @@ var queued = select('comm.message', {
 
 | Function | Description |
 |---|---|
-| `error('message')` | **Abort** the action and show an error to the user. Rolls back all changes. |
-| `warn('message')` | Show a warning but continue execution. |
-| `info('message')` | Show an informational message. A **receipt for work the action did** — not a way to publish a computed value; see *When an action is the wrong tool*. |
-| `exit('message'?, 'level'?)` | **Stop the script early without error** — changes made so far are kept. Level `'info'` (default) or `'warn'` styles the message. This is the DSL's early-return: a bare `return` is not valid at the top level of `execute:`. |
+| `error('message', values?)` | **Abort** the action and show an error to the user. Rolls back all changes. |
+| `warn('message', values?, opts?)` | Show a warning but continue execution. |
+| `info('message', values?, opts?)` | Show an informational message. A **receipt for work the action did** — not a way to publish a computed value; see *When an action is the wrong tool*. |
+| `exit('message'?, 'level'?, values?)` | **Stop the script early without error** — changes made so far are kept. Level `'info'` (default), `'warning'`, `'danger'` or `'success'` styles the message. This is the DSL's early-return: a bare `return` is not valid at the top level of `execute:`. |
 | `notify(userId, 'message')` | Send an in-app notification to a specific user. First arg is a user ID (typically `[owner_id]` or similar). |
 
+The message of `error` / `warn` / `info` / `exit` is translatable: it is looked up by its exact English text in the module's `messages` translations (see `dforge://reference/translations`). Put values in `{name}` placeholders filled from `values` — never join them into the string, which leaves no fixed text to translate. `opts` carries record links (`{ links: [...] }`), so `links` is not a placeholder name:
+
+```javascript
+error('Insufficient stock. Available: {available}, requested: {requested}',
+    { available: availableQty, requested: params[quantity] })
+```
+
 ### Email
 
 | Function | Description |

package/skills/dforge-mcp-author/references/data-views.md

@@ -4,7 +4,7 @@ Data views define how users see and interact with entity data. One entity can ha
 
 Lives in: `ui/data_views.json`
 
-> **Not to be confused with entity views.** An *entity view* (`views` on an entity file) is column-level **security** — which columns a folder may see at all — and is what `folders.json`'s `viewName` binds. A *data view* is a presentation of an entity, referenced by a menu's `dataViewCode`. A third thing, `isView` + `viewSql` on an entity, means the entity is backed by a SQL view. See `security.md` → Column-level security.
+> **Not to be confused with entity views.** An *entity view* (`views` on an entity file) is column-level **security** — which columns a folder may see at all — and is what `folders.json`'s `viewName` binds. A *data view* is a presentation of an entity, referenced by a menu's `dataViewCode`. See `security.md` → Column-level security.
 
 ## Structure
 

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

@@ -318,16 +318,17 @@ Each of these is an install-time error, and each is silent at runtime if it slip
 
 `"viewName": "default"` means **no view** (full column set) and declares nothing. It is what every shipped module writes, and what the runtime auto-creates for an entity reached without a folder binding — so it is exempt from the checks above. A module that really declares a view named `default` still gets it bound.
 
-### Don't confuse the three "views"
+### Don't confuse the two "views"
 
 | Term | Where | What it is |
 |---|---|---|
 | **Entity view** | `entities/*.json` → `views` | Column-level security (this section) |
 | **Data view** | `ui/data_views.json` | A grid / kanban / calendar over an entity (`data-views.md`) |
-| **SQL view** | `entities/*.json` → `isView` + `viewSql` | An entity backed by a SQL view instead of a table |
 
 `viewName` in `folders.json` binds the first. Menus' `dataViewCode` references the second.
 
+There is no SQL-view entity. `isView` / `viewSql` are rejected at validate, pack and install: a view entity would duplicate the source entity's metadata, break when that module changes a column, and read around its row and column security. For a read-only slice use a data view (nav paths, `F` columns), a `G` total, the Query Builder, or a stored-procedure report — the last is the one way to show users a slice of an entity they have no rights on, behind an explicit `sp:` grant.
+
 ### When to use subfolders
 
 - **Multi-location modules** (warehouses, offices, branches) — one subfolder per location, filtered by location FK

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

@@ -38,7 +38,7 @@ Translation files mirror the module's content structure. Each translatable objec
         "crm.sales-rep": { "label": "Sales Representative" }
     },
     "views": {
-        "contacts": { "label": "Contacts" },
+        "contacts": { "label": "Contacts", "desc": "People associated with customers" },
         "contacts_list": { "label": "Contact List" },
         "contacts_gallery": { "label": "Contact Cards" }
     },
@@ -80,11 +80,12 @@ Translation files mirror the module's content structure. Each translatable objec
 | `entities` | Entity labels (`label`, `desc`) and all field labels | Entity codes → `{ label, desc, fields: { field_code: { label } } }` |
 | `folders` | Folder labels | Folder codes (root folder key from `ui/folders.json`) |
 | `roles` | Role display labels | Role codes (keys from `security/roles.json`, already module-qualified — e.g. `crm.admin`) → `{ label }` |
-| `views` | Data view labels | View codes (keys from `ui/data_views.json`) |
+| `views` | Data view labels and descriptions (`label`, `desc`) | View codes (keys from `ui/data_views.json`) → `{ label, desc }` |
 | `menus` | Menu node labels (root + nested items) | Menu root key → `{ label, items: { item_code: { label } } }` matching `ui/menus.json` structure |
 | `actions` | Action labels, descriptions, param labels **and param dropdown option labels** | Action codes (keys from `ui/actions.json`) → `{ label, desc, params: { param_cd: { label, options: { value: … } } } }` |
 | `reports` | Report dataset captions, param labels **and param dropdown option labels** | Report codes → `{ datasets: { ds_cd: { caption } }, params: { param_cd: { label, options: { value: … } } } }` |
 | `entities.<e>.constraints` | Check/unique constraint violation messages (opt-in — warned, not enforced) | Constraint codes → `{ message }` under the owning entity |
+| `messages` | DSL `info` / `warn` / `error` / `exit` texts (opt-in — warned, not enforced) | Exact English text → translated text |
 | `entities.<e>.fields.<f>.options` | Dropdown/radio/flags **option labels** (opt-in) | Option `value` → localized label (string) or `{ label, icon, color }` |
 | `domains` | Column domain labels **and** their shared option labels (opt-in) | Domain codes → `{ label, options: { value: … } }` |
 
@@ -174,6 +175,22 @@ A `dropdown` **parameter** carries per-value labels exactly like a column, and t
 - **This requires base labels in the DSL.** `options=bank_transfer,cash` stores bare codes, and the dialog shows `bank_transfer` in *every* locale including English until you write `options=[bank_transfer:Bank transfer, cash:Cash]` (or the JSON object form). See `action-dsl.md`.
 - **Prefer a domain.** If the param's choices are the same list a column uses — which they usually are, since the value normally ends up written to that column — declare the param as `domain <domainCd>` and skip this section entirely: it inherits the domain's translated options. Reach for per-param `options` only when the list belongs to that one parameter and matches no column.
 
+### Action messages ARE translatable (opt-in)
+
+The text an action passes to `info()`, `warn()`, `error()` or `exit()` is the base text **and the key**. Translate it under `messages` in each non-English file, keyed by the exact English text; `{name}` placeholders are filled from the call's second argument (`exit()`: third, after the level) and may be reordered:
+
+```json
+"messages": {
+    "Item processed successfully": "Товар успішно оброблено",
+    "Recount completed: {count} line(s) checked": "Перерахунок завершено: перевірено рядків — {count}"
+}
+```
+
+- Lookup is in the **action's own module** (a bridge module's action uses the bridge's `messages`), in the user's language; a queued action uses the language of the user who queued it, a scheduled job the workspace default. No entry → the English text. Needs platform 1.26.0.
+- A message joined from text and values (`'Bill ' + [bill_number]`) cannot be translated — rewrite it with placeholders.
+- A link label must be data (a record number), not a word: links are placed after translation.
+- **Opt-in, never mandatory.** With `supportedLocales`, install and `dforge_module_validate` warn about untranslated and joined messages; both always warn about `messages` entries no script uses (an English wording change leaves one behind) and about placeholders with no value. `dforge_translation_sync` adds every fixed message text to the non-English files.
+
 ### Roles ARE translated — and completeness is enforced
 
 Role labels are **required and localized** (this changed — older docs said roles were skipped; they are not). `SecurityRegistrar` gives every role a `res_id`, so `TranslationRegistrar` wires the role label exactly like entities/views/menus:
@@ -225,7 +242,7 @@ If you include these sections, the install succeeds (they're silently ignored)
         "crm.sales-rep": { "label": "Vertriebsmitarbeiter" }
     },
     "views": {
-        "contacts": { "label": "Kontakte" }
+        "contacts": { "label": "Kontakte", "desc": "Personen, die mit Kunden verknüpft sind" }
     },
     "menus": {
         "crm_menu": {