@dforge-core/dforge-mcp 0.2.33 → 0.2.34

package/CHANGELOG.md

@@ -4,7 +4,38 @@ 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.
 
-## Unreleased
+## 0.2.34 — 2026-10-06
+
+**A report has a `label` beside its `description`** (dForge-core 61ad762). The label is
+the report's name — page title, breadcrumb, parameter dialog — and the description shows
+under it, as a data view's does. Without a label the description is the name, as before,
+and the platform now warns about it.
+
+- `dforge_report_add` takes `report.label`, writes it ahead of `description`, and warns
+  when it is omitted. Its help asks for a short label plus a description.
+- `dforge_module_validate` warns, with the platform's wording, about a report with no
+  label. The CLI's copy of the same warning is listed once.
+- `dforge://schema/reports` carries `label`. Pre-staged from dForge-core; it is
+  re-vendored from `@dforge-core/metadata` 0.0.34 at publish, and the CLI warning needs
+  `@dforge-core/dforge-cli` 0.2.27.
+- `dforge://reference/reports` and the build skill name reports with `label`.
+
+**Upgrade migrations** (dForge-core 9e93062). A module may ship `migrations/<version>.sql`
+for the data a new version reshapes; an upgrade runs each one above the installed version,
+inside the install transaction. `dforge://docs/conventions` and the manifest reference say
+when they run, how they are named, `"dForge".next_id()` and the `"admin": ">=1.21.0"`
+dependency; the ship skill's version audit asks for one when a release moves data.
+`dforge_module_pack` packs the whole directory, `migrations/` included.
+
+**A dependency on a system module may name no entity.** `dforge_dependency_add` takes
+`entities: []` against admin, metadata, workspace or sys-billing — a pure platform-version
+gate such as `"admin": ">=1.21.0"` for upgrade migrations. It writes `"entities": {}` to
+the contract and a plain version string to the manifest. Any other module still needs an
+entity. `dforge://schema/deps` says the same, pre-staged from dForge-core.
+
+- Dependencies: `@dforge-core/metadata` `^0.0.34`, `@dforge-core/dforge-cli` `^0.2.27`.
+
+## 0.2.33
 
 **`isView` / `viewSql` are gone** (dForge-core#1312). SQL-view entities were in the
 entity schema and the references but never built: the entity installed as an empty table,

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.26/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.27/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31210,9 +31210,14 @@ var SCHEMA_BINDINGS = [
   { fileMatch: ["logic/triggers.json"], schema: "triggers" },
   { fileMatch: ["logic/webhooks.json"], schema: "webhooks" },
   { fileMatch: ["deps/*.json"], schema: "deps" },
-  { fileMatch: ["seed-data/*.json"], schema: "seed-data" },
+  { fileMatch: ["seed-data/*.json", "demo-data/*.json"], schema: "seed-data" },
   { fileMatch: ["settings.json"], schema: "settings" },
-  { fileMatch: ["translations/*.json"], schema: "translations" }
+  { fileMatch: ["translations/*.json"], schema: "translations" },
+  { fileMatch: ["domains.json"], schema: "domains" },
+  { fileMatch: ["registers.json"], schema: "registers" },
+  { fileMatch: ["traits.json"], schema: "traits" },
+  { fileMatch: ["ui/card_layouts.json"], schema: "card-layouts" },
+  { fileMatch: ["logic/stored_procedures.json"], schema: "stored-procedures" }
 ];
 function schemaEntries() {
   return SCHEMA_BINDINGS.map((b) => ({
@@ -31285,7 +31290,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.33/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.34/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -34597,7 +34602,7 @@ var path10 = __toESM(require("path"));
 var fs7 = __toESM(require("fs"));
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.33/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.34/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -35377,6 +35382,45 @@ var BUILTINS = [
     returns: "object",
     doc: "Load the referenced record for a FK column. Read its fields with `ref.get('field')`."
   },
+  // Register reads. The first argument names a REGISTER (`module_cd.register_cd`,
+  // declared in that module's registers.json) and not an entity, so none of these
+  // carries `entityArg` — entity-code completion there would offer the wrong list.
+  {
+    name: "getBalance",
+    signature: "getBalance(register, dims?, asOf?)",
+    returns: "object",
+    doc: "Balance of an accumulation register per resource. A dimension left out of `dims` is summed over, so passing none gives the register's total. `asOf` reads as of a date instead of now."
+  },
+  {
+    name: "getTurnover",
+    signature: "getTurnover(register, dims, from, to)",
+    returns: "object",
+    doc: "What moved through a register over an interval: `{in, out, net}` per resource. `dims` may be `null` to sum over every dimension; `from` and `to` are both required."
+  },
+  {
+    name: "getSlice",
+    signature: "getSlice(register, dims, onDate?, mode?)",
+    returns: "object | null",
+    doc: "One record of an information register \u2014 the latest on or before `onDate`, or `null` when there is none. Returns the record plus `_period`. Unlike a balance, a dimension may NOT be omitted: a slice is one keyed record, not a sum."
+  },
+  {
+    name: "getAccountBalance",
+    signature: "getAccountBalance(register, account, filter?, asOf?)",
+    returns: "object",
+    doc: "Balance of one account of an accounting register: `{debit, credit, net}` per resource. `filter` narrows by a dimension, or by an analytic kind the ACCOUNT declares \u2014 an analytic takes the key alone, or `{ entity, value }` to name one entity of a kind that is a union of several."
+  },
+  {
+    name: "getAccountTurnover",
+    signature: "getAccountTurnover(register, account, filter, from, to)",
+    returns: "object",
+    doc: "What moved through one account over an interval: `{debit, credit, net}` per resource. `filter` narrows as in `getAccountBalance` and may be `null`; `from` and `to` are both required."
+  },
+  {
+    name: "getCorrespondence",
+    signature: "getCorrespondence(register, debitAccount, creditAccount, filter, from, to)",
+    returns: "object",
+    doc: 'What moved between two accounts over an interval. Needs `lineMode: "compound"` \u2014 a classic register records the other half of an entry as an untied second row and cannot answer this. `filter` narrows by dimensions the two sides share, never by an analytic (an analytic belongs to one account and this read names two).'
+  },
   // Messaging
   {
     name: "error",
@@ -37149,11 +37193,141 @@ ${warnings.map((w) => `  \u2022 ${w}`).join("\n")}` : void 0
 // src/tools/adds.ts
 var fs11 = __toESM(require("fs"));
 var path14 = __toESM(require("path"));
+
+// src/tools/validate/reports.ts
+function unlabeledReportMessage(reportCd, description) {
+  const desc = typeof description === "string" && description.trim() !== "" ? description : void 0;
+  return `Report '${reportCd}' declares no "label", so its description names it` + (desc ? `: "${desc}".` : ".") + " Add a short label; the description then shows under it.";
+}
+function checkReports(ctx) {
+  const { manifest, err, warn, fieldDefsOf, deps, isKnownEntity, reports } = ctx;
+  for (const [rcode, rawReport] of Object.entries(reports)) {
+    const report = rawReport ?? {};
+    const where = `ui/reports.json \u2192 ${rcode}`;
+    if (typeof report.label !== "string" || report.label.trim() === "") {
+      warn("ui/reports.json", unlabeledReportMessage(rcode, report.description));
+    }
+    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.`
+      );
+    }
+  }
+}
+
+// src/tools/adds.ts
 var reportAddSchema = {
   moduleDir: external_exports.string(),
   code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Report code (keys ui/reports.json)."),
   report: external_exports.object({
-    description: external_exports.string(),
+    label: external_exports.string().optional().describe(
+      "The report's name: page title, breadcrumb and parameter dialog. Keep it short ('Trial Balance'). Omitted, the description names the report and pack/validate/install warn."
+    ),
+    description: external_exports.string().describe("What the report shows, under its label on the page ('Debit and credit totals per account for a period')."),
     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().describe(
@@ -37169,7 +37343,7 @@ var reportAddSchema = {
       "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?, 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`)."
+    "Full report spec per reports.schema.json: { label, 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) {
@@ -37178,11 +37352,16 @@ function reportAdd(args) {
   if (Object.prototype.hasOwnProperty.call(reports, args.code)) {
     throw new Error(`Report '${args.code}' already exists in ui/reports.json.`);
   }
-  reports[args.code] = args.report;
-  return makeResult(`Added report '${args.code}'.`, {
-    [rel(paths.root, paths.reports)]: jsonText(reports),
-    "manifest.json": jsonText(withTodayStamp(manifest))
-  });
+  const { label, ...rest } = args.report;
+  reports[args.code] = label?.trim() ? { label, ...rest } : rest;
+  return makeResult(
+    `Added report '${args.code}'.`,
+    {
+      [rel(paths.root, paths.reports)]: jsonText(reports),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    },
+    label?.trim() ? void 0 : unlabeledReportMessage(args.code, args.report.description)
+  );
 }
 var settingAddSchema = {
   moduleDir: external_exports.string(),
@@ -37368,13 +37547,13 @@ function diagramAdd(args) {
     }
   );
 }
-var SYSTEM_MODULES = /* @__PURE__ */ new Set(["admin", "metadata", "workspace"]);
+var SYSTEM_MODULES = /* @__PURE__ */ new Set(["admin", "metadata", "workspace", "sys-billing"]);
 var dependencyAddSchema = {
   moduleDir: external_exports.string(),
   moduleCode: external_exports.string().regex(/^[a-z][a-z0-9_-]*$/).describe("Module to depend on."),
   version: external_exports.string().default(">=0.1.0").describe("Semver range."),
-  entities: external_exports.array(external_exports.string()).min(1).describe(
-    "The provider entities this module consumes, e.g. ['party']. Required: every dependency needs a deps/<module>.json contract naming at least one entity, and a dependency you cannot name a consumed entity for should not be declared at all. Also narrows the manifest dep to the object form `{ version, entities }`."
+  entities: external_exports.array(external_exports.string()).describe(
+    "The provider entities this module consumes, e.g. ['party']. Every dependency needs a deps/<module>.json contract naming at least one entity, and a dependency you cannot name a consumed entity for should not be declared at all. Narrows the manifest dep to the object form `{ version, entities }`. Exception: against a system module (admin, metadata, workspace, sys-billing) pass [] for a pure platform-version gate, e.g. admin >=1.21.0 for upgrade migrations; the contract then declares \"entities\": {} and the manifest dep stays a plain version string."
   ),
   use: external_exports.array(external_exports.string()).optional().describe(
     "Provenance tokens recorded against each declared entity: '<kind>:<symbol>' where kind is ref|extends|formula|action|view|report|print|role, e.g. 'ref:invoice.customer'. 'extends' must be fully qualified ('extends:parties.party'). Defaults to a placeholder you must refine."
@@ -37394,6 +37573,13 @@ function dependencyAdd(args) {
       `Dependency on '${args.moduleCode}' already exists. Edit manifest.json directly to change the version.`
     );
   }
+  const isSystem = SYSTEM_MODULES.has(args.moduleCode);
+  const gateOnly = args.entities.length === 0;
+  if (gateOnly && !isSystem) {
+    throw new Error(
+      `Name at least one '${args.moduleCode}' entity this module consumes. Only a system module (${[...SYSTEM_MODULES].join(", ")}) may be depended on with no entity, as a platform-version gate.`
+    );
+  }
   const contractPath = path14.join(paths.root, "deps", `${args.moduleCode}.json`);
   if (fs11.existsSync(contractPath)) {
     throw new Error(
@@ -37404,10 +37590,10 @@ function dependencyAdd(args) {
     ...manifest,
     dependencies: {
       ...deps,
-      [args.moduleCode]: { version: args.version, entities: args.entities }
+      [args.moduleCode]: gateOnly ? args.version : { version: args.version, entities: args.entities }
     }
   });
-  const placeholderUse = !args.use || args.use.length === 0;
+  const placeholderUse = !gateOnly && (!args.use || args.use.length === 0);
   const use = placeholderUse ? [`ref:${manifest.code}`] : args.use;
   const contract = {
     module: args.moduleCode,
@@ -37425,26 +37611,28 @@ function dependencyAdd(args) {
       `deps/${args.moduleCode}.json was written with a placeholder provenance token 'ref:${manifest.code}'. Replace it with the real usage (e.g. 'ref:<my_entity>.<my_column>', 'extends:${args.moduleCode}.<entity>', 'role:<role_cd>') \u2014 it is the record of WHY the dependency exists.`
     );
   }
-  if (!args.pks) {
+  if (!gateOnly && !args.pks) {
     warnings.push(
       `PKs were guessed as '<entity>_id'. Check them against ${args.moduleCode}'s entity files \u2014 a wrong pk fails the install-time satisfaction check.`
     );
   }
-  if (SYSTEM_MODULES.has(args.moduleCode)) {
+  if (isSystem && !gateOnly) {
     warnings.push(
       `'${args.moduleCode}' is a system module \u2014 always provisioned, so this dependency is only meaningful as a minimum-platform-version gate. If you are not gating a platform feature, drop it.`
     );
   }
-  warnings.push(
-    `Declare the columns you actually read, write or join on under each entity's 'columns' \u2014 see dforge://schema/deps.`
-  );
+  if (!gateOnly) {
+    warnings.push(
+      `Declare the columns you actually read, write or join on under each entity's 'columns' \u2014 see dforge://schema/deps.`
+    );
+  }
   return makeResult(
-    `Added dependency on '${args.moduleCode}' (${args.version}) for entities [${args.entities.join(", ")}], with the required deps/${args.moduleCode}.json contract.`,
+    gateOnly ? `Added platform-version gate on '${args.moduleCode}' (${args.version}), with a deps/${args.moduleCode}.json contract that declares no entity.` : `Added dependency on '${args.moduleCode}' (${args.version}) for entities [${args.entities.join(", ")}], with the required deps/${args.moduleCode}.json contract.`,
     {
       "manifest.json": jsonText(newManifest),
       [`deps/${args.moduleCode}.json`]: jsonText(contract)
     },
-    warnings.join("\n")
+    warnings.length ? warnings.join("\n") : void 0
   );
 }
 
@@ -38265,124 +38453,6 @@ function checkDiagrams(ctx) {
   }
 }
 
-// src/tools/validate/reports.ts
-function checkReports(ctx) {
-  const { manifest, err, warn, fieldDefsOf, deps, isKnownEntity, reports } = ctx;
-  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.`
-      );
-    }
-  }
-}
-
 // src/tools/module-validate.ts
 var moduleValidateSchema = {
   moduleDir: external_exports.string().describe("Path to the module root. Run this after authoring and before dforge_module_pack.")
@@ -38420,7 +38490,9 @@ function moduleValidate(args, cli) {
       if (res.report.error) err("cli: package", res.report.error);
       for (const c of res.report.checks) if (!c.ok) err(`cli: ${c.name}`, c.message ?? "failed");
       for (const w of res.report.warnings) {
-        const dup = issues.some((i) => i.where === w.where && i.message.includes("toString") && w.message.includes("toString"));
+        const dup = issues.some(
+          (i) => i.where === w.where && i.message.includes("toString") && w.message.includes("toString") || i.level === "warning" && i.message === w.message
+        );
         if (!dup) warn(w.where, w.message);
       }
     }
@@ -38792,7 +38864,7 @@ var resources = [
   schema(
     "reports",
     "Reports JSON schema",
-    "JSON Schema for ui/reports.json \u2014 map of report code \u2192 { description, layout.panels[], datasets, parameters? }. Datasets and panel queries reuse the filter shape from data_views."
+    "JSON Schema for ui/reports.json \u2014 map of report code \u2192 { label, description, layout.panels[], datasets, parameters? }. Datasets and panel queries reuse the filter shape from data_views."
   ),
   schema(
     "stored-procedures",
@@ -38825,7 +38897,7 @@ var resources = [
   reference("action-dsl", "Action DSL grammar + 'Registering the action' (ui/actions.json: entityCode/executionMode/script/isAsync/bi- icon)."),
   reference("filters", "Canonical filter shape for views, folders, and reports."),
   reference("security", "Security roles + rights matrix: 'rights' key, SIUDC for entities, E for actions/reports/folders."),
-  reference("reports", "Reports: layout panels + datasets (Query or Stored Procedure)."),
+  reference("reports", "Reports: label + description, layout panels + datasets (Query or Stored Procedure)."),
   reference("settings", "Module settings shape."),
   reference("jobs", "Scheduled jobs: cron, timeout, jobClass, and the no-record-context constraint."),
   reference("number-sequences", "Number sequences for reference numbers / codes."),
@@ -39188,7 +39260,7 @@ server.registerTool(
   "dforge_report_add",
   {
     title: "Add a report",
-    description: "PHASE 3: Add a report to ui/reports.json. Read dforge://schema/reports for the layout/datasets/parameters shape.",
+    description: "PHASE 3: Add a report to ui/reports.json. Give it a short `label` (its name: page title, breadcrumb, parameter dialog) and a `description` of what it shows, which appears under the label; without a label the description becomes the title and pack/validate/install warn. Read dforge://schema/reports for the layout/datasets/parameters shape.",
     inputSchema: { ...reportAddSchema, ...applyInput }
   },
   envelope(reportAdd)
@@ -39251,7 +39323,7 @@ server.registerTool(
   "dforge_dependency_add",
   {
     title: "Add a module dependency",
-    description: "Add a dependency on another dForge module. Writes BOTH halves the platform requires: the manifest.json entry and the deps/<module>.json contract declaring what this module consumes \u2014 a manifest dependency without a contract fails validate, pack and install. Name the consumed entities in `entities`; do not declare a dependency you cannot name one for, and do not depend on the system modules (admin, metadata, workspace) except to gate a minimum platform version.",
+    description: "Add a dependency on another dForge module. Writes BOTH halves the platform requires: the manifest.json entry and the deps/<module>.json contract declaring what this module consumes \u2014 a manifest dependency without a contract fails validate, pack and install. Name the consumed entities in `entities`; do not declare a dependency you cannot name one for, and do not depend on the system modules (admin, metadata, workspace, sys-billing) except to gate a minimum platform version \u2014 a gate for a feature that introduced no entity passes `entities: []`.",
     inputSchema: { ...dependencyAddSchema, ...applyInput }
   },
   envelope(dependencyAdd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.33",
+  "version": "0.2.34",
   "description": "MCP server for dForge module authoring. Exposes 35 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",
@@ -26,8 +26,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@dforge-core/dforge-cli": "^0.2.26",
-    "@dforge-core/metadata": "^0.0.33",
+    "@dforge-core/dforge-cli": "^0.2.27",
+    "@dforge-core/metadata": "^0.0.34",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },

package/resources/docs/conventions.md

@@ -71,6 +71,8 @@ Use the CRM sample module (`modules/crm/`) as a reference implementation.
 ├── /print_templates/          # HTML/CSS print templates (optional)
 │   ├── invoice.html
 │   └── invoice.css
+├── /migrations/               # Upgrade data scripts, {version}.sql (optional)
+│   └── 0.2.0.sql
 └── /files/                    # Module static files (optional) — README, docs
     └── README.md
 ```
@@ -964,6 +966,24 @@ Use semantic versioning: `MAJOR.MINOR.PATCH`
 1. **`version`**: Overall module version (includes all changes)
 2. **`dbSchemaVersion`**: Database schema version (only bumped for schema changes)
 
+### Upgrade Migrations (`migrations/`)
+
+A table or column change needs no script: the installer generates the DDL. A script is for the DATA a new version reshapes — filling a new column from an old one, moving rows to a new table, dropping a table the new version no longer declares (the platform never drops one on its own).
+
+```
+migrations/
+└── 0.11.0.sql      # runs on an upgrade from below 0.11.0 to 0.11.0 or later
+```
+
+- **Name** — the module `version` the file upgrades to, `MAJOR.MINOR.PATCH.sql`. Keyed by `version`, not `dbSchemaVersion`. A misnamed file, or one newer than the manifest `version`, fails the package at load.
+- **When** — on an upgrade only: every file above the installed version and no higher than the package's, in ascending order. A fresh install or a same-version reinstall runs none.
+- **Where** — inside the install transaction, after the new tables and columns exist and before `NOT NULL` is applied or a register's `totals` cache is rebuilt. A table the new version removed is still there to read. A failing script rolls the upgrade back and the module stays on the old version; refuse unconvertible data with `RAISE EXCEPTION '…'`, which the operator sees.
+- **Ids** — `"dForge".next_id()` mints a row id in SQL. Declare `"admin": ">=1.21.0"` in `dependencies`; that is also what guarantees a platform that runs migrations.
+- **Locks** — a script writing a posted document or its register journal wraps the writes in `SELECT set_config('registry.posting', 'true', true);` … `'false'`, so the post locks stand aside. Period locks do not; reopen a closed period and close it again.
+- A `kind: "pack"` module cannot carry migrations.
+
+Reference: `modules/gl/migrations/0.11.0.sql` in dForge-core.
+
 ---
 
 ## Installation & Reinstallation

package/resources/schemas/deps.schema.json

@@ -18,11 +18,16 @@
 		},
 		"entities": {
 			"type": "object",
-			"description": "Consumed provider entities, keyed by entity code (e.g. 'party').",
-			"minProperties": 1,
+			"description": "Consumed provider entities, keyed by entity code (e.g. 'party'). At least one, except against a system module (admin, metadata, workspace, sys-billing), where {} declares a pure platform-version gate for a feature that introduced no entity.",
 			"additionalProperties": { "$ref": "#/definitions/entityContract" }
 		}
 	},
+	"if": {
+		"not": { "properties": { "module": { "enum": ["admin", "metadata", "workspace", "sys-billing"] } }, "required": ["module"] }
+	},
+	"then": {
+		"properties": { "entities": { "minProperties": 1 } }
+	},
 	"definitions": {
 		"entityContract": {
 			"type": "object",

package/resources/schemas/domains.schema.json

@@ -2,7 +2,7 @@
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "https://dforge.dev/schemas/domains.schema.json",
 	"title": "dForge Column Domains",
-	"description": "domains.json — reusable, named semantic types. A domain bundles a base datatype, a control, sizing and a shared option list under one code; columns reference it via \"domain\": \"module_cd.domain_cd\" instead of restating the definition. Structural fields are materialized onto each column at install; options stay on the domain and resolve at metadata-load time, so a shared list is authored and translated exactly once.",
+	"description": "domains.json — reusable, named semantic types. A domain bundles a base datatype, a control, sizing and a shared option list under one code; columns reference it via \"domain\": \"domain_cd\" (this module's own) or \"module_cd.domain_cd\" (another module's) instead of restating the definition. Structural fields are materialized onto each column at install; options stay on the domain and resolve at metadata-load time, so a shared list is authored and translated exactly once.",
 	"type": "object",
 	"additionalProperties": {
 		"$ref": "#/$defs/domain"