@dforge-core/dforge-mcp 0.2.5 → 0.2.14

package/CHANGELOG.md

@@ -4,6 +4,108 @@ 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
+
+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,
+and the removal of two parameter spellings the installer never read.
+
+Requires `@dforge-core/metadata` ≥ 0.0.15 (bumped): the vendored
+`resources/schemas/reports.schema.json` served as `dforge://schema/reports` comes from
+there.
+
+### Added — record-report attachments
+
+A report in `ui/reports.json` gains an `entities` array. Each entry attaches the report to
+one entity, mapping report parameters to source columns on it:
+
+```jsonc
+"credit_check": {
+    "entities": [
+        { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 },
+        { "entityCd": "crm.quote",     "params": { "customer_id": "customer_id" }, "orderNum": 45 }
+    ]
+}
+```
+
+The report then appears on that record's toolbar and opens on a record-scoped route with
+the mapped params resolved server-side and hidden. `dforge_report_add` accepts and
+documents the block; `references/reports.md` gains a **Record reports** section with the
+rules (source-column allowlist, type compatibility, one attachment per (entity, report)
+pair, the `"metadata": ">=1.5.0"` gate, and the cross-module dependency bound).
+
+Note the two different `params` keys, which the tool description now calls out: on an
+attachment it is the *mapping* (param code → column); on the report or a dataset it is the
+*declaration*.
+
+### Added — `dforge_module_validate` checks reports
+
+Mirrors the server's new pack-time `ReportAttachmentValidator`, so these fail offline
+instead of at install against a live tenant:
+
+- a mapped param code neither the report-level `parameters` block nor any dataset declares;
+- a source column the entity doesn't have, or one that's a set / formula / free-text column;
+- two attachments to the same entity in one report (the second overwrites the first);
+- an attachment to a cross-module entity whose module isn't a declared dependency;
+- `isRequired`, a top-level `link`, or `fieldTypeCd` + `domain` together on a param;
+- a warning when a module ships attachments with no `metadata` dependency.
+
+### Added — report-level `parameters`
+
+Report parameters are **report-scoped**: the declaration is stored once per report
+(`report.param_set_id` → `param_set`), the authoring API is `report.params.save`, and
+`report.get` flattens per-dataset defaults report-wide before use. The installer had only
+ever read the per-dataset shorthand, so a report-level block was silently dropped and the
+report installed with no parameters at all — which is what made
+`crm-fin.customer_statement` and `wms-fin.vendor_statement` ship parameterless.
+
+Both declaration sites are now legal and mean the same thing; the installer merges them,
+**report level winning** on a code collision:
+
+```jsonc
+"customer_statement": {
+    "parameters": {
+        "customer_id": { "label": "Customer", "fieldTypeCd": "lookup",
+                         "params": { "link": { "entity": "parties.party" } }, "required": true }
+    },
+    "datasets": { "statement_invoices": { }, "statement_payments": { } }
+}
+```
+
+Declare at report level when several datasets use the parameter — `customer_statement` is
+exactly that case, and there is no meaningful dataset to attribute it to.
+`datasets.<cd>.params` stays the right shorthand for a single-dataset parameter, and every
+module written before this keeps working.
+
+`dforge_module_validate` merges both sites when resolving a record-report mapping, so a
+mapping onto a report-level parameter resolves exactly as install will resolve it.
+
+### Fixed — two report-param spellings that are silently ignored
+
+Unlike `parameters`, these are simply misspellings of keys that already exist, so they are
+gone from the schema rather than implemented — and the validator flags them at either
+declaration site:
+
+- **`isRequired`** — the key is `required`; the parameter installed as optional.
+- **top-level `link`** on a lookup parameter — it belongs under `params`; the parameter
+  installed with no autocomplete.
+
+`references/reports.md` also corrects the rights-key example from `report.<code>` to the
+colon form `report:<code>`, and the lookup parameter config from `params.entityCd` to
+`params.link.entity`.
+
+### Changed — steer calculation toward reports, not the DSL
+
+`action-dsl.md`'s *When an action is the wrong tool* now names the record report as the
+direct replacement for a `check_…` action — same toolbar entry point, but the user sees
+the open invoices and the ageing rather than just "FAILED" — and adds the general rule:
+**do not compute in the DSL what a report dataset already aggregates.** Sums, ratios,
+ageing buckets and exposure get formatting, drill-through, row caps and live re-reads for
+free from a report; DSL arithmetic over `select()` reproduces that badly, once, somewhere
+nothing else can reuse. Write DSL when the number must be *written down* or must *stop*
+something. The same steer is in `dsl-reference.md`, Phase 2a and Phase 3c of the
+`dforge-module-build` skill, and the validation checklist.
+
 ## 0.2.5
 
 Catches up with the platform's parameter-options work (dForge-core 1.20.0). A dropdown

package/dist/server.js

