@dforge-core/dforge-mcp 0.2.1 → 0.2.2

package/package.json

@@ -1,48 +1,48 @@
 {
-  "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.1",
-  "description": "MCP server for dForge module authoring. Exposes 34 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",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/dforge-core/dforge-mcp.git"
-  },
-  "bin": {
-    "dforge-mcp": "dist/server.js",
-    "dforge-install-skills": "scripts/install-skills.mjs"
-  },
-  "files": [
-    "dist/",
-    "docs/",
-    "resources/",
-    "skills/",
-    "scripts/install-skills.mjs",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "main": "dist/server.js",
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsup",
-    "sync-schemas": "node scripts/vendor-schemas.cjs",
-    "prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "install-skills": "node scripts/install-skills.mjs"
-  },
-  "dependencies": {
-    "@dforge-core/dforge-cli": "^0.2.7",
-    "@dforge-core/metadata": "^0.0.10",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^22.20.1",
-    "tsup": "^8.5.1",
-    "typescript": "^6.0.3",
-    "vitest": "^3.2.7"
-  }
+	"name": "@dforge-core/dforge-mcp",
+	"version": "0.2.2",
+	"description": "MCP server for dForge module authoring. Exposes 34 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",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
+	},
+	"bin": {
+		"dforge-mcp": "dist/server.js",
+		"dforge-install-skills": "scripts/install-skills.mjs"
+	},
+	"files": [
+		"dist/",
+		"docs/",
+		"resources/",
+		"skills/",
+		"scripts/install-skills.mjs",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"main": "dist/server.js",
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"build": "tsup",
+		"sync-schemas": "node scripts/vendor-schemas.cjs",
+		"prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"install-skills": "node scripts/install-skills.mjs"
+	},
+	"dependencies": {
+		"@dforge-core/dforge-cli": "^0.2.10",
+		"@dforge-core/metadata": "^0.0.12",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@types/node": "^22.20.1",
+		"tsup": "^8.5.1",
+		"typescript": "^6.0.3",
+		"vitest": "^3.2.7"
+	}
 }

package/resources/docs/conventions.md

@@ -135,15 +135,14 @@ The entity file uses the same `fields` schema as regular entities, plus an `exte
 	"fields": {
 		"customer_id": {
 			"dbDatatype": "int8",
-			"isNullable": true,
-			"flags": "EM",
+			"flags": "E",
 			"orderNum": 34,
 			"description": "Customer FK"
 		},
 		"customer": {
 			"columnType": "R",
 			"fieldTypeCd": "lookup",
-			"flags": "VEM",
+			"flags": "VE",
 			"orderNum": 35,
 			"description": "Customer",
 			"link": {
@@ -641,7 +640,6 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 		},
 		"department_id": {
 			"dbDatatype": "cuid",
-			"fieldTypeCd": "hidden",
 			"flags": "EM",
 			"orderNum": 30,
 			"description": "Department ID"
@@ -715,8 +713,7 @@ For every foreign key relationship, create TWO columns:
 ```json
 "department_id": {
 	"dbDatatype": "cuid",
-	"fieldTypeCd": "hidden",
-	"flags": "EM",
+	"flags": "E",
 	"orderNum": 30,
 	"description": "Department ID"
 }
