@dforge-core/dforge-mcp 0.2.14 → 0.2.16

package/CHANGELOG.md

@@ -4,7 +4,245 @@ 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.6
+## 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
+transaction (platform change `5398a48b0`). Both had been documented here as the
+opposite — "a UI hint" and "does not open a transaction" — so this release is a
+correction pass across the authoring guidance, with no tool or schema changes.
+
+### Changed — `canExecute` is enforced, with a fail-open subset
+
+`action.execute` now evaluates the stored `can_execute_parsed` AST over every targeted
+record before any write and refuses the call with `ACTION_EXECUTION_FAIL`. So
+`canExecute: false` is a genuine "only automation may fire this" — the scheduler and
+triggers invoke the script engine directly and still bypass it.
+
+The server evaluator is a scalar walker, not the formula engine, and the client has its
+own separate gaps, so `references/action-dsl.md` and `dsl-reference.md` now carry a tier
+table instead of a single list:
+
+| tier | construct | client | server |
+|---|---|---|---|
+| 1 | **comparisons** (`=` `!=` `<` `<=` `>` `>=`) between fields and literals, combined with `AND` / `OR` / `NOT`; a bare `true` / `false` | evaluates | **enforces** |
+| 2 | arithmetic, `IN`, `BETWEEN`, any formula function | evaluates | fail-open |
+| 3 | ref navigation, `SUM` / `COUNT` / `AVG`, any unknown function (a typo included) | **fail-open (throws)** | fail-open |
+| — | `$[setting]` references | **evaluates as null** (no throw) | fail-open |
+
+Four things in there are easy to get wrong and are called out explicitly:
+
+- **A bare boolean field is not enforced.** The walker evaluates conditions, not values —
+  a field resolves only as an operand of a comparison — so `canExecute: [is_active]` and
+  `NOT [is_blocked]` fail open. Write `[is_active] = true` and `NOT ([is_blocked] = true)`.
+- **A misspelled function ships silently.** A `canExecute` is never validated against the
+  function set at install (`FindUnknownFunctions` is wired only into the formula-column
+  path), so `TOADY()` installs and enables the button for every record.
+- **Tier 3 mixed into a predicate is worse than useless**, because the two sides disagree
+  about short-circuiting: the server's `AND` / `OR` short-circuit, the client's evaluator
+  does not. `[status] = 'Pending' AND COUNT([lines]) > 0` on a non-`Pending` record throws
+  in the browser, is caught, and **enables** the button — then the server refuses the call.
+  An error where a greyed-out button was wanted. Count with a Generated (`G`) column and
+  compare the scalar. Mixing tier 1 with tier 2 is fine and is the normal shape.
+- **Settings do not work in `canExecute` at all** — the client resolver is stubbed to
+  `null` and the server has none, so the guard is unenforced server-side and tends to jam
+  the button *shut* client-side. Read them in `execute:`.
+
+`references/jobs.md` also stops promising that `canExecute: false` hides the button: the
+action stays in the toolbar, permanently disabled.
+
+### Changed — `isTransacted` opens a transaction, and defaults to `true`
+
+The *Don't assume your action is atomic* section is replaced by *Atomicity*. `true` now
+makes the whole run one transaction in both execution modes, covering the script's own
+`insert()` / `update()` / `query()` calls as well as the flush of `[field] = …`
+assignments, and it no longer depends on the entity carrying `auditHistory` — advice to
+reach for that trait as an atomicity switch is gone.
+
+`false` is documented per mode, because "failures are isolated" only ever made sense where
+there is a loop: `single` / `each` report the failure and continue with the next record,
+while a `batch` script is one invocation, so a failure just ends the run with its earlier
+writes committed and its `[field]` assignments never flushed.
+
+The background path is the exception, and it splits by mode too: the worker opens no
+transaction, so nothing is ever undone; its `single` / `each` loop still reads the flag for
+control flow, while its `batch` path never reads it at all — a queued `batch` action gets
+nothing from `isTransacted` in either direction.
+
+### Fixed — `isAsync` does not force background execution, and there is no Hangfire
+
+`isAsync: true` only *permits* queuing. The server branches on the `async` argument the
+request carries, so a parameterless action is queued directly while one with parameters is
+offered to the user as both "Run" (inline, transactional) and "Run in Background". Whether
+an action is atomic is therefore not answerable from the manifest alone.
+
+Two claims that dForge runs background actions "via Hangfire" are removed — the platform
+uses a hosted `BackgroundService` polling `background_action`, and `FileCleanupService`
+says so in as many words.
+
+### Changed — validation checklist
+
+Two new items under actions: that a `canExecute` meant to *gate* is written in the
+server-enforced subset, and that no bare boolean field is used as a whole condition. The
+`references/formulas.md` entry for `canExecute:` blocks now summarises the same rules and
+points at `action-dsl.md`.
+
+## 0.2.14
 
 Record reports — a report attached to an entity so it opens **from a record**, with the
 record's values feeding its parameters — plus a report-level home for report parameters,

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.14",
+	"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`)