@@ -31002,7 +31002,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.13/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.14/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31214,7 +31214,7 @@ function buildZedSettings() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.14/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.15/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -35146,9 +35146,20 @@ var reportAddSchema = {
     description: external_exports.string(),
     layout: external_exports.record(external_exports.string(), external_exports.unknown()),
     datasets: external_exports.record(external_exports.string(), external_exports.unknown()),
-    parameters: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+    parameters: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
+      "Report-level parameter declarations \u2014 the canonical home for a param, and the only one that fits a param several datasets use. Merged with each dataset's `params` into the report's one param set; this block wins on a code collision."
+    ),
+    entities: external_exports.array(
+      external_exports.object({
+        entityCd: external_exports.string(),
+        params: external_exports.record(external_exports.string(), external_exports.string()).optional(),
+        orderNum: external_exports.number().int().optional()
+      }).passthrough()
+    ).optional().describe(
+      "RECORD-REPORT attachments \u2014 entities this report can be opened FROM, so it appears on the record's toolbar with the record's values feeding its params. Each entry: { entityCd, params: { <reportParamCd>: <sourceColumnOnThatEntity> }, orderNum? }. NOTE `params` here is the MAPPING (param \u2192 column), not a param declaration. Qualify a cross-module entityCd ('parties.party') and declare that module as a dependency. Source columns: the PK, a reference ('R') column, or a bounded scalar \u2014 never text/json/file. Requires 'metadata': '>=1.5.0' in the manifest."
+    )
   }).passthrough().describe(
-    "Full report spec per reports.schema.json: { description, layout: { panels: [...] }, datasets: { code: {...} }, parameters? }."
+    "Full report spec per reports.schema.json: { description, layout: { panels: [...] }, datasets: { code: {...} }, parameters?, entities?, reloadInterval? }. PARAMS ARE REPORT-SCOPED: declare them in the top-level `parameters` block, or as shorthand under `datasets.<cd>.params` when exactly one dataset uses the param \u2014 the installer merges both into the report's single param set, report level winning on a collision. A param several datasets use belongs at report level; there is no meaningful dataset to attribute it to. Within a param, use `required` (not `isRequired`) and nest a lookup's binding as `params: { link: { entity } }` (not a top-level `link`)."
   )
 };
 function reportAdd(args) {
@@ -35919,6 +35930,119 @@ 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.`
     );
   }
+  for (const [rcode, rawReport] of Object.entries(reports)) {
+    const report = rawReport ?? {};
+    const where = `ui/reports.json \u2192 ${rcode}`;
+    const declaredParams = /* @__PURE__ */ new Set();
+    const checkParamDef = (loc, pcode, pdef) => {
+      const p = pdef ?? {};
+      if ("isRequired" in p) {
+        err(
+          `${where} \u2192 ${loc}.${pcode}`,
+          "uses 'isRequired', which the installer does not read \u2014 the param installs as OPTIONAL. Rename it to 'required'."
+        );
+      }
+      if ("link" in p) {
+        err(
+          `${where} \u2192 ${loc}.${pcode}`,
+          'puts \'link\' at the top level, where the installer does not read it \u2014 a lookup param with no `params.link` has no autocomplete. Nest it: "params": { "link": { "entity": "\u2026" } }.'
+        );
+      }
+      if ("fieldTypeCd" in p && "domain" in p) {
+        err(
+          `${where} \u2192 ${loc}.${pcode}`,
+          "declares both 'fieldTypeCd' and 'domain' \u2014 install rejects the pair rather than picking a winner. A domain supplies the control; drop the fieldTypeCd."
+        );
+      }
+    };
+    const reportParams = report.parameters ?? {};
+    for (const [pcode, pdef] of Object.entries(reportParams)) {
+      declaredParams.add(pcode);
+      checkParamDef("parameters", pcode, pdef);
+    }
+    const datasets = report.datasets ?? {};
+    for (const [dcode, ds] of Object.entries(datasets)) {
+      const dsParams = ds?.params ?? {};
+      for (const [pcode, pdef] of Object.entries(dsParams)) {
+        declaredParams.add(pcode);
+        checkParamDef(`datasets.${dcode}.params`, pcode, pdef);
+      }
+    }
+    const attachments = report.entities;
+    if (attachments === void 0) continue;
+    if (!Array.isArray(attachments)) {
+      err(where, "'entities' must be an array of record-report attachments.");
+      continue;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const raw of attachments) {
+      const att = raw ?? {};
+      const entityCd = att.entityCd;
+      if (typeof entityCd !== "string" || entityCd.trim() === "") {
+        err(where, "an entry in 'entities' is missing 'entityCd'.");
+        continue;
+      }
+      const bare = entityCd.startsWith(`${manifest.code}.`) ? entityCd.slice(manifest.code.length + 1) : entityCd;
+      if (seen.has(bare)) {
+        err(
+          where,
+          `attaches to '${entityCd}' twice. One attachment per (entity, report) pair \u2014 merge the two 'params' maps into a single entry.`
+        );
+        continue;
+      }
+      seen.add(bare);
+      if (!isKnownEntity(entityCd)) {
+        err(
+          where,
+          `attaches to '${entityCd}', which is not a known entity (same-module, system, or a declared cross-module dependency). Qualify a foreign entity as 'module.entity' and add that module to the manifest's dependencies.`
+        );
+      }
+      const paramMap = att.params ?? {};
+      for (const [paramCd, source] of Object.entries(paramMap)) {
+        if (!declaredParams.has(paramCd)) {
+          err(
+            where,
+            `maps '${paramCd}' from '${entityCd}.${String(source)}', but '${paramCd}' is not a declared parameter of this report. Declare it in the report's 'parameters' block, or under the 'params' of the dataset that consumes it.`
+          );
+          continue;
+        }
+        if (typeof source !== "string" || source.trim() === "") {
+          err(where, `maps parameter '${paramCd}' from an empty source column on '${entityCd}'.`);
+          continue;
+        }
+        const fields = fieldDefsOf[bare];
+        if (!fields) continue;
+        const col = fields[source];
+        if (!col) {
+          err(
+            where,
+            `maps parameter '${paramCd}' from '${entityCd}.${source}', which is not a column of that entity.`
+          );
+          continue;
+        }
+        if (col.columnType === "S" || col.columnType === "F") {
+          err(
+            where,
+            `maps parameter '${paramCd}' from '${entityCd}.${source}', a ${col.columnType === "S" ? "set ('S')" : "formula ('F')"} column. Map the PK, a reference ('R') column, or a bounded scalar.`
+          );
+          continue;
+        }
+        const db = typeof col.dbDatatype === "string" ? col.dbDatatype.toLowerCase() : "";
+        if (col.columnType !== "R" && col.isPk !== true && /^(text|json|jsonb|bytea|uuid)$/.test(db)) {
+          err(
+            where,
+            `maps parameter '${paramCd}' from '${entityCd}.${source}' (dbDatatype '${db}'), which is not a valid record-report parameter source. Allowed: the entity PK, a reference column, or a bounded scalar (number, date/datetime, bool, dropdown/radio/flags code).`
+          );
+        }
+      }
+    }
+    if (seen.size > 0 && !deps.has("metadata")) {
+      warn(
+        where,
+        `declares record-report attachments but the manifest has no 'metadata' dependency. The 'entity_report' table ships with the metadata system module \u2014 add "metadata": ">=1.5.0" to dependencies so install fails loudly on a platform without it, rather than the attachment quietly doing nothing.`
+      );
+    }
+  }
   const roleCodes = Object.keys(roles);
   const localeFiles = fs11.existsSync(paths.translationsDir) ? fs11.readdirSync(paths.translationsDir).filter((f) => f.toLowerCase().endsWith(".json")).sort() : [];
   for (const raw of supportedLocales) {

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.5",
+	"version": "0.2.14",
 	"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",
-	"packageManager": "pnpm@11.21.0",
+	"packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
@@ -35,8 +35,8 @@
 		"install-skills": "node scripts/install-skills.mjs"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.13",
-		"@dforge-core/metadata": "^0.0.14",
+		"@dforge-core/dforge-cli": "^0.2.14",
+		"@dforge-core/metadata": "^0.0.15",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/docs/dsl-reference.md

@@ -401,7 +401,7 @@ the server translates to an exact `::bigint` SQL literal.
 #### `info(message, opts?)`, `warn(message, opts?)`
 Queue user-facing toast. `opts.links: [{entity, id}]` adds "open record" buttons.
 
-A message is a **receipt for work the action did**, not a way to publish a computed value. An action whose only output is `info('<some computed number>')` stores nothing — it can't be audited, re-read or reported on, and the value arrives unformatted. Build a report, a formula column, or an action that writes a result record instead. See `dforge://reference/action-dsl`, *When an action is the wrong tool*.
+A message is a **receipt for work the action did**, not a way to publish a computed value. An action whose only output is `info('<some computed number>')` stores nothing — it can't be audited, re-read or reported on, and the value arrives unformatted. Build a **record report** (a report with an `entities` attachment: it lands on the same record toolbar, but shows the numbers *and* the rows behind them, re-read live on every open), a formula column, or an action that writes a result record instead. Do not compute in DSL what a report dataset already aggregates. See `dforge://reference/action-dsl`, *When an action is the wrong tool*, and `dforge://reference/reports`.
 
 ```dsl
 info('Created PO ' + po.po_number, {

package/resources/schemas/data-views.schema.json

@@ -247,11 +247,51 @@
 			"additionalProperties": false
 		},
 
+		"calculatedMember": {
+			"type": "object",
+			"description": "A synthetic, read-only member of a pivot-like view — a row (default) or column derived by a formula over other members at each cross-axis position. Platform-generic: any pivot-like surface consumes the same shape, so a module declares the metric in config with no platform code change. Pure presentation — no storage, evaluated client-side by the stock formula engine.",
+			"required": ["key", "label", "refs", "formula"],
+			"properties": {
+				"key": { "type": "string", "description": "Stable render key. Must not collide with a real member key." },
+				"axis": { "type": "string", "enum": ["row", "column"], "default": "row", "description": "Which axis the member is added to. A calculated ROW is a formula over other rows evaluated once per column; a calculated COLUMN is the transpose." },
+				"label": { "type": "string", "description": "Member label shown in the row/column head." },
+				"field": { "type": "string", "description": "Value field the refs read. Defaults to the surface's first value field." },
+				"refs": {
+					"type": "object",
+					"description": "Formula bracket-alias → referenced member identity on the same axis.",
+					"additionalProperties": { "type": "string" }
+				},
+				"formula": { "type": "string", "description": "Formula over the aliases, e.g. `[gp] / [rev] * 100`. Same `[name]` syntax as column formulas. A non-finite result (÷0, missing denominator) renders empty." },
+				"position": {
+					"description": "Placement on the axis. Defaults to the end.",
+					"oneOf": [
+						{ "type": "object", "required": ["after"], "properties": { "after": { "type": "string", "description": "Key of the member to place this one after." } }, "additionalProperties": false },
+						{ "type": "object", "required": ["at"], "properties": { "at": { "type": "string", "enum": ["end"] } }, "additionalProperties": false }
+					]
+				},
+				"depth": { "type": "integer", "minimum": 0, "description": "Indent depth (row members only; 0 = top level)." },
+				"format": {
+					"type": "object",
+					"description": "Display format for the result.",
+					"properties": {
+						"style": { "type": "string", "enum": ["number", "percent"], "default": "number" },
+						"decimals": { "type": "integer", "minimum": 0, "default": 1 }
+					},
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		},
 		"matrixViewConfig": {
 			"type": "object",
 			"description": "Matrix (pivot) view: rowAxis × colAxis grid with a value-source cell entity holding one record per (rowKey, colKey).",
 			"required": ["rowAxis", "colAxis", "cell"],
 			"properties": {
+				"calculatedMembers": {
+					"type": "array",
+					"description": "Synthetic read-only members derived by formula over OTHER members' values (e.g. a Gross Margin % row). Spliced into the rendered axis; never loaded or saved.",
+					"items": { "$ref": "#/$defs/calculatedMember" }
+				},
 				"rowAxis": {
 					"description": "Row axis values: an entity's records ('dataset') or a column's dropdown options ('dropdown').",
 					"oneOf": [

package/resources/schemas/manifest.schema.json

@@ -133,6 +133,12 @@
 			"items": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$" },
 			"description": "Non-English locales the package promises to translate. Each entry MUST match a translations/<locale>.json file, and every translatable resource (entity/field labels, folders, views, menus + items, actions + params, reports + datasets + params, settings) MUST have a label in that file. English is the default — don't list 'en' or 'en-US'."
 		},
+		"features": {
+			"type": "array",
+			"items": { "type": "string", "enum": ["report-security"] },
+			"uniqueItems": true,
+			"description": "Opt-in platform behaviours this package was authored for. Absent or empty = the pre-feature behaviour for all of them, so a module written before a feature existed keeps working until its author declares it and republishes. Unknown names are REJECTED at package load, never ignored — a misspelled feature would silently leave the old behaviour in place while the manifest claims otherwise. Values: 'report-security' = this module's reports require 'E' on their sec_object; declare the matching \"report:<code>\": \"E\" grants in security/roles.json first, or the reports go dark for every role."
+		},
 		"created": {
 			"type": "string",
 			"format": "date",

package/resources/schemas/reports.schema.json

@@ -24,10 +24,42 @@
 					"description": "Map of dataset code → dataset definition. Panels reference datasets by code via `datasetCd`.",
 					"additionalProperties": { "$ref": "#/$defs/dataset" }
 				},
+				"reloadInterval": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Auto-refresh interval in seconds. Omit (or 0) for no auto-refresh."
+				},
 				"parameters": {
 					"type": "object",
-					"description": "Report-level parameters (alternative to per-dataset `params`). Map of param code → param definition.",
+					"description": "Report-level parameter declarations — the canonical home for a parameter, and the only one that fits a parameter several datasets use. Parameters are report-scoped throughout the platform: one `param_set` per report, `report.params.save` in the authoring API, and `report.get` flattens per-dataset defaults report-wide before use. A parameter declared under a dataset's `params` is shorthand for declaring it here; the installer merges both into one set, with this block winning on a code collision.",
 					"additionalProperties": { "$ref": "#/$defs/paramDef" }
+				},
+				"entities": {
+					"type": "array",
+					"description": "Record-report attachments: entities this report can be opened from, with the mapping from report parameter to source column on that entity. Each entry becomes one `dForge.entity_report` row. See docs/business-logic/record-reports.md.",
+					"items": { "$ref": "#/$defs/entityAttachment" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"entityAttachment": {
+			"type": "object",
+			"description": "One (entity, report) attachment. The binding is per-attachment, not per-report — the same report can attach to several entities with different parameter mappings.",
+			"required": ["entityCd"],
+			"properties": {
+				"entityCd": {
+					"type": "string",
+					"description": "Entity the report attaches to, qualified `module.entity` for anything outside the declaring module. The owning module must be this module or a declared dependency."
+				},
+				"params": {
+					"type": "object",
+					"description": "Parameter mapping: report param code → source column on the entity. Stored as `entity_report.param_map` and resolved server-side from the record's PK. Source columns are limited to the PK, reference (`R`) columns, and bounded scalars (number, date/datetime, bool, dropdown/radio/flags code); source and target must be type-compatible. Params left unmapped keep their normal behaviour (default value, or prompt the user).",
+					"additionalProperties": { "type": "string" }
+				},
+				"orderNum": {
+					"type": "integer",
+					"description": "Sort position in the record's combined action + report menu."
 				}
 			},
 			"additionalProperties": false
@@ -228,7 +260,7 @@
 				},
 				"params": {
 					"type": "object",
-					"description": "Dataset-level parameters (alternative to top-level `parameters`)",
+					"description": "Parameters declared on this dataset — shorthand for the report-level `parameters` block, convenient when exactly one dataset uses the parameter. Either way the parameter is REPORT-scoped: `ReportRegistrar` merges the report-level block and every dataset's `params` into the report's one `param_set`, so a parameter declared here serves the whole report (the param bar, saved param sets, `@param` filters in any dataset, and record-report `entities[].params` mappings). On a code collision the report-level block wins. Declare a parameter used by several datasets at report level — there is no meaningful dataset to attribute it to.",
 					"additionalProperties": { "$ref": "#/$defs/paramDef" }
 				}
 			},
@@ -330,30 +362,22 @@
 					"type": "integer",
 					"description": "Display order of the parameter in the report's parameter form. Read by ReportRegistrar (paramDef.OrderNum); falls back to declaration order when omitted."
 				},
+				"columnType": {
+					"type": "string",
+					"enum": ["R"],
+					"description": "Declares a REFERENCE parameter: its submitted value is the whole picked record rather than the bare key. The JSON counterpart of the action DSL's `paramCd: ref <entityCd>`, stored in the same `param.column_type`. Optional — omitting it (a plain `lookup`) submits the key, which is what a filter comparing against a reference column needs, since the server destructures a key object across every key column and ignores non-key fields. Declare \"R\" when the report wants the record itself, not just its identity."
+				},
 				"required": {
 					"type": "boolean",
 					"default": false,
-					"description": "Whether the user must provide a value (older modules also use `isRequired`)"
-				},
-				"isRequired": {
-					"type": "boolean",
-					"description": "Alternate spelling of `required` used by some modules. Prefer `required` for new code."
+					"description": "Whether the user must provide a value. Stored inverted as `param.is_nullable`. There is no `isRequired` spelling — `ReportParamDef` reads this key only."
 				},
 				"default": {
 					"description": "Default value applied if the user doesn't provide one"
 				},
-				"link": {
-					"type": "object",
-					"description": "Entity link for lookup-type params (alternative to nesting under `params.link`). Shape: { entity: '<code>', otherKey?: '<column>' }.",
-					"properties": {
-						"entity": { "type": "string" },
-						"otherKey": { "type": "string" }
-					},
-					"additionalProperties": false
-				},
 				"params": {
 					"type": "object",
-					"description": "Field-type-specific params (e.g. lookup → { link: { entity, otherKey } })"
+					"description": "Field-type-specific params, nested under this key — there is no top-level `link`. A `lookup` param needs `{ \"link\": { \"entity\": \"<code>\", \"otherKey\": \"<column>\" } }`; `otherKey` auto-fills from the target's PK when omitted. Without `params.link` a lookup param installs, warns, and has no autocomplete."
 				}
 			},
 			"additionalProperties": false

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

