@dforge-core/dforge-mcp 0.2.36 → 0.2.38

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.2.38 — 2026-10-12
+
+**A register column's `map` may name a debit and a credit column.** On an accounting (`L`) column,
+a resource the register splits by side maps to `{ "debit": "<line column>", "credit": "<line column>" }`;
+install requires it. `dforge://schema/entity` now allows it (metadata 0.0.39). Before this,
+`gl`, `acc-registry` and any module with a two-sided ledger failed schema validation.
+
+**A registers reference.** `dforge://reference/registers` covers the register kinds (balance, turnover,
+information, accounting classic and compound), `registers.json`, binding a document from its `A` / `L`
+columns, the DSL and report reads, and the common mistakes.
+
+**Demo data is documented.** The conventions reference gains a "Demo data" section: `demo-data/` beside
+`seed-data/`, loaded on request; `$f` formulas, `repeat`, and `vars.json`; the workspace-type gate.
+
+**Three schemas are served.** `dforge://schema/registers`, `card-layouts` and `demo-vars` were vendored or
+new but not registered. `demo-vars` is the schema for `demo-data/vars.json` (metadata 0.0.38).
+
+## 0.2.37 — 2026-10-12
+
+**Author references brought in line with the hand-authoring copy in dForge-core.** Content that
+had only reached one of the two now reaches both:
+
+- **Data views:** a grid view needs a renderable scalar column, from `dataSources[].columns` or
+  from the entity's `V` flags; the `columns` array is authoritative. The old text calling it
+  layout-only was wrong.
+- **Formulas:** the full `NUMBER()` / `BOOLEAN()` rules, where the client and server engines
+  agree, and multi-hop navigation at SQL time with its depth cap.
+- **Security:** don't grant a right on a reference's target just to make its name show up.
+- **Columns and traits:** how the reference picker behaves on a large target; how to show audit
+  columns from a trait; corrected params for the `code`, `tags` and `percent` field types.
+- **Jobs:** `paused` seeds the initial value only; an upgrade never overwrites it.
+- **Flags:** a view column's `notes` row in the example.
+
 ## 0.2.36 — 2026-10-12
 
 **`settings.json` gains `$constraints`**: check constraints across a module's settings, SQL over

package/dist/server.js

@@ -31002,7 +31002,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.28/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.29/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31290,7 +31290,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.35/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.39/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -31530,6 +31530,26 @@ function deriveDbDatatype(fieldTypeCd, options = {}) {
   }
   return base;
 }
