@dforge-core/dforge-mcp 0.2.44 → 0.2.45

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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.45 — 2026-10-25
+
+**English is the base locale, and it lives in the definitions.** Install never reads
+`translations/en.json` / `en-*.json`, so the English file the tools wrote was dead weight: its labels
+were never applied, and the English UI kept showing whatever the definitions said. `dforge_module_create`
+(preset `full`) no longer writes `translations/en-US.json`; `dforge_translation_sync` defaults to the
+`supportedLocales` entries only, refuses an English locale, and warns about a leftover English file;
+`dforge_module_validate` warns about one instead of requiring role labels in it; `dforge_module_plan`
+defaults to no extra locales. The sync seeds a setting from its `description` and a view, menu, folder or
+action from `label`, else `description` — what install shows. `references/translations.md` gains the
+table of where each object's English text lives, and the column-security example drops its
+`en-US.json` for short labels in the definitions.
+
+**File map keys use `/` on Windows too.** Every tool that builds a `files` key from a path (field,
+entity, view, menu, action, role-right, seed, diagram and translation tools, the refactors) returned
+`translations\de-DE.json`-style keys on Windows; they now return `translations/de-DE.json` on every OS.
+
+**DSL builtins.** `attachText(content, fileName, encoding?, mimeType?)` / `attachBase64(base64, fileName, mimeType?)` build a file for `sendEmail()`'s fourth argument, keeping its own type (an `.ics` as `text/calendar`); a scheduled job can attach them, unlike a `printPdf()` file. Follows metadata 0.0.45; `dforge_action_check` knows both. **Needs `@dforge-core/dforge-cli` with them** (0.2.36).
+
+**Schemas follow metadata 0.0.46.** `dforge://schema/registers` accepts `importedKeyField` on an accounting register; `dforge://schema/entity` accepts the `filesize` field type.
+
+**Registers and actions docs.** `getAccountBalance` / `getAccountTurnover` take `exclude` as one document or an array, and an accounting register's `importedKeyField` leaves out postings loaded beside a document. An action in `ui/actions.json` can ship `paramSets` (saved parameter values; a `=` formula or a template reads the record) and a `previewTemplate` (a PDF beside the run dialog's params). **Needs `@dforge-core/dforge-cli` 0.2.36.**
+
+**DSL docs.** `[owner_id].[email]` / `[owner_id].[full_name]` read the user behind a `user` column (platform #1499); `dforge://reference/dsl` says so.
+
+**Registers reference.** Which kind folds rows per dimension tuple (only `balance`); the account-read
+`options` in the reads table; the balance at a document's moment within one second (`before` plus
+`exclude`, the caller ordering what the platform does not); `importedKeyField` marked as being for a
+history loaded from another system; how long a cache rebuild at install can take. Common mistakes gain an
+empty dimension (no `allowEmpty` on any kind; `=COALESCE(...)` or `skipPostingWhenEmpty`), `headerMap`
+taking columns only and why each must be locked, one constant for two resources, a month missing from the
+period calendar counting as closed (`DF003`), and the `registers/column-not-numeric` warning. The engine
+writes an analytic slot's `entity` as `module.entity` (platform #1544), and a loader writes the same; a
+filter matches either spelling, `groupBy` splits old bare slots from new ones until a migration and
+`rebuild-totals`.
+
+**DSL entity codes.** A data built-in's `module.entity` is looked up by module code, hyphen included, and
+otherwise as a schema (platform #1543), so `insert('cdy-tax.x', …)` and `insert('cdy_tax.x', …)` both
+work. The conventions doc notes that install refuses a schema or code another module already holds.
+Roles and settings are translated (the conventions doc called roles ignored); a print template's name is
+its `description`.
+
+**DSL, formulas, fields.** An inline action stops after 10 seconds; an assignment inside a one-line block
+fails; indexing after a call or an index compiles since platform #1537. `TODAY()` / `NOW()` follow the
+request's time zone, a `datetime` column may pin `params.timeZone`, a number-literal formula becomes a
+column `DEFAULT`, and a bare `$[setting]` formula fills a column an insert leaves out. A zero divisor
+fails wherever a formula runs in SQL.
+
+**Reports and print.** A stored procedure's result-column `baseDatatypeCd` codes (`timestamp`, not
+`datetime`); `ROWS 1` on a one-row table function, since install's `SET search_path` stops inlining; every
+`logic/reports/*.sql` runs at every install (and "must be owner of function"); casting columns for
+`RETURN QUERY`. Print: `%B` prints English names, `format_date` returns a string, timestamps follow the
+column's or the request's zone, Scriban's `blank` on a date, stray spaces from an empty reference hop.
+
+**Seed, demo and ship.** Seed rows are re-applied on every install and ship in the package (fictional
+data only); `demo-data/` inserts but does not post, so an accounting demo runs the module's actions; a
+same-version install is skipped yet reports success. `dforge-module-ship` covers an install blocked by an
+open transaction (`pg_stat_activity`), a client timeout during a cache rebuild, and the local dev stack
+(restart `dforge-api`, the `<tenant>._.localhost` URL, an expired CLI token, a platform binary behind the
+tenant). Option labels: plain English in the definition, translated as strings.
+
 ## 0.2.44 — 2026-10-21
 
 **Schemas follow metadata 0.0.44.** `dforge://schema/translations` describes `storedProcedures`