@@ -11,11 +11,14 @@ An action exists to **change something**. Its message is a receipt for work that
 
 Do **not** write an action whose `execute:` block only reads data, computes a value and reports it with `info()`. The result is a line of text that is never stored: it can't be audited, referenced, re-read or reported on, and every reader has to re-run the action to see it again. The value also reaches the user unformatted — a raw `query()` result carries no column metadata, so money renders as `1000.0099999999999` instead of `1,000.01`.
 
+**Do not compute in the DSL what a report can compute.** Sums, ratios, ageing buckets, exposure, "how much is outstanding" — a report dataset already does aggregation, formatting, drill-through and row caps, and it re-reads live data every time it opens. DSL arithmetic over `select()` results reproduces that badly, once, in a place nothing else can reuse. Reach for the DSL when the number has to be **written down** or has to **stop** something; reach for a report when it has to be **looked at**.
+
 If you are about to write a `check_…`, `calculate_…` or `show_…` action, build one of these instead:
 
 | What's actually needed | Build this |
 |---|---|
-| The user needs to **see** current numbers | A **report** or a data view — both are metadata-driven, so values format correctly, and the user can return to them any time without re-running anything. |
+| The user needs to **see** current numbers **for the record they're on** | A **record report** — a report with an `entities` attachment, which puts it on that record's toolbar and feeds its params from the record. This is the direct replacement for a `check_…` action: same entry point, but the user sees the open invoices and the ageing, not just "FAILED". See `references/reports.md`. |
+| The user needs to **see** current numbers generally | A **report** or a data view — both are metadata-driven, so values format correctly, and the user can return to them any time without re-running anything. |
 | A derived value **belongs to the record** | A **formula column** (`columnType: "F"`) or a roll-up — computed on read, visible on the card and in grids, filterable and sortable. |
 | The **verdict itself matters** (approvals, credit checks, compliance) | An action that **writes a result record** — e.g. `credit_check(customer, checked_at, limit, outstanding, projected, verdict, checked_by)`. Now it's auditable and reportable, and `info()` becomes a legitimate receipt with a link to the new row. |
 | The check must **block** something | A **trigger** with `async: false`, or a `canExecute:` guard on the action being gated — enforcement, not narration. |

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