+var INFO_PROPERTIES = ["period", "recorder", "recordChangesOnly"];
+var ACCOUNTING_PROPERTIES = [
+  "chart",
+  "composition",
+  "analyticFields",
+  "lineMode",
+  "account",
+  "debitAccount",
+  "creditAccount",
+  "debitAnalyticFields",
+  "creditAnalyticFields",
+  "sideDimensions"
+];
+var BALANCE_PROPERTIES = ["allowNegative", "autoCreate"];
+var REFUSED = {
+  balance: [...INFO_PROPERTIES, ...ACCOUNTING_PROPERTIES],
+  turnover: ["entity", ...INFO_PROPERTIES, ...ACCOUNTING_PROPERTIES, ...BALANCE_PROPERTIES],
+  info: ["journal", "journalDirection", "journalDate", ...ACCOUNTING_PROPERTIES, "totals", ...BALANCE_PROPERTIES],
+  accounting: ["entity", ...INFO_PROPERTIES, "journalDirection", ...BALANCE_PROPERTIES]
+};
 
 // src/tools/_helpers.ts
 function modulePaths(moduleDir) {
@@ -34602,7 +34622,7 @@ var path10 = __toESM(require("path"));
 var fs7 = __toESM(require("fs"));
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.35/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.39/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -35529,9 +35549,9 @@ var BUILTINS = [
   },
   // Utilities
   { name: "now", signature: "now()", returns: "datetime", doc: "Current date/time. Lowercase \u2014 this is the execute-block date function." },
-  { name: "addDays", signature: "addDays(date, n)", returns: "date", doc: "Add `n` days to a date." },
-  { name: "addMinutes", signature: "addMinutes(date, n)", returns: "datetime", doc: "Add `n` minutes." },
-  { name: "addSeconds", signature: "addSeconds(date, n)", returns: "datetime", doc: "Add `n` seconds." },
+  { name: "addDays", signature: "addDays(date, n)", returns: "date | string", doc: "Add `n` days. Takes a date field, a `Date` or an ISO string; a date field stays a date and a `yyyy-MM-dd` string stays a string. Null stays null; any other value is an error." },
+  { name: "addMinutes", signature: "addMinutes(date, n)", returns: "datetime", doc: "Add `n` minutes. Takes a date field, a `Date` or an ISO string; the result is a timestamp. Null stays null; any other value is an error." },
+  { name: "addSeconds", signature: "addSeconds(date, n)", returns: "datetime", doc: "Add `n` seconds. Takes a date field, a `Date` or an ISO string; the result is a timestamp. Null stays null; any other value is an error." },
   { name: "currentUserId", signature: "currentUserId()", returns: "long", doc: "The acting user's tenant user ID." },
   { name: "flush", signature: "flush()", returns: "void", doc: "Flush pending writes so a following read sees them." },
   { name: "tryParseJson", signature: "tryParseJson(value)", returns: "any | null", doc: "Parse JSON, returning `null` on failure instead of throwing." },
@@ -38871,6 +38891,21 @@ var resources = [
     "Stored procedures JSON schema",
     "JSON Schema for logic/stored_procedures.json \u2014 map of stored-procedure code \u2192 { functionName, schemaName?, params?, columns? }. Required for any report dataset with datasetType 'S': the .sql file under logic/reports/ creates the function, this file registers it as the spCd a dataset binds and the sec_object an sp: right is granted on. functionName names the FUNCTION, never the script."
   ),
+  schema(
+    "registers",
+    "Registers JSON schema",
+    "JSON Schema for registers.json at the module root \u2014 map of register code \u2192 { kind (balance | turnover | info | accounting), dimensions, resources, journal/entity, totals, ... }. Documents bind to a register from their A / L columns instead of restating it."
+  ),
+  schema(
+    "card-layouts",
+    "Card layouts JSON schema",
+    "JSON Schema for ui/card_layouts.json \u2014 layout name \u2192 sections (columnGroup, set, tabGroup). Master/detail is a card layout with a tabGroup of set tabs, not a view type."
+  ),
+  schema(
+    "demo-vars",
+    "Demo data variables JSON schema",
+    'JSON Schema for demo-data/vars.json \u2014 a flat map of variable name \u2192 literal or { "$f": formula }. Demo-data formulas read them as @name.'
+  ),
   {
     uri: "dforge://docs/conventions",
     name: "dForge module conventions",
@@ -38914,6 +38949,7 @@ var resources = [
     mimeType: "text/x-python",
     read: () => readSkill("scripts/xlsx_to_model.py")
   },
+  reference("registers", "Registers: accumulation (balance / turnover / info) and accounting (classic / compound) registers, registers.json, binding a document from its A / L columns (map, per-side debit/credit objects), and the reads. Load before authoring registers.json or an A / L column."),
   reference("data-migration", "Migrating data from a legacy database."),
   reference("manifest", "manifest.json shape: moduleId UUID, semver, entities map, locale-keyed translations, security block."),
   reference("validation-checklist", "Final pre-pack self-review checklist covering every file type."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "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",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@dforge-core/dforge-cli": "^0.2.29",
-    "@dforge-core/metadata": "^0.0.37",
+    "@dforge-core/metadata": "^0.0.39",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },

package/resources/schemas/demo-vars.schema.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/demo_vars.schema.json",
+	"title": "dForge Demo Data Variables",
+	"description": "demo-data/vars.json: the variables demo-data formulas read as @name. A flat map of variable name to value. It is not a data file; the loader skips it, and each module has its own (nothing is shared between modules).",
+	"type": "object",
+	"propertyNames": {
+		"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+		"description": "A letter or underscore, then letters, digits or underscores. Names are case-insensitive, and a repeat variable of the same name shadows the file's."
+	},
+	"additionalProperties": {
+		"description": "A plain value (string, number, boolean or null) is substituted as a literal. { \"$f\": \"...\" } is a formula expanded where the variable is used, e.g. { \"$f\": \"DATEADD(TODAY(), -30, 'DAY')\" }; it may read other variables with @name (a cycle fails the install) but not [column] values.",
+		"oneOf": [
+			{ "type": ["string", "number", "boolean", "null"] },
+			{
+				"type": "object",
+				"required": ["$f"],
+				"properties": {
+					"$f": {
+						"type": "string",
+						"description": "Formula whose result is the variable's value"
+					}
+				},
+				"additionalProperties": false
+			}
+		]
+	}
+}

package/resources/schemas/deps.schema.json

@@ -18,12 +18,24 @@
 		},
 		"entities": {
 			"type": "object",
-			"description": "Consumed provider entities, keyed by entity code (e.g. 'party'). At least one, except against a system module (admin, metadata, workspace, sys-billing), where {} declares a pure platform-version gate for a feature that introduced no entity.",
+			"description": "Consumed provider entities, keyed by entity code (e.g. 'party'). At least one, except against a system module (admin, metadata, workspace, sys-billing), where {} declares a pure platform-version gate for a feature that introduced no entity, or when 'functions' imports at least one function.",
 			"additionalProperties": { "$ref": "#/definitions/entityContract" }
+		},
+		"functions": {
+			"type": "array",
+			"description": "The provider's DSL library functions (logic/functions/*.dsl) the consumer's actions call, as <provider code with '-' replaced by '_'>.<name>(...). Only listed names are reachable, and install checks the installed provider declares each. See docs/business-logic/dsl-functions.md.",
+			"items": { "type": "string", "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$" },
+			"uniqueItems": true,
+			"minItems": 1
 		}
 	},
 	"if": {
-		"not": { "properties": { "module": { "enum": ["admin", "metadata", "workspace", "sys-billing"] } }, "required": ["module"] }
+		"not": {
+			"anyOf": [
+				{ "properties": { "module": { "enum": ["admin", "metadata", "workspace", "sys-billing"] } }, "required": ["module"] },
+				{ "required": ["functions"] }
+			]
+		}
 	},
 	"then": {
 		"properties": { "entities": { "minProperties": 1 } }

package/resources/schemas/entity.schema.json

@@ -259,7 +259,7 @@
 				"lineField": { "type": "string", "description": "The line's foreign-key column(s) to the header, comma-separated in the header's key order for a composite key." },
 				"stateField": { "type": "string", "description": "The bool column that records the posted state, when it is not the registry column itself. Written only by the register engine." },
 				"register": { "type": "string", "description": "The register this column posts to, as 'module_cd.register_cd' (declared in that module's registers.json). Binding to one replaces restating what the register is: the declaration supplies the state entity, dimensions, resources, journal, allowNegative and autoCreate, and this column keeps only what legitimately differs per writer — direction/sign, 'map' and 'dateField'." },
-				"map": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this document's column carrying it. Every resource the register declares must be mapped (install refuses otherwise); a dimension left out binds to a column of the same name. Only meaningful with 'register'. On an accumulation (A) column a value may be a one-hop reference path, '<reference column>.<target column>', read through the reference at posting time (off the line when the binding posts from lines), or an expression: a string starting with '=' holding an F-column formula over the same row with one-hop reference reads — \"=COALESCE([transit_warehouse_id], [dest_warehouse_id])\"." },
+				"map": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "required": ["debit", "credit"], "additionalProperties": false, "properties": { "debit": { "type": "string" }, "credit": { "type": "string" } } } ] }, "description": "Register dimension or resource name -> this document's column carrying it. On an accounting (L) column a resource or dimension the register splits by side maps to { \"debit\": \"<line column>\", \"credit\": \"<line column>\" } instead of one column. Every resource the register declares must be mapped (install refuses otherwise); a dimension left out binds to a column of the same name. Only meaningful with 'register'. On an accumulation (A) column a value may be a one-hop reference path, '<reference column>.<target column>', read through the reference at posting time (off the line when the binding posts from lines), or an expression: a string starting with '=' holding an F-column formula over the same row with one-hop reference reads — \"=COALESCE([transit_warehouse_id], [dest_warehouse_id])\"." },
 				"headerMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this DOCUMENT's column carrying it, for a binding that posts from LINES. A line binding reads every other value off the line, and a dimension that belongs to the document (a dealer, an organisation, a date) cannot be put on the line: a G column is a same-row expression or an aggregate over a child set, so it cannot read a parent. Explicit rather than a fallback, because 'not on the line, try the header' turns a typo into a silent read of an unrelated header column with the same name. Install refuses: a name on neither table, a field also named in 'map', a column also read off the line by 'map', a column that is part of the line's key, a column 'lockedFields' does not freeze (the posting is keyed by it, so it has to hold still while the document is posted), and a RESOURCE unless the register is 'info' (a quantity from the document would be added once per line; an information register's records replace rather than add). A value may be a one-hop reference path off the document, whose reference key column 'lockedFields' must then freeze, or an expression over the document ('=...', see 'map')." },
 				"groupLinesBy": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true, "description": "Line columns whose distinct values each post ONE movement, instead of one per line — a production report posting 'this unit worked today' once per unit with a count of 1. 'map' is then read over a group row: the grouped line columns, every column of the document, and one-hop reads through a reference of either, so an expression may mix the document and the group key. A quoted constant is stamped once per group; a numeric line column mapped to a resource is summed over the group. Install refuses: a binding that posts from the document, an L column, a grouped column the line does not store or 'lockedLineFields' does not freeze, a line column read that is neither grouped nor a summed resource, a non-numeric summed resource, a column both grouped and summed, an ungrouped line resource on an 'info' register, a name both the line and the document carry, and a document column read that 'lockedFields' does not freeze. Accumulation (A) columns only." },
 				"dateField": { "type": "string", "description": "This document's date column, supplying the date the register stamps on each journal row. Required once the register declares a 'journalDate' — one writer that supplied none would make every balance read as of a date quietly short, across all writers. On an accumulation (A) column it may be a one-hop reference path, '<reference column>.<target column>', or an expression over the document ('=...', see 'map')." },

