@dforge-core/dforge-mcp 0.2.36 → 0.2.37

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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

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 = [
   "==",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.36",
+  "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",

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