@@ -71,6 +71,35 @@ The manifest lists every file in the package by logical key. The installer reads
 | `supportedLocales` | string[] | IETF locale tags that the module ships translations for, e.g. `["de-DE", "uk-UA"]`. Files are **auto-discovered** at `./translations/{locale}.json` — there is no per-file manifest entry. English (`en`/`en-*`) is the default and must not be listed. |
 | `printTemplates` | object | `{ "template_code": "./print_templates/template.scriban" }` |
 | `webhooks` | string | path to `./webhooks.json` |
+| `features` | string[] | Opt-in platform behaviours this package was authored for, e.g. `["report-security"]`. Absent/empty = the pre-feature behaviour. See **Feature opt-ins** below. |
+
+## Feature opt-ins
+
+`dependencies` answers "does the platform have this?". `features` answers "should this behaviour apply to **my** module?".
+
+They exist for opposite failure modes. A dependency is a hard gate — the module will not install without it. A feature is the reverse: the platform already has the behaviour, but switching it on for every installed module at once would break every package written before it existed. So it stays off per module until the author asks for it.
+
+```json
+"features": ["report-security"]
+```
+
+| Feature | Effect |
+|---|---|
+| `report-security` | This module's reports require the `E` right on their security object — checked when running or opening a report and when reading or changing its saved presets and panel layouts. Without it, a report is reachable by anyone who can read the underlying data. |
+
+**Adopting one is two releases, in order:**
+
+1. Add `"report:<report_code>": "E"` to every role in `security/roles.json` that should reach each report. Bump `version`, install.
+2. Add `"features": ["report-security"]`. Bump `version` again, install.
+
+Do it in the other order and every report in the module denies for every role until the grants land. Both steps need a version bump — a same-version install is skipped, so the tenant would keep the old manifest.
+
+**Rules:**
+
+- Unknown names are **rejected** at package load, not ignored. A misspelled `report-securty` would otherwise leave the old behaviour in place while the manifest claims the protection is on.
+- Casing and surrounding whitespace are normalised; the canonical spelling is lowercase.
+- Removing a feature genuinely removes it on the next install — an opt-in is a migration window, not a one-way door.
+- Installing against an older platform that predates the feature is safe: unknown manifest keys are ignored there, so the module runs the old behaviour.
 
 ## Dependencies
 

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