package/resources/schemas/settings.schema.json

@@ -4,10 +4,41 @@
 	"title": "dForge Module Settings",
 	"description": "Module-level settings definitions: a flat map of setting code → setting definition. Settings are folder-scoped at runtime (values inherit through the folder tree) and surface in the Module Settings UI.",
 	"type": "object",
+	"propertyNames": {
+		"pattern": "^(\\$constraints|[^$].*)$",
+		"description": "A setting code cannot start with '$'; $constraints is the only reserved key."
+	},
+	"properties": {
+		"$constraints": {
+			"type": "object",
+			"description": "Checks across this module's settings, keyed by constraint name. The settings are the columns of one virtual row, so each is an entity check constraint: SQL over setting codes. settings.set and settings.setMany run every rule naming a written setting, at the folder written and at each folder below it that overrides a setting the rule names; install refuses defaults that fail one. NULL passes, as in a CHECK.",
+			"additionalProperties": {
+				"$ref": "#/$defs/constraint"
+			}
+		}
+	},
 	"additionalProperties": {
 		"$ref": "#/$defs/setting"
 	},
 	"$defs": {
+		"constraint": {
+			"type": "object",
+			"required": ["type", "expression"],
+			"additionalProperties": false,
+			"properties": {
+				"type": {
+					"const": "check"
+				},
+				"expression": {
+					"type": "string",
+					"description": "Boolean over this module's settings in SQL CHECK syntax, e.g. \"default_discount_pct <= max_discount_pct\": comparisons, IS [NOT] NULL, [NOT] IN, [NOT] BETWEEN, regex matches (~ ~* !~ !~*) against a string literal, AND/OR/NOT, + - * /, literals and setting codes (bare or \"quoted\"). No functions, casts or [field] brackets; IS NULL rather than = null. The settings it names are found in it: writing any of them re-checks the rule."
+				},
+				"message": {
+					"type": "string",
+					"description": "Violation message. Localizable via translations/<locale>.json under settings.$constraints.<name>.message."
+				}
+			}
+		},
 		"setting": {
 			"type": "object",
 			"properties": {

package/resources/schemas/translations.schema.json

@@ -46,7 +46,19 @@
 		},
 		"settings": {
 			"type": "object",
-			"description": "Setting code (settings.json) → label and description.",
+			"description": "Setting code (settings.json) → label and description; $constraints → constraint name → message.",
+			"properties": {
+				"$constraints": {
+					"type": "object",
+					"additionalProperties": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"message": { "type": "string" }
+						}
+					}
+				}
+			},
 			"additionalProperties": {
 				"$ref": "#/$defs/labelDesc"
 			}

package/skills/dforge-mcp-author/SKILL.md

@@ -145,7 +145,7 @@ Load these by URI, one per step, at the step that needs them.
 **Per-element references** — `dforge://reference/<name>`:
 `field-types`, `flags`, `column-types`, `column-domains`, `formulas`, `traits`,
 `data-views`, `menus`, `action-dsl`, `filters`, `security`, `reports`,
-`settings`, `jobs`, `number-sequences`, `document-extraction`,
+`settings`, `jobs`, `number-sequences`, `registers`, `document-extraction`,
 `print-templates`, `translations`, `queries`, `schema-import`, `excel-import`,
 `data-migration`, `manifest`, `validation-checklist`, `conventions`.
 

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

@@ -101,6 +101,17 @@ A reference entry may declare `onDelete` and/or `onUpdate` to emit an `ON DELETE
 
 **Why two columns?** The FK stores the actual value. The Reference column configures how the value is rendered in the UI (as a typeahead picker showing the target's `toString`). They must be kept in sync — column order in JSON doesn't matter but `orderNum` determines UI ordering.
 
+### How the picker behaves on a large target
+
+Opening the picker loads the **first 200 rows** of the target entity — enough to browse, cheap on a table of any size. Typing does *not* filter those 200 rows: the query goes to the server as a case-insensitive match over the columns named in the target's `toString`, so a target with 200 000 rows is as pickable as one with 20. Every whitespace-separated term must match at least one of those columns, which is what lets a `toString` of `"{first_name} {last_name}"` answer "John Smith".
+
+Two consequences for the entity you point at:
+
+- **Put the columns people search by in `toString`.** They are the only ones the picker searches. A target whose `toString` is `"{code}"` cannot be found by name, however prominent the name column is elsewhere.
+- **A `toString` built only from formula columns can't be searched server-side.** Neither formula nor set columns translate to a `WHERE` clause, so the picker falls back to narrowing the 200 rows it already loaded — rows past that point stay unreachable. Name at least one stored column in the template.
+
+`refFilter` and folder row filters still apply: they are AND-ed onto the search, so a filtered-out row does not surface just because the user typed its name.
+
 ## Set columns (`columnType: "S"`)
 
 Virtual 1:N backwards reference. Shows a grid of related records on the parent's detail view.

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

@@ -112,6 +112,21 @@ 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.).
 
+## 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.
+
+- **Same file shape as seed data** (`entityCode` + `records`, numbered prefixes for FK order, explicit primary keys), and the same schema.
+- **Loaded on request:** `dforge-cli module install … --with-demo-data`, the "Install demo data" checkbox in the install dialogs, or `dforge-cli data demo add` on an installed module. A module's dependencies' demo data loads first. Rows already there are left alone, so repeating is safe.
+- **Workspace type gates it:** a `production` workspace refuses demo data; `staging` or an unset type needs confirmation (`--yes`).
+- **A value can be a formula**, evaluated once at insert: `{ "$f": "DATEADD(TODAY(), -80, 'DAY')" }`. `[column]` reads another column of the same row, and `@name` reads a variable. `TODAY()`, `DATEADD`, `YEAR`, `FORMAT` and `CONCAT` exist. Relative dates keep a scenario intact whatever the install date.
+- **`repeat`** builds several rows from one template, with `@m` in formulas.
+- **`demo-data/vars.json`** declares the variables: a flat `{ "name": value }` map, where a value is a literal or `{ "$f": "formula" }` and may read other variables. It is not a data file; the loader skips it, and each module has its own.
+- **References by text:** a reference column may name its target by its `toString` text instead of a numeric key; no match, or two, is an error.
+- **Not re-evaluated:** a formula runs at insert; an upgrade never recomputes it.
+
+Depth: the platform changelog entry "Demo data: its own folder, formulas, and a checkbox at install".
+
 ## 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).

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

@@ -60,26 +60,58 @@ Lives in: `ui/data_views.json`
 }
 ```
 
-## Critical rule — the entity needs a visible column
+## Critical rule — the view needs something to draw
 
-A grid-style view can only render an entity that has at least one **visible scalar column** — a field whose `flags` include `V` and whose `columnType` is **not** a set (`S`). Column visibility is entity-driven (the field's flags), **not** view-driven: the `columns` array inside `dataSources[]` is layout-only (reorder/pin/width among already-visible fields) — it can't make a non-`V` field appear.
+A grid-style view resolves its columns one of two ways, and **one of them has to produce a renderable scalar column** — anything that isn't a set (`columnType: "S"`, a 1:N collection with no per-row value):
 
-If none of an entity's fields are visible (or only its set/child-collection columns are), the view renders the runtime empty state *"No visible columns configured for this entity."* — a broken screen the user only hits when they open the menu item. `dforge_module_validate` and `dforge_module_pack` now **reject** this before install.
+1. **The source names its own columns.** `dataSources[].columns` wins outright — see [the section below](#the-columns-array-is-authoritative). Flags don't enter into it, so this route works even when every field on the entity is internal.
+2. **It doesn't, and the entity's `V` flags decide.** With no `columns` array the view falls back to the entity's **visible scalar columns** — fields whose `flags` include `V` and whose `columnType` isn't `S`.
+
+With neither, the view renders the runtime empty state *"No visible columns configured for this entity."* — a broken screen the user only hits when they open the menu item. `dforge_module_validate` / `dforge_module_pack` **reject** that before install.
 
 ```jsonc
-// WRONG — grid over an entity whose fields are all hidden (no "V")
+// WRONG — grid falls back to flags, and no field has "V"
 "fields": {
-    "code": { "fieldTypeCd": "text", "flags": "EM" },   // E=editable, M=required, but no V
-    "lines": { "columnType": "S", "flags": "VE" }        // visible, but a SET — doesn't count for a grid
+    "code": { "fieldTypeCd": "text", "flags": "EM" },   // E=editable, M=… but no V
+    "lines": { "columnType": "S", "flags": "VEM" }        // visible, but a SET — doesn't count for a grid
 }
-// RIGHT — at least one visible scalar field
+// RIGHT (route 2) — at least one visible scalar field
 "fields": {
     "code": { "fieldTypeCd": "text", "flags": "VEM" }     // V present, not a set → satisfies the grid
 }
+// ALSO RIGHT (route 1) — the entity's fields stay internal, the view says what it shows
+"dataSources": [
+    { "entityCode": "audit_log", "columns": ["created_date", "created_by_user"] }
+]
 ```
 
+Practical guidance: reach for route 2. Flags are what every other surface reads — the card, the Fields popover, quick-add — so an entity whose real business fields are invisible is usually a mistake, even when one view papers over it. Route 1 is for columns that are *deliberately* internal, audit columns above all.
+
 This applies to every column-rendering view type (grid, list, kanban, calendar, gallery, tree-grid, master-detail, and the default). The column-agnostic types — `diagram`, `matrix`, `library` — draw from `viewConfig`/relationships instead, so they're **exempt** from this rule.
 
+## The `columns` array is authoritative
+
+A column you name in `dataSources[].columns` renders **even if its flags omit `V`**. The list is your statement of what this view shows, so it wins over the entity's default visibility — that's how the internal (`flags: "I"`) columns the `audit` / `audit-full` traits contribute get onto a grid:
+
+```jsonc
+{
+    "entityCode": "trip",
+    "columns": ["trip_number", "status", "created_by_user"]   // renders Created By, read-only
+}
+```
+
+A promoted column stays **read-only** unless its flags also carry `E`, and it shows up in the Fields popover like any other column.
+
+What `columns` can't do — each fails `dforge_module_validate` / `dforge_module_pack`, instead of dropping silently:
+
+| Entry | Why it's rejected |
+|-------|-------------------|
+| A code the entity doesn't define | Nothing to render — usually a typo (`avatar` for `avatar_image`) |
+| A set column (`columnType: "S"`) | A 1:N collection has no per-row value for a column |
+| A nav path (`account.company_name`) | The list takes plain column codes — add a Reference (`R`) or Formula (`F`) column to the entity and list that |
+
+The `matrix` / `diagram` / `library` types are exempt here too: their `columns` entry feeds axes and config, not a header row.
+
 See [flags.md](flags.md) for the flag string, [column-types.md](column-types.md) for `columnType` (`R`/`S`/`F`).
 
 ## View types

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

@@ -24,10 +24,10 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `textarea` | `string` | Multi-line plain text. | `text` | `defaultLines`, `maxLines` |
 | `markdown` | `string` | Markdown editor (Write/Preview tabs), rendered sanitized. | `text` | — |
 | `richtext` | `string` | Rich text WYSIWYG editor, stores sanitized HTML. | `text` | — |
-| `code` | `string` | Code editor with syntax highlighting. | `text` | `language` |
+| `code` | `string` | Code editor (CodeMirror, dForge DSL grammar). | `text` | `defaultLines` |
 | `dropdown` | `string` | Fixed list of options. | `varchar` | `options: ["a","b",…]` or `[{value,label,icon,color}]` |
 | `flags` | `string` | Multiple checkboxes with letter flags. | `varchar` | `optionSets`, `style: "buttons"` |
-| `tags` | `string` | Free-form tag list. | `varchar` or `text` | — |
+| `tags` | `string` | Free-form comma-separated tag list. | `varchar` or `text` | `options` (optional suggestions) |
 | `color` | `string` | Color picker. | `varchar(20)` | — |
 | `hidden` | `string` | Internal, never shown in UI. | `varchar` | — |
 
@@ -37,7 +37,7 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 |---|---|---|---|---|
 | `number` | `number` | Numeric value. | `int`, `bigint`, `numeric` | `min`, `max`, `scale` |
 | `currency` | `number` | Monetary value. Precision 2. | `numeric(18,2)` | `currency: "USD"`, `min`, `max` |
-| `percent` | `number` | Percentage 0–100. Precision 2. | `numeric(5,2)` | `min`, `max` (default 0–100) |
+| `percent` | `number` | Percentage. Precision 2. | `numeric(5,2)` | `min`, `max` |
 
 ## Boolean-backed
 
@@ -72,7 +72,7 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `user` | `cuid` | `D` | User picker. Writes a user ID directly, no paired FK needed. |
 | `grid` | `set` | `S` | Detail grid of related records (1:N backwards reference). Used with `link` declaring the relation. |
 | `list` | `set` | `S` | Detail list — same 1:N set as `grid`, rendered as a card list instead of a table. |
-| `entitylink` | `json` | `D` | Polymorphic link to any entity — stores the **resolved entity id** plus the record's PK (as strings) and a display caption. Populate from action DSL with the `entityLink('entityCd', record, description?)` built-in; pass a qualified entity code (see `action-dsl.md`). |
+| `entitylink` | `json` | `D` | Polymorphic link to any entity. Stores `{entityId, entity, pk: {col: "val"}, description?}` — `pk` is a per-column map (values as strings), there is no `id` key. Populate from action DSL with the `entityLink('entityCd', record, description?)` built-in; pass a qualified entity code (see `action-dsl.md`). |
 
 ## JSON
 

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

@@ -57,7 +57,8 @@ Because a view writes no DDL, the requiredness `M` produces there is runtime-onl
       "party_id": {},
       "party_name": { "flags": "V" },
       "vat_no":     { "flags": "VEM" },
-      "salary":     { "flags": "" }
+      "salary":     { "flags": "" },
+      "notes":      { "flags": "VE", "isNullable": true }
     }
   }
 }

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

