@dforge-core/dforge-mcp 0.2.35 → 0.2.37

package/CHANGELOG.md

@@ -4,6 +4,47 @@ 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.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
+setting codes (`"expression": "default_discount_pct <= max_discount_pct"`). The settings schema
+and `dforge://schema/translations` describe it.
+
+**Function libraries.** Helpers a module's actions share go in `logic/functions/*.dsl`; another
+module's functions are imported under `"functions"` in `deps/<module>.json` and called as
+`<module>.<fn>()`. `dforge_module_validate` and install check the imports.
+
+**A broken function library is reported once, as itself**, and a `ref` or `domain` may name a
+hyphenated module (`ref cdy-hr.department`); a qualified ref to an unknown module is refused at
+pack and validate.
+
+**DSL reference caught up** (`dforge://docs/dsl`, `action-dsl`): a Function libraries section
+(contents, names, state, imports, errors), the six register reads (`getBalance` ... `getCorrespondence`;
+the built-in count is now 42), text action params staying text, `ref` to a hyphenated module, the
+5-minute action-definition cache after a CLI install, and `query()` CTE and write-target qualification.
+
+**Module install reports a skip.** Installing a package whose version is already installed
+prints `already at vN — nothing installed (use --force to reinstall)` instead of success.
+
+**Register dimensions are never empty** (author skill): an empty dimension refuses the posting by
+design; use a default record, not `COALESCE(…, 0)`.
+
 ## 0.2.35 — 2026-10-07
 
 **`addDays()` moves a date field** (dForge-core #1382). `addDays([order_date], 3)` used to

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.37/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.37/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -38881,7 +38901,7 @@ var resources = [
   {
     uri: "dforge://docs/dsl",
     name: "dForge action DSL reference",
-    description: "Full reference for the dForge action DSL (logic/actions/*.dsl files): block structure (params/canExecute/onBeforeStart/execute), execution modes (single/each/batch), field-access syntax ([field], params[name], [ref].[field], records.*), all 30 built-in host functions (query/insert/error/exit/now/sendEmail/...), supported JS subset (ES5 via Esprima/Jint), common patterns, and pitfalls. **Load this before authoring any DSL action (Phase 2 of the wizard).**",
+    description: "Full reference for the dForge action DSL (logic/actions/*.dsl files): block structure (params/canExecute/onBeforeStart/execute), execution modes (single/each/batch), field-access syntax ([field], params[name], [ref].[field], records.*), all 42 built-in host functions, incl. register reads, plus function libraries (logic/functions/*.dsl) (query/insert/error/exit/now/sendEmail/...), supported JS subset (ES5 via Esprima/Jint), common patterns, and pitfalls. **Load this before authoring any DSL action (Phase 2 of the wizard).**",
     mimeType: "text/markdown",
     read: () => readVendored("docs/dsl-reference.md")
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.35",
+  "version": "0.2.37",
   "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.28",
-    "@dforge-core/metadata": "^0.0.35",
+    "@dforge-core/dforge-cli": "^0.2.29",
+    "@dforge-core/metadata": "^0.0.37",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },

package/resources/docs/dsl-reference.md

@@ -133,6 +133,10 @@ execute:
     var maxDays = params[supplier].payment_terms
 ```
 
+A `ref` names the entity by its code, qualified as `module.entity` for another module; a hyphenated module code is fine (`ref cdy-hr.department`), the schema form `cdy_hr.department` is not. Pack and install refuse a `ref` to a module that is neither this one, a declared dependency nor a system module, and install refuses one naming no installed entity.
+
+A param declared with a text field type (`text`, `textarea`, ...) stays a string whatever JSON type the client sent: `007` keeps its zeros, and a barcode compares to a text column without a cast. No `'' + params[x]` workaround is needed. Every other param is unwrapped as before.
+
 ---
 
 ## Field access syntax
@@ -211,6 +215,8 @@ info('Reminded ' + open.length + ' open invoice(s)')
 > tables. Don't assume the whole action is one transaction either — that depends
 > on the execution path. Applies to `query()` only.
 
+> **Table names.** Bare names are qualified with the current module's schema after `FROM` / `JOIN` / `USING` and as the target of `INSERT INTO`, `MERGE INTO`, `UPDATE`; a qualified name (`wms.stock`) is left as written. A CTE name is a source only inside the query that declares its `WITH` (its own body only under `RECURSIVE`); a write target is always the real table, so `WITH t AS (...) UPDATE t ...` updates the module's `t`.
+
 #### `insert(entityCd, fields) → record`
 Insert a row. Returns the inserted record as a dictionary (PKs populated, defaults applied, audit columns set).
 
@@ -707,13 +713,95 @@ if (meta != null && meta.priority == 'high') { notify([owner_id], 'High priority
 
 ---
 
+### Register reads
+
+The first argument names a **register** (`module_cd.register_cd`, as declared in that module's `registers.json`), not an entity. These only ask questions; a document posts through its `A` / `L` column.
+
+| Function | Returns | Description |
+|---|---|---|
+| `getBalance('module.register', dims?, asOf?)` | Object, per resource | Balance of an accumulation register. A dimension left out of `dims` is summed over. |
+| `getTurnover('module.register', dims, from, to)` | Object, `{in, out, net}` per resource | Movement over an interval. `dims` may be `null`; `from` and `to` are required. |
+| `getSlice('module.register', dims, onDate?, mode?)` | Object or `null` | One record of an information register, the latest on or before `onDate`, plus `_period`. No dimension may be omitted. |
+| `getAccountBalance('module.register', account, filter?, asOf?)` | Object, `{debit, credit, net}` per resource | Balance of one account of an accounting register. |
+| `getAccountTurnover('module.register', account, filter, from, to)` | Object, `{debit, credit, net}` per resource | Movement of one account over an interval. |
+| `getCorrespondence('module.register', debitAccount, creditAccount, filter, from, to)` | Object, per resource | Movement between two accounts. Needs `lineMode: "compound"`; refuses an analytic filter. |
+
+An analytic filter is the key alone (`{ cost_center: 42 }`) or `{ entity, value }` to name one entity of a union kind.
+
+---
+
+## Function libraries
+
+Helpers several actions share go once in `logic/functions/*.dsl`, never pasted into each action. A library is detected by presence; `manifest.json` declares nothing.
+
+```js
+// logic/functions/accounting.dsl
+var recNo = 0
+
+function round2(x) {
+    return Math.round(x * 100) / 100
+}
+
+function accountId(code) {
+    var rows = query('SELECT account_id FROM account WHERE code = @code', { code: code })
+    if (rows.length == 0) error('Account {code} does not exist.', { code: code })
+    return rows[0].account_id
+}
+```
+
+```js
+// logic/actions/commit_sale.dsl
+execute:
+    [amount] = round2([amount])
+    var account = accountId(getSetting('sale_account'))
+    recNo = recNo + 1
+```
+
+- **Contents.** Top-level `function` declarations and top-level `var` / `let` / `const`; any other top-level statement is refused at install. Every built-in an action has.
+- **No record context.** `[field]`, `[ref].[target]`, `params[...]` and `old[...]` are refused: pass values as arguments (`round2([amount])`). `[name]` standing alone is refused too, even where JavaScript would read an array; write a one-element array as `Array.of(name)`. An index (`rows[i]`) is fine.
+- **Names.** File names use letters, digits, `_`, `-`. A library may not declare a built-in's name, a JS global (`Math`, `Date`), `schema` or a `__` name. A name is declared once across a module's libraries. An action may not declare a global of a library's name (a top-level function or variable, or a `var` outside any function): delete the local copy. Inside a function, or a block-scoped `let` / `const`, a name may repeat.
+- **State.** Top-level variables start afresh on every run (each record of a `single` action, each batch, trigger fire and job run), so a counter like `recNo` never leaks between runs or users.
+- **Messages.** `error()` / `warn()` / `info()` / `exit()` texts in a library are translated from the module's `messages` block like an action's.
+- **Errors.** A runtime error names the file and line: `(logic/functions/tax.dsl, line 3)`. A library that does not compile is reported once, as itself (`Function library failed to compile:` with file and line), at pack, validate and install, not as undefined calls in the actions.
+- **Linked at run time**, not copied into actions: changing a library changes every action that calls it.
+- **Not available:** formulas (`F` columns, `canExecute:`) cannot call libraries; the in-app editor does not show them; Studio refuses a module that has libraries or imports.
+
+### Another module's functions
+
+List the functions under `"functions"` in that dependency's contract `deps/<module>.json`, then call them as `<module_with_underscores>.<fn>()`:
+
+```json
+{
+    "module": "cdy-accounting",
+    "version": ">=0.3.0",
+    "entities": {},
+    "functions": ["roleOf"]
+}
+```
+
+```js
+execute:
+    var account = cdy_accounting.roleOf([doc_type], 'stock')
+```
+
+- The namespace is the provider's code with `-` replaced by `_`, so `foo-bar` and `foo_bar` share one. Only the listed functions are in it; a call to another fails at install. Only a module in `dependencies` can be called.
+- The function runs as its provider: unqualified tables resolve in the provider's schema, `getSetting()` reads the provider's settings, its messages use the provider's translations. User, folder, transaction and run limits are the caller's.
+- A provider's top-level variables are its own, fresh per run.
+- Libraries may call imported functions too, and imports chain (a provider's functions call what the provider imports). Import only what you call yourself.
+- Install checks each imported name is a top-level function of the installed provider's libraries. A contract that imports only functions may declare `"entities": {}`.
+- A provider upgrade that drops an imported function is not re-checked against consumers: the call finds `undefined` at run time.
+
+**Definitions are cached.** The server reads an action's definition through a per-tenant cache (5 minutes), cleared on module install, uninstall and Studio publish. A CLI install is noticed only through a connected browser, so without one a changed action can run stale for up to 5 minutes.
+
+---
+
 ## JavaScript subset
 
 Esprima parses ES5; Jint executes.
 
 **Supported control flow:** `if / else`, `for`, `while`, `do...while`, `switch / case / default / break / continue`, `return` (only inside `function`), `try / catch / finally`, `throw`.
 
-**Supported declarations:** `var`, `function`. (No `let`, no `const`.)
+**Supported declarations:** `var`, `function`. (No `let`, no `const` in actions; a function library may use top-level `let` / `const`.)
 
 **Operators:** all standard arithmetic / comparison / logical / assignment, including ternary `? :`.
 
@@ -1060,6 +1148,15 @@ var q = query('SELECT * FROM customer WHERE name = ' + "'" + params[name] + "'",
 var q = query('SELECT * FROM customer WHERE name = @n', { n: params[name] })
 ```
 
+### ❌ Library and import mistakes
+
+- A **function library** (`logic/functions/*.dsl`) that reads `[field]` / `params[...]` / `old[...]`, uses `[name]` alone (write `Array.of(name)`), or has a top-level statement that is not a `function` / `var` / `let` / `const` -- all refused at install. Pass values in as arguments. See "Function libraries" above.
+- Keeping a **local copy** of a library function in an action (a top-level function, or a `var` of the same name outside any function) -- refused at install. Delete the copy.
+- Calling another module's function without importing it: list it under `"functions"` in `deps/<module>.json`, call it as `<module_with_underscores>.fn()`.
+- `ref cdy_hr.department` (schema form) in `params:` -- installs with no picker target. Write `ref cdy-hr.department`.
+- `'' + params[barcode]` to keep a text param text -- no longer needed.
+
+
 ### ❌ Forgetting to bump `[updated_at]` on writes
 
 The `audit` trait auto-maintains `last_updated` on INSERT/UPDATE if the column exists, but only via the standard data-access path. Direct `[field] = value` writes from DSL trigger the same path, so `last_updated` updates correctly. (No action needed — listed here as reassurance.)
@@ -1085,6 +1182,8 @@ The `audit` trait auto-maintains `last_updated` on INSERT/UPDATE if the column e
 | Send toast | `info('msg')`, `warn('msg')` |
 | Send email | `sendEmail(to, subj, body)` or `sendEmail(to, templateCd, dataObj)` |
 | Send inbox notification | `notify(userId, 'msg')` |
+| Call a shared helper | `round2([amount])` from `logic/functions/*.dsl` |
+| Call another module's helper | `cdy_accounting.roleOf(...)`, imported in `deps/<module>.json` |
 | Add days | `addDays(date, n)` |
 | Now | `now()` |
 

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/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

@@ -71,9 +71,9 @@ Full descriptions are on the tools themselves — this is the map.
 | Cross-cutting | `dforge_dependency_add`, `dforge_diagram_add` |
 
 **Composite tools first.** A relation, a roll-up, and a status column each span
-several coordinated keys, and hand-assembling them from `entity_field_add` is
+several coordinated keys, and hand-assembling them from `dforge_entity_field_add` is
 the top source of broken modules. The composite tools emit the whole shape and
-can't express the broken variants. Reach for `entity_field_add` only for a
+can't express the broken variants. Reach for `dforge_entity_field_add` only for a
 plain scalar column.
 
 ## Writing files: preview vs `apply`

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

@@ -59,6 +59,10 @@ params:
 
 Types are a subset of column field types: `text`, `textarea`, `number`, `currency`, `percent`, `checkbox`, `date`, `datetime`, `dropdown`, `lookup`, `user`.
 
+A `ref` names the entity by its code, qualified as `module.entity` for another module; a hyphenated module code is fine (`ref cdy-hr.department`), the schema form `cdy_hr.department` is not. Pack and install refuse a `ref` to a module that is neither this one, a declared dependency nor a system module, and install refuses one naming no installed entity.
+
+A param declared with a text field type (`text`, `textarea`, ...) stays a string whatever JSON type the client sent: `007` keeps its zeros, and a barcode compares to a text column without a cast. No `'' + params[x]` workaround is needed. Every other param is unwrapped as before.
+
 Access in execute block: `params[param_name]` (bracket syntax, NOT dot syntax).
 
 #### Dropdown params: label the options, or borrow a domain
@@ -298,6 +302,21 @@ var queued = select('comm.message', {
 - `query()` remains the escape hatch for anything this shape can't express: aggregates, multi-hop
   joins, CTEs, `FOR UPDATE`.
 
+### Register reads
+
+The first argument names a **register** (`module_cd.register_cd`, as declared in that module's `registers.json`), not an entity. These only ask questions; a document posts through its `A` / `L` column.
+
+| Function | Returns | Description |
+|---|---|---|
+| `getBalance('module.register', dims?, asOf?)` | Object, per resource | Balance of an accumulation register. A dimension left out of `dims` is summed over. |
+| `getTurnover('module.register', dims, from, to)` | Object, `{in, out, net}` per resource | Movement over an interval. `dims` may be `null`; `from` and `to` are required. |
+| `getSlice('module.register', dims, onDate?, mode?)` | Object or `null` | One record of an information register, the latest on or before `onDate`, plus `_period`. No dimension may be omitted. |
+| `getAccountBalance('module.register', account, filter?, asOf?)` | Object, `{debit, credit, net}` per resource | Balance of one account of an accounting register. |
+| `getAccountTurnover('module.register', account, filter, from, to)` | Object, `{debit, credit, net}` per resource | Movement of one account over an interval. |
+| `getCorrespondence('module.register', debitAccount, creditAccount, filter, from, to)` | Object, per resource | Movement between two accounts. Needs `lineMode: "compound"`; refuses an analytic filter. |
+
+An analytic filter is the key alone (`{ cost_center: 42 }`) or `{ entity, value }` to name one entity of a union kind.
+
 ### Messaging
 
 | Function | Description |
@@ -392,6 +411,67 @@ error('Insufficient stock. Available: {available}, requested: {requested}',
 > (undefined in `execute:`) that the server translates to an exact `::bigint` SQL literal.
 
 
+## Function libraries
+
+Helpers several actions share go once in `logic/functions/*.dsl`, never pasted into each action. A library is detected by presence; `manifest.json` declares nothing.
+
+```js
+// logic/functions/accounting.dsl
+var recNo = 0
+
+function round2(x) {
+    return Math.round(x * 100) / 100
+}
+
+function accountId(code) {
+    var rows = query('SELECT account_id FROM account WHERE code = @code', { code: code })
+    if (rows.length == 0) error('Account {code} does not exist.', { code: code })
+    return rows[0].account_id
+}
+```
+
+```js
+// logic/actions/commit_sale.dsl
+execute:
+    [amount] = round2([amount])
+    var account = accountId(getSetting('sale_account'))
+    recNo = recNo + 1
+```
+
+- **Contents.** Top-level `function` declarations and top-level `var` / `let` / `const`; any other top-level statement is refused at install. Every built-in an action has.
+- **No record context.** `[field]`, `[ref].[target]`, `params[...]` and `old[...]` are refused: pass values as arguments (`round2([amount])`). `[name]` standing alone is refused too, even where JavaScript would read an array; write a one-element array as `Array.of(name)`. An index (`rows[i]`) is fine.
+- **Names.** File names use letters, digits, `_`, `-`. A library may not declare a built-in's name, a JS global (`Math`, `Date`), `schema` or a `__` name. A name is declared once across a module's libraries. An action may not declare a global of a library's name (a top-level function or variable, or a `var` outside any function): delete the local copy. Inside a function, or a block-scoped `let` / `const`, a name may repeat.
+- **State.** Top-level variables start afresh on every run (each record of a `single` action, each batch, trigger fire and job run), so a counter like `recNo` never leaks between runs or users.
+- **Messages.** `error()` / `warn()` / `info()` / `exit()` texts in a library are translated from the module's `messages` block like an action's.
+- **Errors.** A runtime error names the file and line: `(logic/functions/tax.dsl, line 3)`. A library that does not compile is reported once, as itself (`Function library failed to compile:` with file and line), at pack, validate and install, not as undefined calls in the actions.
+- **Linked at run time**, not copied into actions: changing a library changes every action that calls it.
+- **Not available:** formulas (`F` columns, `canExecute:`) cannot call libraries; the in-app editor does not show them; Studio refuses a module that has libraries or imports.
+
+### Another module's functions
+
+List the functions under `"functions"` in that dependency's contract `deps/<module>.json`, then call them as `<module_with_underscores>.<fn>()`:
+
+```json
+{
+    "module": "cdy-accounting",
+    "version": ">=0.3.0",
+    "entities": {},
+    "functions": ["roleOf"]
+}
+```
+
+```js
+execute:
+    var account = cdy_accounting.roleOf([doc_type], 'stock')
+```
+
+- The namespace is the provider's code with `-` replaced by `_`, so `foo-bar` and `foo_bar` share one. Only the listed functions are in it; a call to another fails at install. Only a module in `dependencies` can be called.
+- The function runs as its provider: unqualified tables resolve in the provider's schema, `getSetting()` reads the provider's settings, its messages use the provider's translations. User, folder, transaction and run limits are the caller's.
+- A provider's top-level variables are its own, fresh per run.
+- Libraries may call imported functions too, and imports chain (a provider's functions call what the provider imports). Import only what you call yourself.
+- Install checks each imported name is a top-level function of the installed provider's libraries. A contract that imports only functions may declare `"entities": {}`.
+- A provider upgrade that drops an imported function is not re-checked against consumers: the call finds `undefined` at run time.
+
 ## Real examples from the codebase
 
 ### Simple field update (status transition)
@@ -650,6 +730,8 @@ In `ui/actions.json`:
 | `orderNum` | Recommended | Display order in the action menu |
 | `isAsync` | Optional | `true` **permits** background execution — it does not force it. A parameterless action is queued directly; one with params is offered to the user as both "Run" and "Run in Background". Queued runs get a completion notification |
 
+**Definitions are cached.** The server reads an action's definition through a per-tenant cache (5 minutes), cleared on module install, uninstall and Studio publish. A CLI install is noticed only through a connected browser, so without one a changed action can run stale for up to 5 minutes.
+
 ## Atomicity
 
 `isTransacted: true` makes the run **one transaction**, in both execution modes.
@@ -710,7 +792,7 @@ be either.
 > and `ON COMMIT DROP` on any temp table. Only `query()` can do any of this — the
 > structured built-ins emit plain DML — and nothing checks it statically.
 
-1. **Table names are schema-qualified** within the module: `crm.contact`, `wms.stock_movement`, `fin.invoice`. Use the module code as the schema prefix. (Module codes with a hyphen, e.g. `crm-fin`, cannot be schema-qualified in raw SQL — another reason to use the structured built-ins, which accept the qualified `module.entity` code.)
+1. **Bare table names are qualified automatically** with the current module's schema after `FROM` / `JOIN` / `USING`, and as the target of `INSERT INTO`, `MERGE INTO` and `UPDATE`. A name already qualified (`wms.stock_movement`) is left as written, so qualify only another module's table. Left alone: words that name no table (`IS DISTINCT FROM`, `EXTRACT(year FROM d)`, `FOR UPDATE`, `DO UPDATE SET`, `SELECT ... INTO var`), built-in set functions (`generate_series`, `unnest`), literals and comments. A CTE name is a source only inside the query that declares its `WITH` (and in its own body only under `RECURSIVE`); a write target is always the real table, so `WITH t AS (...) UPDATE t ...` updates the module's `t`. `;`-separated statements are each qualified. (Module codes with a hyphen, e.g. `crm-fin`, cannot be schema-qualified by hand in raw SQL; use the structured built-ins, which accept `module.entity`.)
 2. **Use `@param` placeholders** for values — NEVER concatenate user input into SQL strings. The engine auto-parameterizes.
 3. **SELECT, INSERT, UPDATE, DELETE all work** via `query()`. For reads, it returns row arrays. For writes, it executes the statement.
 4. **`insert()` is preferred over `query('INSERT ...')`**, `update()`/`delete()` over `query('UPDATE/DELETE ...')`, and `select()` over `query('SELECT ...')` for module entities — raw SQL skips auto-fill (PKs, audit, number sequences) and metadata validation.
@@ -731,6 +813,11 @@ be either.
 - Calling `TODAY()` or `NOW()` (uppercase) inside `execute:` — **wrong**, they're undefined there and install fails with `'TODAY' is not defined`. Use lowercase **`now()`** in `execute:`; `TODAY()`/`NOW()` are formula-only (`canExecute:`, formula columns).
 - Forgetting that `insert()` returns the full row — you can use `quote.quote_id` immediately after insert.
 - Using `[field]` inside a `query()` SQL string — **wrong**. `[field]` is resolved in JS scope, not inside SQL strings. Pass values as `@param` arguments.
+- A **function library** (`logic/functions/*.dsl`) that reads `[field]` / `params[...]` / `old[...]`, uses `[name]` alone (write `Array.of(name)`), or has a top-level statement that is not a `function` / `var` / `let` / `const` -- all refused at install. Pass values in as arguments. See *Function libraries*.
+- Keeping a **local copy** of a library function in an action (a top-level function, or a `var` of the same name outside any function) -- refused at install. Delete the copy.
+- Calling another module's function without importing it: list it under `"functions"` in `deps/<module>.json`, call it as `<module_with_underscores>.fn()`.
+- `ref cdy_hr.department` (schema form) in `params:` -- installs with no picker target. Write `ref cdy-hr.department`.
+- `'' + params[barcode]` to keep a text param text -- no longer needed.
 
 ## Internal API (advanced)
 

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

@@ -143,10 +143,13 @@ Every entry in `dependencies` needs a contract file at `deps/<module_code>.json`
 ```
 
 - `version` must be the same range as the manifest's dependency entry.
-- `entities` needs at least one entry, except against a system module, where `{}` is a pure platform-version gate. Each entry needs a `pk` and a non-empty `use`.
+- `entities` needs at least one entry, except against a system module (where `{}` is a pure platform-version gate) or a contract that imports only `functions`. Each entry needs a `pk` and a non-empty `use`.
 - `columns` is optional — omit it when you touch no specific column of that entity. Declare only real storage columns you read, write or join on, at their **storage class** (`int8`, `varchar`, `numeric`, `bool`, `date`, `timestamptz`, …; a `cuid` PK is `int8`). Never declare a virtual column (`R`/`S`/`F`) or a column your own extension adds.
 - `use` tokens are `<kind>:<symbol>` where kind is `ref`, `extends`, `formula`, `action`, `view`, `report`, `print` or `role`. `extends` must be fully qualified: `extends:parties.party`.
 
+- `functions` (optional) lists the library functions of that dependency you call: `"functions": ["roleOf"]`, called as `<module_with_underscores>.roleOf()`. Install checks each is a top-level function of the installed provider's libraries. A contract that imports only functions may declare `"entities": {}`. See *Function libraries* in `action-dsl.md`.
+- `logic/functions/*.dsl` (function libraries) is detected by presence. No `manifest.json` key declares it, and `actions` does not list it.
+
 Full schema: `dforge://schema/deps`.
 
 ## Extension entities

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

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

@@ -135,6 +135,15 @@ For each action:
 - [ ] Referenced entities exist
 - [ ] Referenced parameters are declared in `params:`
 
+## Function libraries (`logic/functions/*.dsl`)
+
+- [ ] Only top-level `function` declarations and `var` / `let` / `const`; no other top-level statement
+- [ ] No `[field]`, `[ref].[target]`, `params[...]`, `old[...]`, and no `[name]` standing alone (use `Array.of(name)`); values come in as arguments
+- [ ] No name that is a built-in, a JS global, `schema` or starts with `__`; each name declared once across the libraries
+- [ ] No action keeps a local copy of a library function
+- [ ] Every imported function is listed under `"functions"` in `deps/<module>.json`, exists as a top-level function in the provider, and is called as `<module_with_underscores>.fn()`
+- [ ] A `ref` to another module in `params:` uses the module code (`ref cdy-hr.department`) and the module is a declared dependency
+
 ## Settings
 
 - [ ] `settings.json` exists if the module has any settings

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

@@ -10,8 +10,15 @@ module artifacts.
 
 **Before each phase:** run `dforge_module_inspect` and parse
 `files["_inspect.json"]` — never plan a patch against what you assume is there.
+For Phase 1, first present the proposed entity inventory based only on context
+already provided and get approval before any tool call; if that context is
+insufficient, ask the user for the missing information without calling tools.
+Immediately after approval, run the inspection before any file changes.
 **After each phase:** record it with
 `dforge_module_plan({ action: "complete_phase", moduleDir, phase: "N", note: "..." })`.
+If `dforge_module_inspect` or `dforge_module_plan` fails or is unavailable, stop,
+report the tool name and error to the user, and do not proceed to the next phase
+or patch files.
 
 ## Loading policy — one reference per step, at the step
 
@@ -34,6 +41,7 @@ flags, or column patterns.
 | Hide columns from a user type (column-level security) | `dforge://reference/security` (§Column-level security), `dforge://example/column-security/entities/product.json`, `dforge://example/column-security/ui/folders.json` | — |
 | Add a menu | `dforge://reference/menus`, `dforge://example/ui/menus.json` | — |
 | Add an action | `dforge://reference/action-dsl`, `dforge://example/logic/actions/mark_done.dsl`, `dforge://example/ui/actions.json` | `dforge://docs/dsl` |
+| Share helpers between actions, or call another module's functions | `dforge://reference/action-dsl` (§Function libraries): `logic/functions/*.dsl`, imports in `deps/<module>.json` | `dforge://schema/deps` |
 | Add a trigger | — | `dforge://schema/triggers`; condition syntax in `dforge://docs/dsl` |
 | Add a scheduled job | `dforge://reference/jobs` | `dforge://schema/jobs` |
 | Add a webhook | — | `dforge://schema/webhooks` |
@@ -67,6 +75,12 @@ Enough to author inline; load the linked reference for the full detail.
   size/precision. Common fixes: `number` not `integer`/`float`; `phone` not
   `phoneNumber`; `date` not `datePicker`; `timestamptz` not `datetime`; `bool`
   not `boolean`; `varchar`/`text` not `string`. → `field-types`
+- **Register dimensions are never empty.** An empty dimension refuses the
+  posting by design; do not make one optional or add a `COALESCE([x_id], 0)`
+  technical key. Variants: one `variant_id` dimension, with a default variant
+  for products without options. Untracked batch/series: a seeded default
+  record, not `0`. Optional analytics: accounting analytic slots or plain
+  columns. Ad hoc slices by an optional attribute: a report, not a dimension.
 - **Formula columns** (`columnType: "F"`): `baseDatatypeCd` required, no
   `dbDatatype`, `flags: "V"`. → `formulas`
 - **Roll-up totals** over a child set are Generated (`G`) columns with
@@ -126,7 +140,8 @@ Proposed entities (N):
 Loop with the user until they explicitly approve.
 
 **Pre-scaffold consistency checks** against `docs/DESIGN.md` — if any fail,
-surface it and go back to Phase 0c; don't silently adjust the design:
+surface it and go back to Phase 0 and re-run the design step that produced
+`docs/DESIGN.md`; don't silently adjust the design:
 
 1. Every FK in the relationship map has a corresponding field on the child.
 2. Every action's `canExecute` guard references a status value that exists.
@@ -147,13 +162,15 @@ approval, then patch. Reach for the **composite tools first**:
 
 **Field batching rule** — the only Phase 1 exception to one-at-a-time. A field
 is batchable only if ALL of: scalar primitive (string/integer/decimal/boolean/
-date), no FK or reference, no formula, and unambiguous nullability. Everything
-else goes one at a time. This never justifies batching entities, views, roles,
-actions, or reports.
+date), no FK or reference, no formula, and its nullability is stated explicitly
+by the user (required = M flag, optional = VE flag). Everything else goes one
+at a time. This never justifies batching entities, views, roles, actions, or
+reports.
 
 **Extension entities last.** `extends: "module.entity"`, `toString: null`,
 dotted manifest key. Snapshot the base entity's fields with
-`dforge_module_inspect` on the dependency dir when it's available locally;
+`dforge_module_inspect` on the dependency dir when the dependency module
+directory exists in the current workspace (check the `deps/<module>.json` path);
 otherwise document the known base fields and note that drift tracking is the
 user's responsibility.
 
@@ -209,7 +226,7 @@ must set `jobClass: 'long_running'`. `dforge_module_validate` flags violations.
 
 **3a. Default grids first.** Every entity gets a `viewType: "grid"` view with
 `dataSources: [{ entityCode, columns: [...] }]`. The scaffolder already wrote one
-per entity, so you'll often `view_modify` rather than `view_add`.
+per entity, so you'll often `dforge_view_modify` rather than `dforge_view_add`.
 
 View codes are semantic — the entity name (`feedback_item`), a plural
 (`invoices`), or descriptive (`invoices_kanban`). **Never use the literal code
@@ -279,12 +296,15 @@ stated trigger; every report's params sit on a dataset.
 ## Phase 5 — Security (5a required)
 
 1. **Inspect first.** The scaffolder pre-created `<code>.admin` with `SIUDC` on
-   every entity declared at scaffold time. It exists — don't re-create it
-   (`role_add` fails on an existing code; use `role_right_set` to amend).
+   every entity declared at scaffold time. Preserve this scaffold-generated
+   baseline role; don't re-create it (`dforge_role_add` fails on an existing
+   code; use `dforge_role_right_set` to amend). It is not an inferred user type.
 2. **Derive roles from the intake's user types and verbs.** Re-read the user-type
    sentences in `docs/REQUIREMENTS.md`. One role per distinct user type, named
-   `<code>.<user-type>`. **Forbidden:** a generic admin/contributor/viewer matrix
-   the user didn't ask for.
+   `<code>.<user-type>`. **Forbidden:** adding generic admin/contributor/viewer
+   roles or a matrix the user didn't ask for. The scaffold-generated
+   `<code>.admin` baseline is the sole exception; include its existing rights
+   when showing the actual rights matrix.
 3. **Reflect the role list back** before computing rights. Get confirmation.
 4. **Show the rights matrix as a table** (rows = entities/actions/reports,
    columns = roles, cells = rights strings), each cell explained by the verb it
@@ -332,16 +352,18 @@ When a later phase exposes a problem in an earlier one, in order:
 3. **Identify the target phase + decision.**
 4. **Get user sign-off**, including cascading impacts.
 5. **Apply the smallest tool that fits** — this overrides the phase labels:
-   `entity_field_add` over `entity_add`; `entity_field_rename` over remove+add;
-   `role_right_set` over `role_add`; `view_modify` over remove+add.
+   `dforge_entity_field_add` over `dforge_entity_add`;
+   `dforge_entity_field_rename` over remove+add;
+   `dforge_role_right_set` over `dforge_role_add`;
+   `dforge_view_modify` over remove+add.
 6. **Re-run `dforge_module_inspect`**, fix knock-on impacts, resume.
 
 **Multi-trigger rule:** if several phases expose gaps at once, resolve the
 **earliest-phase** gap first, complete its backtrack, re-inspect, then
 re-evaluate.
 
-**Rename and delete are handled for you** — `entity_field_rename`,
-`entity_field_remove`, `entity_rename`, `entity_delete` each propagate the
+**Rename and delete are handled for you** — `dforge_entity_field_rename`,
+`dforge_entity_field_remove`, `dforge_entity_rename`, `dforge_entity_delete` each propagate the
 cascade in one call. **Always apply the response's `deletes` as well as
 `files`** (or just pass `apply: true`, which guarantees it). Each tool surfaces
 what it could NOT auto-fix — reports, translations, menu labels, DSL bodies,