@@ -7,7 +7,7 @@ SP files: `logic/reports/rpt_*.sql`
 
 ## Structure
 
-A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), and optional `parameters`. Panels reference datasets by code via `datasetCd`.
+A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), optional per-dataset `params`, and an optional `entities` array (record-report attachments). Panels reference datasets by code via `datasetCd`.
 
 ```json
 {
@@ -17,12 +17,18 @@ A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...
             "pipeline": {
                 "caption": "Pipeline Data",
                 "datasetType": "Q",
+                "params": {
+                    "min_amount": { "fieldTypeCd": "number", "label": "Min Amount", "required": false, "default": 0 }
+                },
                 "query": {
                     "entityCd": "opportunity",
                     "columns": ["stage", "amount", "lead_source", "customer.name"],
                     "filter": {
                         "g": "and",
-                        "i": [ { "c": "stage", "o": "nIn", "v": ["Closed Won", "Closed Lost"] } ]
+                        "i": [
+                            { "c": "stage", "o": "nIn", "v": ["Closed Won", "Closed Lost"] },
+                            { "c": "amount", "o": "grEq", "v": "@min_amount" }
+                        ]
                     },
                     "sort": [ { "c": "amount", "d": "desc" } ]
                 }
@@ -38,9 +44,6 @@ A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...
                 },
                 { "vizType": "table", "datasetCd": "pipeline", "title": "Pipeline Detail" }
             ]
-        },
-        "parameters": {
-            "min_amount": { "fieldTypeCd": "number", "label": "Min Amount", "required": false, "default": 0 }
         }
     }
 }
@@ -85,7 +88,7 @@ For SQL the query builder can't express — window functions, CTEs, cross-schema
     "spCd": "rpt_ar_aging",
     "params": {
         "as_of_date": { "fieldTypeCd": "date", "label": "As of Date", "required": true, "default": "=NOW()" },
-        "customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "entityCd": "account" } }
+        "customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "link": { "entity": "account" } } }
     },
     "columnsDef": {
         "customer_name": { "label": "Customer", "fieldTypeCd": "text", "baseDatatypeCd": "string", "width": 200 },
@@ -99,7 +102,7 @@ Key differences from entity datasets:
 - `datasetType: "S"`.
 - `spCd` — the stored-procedure code (the function name **without** the schema prefix; resolved to `sp_id` at install). (**Not** `sp` or `procedureName`.)
 - `columnsDef` — **required** — the platform can't infer columns from a function.
-- Params can be per-dataset or per-report.
+- Params work exactly as they do for an entity dataset, and `datasetType` makes no difference: declare them at report level (`parameters`) or on the dataset (`params`). Report level wins on a code collision.
 
 **Multi-result-set SPs** map extra datasets to the same function via `parentDatasetCd` (the dataset that owns the SP call) + `parentRef` (the named refcursor):
 
@@ -139,16 +142,33 @@ $$;
 
 ## Parameters
 
-Parameters prompt the user before running the report. Declare them per-report (`parameters`) or per-dataset (`params`).
+Parameters prompt the user before running the report.
+
+**Parameters are report-scoped**, so there are two legal declaration sites and they mean the same thing:
+
+- **`parameters`** at report level — the canonical home, and the only one that fits a param several datasets use.
+- **`datasets.<cd>.params`** — shorthand, fine when exactly one dataset uses it. Every module written before this existed uses it, and it stays fully supported.
+
+The installer merges both into the report's single param set (**report level wins** on a code collision), so either way the param serves the whole report: the param bar, saved param sets, `@param` filters in *any* dataset, and record-report mappings.
+
+> Why report-scoped: the declaration is stored once per report (`report.param_set_id` → `param_set`), the authoring API is `report.params.save`, and `report.get` flattens per-dataset defaults report-wide before use. There is no dataset-scoped parameter behaviour to choose between.
 
 ```json
 "parameters": {
-    "start_date": { "fieldTypeCd": "date", "label": "Start Date", "required": true, "default": "=STARTMONTH()" },
-    "status":   { "domain": "fin.doc_status", "label": "Status" },
-    "region": { "fieldTypeCd": "dropdown", "label": "Region", "params": { "options": [
-        { "value": "north", "label": "North" }, { "value": "south", "label": "South" }
-    ] } },
-    "customer": { "fieldTypeCd": "lookup", "label": "Customer", "params": { "entityCd": "account" } }
+    "customer": { "fieldTypeCd": "lookup", "label": "Customer", "params": { "link": { "entity": "account" } } }
+},
+"datasets": {
+    "sales": {
+        "datasetType": "Q",
+        "params": {
+            "start_date": { "fieldTypeCd": "date", "label": "Start Date", "required": true, "default": "=STARTMONTH()" },
+            "status":   { "domain": "fin.doc_status", "label": "Status" },
+            "region": { "fieldTypeCd": "dropdown", "label": "Region", "params": { "options": [
+                { "value": "north", "label": "North" }, { "value": "south", "label": "South" }
+            ] } }
+        },
+        "query": { "entityCd": "invoice", "columns": ["invoice_number", "total"] }
+    }
 }
 ```
 
@@ -159,9 +179,11 @@ Parameters prompt the user before running the report. Declare them per-report (`
 | `label` | Display label in the parameter dialog |
 | `required` | Whether the user must fill this before running |
 | `default` | Plain value or `=`-prefixed formula (`"=NOW()"`, `"=STARTMONTH()"`, `"=TODAY()"`) |
