@dforge-core/dforge-mcp 0.2.15 → 0.2.16

package/CHANGELOG.md

@@ -4,6 +4,162 @@ 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.16
+
+Entity views — the platform's **column-level security** — became reachable from a
+module package (platform change `e6e29b604`). A view is a named subset of an
+entity's columns declared under `views` on the entity file; a folder binds one per
+entity with `entities.<code>.viewName`, and users working there see only the
+columns that view lists. The schema had gained the property while nothing here
+knew about it, so authoring one meant an editor error on valid metadata and a
+refactor that could quietly break the module.
+
+### Added — entity views are validated offline
+
+`dforge_module_validate` now mirrors what the platform installer rejects, all of
+which is silent at runtime if it slips through:
+
+| Check | Why it matters |
+|---|---|
+| Column exists on the entity | A stale name is simply not in the view |
+| View lists the primary key | Records are addressed by it — the client cannot open a row without it |
+| View has at least one column | A view is the COMPLETE visible set, so an empty one would hide every field |
+| No two views differing only by case | A folder binds case-insensitively; only one could ever be reached |
+| No column listed twice under different casing | Both name one column and the later would silently win |
+| `formula` override only on a `columnType: "F"` column | Elsewhere that field is the SQL default and the install FAILS — a view cannot change a physical column's `DEFAULT` |
+| `folders.json` `viewName` resolves to a declared view | **Fails the install** — it does not fall back, because falling back shows every column |
+
+`"default"` is exempt from the last check and means "no view": every shipped module
+writes it, and the platform auto-creates a column-less row under that name for any
+entity reached without a folder binding.
+
+### Fixed — refactors reach into views
+
+`dforge_entity_field_rename` and `dforge_entity_field_remove` rewrote fields, links,
+formulas, data views and seed data but never touched `views.<v>.columns.<cd>`. Since
+the platform now rejects a view naming a column the entity does not have, a rename
+handed back a module that no longer installs. Both cascade into entity views now,
+including per-view `formula` overrides, preserving the view's column order (which is
+its display order). Removal warns when a view is left with no columns, or when a
+per-view formula still names a removed field — the same judgement-call warnings the
+tool already emitted for entity formulas.
+
+### Fixed — `viewName` was documented as a data view code
+
+It is not, and the mistake ran from `schemas/folders.schema.json` through
+`references/security.md` to `dforge-module-build`'s Phase 3, which claimed
+`"default"` was "a fallback alias the platform resolves to the entity's first
+declared view". It resolves to *no view* (the full column set), and any other
+undeclared name now fails the install — so the wrong mental model produced a hard
+error rather than a shrug. Data view codes are what a menu's `dataViewCode`
+references.
+
+### Changed
+
+- `@dforge-core/metadata` → `0.0.18`; `resources/schemas/` re-vendored, so
+  `entity.schema.json` carries `views` (with the per-column `formula` override), the
+  retired `H` flag and the per-view `M` fold below, and the editor stops flagging a
+  valid `views` block as an unknown property. The
+  `minimumReleaseAgeExclude` pin in `pnpm-workspace.yaml` moves with it — a caret on
+  a `0.0.x` version pins the patch, so the dep does not float onto a new metadata
+  release by itself.
+- `references/security.md` gains a **Column-level security** section — the layer the
+  3-layer model named but never documented — with the rules, the empty-override trap
+  (`COALESCE` skips NULL only, so `"flags": ""` means "no flags", not "inherit"), and
+  a table disambiguating the platform's three "views": entity views, data views, and
+  `isView`/`viewSql` SQL-backed entities.
+- Cross-references in `references/flags.md` (the same letters override per view),
+  `references/formulas.md` (the per-view override and its `"F"`-only rule) and
+  `references/data-views.md` (the name collision); two new lines in
+  `references/validation-checklist.md`; `dforge-module-build` Phase 5 gains guidance
+  on when column-level security is the right answer instead of more roles.
+- `dforge_module_inspect` reports `entityViews` per entity (name → column count).
+
+### Removed — the `H` flag
+
+`H` was in the flag vocabulary from the start, documented as "permanently hidden —
+stronger than omitting `V`", and **nothing ever read it**. A column carrying it was
+hidden because its flags string contained no `V`. The platform retired it
+(`abbedb009`), so `field-rules` now rejects `H` with a message pointing at the fix
+rather than at the generic "U/S/P are not flag letters" hint: omit `V` to hide a
+column, use an entity view to hide it from specific folders, `fieldTypeCd: "hidden"`
+to render it as a hidden input, and `I` to mark it platform-managed.
+
+`references/flags.md` and the `dforge://reference/flags` blurb drop it too, and both
+`^[VIEMH]+$` checks in `field-rules` are now `^[VIEM]+$`.
+
+### Added — `M` in a per-view override
+
+`views.<v>.columns.<cd>.flags` previously accepted `M` and did nothing with it: the
+platform's `MandatoryFlagNormalizer` folded `M` into `isNullable` for entity fields
+only. The fold now covers view overrides, so the shorthand means the same thing at
+both levels — and because a view writes no DDL, the requiredness it produces is
+runtime-only. That makes **"nullable in the database, mandatory in this view"**
+expressible for the first time:
+
+```json
+"vat_no": { "flags": "VEM" }                      // required in this view
+"vat_no": { "flags": "VE", "isNullable": false }  // the same thing, spelled out
+```
+
+`references/flags.md` gains a **Per-view overrides** section covering it, plus the
+two traps that come with it: the letters **replace** rather than merge (so
+`{ "flags": "V" }` is read-only however the entity flagged the column), and the `M`
+fold is **one-directional** — dropping `M` from a view does not make a column
+optional, since `isNullable` still inherits. `references/security.md` picks up the
+same note.
+
+### Fixed — smaller documentation corrections
+
+- **`I` was called "Internal" throughout `references/flags.md`.** The runtime reads
+  it as **Identity** (`EntityColumn.IsIdentity => HasFlag('I')`); the letter is
+  unchanged, the name was wrong in the letter table, two rules and the role-rights
+  disambiguation note.
+- **`"flags": null` was implied to mean "inherit".** It does not validate — the
+  property is typed `string`, so only OMITTING the key inherits. (To inherit
+  everything, set the whole column override to `{}` or `null`.)
+
+### Added — a worked example module
+
+`examples/column-security/` (served as `dforge://example/column-security/…`): one
+`product` entity carrying both stock and pricing, two folders showing two different
+column sets of it. It is the first bundled example with a `ui/folders.json` at all,
+so the *binding* half of column-level security had no example anywhere before.
+
+Its `accountant` view demonstrates both override kinds — `{ "flags": "V" }` making a
+column read-only in that view only, and a per-view `formula` computing margin as a
+percentage where the entity computes an amount — while `storekeeper` shows the plain
+case where the price columns are simply absent. The README lists the five ways a view
+fails the install, and a test pins the module at zero errors AND zero warnings, since
+a warning copied out of an example propagates into every module built from it.
+
+Note its manifest declares no `dataViews`/`menus`/`security` pointers: those files are
+found by convention and the manifest schema is `additionalProperties: false`.
+
+### Fixed — `simple-todo`'s manifest was not schema-valid
+
+It declared `dataViews`, `menus`, `actions`, `security` and `seedData` pointers. None
+of those are manifest properties, the schema is `additionalProperties: false`, and no
+shipped module declares them — every path is resolved by convention from the module
+root (`ui/data_views.json`, `security/roles.json`, …), here and in the platform alike.
+Removed. This matters more than a stray key usually would: the examples are served as
+resources and described to agents as mandatory structures to copy, so an invalid shape
+in one propagates into every module built from it.
+
+### Fixed — the view-column flag vocabulary
+
+`entity.schema.json` described a view column's `flags` as `I/E/V/O/G/S/F/X/W`, with the
+example `'VO'` "to expose it read-only". No such letters: the canonical set is
+`V/I/E/M/H` (`flagDefs`), the client `Column` honours `V`/`E`/`I`, and the installer
+resolves `M` into `isNullable`. Nothing reads `O`, `G`, `S`, `F`, `X` or `W`. Read-only
+is plain `"V"` — visible, not editable.
+
+`references/flags.md` here was already right, and both the new guidance and the
+`column-security` example use only `V`/`VE`. Fixed upstream and picked up with
+`@dforge-core/metadata` **0.0.17**, so `resources/schemas/entity.schema.json` now says
+the same thing — which matters because that is the copy the editor `$schema` binding
+validates against.
+
 ## 0.2.15
 
 `canExecute` became a real server-side gate and `isTransacted` began opening a real