@@ -727,7 +724,7 @@ For every foreign key relationship, create TWO columns:
 "department": {
 	"columnType": "R",
 	"fieldTypeCd": "lookup",
-	"flags": "VEM",
+	"flags": "VE",
 	"orderNum": 35,
 	"description": "Department",
 	"link": {
@@ -752,8 +749,14 @@ For every foreign key relationship, create TWO columns:
 - Reference columns use `"link"` (not `"params"`) for entity binding
 - `link.entity` = target entity code, `link.thisKey` = local FK field, `link.otherKey` = remote PK field
 - `params` is used for other purposes (e.g., dropdown `options`)
-- Hidden FK column: `flags: "EM"` (no `V` = hidden from UI)
-- Visible reference column: `flags: "VEM"`, `columnType: "R"`
+- Hidden FK column: `flags: "E"` (no `V` = hidden from UI), `flags: "EM"` when the
+  relationship is genuinely required. `M` resolves to `isNullable: false` at install, so it
+  makes the FK `NOT NULL`; omitting both leaves the column nullable, which is the default.
+  Declaring `M` alongside `"isNullable": true` fails at pack time.
+- Visible reference column: `columnType: "R"`, `flags: "VE"` — or `"VEM"` when the FK is
+  required. **Keep the two in step.** `M` is inert on a virtual column (a Reference is
+  required exactly when its hidden FK is), so `VEM` over an optional FK changes nothing but
+  reads as a required field to the next author.
 - The FK column's `dbDatatype` **MUST match the referenced PK's type** — use `cuid` for `identity`-trait PKs (`cuid` is physically `int8`, **not** a UUID). A mismatch (e.g. FK `uuid` → PK `cuid`) fails install with *"foreign key constraint … cannot be implemented"*.
 
 ---

package/resources/docs/dsl-reference.md

@@ -149,7 +149,10 @@ var open = query(
     { s: 'open', cid: [customer_id] }
 )
 if (open.length == 0) { exit('Nothing open', 'info') }
-info('Open invoices: ' + open.length + ', total $' + open[0].total)
+for (var i = 0; i < open.length; i++) {
+    update('fin.invoice', open[i].invoice_id, { status: 'reminded' })
+}
+info('Reminded ' + open.length + ' open invoice(s)')
 ```
 
 > **Pooled connection.** The connection is handed to another request once your
@@ -228,7 +231,8 @@ The result is a **read-only** snapshot — writing to it (`rec.set(...)`) throws
 
 ```dsl
 var rec = getRecord('crm.customer', [customer_id])
-info('Customer: ' + rec.name + ' — credit limit $' + rec.credit_limit)
+if (rec.credit_limit == null) { error('Customer has no credit limit set') }
+[customer_name] = rec.name
 ```
 
 #### `getRecordOrNull(entityCd, key) → record | null`
@@ -245,7 +249,7 @@ Call a stored procedure with named args. Returns the proc's result row (or rows
 
 ```dsl
 var summary = callProc('fin.compute_balance', { account_id: [account_id], as_of: now() })
-info('Balance: ' + summary.balance)
+[closing_balance] = summary.balance
 ```
 
 #### `preloadRef(fkField)`
@@ -289,6 +293,8 @@ Fractional-unit arithmetic.
 #### `info(message, opts?)`, `warn(message, opts?)`
 Queue user-facing toast. `opts.links: [{entity, id}]` adds "open record" buttons.
 
+A message is a **receipt for work the action did**, not a way to publish a computed value. An action whose only output is `info('<some computed number>')` stores nothing — it can't be audited, re-read or reported on, and the value arrives unformatted. Build a report, a formula column, or an action that writes a result record instead. See `dforge://reference/action-dsl`, *When an action is the wrong tool*.
+
 ```dsl
 info('Created PO ' + po.po_number, {
     links: [{ entity: 'purchase_order', id: po.purchase_order_id }]
@@ -458,12 +464,21 @@ if (det != null) { var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url')
 #### `entityLink(entityCd, record, description?) → link value`
 Build a clickable link to any entity record for storing in an `entitylink` (jsonb)
 column. `record` is a row object (e.g. from `insert()` / `getRecord()`); its PK
-columns are stored as **strings** so snowflake/cuid ids > 2^53 stay exact. Optional
-`description` sets the display text.
+columns are stored as **strings** so snowflake/cuid ids > 2^53 stay exact.
+
+The target entity is resolved at build time and stored **by id**, not by code:
+`entity_cd` is only unique per module, so a bare `'invoice'` would re-resolve at click
+time against the *reader's* folder module and could land on another module's entity.
+Always qualify the code you pass (`'fin.invoice'`).
+
+`description` is optional — omit it and the link is captioned with the entity's
+`toString` evaluated against `record`, the way records are captioned everywhere else.
+An explicit `description` still wins.
 
 ```dsl
 var task = insert('workspace.task', { title: 'Follow up' })
-insert('workspace.task_note', { link: entityLink('workspace.task', task, task.title) })
+# Captioned by workspace.task's toString — no third argument needed.
+insert('workspace.task_note', { link: entityLink('workspace.task', task) })
 ```
 
 #### `flush()`

package/resources/schemas/entity.schema.json

@@ -130,7 +130,7 @@
 				"flags": {
 					"type": "string",
 					"pattern": "^[VIEMH]*$",
-					"description": "Display flags: V=Visible, I=Identity, E=Editable, M=Mandatory, H=Hidden"
+					"description": "Display flags: V=Visible, I=Identity, E=Editable, M=Mandatory, H=Hidden. M is resolved into isNullable:false at install, so it makes the column NOT NULL; it is inert on virtual (R/S/F) and identity columns. Declaring M together with isNullable:true is rejected at pack time."
 				},
 				"isPk": {
 					"type": "boolean",
@@ -138,7 +138,7 @@
 				},
 				"isNullable": {
 					"type": "boolean",
-					"description": "Whether the column allows NULL values"
+					"description": "Whether the column allows NULL values. Omitted means true (nullable) — only an explicit false, or the M flag which resolves to it, makes the column NOT NULL. Adding it to a column that existing tenant rows leave empty aborts the upgrade."
 				},
 				"isIdentity": {
 					"type": "boolean",

package/resources/schemas/triggers.schema.json

@@ -33,7 +33,7 @@
 				"event": {
 					"type": "string",
 					"enum": ["insert", "update", "delete", "status_change", "any"],
-					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete."
+					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete. Events are raised by the row change itself, whichever path wrote it \u2014 a user edit and an action's `[field] = value` both count \u2014 except for the DSL's insert()/update()/delete()/query() builtins writing OTHER records, which raise nothing."
 				},
 				"condition": {
 					"type": "string",

package/skills/dforge-mcp-author/examples/simple-todo/entities/todo_item.json

@@ -23,6 +23,7 @@
 			"dbDatatype": "varchar",
 			"fieldTypeCd": "dropdown",
 			"flags": "VEM",
+			"formula": "'medium'",
 			"maxLen": 20,
 			"orderNum": 30,
 			"description": "Priority",

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

@@ -5,6 +5,26 @@ Actions are dForge's business logic. They are scripts with three declarative blo
 Lives in: `logic/actions/<action_name>.dsl`
 Registered in: `ui/actions.json`
 
+## When an action is the wrong tool
+
+An action exists to **change something**. Its message is a receipt for work that was done — not the output itself.
+
+Do **not** write an action whose `execute:` block only reads data, computes a value and reports it with `info()`. The result is a line of text that is never stored: it can't be audited, referenced, re-read or reported on, and every reader has to re-run the action to see it again. The value also reaches the user unformatted — a raw `query()` result carries no column metadata, so money renders as `1000.0099999999999` instead of `1,000.01`.
+
+If you are about to write a `check_…`, `calculate_…` or `show_…` action, build one of these instead:
+
+| What's actually needed | Build this |
+|---|---|
+| The user needs to **see** current numbers | A **report** or a data view — both are metadata-driven, so values format correctly, and the user can return to them any time without re-running anything. |
+| A derived value **belongs to the record** | A **formula column** (`columnType: "F"`) or a roll-up — computed on read, visible on the card and in grids, filterable and sortable. |
+| The **verdict itself matters** (approvals, credit checks, compliance) | An action that **writes a result record** — e.g. `credit_check(customer, checked_at, limit, outstanding, projected, verdict, checked_by)`. Now it's auditable and reportable, and `info()` becomes a legitimate receipt with a link to the new row. |
+| The check must **block** something | A **trigger** with `async: false`, or a `canExecute:` guard on the action being gated — enforcement, not narration. |
+
+Messages stay correct for exactly two things, and both are short by nature:
+
+- a **receipt** for a mutation that just happened — `info('Created PO ' + po.po_number, { links: [...] })`
+- a **refusal** that prevented one — `error('Period is closed')`
+
 ## Structure
 
 A DSL file has up to three blocks. All are optional (but `execute:` is needed to actually do something).
@@ -126,6 +146,17 @@ var note = params[note]             // no quotes around param name in this DSL
 > `null` key **throws** (a `col = NULL` predicate can never match), and array keys are rejected —
 > loop and mutate per id instead.
 
+> **These writes raise no events.** `insert()`, `update()`, `delete()` and `query()` are the raw
+> write layer: by design they skip folder row-filters, closed-period checks and registry state, and
+> they raise no trigger or webhook events either. Only the **acted-on record's own**
+> `[field] = value` raises them — that one is indistinguishable from a user editing the same field,
+> and fires the entity's `update` / `status_change` triggers exactly as the grid does.
+>
+> So a trigger on `b` will not see `update('b', …)` from an action bound to `a`. If `b` must react,
+> put the trigger on `a` — the entity the action is bound to — or make the change through `b`'s own
+> action. The symptom when you get this wrong is a trigger that simply never fires, with nothing in
+> the log to say why.
+
 ### select() — structured multi-row reads
 
 The read counterpart to `insert()`/`update()`/`delete()`. Entity codes are metadata-validated,
@@ -174,7 +205,7 @@ var queued = select('comm.message', {
 |---|---|
 | `error('message')` | **Abort** the action and show an error to the user. Rolls back all changes. |
 | `warn('message')` | Show a warning but continue execution. |
-| `info('message')` | Show an informational message. |
+| `info('message')` | Show an informational message. A **receipt for work the action did** — not a way to publish a computed value; see *When an action is the wrong tool*. |
 | `exit('message'?, 'level'?)` | **Stop the script early without error** — changes made so far are kept. Level `'info'` (default) or `'warn'` styles the message. This is the DSL's early-return: a bare `return` is not valid at the top level of `execute:`. |
 | `notify(userId, 'message')` | Send an in-app notification to a specific user. First arg is a user ID (typically `[owner_id]` or similar). |
 
@@ -203,7 +234,7 @@ var queued = select('comm.message', {
 | `addDays(date, n)` | Date | Add `n` days to a date, e.g. `addDays(now(), 30)`. |
 | `nextNumber('entity')` | String | Generate next value from a number sequence. Usually not needed — platform auto-fills on `insert()`. Use for pre-generating numbers. |
 | `callProc('proc_name', { args })` | Result | Call a stored procedure. Args are passed as named parameters. |
-| `entityLink('entityCd', record, description?)` | Link value | Build a clickable link to any entity record, for storing in an `entitylink` (jsonb) column. `record` is a row object (e.g. the result of `insert()` or `getRecord()`); its PK columns are read and stored as **strings**, so snowflake/cuid ids (> 2^53) stay exact. Optional `description` sets the link's display text. |
+| `entityLink('entityCd', record, description?)` | Link value | Build a clickable link to any entity record, for storing in an `entitylink` (jsonb) column. `record` is a row object (e.g. the result of `insert()` or `getRecord()`); its PK columns are read and stored as **strings**, so snowflake/cuid ids (> 2^53) stay exact. The entity is resolved at build time and stored **by id** — `entity_cd` is only unique per module, so always pass a qualified code (`'fin.invoice'`). Omit `description` and the link is captioned with the entity's `toString` against `record`; an explicit `description` wins. |
 
 > **Dates: `now()` in `execute:`, `TODAY()`/`NOW()` in formulas.** The `execute:` block runs as
 > JavaScript (Jint) and exposes **lowercase `now()`** only — `TODAY()` and `NOW()` (uppercase) are
@@ -514,6 +545,7 @@ way.
 
 ## Common mistakes
 
+- Writing an action that only reads, computes and prints (`info('Balance: ' + total)`) — **wrong shape**, not just wrong formatting. Nothing is stored, so nobody can re-read the answer. Use a report, a formula column, or write a result record. → *When an action is the wrong tool* (top of this file)
 - Writing `params.note` instead of `params[note]` — **wrong**. Use bracket syntax for params.
 - Writing `params["note"]` — **also wrong in DSL syntax**. Use `params[note]` without quotes.
 - Writing `update [status] = 'Draft'` (declarative style) — **wrong**. Use `[status] = 'Draft'` (assignment).

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

@@ -33,8 +33,14 @@ Most columns. They map 1:1 to a physical SQL column.
 
 Virtual N:1 lookup. No physical column. Always **paired with a hidden FK column** that does hold the physical data. Together they form the **FK+Reference pattern**.
 
+The example below is a **required** relation, so both halves carry `M`. For an optional
+one, drop it from both: FK `"E"`, Reference `"VE"`. `M` resolves to `isNullable: false`
+at install, so it is what makes the FK column `NOT NULL` — and while `M` is inert on the
+virtual Reference half, leaving it there over an optional FK reads as a required field to
+the next author. `dforge_entity_reference_add({ required })` emits both halves in step.
+
 ```json
-// Hidden FK column — physical, hidden
+// Hidden FK column — physical, hidden. "E" instead of "EM" if the relation is optional.
 "account_id": {
     "dbDatatype": "cuid",
     "flags": "EM",
@@ -175,9 +181,10 @@ inside one aggregate must point at the **same** set column, and `COUNT(*)` is re
 
 > ⛔ **Do not use a Formula (`F`) column for set aggregation.** `SUM([set].[field])` in an `F`
 > column is **not supported** by the engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and
-> nav resolution only walks single-hop N:1 references, never a 1:N set. The column silently renders
-> **empty** on the form, grid, and reports (no error). `F` is for same-row expressions
-> (`[qty] * [price]`) and single-hop reference navigation (`[account].[name]`) only.
+> nav resolution walks N:1 references only, never a 1:N set (however many hops it is given). The
+> column silently renders **empty** on the form, grid, and reports (no error). `F` is for same-row
+> expressions (`[qty] * [price]`) and N:1 reference navigation (`[account].[name]`, and multi-hop
+> chains — see `dforge://reference/formulas`).
 
 > ⛔ **The aggregated child column must be physical.** A `G` trigger reads the child's `OLD`/`NEW`
 > physical values, so aggregating a **virtual** child column (`F`/`R`/`S`) fails at install with

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

@@ -64,8 +64,10 @@ Only include what your module actually uses — not every module needs `print_te
 
 **Every reference to another entity is two columns**:
 
-1. Hidden FK column with `flags: "EM"` and `dbDatatype` matching the target PK type
-2. Visible Reference column with `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VEM"`, and a `link` object pointing at the target
+1. Hidden FK column with `flags: "E"` — `"EM"` when the relation is genuinely required — and `dbDatatype` matching the target PK type
+2. Visible Reference column with `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VE"` / `"VEM"` **matching the FK**, and a `link` object pointing at the target
+
+`M` resolves to `isNullable: false` at install, so it is what makes the FK column `NOT NULL` — keep the two halves in step. `dforge_entity_reference_add({ required })` emits both correctly.
 
 Plus the actual FK constraint declared in the entity's `references` block.
 

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

@@ -67,8 +67,8 @@ If none of an entity's fields are visible (or only its set/child-collection colu
 ```jsonc
 // WRONG — grid over an entity whose fields are all hidden (no "V")
 "fields": {
-    "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
+    "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
 }
 // RIGHT — at least one visible scalar field
 "fields": {

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

@@ -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 `{entity, id}` pair). Populate from action DSL with the `entityLink('entityCd', record, description?)` built-in (see `action-dsl.md`). |
+| `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`). |
 
 ## JSON
 

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

@@ -11,26 +11,54 @@ Valid flags regex: `^[VIEMH]*$`
 | `V` | Visible | Column appears in grid / form / card views. Omit to hide from standard UI. |
 | `I` | Internal | Auto-managed by the platform. Used on PK columns, audit timestamps, system fields. Not shown in UI, not directly editable by users. |
 | `E` | Editable | User can modify the value in the UI. Omit for read-only. |
-| `M` | Mandatory | Required (NOT NULL + UI enforcement). |
+| `M` | Mandatory | Required. Resolved into `isNullable: false` at install — see below. |
 | `H` | Hidden | Permanently hidden — never shown, not even in admin metadata views. Stronger than omitting `V`. |
 
 **Only these 5 letters are valid.** The platform rejects any other characters.
 
+## `M` is the platform's one notion of "required"
+
+At install, `MandatoryFlagNormalizer` folds `M` into `isNullable: false` before DDL
+generation. Everything downstream reads only `isNullable`: the `NOT NULL` in the
+generated DDL, `data.insert`'s required-column check, and the red asterisk on the
+client. There is no second signal.
+
+Four consequences worth knowing before you type a flag:
+
+- **`M` makes the column `NOT NULL`.** It is not decoration and not a UI hint. Put it
+  on a column only when a row is genuinely meaningless without the value.
+- **`M` together with `"isNullable": true` is a hard error at pack time**, naming the
+  entity and every offending field. It's a contradiction only you can resolve: drop
+  `M` if the column is optional, or drop `isNullable` if it is required.
+- **`M` is inert on virtual (`R`/`S`/`F`) and identity columns** — nullability is
+  meaningless where there is no physical column. It won't fail, but `VEM` on a
+  Reference over an *optional* FK reads as a required field to the next author, which
+  is exactly how these get out of step. Match the Reference to its FK.
+- **Adding `M` to a shipped field aborts the upgrade** on any tenant whose existing
+  rows leave it empty — rolled back, naming the column and its NULL row count. Give
+  the column a `params.serverDefault` if the install should backfill it. Removing `M`
+  is always safe.
+
+Omitting both `M` and `isNullable` leaves the column nullable — that is the default.
+
 ## Common column flag combinations
 
 | Flags | Meaning | Use case |
 |---|---|---|
-| `"VEM"` | Visible, Editable, Mandatory | Required field shown in UI (most business fields) |
-| `"VE"` | Visible, Editable, optional | Nullable field |
+| `"VEM"` | Visible, Editable, Mandatory | Required field shown in UI |
+| `"VE"` | Visible, Editable, optional | Nullable field — the common case for most business fields |
 | `"V"` | Visible, read-only | Display-only, like formula columns or computed values |
-| `"EM"` | Editable, Mandatory, **not visible** | Hidden FK columns in the FK+Reference pattern |
+| `"E"` | Editable, **not visible** | Hidden FK column of an *optional* relation |
+| `"EM"` | Editable, Mandatory, **not visible** | Hidden FK column of a *required* relation |
 | `"I"` | Internal | Trait-provided columns (PK, audit timestamps). Platform-managed. |
 | `""` (empty) | No flags | Rare — column exists but is invisible and not editable |
 
 ## Rules
 
-1. **Hidden FK columns**: always `"EM"`. They must be writeable (E) and required (M), but never shown (no V).
-2. **Visible Reference columns**: always `"VEM"`. The user sees and edits the lookup picker.
+1. **Hidden FK columns**: `"E"`, or `"EM"` when the relationship is genuinely required.
+   Writeable (E), never shown (no V). `M` here is what makes the FK `NOT NULL`.
+2. **Visible Reference columns**: `"VE"`, or `"VEM"` when the FK is required — **keep the
+   two halves in step**. `dforge_entity_reference_add({ required })` sets both for you.
 3. **Formula columns**: usually `"V"` (visible, read-only). The user never edits them.
 4. **Trait columns** (PK, audit): use `"I"` (internal). These are set automatically by `traits: ["identity", "audit"]`.
 5. **Don't use `I` on your own columns** — it's reserved for trait-provided and platform-managed columns.
@@ -68,6 +96,9 @@ These are **NOT** flag letters. They're separate properties on the column defini
 - Using `"U"` for unique — **not a valid flag**. Use `"isUnique": true` or indexes.
 - Using `"S"` for searchable — **not a valid flag**.
 - Using `"P"` for primary key — **not a valid flag**. Use `"isPk": true` or the `identity` trait.
+- Declaring `M` **and** `"isNullable": true` on the same field — a contradiction that fails the pack.
+- Reaching for `"VEM"` by default — `M` now means `NOT NULL`. Most business fields are `"VE"`.
+- Putting `M` on a Reference whose hidden FK is optional — inert, but it misreports the field as required.
 - Using `"VEM"` on trait-provided columns (PK, audit) — **don't**. Traits set their own flags (`"I"`).
 - Using `"I"` on business columns — **don't**. `I` means "platform-managed"; regular business columns use `V`/`E`/`M`.
 - Using long names like `"Visible,Editable"` — **wrong**. Single letters concatenated: `"VE"`.

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

@@ -26,6 +26,12 @@ The same grammar applies everywhere.
 `CONTAINS` / `STARTS_WITH` / `ENDS_WITH` are infix operators, not functions — write
 `[note] CONTAINS 'urgent'`, never `CONTAINS([note], 'urgent')`.
 
+**Comparison is null-safe and two-valued in every context.** `null = null` is true, and
+`[x] != null` is true for any non-null `x`. There is no SQL-style third "unknown" answer,
+so `IF([completed_date] != null, 100, 0)` gives the same result on the record card and in
+a report. At SQL time `=` / `!=` translate to `IS NOT DISTINCT FROM` / `IS DISTINCT FROM`
+to preserve that.
+
 ## Examples
 
 ```
@@ -156,8 +162,9 @@ like any other boolean. A bare `date` column is treated as a **local calendar da
 - `AVG`, `MIN`, `MAX` similarly
 
 > ⚠️ **Set aggregation is NOT a Formula (`F`) feature.** `SUM([set].[field])` in an `F` column is
-> unsupported by the engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and nav resolution
-> only walks single-hop N:1 references, never a 1:N set. It silently renders **empty** (no error).
+> unsupported by **either** engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and nav
+> resolution walks N:1 references only, never a 1:N set, however many hops it is given. It
+> silently renders **empty** (no error).
 
 Put set aggregations in a **Generated (`G`) column** instead. The installer detects the set
 navigation and maintains the value with a database trigger on the child table. The aggregated
@@ -186,9 +193,20 @@ and the JSON shape: `column-types.md` → "Roll-up totals over child rows — us
 [account].[primary_contact].[phone]      -- chained
 ```
 
-Navigation works through `columnType: "R"` columns (reference columns). Chains of length 1 are **synchronous** and resolved instantly. Chains of length ≥ 2 are **asynchronous** — the formula engine resolves them after the initial data load.
+Navigation works through `columnType: "R"` columns (reference columns) — every step except the last must be a Reference, and the last reads a field on the final referenced record. Chains of length 1 are **synchronous** and resolved instantly. Chains of length ≥ 2 are **asynchronous** — the formula engine resolves them after the initial data load.
+
+**SQL-time (reports, filters, sorts).** Multi-hop navigation works here too: QueryBuilder pre-scans the formula and registers one `LEFT JOIN` per hop, then the translator resolves the path against the final alias. A nav path may also land on a *formula* column of the referenced entity — that formula is translated against the referenced entity's alias, and its own hops are joined off that alias. The same nav map drives formula columns in filters and ORDER BY, so filtering and sorting a report by a nav-formula column works.
+
+Hops are counted from the query's **root** entity and capped at `MaxNavigationDepth`, whether they come from a dotted column, a formula's own navigation, or the combination — so the hops spent reaching a formula reduce the budget left for that formula's own navigation.
+
+Still unavailable at SQL time — the column comes back NULL and the **response carries a warning** naming the column and the reason:
+
+- Settings references `$[SettingName]`
+- Navigation past the hop cap
+- **Extension-table columns** — a column an extension module added lives in a separate 1:1 ext table needing its own JOIN, and every alias the translator emits is the entity's own base alias. Applies to the hidden FK and to the Reference built on it, on the query's own entity as well as a referenced one
+- **Misauthored nav paths** — a final segment that isn't a column of the referenced entity, or a dot after something that isn't a Reference (`account.account_name.foo`)
 
-**SQL-time (reports, filters, sorts):** single-hop navigation (`[ref].[field]`) is translated to a `LEFT JOIN` and computes in reports and query datasets. Multi-hop chains and `$[Setting]` references are **not** available at SQL time — the column returns NULL there and the response carries a warning naming the column. Keep report-bound formulas to single-hop navigation.
+Warning wording follows the clause, because the same unresolvable path costs a different thing in each: a SELECT slot goes NULL (*"could not be computed and will be empty"*), an ORDER BY term is dropped so rows come back in a different order (*"Sorting by … was skipped"*), and a WHERE condition is dropped so **more** rows come back than were asked for (*"Filter on … was ignored"*). Untranslatable formula filters are never dropped silently.
 
 ## Sync vs async formulas
 

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

@@ -79,8 +79,10 @@ If the source uses non-standard audit column names (e.g. `date_created`, `modifi
 
 For each FK, create **two columns** following the FK+Reference pattern:
 
-1. Hidden FK column: `flags: "EM"`, matching `dbDatatype`
-2. Visible Reference column: `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VEM"`, with `link`
+1. Hidden FK column: `flags: "E"` — `"EM"` only when the source column is `NOT NULL` — matching `dbDatatype`
+2. Visible Reference column: `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags` **matching the FK** (`"VE"` / `"VEM"`), with `link`
+
+`M` resolves to `isNullable: false` at install, so carrying it onto an FK the source declares nullable would import the column as `NOT NULL`. `dforge_dbml_import` / `dforge_module_import` take `M` from the source's own nullability.
 
 Plus declare the constraint in the entity's `references` block.
 

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

@@ -42,8 +42,9 @@ For each entity:
 ### FK+Reference pattern
 
 - [ ] Every reference column (`columnType: "R"`) has a paired hidden FK column
-- [ ] The hidden FK column has `flags: "EM"` (not `V`, not `I`)
-- [ ] The reference column has `flags: "VEM"`, `fieldTypeCd: "lookup"`, and a `link` object
+- [ ] The hidden FK column has `flags: "E"` — `"EM"` only if the relation is required (not `V`, not `I`)
+- [ ] The reference column has `flags` **matching the FK** (`"VE"` / `"VEM"`), `fieldTypeCd: "lookup"`, and a `link` object
+- [ ] No field declares `M` together with `"isNullable": true` — that combination fails the pack
 - [ ] `link.entity` points to an entity that exists (in this module or a dependency)
 - [ ] `link.thisKey` matches the FK column name on this entity
 - [ ] `link.otherKey` matches the PK column name on the target entity

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

@@ -57,8 +57,10 @@ Enough to author inline; load the linked reference for the full detail.
 - **A relation is TWO columns + a references entry.** Use
   `dforge_entity_reference_add` — it emits all three parts. → `column-types`
 - **Flags** are letters from `V I E M H` only (never `U`/`S`/`P`): `VEM`
-  required+visible, `VE` optional+visible, `V` read-only, `EM` hidden FK, `I`
-  trait-provided. → `flags`
+  required+visible, `VE` optional+visible, `V` read-only, `E`/`EM` hidden FK
+  (optional/required), `I` trait-provided. `M` means required — it resolves to
+  `isNullable: false`, so it makes the column `NOT NULL`; don't spend it as
+  decoration, and never pair it with `"isNullable": true`. → `flags`
 - **`fieldTypeCd` = UI control; `dbDatatype` = SQL type.** Omit `dbDatatype` on
   plain data columns — it's derived. Set it only for a hidden FK or to override
   size/precision. Common fixes: `number` not `integer`/`float`; `phone` not
@@ -168,9 +170,14 @@ to fill a sub-step** — a pure CRUD module skips Phase 2 entirely (record it wi
 | 2c Jobs | a cron timer fires | `dforge_job_add` |
 | 2d Webhooks | a DB event → outbound POST | `dforge_webhook_add` |
 
-**2a Actions.** Load all four resources in the action row — the wrong-field-
-access / wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only
-surface when you cross-check them. Draft the DSL, run
+**2a Actions.** First check the action is an action at all: it must **change**
+something. If the `execute:` block would only read, compute and `info()` the
+answer, build a report, a formula column, or an action that writes a result
+record instead — a printed number is never stored and can't be re-read
+(`dforge://reference/action-dsl`, *When an action is the wrong tool*). Then load
+all four resources in the action row — the wrong-field-access /
+wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only surface when
+you cross-check them. Draft the DSL, run
 **`dforge_action_check({ dslBody, executionMode })`** to catch install failures
 before committing, then `dforge_action_add`. One action per turn.