-| `params` | Extra config — `options` for dropdowns, `entityCd` for lookups |
+| `params` | Extra config — `options` for dropdowns, `link: { entity, otherKey? }` for lookups |
 | `orderNum` | Display order in the parameter form (falls back to declaration order) |
 
+Two spellings that look right and are silently ignored: **`isRequired`** (the key is `required`, so the param installs as optional) and a **top-level `link`** (it must be nested under `params`, so the lookup installs with no autocomplete). Both are validator errors.
+
 **Dropdown params: prefer `domain`, and never ship bare codes.** A list shared with a column belongs on a `column_domain` — bind the param to it and the options plus their translations are authored once (`column-domains.md`). For a list that exists only for this report, write the rich option form (`{ "value": "north", "label": "North" }`); a bare `"options": ["north", "south"]` renders the raw codes in **every** locale, English included. Per-locale labels go under `reports.<cd>.params.<param_cd>.options` (`translations.md`).
 
 Reference a parameter with `@param_code` inside a query filter value:
@@ -260,14 +282,72 @@ Dashboard KPI/chart *tiles* get the same support via a `sources` map in the tile
 
 `config.chartSize` ∈ `sm | m | l | xl` controls the default chart height (`m` when omitted).
 
+## Record reports (`entities`)
+
+A report can be **attached to an entity** so it opens from a record — the way a print template does — with the record's values feeding its parameters. Add an `entities` array to the report:
+
+```json
+"credit_check": {
+    "description": "Customer Credit Check — limit against outstanding AR and open quotes",
+    "entities": [
+        { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 },
+        { "entityCd": "crm.quote",     "params": { "customer_id": "customer_id" }, "orderNum": 45 }
+    ],
+    "parameters": {
+        "customer_id": {
+            "label": "Customer",
+            "fieldTypeCd": "lookup",
+            "params": { "link": { "entity": "parties.party" } },
+            "required": true
+        }
+    },
+    "layout": { "panels": [ { "vizType": "table", "datasetCd": "open_invoices" } ] },
+    "datasets": {
+        "open_invoices": {
+            "caption": "Open Invoices",
+            "datasetType": "Q",
+            "query": {
+                "entityCd": "invoice",
+                "columns": ["invoice_number", "due_date", "amount_due"],
+                "filter": { "g": "and", "i": [ { "c": "customer_id", "o": "eq", "v": "@customer_id" } ] }
+            }
+        }
+    }
+}
+```
+
+Each entry becomes one attachment row, and the report gains a toolbar entry on that entity's record. Note the two different `params` keys:
+
+- `entities[].params` — the **mapping**: report param code → **source column on the attached entity**.
+- `parameters` / `datasets.<cd>.params` — the param **declaration**. The mapping can only name codes declared in one of those.
+
+| Rule | Detail |
+|---|---|
+| `entityCd` | Qualified `module.entity` for anything outside this module, and that module must be a **declared dependency**. |
+| Source columns | The entity PK, a reference (`R`) column, or a bounded scalar (number, date/datetime, bool, dropdown/radio/flags code). `text`, `json`, `file`/`image` are rejected. |
+| Types | Source and target must be compatible; only `lookup`↔`number` and `date`↔`datetime` widen. A names-only match like `{ "customer_id": "created_date" }` is an error, not a runtime surprise. |
+| One per pair | One attachment per (entity, report). Two entries for the same entity overwrite each other. |
+| Unmapped params | Keep their normal behaviour — default value, or prompt the user. |
+| Mapped params | Are **hidden** on the record-report page. The URL is about this record; pivoting means going back to a record. |
+| Dependency | Declare `"metadata": ">=1.5.0"` — the attachment table ships with the metadata system module, so this is the gate that fails loudly on an older platform instead of the attachment quietly doing nothing. This is metadata's **`version`**; dependency ranges are never checked against `dbSchemaVersion`, so do not use the `1.4.0` of the migration that creates the table. |
+| Rights | Report `E` is still required. A bridge role must grant `E` on the report **and** `S` on the dataset entities. |
+
+There is no `canExecute` on an attachment: if the record exists the report is meaningful for it, and an empty report is a legitimate answer.
+
+> **Prefer a record report over an action that calculates.** See *When an action is the wrong tool* in `references/action-dsl.md`. If the `execute:` block only reads, computes and `info()`s a number, it is not an action — a printed number is never stored, can't be re-read, and shows the verdict without the working. Attach a report instead: it gets you KPI tiles, charts, the underlying rows, drill-through, saved layouts and row caps for free, and the DSL you don't write is DSL that can't drift from the data.
+>
+> Keep it an action when it **changes** something — writing the result to a column, creating a record, or *blocking* a transition. "Explain the number" is a report; "refuse the over-limit quote" is an action or trigger.
+
 ## Grants
 
