@dforge-core/dforge-mcp 0.2.15 → 0.2.17

package/resources/schemas/entity.schema.json

@@ -95,10 +95,88 @@
 				}
 			},
 			"additionalProperties": true
+		},
+		"views": {
+			"type": "object",
+			"description": "Entity views keyed by view name — column-level security. Unrelated to 'isView'/'viewSql' (a SQL-view-backed entity) and to ui/data_views.json (grids, kanban, calendars). A folder binds one view per entity via ui/folders.json (entities.<code>.viewName); users working in that folder see ONLY the columns the view lists. Entities without views (or folders naming a view that isn't declared here) show the entity's full column set.",
+			"propertyNames": {
+				"pattern": "^[a-zA-Z_][a-zA-Z0-9_-]*$",
+				"maxLength": 100
+			},
+			"additionalProperties": {
+				"$ref": "#/$defs/entityView"
+			}
 		}
 	},
 	"additionalProperties": false,
 	"$defs": {
+		"entityView": {
+			"type": "object",
+			"description": "One entity view: the columns it exposes, plus optional per-view overrides on each.",
+			"required": ["columns"],
+			"properties": {
+				"columns": {
+					"type": "object",
+					"description": "Column code -> per-view overrides. Columns absent from this map are hidden in a folder bound to this view. Use {} (or null) to expose a column with no overrides. Must include the entity's primary key column(s) — records are addressed by them; hide the key from the UI by omitting 'V' from its flags instead.",
+					"minProperties": 1,
+					"propertyNames": {
+						"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+					},
+					"additionalProperties": {
+						"$ref": "#/$defs/entityViewColumn"
+					}
+				},
+				"params": {
+					"type": "object",
+					"description": "Free-form view configuration, stored on entity_view.params.",
+					"additionalProperties": true
+				}
+			},
+			"additionalProperties": false
+		},
+		"entityViewColumn": {
+			"description": "Per-view overrides for one column. Every property is optional; anything omitted falls back to the entity-level value on the column itself.",
+			"type": ["object", "null"],
+			"properties": {
+				"flags": {
+					"type": "string",
+					"maxLength": 10,
+					"pattern": "^[VIEM]*$",
+					"description": "Flag letters for this column in this view — the same V/I/E/M vocabulary as a field's 'flags'. One rule, three cases: OMIT the key to inherit the entity-level flags (omission is the only inherit spelling — this field is a string, so a literal null does not validate; to inherit everything, set the whole column override to null or {}); any string, empty included, OVERRIDES them, because the runtime merges view over entity with COALESCE, which skips a missing value only; and a non-empty string REPLACES the entity letters rather than merging with them. So 'V' exposes the column read-only (visible, not editable) however the entity flagged it, and '' means 'no flags here' — neither visible nor editable. M works here as it does on a field: the installer folds it into this override's isNullable, making the column required IN THIS VIEW even when it is nullable in the database (a view writes no DDL, so the requiredness is runtime-only). Declaring M together with \"isNullable\": true is rejected at pack time. Note the fold is one-directional — DROPPING M from a view's flags does not make a column optional, because isNullable still COALESCEs to the entity value; write \"isNullable\": true to loosen it."
+				},
+				"orderNum": {
+					"type": "integer",
+					"description": "Display order within this view."
+				},
+				"isNullable": {
+					"type": "boolean",
+					"description": "Nullability override for this view."
+				},
+				"editMask": {
+					"type": "string",
+					"maxLength": 100
+				},
+				"displayFmt": {
+					"type": "string",
+					"maxLength": 100
+				},
+				"refFilter": {
+					"type": "object",
+					"description": "Lookup filter override for a reference column in this view.",
+					"additionalProperties": true
+				},
+				"formula": {
+					"type": "string",
+					"description": "Formula override for this column in this view, in the same DSL as a field's 'formula'. Allowed only on a column the entity declares as columnType 'F'; on any other column the install FAILS (it does not silently ignore the override), because there that field holds the SQL default and a view cannot change a physical column's DEFAULT. There is no per-view default value for a normal column today. The runtime prefers it over the entity-level formula, so one view can compute a column differently from the entity. The parsed AST is regenerated at install; a formula that does not parse, calls an unimplemented function, or aggregates over a 1:N set fails the install (each renders empty at runtime)."
+				},
+				"params": {
+					"type": "object",
+					"description": "Control-specific configuration override for this view.",
+					"additionalProperties": true
+				}
+			},
+			"additionalProperties": false
+		},
 		"field": {
 			"type": "object",
 			"description": "Entity column/field definition",
@@ -129,8 +207,8 @@
 				},
 				"flags": {
 					"type": "string",
-					"pattern": "^[VIEMH]*$",
-					"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."
+					"pattern": "^[VIEM]*$",
+					"description": "Column flags, in any order. V=Visible and E=Editable are display/interaction; I=Identity marks a platform-managed column (never user-editable, excluded from required validation); M=Mandatory is not a runtime flag at all — it is resolved into isNullable:false at install, so it makes the column NOT NULL, is inert on virtual (R/S/F) and identity columns, and declaring it together with isNullable:true is rejected at pack time. Any other letter is rejected at pack time; there is no H flag — a column is hidden by omitting V."
 				},
 				"isPk": {
 					"type": "boolean",

package/resources/schemas/folders.schema.json

@@ -58,7 +58,7 @@
 			"properties": {
 				"viewName": {
 					"type": "string",
-					"description": "Entity view name (data view code) to use in this folder. Common values include 'default'."
+					"description": "Entity view to bind for this entity in this folder — the name of a key under the entity definition's 'views' (column-level security), NOT a data view code from ui/data_views.json. Users in this folder then see only the columns that view lists. The conventional 'default' declares nothing and means 'no view' (full column set); any other name that the entity does not declare fails the install."
 				},
 				"quickAdd": {
 					"type": "boolean",

package/resources/schemas/manifest.schema.json

@@ -49,7 +49,7 @@
 		},
 		"schemaName": {
 			"type": "string",
-			"description": "Database schema name override (defaults to module code, system modules use 'dForge')"
+			"description": "Database schema name override (defaults to module code, system modules use 'dForge'). Do NOT share one schema between modules that extend other modules' entities: an extension's columns live in \"{schemaName}\".\"{entity}_ext\", named for the schema rather than the module, and nothing records which module wrote a column — so install rejects a module that both shares its schema with another installed module and declares 'extends'. Leave unset (the module code, which is unique) for bridge modules."
 		},
 		"system": {
 			"type": "boolean",

package/resources/schemas/menus.schema.json

@@ -23,7 +23,7 @@
 				"folders": {
 					"type": "array",
 					"items": { "type": "string" },
-					"description": "Folder codes where this menu is available"
+					"description": "Flat folder codes this menu is linked to (module code for the root, module code + '_' + each nesting segment for children, e.g. 'logistics_all_trips'; the full path, the module-relative path, and a folder's own key when unique in the tree also resolve). Omit to link the menu to every folder the module declares. Scopes the folder-to-menu link only — every folder in ui/folders.json is created either way. A code matching no folder, or a key two branches share, fails the install."
 				},
 				"items": {
 					"type": "object",

package/resources/schemas/triggers.schema.json

@@ -50,7 +50,7 @@
 				"async": {
 					"type": "boolean",
 					"default": true,
-					"description": "When true (the default), the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller — so an async:false trigger can undo the user's write. Keep async:false actions fast; they run on the request's transaction."
+					"description": "When true (the default), the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller — so an async:false trigger can undo the user's write. That holds for a trigger on ANOTHER module's entity too (the bridge shape): a bridge can veto its host's write, the same way a mandatory extension column already refuses one. Use it to enforce an invariant, not merely to react — the error names the blocking module and trigger (code TRIGGER_ACTION_FAIL), and a bug in the action blocks the host's workflow just as effectively as a real violation. Keep async:false actions fast; they run on the request's transaction."
 				}
 			},
 			"additionalProperties": false

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

@@ -0,0 +1,67 @@
+# column-security — entity views example
+
+A minimal module whose only job is to demonstrate **entity views**: dForge's
+column-level security. One `product` entity holds both stock and pricing, and two
+folders show two different column sets of it.
+
+## The shape
+
+Column-level security is always **two halves**, and both are required:
+
+| Piece | File | Effect |
+|---|---|---|
+| The column set | `entities/product.json` → `views` | Declares `storekeeper` and `accountant` — each a named subset of the entity's columns |
+| The binding | `ui/folders.json` → `entities.product.viewName` | The Warehouse folder binds `storekeeper`, the Finance folder binds `accountant` |
+
+```
+product columns:  name  sku  quantity  cost_price  sale_price  margin
+
+Warehouse folder → view "storekeeper":  name  sku  quantity
+Finance folder   → view "accountant":   name  sku  quantity(read-only)  cost_price  sale_price  margin
+```
+
+A user working in Warehouse cannot see `cost_price` **at all** — not on screen, not
+through a filter, not in an export. The columns a view omits are invisible *and*
+unqueryable there. That is the mechanism: omission is the restriction.
+
+## What each view demonstrates
+
+- **`storekeeper`** — the plain case: list the columns this folder may see, and no
+  others. Note it still lists `product_id`; a view must include the primary key
+  because records are addressed by it.
+- **`accountant`** — the override cases:
+  - `"quantity": { "flags": "V" }` — visible but **not** editable here, while the
+    entity itself declares `VEM`. A per-column `flags` override re-flags the column
+    for the folders bound to this view only.
+  - `"margin": { "formula": "…", "displayFmt": "N1" }` — a per-view **formula**
+    override: the entity computes margin as an absolute amount, this view computes it
+    as a percentage. Allowed only because `margin` is a `columnType: "F"` column — on
+    any other column that field holds the SQL default, so the override would be inert
+    and the install rejects it.
+
+## Things that would fail the install
+
+Worth knowing, because each one is silent at runtime if it slips through:
+
+- Dropping `product_id` from a view — records the client cannot open or save.
+- A view with **no** columns, or a column code the entity doesn't have.
+- Two views whose names differ only by case — a folder binds case-insensitively, so
+  only one could ever be reached.
+- A `viewName` in `folders.json` that no view declares. This does **not** fall back:
+  the fallback would be the entity's full column set, so a typo would quietly
+  *unrestrict* the folder. `"default"` is the one exempt name and means "no view".
+
+`dforge_module_validate` checks all of these offline, before packing.
+
+## What this example deliberately leaves out
+
+The `product_grid` data view lists **every** column, including the prices. That is
+correct: a data view describes the presentation, and the folder's entity view decides
+what a user in that folder is allowed to see of it. The grid renders whichever
+columns survive the view — you do not maintain one data view per role.
+
+Entity views are also unrelated to the two other things called "view" here: a *data
+view* (`ui/data_views.json`) is a grid/kanban/calendar, and `isView` + `viewSql` on an
+entity means it is backed by a SQL view.
+
+See `dforge://reference/security` → Column-level security for the full rules.

package/skills/dforge-mcp-author/examples/column-security/entities/product.json

@@ -0,0 +1,79 @@
+{
+	"description": "Products, with stock and pricing on one record",
+	"dbObject": "product",
+	"toString": "{name}",
+	"traits": ["identity", "audit"],
+	"fields": {
+		"name": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "text",
+			"flags": "VEM",
+			"maxLen": 200,
+			"orderNum": 10,
+			"description": "Product Name"
+		},
+		"sku": {
+			"dbDatatype": "varchar",
+			"fieldTypeCd": "text",
+			"flags": "VEM",
+			"maxLen": 40,
+			"orderNum": 20,
+			"description": "SKU"
+		},
+		"quantity": {
+			"dbDatatype": "numeric(18,2)",
+			"fieldTypeCd": "number",
+			"flags": "VEM",
+			"precision": 2,
+			"orderNum": 30,
+			"description": "Quantity On Hand"
+		},
+		"cost_price": {
+			"dbDatatype": "numeric(18,2)",
+			"fieldTypeCd": "currency",
+			"flags": "VEM",
+			"precision": 2,
+			"orderNum": 40,
+			"description": "Cost Price"
+		},
+		"sale_price": {
+			"dbDatatype": "numeric(18,2)",
+			"fieldTypeCd": "currency",
+			"flags": "VEM",
+			"precision": 2,
+			"orderNum": 50,
+			"description": "Sale Price"
+		},
+		"margin": {
+			"columnType": "F",
+			"fieldTypeCd": "currency",
+			"baseDatatypeCd": "number",
+			"flags": "V",
+			"precision": 2,
+			"formula": "[sale_price] - [cost_price]",
+			"orderNum": 60,
+			"description": "Margin"
+		}
+	},
+	"views": {
+		"storekeeper": {
+			"columns": {
+				"product_id": {},
+				"name": {},
+				"sku": {},
+				"quantity": {}
+			}
+		},
+		"accountant": {
+			"columns": {
+				"product_id": {},
+				"name": {},
+				"sku": {},
+				"quantity": { "flags": "V" },
+				"cost_price": {},
+				"sale_price": {},
+				"margin": { "formula": "([sale_price] - [cost_price]) / [sale_price] * 100", "displayFmt": "N1" }
+			}
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/manifest.json

@@ -0,0 +1,23 @@
+{
+	"packageFormat": 1,
+	"moduleId": "20000000-0000-0000-0000-000000000003",
+	"code": "column_security",
+	"version": "0.1.0",
+	"dbSchemaVersion": "0.0.1",
+	"displayName": "Column Security",
+	"description": "Example module demonstrating entity views — column-level security",
+	"author": { "name": "dForge Examples" },
+	"license": "MIT",
+	"category": "Examples",
+	"tags": ["example", "security", "entity-views"],
+	"icon": "bi-eye-slash",
+	"dependencies": {
+		"admin": ">=0.0.1"
+	},
+	"supportedLocales": ["en-US"],
+	"created": "2026-08-19",
+	"updated": "2026-08-19",
+	"entities": {
+		"product": "./entities/product.json"
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/security/roles.json

@@ -0,0 +1,16 @@
+{
+	"column_security.storekeeper": {
+		"description": "Counts stock; never sees cost or price",
+		"rights": {
+			"product": "SIU",
+			"folder:warehouse": "E"
+		}
+	},
+	"column_security.accountant": {
+		"description": "Owns costing and pricing",
+		"rights": {
+			"product": "SIU",
+			"folder:finance": "E"
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/translations/en-US.json

@@ -0,0 +1,35 @@
+{
+	"entities": {
+		"product": {
+			"label": "Product",
+			"fields": {
+				"name": { "label": "Product Name" },
+				"sku": { "label": "SKU" },
+				"quantity": { "label": "Quantity On Hand" },
+				"cost_price": { "label": "Cost Price" },
+				"sale_price": { "label": "Sale Price" },
+				"margin": { "label": "Margin" }
+			}
+		}
+	},
+	"folders": {
+		"warehouse": { "label": "Warehouse" },
+		"finance": { "label": "Finance" }
+	},
+	"roles": {
+		"column_security.storekeeper": { "label": "Storekeeper" },
+		"column_security.accountant": { "label": "Accountant" }
+	},
+	"views": {
+		"product_grid": { "label": "Products" }
+	},
+	"menus": {
+		"product_menu": {
+			"label": "Products",
+			"items": {
+				"catalog": { "label": "Catalog" },
+				"all_products": { "label": "Products" }
+			}
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/ui/data_views.json

@@ -0,0 +1,20 @@
+{
+	"product_grid": {
+		"label": "Products",
+		"description": "One grid, two column sets — whichever the folder's entity view allows",
+		"viewType": "grid",
+		"icon": "bi-box-seam",
+		"dataSources": [{
+			"entityCode": "product",
+			"columns": [
+				{ "column_cd": "name", "width": 240 },
+				{ "column_cd": "sku", "width": 120 },
+				{ "column_cd": "quantity", "width": 120 },
+				{ "column_cd": "cost_price", "width": 120 },
+				{ "column_cd": "sale_price", "width": 120 },
+				{ "column_cd": "margin", "width": 120 }
+			],
+			"order": ["name"]
+		}]
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/ui/folders.json

@@ -0,0 +1,23 @@
+{
+	"label": "Products",
+	"description": "Product master data",
+	"icon": "bi-box-seam",
+	"children": {
+		"warehouse": {
+			"label": "Warehouse",
+			"description": "Stock keeping — no pricing",
+			"color": "#0ea5e9",
+			"entities": {
+				"product": { "viewName": "storekeeper", "quickAdd": true }
+			}
+		},
+		"finance": {
+			"label": "Finance",
+			"description": "Costing and pricing",
+			"color": "#f59e0b",
+			"entities": {
+				"product": { "viewName": "accountant", "quickAdd": false }
+			}
+		}
+	}
+}

package/skills/dforge-mcp-author/examples/column-security/ui/menus.json

@@ -0,0 +1,21 @@
+{
+	"product_menu": {
+		"label": "Products",
+		"items": {
+			"catalog": {
+				"orderNum": 1,
+				"label": "Catalog",
+				"icon": "box-seam",
+				"children": {
+					"all_products": {
+						"itemType": "V",
+						"label": "Products",
+						"icon": "box-seam",
+						"dataViewCode": "product_grid",
+						"orderNum": 1
+					}
+				}
+			}
+		}
+	}
+}

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

@@ -6,10 +6,15 @@
 	"dbSchemaVersion": "0.0.1",
 	"displayName": "Simple Todo",
 	"description": "Minimal example module demonstrating the dForge package format",
-	"author": { "name": "dForge Examples" },
+	"author": {
+		"name": "dForge Examples"
+	},
 	"license": "MIT",
 	"category": "Examples",
-	"tags": ["example", "todo"],
+	"tags": [
+		"example",
+		"todo"
+	],
 	"icon": "bi-check-square",
 	"dependencies": {
 		"admin": ">=0.0.1"
@@ -19,14 +24,5 @@
 	"entities": {
 		"todo_list": "./entities/todo_list.json",
 		"todo_item": "./entities/todo_item.json"
-	},
-	"dataViews": "./ui/data_views.json",
-	"menus": "./ui/menus.json",
-	"actions": "./ui/actions.json",
-	"security": {
-		"roles": "./security/roles.json"
-	},
-	"seedData": [
-		"./seed-data/01-lists.json"
-	]
+	}
 }

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

@@ -36,8 +36,9 @@ Virtual N:1 lookup. No physical column. Always **paired with a hidden FK column*
 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.
+virtual Reference half (at the entity level; a per-view override behaves differently, see
+`flags.md`), 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. "E" instead of "EM" if the relation is optional.

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

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

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

@@ -2,19 +2,21 @@
 
 Column flags are single-letter codes concatenated into a string. Order doesn't matter — `"VEM"` and `"EMV"` are equivalent.
 
-Valid flags regex: `^[VIEMH]*$`
+Valid flags regex: `^[VIEM]*$`
 
 ## Flag letters
 
 | Letter | Name | Meaning |
 |---|---|---|
 | `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. |
+| `I` | Identity | Auto-managed by the platform. Used on PK columns, audit timestamps, system fields. Not shown in UI, not directly editable by users, excluded from required validation. |
 | `E` | Editable | User can modify the value in the UI. Omit for read-only. |
 | `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.
+**Only these 4 letters are valid.** The platform rejects any other characters.
+> **There is no `H` flag.** Earlier drafts listed one, described as "stronger than omitting `V`", and nothing ever read it — a column with `flags: "H"` is hidden because the string contains no `V`, not because it contains `H`. To hide a column, omit `V`. To hide it from specific folders (and make it unqueryable there), use an entity view. To render it as a hidden input, use `fieldTypeCd: "hidden"`.
+
+> **The same letters override per entity view.** `views.<v>.columns.<cd>.flags` re-flags a column for the folders bound to that view, while the entity keeps its own flags everywhere else. Same `^[VIEM]*$` vocabulary — see "Per-view overrides" below. See `security.md` → Column-level security.
 
 ## `M` is the platform's one notion of "required"
 
@@ -31,7 +33,8 @@ Four consequences worth knowing before you type a flag:
   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
+  meaningless where there is no physical column. (At the *entity* level; a per-view
+  override behaves differently — see "Per-view overrides".) 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
@@ -41,6 +44,33 @@ Four consequences worth knowing before you type a flag:
 
 Omitting both `M` and `isNullable` leaves the column nullable — that is the default.
 
+## Per-view overrides
+
+`views.<v>.columns.<cd>.flags` re-flags one column for the folders bound to that view. The letters are the same four, and `M` means the same thing — the installer folds it into **that override's** `isNullable`.
+
+Because a view writes no DDL, the requiredness `M` produces there is runtime-only. That is how you express **"nullable in the database, mandatory in this view"**, which no entity-level flag can say:
+
+```json
+"views": {
+  "compliance": {
+    "columns": {
+      "party_id": {},
+      "party_name": { "flags": "V" },
+      "vat_no":     { "flags": "VEM" },
+      "salary":     { "flags": "" }
+    }
+  }
+}
+```
+
+Three rules to keep straight:
+
+- **The letters replace, they don't merge.** The cascade is `COALESCE(view, entity)`. A non-empty string wins outright, so `{ "flags": "V" }` is read-only there however the entity flagged the column.
+- **`""` is a real value, omission is not.** An empty string means "no flags here" — neither visible nor editable. To inherit, leave the key out; `"flags": null` fails schema validation, since the property is typed `string`. (To inherit *everything*, set the whole column override to `{}` or `null`.)
+- **The `M` fold is one-directional.** Dropping `M` from a view's flags does NOT make the column optional — `isNullable` still `COALESCE`s to the entity value. Write `"isNullable": true` to loosen it, and only where the database actually allows null, or the save trades a clean validation error for a raw constraint violation.
+
+Unlike the entity level, `M` here is *not* inert on virtual or identity columns: the fold only reaches the runtime required check, so a view can mark a Reference required. (Identity columns stay excluded — they are never asked of the user.)
+
 ## Common column flag combinations
 
 | Flags | Meaning | Use case |
@@ -50,7 +80,7 @@ Omitting both `M` and `isNullable` leaves the column nullable — that is the de
 | `"V"` | Visible, read-only | Display-only, like formula columns or computed values |
 | `"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. |
+| `"I"` | Identity | Trait-provided columns (PK, audit timestamps). Platform-managed. |
 | `""` (empty) | No flags | Rare — column exists but is invisible and not editable |
 
 ## Rules
@@ -60,9 +90,9 @@ Omitting both `M` and `isNullable` leaves the column nullable — that is the de
 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"]`.
+4. **Trait columns** (PK, audit): use `"I"` (identity). 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.
-6. **Don't mix `I` with `V` or `E`** — internal columns are not user-facing.
+6. **Don't mix `I` with `V` or `E`** — identity columns are not user-facing.
 
 ## Entity rights flags (different namespace — roles only)
 
@@ -79,7 +109,7 @@ These letters appear in role `rights` declarations, **NOT** on column flags. Don
 
 So `"SIUD"` on a role grants full CRUD; `"SI"` grants read + create only.
 
-**Note**: the `I` in column flags (Internal) and the `I` in role rights (Insert) are different concepts using the same letter. Context makes them unambiguous — column flags go on entity fields, role rights go on `security/roles.json`.
+**Note**: the `I` in column flags (Identity) and the `I` in role rights (Insert) are different concepts using the same letter. Context makes them unambiguous — column flags go on entity fields, role rights go on `security/roles.json`.
 
 ## How uniqueness, PKs, and search work
 
@@ -101,4 +131,6 @@ These are **NOT** flag letters. They're separate properties on the column defini
 - 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`.
+- Expecting a per-view `{ "flags": "VE" }` to make a column **optional** because it drops `M` — it doesn't. `isNullable` still inherits; write `"isNullable": true`.
+- Writing `"flags": null` in a view override to inherit — fails validation. Omit the key.
 - Using long names like `"Visible,Editable"` — **wrong**. Single letters concatenated: `"VE"`.

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

@@ -3,6 +3,13 @@
 Formulas are used in:
 
 - **Formula columns** (`columnType: "F"`) — computed values
+- **Per-view formula overrides** (`views.<v>.columns.<cd>.formula`) — one entity view
+  computing a column differently from the entity. Allowed **only** on a column the
+  entity declares as `columnType: "F"`; on any other column the install FAILS, because
+  there that field holds the SQL default and a view cannot change a physical column's
+  `DEFAULT`. (There is no per-view default value for a normal column.) Same rules as an
+  `F` column otherwise: it must parse, call only implemented functions, and not
+  aggregate over a 1:N set. See `security.md` → Column-level security.
 - **Action `canExecute:` blocks** — availability checks. Evaluated on both sides
   and **enforced** by `action.execute`, but only over a narrow subset: comparisons
   between fields and literals combined with `AND` / `OR` / `NOT`. Functions,