@@ -129,8 +129,12 @@ The whole date family evaluates identically **client-side and SQL-time** (report
 ### Conversion and context functions
 
 - `TEXT(v)` — as text (null becomes `''`)
-- `NUMBER(v)` — as a number, or null when the value isn't numeric (including a blank string)
-- `BOOLEAN(v)` — null, `''` and `0` are false; everything else is true
+- `NUMBER(v)` — as a number, or null when the text isn't one. "Is a number" means an optional
+  sign, digits and an optional fraction/exponent — a blank string, `'0x10'` and `'Infinity'`
+  are all null, because SQL would reject them too
+- `BOOLEAN(v)` — null is false; a number is false only at **zero**; text is false only when
+  **empty**; anything else is true. Note that text and numbers differ: the string `'0'` is
+  true (it isn't empty) while the number `0` is false
 - `JSON_GET(json, 'key' [, type])` — read a key out of a JSON column. The optional type is a
   string literal: `'text'` (default), `'number'`/`'numeric'`, `'int'`/`'integer'`/`'bigint'`,
   `'bool'`/`'boolean'`, `'date'`, `'datetime'`/`'timestamp'`/`'timestamptz'`
@@ -143,21 +147,44 @@ report selects it, or when it is used in a filter or sort. **Every function list
 implemented in both**, so a column reads the same in a grid and in a report; a test executes
 each one against PostgreSQL and diffs the result against the client runtime.
 
-Two deliberate points of agreement, because the engines disagree by nature:
+Four deliberate points of agreement, because the engines disagree by nature:
 
-- **Out-of-domain math is null, not an error.** `SQRT(-1)`, `LOG(0)`, `ASIN(2)`, `EXP(1000)`,
-  `POW(0, -1)`, `MOD(x, 0)` — JavaScript would answer NaN or Infinity and PostgreSQL would
-  raise (failing the whole report). Both return null, so the cell renders blank.
+- **Comparison is null-safe and two-valued.** `null = null` is true and `[x] != null` is true
+  for any non-null `x` — there is no SQL "unknown" third answer that an enclosing `IF`/`AND`
+  would then read as false. `IF([completed_date] != null AND …, 100, 0)` therefore scores the
+  same in a grid and in a report. (At SQL time `=`/`!=` become `IS NOT DISTINCT FROM` /
+  `IS DISTINCT FROM`.) `ISNULL([x])` remains the clearer spelling of an explicit null check.
+
+- **Out-of-domain math is null, not an error.** `SQRT(-1)`, `LOG(0)`, `ASIN(2)`, `ATANH(1)`,
+  `EXP(1000)`, `POW(0, -1)`, `POW(-8, 0.5)`, `POW(10, 1000)`, `MOD(x, 0)` — JavaScript would
+  answer NaN or Infinity and PostgreSQL would raise (failing the whole report). Both return
+  null, so the cell renders blank. A result too *small* to represent is the one exception:
+  `POW(10, -1000)` is **0** on both sides, because zero is the answer, not "no answer".
 - **String indexing is JavaScript-flavoured, not SQL's.** `SUBSTRING(s, start, end)` and
   `MID(s, start, len)` take a **0-based** start, and `SUBSTRING`'s third argument is an **end
-  offset**, not a length. `INDEX_OF` / `LAST_INDEX_OF` return a 0-based index, or `-1`.
-
-Known remaining difference: `CONCAT` on a numeric column renders PostgreSQL's declared scale
-(`-3.0`) where the client renders the JavaScript number (`-3`). Use `FORMAT`/`TEXT` when the
-exact rendering matters.
-
-`CURRENT_USER_ID()` needs the requesting user, so it resolves in grids, reports, filters and
-`select()`, but not in a context with no user (an unattended job).
+  offset**, not a length. A negative offset clamps to 0, and reversed bounds **swap** —
+  `SUBSTRING(s, 4, 1)` is the same as `SUBSTRING(s, 1, 4)`. `INDEX_OF` / `LAST_INDEX_OF`
+  return a 0-based index, or `-1`.
+- **Comparison never invents a number.** `[a] = [b]` reads both sides as numbers only when
+  both genuinely are (a number, or text SQL would also accept as one). A blank string is not
+  zero, so `NULLIF([note], '')` leaves a note of `'0'` alone, and `[qty] = ''` is false. The
+  same comparator backs `=`, `!=`, `<`, `>`, `<=`, `>=` and `BETWEEN`, so they can't disagree
+  with each other.
+
+Three known remaining differences:
+
+- `CONCAT` on a numeric column renders PostgreSQL's declared scale (`-3.0`) where the client
+  renders the JavaScript number (`-3`). Use `FORMAT`/`TEXT` when the exact rendering matters.
+- `MIN`/`MAX` are **number** functions. Handed a non-numeric argument the client silently
+  drops it, while a report raises on the type mismatch. Wrap the argument in `NUMBER()` if a
+  column might not be numeric.
+- `NUMBER('1e309')` is null client-side — the magnitude exceeds what a JavaScript number can
+  hold, and every non-finite result in the client is null. PostgreSQL's `numeric` has a far
+  wider range, so a report keeps the value.
+
+`CURRENT_USER_ID()` needs the requesting user. It resolves in grids, cards, reports, filters,
+sorts and `select()` — anywhere a request has one — but not in a context with no user, such as
+a scheduled job.
 
 ### Unknown functions
 

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

@@ -37,7 +37,7 @@ Lives in: `logic/jobs.json` at the module root. Schema: [`docs/schemas/jobs.sche
 | `timeZone`       | No       | tenant tz    | IANA name. Falls back to `auth.tenant.time_zone`.                                                                                    |
 | `params`         | No       | `{}`         | Static parameters passed to the action as `__params`. Manifest-fixed — an admin cannot change them. For tenant-configurable values use module settings, resolved from the job's folder (below).       |
 | `enabled`        | No       | `true`       | `false` fully disables — no scheduler, no manual trigger.                                                                            |
-| `paused`         | No       | `false`      | Soft pause. Scheduler skips, but "Run now" still works.                                                                              |
+| `paused`         | No       | `false`      | Soft pause. Scheduler skips, but "Run now" still works. Seeds the initial value only — upgrades never overwrite it.                   |
 | `description`    | No       |              | Human-readable description.                                                                                                          |
 
 **Hard cap: 50 jobs per module.**
@@ -152,7 +152,7 @@ Full source: [`modules/chore/`](../../../modules/chore/).
 - **Sub-minute cron.** The scheduler ticks every 60 s. Anything finer is dishonest — declare a minute cron.
 - **Renaming `code` between versions.** Treats it as a new job and leaves the old `scheduled_job` row orphaned until uninstall (actually reaped on upgrade — but you lose `job_run` history). Keep `code` stable.
 - **"Schedule this 5 minutes from now" pattern.** There is no per-call `schedule()`. Use a cron-scan job that watches a queue table — see [memory: cron-scan pattern](../../../docs/business-logic/jobs.md#when-to-use-a-job-vs-a-trigger).
-- **Confusing `enabled` and `paused`.** `enabled: false` → "Run now" no-ops. `paused: true` → cron skips but "Run now" works. Use `paused` for incident response; use `enabled: false` when you mean "turn this off entirely".
+- **Confusing `enabled` and `paused`.** `enabled: false` → "Run now" no-ops. `paused: true` → cron skips but "Run now" works. Use `paused` for incident response; use `enabled: false` when you mean "turn this off entirely". Only `enabled` is rewritten on upgrade — `paused` is operator state, so shipping `paused: true` in a new version does nothing to tenants that already have the job.
 
 ## Reference
 

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

@@ -0,0 +1,274 @@
+# Registers Reference
+
+A **register** is a declared store of movements or values that documents write to by posting, and that the platform reads back with fixed primitives. Declare it once in `registers.json`; documents bind to it from an `A` or `L` column.
+
+Lives in: `registers.json` at the module root (a keyed dictionary, like `logic/jobs.json`). Schema: [`docs/schemas/registers.schema.json`](../../../docs/schemas/registers.schema.json); binding params: `registryColumnParams` in [`docs/schemas/entity.schema.json`](../../../docs/schemas/entity.schema.json). Full guide: [`docs/business-logic/registers.md`](../../../docs/business-logic/registers.md). Check with `dforge_module_validate`, then `dforge_module_pack` and `dforge_module_install`.
+
+## Register or plain table?
+
+| You need | Use |
+|---|---|
+| Running quantity or amount per key, with undo on unpost | `balance` register |
+| "How much moved in a period", no running total | `turnover` register |
+| A value that changes over time, or a keyed lookup, with "value as of a date" | `info` register |
+| Double-entry postings by account, with analytics | `accounting` register |
+| Ordinary master or transactional data nobody aggregates by key | Plain entity |
+| An ad hoc slice by an optional attribute | A report, not a dimension |
+
+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.
+
+## The kinds
+
+| `kind` | Keeps | Written by | Read by | Key rules |
+|---|---|---|---|---|
+| `balance` | State row per dimension tuple, plus optional journal | `A` column | `getBalance`, `getTurnover` | Needs `entity`. Set `journal`, `journalDirection`, `journalDate` from the start. `allowNegative` default `false`, `autoCreate` default `true`. |
+| `turnover` | Journal only | `A` column | `getTurnover` | No `entity`, no `allowNegative`/`autoCreate`. `journal`, `journalDirection`, `journalDate` mandatory. `getBalance` refuses it. |
+| `info` | One table of records | `data.set` (independent) or `A` column (subordinate, has `recorder`) | `getSlice` | Needs `entity`, no `journal`. Optional `period`. Independent: unique constraint over dimensions + `period`. Binding needs a `recorder`. |
+| `accounting`, `classic` | Postings, one account per row | `L` column | `getAccountBalance`, `getAccountTurnover`, dataset `R` | `chart`, `account`, `analyticFields`, `composition`. Every resource split `debitField`/`creditField`. No correspondence. |
+| `accounting`, `compound` | Postings, debit and credit account on one row | `L` column | Same, plus `getCorrespondence` | `debitAccount` != `creditAccount`, per-side analytic arrays, optional `sideDimensions`. Resource shared (`field`) or split. Balance check refused. |
+
+Every register needs `dimensions` (1-8 columns) and `resources` (1-64). A resource is `required` by default; set `"required": false` when only some writers supply it. A property a kind refuses fails install; it is never ignored.
+
+## `registers.json`
+
+Register codes: lowercase letters, digits, underscores. A document addresses one as `module_cd.register_cd`. `label` gives it a translatable name.
+
+### Balance (`wms-registry.stock`)
+
+```json
+{
+    "stock": {
+        "kind": "balance",
+        "label": "Stock on Hand",
+        "entity": "stock",
+        "journal": "stock_movement",
+        "journalDirection": "movement_direction",
+        "journalDate": "movement_date",
+        "dimensions": ["warehouse_id", "product_id"],
+        "resources": { "quantity": { "field": "quantity" } },
+        "allowNegative": false,
+        "autoCreate": true
+    }
+}
+```
+
+### Turnover (`wms-registry.product_flow`)
+
+```json
+{
+    "product_flow": {
+        "kind": "turnover",
+        "journal": "product_flow",
+        "journalDirection": "flow_direction",
+        "journalDate": "flow_date",
+        "dimensions": ["warehouse_id", "product_id"],
+        "resources": {
+            "received": { "field": "received", "required": false },
+            "shipped": { "field": "shipped", "required": false }
+        }
+    }
+}
+```
+
+### Info (`wms-registry.outlet_price`, subordinate)
+
+```json
+{
+    "outlet_price": {
+        "kind": "info",
+        "entity": "outlet_price",
+        "recorder": "source",
+        "period": "effective_from",
+        "dimensions": ["warehouse_id", "product_id"],
+        "resources": {
+            "price": { "field": "price" },
+            "currency_cd": { "field": "currency_cd", "required": false }
+        }
+    }
+}
+```
+
+`recorder` is a jsonb column the platform stamps with the writing document. Add `"recordChangesOnly": true` (and `absentAs` per resource) to skip a record equal to the slice already in effect.
+
+### Accounting, classic (`acc-registry.gl`)
+
+```json
+{
+    "gl": {
+        "kind": "accounting",
+        "lineMode": "classic",
+        "chart": "account",
+        "journal": "gl_acc_posting",
+        "journalDate": "posted_on",
+        "account": "account_id",
+        "composition": {
+            "entity": "account_analytic",
+            "account": "account_id",
+            "slot": "slot_no",
+            "analytic": "analytic_kind_cd"
+        },
+        "analyticFields": ["analytic1", "analytic2", "analytic3", "analytic4"],
+        "dimensions": ["period_key"],
+        "resources": {
+            "amount": { "debitField": "debit_amount", "creditField": "credit_amount" }
+        }
+    }
+}
+```
+
+`composition` is where the chart says which analytic kind each account carries in which slot. It is required exactly when slot columns are declared; `"analyticFields": []` needs none. Its entity needs a unique constraint over `(account, slot)`.
+
+### Accounting, compound (`acc-registry.gl_corr`)
+
+```json
+{
+    "gl_corr": {
+        "kind": "accounting",
+        "lineMode": "compound",
+        "chart": "account",
+        "journal": "gl_corr_posting",
+        "journalDate": "posted_on",
+        "debitAccount": "debit_account_id",
+        "creditAccount": "credit_account_id",
+        "composition": { "entity": "account_analytic", "account": "account_id", "slot": "slot_no", "analytic": "analytic_kind_cd" },
+        "debitAnalyticFields": ["dt_analytic1", "dt_analytic2"],
+        "creditAnalyticFields": ["ct_analytic1", "ct_analytic2"],
+        "dimensions": ["period_key", "organization_id", "currency_cd"],
+        "sideDimensions": {
+            "currency_cd": { "debitField": "dt_currency_cd", "creditField": "ct_currency_cd" }
+        },
+        "resources": {
+            "amount": { "field": "amount" },
+            "currency_amount": { "debitField": "dt_currency_amount", "creditField": "ct_currency_amount" }
+        }
+    }
+}
+```
+
+The slot cap lives in three places that must agree: the posting's slot columns, `analyticFields`, and the chart's check constraint on the composition table. The platform does not parse that check; a mismatch is refused at post time.
+
+## Binding a document
+
+A register column is a `bool` state column. `A` writes `balance`, `turnover` and `info`; `L` writes `accounting`. Install resolves `register` and refuses an undeclared one.
+
+### `A` column (`wms-registry.stock`)
+
+```json
+"stock_out": {
+    "columnType": "A",
+    "dbDatatype": "bool",
+    "flags": "V",
+    "description": "Stock Out (source)",
+    "params": {
+        "stateField": "stock_out_state",
+        "register": "wms-registry.stock",
+        "direction": "decrease",
+        "dateField": "transfer_date",
+        "map": {
+            "warehouse_id": "source_warehouse_id",
+            "product_id": "product_id",
+            "quantity": "quantity"
+        },
+        "lockedFields": ["transfer_date", "source_warehouse_id", "product_id", "quantity"]
+    }
+}
+```
+
+| Param | Meaning |
+|---|---|
+| `register` | `module_cd.register_cd`. Do not combine with inline `registries`. |
+| `direction` | `increase` or `decrease`. Refused on `info`. `sign` decides per row instead. |
+| `dateField` | Document date stamped into `journalDate` or `period`. Required once the register declares either. Must be in `lockedFields`. `dateTrunc` (`day`/`month`/`year`) truncates it. |
+| `map` | Register name to column. A dimension left out binds to the column of the same name. Every required resource must be mapped. |
+| `lineEntity` + `lineField` | Post from lines: one movement per line. Declared per binding. Needs `lockedLineFields`. |
+| `headerMap` | On a line posting, register name to a **document** column. A resource may come from the document only on an `info` register. Every column must be in `lockedFields`. |
+| `groupLinesBy` | One movement per distinct value of these line columns. `map` is read over a group row; numeric resources are summed. |
+| `skipPostingWhenEmpty` | Dimensions whose emptiness means "this row posts nothing". The exception, see below. |
+| `lockedFields` / `lockedLineFields` | Columns frozen while posted. `["*"]` freezes the whole row. |
+| `movementMapping` | Journal attribute column to document or line column. |
+
+### `map` value forms
+
+| Form | Example | Notes |
+|---|---|---|
+| Column | `"qty"` | The default. |
+| One-hop path | `"product.product_group"` | Root is an `R` column with a `link`. The reference key column must be locked. Two hops refused. |
+| Expression | `"=COALESCE([transit_warehouse_id], [dest_warehouse_id])"` | Leading `=`, `F`-column formula, one-hop `[ref].[col]` reads. Every column read must be locked. |
+| Quoted constant | `"'1'"` | Stamped as is. A resource constant must be a number, outside `info`. |
+| Per-side object | `{ "debit": "dt_currency_cd", "credit": "ct_currency_cd" }` | `L` column only. For a resource or dimension the register splits by side. Both sides named. |
+
+The per-side object shape was missing from the entity schema until metadata 0.0.39. Validate with metadata 0.0.39 or later.
+
+Paths, expressions, `dateTrunc`, `headerMap`, `groupLinesBy` and `skipPostingWhenEmpty` are `A`-only. An `L` column refuses them.
+
+### `L` column (`acc-registry.gl_corr`)
+
+```json
+"params": {
+    "register": "acc-registry.gl_corr",
+    "lineEntity": "gl_corr_line",
+    "lineField": "gl_corr_entry_id",
+    "debitAccountField": "debit_account_id",
+    "creditAccountField": "credit_account_id",
+    "dateField": "entry_date",
+    "periodDimField": "period_key",
+    "map": {
+        "organization_id": "organization_id",
+        "currency_cd": { "debit": "dt_currency_cd", "credit": "ct_currency_cd" },
+        "amount": "amount",
+        "currency_amount": { "debit": "dt_currency_amount", "credit": "ct_currency_amount" }
+    },
+    "debitAnalytics": { "cost_center": "dt_cost_center_id" },
+    "creditAnalytics": { "counterparty": "ct_counterparty_id" },
+    "lockedFields": ["entry_date", "period_key"],
+    "lockedLineFields": ["*"]
+}
+```
+
+- Classic uses `accountField` and `analytics`. Compound uses `debitAccountField` + `creditAccountField` and `debitAnalytics` / `creditAnalytics`. Mixing them is refused.
+- `analytics` maps an analytic **kind** to a line column. The chart decides the slot per account, so one line column can land in `analytic1` on one account and `analytic2` on another.
+- `lineEntity` and `lineField` are required. `lockedLineFields` must cover every line column the posting copies, or be `["*"]`.
+- Every register dimension must be mapped, be a same-name line column, or be the `periodDimField` (a shared dimension).
+- `validation.balanced: ["amount"]` checks debits equal credits on classic. It is refused on compound, which balances by construction.
+
+## Reads
+
+| Read | Kinds | Returns |
+|---|---|---|
+| `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 |
+| `getCorrespondence(register, debitAccount, creditAccount, filter, from, to)` | compound | Same shape |
+
+```
+execute:
+    var onHand = getBalance("wms-registry.stock", { warehouse_id: [warehouse_id], product_id: [product_id] })
+    var price = getSlice("wms-registry.outlet_price", { warehouse_id: [warehouse_id], product_id: [product_id] }, [order_date])
+```
+
+- A dimension left out is summed over by `getBalance` and `getTurnover`. `getSlice` refuses an omitted dimension.
+- 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.
+- **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
+
+`totals` caches the turnover inside each `day`/`month`/`quarter`/`year`, never a closing balance, so a backdated posting touches one row. Declare an `entity` whose PRIMARY KEY is exactly (dimensions, `periodField`), with `inField`/`outField` per resource (`debitField`/`creditField` and an `accountField` on accounting). Posting maintains it; install rebuilds it when its shape changes. Not available on `info`. Details: registers.md section 8.4.
+
+## 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.
+- **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.
+- **Two resources from one document column**, or two resources storing into one register column. Refused.
+- **Binding to an independent `info` register.** Refused. Write it with `data.set`, or give it a `recorder`.
+- **Direct writes to register tables.** They are ordinary entities. Withhold `I`/`U`/`D` on state, journal and cache in the module's roles.
+- **`A`/`L` column in an `extends` entity.** An `A` column is allowed (a bridge posts another module's document; the state lives in the bridge's `_ext` table). An `L` column is allowed but not yet tested. See [`register-posting-from-extensions.md`](../../../docs/business-logic/register-posting-from-extensions.md).
+- **`mark-imported` is not `post`.** A document posted in another system is marked with `dforge-cli register mark-imported --entity <e> --state-column <col> --where "<sql>"`. Its state column stays false, and the engine refuses to post or unpost it. Do not set the flag by hand.
+- **Posting a mark-imported document, or unposting a receipt a later shipment consumed** (with `allowNegative: false`), is refused with `REGISTER_NEGATIVE_BALANCE` or an imported-document error.

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

@@ -145,6 +145,13 @@ installer resolves those within this module only, so a dotted one silently grant
 }
 ```
 8. **Folder access** is granted separately — roles can reference folder codes, but folder definitions themselves live in `ui/folders.json`.
+9. **Don't grant a right on a reference's target just to make the name show up.** A reference column
+   resolves its display value for anyone who can read the record carrying it — a read-only driver role
+   with `S` on `trip` sees each trip's Vehicle name without any grant on `vehicle`. Grant `S` on the
+   target only when the role should genuinely *browse* that entity, open its records, or when a view
+   or formula navigates **through** the reference to another of its columns (`vehicle.plate_no`) —
+   that still requires the right. Granting it for the name alone unlocks the entity as a full catalog
+   everywhere, which is strictly more than intended.
 
 ## Folders (`ui/folders.json`)
 

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

@@ -42,6 +42,8 @@ Adds **two timestamp columns** (no user tracking):
 
 Both columns have `flags: "I"` (internal — not shown in UI by default, managed by the platform).
 
+To show one, name it in a data view's `dataSources[].columns` — an explicitly listed column renders (read-only) regardless of its flags. See [Showing audit columns](#showing-audit-columns) below.
+
 **Important**: `audit` does NOT add `created_by` / `updated_by` user columns. For user tracking, use `audit-full`.
 
 ### `audit-full`
@@ -59,6 +61,34 @@ Use `audit-full` when you need to know **who** created/modified a record, not ju
 
 **You don't need to declare both `audit` and `audit-full`** — `audit-full` inherits from `audit` automatically.
 
+### Showing audit columns
+
+Trait columns are internal by default, not off-limits. Two ways to surface them:
+
+1. **Per view (usual case)** — list the column in `ui/data_views.json`. A column named in `dataSources[].columns` renders whatever its flags say, so this is all it takes:
+
+   ```json
+   {
+     "entityCode": "trip",
+     "columns": ["trip_number", "status", "created_by_user", "last_updated_by_user"]
+   }
+   ```
+
+   It renders **read-only** (the trait flags carry no `'E'`) and shows up in the Fields popover so users can toggle it off. Use the Reference columns (`created_by_user`) for a readable name — `created_by` is the raw cuid FK.
+
+2. **Everywhere, or editable** — redeclare the field on the entity with your own flags. An explicit field definition wins over the trait's, as long as the type matches:
+
+   ```json
+   "created_by_user": {
+     "columnType": "R",
+     "fieldTypeCd": "lookup",
+     "flags": "V",
+     "orderNum": 9904,
+     "description": "Created By",
+     "link": { "entity": "user", "thisKey": "created_by", "otherKey": "user_id" }
+   }
+   ```
+
 > **⚠️ `audit-full` + seed data needs handling.** `created_by` and `last_updated_by` are
 > **required** (NOT NULL) cuid FKs to `user`, with **no default formula**. At runtime the platform
 > fills them from the current user, but at **seed** time there is no current user, so a seeded