-Grant report access with the `E` right:
+Grant report access with the `E` right — a **colon** prefix, never a dot:
 
 ```json
-"rights": { "report.sales_pipeline": "E" }
+"rights": { "report:sales_pipeline": "E" }
 ```
 
+A dependency's report is granted with the qualified form, `"report:fin.ar_aging": "E"` — bridge modules need this to grant on a report they attach but do not own.
+
 ## Common mistakes
 
 - Using a bare `"layout": [ ... ]` array — `layout` is an **object**: `"layout": { "panels": [ ... ] }`.
@@ -276,5 +356,11 @@ Grant report access with the `E` right:
 - Using `sp` / `procedureName` for an SP dataset — the field is `spCd`.
 - Forgetting `columnsDef` on an SP dataset — **required**.
 - Forgetting to grant `E` on the report in at least one role — it becomes invisible.
+- Writing the rights key as `report.<code>` — actions/reports/folders take a **colon**: `report:<code>`.
+- Writing `isRequired` instead of `required`, or a top-level `link` instead of `params.link` — both are ignored at install.
+- Declaring both `fieldTypeCd` and `domain` on one param — install rejects the pair rather than picking a winner.
+- Mapping a record-report attachment onto a param no dataset declares, or from a `text`/`json` column — both are rejected.
+- Attaching a report to another module's entity without declaring that module as a dependency.
 - Forgetting `p_folder_uid` / `p_user_id` as the first two SP function params — the call fails.
 - Referencing a parameter as `$param` — use `@param_code` in filters.