package/dist/server.js

@@ -31214,7 +31214,7 @@ function buildZedSettings() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.15/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.18/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -33137,9 +33137,10 @@ function checkFieldSpec(where, field) {
       'dropdown options go under params.options, not at the field root, e.g. "params": { "options": [{ "value": "a", "label": "A" }] }.'
     );
   }
-  if (typeof v.flags === "string" && v.flags.length > 0 && !/^[VIEMH]+$/.test(v.flags)) {
+  if (typeof v.flags === "string" && v.flags.length > 0 && !/^[VIEM]+$/.test(v.flags)) {
+    const hint = v.flags.includes("H") ? " There is no 'H' flag \u2014 a column is hidden by omitting 'V'." : " U/S/P are not flag letters.";
     err(
-      `flags '${v.flags}' contains invalid letters \u2014 use only V/I/E/M/H (e.g. VEM, VE, V, E). U/S/P are not flag letters.`
+      `flags '${v.flags}' contains invalid letters \u2014 use only V/I/E/M (e.g. VEM, VE, V, E).${hint}`
     );
   }
   if (typeof v.flags === "string" && v.flags.includes("M") && v.isNullable === true) {
@@ -33186,7 +33187,7 @@ function checkFieldSpec(where, field) {
     if (typeof v.formula !== "string" || v.formula.trim() === "") {
       err("formula column (columnType 'F') requires a non-empty 'formula' expression.");
     }
-    if (typeof v.flags === "string" && v.flags !== "V" && /^[VIEMH]+$/.test(v.flags)) {
+    if (typeof v.flags === "string" && v.flags !== "V" && /^[VIEM]+$/.test(v.flags)) {
       warn(
         `formula column has flags '${v.flags}' \u2014 a computed column is read-only, expected flags 'V'.`
       );
@@ -33717,6 +33718,23 @@ function entityFieldRename(args) {
       changes.push(`references.${rname}.from.field`);
     }
   }
+  const entityViews = entity.views ?? {};
+  for (const [vname, v] of Object.entries(entityViews)) {
+    const cols = v.columns;
+    if (!cols) continue;
+    if (oldName in cols) {
+      v.columns = renameKey(cols, oldName, newName);
+      changes.push(`views.${vname}.columns.${oldName}`);
+    }
+    for (const [cn, ov] of Object.entries(
+      v.columns
+    )) {
+      if (ov && typeof ov.formula === "string" && ov.formula.includes(oldToken)) {
+        ov.formula = ov.formula.split(oldToken).join(newToken);
+        changes.push(`views.${vname}.${cn}.formula`);
+      }
+    }
+  }
   files[rel(paths.root, entityPath)] = jsonText(entity);
   for (const [oname, orel] of Object.entries(manifest.entities ?? {})) {
     if (oname === entityName || oname.includes(".")) continue;
@@ -33840,6 +33858,31 @@ function entityFieldRemove(args) {
       changes.push(`references.${rn}`);
     }
   }
+  const entityViews = entity.views ?? {};
+  for (const [vname, v] of Object.entries(entityViews)) {
+    const cols = v.columns;
+    if (!cols) continue;
+    const kept = {};
+    for (const [k, val] of Object.entries(cols)) if (!removed.has(k)) kept[k] = val;
+    if (Object.keys(kept).length !== Object.keys(cols).length) {
+      v.columns = kept;
+      changes.push(`views.${vname}.columns`);
+    }
+    if (Object.keys(kept).length === 0) {
+      warnings.push(
+        `view '${vname}' has no columns left \u2014 delete the view, or give it columns (an empty view fails the install)`
+      );
+    }
+    for (const [cn, ov] of Object.entries(kept)) {
+      if (ov && typeof ov.formula === "string") {
+        for (const r of removed) {
+          if (ov.formula.includes(`[${r}]`)) {
+            warnings.push(`formula in view '${vname}'.${cn} still references removed '[${r}]'`);
+          }
+        }
+      }
+    }
+  }
   files[rel(paths.root, entityPath)] = jsonText(entity);
   for (const [fn, f] of Object.entries(entity.fields)) {
     if (typeof f.formula !== "string") continue;
@@ -35372,6 +35415,11 @@ function moduleInspect(args) {
       fieldCount: Object.keys(fields).length,
       fields: Object.keys(fields),
       hasNumberSequence: Boolean(e.numberSequence),
+      entityViews: Object.fromEntries(
+        Object.entries(e.views ?? {}).map(
+          ([vname, v]) => [vname, Object.keys(v?.columns ?? {}).length]
+        )
+      ),
       // Read as an OWN property — `toString` is inherited from
       // Object.prototype, so a plain `e.toString` reports the built-in
       // function (which JSON.stringify then silently drops) for every
@@ -35615,6 +35663,67 @@ function moduleValidate(args) {
       }
     }
   }
+  for (const [name, e] of Object.entries(entities)) {
+    const entityViews = e.views ?? {};
+    if (Object.keys(entityViews).length === 0) continue;
+    const fields = fieldDefsOf[name] ?? {};
+    const cols = columnsOf[name];
+    const pk = pkOf2(name);
+    const byLower = /* @__PURE__ */ new Map();
+    for (const vname of Object.keys(entityViews)) {
+      const list = byLower.get(vname.trim().toLowerCase()) ?? [];
+      list.push(vname);
+      byLower.set(vname.trim().toLowerCase(), list);
+    }
+    for (const [, spellings] of byLower) {
+      if (spellings.length > 1) {
+        err(
+          `entities/${name}.json \u2192 views`,
+          `views ${spellings.map((v) => `'${v}'`).join(" and ")} differ only by case or surrounding whitespace. A folder binds a view case-insensitively, so only one could ever be reached.`
+        );
+      }
+    }
+    for (const [vname, view] of Object.entries(entityViews)) {
+      const where = `entities/${name}.json \u2192 views.${vname}`;
+      const vcols = view?.columns ?? void 0;
+      if (!vcols || Object.keys(vcols).length === 0) {
+        err(
+          where,
+          "lists no columns. A view is the COMPLETE set of columns visible in a folder bound to it, so an empty one would hide every field \u2014 the installer rejects it."
+        );
+        continue;
+      }
+      const declared = Object.keys(vcols);
+      for (const cd of declared) {
+        if (cols && !cols.has(cd)) {
+          err(where, `column '${cd}' is not a field on entity '${name}'`);
+        }
+      }
+      const dupes = declared.filter(
+        (c, i) => declared.findIndex((o) => o.toLowerCase() === c.toLowerCase()) !== i
+      );
+      for (const d of dupes) {
+        err(where, `lists column '${d}' more than once (differing only by case)`);
+      }
+      if (pk && !declared.some((c) => c.toLowerCase() === pk.toLowerCase())) {
+        err(
+          where,
+          `omits the primary key '${pk}'. A view must list it \u2014 records are addressed by it. To keep it off the screen, drop 'V' from its flags instead of omitting it.`
+        );
+      }
+      for (const [cd, ovRaw] of Object.entries(vcols)) {
+        const ov = ovRaw ?? {};
+        if (typeof ov.formula !== "string" || ov.formula.trim() === "") continue;
+        const colType = fields[cd]?.columnType;
+        if (colType !== "F") {
+          err(
+            `${where}.columns.${cd}`,
+            `sets a formula on a column of type '${colType ?? "D"}'. A view formula is only evaluated on a Formula ("F") column \u2014 on any other column that field holds the SQL default, and the override would do nothing.`
+          );
+        }
+      }
+    }
+  }
   const views = readJsonOrDefault(paths.dataViews, {});
   const viewCodes = new Set(Object.keys(views));
   for (const [vcode, v] of Object.entries(views)) {
@@ -35930,6 +36039,30 @@ function moduleValidate(args) {
       `folder code '${code2}' is used ${dupPaths.length} times (${dupPaths.join(", ")}). Codes must be unique across the whole tree: role rights say 'folder:${code2}' with no path, and translations key on 'folders.${code2}.label', so duplicates are ambiguous and silently collide.`
     );
   }
+  const folderNodes = [
+    { path: "(root)", node: folderRoot },
+    ...walkFolders(folderRoot).map((f) => ({ path: f.path, node: f.node }))
+  ];
+  for (const { path: fpath, node } of folderNodes) {
+    const bindings = node.entities ?? {};
+    for (const [entityCd, binding] of Object.entries(bindings)) {
+      const viewName = (binding ?? {})?.viewName;
+      if (typeof viewName !== "string" || viewName.trim() === "") continue;
+      if (viewName.trim().toLowerCase() === "default") continue;
+      if (entityCd.includes(".")) continue;
+      const e = entities[entityCd];
+      if (!e) continue;
+      const declared = Object.keys(
+        e.views ?? {}
+      ).map((v) => v.trim().toLowerCase());
+      if (!declared.includes(viewName.trim().toLowerCase())) {
+        err(
+          `ui/folders.json \u2192 ${fpath} \u2192 entities.${entityCd}`,
+          `viewName '${viewName}' is not declared under 'views' in entities/${entityCd}.json. This fails the install: an unresolved view would show every column of the entity, which is the opposite of what naming one asks for. Declare the view, or drop 'viewName' (or use "default", which means no view).`
+        );
+      }
+    }
+  }
   for (const [rcode, rawReport] of Object.entries(reports)) {
     const report = rawReport ?? {};
     const where = `ui/reports.json \u2192 ${rcode}`;
@@ -36350,6 +36483,15 @@ function matrixExample(relPath, description) {
     read: () => readSkill(`examples/matrix-budget/${relPath}`)
   };
 }
+function columnSecurityExample(relPath, description) {
+  return {
+    uri: `dforge://example/column-security/${relPath}`,
+    name: `Example: column-security/${relPath}`,
+    description,
+    mimeType: relPath.endsWith(".json") ? "application/json" : "text/plain",
+    read: () => readSkill(`examples/column-security/${relPath}`)
+  };
+}
 var resources = [
   schema(
     "manifest",
@@ -36359,7 +36501,7 @@ var resources = [
   schema(
     "entity",
     "Entity JSON schema",
-    "JSON Schema for entity files under entities/*.json (description, dbObject, toString, traits, fields)."
+    "JSON Schema for entity files under entities/*.json (description, dbObject, toString, traits, fields, views)."
   ),
   schema(
     "domains",
@@ -36442,7 +36584,7 @@ var resources = [
   },
   // ── Per-element authoring references (skills/.../references/*.md) ──────
   reference("field-types", "Field types \u2014 fieldTypeCd (UI control) vs dbDatatype (SQL type), and the correct value for each. Load before adding any field."),
-  reference("flags", "Column flags \u2014 only V/I/E/M/H; valid combos (VEM/VE/V/EM/I) and why 'VEMHI' is invalid. Load before setting any flags."),
+  reference("flags", "Column flags \u2014 only V/I/E/M (there is no H); valid combos (VEM/VE/V/EM/I), how M folds into isNullable, and how the same letters override per entity view. Load before setting any flags."),
   reference("column-types", "The FK + Reference two-column pattern (the #1 source of broken modules) and Set columns. Load before any relation."),
   reference("column-domains", "Column domains: a reusable field type (datatype + control + shared option list) referenced via a single `domain` key. Use when the same enum/type repeats across columns. Load before authoring domains.json or a domain-backed column."),
   reference("formulas", "Formula columns (columnType 'F'): baseDatatypeCd, no dbDatatype, flags 'V', and the formula expression grammar."),
@@ -36488,7 +36630,13 @@ var resources = [
   matrixExample("entities/budget_category.json", "Matrix row-axis (dataset) entity."),
   matrixExample("manifest.json", "Matrix example manifest (entities + dataViews + roles + seed)."),
   matrixExample("security/roles.json", "Matrix example roles: S on the axis entity, SIUD on the editable cell entity."),
-  matrixExample("seed-data/01-categories.json", "Matrix example seed: row-axis category records.")
+  matrixExample("seed-data/01-categories.json", "Matrix example seed: row-axis category records."),
+  columnSecurityExample("entities/product.json", `Canonical ENTITY VIEWS (column-level security): one entity, two views \u2014 'storekeeper' (a plain column subset, prices absent entirely) and 'accountant' (with a per-column flags override making a column read-only in that view only, and a per-view formula override on an "F" column). Both list the primary key, which a view must.`),
+  columnSecurityExample("ui/folders.json", "The BINDING half: two folders over one entity, each with a different entities.product.viewName. Without this the views exist and nothing uses them; with a name no view declares, the install fails rather than falling back to the full column set."),
+  columnSecurityExample("security/roles.json", "Roles for the two folders. Note rights are per ENTITY, not per column \u2014 the column dimension is the entity view, not the role."),
+  columnSecurityExample("ui/data_views.json", "The data view lists EVERY column including prices \u2014 correct: presentation is one axis, the folder's entity view decides what a user may see of it. You do not maintain one data view per role."),
+  columnSecurityExample("manifest.json", "Column-security example manifest. Note it declares no dataViews/menus/security pointers \u2014 those files are found by convention, and the manifest schema is additionalProperties:false."),
+  columnSecurityExample("README.md", "Why entity views exist, what each of the two views demonstrates, and the five ways a view fails the install.")
 ];
 function readVendored(rel2) {
   const p = path16.join(RESOURCES_DIR, rel2);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.15",
+	"version": "0.2.16",
 	"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",
@@ -36,7 +36,7 @@
 	},
 	"dependencies": {
 		"@dforge-core/dforge-cli": "^0.2.14",
-		"@dforge-core/metadata": "^0.0.15",
+		"@dforge-core/metadata": "^0.0.18",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/docs/conventions.md

@@ -426,7 +426,7 @@ slashes.
 - **The whole file is the root folder.** Top-level fields (`label`, `description`, `color`, `entities`) belong to the root.
 - **Subfolders nest under `children`** (a dictionary keyed by path segment).
 - **Each child key is a single path segment** — lowercase letters, digits, dashes, and underscores only, no slashes. Pattern: `^[a-z0-9][a-z0-9_-]*$`. Slashes are forbidden in keys because deeper trees use `children` recursively, not slashes in keys.
-- **`entities` is a dictionary** mapping entity codes to settings objects. Each entity has `viewName` (string or null), `quickAdd` (boolean), and an optional `rowFilter`.
+- **`entities` is a dictionary** mapping entity codes to settings objects. Each entity has `viewName` (an **entity view** name — see below — or null), `quickAdd` (boolean), and an optional `rowFilter`.
 - **`inheritSecurity`** is allowed only on child folders. The root has no parent to inherit from, so the field is rejected at the root level with a clear error.
 - **Children can have their own children**, recursively, for arbitrary tree depth.
 
@@ -464,6 +464,78 @@ The DB still has a `UNIQUE INDEX` on `(module_id, folder_path)` as
 defense-in-depth, and `FolderTreeFlattener` validates the file format
 before the install pipeline touches the database.
 
+### Entity views — column-level security
+
+An **entity view** is a named subset of an entity's columns, declared on the entity file and bound per folder. Users working in that folder see **only** the columns the view lists — the rest are neither visible nor queryable there. This is the column-level layer of the security model; roles grant rights per *entity*, never per field.
+
+Two halves, both required:
+
+| File | Key | Effect |
+|------|-----|--------|
+| `entities/<entity>.json` | `views.<viewName>.columns` | Declares the view and its column set |
+| `ui/folders.json` | `entities.<code>.viewName` | Binds that view for this entity in this folder |
+
+```jsonc
+"views": {
+	"storekeeper": {
+		"columns": {
+			"product_id": {},
+			"name": {},
+			"quantity": {}
+		}
+	},
+	"accountant": {
+		"columns": {
+			"product_id": {},
+			"name": {},
+			"quantity": { "flags": "V" },
+			"cost_price": {},
+			"sale_price": {}
+		}
+	}
+}
+```
+
+**Per-column overrides** (all optional, each falls back to the entity-level value): `flags`, `orderNum`, `isNullable`, `editMask`, `displayFmt`, `refFilter`, `params`, `formula`. `{}` means "expose this column, override nothing".
+
+**An empty override is a value, not an absence.** The runtime merges view over entity with `COALESCE(view, entity)`, which skips NULL only — so `"flags": ""` means "no flags in this view" (a column neither visible nor editable) and `"params": {}` suppresses the entity-level params rather than inheriting them. Omit the key entirely to inherit.
+
+`formula` lets one view compute a column differently from the entity, and only on a column the entity declares as `columnType: "F"` — elsewhere that field holds the SQL default, so an override there would be inert.
+
+**Rules the installer enforces** (each is silent at runtime, which is why they fail the install instead):
+
+- A column absent from `columns` is **hidden**. That is the mechanism, not an oversight.
+- A view must list the **primary key** — records are addressed by it. Keep it off screen by dropping `V` from its flags instead of omitting it.
+- A column code that doesn't exist, a view with **no** columns, one column listed twice under different casing, or two views whose names differ only by case (a folder binds case-insensitively, so only one could ever be reached).
+- Views belong to the entity's **own** module; an `extends` extension declaring `views` is rejected, since a view enumerates the complete column set.
+- A `viewName` that no view declares, or one naming a column-less view, **fails the install**. It does not fall back: the fallback is the full column set, so a typo would quietly *unrestrict* the folder.
+
+**`"default"` is the one exempt name** and means "no view" (full column set). It is what the ~100 shipped folder entries write, what `FolderExporter` writes back for a NULL `view_name`, and what the runtime auto-creates (column-less) for an entity reached without a folder binding — so rejecting it would fail every install. A module that really declares a view named `default` still gets it bound.
+
+Don't confuse the three things called "view": an **entity view** (`views`, this section) is column security; a **data view** (`ui/data_views.json`, referenced by a menu's `dataViewCode`) is a grid/kanban/calendar; `isView` + `viewSql` on an entity means it is backed by a SQL view. `folders.json`'s `viewName` binds the first.
+
+## Column Domains (`domains.json`)
+
+A **domain** is a reusable, named semantic type: a base datatype, a control, sizing, and a shared option list under one code. Columns reference it instead of restating the definition.
+
+```json
+{
+	"doc_status": {
+		"description": "Document Status",
+		"baseDatatypeCd": "string",
+		"dbDatatype": "varchar",
+		"maxLen": 20,
+		"fieldTypeCd": "dropdown",
+		"params": {
+			"options": [
+				{ "value": "draft", "label": "Draft" },
+				{ "value": "posted", "label": "Posted", "color": "#0a0" }
+			]
+		}
+	}
+}
+```
+
 ### 5. Security Roles (`security/roles.json`)
 
 ```json
@@ -939,6 +1011,7 @@ When creating a module, ensure:
 - [ ] `menus.json` uses nested dictionaries with `children` (not arrays)
 - [ ] `menus.json` leaf items use `dataViewCode` (not `viewCode`)
 - [ ] `folders.json` uses entity dictionary with `{ viewName, quickAdd }` objects
+- [ ] Every `viewName` is `"default"` (= no view) or a view the entity declares under `views`; each declared view lists the primary key and at least one column
 - [ ] `roles.json` uses `"rights"` property (not `"entityRights"`)
 - [ ] Seed data files are numbered for FK dependency order (01-, 02-, etc.)
 - [ ] Seed data includes explicit numeric (int8) PKs for cross-entity references — NOT UUID strings (`cuid` is `int8`)

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

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

@@ -213,7 +213,7 @@ Lives in: `ui/folders.json`
 
 | Property | Type | Description |
 |---|---|---|
-| `viewName` | string | Default data view (usually `"default"`) |
+| `viewName` | string | Entity view to bind — a key under the entity's `views` (see [Column-level security](#column-level-security-entity-views)), **not** a `ui/data_views.json` code. `"default"` means "no view" (full column set). |
 | `quickAdd` | boolean | Show "+" quick-add button (`true` for main entities, `false` for detail/line items) |
 | `rowFilter` | object | Row-level filter scoping which records are visible in this folder |
 
@@ -226,6 +226,82 @@ Row filters use a compact filter object with:
 
 This is how **row-level security** works in the module package — subfolders with `rowFilter` restrict which rows are visible. Users assigned to "Central Warehouse" only see stock where `warehouse_id = 2001`.
 
+## Column-level security (entity views)
+
+> Worked example: `dforge://example/column-security/` — one entity, two folders, two
+> column sets. Its README walks the overrides and the ways a view fails the install.
+
+Layer 2 of the model. A **entity view** is a named subset of an entity's columns, declared on the entity itself; a folder binds one per entity. Users working in that folder see **only** the columns the view lists — the rest are neither visible nor queryable there.
+
+Two halves, both required:
+
+| File | Key | Effect |
+|---|---|---|
+| `entities/<entity>.json` | `views.<viewName>.columns` | Declares the view and its column set |
+| `ui/folders.json` | `entities.<code>.viewName` | Binds that view for this entity in this folder |
+
+```json
+{
+    "fields": { "product_id": {}, "name": {}, "price": {}, "cost": {}, "quantity": {} },
+    "views": {
+        "accountant": {
+            "columns": {
+                "product_id": {},
+                "name": { "flags": "V" },
+                "price": { "flags": "VE" },
+                "cost": { "flags": "V" }
+            }
+        },
+        "storekeeper": {
+            "columns": {
+                "product_id": {},
+                "name": { "flags": "V" },
+                "quantity": { "flags": "VE" }
+            }
+        }
+    }
+}
+```
+
+```json
+"entities": { "product": { "viewName": "accountant", "quickAdd": true } }
+```
+
+The storekeeper folder cannot see `price` or `cost` at all — not on screen, not through a filter, not in an export.
+
+**Per-column overrides** (all optional, each falls back to the entity-level value): `flags`, `orderNum`, `isNullable`, `editMask`, `displayFmt`, `refFilter`, `params`, `formula`. `{}` means "expose this column, override nothing".
+
+> **An empty override is a value, not an absence.** The runtime merges view over entity with `COALESCE`, which skips NULL only — so `"flags": ""` means "no flags in this view" (a column neither visible nor editable) and `"params": {}` suppresses the entity-level params rather than inheriting them. Omit the key entirely to inherit — `"flags": null` fails schema validation. See `flags.md` for the flag letters.
+
+> **`M` works in a view override too**, folding into that override's `isNullable`. Since a view writes no DDL, the requiredness is runtime-only — which is how a column nullable in the database is made mandatory inside one view: `{ "flags": "VEM" }`. The fold is one-directional: dropping `M` does not loosen the column, because `isNullable` still inherits. See `flags.md` → Per-view overrides.
+
+`formula` lets one view compute a column differently from the entity — same DSL as a field's `formula`, and **only on a column the entity declares as `columnType: "F"`**; elsewhere 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. See `formulas.md`.
+
+### Rules the installer enforces
+
+Each of these is an install-time error, and each is silent at runtime if it slips through — which is why `dforge_module_validate` checks them offline:
+
+- A column absent from `columns` is **hidden**. That is the mechanism, not an oversight.
+- A view must list the entity's **primary key** — records are addressed by it. To keep it off screen, drop `V` from its flags instead of omitting it.
+- A column code that doesn't exist on the entity, a view with **no columns**, the same column listed twice under different casing, or two views on one entity whose names differ only by case (a folder binds case-insensitively, so only one could ever be reached).
+- Views must be declared on the entity's **own** module. An `extends` extension declaring `views` is rejected — a view enumerates the complete column set, which an extension does not own.
+- A `viewName` that no view declares, or one naming a view with no columns, **fails the install**. It does not fall back: the fallback is the entity's full column set, so a typo would quietly *unrestrict* the folder.
+- Columns removed from a view are reaped on upgrade — that is the security change the author asked for. Whole views are not: `entity_view` also holds tenant views from the card-layout editor, and the installer cannot tell them apart.
+
+### `"default"` is the one exempt name
+
+`"viewName": "default"` means **no view** (full column set) and declares nothing. It is what every shipped module writes, and what the runtime auto-creates for an entity reached without a folder binding — so it is exempt from the checks above. A module that really declares a view named `default` still gets it bound.
+
+### Don't confuse the three "views"
+
+| Term | Where | What it is |
+|---|---|---|
+| **Entity view** | `entities/*.json` → `views` | Column-level security (this section) |
+| **Data view** | `ui/data_views.json` | A grid / kanban / calendar over an entity (`data-views.md`) |
+| **SQL view** | `entities/*.json` → `isView` + `viewSql` | An entity backed by a SQL view instead of a table |
+
+`viewName` in `folders.json` binds the first. Menus' `dataViewCode` references the second.
+
 ### When to use subfolders
 
 - **Multi-location modules** (warehouses, offices, branches) — one subfolder per location, filtered by location FK

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

@@ -105,6 +105,8 @@ For each entity:
 ## Security
 
 - [ ] `security/roles.json` exists (at least one role)
+- [ ] Every entity view (`views.<v>.columns` on an entity) lists the entity's **primary key**, names only real columns, and has at least one column — each of these fails the install
+- [ ] Every `viewName` in `ui/folders.json` is either `"default"` (= no view) or a view that entity actually declares — an unresolved name fails the install rather than falling back
 - [ ] Every role has `description` and `rights` (both required; no `label` field in `roles.json` — the `roles.schema.json` sets `additionalProperties: false`, so any extra field including `label` is rejected here). `description` is the English display-name fallback; **localized role labels live in the translation files** (`roles.<code>.label`) and are completeness-enforced — see Translations below.
 - [ ] The field name is `rights`, NOT `entityRights`
 - [ ] Rights strings use only valid letters: `SIUDC` for entities, `E` for actions/reports/folders

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

@@ -31,6 +31,7 @@ flags, or column patterns.
 | Add a grid / list view | `dforge://reference/data-views`, `dforge://example/ui/data_views.json` | — |
 | Add a matrix (pivot) view | `dforge://reference/data-views` (§Matrix), `dforge://example/matrix-budget/ui/data_views.json`, `dforge://example/matrix-budget/entities/budget_line.json` | — |
 | Add kanban / calendar / tree-grid / master-detail | `dforge://reference/data-views` | `dforge://schema/data-views` |
+| Hide columns from a user type (column-level security) | `dforge://reference/security` (§Column-level security), `dforge://example/column-security/entities/product.json`, `dforge://example/column-security/ui/folders.json` | — |
 | Add a menu | `dforge://reference/menus`, `dforge://example/ui/menus.json` | — |
 | Add an action | `dforge://reference/action-dsl`, `dforge://example/logic/actions/mark_done.dsl`, `dforge://example/ui/actions.json` | `dforge://docs/dsl` |
 | Add a trigger | — | `dforge://schema/triggers`; condition syntax in `dforge://docs/dsl` |
@@ -204,8 +205,11 @@ per entity, so you'll often `view_modify` rather than `view_add`.
 
 View codes are semantic — the entity name (`feedback_item`), a plural
 (`invoices`), or descriptive (`invoices_kanban`). **Never use the literal code
-`default`**; `ui/folders.json`'s `viewName: "default"` is a fallback alias the
-platform resolves to the entity's first declared view.
+`default`.** Note that `ui/folders.json`'s `viewName` is a different axis
+entirely: it binds an *entity view* (column-level security, declared under
+`views` on the entity file), not a data view code. `"default"` there means "no
+entity view — show the full column set", and any other name the entity does not
+declare **fails the install**. See `references/security.md`.
 
 Then wire menus with `dforge_menu_add` — a section node per group, leaves
 pointing at the views.
@@ -273,6 +277,13 @@ stated trigger; every report's params sit on a dataset.
 4. **Show the rights matrix as a table** (rows = entities/actions/reports,
    columns = roles, cells = rights strings), each cell explained by the verb it
    maps to. Get sign-off.
+5. **Column-level security only when the intake asks for it.** Roles grant rights
+   per entity, not per field. When a user type must not see specific *columns*
+   (salaries, cost prices, personal data), that is an **entity view**: declare
+   `views.<name>.columns` on the entity and bind it with `viewName` on the folder
+   that user type works in. Don't reach for it otherwise — a view is the complete
+   column list, so it is one more list to keep in step with the fields. Rules and
+   the worked example: `references/security.md` → Column-level security.
 5. `dforge_role_add` for new roles; `dforge_role_right_set` per grant when
    amending an existing one.