package/README.md

@@ -143,7 +143,7 @@ The field/entity tools validate against the `@dforge-core/metadata` registry: an
 | Tool | Behavior |
 |---|---|
 | `dforge_setting_add` | Configurable module-level setting |
-| `dforge_translation_sync` | Generate/refresh `translations/<locale>.json` from the module's own contents. Never overwrites existing translated text; fills the role labels that are **completeness-enforced at install**. Defaults to en-US + every `supportedLocales` entry |
+| `dforge_translation_sync` | Generate/refresh `translations/<locale>.json` from the module's own contents. Never overwrites existing translated text; fills the role labels that are **completeness-enforced at install**. Defaults to every `supportedLocales` entry; writes no English file (install skips `en*.json` — English lives in the definitions) |
 | `dforge_seed_add` | Write a seed file for one entity. Enforces numeric `{entity}_id` PKs, parent-before-child load order, `audit-full` System-user columns, and FKs that point at seeded parents |
 
 **Security (Phase 5)**

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.35/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.36/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31132,53 +31132,6 @@ function buildActions() {
 function buildSettings() {
   return {};
 }
-function buildTranslations(opts) {
-  const entities = {};
-  for (const e of opts.entities) {
-    const fields = {
-      // identity trait → primary key column
-      [`${e.name}_id`]: { label: `${e.label} ID` },
-      [NAME_FIELD]: { label: "Name" }
-    };
-    if (e.traits === "identity+audit") {
-      fields.created_date = { label: "Created Date" };
-      fields.last_updated = { label: "Last Updated" };
-    }
-    const entityEntry = { label: e.label };
-    if (opts.description && opts.entities.length === 1) {
-      entityEntry.desc = opts.description;
-    }
-    entityEntry.fields = fields;
-    if (e.constraints?.length) {
-      entityEntry.constraints = Object.fromEntries(
-        e.constraints.map((c) => [c.name, { message: c.message }])
-      );
-    }
-    entities[e.name] = entityEntry;
-  }
-  return {
-    entities,
-    folders: {
-      // folders.json root folder key is the module code (see buildFolders).
-      [opts.code]: { label: opts.displayName }
-    },
-    roles: {
-      // Role labels are completeness-enforced in every locale incl. en-US.
-      [`${opts.code}.admin`]: { label: `${opts.displayName} Administrator` }
-    },
-    views: Object.fromEntries(
-      opts.entities.map((e) => [e.name, { label: e.label }])
-    ),
-    menus: {
-      [`${opts.code}_menu`]: {
-        label: opts.displayName,
-        items: Object.fromEntries(
-          opts.entities.map((e) => [e.name, { label: e.label }])
-        )
-      }
-    }
-  };
-}
 function buildSeedData(entity) {
   const entityCode = typeof entity === "string" ? entity : entity?.name ?? "";
   return { entityCode, records: [] };
@@ -31290,7 +31243,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.44/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.46/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -31310,6 +31263,7 @@ var fieldTypes = [
   { cd: "number", name: "Number", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: null, useStringInFilter: false },
   { cd: "currency", name: "Currency", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: 2, useStringInFilter: false },
   { cd: "percent", name: "Percent", columnType: "D", baseDatatypeCd: "number", supportedAgg: "CAM", maxLen: null, precision: 2, useStringInFilter: false },
+  { cd: "filesize", name: "File Size", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: null, useStringInFilter: false },
   { cd: "checkbox", name: "Checkbox", columnType: "D", baseDatatypeCd: "bool", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
   { cd: "date", name: "Date", columnType: "D", baseDatatypeCd: "date", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },
   { cd: "datetime", name: "Date & Time", columnType: "D", baseDatatypeCd: "timestamp", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },
@@ -31509,7 +31463,8 @@ var NUMERIC_TOTAL = 18;
 var TEXT_BACKED = /* @__PURE__ */ new Set(["textarea", "markdown", "richtext", "code"]);
 var DB_DATATYPE_OVERRIDE = {
   file: "jsonb",
-  image: "jsonb"
+  image: "jsonb",
+  filesize: "int8"
 };
 function deriveDbDatatype(fieldTypeCd, options = {}) {
   const ft = getFieldType(fieldTypeCd);
@@ -31541,7 +31496,8 @@ var ACCOUNTING_PROPERTIES = [
   "creditAccount",
   "debitAnalyticFields",
   "creditAnalyticFields",
-  "sideDimensions"
+  "sideDimensions",
+  "importedKeyField"
 ];
 var BALANCE_PROPERTIES = ["allowNegative", "autoCreate"];
 var REFUSED = {
@@ -31550,6 +31506,40 @@ var REFUSED = {
   info: ["journal", "journalDirection", "journalDate", ...ACCOUNTING_PROPERTIES, "totals", ...BALANCE_PROPERTIES],
   accounting: ["entity", ...INFO_PROPERTIES, "journalDirection", ...BALANCE_PROPERTIES]
 };
+var SUMMED = ["balance", "turnover", "accounting"];
+var slot = (path21, on, what, summed = false) => ({
+  path: path21.split("."),
+  on,
+  what,
+  ...summed ? { numericFor: SUMMED } : {}
+});
+var REGISTER_COLUMN_SLOTS = [
+  slot("journalDirection", "journal", "Journal direction column"),
+  slot("journalDate", "journal", "Journal date column"),
+  slot("period", "entity", "Period column"),
+  slot("recorder", "entity", "Recorder column"),
+  slot("dimensions.*", "carrier", "Dimension"),
+  slot("resources.*.field", "carrier", "Resource '{0}' column", true),
+  slot("resources.*.debitField", "carrier", "Resource '{0}' column", true),
+  slot("resources.*.creditField", "carrier", "Resource '{0}' column", true),
+  slot("account", "journal", "Account column"),
+  slot("debitAccount", "journal", "Debit account column"),
+  slot("creditAccount", "journal", "Credit account column"),
+  slot("analyticFields.*", "journal", "Analytic slot column"),
+  slot("debitAnalyticFields.*", "journal", "Analytic slot column"),
+  slot("creditAnalyticFields.*", "journal", "Analytic slot column"),
+  slot("sideDimensions.*.debitField", "journal", "Dimension '{0}' debit column"),
+  slot("sideDimensions.*.creditField", "journal", "Dimension '{0}' credit column"),
+  slot("composition.account", "composition", "Composition 'account' column"),
+  slot("composition.slot", "composition", "Composition 'slot' column"),
+  slot("composition.analytic", "composition", "Composition 'analytic' column"),
+  slot("totals.periodField", "totals", "Totals period column"),
+  slot("totals.accountField", "totals", "Totals account column"),
+  slot("totals.resources.*.inField", "totals", "Totals '{0}' inField", true),
+  slot("totals.resources.*.outField", "totals", "Totals '{0}' outField", true),
+  slot("totals.resources.*.debitField", "totals", "Totals '{0}' debitField", true),
+  slot("totals.resources.*.creditField", "totals", "Totals '{0}' creditField", true)
+];
 
 // src/tools/_helpers.ts
 function modulePaths(moduleDir) {
@@ -31648,7 +31638,7 @@ function jsonText(obj) {
   return JSON.stringify(obj, null, "	") + "\n";
 }
 function rel(root, abs) {
-  return path.relative(root, abs);
+  return path.relative(root, abs).split(path.sep).join("/");
 }
 function loadManifest(moduleDir) {
   const paths = modulePaths(moduleDir);
@@ -31955,7 +31945,7 @@ var createModuleSchema = {
   version: external_exports.string().regex(/^\d+\.\d+\.\d+(-[\w.]+)?$/).default("0.1.0"),
   dbSchemaVersion: external_exports.string().regex(/^\d+\.\d+\.\d+(-[\w.]+)?$/).default("0.0.1"),
   dependencies: external_exports.array(external_exports.string()).default([]).describe("Other modules this one requires, by code (e.g. ['parties']). Leave empty unless it genuinely depends on another module. Do NOT list 'admin' or 'metadata' \u2014 they're system modules present in every tenant, so depending on them is redundant (the check always passes and never affects install order)."),
-  preset: external_exports.enum(["minimal", "minimal-plus", "full"]).default("minimal").describe("'minimal' = manifest+entity+UI+role only. 'full' = also settings/translations/seed-data/logic stubs. 'minimal-plus' behaves like 'minimal' here since MCP can't loop; pass all entities up-front."),
+  preset: external_exports.enum(["minimal", "minimal-plus", "full"]).default("minimal").describe("'minimal' = manifest+entity+UI+role only. 'full' = also settings/seed-data/logic stubs. No translation file: English lives in the definitions, other locales come from dforge_translation_sync. 'minimal-plus' behaves like 'minimal' here since MCP can't loop; pass all entities up-front."),
   entities: external_exports.array(
     external_exports.object({
       name: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Entity code, e.g. 'customer'. Lowercase, digits, underscore; first char a letter."),
@@ -32039,7 +32029,6 @@ function createModuleFiles(args) {
   if (buildZedTasks2) write(".zed/tasks.json", buildZedTasks2());
   if (opts.preset === "full") {
     write("settings.json", buildSettings());
-    write("translations/en-US.json", buildTranslations(opts));
     for (const e of opts.entities) {
       write(`seed-data/01-${e.name}.json`, buildSeedData());
     }
@@ -32132,9 +32121,9 @@ var planModuleSchema = {
   dependencies: external_exports.array(external_exports.string()).optional().describe(
     "[write_identity] Other dForge module codes this module depends on. admin + metadata are always implicit."
   ),
-  locales: external_exports.array(external_exports.string()).optional().describe("[write_identity] Locale codes, e.g. ['en-US', 'de-DE']. Default: ['en-US']."),
+  locales: external_exports.array(external_exports.string()).optional().describe("[write_identity] Locales besides English, e.g. ['uk-UA', 'de-DE'] \u2014 recorded in CLAUDE.md only; declare them in manifest.supportedLocales and run dforge_translation_sync to create the files. English is the base: its text lives in the definitions and needs no file. Default: [] (English only)."),
   preset: external_exports.enum(["minimal", "minimal-plus", "full"]).optional().describe(
-    "[write_identity] Scaffold depth: minimal = entities + views + role; full = + settings + translations + seed-data stubs."
+    "[write_identity] Scaffold depth: minimal = entities + views + role; full = + settings + seed-data stubs."
   ),
   // ── write_requirements / write_design fields (Phase 0b / 0c) ────────
   userConfirmed: external_exports.boolean().optional().describe(
@@ -32364,8 +32353,8 @@ function handleCheck(root) {
         `What's the module's display name? (e.g. "Purchase Orders", "HR Leave Requests")`,
         "What code should it use? (snake_case, letters + digits + underscores \u2014 becomes the DB schema name; suggest a default derived from the display name)",
         "Does this module depend on any other dForge modules \u2014 e.g. needing entities from 'crm' or 'parties'? (admin and metadata are platform-implicit; list any others, or say None)",
-        "English only, or any other locales the module needs to ship with translations for?",
-        "How complete should the initial scaffold be? (minimal = entities + default views + single admin role; minimal-plus = + settings/translation stubs; full = + logic stubs + seed data structure)"
+        "English only, or which other locales should the module ship translations for (e.g. uk-UA)? English is the base and needs no translation file.",
+        "How complete should the initial scaffold be? (minimal = entities + default views + single admin role; minimal-plus = + settings stubs; full = + logic stubs + seed data structure)"
       ],
       writeAction: "Once all answers are collected and reflected back, call dforge_module_plan({ action: 'write_identity', moduleDir, displayName, code, dependencies, locales, preset })."
     };
@@ -32439,11 +32428,12 @@ function handleCheck(root) {
   };
 }
 function handleWriteIdentity(root, args) {
-  const { displayName, code: code2, dependencies = [], locales = ["en-US"], preset = "minimal" } = args;
+  const { displayName, code: code2, dependencies = [], preset = "minimal" } = args;
+  const locales = (args.locales ?? []).filter((l) => !/^en(-|$)/i.test(l.trim()));
   if (!displayName) throw new Error("displayName is required for write_identity.");
   if (!code2) throw new Error("code is required for write_identity.");
   const depsText = dependencies.length > 0 ? dependencies.join(", ") : "None";
-  const localesText = locales.join(", ");
+  const localesText = ["English (base, in the definitions)", ...locales].join(", ");
   const claudeMd = buildClaudeMd({ root, displayName, code: code2, depsText, localesText, preset });
   return {
     summary: `Phase 0a complete \u2014 CLAUDE.md prepared for module '${code2}'.`,
@@ -34622,7 +34612,7 @@ var path10 = __toESM(require("path"));
 var fs7 = __toESM(require("fs"));
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.44/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.46/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -35476,7 +35466,7 @@ var BUILTINS = [
     name: "sendEmail",
     signature: "sendEmail(to, subjectOrTemplate, dataOrBody?, attachments?)",
     returns: "void",
-    doc: "Queue an outbound email. Three arguments, and the **second** picks the mode: `sendEmail(to, 'order.shipped', { ref: [code] })` sends a template, `sendEmail(to, 'Your order shipped', '<p>\u2026</p>')` sends raw HTML. A second argument with no spaces that contains `.` or `_` is read as a template code \u2014 so a raw subject like `'Shipped.'` silently becomes one; give a raw subject spaces. The optional **fourth** argument attaches files: a `printPdf()` result, or an array of them (`[a, b]`; pass a single file as itself, because a one-name `[a]` reads as a field reference in the DSL). Only a `printPdf()` result can be attached, and only by the user who generated it (or a workspace admin); at most 5 files and 10 MB in all per email (`Email:MaxAttachments`, `Email:MaxAttachmentBytes`). A file the sender may not attach fails the action. Not available in a scheduled job, whose emails with attachments are not queued."
+    doc: "Queue an outbound email. Three arguments, and the **second** picks the mode: `sendEmail(to, 'order.shipped', { ref: [code] })` sends a template, `sendEmail(to, 'Your order shipped', '<p>\u2026</p>')` sends raw HTML. A second argument with no spaces that contains `.` or `_` is read as a template code \u2014 so a raw subject like `'Shipped.'` silently becomes one; give a raw subject spaces. The optional **fourth** argument attaches files: a `printPdf()`, `attachText()` or `attachBase64()` result, or an array of them (`[a, b]`; pass a single file as itself, because a one-name `[a]` reads as a field reference in the DSL). A `printPdf()` file can be attached only by the user who generated it (or a workspace admin) and not in a scheduled job; a file built with `attachText()` / `attachBase64()` has no owner and works everywhere, a scheduled job included. At most 5 files and 10 MB in all per email (`Email:MaxAttachments`, `Email:MaxAttachmentBytes`). A file the sender may not attach fails the action."
   },
   // External calls
   {
@@ -35529,6 +35519,18 @@ var BUILTINS = [
     returns: "string",
     doc: "`downloadText()` for bytes: decodes `base64` and hands it to the user as `fileName` (`application/octet-stream` unless `mimeType` says otherwise). Returns the signed download URL."
   },
+  {
+    name: "attachText",
+    signature: "attachText(content, fileName, encoding?, mimeType?)",
+    returns: "object",
+    doc: "Build a text file to attach to an email: encodes `content` in `encoding` (`utf-8` by default) and returns a descriptor for `sendEmail()`'s fourth argument, e.g. `sendEmail(to, 'Interview', body, attachText(ics, 'invite.ics', 'utf-8', 'text/calendar'))`. The file keeps `mimeType` (`text/plain` by default). It is the script's own output, so no user's rights are involved and it works in a scheduled job. Only the emails of this run can name it. Max 10 MB per file and 10 files per run, shared with `downloadText()` / `downloadBase64()`."
+  },
+  {
+    name: "attachBase64",
+    signature: "attachBase64(base64, fileName, mimeType?)",
+    returns: "object",
+    doc: "`attachText()` for bytes given as base64 (`application/octet-stream` unless `mimeType` says otherwise)."
+  },
   {
     name: "getSetting",
     signature: "getSetting(settingCd)",
@@ -36389,10 +36391,17 @@ function checkConstraintTranslations(ctx) {
 function checkTranslationCompleteness(ctx) {
   const { paths, err, warn, roles, supportedLocales } = ctx;
   const roleCodes = Object.keys(roles);
-  const localeFiles = fs7.existsSync(paths.translationsDir) ? fs7.readdirSync(paths.translationsDir).filter((f) => f.toLowerCase().endsWith(".json")).sort() : [];
+  const allFiles = fs7.existsSync(paths.translationsDir) ? fs7.readdirSync(paths.translationsDir).filter((f) => f.toLowerCase().endsWith(".json")).sort() : [];
+  const localeFiles = allFiles.filter((f) => !isEnglishLocale(f.slice(0, -5)));
+  for (const file2 of allFiles.filter((f) => isEnglishLocale(f.slice(0, -5)))) {
+    warn(
+      `translations/${file2}`,
+      "install never reads an English translation file \u2014 the English UI shows the definitions' own text (an entity's or field's `description`, a menu's, action's or report's `label`, a role's or setting's `description`). Move any wording you want from this file into the definitions, then delete it."
+    );
+  }
   for (const raw of supportedLocales) {
     const locale = raw.trim();
-    if (!locale) continue;
+    if (!locale || isEnglishLocale(locale)) continue;
     if (!resolveTranslationFile(paths.translationsDir, locale)) {
       err(
         "translations",
@@ -36400,12 +36409,6 @@ function checkTranslationCompleteness(ctx) {
       );
     }
   }
-  if (roleCodes.length > 0 && localeFiles.length === 0) {
-    warn(
-      "translations",
-      `no translations/ files \u2014 ship at least translations/en-US.json with a roles block (a 'label' for each of: ${roleCodes.join(", ")}); role labels are completeness-enforced at install.`
-    );
-  }
   for (const file2 of localeFiles) {
     let tx;
     try {
@@ -36422,7 +36425,7 @@ function checkTranslationCompleteness(ctx) {
     if (missing.length > 0) {
       err(
         `translations/${file2}`,
-        `missing roles.<code>.label for: ${missing.join(", ")} \u2014 completeness is enforced in every locale (including en-US); install fails with "Label for role '<code>'."`
+        `missing roles.<code>.label for: ${missing.join(", ")} \u2014 completeness is enforced in every non-English locale file; install fails with "Label for role '<code>'."`
       );
     }
   }
@@ -36891,7 +36894,7 @@ function str(obj, key) {
 var translationSyncSchema = {
   moduleDir: external_exports.string().describe("Path to the module root."),
   locales: external_exports.array(external_exports.string().regex(/^[a-z]{2}(-[A-Z]{2})?$/)).optional().describe(
-    "Locales to sync. Default: 'en-US' plus every entry in manifest.supportedLocales \u2014 i.e. exactly the set install requires."
+    "Non-English locales to sync. Default: every entry in manifest.supportedLocales \u2014 exactly the set install requires. An English locale is refused: install never reads translations/en*.json, English text belongs in the definitions."
   ),
   prune: external_exports.boolean().default(false).describe(
     "Remove keys that no longer correspond to anything in the module (e.g. after an entity delete). Off by default \u2014 pruning discards translated text."
@@ -36907,8 +36910,8 @@ function buildSkeleton(moduleDir) {
       `traits.json \u2014 ${traitsError} Its traits can't be overlaid, so the entities that use one would be skipped as declaring an unknown trait and their columns would go unlabelled \u2014 which fails the install. Fix the file and sync again.`
     );
   }
-  const push = (section, pathParts, english, required2 = false, legacyParts, nonEnglishOnly = false) => {
-    entries.push({ pathParts, english, required: required2, legacyParts, nonEnglishOnly });
+  const push = (section, pathParts, english, required2 = false, legacyParts) => {
+    entries.push({ pathParts, english, required: required2, legacyParts });
     counts[section] = (counts[section] ?? 0) + 1;
   };
   for (const [name, relPath] of Object.entries(manifest.entities ?? {})) {
@@ -36990,10 +36993,10 @@ function buildSkeleton(moduleDir) {
   }
   const settings = readJsonOrDefault(paths.settings, {});
   for (const [code2, s] of Object.entries(settings)) {
-    push("settings", ["settings", code2, "label"], str(s, "label") ?? str(s, "description") ?? str(s, "desc") ?? titleize(code2));
+    push("settings", ["settings", code2, "label"], str(s, "description") ?? str(s, "label") ?? str(s, "desc") ?? titleize(code2));
   }
   for (const text of actionMessageTexts(paths.logicDir, actions).keys()) {
-    push("messages", ["messages", text], text, false, void 0, true);
+    push("messages", ["messages", text], text);
   }
   return { entries, counts };
 }
@@ -37022,9 +37025,20 @@ function pruneTo(existing, keep, trail = []) {
 function translationSync(args) {
   const { paths, manifest } = loadManifest(args.moduleDir);
   const declared = Array.isArray(manifest.supportedLocales) ? manifest.supportedLocales.filter((l) => typeof l === "string") : [];
-  const locales = args.locales ?? ["en-US", ...declared];
+  const isEnglish = (l) => l.toLowerCase() === "en" || l.toLowerCase().startsWith("en-");
+  const english = (args.locales ?? []).filter(isEnglish);
+  if (english.length > 0) {
+    throw new Error(
+      `Refusing to sync ${english.join(", ")}: install never reads translations/en*.json. English is the base locale and lives in the definitions \u2014 an entity's or field's \`description\`, a menu's, action's or report's \`label\`, a role's or setting's \`description\`. Edit the text there.`
+    );
+  }
+  const ignored = fs9.existsSync(paths.translationsDir) ? fs9.readdirSync(paths.translationsDir).filter((f) => f.toLowerCase().endsWith(".json") && isEnglish(f.slice(0, -5))) : [];
+  const staleEnglish = ignored.length > 0 ? ` Leftover ${ignored.map((f) => `translations/${f}`).join(", ")} is never read by install \u2014 move any wording you want from it into the definitions, then delete it.` : "";
+  const locales = args.locales ?? declared.filter((l) => !isEnglish(l));
   if (locales.length === 0) {
-    throw new Error("No locales to sync. Pass `locales`, or declare them in manifest.supportedLocales.");
+    throw new Error(
+      'No locales to sync. An English-only module needs no translation files: its English text lives in the definitions. To translate, declare the other locales in manifest.supportedLocales (e.g. ["uk-UA"]).' + staleEnglish
+    );
   }
   const { entries, counts } = buildSkeleton(args.moduleDir);
   if (entries.length === 0) {
@@ -37033,11 +37047,11 @@ function translationSync(args) {
     );
   }
   const keep = new Set(entries.map((e) => compositeKey(...e.pathParts)));
-  const isEnglish = (l) => l.toLowerCase() === "en" || l.toLowerCase().startsWith("en-");
   const files = {};
   const report = [];
   let totalAdded = 0;
   let missingRequired = 0;
+  const seeded = [];
   for (const locale of locales) {
     const abs = path12.join(paths.translationsDir, `${locale}.json`);
     let existing = {};
@@ -37051,7 +37065,6 @@ function translationSync(args) {
     const next = args.prune ? pruneTo(existing, keep) : JSON.parse(JSON.stringify(existing));
     let added = 0;
     for (const entry of entries) {
-      if (entry.nonEnglishOnly && isEnglish(locale)) continue;
       const current = getIn(next, entry.pathParts);
       if (typeof current === "string" && current.trim() !== "") continue;
       const legacy = entry.legacyParts && getIn(existing, entry.legacyParts);
@@ -37061,10 +37074,21 @@ function translationSync(args) {
     }
     files[rel(paths.root, abs)] = jsonText(next);
     totalAdded += added;
+    if (added > 0) seeded.push(locale);
     report.push(`${locale}: +${added} key(s)${added === 0 ? " (already complete)" : ""}`);
   }
-  const nonEnglish = locales.filter((l) => !isEnglish(l));
-  const warning = nonEnglish.length > 0 && totalAdded > 0 ? `Newly-added keys in ${nonEnglish.join(", ")} are seeded with the ENGLISH source text so the file is installable immediately \u2014 they still need real translation. (Untranslated values fall back to en-US at runtime, so this never breaks; it just shows English.)` : void 0;
+  const warnings = [];
+  if (totalAdded > 0) {
+    warnings.push(
+      `Newly-added keys in ${seeded.join(", ")} are seeded with the ENGLISH source text so the file is installable immediately \u2014 they still need real translation.`
+    );
+  }
+  if (ignored.length > 0) {
+    warnings.push(
+      `${ignored.map((f) => `translations/${f}`).join(", ")} is never read by install \u2014 the English UI shows the definitions' own \`description\` / \`label\`. Move any wording you want from it into the definitions, then delete it.`
+    );
+  }
+  const warning = warnings.length > 0 ? warnings.join(" ") : void 0;
   const sections = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(", ");
   return makeResult(
     `Synced ${locales.length} locale file(s) from ${entries.length} translatable keys (${sections}). ${report.join("; ")}.${missingRequired > 0 ? ` Filled ${missingRequired} install-blocking role label(s).` : ""}`,
@@ -38971,7 +38995,8 @@ var resources = [
   reference("registers", "Registers: accumulation (balance / turnover / info) and accounting (classic / compound) registers, registers.json, binding a document from its A / L columns (map, per-side debit/credit objects), and the reads. Load before authoring registers.json or an A / L column."),
   reference("reactions", "Field-change reactions: `reactions` on an entity (formula rules and server `call` rules) that suggest a stored, editable value when the user edits another field; a bridge module's reactions on its host's entity (`reaction:<code>` in deps); dependent references. Load before authoring any reaction."),
   reference("data-migration", "Migrating data from a legacy database."),
-  reference("manifest", "manifest.json shape: moduleId UUID, semver, entities map, locale-keyed translations, security block."),
+  reference("manifest", "manifest.json shape: moduleId UUID, semver, entities map, supportedLocales (non-English only), security block."),
+  reference("conventions", "Cross-cutting module rules: naming, structure, translations, upgrade migrations."),
   reference("validation-checklist", "Final pre-pack self-review checklist covering every file type."),
   // ── Canonical example module (skills/.../examples/simple-todo) ────────
   example("manifest.json", "Canonical manifest.json."),
@@ -39334,7 +39359,7 @@ server.registerTool(
   "dforge_translation_sync",
   {
     title: "Sync translation files",
-    description: "PHASE 4: Generate or refresh translations/<locale>.json from what the module actually contains \u2014 entity + field labels (including trait-provided columns), views, menus, roles, actions, folders, settings. Existing translated text is NEVER overwritten; missing keys are seeded with the English source so the file is immediately installable. Defaults to en-US plus every manifest.supportedLocales entry \u2014 exactly the set install requires. Run it after any entity/view/role change: role labels are completeness-enforced and a missing one FAILS install.",
+    description: "PHASE 4: Generate or refresh translations/<locale>.json from what the module actually contains \u2014 entity + field labels (including trait-provided columns), views, menus, roles, actions, folders, settings. Existing translated text is NEVER overwritten; missing keys are seeded with the English source so the file is immediately installable. Defaults to every manifest.supportedLocales entry \u2014 exactly the set install requires. Writes no English file: install never reads translations/en*.json, English text lives in the definitions (entity/field/role/setting `description`, menu/action/report `label`). Run it after any entity/view/role change: role labels are completeness-enforced and a missing one FAILS install.",
     inputSchema: { ...translationSyncSchema, ...applyInput }
   },
   envelope(translationSync)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.44",
+  "version": "0.2.45",
   "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.35",
-    "@dforge-core/metadata": "^0.0.44",
+    "@dforge-core/dforge-cli": "^0.2.36",
+    "@dforge-core/metadata": "^0.0.46",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },

package/resources/docs/conventions.md

@@ -66,8 +66,8 @@ Use the CRM sample module (`modules/crm/`) as a reference implementation.
 ├── /security/                 # Security definitions
 │   └── roles.json
 ├── /translations/             # Translations (optional)
-│   ├── en-US.json
-│   └── de-DE.json
+│   ├── de-DE.json         # one per supportedLocales entry — never en*.json
+│   └── uk-UA.json
 ├── /print_templates/          # HTML/CSS print templates (optional)
 │   ├── invoice.html
 │   └── invoice.css
@@ -106,6 +106,7 @@ Use the CRM sample module (`modules/crm/`) as a reference implementation.
 - `entities` maps entity codes to file paths (relative to module root)
 - Omit `"system": true` for regular modules (defaults to false)
 - Omit `schemaName` to use `code` as the schema name
+- The schema and the code must be free: a first install, or an upgrade that moves the module to another schema, is refused when another module already holds that schema or code (compared case-insensitively). Modules that already share a schema keep upgrading.
 
 ### 1b. Module Extensions
 
@@ -644,37 +645,39 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 
 **Reference:** `modules/chore/` — single-job smoke-test module.
 
-### 8. Translations (`translations/en-US.json`)
+### 8. Translations (`translations/de-DE.json`)
+
+One file per locale in `manifest.supportedLocales`. There is **no** English file: install skips `translations/en.json` and `en-*.json`, and the English UI shows the definitions' own text — an entity's or field's `description`, a view's, menu's, action's or report's `label`, a role's or setting's `description`. Keep those short labels.
 
 ```json
 {
 	"entities": {
 		"department": {
-			"label": "Department",
-			"desc": "Company departments",
+			"label": "Abteilung",
+			"desc": "Abteilungen des Unternehmens",
 			"fields": {
-				"department_id": { "label": "Department ID" },
-				"department_name": { "label": "Department Name" }
+				"department_id": { "label": "Abteilungs-ID" },
+				"department_name": { "label": "Abteilungsname" }
 			}
 		},
 		"employee": {
 			"constraints": {
-				"chk_salary_positive": { "message": "Salary must be positive" }
+				"chk_salary_positive": { "message": "Das Gehalt muss positiv sein" }
 			}
 		}
 	},
 	"folders": {
-		"hr": { "label": "Human Resources" }
+		"hr": { "label": "Personalwesen" }
 	},
 	"views": {
-		"departments": { "label": "Departments" },
-		"employees": { "label": "All Employees" }
+		"departments": { "label": "Abteilungen" },
+		"employees": { "label": "Alle Mitarbeiter" }
 	},
 	"menus": {
-		"hr_menu": { "label": "Human Resources" }
+		"hr_menu": { "label": "Personalwesen" }
 	},
 	"actions": {
-		"approve_leave": { "label": "Approve Leave", "desc": "Approve a leave request" }
+		"approve_leave": { "label": "Urlaub genehmigen", "desc": "Einen Urlaubsantrag genehmigen" }
 	}
 }
 ```
@@ -683,7 +686,7 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 
 **Constraint violation messages are localizable (opt-in).** The `message` on a check/unique constraint in the entity JSON is the base (fallback) text. To localize it, add a per-locale override under `entities.<entityCd>.constraints.<constraintName>.message` in each `translations/<locale>.json`. The server resolves it with culture fallback (per-locale → base) and it surfaces identically on the client pre-save validator and the server DB-violation path. Unlike labels, constraint overrides are **not** completeness-enforced: a missing override for a declared `supportedLocales` entry emits a **non-fatal warning** (from `dforge_module_validate` pre-flight and at install) and the base message is used as the fallback.
 
-**Silently ignored at runtime:** `roles` and `print_templates` — the resource rows have no `res_id`, so translations are reserved for future use. `settings` is validated for completeness (when listed in `supportedLocales`) but the registrar does not display the translated labels, so don't expect localized output. Display names for these come from the source manifest (`description` for roles, `label` for print templates and settings).
+**Roles and settings are translated; print templates are not.** `roles.<code>.label` and `settings.<code>.label` are completeness-enforced for each declared locale, over the English `description` in `security/roles.json` and `settings.json` (the registrar reads no `label` there). A print template has no translatable resource: its name is its `description` in every language, and a `print_templates` section is ignored.
 
 ---