+- Writing an action that computes a number and `info()`s it, where a record report would show the working.

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

@@ -73,6 +73,9 @@ For each entity:
 - [ ] Each source has `entityCode` and `columns`
 - [ ] `entityCode` points to an entity that exists
 - [ ] Column codes in `columns` all exist on the entity
+- [ ] No `columns` entry is a **set** (`columnType: "S"`) — a 1:N collection has no per-row value to put in a column; show it on the record card instead. **Rejected at validate/pack**
+- [ ] No `columns` entry is a **dotted navigation path** (`owner.email`, `account.company_name`) — a view's column list is matched against the entity's own columns, so a dotted entry resolves to nothing. Add a Reference (`R`) or Formula (`F`) column to the entity and list that. **Rejected at validate/pack**
+- [ ] A listed column does **not** need `V` in its flags — the renderer promotes anything the list names (that is how trait-contributed `created_by_user`, flagged `I`, appears). Listing a non-`V` column is valid intent, not a mistake
 - [ ] The rendered entity has **at least one visible scalar column** (a field with `V` in `flags`, `columnType` not `S`) — a grid/list/kanban/etc. view over an entity whose fields are all hidden (or only sets) is **rejected** at validate/pack and would render "No visible columns configured for this entity." `diagram`/`matrix`/`library` are exempt
 - [ ] If set, `viewType` is from the supported list (`grid`, `list`, `kanban`, `calendar`, `gallery`, `tree-grid`, `diagram`, `master-detail`, `library`, `matrix`)
 - [ ] A `matrix` view has a `viewConfig` with `rowAxis`, `colAxis`, and `cell` (cell `entity` matches the primary `dataSources` entity; `rowKey`/`colKey` are real cell columns)
@@ -89,6 +92,16 @@ For each entity:
 - [ ] Every `reportCode` points to a report that exists
 - [ ] `orderNum` is set on each node for deterministic ordering
 
+## Reports (`ui/reports.json`)
+
+- [ ] Params are declared in the report-level `parameters` block, or under `datasets.<cd>.params` — a param several datasets use belongs at report level (the installer merges both; report level wins on a collision)
+- [ ] Params use `required` (not `isRequired`), and a lookup nests its binding as `params: { link: { entity } }` (not a top-level `link`)
+- [ ] No param declares both `fieldTypeCd` and `domain`
+- [ ] `layout` is an object (`{ "panels": [...] }`), and the chart kind is `config.chartType` with `vizType: "chart"`
+- [ ] Record-report attachments (`entities`): every mapped param code is declared at report level or on a dataset; every source column is the PK, a reference (`R`) column, or a bounded scalar; cross-module `entityCd` is qualified and its module is a declared dependency
+- [ ] A module with attachments declares `"metadata": ">=1.5.0"`
+- [ ] No `check_…` / `calculate_…` action exists that a record report should be
+
 ## Security
 
 - [ ] `security/roles.json` exists (at least one role)

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

@@ -172,9 +172,12 @@ to fill a sub-step** — a pure CRUD module skips Phase 2 entirely (record it wi
 
 **2a Actions.** First check the action is an action at all: it must **change**
 something. If the `execute:` block would only read, compute and `info()` the
-answer, build a report, a formula column, or an action that writes a result
-record instead — a printed number is never stored and can't be re-read
-(`dforge://reference/action-dsl`, *When an action is the wrong tool*). Then load
+answer, build a **record report** (a report with an `entities` attachment — same
+toolbar entry point, but it shows the working and re-reads live data), a formula
+column, or an action that writes a result record instead — a printed number is
+never stored and can't be re-read (`dforge://reference/action-dsl`, *When an
+action is the wrong tool*). Do not compute in DSL what a report dataset already
+aggregates. Then load
 all four resources in the action row — the wrong-field-access /
 wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only surface when
 you cross-check them. Draft the DSL, run
@@ -219,10 +222,31 @@ pointing at the views.
 
 If none fire, skip specialized views for that entity.
 
-**3c. Reports** only when aggregation/grouping isn't covered by views.
+**3c. Reports** only when aggregation/grouping isn't covered by views — or when
+Phase 2a sent you here because the "action" only wanted to show a number.
+
+Params are **report-scoped**: declare them in the report-level `parameters`
+block, or as shorthand under `datasets.<cd>.params` when exactly one dataset uses
+the param. The installer merges both into the report's one param set, report level
+winning on a collision — so a param several datasets share belongs at report level.
+Grant with a **colon** key: `"report:<code>": "E"`.
+
+A report that answers a question *about one record* takes an `entities`
+attachment, which puts it on that record's toolbar with the record's values
+feeding its params:
+
+```json
+"entities": [ { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 } ]
+```
+
+`entities[].params` is the **mapping** (report param → source column), not a
+param declaration. Qualify a cross-module `entityCd` and declare that module as a
+dependency; add `"metadata": ">=1.5.0"` too. Source columns are limited to the
+PK, a reference column, or a bounded scalar. Full rules:
+`dforge://reference/reports`.
 
 **Exit:** every entity has a grid and a menu entry; every specialized view has a
-stated trigger.
+stated trigger; every report's params sit on a dataset.
 
 ## Phase 4 — Polish (mostly optional)