@dforge-core/dforge-mcp 0.1.11 → 0.2.0

package/dist/server.js

@@ -98,7 +98,7 @@ var require_code = __commonJS({
     }
     exports2._ = _;
     var plus = new _Code("+");
-    function str(strs, ...args) {
+    function str2(strs, ...args) {
       const expr = [safeStringify(strs[0])];
       let i = 0;
       while (i < args.length) {
@@ -109,7 +109,7 @@ var require_code = __commonJS({
       optimize(expr);
       return new _Code(expr);
     }
-    exports2.str = str;
+    exports2.str = str2;
     function addCodeArg(code2, arg) {
       if (arg instanceof _Code)
         code2.push(...arg._items);
@@ -152,7 +152,7 @@ var require_code = __commonJS({
       return;
     }
     function strConcat(c1, c2) {
-      return c2.emptyStr() ? c1 : c1.emptyStr() ? c2 : str`${c1}${c2}`;
+      return c2.emptyStr() ? c1 : c1.emptyStr() ? c2 : str2`${c1}${c2}`;
     }
     exports2.strConcat = strConcat;
     function interpolate(x) {
@@ -1114,22 +1114,22 @@ var require_util = __commonJS({
       return (0, codegen_1._)`${topSchemaRef}${schemaPath}${(0, codegen_1.getProperty)(keyword)}`;
     }
     exports2.schemaRefOrVal = schemaRefOrVal;
-    function unescapeFragment(str) {
-      return unescapeJsonPointer(decodeURIComponent(str));
+    function unescapeFragment(str2) {
+      return unescapeJsonPointer(decodeURIComponent(str2));
     }
     exports2.unescapeFragment = unescapeFragment;
-    function escapeFragment(str) {
-      return encodeURIComponent(escapeJsonPointer(str));
+    function escapeFragment(str2) {
+      return encodeURIComponent(escapeJsonPointer(str2));
     }
     exports2.escapeFragment = escapeFragment;
-    function escapeJsonPointer(str) {
-      if (typeof str == "number")
-        return `${str}`;
-      return str.replace(/~/g, "~0").replace(/\//g, "~1");
+    function escapeJsonPointer(str2) {
+      if (typeof str2 == "number")
+        return `${str2}`;
+      return str2.replace(/~/g, "~0").replace(/\//g, "~1");
     }
     exports2.escapeJsonPointer = escapeJsonPointer;
-    function unescapeJsonPointer(str) {
-      return str.replace(/~1/g, "/").replace(/~0/g, "~");
+    function unescapeJsonPointer(str2) {
+      return str2.replace(/~1/g, "/").replace(/~0/g, "~");
     }
     exports2.unescapeJsonPointer = unescapeJsonPointer;
     function eachItem(xs, f) {
@@ -2154,8 +2154,8 @@ var require_json_schema_traverse = __commonJS({
         post(schema2, jsonPtr, rootSchema, parentJsonPtr, parentKeyword, parentSchema, keyIndex);
       }
     }
-    function escapeJsonPtr(str) {
-      return str.replace(/~/g, "~0").replace(/\//g, "~1");
+    function escapeJsonPtr(str2) {
+      return str2.replace(/~/g, "~0").replace(/\//g, "~1");
     }
   }
 });
@@ -2981,7 +2981,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve7.call(this, root, ref);
+      let _sch = resolve8.call(this, root, ref);
       if (_sch === void 0) {
         const schema2 = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
         const { schemaId } = this.opts;
@@ -3008,7 +3008,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve7(root, ref) {
+    function resolve8(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3219,15 +3219,15 @@ var require_utils = __commonJS({
         return { host, isIPV6: false };
       }
     }
-    function findToken(str, token) {
+    function findToken(str2, token) {
       let ind = 0;
-      for (let i = 0; i < str.length; i++) {
-        if (str[i] === token) ind++;
+      for (let i = 0; i < str2.length; i++) {
+        if (str2[i] === token) ind++;
       }
       return ind;
     }
-    function removeDotSegments(path12) {
-      let input = path12;
+    function removeDotSegments(path17) {
+      let input = path17;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3479,8 +3479,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path12, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path12 && path12 !== "/" ? path12 : void 0;
+        const [path17, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path17 && path17 !== "/" ? path17 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -3635,59 +3635,59 @@ var require_fast_uri = __commonJS({
         normalizeString(uri, options);
       } else if (typeof uri === "object") {
         uri = /** @type {T} */
-        parse3(serialize(uri, options), options);
+        parse3(serialize2(uri, options), options);
       }
       return uri;
     }
-    function resolve7(baseURI, relativeURI, options) {
+    function resolve8(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
-      return serialize(resolved, schemelessOptions);
+      return serialize2(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative2, options, skipNormalization) {
+    function resolveComponent(base, relative3, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
-        base = parse3(serialize(base, options), options);
-        relative2 = parse3(serialize(relative2, options), options);
+        base = parse3(serialize2(base, options), options);
+        relative3 = parse3(serialize2(relative3, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative2.scheme) {
-        target.scheme = relative2.scheme;
-        target.userinfo = relative2.userinfo;
-        target.host = relative2.host;
-        target.port = relative2.port;
-        target.path = removeDotSegments(relative2.path || "");
-        target.query = relative2.query;
+      if (!options.tolerant && relative3.scheme) {
+        target.scheme = relative3.scheme;
+        target.userinfo = relative3.userinfo;
+        target.host = relative3.host;
+        target.port = relative3.port;
+        target.path = removeDotSegments(relative3.path || "");
+        target.query = relative3.query;
       } else {
-        if (relative2.userinfo !== void 0 || relative2.host !== void 0 || relative2.port !== void 0) {
-          target.userinfo = relative2.userinfo;
-          target.host = relative2.host;
-          target.port = relative2.port;
-          target.path = removeDotSegments(relative2.path || "");
-          target.query = relative2.query;
+        if (relative3.userinfo !== void 0 || relative3.host !== void 0 || relative3.port !== void 0) {
+          target.userinfo = relative3.userinfo;
+          target.host = relative3.host;
+          target.port = relative3.port;
+          target.path = removeDotSegments(relative3.path || "");
+          target.query = relative3.query;
         } else {
-          if (!relative2.path) {
+          if (!relative3.path) {
             target.path = base.path;
-            if (relative2.query !== void 0) {
-              target.query = relative2.query;
+            if (relative3.query !== void 0) {
+              target.query = relative3.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative2.path[0] === "/") {
-              target.path = removeDotSegments(relative2.path);
+            if (relative3.path[0] === "/") {
+              target.path = removeDotSegments(relative3.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative2.path;
+                target.path = "/" + relative3.path;
               } else if (!base.path) {
-                target.path = relative2.path;
+                target.path = relative3.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative2.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative3.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative2.query;
+            target.query = relative3.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -3695,7 +3695,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative2.fragment;
+      target.fragment = relative3.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -3703,7 +3703,7 @@ var require_fast_uri = __commonJS({
       const normalizedB = normalizeComparableURI(uriB, options);
       return normalizedA !== void 0 && normalizedB !== void 0 && normalizedA.toLowerCase() === normalizedB.toLowerCase();
     }
-    function serialize(cmpts, opts) {
+    function serialize2(cmpts, opts) {
       const component = {
         host: cmpts.host,
         scheme: cmpts.scheme,
@@ -3881,7 +3881,7 @@ var require_fast_uri = __commonJS({
     function normalizeStringWithStatus(uri, opts) {
       const { parsed, malformedAuthorityOrPort } = parseWithStatus(uri, opts);
       return {
-        normalized: malformedAuthorityOrPort ? uri : serialize(parsed, opts),
+        normalized: malformedAuthorityOrPort ? uri : serialize2(parsed, opts),
         malformedAuthorityOrPort
       };
     }
@@ -3891,16 +3891,16 @@ var require_fast_uri = __commonJS({
         return malformedAuthorityOrPort ? void 0 : normalized;
       }
       if (typeof uri === "object") {
-        return serialize(uri, opts);
+        return serialize2(uri, opts);
       }
     }
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve7,
+      resolve: resolve8,
       resolveComponent,
       equal,
-      serialize,
+      serialize: serialize2,
       parse: parse3
     };
     module2.exports = fastUri;
@@ -3959,7 +3959,7 @@ var require_core = __commonJS({
     var util_1 = require_util();
     var $dataRefSchema = require_data();
     var uri_1 = require_uri();
-    var defaultRegExp = (str, flags) => new RegExp(str, flags);
+    var defaultRegExp = (str2, flags) => new RegExp(str2, flags);
     defaultRegExp.code = "new RegExp";
     var META_IGNORE_OPTIONS = ["removeAdditional", "useDefaults", "coerceTypes"];
     var EXT_SCOPE_NAMES = /* @__PURE__ */ new Set([
@@ -4754,16 +4754,16 @@ var require_ucs2length = __commonJS({
   "node_modules/ajv/dist/runtime/ucs2length.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    function ucs2length(str) {
-      const len = str.length;
+    function ucs2length(str2) {
+      const len = str2.length;
       let length = 0;
       let pos = 0;
       let value;
       while (pos < len) {
         length++;
-        value = str.charCodeAt(pos++);
+        value = str2.charCodeAt(pos++);
         if (value >= 55296 && value <= 56319 && pos < len) {
-          value = str.charCodeAt(pos);
+          value = str2.charCodeAt(pos);
           if ((value & 64512) === 56320)
             pos++;
         }
@@ -6646,8 +6646,8 @@ var require_formats = __commonJS({
     }
     var DATE = /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
     var DAYS = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
-    function date5(str) {
-      const matches = DATE.exec(str);
+    function date5(str2) {
+      const matches = DATE.exec(str2);
       if (!matches)
         return false;
       const year = +matches[1];
@@ -6666,8 +6666,8 @@ var require_formats = __commonJS({
     }
     var TIME = /^(\d\d):(\d\d):(\d\d(?:\.\d+)?)(z|([+-])(\d\d)(?::?(\d\d))?)?$/i;
     function getTime(strictTimeZone) {
-      return function time3(str) {
-        const matches = TIME.exec(str);
+      return function time3(str2) {
+        const matches = TIME.exec(str2);
         if (!matches)
           return false;
         const hr = +matches[1];
@@ -6713,8 +6713,8 @@ var require_formats = __commonJS({
     var DATE_TIME_SEPARATOR = /t|\s/i;
     function getDateTime(strictTimeZone) {
       const time3 = getTime(strictTimeZone);
-      return function date_time(str) {
-        const dateTime = str.split(DATE_TIME_SEPARATOR);
+      return function date_time(str2) {
+        const dateTime = str2.split(DATE_TIME_SEPARATOR);
         return dateTime.length === 2 && date5(dateTime[0]) && time3(dateTime[1]);
       };
     }
@@ -6739,13 +6739,13 @@ var require_formats = __commonJS({
     }
     var NOT_URI_FRAGMENT = /\/|:/;
     var URI = /^(?:[a-z][a-z0-9+\-.]*:)(?:\/?\/(?:(?:[a-z0-9\-._~!$&'()*+,;=:]|%[0-9a-f]{2})*@)?(?:\[(?:(?:(?:(?:[0-9a-f]{1,4}:){6}|::(?:[0-9a-f]{1,4}:){5}|(?:[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){4}|(?:(?:[0-9a-f]{1,4}:){0,1}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){3}|(?:(?:[0-9a-f]{1,4}:){0,2}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){2}|(?:(?:[0-9a-f]{1,4}:){0,3}[0-9a-f]{1,4})?::[0-9a-f]{1,4}:|(?:(?:[0-9a-f]{1,4}:){0,4}[0-9a-f]{1,4})?::)(?:[0-9a-f]{1,4}:[0-9a-f]{1,4}|(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?))|(?:(?:[0-9a-f]{1,4}:){0,5}[0-9a-f]{1,4})?::[0-9a-f]{1,4}|(?:(?:[0-9a-f]{1,4}:){0,6}[0-9a-f]{1,4})?::)|[Vv][0-9a-f]+\.[a-z0-9\-._~!$&'()*+,;=:]+)\]|(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)|(?:[a-z0-9\-._~!$&'()*+,;=]|%[0-9a-f]{2})*)(?::\d*)?(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*|\/(?:(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)?|(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)(?:\?(?:[a-z0-9\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?(?:#(?:[a-z0-9\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?$/i;
-    function uri(str) {
-      return NOT_URI_FRAGMENT.test(str) && URI.test(str);
+    function uri(str2) {
+      return NOT_URI_FRAGMENT.test(str2) && URI.test(str2);
     }
     var BYTE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/gm;
-    function byte(str) {
+    function byte(str2) {
       BYTE.lastIndex = 0;
-      return BYTE.test(str);
+      return BYTE.test(str2);
     }
     var MIN_INT32 = -(2 ** 31);
     var MAX_INT32 = 2 ** 31 - 1;
@@ -6759,11 +6759,11 @@ var require_formats = __commonJS({
       return true;
     }
     var Z_ANCHOR = /[^\\]\\Z/;
-    function regex(str) {
-      if (Z_ANCHOR.test(str))
+    function regex(str2) {
+      if (Z_ANCHOR.test(str2))
         return false;
       try {
-        new RegExp(str);
+        new RegExp(str2);
         return true;
       } catch (e) {
         return false;
@@ -6873,12 +6873,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs10, exportName) {
+    function addFormats(ajv, list, fs14, exportName) {
       var _a3;
       var _b;
       (_a3 = (_b = ajv.opts.code).formats) !== null && _a3 !== void 0 ? _a3 : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs10[f]);
+        ajv.addFormat(f, fs14[f]);
     }
     module2.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -7245,8 +7245,8 @@ function getErrorMap() {
 
 // node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path12, errorMaps, issueData } = params;
-  const fullPath = [...path12, ...issueData.path || []];
+  const { data, path: path17, errorMaps, issueData } = params;
+  const fullPath = [...path17, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -7361,11 +7361,11 @@ var errorUtil;
 
 // node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path12, key) {
+  constructor(parent, value, path17, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path12;
+    this._path = path17;
     this._key = key;
   }
   get path() {
@@ -11285,10 +11285,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema2) {
   return mergeDefs(schema2._zod.def);
 }
-function getElementAtPath(obj, path12) {
-  if (!path12)
+function getElementAtPath(obj, path17) {
+  if (!path17)
     return obj;
-  return path12.reduce((acc, key) => acc?.[key], obj);
+  return path17.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -11303,14 +11303,14 @@ function promiseAllObject(promisesObj) {
 }
 function randomString(length = 10) {
   const chars = "abcdefghijklmnopqrstuvwxyz";
-  let str = "";
+  let str2 = "";
   for (let i = 0; i < length; i++) {
-    str += chars[Math.floor(Math.random() * chars.length)];
+    str2 += chars[Math.floor(Math.random() * chars.length)];
   }
-  return str;
+  return str2;
 }
-function esc(str) {
-  return JSON.stringify(str);
+function esc(str2) {
+  return JSON.stringify(str2);
 }
 function slugify(input) {
   return input.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_-]+/g, "-").replace(/^-+|-+$/g, "");
@@ -11424,8 +11424,8 @@ var primitiveTypes = /* @__PURE__ */ new Set([
   "symbol",
   "undefined"
 ]);
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function escapeRegex(str2) {
+  return str2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function clone(inst, def, params) {
   const cl = new inst._zod.constr(def ?? inst._zod.def);
@@ -11697,11 +11697,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path12, issues) {
+function prefixIssues(path17, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path12);
+    iss.path.unshift(path17);
     return iss;
   });
 }
@@ -11848,16 +11848,16 @@ function flattenError(error51, mapper = (issue2) => issue2.message) {
 }
 function formatError(error51, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error52, path12 = []) => {
+  const processError = (error52, path17 = []) => {
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path12, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path17, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
       } else {
-        const fullpath = [...path12, ...issue2.path];
+        const fullpath = [...path17, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -11884,17 +11884,17 @@ function formatError(error51, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error51, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error52, path12 = []) => {
+  const processError = (error52, path17 = []) => {
     var _a3, _b;
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path12, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path17, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
       } else {
-        const fullpath = [...path12, ...issue2.path];
+        const fullpath = [...path17, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -11926,8 +11926,8 @@ function treeifyError(error51, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path12 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path12) {
+  const path17 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path17) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -25052,13 +25052,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path12 = ref.slice(1).split("/").filter(Boolean);
-  if (path12.length === 0) {
+  const path17 = ref.slice(1).split("/").filter(Boolean);
+  if (path17.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path12[0] === defsKey) {
-    const key = path12[1];
+  if (path17[0] === defsKey) {
+    const key = path17[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -28828,7 +28828,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve7) => setTimeout(resolve7, pollInterval));
+        await new Promise((resolve8) => setTimeout(resolve8, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error51) {
@@ -28845,7 +28845,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve7, reject) => {
+    return new Promise((resolve8, reject) => {
       const earlyReject = (error51) => {
         reject(error51);
       };
@@ -28923,7 +28923,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve7(parseResult.data);
+            resolve8(parseResult.data);
           }
         } catch (error51) {
           reject(error51);
@@ -29184,12 +29184,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve7, reject) => {
+    return new Promise((resolve8, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve7, interval);
+      const timeoutId = setTimeout(resolve8, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -30289,7 +30289,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve7) => setTimeout(resolve7, pollInterval));
+      await new Promise((resolve8) => setTimeout(resolve8, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -30938,12 +30938,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve7) => {
+    return new Promise((resolve8) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve7();
+        resolve8();
       } else {
-        this._stdout.once("drain", resolve7);
+        this._stdout.once("drain", resolve8);
       }
     });
   }
@@ -31410,7 +31410,8 @@ function modulePaths(moduleDir) {
     jobs: path.join(root, "logic", "jobs.json"),
     triggers: path.join(root, "logic", "triggers.json"),
     webhooks: path.join(root, "logic", "webhooks.json"),
-    settings: path.join(root, "settings.json")
+    settings: path.join(root, "settings.json"),
+    domains: path.join(root, "domains.json")
   };
 }
 function readJson(absPath) {
@@ -31460,6 +31461,7 @@ function withTodayStamp(manifest) {
   return { ...manifest, updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10) };
 }
 var PHASE_STATE_FILE = "docs/phase.json";
+var BUILD_PHASES = ["1", "2", "3", "4", "5", "6"];
 function phaseStateJson(state) {
   return JSON.stringify(state, null, "	") + "\n";
 }
@@ -31472,6 +31474,21 @@ function readPhaseState(moduleDir) {
     return null;
   }
 }
+function markPhase(moduleDir, phase, opts = {}) {
+  const prior = readPhaseState(moduleDir) ?? {};
+  const state = {
+    ...prior,
+    phases: {
+      ...prior.phases ?? {},
+      [phase]: {
+        completedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+        ...opts.skipped ? { skipped: true } : {},
+        ...opts.note ? { note: opts.note } : {}
+      }
+    }
+  };
+  return { state, json: phaseStateJson(state) };
+}
 function isReadyToScaffold(moduleDir) {
   const state = readPhaseState(moduleDir);
   if (state && typeof state.readyToScaffold === "boolean") return state.readyToScaffold;
@@ -31555,6 +31572,36 @@ function assertSecurityCoverage(moduleDir) {
   }
   return void 0;
 }
+var KEY_SEP = "::";
+function compositeKey(...parts) {
+  return parts.join(KEY_SEP);
+}
+function walkFolders(root) {
+  const out = [];
+  const visit = (node, trail) => {
+    const children = node.children ?? {};
+    for (const [code2, child] of Object.entries(children)) {
+      if (!child || typeof child !== "object") continue;
+      const next = [...trail, code2];
+      out.push({ code: code2, path: next.join("/"), node: child });
+      visit(child, next);
+    }
+  };
+  visit(root, []);
+  return out;
+}
+function duplicateFolderCodes(root) {
+  const byCode = /* @__PURE__ */ new Map();
+  for (const f of walkFolders(root)) {
+    const paths = byCode.get(f.code) ?? [];
+    paths.push(f.path);
+    byCode.set(f.code, paths);
+  }
+  for (const [code2, paths] of byCode) {
+    if (paths.length < 2) byCode.delete(code2);
+  }
+  return byCode;
+}
 var TRAIT_CODES = traits.map((t) => t.cd);
 var TRAIT_CODE_SET = new Set(TRAIT_CODES);
 var traitsInput = external_exports.array(external_exports.string()).default(["identity", "audit"]).superRefine((arr, ctx) => {
@@ -31569,9 +31616,25 @@ var traitsInput = external_exports.array(external_exports.string()).default(["id
 }).describe(
   "Entity trait codes \u2014 identity, audit, audit-full, soft-delete, sorting, postable, accumulation, ledger, period. 'identity' makes the PK '{entity}_id'. Traits expand into columns server-side at install; list only the codes."
 );
+function unknownTraits(traitCodes) {
+  return traitCodes.filter((cd) => !TRAIT_CODE_SET.has(cd));
+}
+function assertKnownTraits(traitCodes, entityName) {
+  const bad = unknownTraits(traitCodes);
+  if (bad.length === 0) return;
+  throw new Error(
+    `Entity '${entityName}' declares unknown trait(s): ${bad.join(", ")}. Valid: ${TRAIT_CODES.join(", ")}. An unrecognized trait is silently ignored when columns are expanded, so its columns would quietly go missing rather than fail loudly. (See dforge://reference/traits.)`
+  );
+}
 function withTraits(entity, traitCodes) {
   return { ...entity, traits: [...traitCodes] };
 }
+function withIdentityToString(entity, entityName, traitCodes) {
+  const ts = Object.prototype.hasOwnProperty.call(entity, "toString") ? entity.toString : void 0;
+  if (typeof ts !== "string" || ts !== "{id}") return entity;
+  const pk = traitCodes.includes("identity") ? `${entityName}_id` : "id";
+  return { ...entity, toString: `{${pk}}` };
+}
 
 // src/tools/create-module.ts
 var createModuleSchema = {
@@ -31652,7 +31715,11 @@ function createModuleFiles(args) {
   };
   write("manifest.json", buildManifest(opts, moduleId));
   for (const e of opts.entities) {
-    write(`entities/${e.name}.json`, withTraits(buildEntity(e), traitsByName[e.name]));
+    const traits2 = traitsByName[e.name];
+    write(
+      `entities/${e.name}.json`,
+      withIdentityToString(withTraits(buildEntity(e), traits2), e.name, traits2)
+    );
   }
   write("ui/data_views.json", buildDataViews(opts.entities));
   write("ui/folders.json", buildFolders(opts));
@@ -31736,8 +31803,15 @@ Total FKs: <N>
 *Approved: <date>*
 `;
 var planModuleSchema = {
-  action: external_exports.enum(["check", "write_identity", "write_requirements", "write_design", "validate"]).describe(
-    "Sub-command: 'check' = current Phase 0 state; 'write_identity' = Phase 0a; 'write_requirements' = Phase 0b; 'write_design' = Phase 0c; 'validate' = Phase 0d."
+  action: external_exports.enum([
+    "check",
+    "write_identity",
+    "write_requirements",
+    "write_design",
+    "validate",
+    "complete_phase"
+  ]).describe(
+    "Sub-command: 'check' = current lifecycle state (Phase 0 sub-phase, or the build/ship phase once Phase 0 is done) + which skill to run next; 'write_identity' = Phase 0a; 'write_requirements' = Phase 0b; 'write_design' = Phase 0c; 'validate' = Phase 0d; 'complete_phase' = record a build phase (1-6) as done or deliberately skipped."
   ),
   moduleDir: external_exports.string().describe(
     "Absolute path to the module directory. Ask the user for this before the first call."
@@ -31767,7 +31841,15 @@ var planModuleSchema = {
     })
   ).optional().describe(
     "[validate] Semantic check results from agent evaluation. Omit on the first call (structural pre-check only). Provide after evaluating the returned semanticChecks."
-  )
+  ),
+  // ── complete_phase fields (Phases 1-6) ───────────────────────────────
+  phase: external_exports.enum(BUILD_PHASES).optional().describe(
+    "[complete_phase] Which build phase finished: '1' domain, '2' behavior, '3' views/reports, '4' polish, '5' security, '6' verify."
+  ),
+  skipped: external_exports.boolean().optional().describe(
+    "[complete_phase] True when the phase was deliberately skipped rather than done (only valid for the optional phases 2 and 4). Recording it stops a resumed session from re-proposing work the user already declined."
+  ),
+  note: external_exports.string().optional().describe("[complete_phase] One-line record of what was done or why it was skipped.")
 };
 function planModule(rawArgs) {
   const root = path3.resolve(rawArgs.moduleDir);
@@ -31782,7 +31864,168 @@ function planModule(rawArgs) {
       return handleWriteDesign(root, rawArgs);
     case "validate":
       return handleValidate(root, rawArgs);
+    case "complete_phase":
+      return handleCompletePhase(root, rawArgs);
+  }
+}
+var SKILL_FOR_PHASE = {
+  "0a": "dforge-module-design",
+  "0b": "dforge-module-design",
+  "0c": "dforge-module-design",
+  "0d": "dforge-module-design",
+  "1": "dforge-module-build",
+  "2": "dforge-module-build",
+  "3": "dforge-module-build",
+  "4": "dforge-module-build",
+  "5": "dforge-module-build",
+  "6": "dforge-module-ship"
+};
+var PHASE_TITLES = {
+  "1": "Domain \u2014 entities, fields, relations (required)",
+  "2": "Behavior \u2014 actions, triggers, jobs, webhooks (optional)",
+  "3": "Views + menus, reports (3a grids required)",
+  "4": "Polish \u2014 settings, translations, seed data (optional)",
+  "5": "Security \u2014 roles + rights matrix (5a required)",
+  "6": "Verify \u2014 validate, pack, install (required)"
+};
+var REQUIRED_PHASES = ["1", "3", "5", "6"];
+function gatherEvidence(root) {
+  const paths = modulePaths(root);
+  const empty = {
+    scaffolded: false,
+    entityCount: 0,
+    entitiesWithoutFields: [],
+    entitiesWithoutView: [],
+    entitiesWithoutSelect: [],
+    actionCount: 0,
+    viewCount: 0,
+    roleCount: 0
+  };
+  if (!fileExists(paths.manifest)) return empty;
+  let manifest;
+  try {
+    manifest = JSON.parse(readFile(paths.manifest));
+  } catch {
+    return empty;
+  }
+  const entityMap = manifest.entities ?? {};
+  const names = Object.keys(entityMap).filter((n) => !n.includes("."));
+  const entitiesWithoutFields = [];
+  for (const name of names) {
+    const abs = path3.join(root, entityMap[name].replace(/^\.\//, ""));
+    if (!fileExists(abs)) {
+      entitiesWithoutFields.push(name);
+      continue;
+    }
+    try {
+      const e = JSON.parse(readFile(abs));
+      if (Object.keys(e.fields ?? {}).length === 0) entitiesWithoutFields.push(name);
+    } catch {
+      entitiesWithoutFields.push(name);
+    }
+  }
+  const views = readJsonOrDefault(paths.dataViews, {});
+  const covered = /* @__PURE__ */ new Set();
+  for (const v of Object.values(views)) {
+    for (const s of v.dataSources ?? []) {
+      if (typeof s.entityCode === "string") covered.add(s.entityCode);
+    }
+  }
+  let entitiesWithoutSelect = [];
+  try {
+    entitiesWithoutSelect = checkSecurityCoverage(root).uncoveredEntities;
+  } catch {
+    entitiesWithoutSelect = names;
+  }
+  return {
+    scaffolded: true,
+    entityCount: names.length,
+    entitiesWithoutFields,
+    entitiesWithoutView: names.filter((n) => !covered.has(n)),
+    entitiesWithoutSelect,
+    actionCount: Object.keys(readJsonOrDefault(paths.actions, {})).length,
+    viewCount: Object.keys(views).length,
+    roleCount: Object.keys(readJsonOrDefault(paths.roles, {})).length
+  };
+}
+function buildPhaseCheck(root) {
+  const ledger = readPhaseState(root)?.phases ?? {};
+  const ev = gatherEvidence(root);
+  const recorded = (p) => Boolean(ledger[p]);
+  const completed = BUILD_PHASES.filter(recorded);
+  const gaps = [];
+  if (!ev.scaffolded) {
+    gaps.push("no manifest.json \u2014 the module has not been scaffolded (dforge_module_create).");
+  } else {
+    if (ev.entitiesWithoutFields.length > 0) {
+      gaps.push(
+        `Phase 1: entities with no fields yet: ${ev.entitiesWithoutFields.join(", ")}.`
+      );
+    }
+    if (ev.entitiesWithoutView.length > 0) {
+      gaps.push(
+        `Phase 3a: entities with no data view: ${ev.entitiesWithoutView.join(", ")} (every entity needs a default grid).`
+      );
+    }
+    if (ev.entitiesWithoutSelect.length > 0) {
+      gaps.push(
+        `Phase 5a: entities with no role granting Select: ${ev.entitiesWithoutSelect.join(", ")} (dforge_module_pack refuses to build until fixed).`
+      );
+    }
+  }
+  const next = BUILD_PHASES.find((p) => !recorded(p));
+  const allRequiredDone = REQUIRED_PHASES.every(recorded);
+  if (!next || allRequiredDone && gaps.length === 0) {
+    return {
+      summary: `Module complete \u2014 all build phases recorded${gaps.length ? " (with open gaps, see below)" : ""}.`,
+      currentPhase: "complete",
+      phase0: "complete",
+      readyToScaffold: true,
+      completed,
+      pending: [],
+      gaps,
+      evidence: ev,
+      nextStep: gaps.length > 0 ? "Every phase is recorded as done, but the module still shows the gaps listed above. Resolve them, then re-run dforge_module_validate." : "Nothing left to do. Run dforge_module_validate for a final check if the module has changed since install."
+    };
+  }
+  return {
+    summary: `Phase 0 complete. ${completed.length ? `Recorded: ${completed.join(", ")}. ` : ""}Next: Phase ${next} \u2014 ${PHASE_TITLES[next]}.`,
+    currentPhase: next,
+    phase0: "complete",
+    readyToScaffold: true,
+    completed,
+    pending: BUILD_PHASES.filter((p) => !recorded(p)),
+    optionalPhases: ["2", "4"],
+    gaps,
+    evidence: ev,
+    nextSkill: SKILL_FOR_PHASE[next],
+    nextStep: `Run the '${SKILL_FOR_PHASE[next]}' skill and work Phase ${next} (${PHASE_TITLES[next]}). ` + (gaps.length > 0 ? `Open gaps to resolve first: ${gaps.join(" ")} ` : "") + `When the phase is done (or the user declines an optional one), record it with dforge_module_plan({ action: 'complete_phase', moduleDir, phase: '${next}', note: '...' }).`
+  };
+}
+function handleCompletePhase(root, args) {
+  if (!args.phase) {
+    throw new Error(
+      `complete_phase needs a 'phase' \u2014 one of ${BUILD_PHASES.join(", ")}. (Phase 0 sub-phases are recorded by write_identity / write_requirements / write_design / validate.)`
+    );
+  }
+  if (!isReadyToScaffold(root)) {
+    throw new Error(
+      "Phase 0 has not passed validation yet \u2014 there are no build phases to record. Call dforge_module_plan({ action: 'check', moduleDir }) to see what Phase 0 still needs."
+    );
+  }
+  if (args.skipped && args.phase !== "2" && args.phase !== "4") {
+    throw new Error(
+      `Phase ${args.phase} (${PHASE_TITLES[args.phase]}) is required and can't be marked skipped. Only Phases 2 and 4 are optional.`
+    );
   }
+  const { json: json2 } = markPhase(root, args.phase, { skipped: args.skipped, note: args.note });
+  const { currentPhase, nextSkill, nextStep, gaps } = buildPhaseCheck(root);
+  return {
+    summary: `Recorded Phase ${args.phase} as ${args.skipped ? "SKIPPED" : "complete"}${args.note ? ` \u2014 ${args.note}` : ""}.`,
+    files: { [P0.phaseState]: json2 },
+    next: { currentPhase, nextSkill, nextStep, gaps },
+    nextStep: `Write the updated ${P0.phaseState} to disk, then continue: ${nextStep}`
+  };
 }
 function handleCheck(root) {
   const claudePath = path3.join(root, P0.identity);
@@ -31800,16 +32043,7 @@ function handleCheck(root) {
   if (has0d) completed.push("0d");
   const allPhases = ["0a", "0b", "0c", "0d"];
   const pending = allPhases.filter((p) => !completed.includes(p));
-  if (has0d) {
-    return {
-      summary: "Phase 0 complete \u2014 all docs present and validated.",
-      currentPhase: "complete",
-      completed,
-      pending: [],
-      readyToScaffold: true,
-      nextStep: "All Phase 0 docs are in place. Call dforge_module_create({ moduleDir, code, displayName, entities, ... }) to scaffold the module."
-    };
-  }
+  if (has0d) return buildPhaseCheck(root);
   if (!has0a) {
     return {
       summary: "Phase 0 not started.",
@@ -32305,7 +32539,15 @@ function addEntityFiles(args) {
   };
   const files = {};
   files["manifest.json"] = JSON.stringify(newManifest, null, "	") + "\n";
-  files[`entities/${newEntity.name}.json`] = JSON.stringify(withTraits(buildEntity(newEntity), args.entity.traits), null, "	") + "\n";
+  files[`entities/${newEntity.name}.json`] = JSON.stringify(
+    withIdentityToString(
+      withTraits(buildEntity(newEntity), args.entity.traits),
+      args.entity.name,
+      args.entity.traits
+    ),
+    null,
+    "	"
+  ) + "\n";
   files["ui/data_views.json"] = JSON.stringify(buildDataViews(allEntities), null, "	") + "\n";
   files["ui/folders.json"] = JSON.stringify(buildFolders(opts), null, "	") + "\n";
   files["ui/menus.json"] = JSON.stringify(buildMenus(opts), null, "	") + "\n";
@@ -32798,6 +33040,8 @@ function installModule(args) {
 
 // src/tools/entity-field.ts
 var path6 = __toESM(require("path"));
+
+// src/tools/field-rules.ts
 var FIELD_TYPE_ALIASES = {
   integer: "number",
   int: "number",
@@ -32815,6 +33059,141 @@ var FIELD_TYPE_ALIASES = {
   select: "dropdown",
   multiselect: "flags"
 };
+var DB_DATATYPE_ALIASES = {
+  boolean: "bool",
+  string: "varchar",
+  datetime: "timestamptz",
+  timestamp: "timestamptz",
+  integer: "int",
+  number: ["int", "bigint", "numeric"],
+  float: "numeric",
+  decimal: "numeric",
+  double: "numeric",
+  uuid: "cuid"
+};
+function formatSuggestion(fix) {
+  return Array.isArray(fix) ? fix.map((f) => `'${f}'`).join(" / ") : `'${fix}'`;
+}
+function checkFieldSpec(where, field) {
+  const issues = [];
+  if (!field || typeof field !== "object") {
+    return [{ level: "error", message: `${where}: field spec is not an object.` }];
+  }
+  const v = field;
+  const err = (message) => issues.push({ level: "error", message: `${where}: ${message}` });
+  const warn = (message) => issues.push({ level: "warning", message: `${where}: ${message}` });
+  if (v.defaultValue !== void 0 || v.default !== void 0) {
+    err(
+      `entity fields have no 'defaultValue'/'default' key (settings-only). Set a default with 'formula' (e.g. "formula": "'draft'" or "formula": "TODAY()"), a numberSequence, or DSL logic.`
+    );
+  }
+  if (v.options !== void 0) {
+    err(
+      'dropdown options go under params.options, not at the field root, e.g. "params": { "options": [{ "value": "a", "label": "A" }] }.'
+    );
+  }
+  if (typeof v.flags === "string" && v.flags.length > 0 && !/^[VIEMH]+$/.test(v.flags)) {
+    err(
+      `flags '${v.flags}' contains invalid letters \u2014 use only V/I/E/M/H (e.g. VEM, VE, V, EM). U/S/P are not flag letters.`
+    );
+  }
+  if (typeof v.fieldTypeCd === "string" && v.fieldTypeCd.length > 0 && !isFieldTypeCd(v.fieldTypeCd)) {
+    const alias = FIELD_TYPE_ALIASES[v.fieldTypeCd.toLowerCase()];
+    const hint = alias ? ` Did you mean '${alias}'?` : ` Valid codes: ${[...fieldTypeCds].sort().join(", ")}.`;
+    err(
+      `fieldTypeCd '${v.fieldTypeCd}' is not a valid field type.${hint} (See dforge://reference/field-types.)`
+    );
+  }
+  const columnType = typeof v.columnType === "string" ? v.columnType : "";
+  if (columnType.length > 0 && !getColumnType(columnType)) {
+    err(
+      `columnType '${columnType}' is invalid. Use 'R' (reference), 'S' (set/child list), or 'F' (formula) \u2014 or omit it for a plain data column. (A/L/G exist for register columns.)`
+    );
+  }
+  if (typeof v.dbDatatype === "string" && v.dbDatatype.length > 0) {
+    const base = v.dbDatatype.replace(/\(.*$/, "").trim().toLowerCase();
+    const fix = DB_DATATYPE_ALIASES[base];
+    if (fix) {
+      err(
+        `dbDatatype '${v.dbDatatype}' is not a SQL type \u2014 use ${formatSuggestion(fix)}. (dbDatatype = SQL type; fieldTypeCd = UI control. See dforge://reference/field-types.)`
+      );
+    } else if (isFieldTypeCd(base) && base !== "date" && base !== "time" && base !== "text") {
+      err(
+        `dbDatatype '${v.dbDatatype}' is a fieldTypeCd, not a SQL type. Use a SQL type (bool, varchar, text, int, bigint, numeric, timestamptz, date, time, cuid, json), or omit it \u2014 it's derived from fieldTypeCd.`
+      );
+    }
+  }
+  if (columnType === "F") {
+    if (typeof v.baseDatatypeCd !== "string" || v.baseDatatypeCd.length === 0) {
+      err("formula column (columnType 'F') requires 'baseDatatypeCd'. (See dforge://reference/formulas.)");
+    }
+    if (v.dbDatatype !== void 0) {
+      err(
+        "formula column (columnType 'F') must NOT set 'dbDatatype' \u2014 it owns no physical column. Use 'baseDatatypeCd' instead."
+      );
+    }
+    if (typeof v.formula !== "string" || v.formula.trim() === "") {
+      err("formula column (columnType 'F') requires a non-empty 'formula' expression.");
+    }
+    if (typeof v.flags === "string" && v.flags !== "V" && /^[VIEMH]+$/.test(v.flags)) {
+      warn(
+        `formula column has flags '${v.flags}' \u2014 a computed column is read-only, expected flags 'V'.`
+      );
+    }
+  }
+  if (columnType === "G") {
+    if (typeof v.formula !== "string" || v.formula.trim() === "") {
+      err("generated column (columnType 'G') requires a 'formula' expression.");
+    }
+    if (typeof v.dbDatatype !== "string" || v.dbDatatype.length === 0) {
+      err(
+        "generated column (columnType 'G') requires 'dbDatatype' \u2014 it's a physical, trigger-maintained column. (See dforge://reference/column-types.)"
+      );
+    }
+    if (v.baseDatatypeCd !== void 0) {
+      err("generated column (columnType 'G') must NOT set 'baseDatatypeCd' \u2014 use 'dbDatatype'.");
+    }
+  }
+  if (columnType === "R") {
+    const link = v.link;
+    if (!link || typeof link !== "object") {
+      err(
+        "reference column (columnType 'R') requires a 'link' object { entity, thisKey, otherKey }. (See dforge://reference/column-types.)"
+      );
+    } else {
+      for (const k of ["entity", "thisKey", "otherKey"]) {
+        if (typeof link[k] !== "string" || link[k].length === 0) {
+          err(`reference column's link.${k} is missing \u2014 link needs { entity, thisKey, otherKey }.`);
+        }
+      }
+      if (link.otherKey === "id") {
+        err(
+          `link.otherKey is 'id' \u2014 the identity trait names the PK '{entity}_id' (e.g. '${String(link.entity ?? "target")}_id'), never 'id'.`
+        );
+      }
+    }
+    if (v.fieldTypeCd !== void 0 && v.fieldTypeCd !== "lookup") {
+      warn(
+        `reference column has fieldTypeCd '${String(v.fieldTypeCd)}' \u2014 the visible half of an FK+Reference pair is normally 'lookup'.`
+      );
+    }
+    if (v.dbDatatype !== void 0) {
+      err(
+        "reference column (columnType 'R') must NOT set 'dbDatatype' \u2014 the physical column is the paired hidden FK (flags 'EM'), not this one."
+      );
+    }
+  }
+  return issues;
+}
+function parseSetAggregate(formula) {
+  const m = formula.match(
+    /\b(SUM|COUNT|AVG|MIN|MAX)\s*\(\s*\[([a-z][a-z0-9_]*)\]\s*\.\s*\[([a-z][a-z0-9_]*)\]\s*\)/i
+  );
+  if (!m) return null;
+  return { agg: m[1].toUpperCase(), setField: m[2], childField: m[3] };
+}
+
+// src/tools/entity-field.ts
 function finalizeField(field) {
   const ftc = field.fieldTypeCd;
   if (typeof ftc !== "string" || field.dbDatatype !== void 0) return field;
@@ -32839,37 +33218,11 @@ var fieldSchema = external_exports.object({
   link: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
   params: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
 }).passthrough().superRefine((val, ctx) => {
-  const v = val;
-  if (v.defaultValue !== void 0 || v.default !== void 0) {
-    ctx.addIssue({
-      code: external_exports.ZodIssueCode.custom,
-      message: `entity fields have no 'defaultValue'/'default' key (settings-only). Set a default with 'formula' (e.g. "formula": "'draft'" or "formula": "TODAY()"), a numberSequence, or DSL logic.`
-    });
-  }
-  if (v.options !== void 0) {
-    ctx.addIssue({
-      code: external_exports.ZodIssueCode.custom,
-      message: 'dropdown options go under params.options, not at the field root, e.g. "params": { "options": [{ "value": "a", "label": "A" }] }.'
-    });
-  }
-  if (typeof v.flags === "string" && v.flags.length > 0 && !/^[VIEMH]+$/.test(v.flags)) {
+  for (const issue2 of checkFieldSpec("field", val)) {
+    if (issue2.level !== "error") continue;
     ctx.addIssue({
       code: external_exports.ZodIssueCode.custom,
-      message: `flags '${v.flags}' contains invalid letters \u2014 use only V/I/E/M/H (e.g. VEM, VE, V, EM). U/S/P are not flag letters.`
-    });
-  }
-  if (typeof v.fieldTypeCd === "string" && v.fieldTypeCd.length > 0 && !isFieldTypeCd(v.fieldTypeCd)) {
-    const alias = FIELD_TYPE_ALIASES[v.fieldTypeCd.toLowerCase()];
-    const hint = alias ? ` Did you mean '${alias}'?` : ` Valid codes: ${[...fieldTypeCds].sort().join(", ")}.`;
-    ctx.addIssue({
-      code: external_exports.ZodIssueCode.custom,
-      message: `fieldTypeCd '${v.fieldTypeCd}' is not a valid field type.${hint} (See dforge://reference/field-types.)`
-    });
-  }
-  if (typeof v.columnType === "string" && v.columnType.length > 0 && !getColumnType(v.columnType)) {
-    ctx.addIssue({
-      code: external_exports.ZodIssueCode.custom,
-      message: `columnType '${v.columnType}' is invalid. Use 'R' (reference), 'S' (set/child list), or 'F' (formula) \u2014 or omit it for a plain data column. (A/L/G exist for register columns.)`
+      message: issue2.message.replace(/^field: /, "")
     });
   }
 }).describe(
@@ -32935,9 +33288,324 @@ function entityFieldModify(args) {
   );
 }
 
+// src/tools/entity-compose.ts
+var path7 = __toESM(require("path"));
+function loadEntity(moduleDir, entityName) {
+  const { paths, manifest } = loadManifest(moduleDir);
+  const entityPath = path7.join(paths.entitiesDir, `${entityName}.json`);
+  try {
+    const entity = readJson(entityPath);
+    return { paths, manifest, entity, entityPath };
+  } catch {
+    throw new Error(
+      `Entity '${entityName}' not found at entities/${entityName}.json. Existing entities: ${Object.keys(manifest.entities ?? {}).join(", ") || "(none)"}.`
+    );
+  }
+}
+var fieldsOf = (entity) => entity.fields ?? {};
+function nextOrderNum(fields) {
+  let max = 0;
+  for (const f of Object.values(fields)) {
+    const n = typeof f?.orderNum === "number" ? f.orderNum : 0;
+    if (n > max) max = n;
+  }
+  return Math.ceil((max + 10) / 10) * 10;
+}
+var pkOf = (entityCode) => `${entityCode.split(".").pop()}_id`;
+var pascal = (s) => s.split(/[._]/).filter(Boolean).map((p) => p[0].toUpperCase() + p.slice(1)).join("");
+var entityReferenceAddSchema = {
+  moduleDir: external_exports.string().describe("Path to the module root."),
+  entity: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("The CHILD entity \u2014 the one that gets the FK columns."),
+  targetEntity: external_exports.string().regex(/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/).describe(
+    "The PARENT entity being pointed at. Cross-module dotted form ('fin.invoice') is allowed when it's a declared dependency."
+  ),
+  name: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe(
+    "Name of the VISIBLE reference column, e.g. 'list' or 'customer'. The hidden FK column is named '<name>_id' unless fkField overrides it."
+  ),
+  fkField: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe("Override the hidden FK column name. Default: '<name>_id'."),
+  label: external_exports.string().optional().describe("Display label for the reference column. Default: derived from name."),
+  required: external_exports.boolean().default(true).describe("true \u2192 flags 'VEM' (required); false \u2192 'VE' (optional). Mirrors the FK's nullability."),
+  targetPk: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe(
+    "The parent's PK column. Default '{targetEntity}_id' (what the identity trait provides). Never 'id'."
+  ),
+  orderNum: external_exports.number().int().optional().describe("Order of the reference column in the UI. Default: appended.")
+};
+function entityReferenceAdd(args) {
+  const { paths, manifest, entity, entityPath } = loadEntity(args.moduleDir, args.entity);
+  const fields = fieldsOf(entity);
+  const fkField = args.fkField ?? `${args.name}_id`;
+  const targetPk = args.targetPk ?? pkOf(args.targetEntity);
+  if (fkField === args.name) {
+    throw new Error(
+      `fkField and name are both '${fkField}' \u2014 an FK+Reference is TWO columns: a hidden FK ('${args.name}_id') plus a visible reference ('${args.name}'). They can't share a name.`
+    );
+  }
+  if (Object.prototype.hasOwnProperty.call(fields, args.name)) {
+    throw new Error(
+      `Column '${args.name}' already exists on '${args.entity}'. Remove it first (dforge_entity_field_remove) or pick a different name.`
+    );
+  }
+  const existingFk = fields[fkField];
+  if (existingFk && typeof existingFk.columnType === "string" && existingFk.columnType !== "D") {
+    throw new Error(
+      `Column '${fkField}' already exists on '${args.entity}' as a '${existingFk.columnType}' column, so it can't serve as the hidden FK. Pass a different fkField.`
+    );
+  }
+  const reusedFk = Boolean(existingFk);
+  const fkFixes = [];
+  if (existingFk) {
+    const flags2 = typeof existingFk.flags === "string" ? existingFk.flags : "";
+    if (existingFk.dbDatatype !== "cuid") {
+      fkFixes.push(
+        `dbDatatype ${existingFk.dbDatatype === void 0 ? "(unset)" : `'${String(existingFk.dbDatatype)}'`} \u2192 'cuid' (the target PK type)`
+      );
+    }
+    if (flags2 !== "EM") {
+      fkFixes.push(`flags '${flags2 || "(unset)"}' \u2192 'EM' (hidden, not user-visible)`);
+    }
+    if (existingFk.fieldTypeCd !== void 0) {
+      fkFixes.push(
+        `dropped fieldTypeCd '${String(existingFk.fieldTypeCd)}' (the hidden FK has no UI control \u2014 the Reference column carries it)`
+      );
+    }
+    if (existingFk.columnType !== void 0) {
+      fkFixes.push(`dropped columnType '${String(existingFk.columnType)}' (a hidden FK is a plain data column)`);
+    }
+  }
+  if (args.targetEntity === args.entity && !args.fkField) {
+    if (fkField === pkOf(args.entity)) {
+      throw new Error(
+        `Derived FK column '${fkField}' collides with '${args.entity}'s own identity PK. Pass an explicit fkField (e.g. 'parent_id').`
+      );
+    }
+  }
+  const label = args.label ?? pascal(args.name).replace(/([a-z])([A-Z])/g, "$1 $2");
+  const flags = args.required ? "VEM" : "VE";
+  const base = args.orderNum ?? nextOrderNum(fields);
+  if (existingFk) {
+    const { fieldTypeCd: _ft, columnType: _ct, ...keep } = existingFk;
+    fields[fkField] = {
+      ...keep,
+      dbDatatype: "cuid",
+      flags: "EM",
+      orderNum: typeof existingFk.orderNum === "number" ? existingFk.orderNum : base,
+      description: typeof existingFk.description === "string" ? existingFk.description : `${label} ID`
+    };
+  } else {
+    fields[fkField] = {
+      dbDatatype: "cuid",
+      flags: "EM",
+      orderNum: base,
+      description: `${label} ID`
+    };
+  }
+  fields[args.name] = {
+    columnType: "R",
+    fieldTypeCd: "lookup",
+    flags,
+    orderNum: base + 5,
+    description: label,
+    link: { entity: args.targetEntity, thisKey: fkField, otherKey: targetPk }
+  };
+  entity.fields = fields;
+  const refs = entity.references ?? {};
+  const refName = `FK_${pascal(args.entity)}_${pascal(args.name)}`;
+  refs[refName] = {
+    from: { field: fkField },
+    to: { entity: args.targetEntity, field: targetPk }
+  };
+  entity.references = refs;
+  const warnings = [];
+  if (fkFixes.length > 0) {
+    warnings.push(
+      `Reused column '${fkField}' was not in the hidden-FK shape and has been normalized: ${fkFixes.join("; ")}. Re-check anything that referenced it as a plain column.`
+    );
+  }
+  if (args.targetEntity.includes(".")) {
+    warnings.push(
+      `'${args.targetEntity}' is cross-module \u2014 make sure '${args.targetEntity.split(".")[0]}' is a declared dependency (dforge_dependency_add).`
+    );
+  }
+  return makeResult(
+    `Added reference '${args.name}' on '${args.entity}' \u2192 '${args.targetEntity}' (${reusedFk ? `reused existing FK '${fkField}'${fkFixes.length ? " (normalized)" : ""}` : `hidden FK '${fkField}'`} + Reference column + references.${refName}, ${args.required ? "required" : "optional"}).`,
+    {
+      [rel(paths.root, entityPath)]: jsonText(entity),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    },
+    warnings.length > 0 ? warnings.join("\n") : void 0
+  );
+}
+var entityRollupAddSchema = {
+  moduleDir: external_exports.string().describe("Path to the module root."),
+  entity: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("The PARENT entity that gets the roll-up total."),
+  name: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Name of the new Generated column, e.g. 'total_amount'."),
+  childEntity: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("The CHILD entity whose rows are aggregated."),
+  childField: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe(
+    "The child column to aggregate. MUST be physical (a plain data column or a same-row Generated one) \u2014 aggregating a virtual F/R/S column fails install."
+  ),
+  agg: external_exports.enum(["SUM", "COUNT", "AVG", "MIN", "MAX"]).default("SUM").describe("Aggregate function."),
+  setField: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe(
+    "Name of the Set column on the parent that lists the child rows. Reused if it already exists; created if not. Default: '<childEntity>s'."
+  ),
+  childFkField: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe(
+    "The FK column on the child pointing back at the parent \u2014 only needed when the Set column has to be created. Default: '{parentEntity}_id'."
+  ),
+  label: external_exports.string().optional().describe("Display label. Default: derived from name."),
+  dbDatatype: external_exports.string().optional().describe("SQL type of the total. Default: copied from the aggregated child column (numeric for AVG, int8 for COUNT)."),
+  orderNum: external_exports.number().int().optional()
+};
+function entityRollupAdd(args) {
+  const { paths, manifest, entity, entityPath } = loadEntity(args.moduleDir, args.entity);
+  const fields = fieldsOf(entity);
+  if (Object.prototype.hasOwnProperty.call(fields, args.name)) {
+    throw new Error(`Column '${args.name}' already exists on '${args.entity}'.`);
+  }
+  const { entity: child } = loadEntity(args.moduleDir, args.childEntity);
+  const childFields = fieldsOf(child);
+  const childCol = childFields[args.childField];
+  if (!childCol) {
+    throw new Error(
+      `'${args.childField}' is not a column on child entity '${args.childEntity}'. Its columns: ${Object.keys(childFields).join(", ") || "(none)"}.`
+    );
+  }
+  const childType = typeof childCol.columnType === "string" ? childCol.columnType : "D";
+  if (childType === "F" || childType === "R" || childType === "S") {
+    throw new Error(
+      `'${args.childEntity}.${args.childField}' is a virtual '${childType}' column. A Generated aggregate reads the child's PHYSICAL column, so install fails with \`column old.${args.childField} does not exist\`. Aggregate a plain data column (or a same-row Generated one) instead. (See dforge://reference/column-types.)`
+    );
+  }
+  const setField = args.setField ?? `${args.childEntity}s`;
+  const existingSet = fields[setField];
+  let createdSet = false;
+  if (existingSet) {
+    if (existingSet.columnType !== "S") {
+      throw new Error(
+        `Column '${setField}' already exists on '${args.entity}' but is not a set column (columnType 'S'). Pass a different setField.`
+      );
+    }
+    const linked = existingSet.link?.entity;
+    if (linked && linked !== args.childEntity) {
+      throw new Error(
+        `Set column '${setField}' on '${args.entity}' points at '${String(linked)}', not '${args.childEntity}'.`
+      );
+    }
+  } else {
+    const childFk = args.childFkField ?? `${args.entity}_id`;
+    if (!childFields[childFk]) {
+      throw new Error(
+        `Can't create the set column '${setField}': the child '${args.childEntity}' has no FK column '${childFk}' pointing back at '${args.entity}'. Add the relation first with dforge_entity_reference_add({ entity: '${args.childEntity}', targetEntity: '${args.entity}', name: '${args.entity}' }), or pass childFkField explicitly.`
+      );
+    }
+    fields[setField] = {
+      columnType: "S",
+      fieldTypeCd: "grid",
+      flags: "VEM",
+      orderNum: nextOrderNum(fields),
+      description: pascal(setField).replace(/([a-z])([A-Z])/g, "$1 $2"),
+      link: { entity: args.childEntity, thisKey: pkOf(args.entity), otherKey: childFk }
+    };
+    createdSet = true;
+  }
+  const label = args.label ?? pascal(args.name).replace(/([a-z])([A-Z])/g, "$1 $2");
+  let dbDatatype = args.dbDatatype;
+  if (!dbDatatype) {
+    if (args.agg === "COUNT") dbDatatype = "int8";
+    else if (args.agg === "AVG") dbDatatype = "numeric(18,4)";
+    else if (typeof childCol.dbDatatype === "string" && childCol.dbDatatype) dbDatatype = childCol.dbDatatype;
+    else if (typeof childCol.fieldTypeCd === "string") {
+      dbDatatype = deriveDbDatatype(childCol.fieldTypeCd, {}) ?? "numeric(18,2)";
+    } else dbDatatype = "numeric(18,2)";
+  }
+  fields[args.name] = {
+    columnType: "G",
+    dbDatatype,
+    flags: "V",
+    orderNum: args.orderNum ?? nextOrderNum(fields),
+    description: label,
+    formula: `${args.agg}([${setField}].[${args.childField}])`
+  };
+  entity.fields = fields;
+  return makeResult(
+    `Added roll-up '${args.name}' on '${args.entity}' = ${args.agg}([${setField}].[${args.childField}]) as a Generated column (${dbDatatype})${createdSet ? `, plus the set column '${setField}'` : ""}.`,
+    {
+      [rel(paths.root, entityPath)]: jsonText(entity),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+var statusOption = external_exports.union([
+  external_exports.string(),
+  external_exports.object({
+    value: external_exports.string(),
+    label: external_exports.string().optional(),
+    color: external_exports.string().optional(),
+    icon: external_exports.string().optional()
+  }).passthrough()
+]);
+var entityStatusAddSchema = {
+  moduleDir: external_exports.string().describe("Path to the module root."),
+  entity: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Entity to add the status column to."),
+  name: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).default("status").describe("Column name. Default 'status'."),
+  options: external_exports.array(statusOption).min(2).describe(
+    "The status values, in workflow order. Either bare strings ('draft') or objects ({ value, label?, color?, icon? }). A single-value status should be a checkbox instead."
+  ),
+  initial: external_exports.string().optional().describe(
+    "The value new records start at \u2014 emitted as a `formula` (entity fields have NO defaultValue key). Must be one of options. Default: the first option."
+  ),
+  label: external_exports.string().optional().describe("Display label. Default: derived from name."),
+  required: external_exports.boolean().default(true).describe("true \u2192 flags 'VEM'; false \u2192 'VE'."),
+  orderNum: external_exports.number().int().optional()
+};
+function entityStatusAdd(args) {
+  const { paths, manifest, entity, entityPath } = loadEntity(args.moduleDir, args.entity);
+  const fields = fieldsOf(entity);
+  if (Object.prototype.hasOwnProperty.call(fields, args.name)) {
+    throw new Error(
+      `Column '${args.name}' already exists on '${args.entity}'. Use dforge_entity_field_modify to change it.`
+    );
+  }
+  const options = args.options.map(
+    (o) => typeof o === "string" ? { value: o, label: o.replace(/[_-]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()) } : { label: o.value.replace(/[_-]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()), ...o }
+  );
+  const values = options.map((o) => o.value);
+  const dupes = values.filter((v, i) => values.indexOf(v) !== i);
+  if (dupes.length > 0) {
+    throw new Error(`Duplicate status value(s): ${[...new Set(dupes)].join(", ")}.`);
+  }
+  const initial = args.initial ?? values[0];
+  if (!values.includes(initial)) {
+    throw new Error(
+      `initial '${initial}' is not one of the declared options (${values.join(", ")}).`
+    );
+  }
+  const label = args.label ?? pascal(args.name).replace(/([a-z])([A-Z])/g, "$1 $2");
+  const maxLen = Math.max(20, ...values.map((v) => v.length));
+  fields[args.name] = {
+    dbDatatype: "varchar",
+    fieldTypeCd: "dropdown",
+    flags: args.required ? "VEM" : "VE",
+    maxLen,
+    orderNum: args.orderNum ?? nextOrderNum(fields),
+    description: label,
+    // Entity fields have no `defaultValue` key — the initial value is a
+    // quoted literal formula.
+    formula: `'${initial}'`,
+    params: { options }
+  };
+  entity.fields = fields;
+  return makeResult(
+    `Added status column '${args.name}' on '${args.entity}' with ${values.length} options (${values.join(" \u2192 ")}), starting at '${initial}'.`,
+    {
+      [rel(paths.root, entityPath)]: jsonText(entity),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    },
+    `Status values are now fixed in the entity. Any action's canExecute: guard must reference one of: ${values.join(", ")}.`
+  );
+}
+
 // src/tools/refactor.ts
 var fs6 = __toESM(require("fs"));
-var path7 = __toESM(require("path"));
+var path8 = __toESM(require("path"));
 var code = external_exports.string().regex(/^[a-z][a-z0-9_]*$/);
 var entityFieldRenameSchema = {
   moduleDir: external_exports.string().describe("Path to the module root."),
@@ -32956,7 +33624,7 @@ function entityFieldRename(args) {
   const { paths, manifest } = loadManifest(args.moduleDir);
   const entityRel = (manifest.entities ?? {})[entityName];
   if (!entityRel) throw new Error(`Entity '${entityName}' is not in the manifest.`);
-  const entityPath = path7.join(paths.root, entityRel.replace(/^\.\//, ""));
+  const entityPath = path8.join(paths.root, entityRel.replace(/^\.\//, ""));
   const entity = readJson(entityPath);
   const fields = entity.fields ?? {};
   if (!(oldName in fields)) throw new Error(`Field '${oldName}' not found on entity '${entityName}'.`);
@@ -32989,7 +33657,7 @@ function entityFieldRename(args) {
   files[rel(paths.root, entityPath)] = jsonText(entity);
   for (const [oname, orel] of Object.entries(manifest.entities ?? {})) {
     if (oname === entityName || oname.includes(".")) continue;
-    const op = path7.join(paths.root, orel.replace(/^\.\//, ""));
+    const op = path8.join(paths.root, orel.replace(/^\.\//, ""));
     if (!fs6.existsSync(op)) continue;
     const oe = readJson(op);
     let touched = false;
@@ -33043,7 +33711,7 @@ function entityFieldRename(args) {
   }
   if (fs6.existsSync(paths.seedDataDir)) {
     for (const file2 of fs6.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json"))) {
-      const fp = path7.join(paths.seedDataDir, file2);
+      const fp = path8.join(paths.seedDataDir, file2);
       let data;
       try {
         data = JSON.parse(fs6.readFileSync(fp, "utf8"));
@@ -33082,7 +33750,7 @@ function entityFieldRemove(args) {
   const { paths, manifest } = loadManifest(args.moduleDir);
   const entityRel = (manifest.entities ?? {})[entityName];
   if (!entityRel) throw new Error(`Entity '${entityName}' is not in the manifest.`);
-  const entityPath = path7.join(paths.root, entityRel.replace(/^\.\//, ""));
+  const entityPath = path8.join(paths.root, entityRel.replace(/^\.\//, ""));
   const entity = readJson(entityPath);
   const fields = entity.fields ?? {};
   if (!(fieldName in fields)) throw new Error(`Field '${fieldName}' not found on entity '${entityName}'.`);
@@ -33147,7 +33815,7 @@ function entityFieldRemove(args) {
   }
   if (fs6.existsSync(paths.seedDataDir)) {
     for (const file2 of fs6.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json"))) {
-      const fp = path7.join(paths.seedDataDir, file2);
+      const fp = path8.join(paths.seedDataDir, file2);
       let data;
       try {
         data = JSON.parse(fs6.readFileSync(fp, "utf8"));
@@ -33174,7 +33842,7 @@ function entityFieldRemove(args) {
   }
   for (const [oname, orel] of Object.entries(manifest.entities ?? {})) {
     if (oname === entityName || oname.includes(".")) continue;
-    const op = path7.join(paths.root, orel.replace(/^\.\//, ""));
+    const op = path8.join(paths.root, orel.replace(/^\.\//, ""));
     if (!fs6.existsSync(op)) continue;
     let oe;
     try {
@@ -33217,7 +33885,7 @@ function entityRename(args) {
   const files = {};
   const deletes = [];
   const changes = [];
-  const oldPath = path7.join(paths.root, entityMap[oldE].replace(/^\.\//, ""));
+  const oldPath = path8.join(paths.root, entityMap[oldE].replace(/^\.\//, ""));
   const entity = readJson(oldPath);
   const usesIdentity = (entity.traits ?? []).includes("identity");
   const oldPk = `${oldE}_id`;
@@ -33226,7 +33894,7 @@ function entityRename(args) {
     entity.dbObject = newE;
     changes.push("entity.dbObject");
   }
-  const newPath = path7.join(paths.root, "entities", `${newE}.json`);
+  const newPath = path8.join(paths.root, "entities", `${newE}.json`);
   files[rel(paths.root, newPath)] = jsonText(entity);
   deletes.push(rel(paths.root, oldPath));
   changes.push(`entity file \u2192 entities/${newE}.json`);
@@ -33234,7 +33902,7 @@ function entityRename(args) {
   manifest.entities[newE] = `./entities/${newE}.json`;
   for (const [oname, orel] of Object.entries(entityMap)) {
     if (oname === oldE || oname.includes(".")) continue;
-    const op = path7.join(paths.root, orel.replace(/^\.\//, ""));
+    const op = path8.join(paths.root, orel.replace(/^\.\//, ""));
     if (!fs6.existsSync(op)) continue;
     const oe = readJson(op);
     let touched = false;
@@ -33303,7 +33971,7 @@ function entityRename(args) {
   }
   const folders = readJsonOrDefault(paths.folders, {});
   let foldersTouched = false;
-  const walkFolders = (node) => {
+  const walkFolders2 = (node) => {
     if (!node || typeof node !== "object") return;
     const rec = node;
     const ents = rec.entities;
@@ -33312,16 +33980,16 @@ function entityRename(args) {
       foldersTouched = true;
     }
     const children = rec.children;
-    if (children) for (const c of Object.values(children)) walkFolders(c);
+    if (children) for (const c of Object.values(children)) walkFolders2(c);
   };
-  walkFolders(folders);
+  walkFolders2(folders);
   if (foldersTouched) {
     files[rel(paths.root, paths.folders)] = jsonText(folders);
     changes.push("folders.json (entity bindings)");
   }
   if (fs6.existsSync(paths.seedDataDir)) {
     for (const file2 of fs6.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json"))) {
-      const fp = path7.join(paths.seedDataDir, file2);
+      const fp = path8.join(paths.seedDataDir, file2);
       let data;
       try {
         data = JSON.parse(fs6.readFileSync(fp, "utf8"));
@@ -33358,7 +34026,7 @@ function entityDelete(args) {
   const deletes = [];
   const changes = [];
   const warnings = [];
-  const ePath = path7.join(paths.root, entityMap[target].replace(/^\.\//, ""));
+  const ePath = path8.join(paths.root, entityMap[target].replace(/^\.\//, ""));
   if (fs6.existsSync(ePath)) deletes.push(rel(paths.root, ePath));
   const { [target]: _dropped, ...restEntities } = entityMap;
   void _dropped;
@@ -33366,7 +34034,7 @@ function entityDelete(args) {
   changes.push("manifest.entities entry");
   for (const [oname, orel] of Object.entries(entityMap)) {
     if (oname === target || oname.includes(".")) continue;
-    const op = path7.join(paths.root, orel.replace(/^\.\//, ""));
+    const op = path8.join(paths.root, orel.replace(/^\.\//, ""));
     if (!fs6.existsSync(op)) continue;
     let oe;
     try {
@@ -33396,7 +34064,7 @@ function entityDelete(args) {
   }
   const folders = readJsonOrDefault(paths.folders, {});
   let foldersTouched = false;
-  const walkFolders = (node) => {
+  const walkFolders2 = (node) => {
     if (!node || typeof node !== "object") return;
     const rec = node;
     const ents = rec.entities;
@@ -33405,9 +34073,9 @@ function entityDelete(args) {
       foldersTouched = true;
     }
     const children = rec.children;
-    if (children) for (const c of Object.values(children)) walkFolders(c);
+    if (children) for (const c of Object.values(children)) walkFolders2(c);
   };
-  walkFolders(folders);
+  walkFolders2(folders);
   if (foldersTouched) {
     files[rel(paths.root, paths.folders)] = jsonText(folders);
     changes.push("folders.json (binding)");
@@ -33443,7 +34111,7 @@ function entityDelete(args) {
   }
   if (fs6.existsSync(paths.seedDataDir)) {
     for (const file2 of fs6.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json"))) {
-      const fp = path7.join(paths.seedDataDir, file2);
+      const fp = path8.join(paths.seedDataDir, file2);
       let data;
       try {
         data = JSON.parse(fs6.readFileSync(fp, "utf8"));
@@ -33470,7 +34138,294 @@ function entityDelete(args) {
 }
 
 // src/tools/action-add.ts
-var path8 = __toESM(require("path"));
+var path9 = __toESM(require("path"));
+
+// src/tools/dsl-check.ts
+var BLOCKS = ["params", "canExecute", "onBeforeStart", "execute"];
+var DSL_BUILTINS = /* @__PURE__ */ new Set([
+  "addDays",
+  "addSeconds",
+  "callApi",
+  "callProc",
+  "callService",
+  "delete",
+  "detectDocument",
+  "download",
+  "entityLink",
+  "error",
+  "exit",
+  "flush",
+  "getFileInfo",
+  "getFileUrl",
+  "getRecord",
+  "getRecordOrNull",
+  "getSecret",
+  "getSetting",
+  "info",
+  "insert",
+  "nextNumber",
+  "notify",
+  "now",
+  "ocrExtract",
+  "preloadRef",
+  "query",
+  "select",
+  "sendEmail",
+  "tryParseJson",
+  "update",
+  "warn"
+]);
+var JS_RESERVED = /* @__PURE__ */ new Set([
+  "if",
+  "for",
+  "while",
+  "switch",
+  "catch",
+  "return",
+  "typeof",
+  "function",
+  "do",
+  "else",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "throw",
+  "try",
+  "parseInt",
+  "parseFloat",
+  "isNaN",
+  "isFinite",
+  "String",
+  "Number",
+  "Boolean",
+  "Array",
+  "Object",
+  "Date",
+  "Math",
+  "JSON",
+  "RegExp",
+  "Error"
+]);
+var FORMULA_ONLY = ["TODAY", "NOW"];
+function blank(src) {
+  let out = "";
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "'" || c === '"') {
+      const quote = c;
+      out += " ";
+      i++;
+      while (i < src.length && src[i] !== quote) {
+        if (src[i] === "\\") {
+          out += "  ";
+          i += 2;
+          continue;
+        }
+        out += src[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      if (i < src.length) {
+        out += " ";
+        i++;
+      }
+      continue;
+    }
+    if (c === "#" || c === "/" && src[i + 1] === "/") {
+      while (i < src.length && src[i] !== "\n") {
+        out += " ";
+        i++;
+      }
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+var lineOf = (src, index) => src.slice(0, index).split("\n").length;
+function readStringLiteral(src, start) {
+  const quote = src[start];
+  if (quote !== "'" && quote !== '"') return null;
+  let value = "";
+  let i = start + 1;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "\\") {
+      if (i + 1 < src.length) value += src[i + 1];
+      i += 2;
+      continue;
+    }
+    if (c === quote) return { value, end: i + 1 };
+    value += c;
+    i++;
+  }
+  return null;
+}
+function sqlLiterals(src) {
+  const out = [];
+  const callRe = /\b(query|callProc)\s*\(\s*/g;
+  for (const m of src.matchAll(callRe)) {
+    const argStart = (m.index ?? 0) + m[0].length;
+    const lit = readStringLiteral(src, argStart);
+    if (!lit) continue;
+    out.push({ sql: lit.value, index: m.index ?? 0, end: lit.end });
+  }
+  return out;
+}
+function parseBlocks(src) {
+  const lines = src.split("\n");
+  const found = [];
+  let offset = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^([A-Za-z][A-Za-z0-9_]*)\s*:\s*$/);
+    if (m) found.push({ block: m[1], start: offset + m[0].length, end: src.length, line: i + 1 });
+    offset += lines[i].length + 1;
+  }
+  for (let i = 0; i < found.length - 1; i++) {
+    found[i].end = src.lastIndexOf("\n", found[i + 1].start - found[i + 1].block.length - 2) + 1;
+  }
+  return found;
+}
+function checkDsl(src, opts = {}) {
+  const issues = [];
+  const add = (level, rule, message, line) => issues.push({ level, rule, message, ...line ? { line } : {} });
+  const code2 = blank(src);
+  const blocks = parseBlocks(src);
+  const names = blocks.map((b) => b.block);
+  if (src.trim() === "") {
+    add("error", "dsl-empty", "DSL body is empty \u2014 at minimum it needs an `execute:` block.");
+    return issues;
+  }
+  if (!names.includes("execute")) {
+    add(
+      "error",
+      "missing-execute",
+      "no `execute:` block \u2014 it is the only required block in a .dsl file."
+    );
+  }
+  for (const b of blocks) {
+    if (!BLOCKS.includes(b.block)) {
+      add(
+        "warning",
+        "unknown-block",
+        `'${b.block}:' is not a DSL block marker \u2014 expected one of ${BLOCKS.join(", ")}. (A stray label at column 0 is parsed as a block.)`,
+        b.line
+      );
+    }
+  }
+  const known = names.filter((n) => BLOCKS.includes(n));
+  const order = known.map((n) => BLOCKS.indexOf(n));
+  for (let i = 1; i < order.length; i++) {
+    if (order[i] < order[i - 1]) {
+      add(
+        "error",
+        "block-order",
+        `blocks must appear in the order ${BLOCKS.join(" \u2192 ")}; found '${known[i - 1]}:' before '${known[i]}:'.`
+      );
+      break;
+    }
+  }
+  for (const b of BLOCKS) {
+    if (known.filter((n) => n === b).length > 1) {
+      add("error", "duplicate-block", `'${b}:' is declared more than once.`);
+    }
+  }
+  const execBlock = blocks.find((b) => b.block === "execute");
+  const execCode = execBlock ? code2.slice(execBlock.start, execBlock.end) : "";
+  const execOffset = execBlock ? execBlock.start : 0;
+  if (execBlock) {
+    for (const fn of FORMULA_ONLY) {
+      const re = new RegExp(`\\b${fn}\\s*\\(\\s*\\)`, "g");
+      for (const m of execCode.matchAll(re)) {
+        add(
+          "error",
+          "execute-formula-date",
+          `the execute: block calls ${fn}(), which is undefined at runtime \u2014 install fails with "'${fn}' is not defined". Use lowercase now() in execute:. ${fn}() is formula-only (canExecute:, formula columns).`,
+          lineOf(src, execOffset + (m.index ?? 0))
+        );
+      }
+    }
+  }
+  const recordRefs = [...code2.matchAll(/(?<![\w\]$])\[([a-z][a-z0-9_]*)\]/g)];
+  const mode = (opts.executionMode ?? "").toLowerCase();
+  if (opts.viaJob && recordRefs.length > 0) {
+    const first = recordRefs[0];
+    add(
+      "error",
+      "job-record-context",
+      `uses record-context syntax [${first[1]}] but is invoked by a scheduled job \u2014 jobs run as the system user with NO current record, so [field] is a hard error. Fetch rows with select() (or query()) inside the job action instead.`,
+      lineOf(src, first.index ?? 0)
+    );
+  }
+  if (mode === "batch" && execBlock) {
+    const inExec = recordRefs.filter(
+      (m) => (m.index ?? 0) >= execBlock.start && (m.index ?? 0) < execBlock.end
+    );
+    if (inExec.length > 0) {
+      add(
+        "error",
+        "batch-record-context",
+        `executionMode is 'batch' but execute: uses record-context [${inExec[0][1]}] \u2014 in batch mode there is no current record. Iterate the selection instead: \`for rec in records { rec[field] }\`.`,
+        lineOf(src, inExec[0].index ?? 0)
+      );
+    }
+  }
+  for (const { sql, index, end } of sqlLiterals(src)) {
+    const bad = sql.match(/(?<![:\w]):([a-z][a-z0-9_]*)/i);
+    if (bad) {
+      add(
+        "error",
+        "sql-placeholder",
+        `SQL uses ':${bad[1]}' as a placeholder \u2014 dForge binds '@${bad[1]}'. Rewrite as '@${bad[1]}' and pass { ${bad[1]}: value } as the params argument.`,
+        lineOf(src, index)
+      );
+    }
+    const after = src.slice(end, end + 40);
+    if (/^\s*\+/.test(after)) {
+      add(
+        "warning",
+        "sql-concat",
+        "SQL string looks concatenated \u2014 build queries with @placeholders + a params object, never by string concatenation.",
+        lineOf(src, index)
+      );
+    }
+  }
+  if (execBlock) {
+    const declaresFunction = /\bfunction\b/.test(execCode);
+    const returnRe = declaresFunction ? /^[ \t]{0,8}return\b/gm : /\breturn\b/g;
+    for (const m of execCode.matchAll(returnRe)) {
+      add(
+        "error",
+        "top-level-return",
+        "top-level `return` is invalid in a DSL body. Use exit('msg', 'info') to stop and commit, or error('msg') to stop and roll back.",
+        lineOf(src, execOffset + (m.index ?? 0))
+      );
+    }
+  }
+  const local = /* @__PURE__ */ new Set();
+  for (const m of code2.matchAll(/\bfunction\s+([A-Za-z_$][\w$]*)/g)) local.add(m[1]);
+  for (const m of code2.matchAll(/\bvar\s+([A-Za-z_$][\w$]*)/g)) local.add(m[1]);
+  const reported = /* @__PURE__ */ new Set();
+  for (const m of code2.matchAll(/(?<![.\w$])([A-Za-z_$][\w$]*)\s*\(/g)) {
+    const fn = m[1];
+    if (DSL_BUILTINS.has(fn) || JS_RESERVED.has(fn) || local.has(fn) || reported.has(fn) || FORMULA_ONLY.includes(fn)) {
+      continue;
+    }
+    reported.add(fn);
+    add(
+      "warning",
+      "unknown-builtin",
+      `calls '${fn}()', which is not a DSL host function or a locally declared one. Check the name against dforge://docs/dsl (Built-in functions).`,
+      lineOf(src, m.index ?? 0)
+    );
+  }
+  return issues;
+}
+
+// src/tools/action-add.ts
 var actionAddSchema = {
   moduleDir: external_exports.string(),
   code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Action code (becomes the DSL filename and registry key)."),
@@ -33490,18 +34445,16 @@ var actionAddSchema = {
     "Full DSL source. Should contain `params:`, optional `canExecute:`, optional `onBeforeStart:` (async only), and required `execute:` blocks."
   )
 };
-function assertNoFormulaDateInExecute(dslBody, code2) {
-  const m = dslBody.match(/(^|\n)[ \t]*execute:/);
-  if (!m) return;
-  const execPart = dslBody.slice((m.index ?? 0) + m[0].length);
-  if (/\bTODAY\s*\(\s*\)/.test(execPart)) {
+function actionAdd(args) {
+  const dslIssues = checkDsl(args.dslBody, { executionMode: args.executionMode });
+  const dslErrors = dslIssues.filter((i) => i.level === "error");
+  if (dslErrors.length > 0) {
     throw new Error(
-      `Action '${code2}': the execute: block calls TODAY(), which is undefined at runtime \u2014 install fails with "'TODAY' is not defined". Use lowercase now() in execute:. TODAY()/NOW() are formula-only (canExecute:, formula columns).`
+      `Action '${args.code}' has ${dslErrors.length} DSL error(s):
+` + dslErrors.map((i) => `  \u2022 ${i.line ? `line ${i.line}: ` : ""}${i.message}`).join("\n") + "\n\nFix the DSL body and call again. (Load dforge://docs/dsl for the full grammar.)"
     );
   }
-}
-function actionAdd(args) {
-  assertNoFormulaDateInExecute(args.dslBody, args.code);
+  const dslWarnings = dslIssues.filter((i) => i.level === "warning");
   const { paths, manifest } = loadManifest(args.moduleDir);
   const actionsJson = readJsonOrDefault(paths.actions, {});
   if (Object.prototype.hasOwnProperty.call(actionsJson, args.code)) {
@@ -33521,7 +34474,7 @@ function actionAdd(args) {
     actionEntry.icon = args.icon.startsWith("bi-") ? args.icon : `bi-${args.icon}`;
   }
   actionsJson[args.code] = actionEntry;
-  const dslPath = path8.join(paths.logicDir, "actions", `${args.code}.dsl`);
+  const dslPath = path9.join(paths.logicDir, "actions", `${args.code}.dsl`);
   const dslBody = args.dslBody.endsWith("\n") ? args.dslBody : args.dslBody + "\n";
   return makeResult(
     `Added action '${args.code}' targeting entity '${args.entityCode}' (executionMode=${args.executionMode}${args.isAsync ? ", async" : ""}).`,
@@ -33529,10 +34482,82 @@ function actionAdd(args) {
       [rel(paths.root, paths.actions)]: jsonText(actionsJson),
       [rel(paths.root, dslPath)]: dslBody,
       "manifest.json": jsonText(withTodayStamp(manifest))
-    }
+    },
+    dslWarnings.length > 0 ? `DSL warnings (not blocking):
+${dslWarnings.map((i) => `  \u2022 ${i.line ? `line ${i.line}: ` : ""}${i.message}`).join("\n")}` : void 0
   );
 }
 
+// src/tools/action-check.ts
+var fs7 = __toESM(require("fs"));
+var path10 = __toESM(require("path"));
+var actionCheckSchema = {
+  moduleDir: external_exports.string().optional().describe(
+    "Module root. Required when checking an on-disk action (actionCode); optional when checking a raw dslBody."
+  ),
+  actionCode: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe(
+    "Check an action already registered in ui/actions.json \u2014 its DSL file, executionMode, and any job binding are read from disk. Omit to check a raw dslBody instead."
+  ),
+  dslBody: external_exports.string().optional().describe("Raw DSL source to check. Use this to validate a draft BEFORE calling dforge_action_add."),
+  executionMode: external_exports.enum(["single", "each", "batch"]).optional().describe(
+    "Execution mode the body will run under. Gates the record-context rules ('[field]' is invalid in batch mode). Read from ui/actions.json when actionCode is used."
+  ),
+  viaJob: external_exports.boolean().optional().describe(
+    "True when a scheduled job will fire this action \u2014 jobs have NO current record, so '[field]' becomes a hard error. Detected automatically from logic/jobs.json when actionCode is used."
+  )
+};
+function actionCheck(args) {
+  let body = args.dslBody;
+  let mode = args.executionMode;
+  let viaJob = args.viaJob ?? false;
+  let label = "draft DSL body";
+  if (args.actionCode) {
+    if (!args.moduleDir) {
+      throw new Error("moduleDir is required when checking an on-disk action (actionCode).");
+    }
+    const { paths } = loadManifest(args.moduleDir);
+    const actions = readJsonOrDefault(paths.actions, {});
+    const entry = actions[args.actionCode];
+    if (!entry) {
+      throw new Error(
+        `Action '${args.actionCode}' is not in ui/actions.json. Registered actions: ${Object.keys(actions).join(", ") || "(none)"}.`
+      );
+    }
+    const script = entry.script ?? args.actionCode;
+    const dslPath = path10.join(paths.logicDir, "actions", `${script}.dsl`);
+    if (!fs7.existsSync(dslPath)) {
+      throw new Error(
+        `Action '${args.actionCode}' declares script '${script}' but logic/actions/${script}.dsl does not exist.`
+      );
+    }
+    body = fs7.readFileSync(dslPath, "utf8");
+    mode = mode ?? (entry.executionMode ?? entry.mode);
+    label = `logic/actions/${script}.dsl`;
+    if (args.viaJob === void 0) {
+      const jobFile = readJsonOrDefault(paths.jobs, {});
+      viaJob = (jobFile.jobs ?? []).some((j) => j.action === args.actionCode);
+    }
+  }
+  if (body === void 0) {
+    throw new Error("Pass either dslBody (a draft) or actionCode (an action already on disk).");
+  }
+  const issues = checkDsl(body, { executionMode: mode, viaJob });
+  const errors = issues.filter((i) => i.level === "error");
+  const warnings = issues.filter((i) => i.level === "warning");
+  const summary = errors.length === 0 && warnings.length === 0 ? `\u2713 ${label}: no DSL issues${mode ? ` (executionMode '${mode}'${viaJob ? ", job-invoked" : ""})` : ""}.` : `${label}: ${errors.length} error(s), ${warnings.length} warning(s).${errors.length ? ` First: ${errors[0].message}` : ""}`;
+  return {
+    summary,
+    files: {
+      "_action_check.json": JSON.stringify(
+        { ok: errors.length === 0, executionMode: mode ?? null, viaJob, errors, warnings },
+        null,
+        "	"
+      ) + "\n"
+    },
+    warning: errors.length ? `${errors.length} DSL error(s) \u2014 each is a documented install failure. Fix before dforge_action_add / dforge_module_pack.` : void 0
+  };
+}
+
 // src/tools/view.ts
 var dataSourceSchema = external_exports.object({
   entityCode: external_exports.string(),
@@ -33608,6 +34633,431 @@ function viewModify(args) {
   });
 }
 
+// src/tools/menu.ts
+var menuAddSchema = {
+  moduleDir: external_exports.string().describe("Path to the module root."),
+  menu: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Root menu key in ui/menus.json, e.g. 'crm_menu'. Created if it doesn't exist yet."),
+  menuLabel: external_exports.string().optional().describe("Label for the root menu \u2014 only used when the root is being created."),
+  parentPath: external_exports.string().default("").describe(
+    "Slash-separated item codes under the root, e.g. 'lists/archive'. Empty = add directly under the root menu."
+  ),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Code of the new item (its key under the parent's items/children)."),
+  label: external_exports.string().min(1).describe("Display label."),
+  dataViewCode: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe(
+    "For a LEAF item: the view code from ui/data_views.json this item opens. Omit to create a SECTION node (a container for children). Note the key is dataViewCode, never viewCode."
+  ),
+  icon: external_exports.string().optional().describe(
+    "Bootstrap icon name. A leading 'bi-' is STRIPPED \u2014 menu icons are bare names ('list-ul'), unlike action icons which keep the prefix."
+  ),
+  orderNum: external_exports.number().int().optional().describe("Sort position among siblings. Default: appended after the current highest.")
+};
+function childKey(node, isRoot) {
+  if (isRoot) return "items";
+  return Object.prototype.hasOwnProperty.call(node, "items") ? "items" : "children";
+}
+function nextOrder(children) {
+  let max = 0;
+  for (const c of Object.values(children)) {
+    const n = typeof c?.orderNum === "number" ? c.orderNum : 0;
+    if (n > max) max = n;
+  }
+  return max + 1;
+}
+function menuAdd(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const menus = readJsonOrDefault(paths.menus, {});
+  if (args.dataViewCode) {
+    const views = readJsonOrDefault(paths.dataViews, {});
+    if (!Object.prototype.hasOwnProperty.call(views, args.dataViewCode)) {
+      throw new Error(
+        `dataViewCode '${args.dataViewCode}' has no matching view in ui/data_views.json. Existing views: ${Object.keys(views).join(", ") || "(none)"}. Add the view first with dforge_view_add.`
+      );
+    }
+  }
+  let root = menus[args.menu];
+  if (!root) {
+    root = { label: args.menuLabel ?? manifest.displayName, items: {} };
+    menus[args.menu] = root;
+  }
+  let cursor = root;
+  let isRoot = true;
+  const segments = args.parentPath.split("/").filter(Boolean);
+  const walked = [];
+  for (const seg of segments) {
+    const key2 = childKey(cursor, isRoot);
+    const children2 = cursor[key2] ?? {};
+    if (!children2[seg]) {
+      throw new Error(
+        `Menu path segment '${seg}' not found under '${walked.join("/") || args.menu}'. Available: ${Object.keys(children2).join(", ") || "(none)"}.`
+      );
+    }
+    cursor = children2[seg];
+    walked.push(seg);
+    isRoot = false;
+  }
+  if (!isRoot && cursor.dataViewCode) {
+    throw new Error(
+      `'${walked.join("/")}' is a leaf item (it has a dataViewCode) \u2014 it can't contain children. Nest under a section node instead (a node with no dataViewCode).`
+    );
+  }
+  const key = childKey(cursor, isRoot);
+  const children = cursor[key] ?? {};
+  if (children[args.code]) {
+    throw new Error(
+      `Menu item '${args.code}' already exists under '${walked.join("/") || args.menu}'.`
+    );
+  }
+  const node = { label: args.label, orderNum: args.orderNum ?? nextOrder(children) };
+  if (args.icon) {
+    node.icon = args.icon.replace(/^bi-/, "");
+  }
+  if (args.dataViewCode) {
+    node.itemType = "V";
+    node.dataViewCode = args.dataViewCode;
+  } else {
+    node.children = {};
+  }
+  children[args.code] = node;
+  cursor[key] = children;
+  const kind = args.dataViewCode ? `leaf \u2192 view '${args.dataViewCode}'` : "section";
+  return makeResult(
+    `Added menu ${kind} '${args.code}' under '${args.menu}${walked.length ? "/" + walked.join("/") : ""}'.`,
+    {
+      [rel(paths.root, paths.menus)]: jsonText(menus),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+
+// src/tools/translations.ts
+var fs8 = __toESM(require("fs"));
+var path11 = __toESM(require("path"));
+function titleize(code2) {
+  return code2.split(/[_-]/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+}
+function str(obj, key) {
+  const v = obj?.[key];
+  return typeof v === "string" && v.trim() !== "" ? v : void 0;
+}
+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."
+  ),
+  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."
+  )
+};
+function buildSkeleton(moduleDir) {
+  const { paths, manifest } = loadManifest(moduleDir);
+  const entries = [];
+  const counts = {};
+  const push = (section, pathParts, english, required2 = false) => {
+    entries.push({ pathParts, english, required: required2 });
+    counts[section] = (counts[section] ?? 0) + 1;
+  };
+  for (const [name, relPath] of Object.entries(manifest.entities ?? {})) {
+    if (name.includes(".")) continue;
+    const abs = path11.join(paths.root, relPath.replace(/^\.\//, ""));
+    if (!fs8.existsSync(abs)) {
+      throw new Error(
+        `manifest.entities.${name} points at '${relPath}', which does not exist on disk. Fix the manifest or restore the file \u2014 syncing now would silently omit that entity's translation keys and the gap would only surface at install.`
+      );
+    }
+    let e;
+    try {
+      e = JSON.parse(fs8.readFileSync(abs, "utf8"));
+    } catch (ex) {
+      throw new Error(`${relPath} is not valid JSON: ${ex.message}`);
+    }
+    push("entities", ["entities", name, "label"], str(e, "description") ?? titleize(name));
+    const authored = e.fields ?? {};
+    const traitCodes = e.traits ?? [];
+    assertKnownTraits(traitCodes, name);
+    const traitFields = expandTraits(traitCodes, name);
+    const all = { ...traitFields, ...authored };
+    for (const [fname, f] of Object.entries(all)) {
+      push(
+        "fields",
+        ["entities", name, "fields", fname, "label"],
+        str(f, "description") ?? str(f, "label") ?? titleize(fname)
+      );
+    }
+  }
+  const views = readJsonOrDefault(paths.dataViews, {});
+  for (const [code2, v] of Object.entries(views)) {
+    push("views", ["views", code2, "label"], str(v, "label") ?? titleize(code2));
+  }
+  const menus = readJsonOrDefault(paths.menus, {});
+  const walkMenu = (node, trail) => {
+    const children = node.items ?? node.children ?? {};
+    for (const [code2, child] of Object.entries(children)) {
+      const next = [...trail, "items", code2];
+      push("menus", [...next, "label"], str(child, "label") ?? titleize(code2));
+      walkMenu(child, next);
+    }
+  };
+  for (const [code2, m] of Object.entries(menus)) {
+    push("menus", ["menus", code2, "label"], str(m, "label") ?? titleize(code2));
+    walkMenu(m, ["menus", code2]);
+  }
+  const roles = readJsonOrDefault(paths.roles, {});
+  for (const [code2, r] of Object.entries(roles)) {
+    push(
+      "roles",
+      ["roles", code2, "label"],
+      str(r, "description") ?? titleize(code2.split(".").pop() ?? code2),
+      true
+    );
+  }
+  const actions = readJsonOrDefault(paths.actions, {});
+  for (const [code2, a] of Object.entries(actions)) {
+    push("actions", ["actions", code2, "label"], str(a, "label") ?? titleize(code2));
+  }
+  const folders = readJsonOrDefault(paths.folders, {});
+  if (Object.keys(folders).length > 0) {
+    const dupes = duplicateFolderCodes(folders);
+    if (dupes.size > 0) {
+      const detail = [...dupes].map(([code2, paths_]) => `'${code2}' (${paths_.join(", ")})`).join("; ");
+      throw new Error(
+        `ui/folders.json reuses folder code(s) across branches: ${detail}. Translation keys are flat (\`folders.<code>.label\`), so duplicates would overwrite each other \u2014 and role rights (\`folder:<code>\`) can't tell them apart either. Rename them to unique codes, then re-run.`
+      );
+    }
+    push("folders", ["folders", manifest.code, "label"], str(folders, "label") ?? titleize(manifest.code));
+    for (const f of walkFolders(folders)) {
+      push("folders", ["folders", f.code, "label"], str(f.node, "label") ?? titleize(f.code));
+    }
+  }
+  const settings = readJsonOrDefault(paths.settings, {});
+  for (const [code2, s] of Object.entries(settings)) {
+    push("settings", ["settings", code2, "label"], str(s, "label") ?? titleize(code2));
+  }
+  return { entries, counts };
+}
+var getIn = (root, parts) => parts.reduce((acc, p) => acc && typeof acc === "object" ? acc[p] : void 0, root);
+function setIn(root, parts, value) {
+  let cursor = root;
+  for (const p of parts.slice(0, -1)) {
+    if (!cursor[p] || typeof cursor[p] !== "object") cursor[p] = {};
+    cursor = cursor[p];
+  }
+  cursor[parts[parts.length - 1]] = value;
+}
+function pruneTo(existing, keep, trail = []) {
+  const out = {};
+  for (const [k, v] of Object.entries(existing)) {
+    const parts = [...trail, k];
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      const sub = pruneTo(v, keep, parts);
+      if (Object.keys(sub).length > 0) out[k] = sub;
+      continue;
+    }
+    if (keep.has(compositeKey(...parts))) out[k] = v;
+  }
+  return out;
+}
+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];
+  if (locales.length === 0) {
+    throw new Error("No locales to sync. Pass `locales`, or declare them in manifest.supportedLocales.");
+  }
+  const { entries, counts } = buildSkeleton(args.moduleDir);
+  if (entries.length === 0) {
+    throw new Error(
+      "Nothing translatable found \u2014 the module has no entities, views, menus, or roles yet. Author them first."
+    );
+  }
+  const keep = new Set(entries.map((e) => compositeKey(...e.pathParts)));
+  const files = {};
+  const report = [];
+  let totalAdded = 0;
+  let missingRequired = 0;
+  for (const locale of locales) {
+    const abs = path11.join(paths.translationsDir, `${locale}.json`);
+    let existing = {};
+    if (fs8.existsSync(abs)) {
+      try {
+        existing = JSON.parse(fs8.readFileSync(abs, "utf8"));
+      } catch (e) {
+        throw new Error(`translations/${locale}.json is not valid JSON: ${e.message}`);
+      }
+    }
+    const next = args.prune ? pruneTo(existing, keep) : JSON.parse(JSON.stringify(existing));
+    let added = 0;
+    for (const entry of entries) {
+      const current = getIn(next, entry.pathParts);
+      if (typeof current === "string" && current.trim() !== "") continue;
+      setIn(next, entry.pathParts, entry.english);
+      added++;
+      if (entry.required) missingRequired++;
+    }
+    files[rel(paths.root, abs)] = jsonText(next);
+    totalAdded += added;
+    report.push(`${locale}: +${added} key(s)${added === 0 ? " (already complete)" : ""}`);
+  }
+  const isEnglish = (l) => l.toLowerCase() === "en" || l.toLowerCase().startsWith("en-");
+  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 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).` : ""}`,
+    files,
+    warning
+  );
+}
+
+// src/tools/seed.ts
+var fs9 = __toESM(require("fs"));
+var path12 = __toESM(require("path"));
+var SYSTEM_USER = 0;
+var seedAddSchema = {
+  moduleDir: external_exports.string().describe("Path to the module root."),
+  entity: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Entity these records belong to."),
+  records: external_exports.array(external_exports.record(external_exports.string(), external_exports.unknown())).min(1).describe(
+    "The rows. Each MUST carry an explicit numeric PK under '{entity}_id' (cuid is int8, not a UUID). FK values must match a PK of an already-seeded parent."
+  ),
+  order: external_exports.number().int().min(1).max(99).optional().describe(
+    "Load order \u2014 becomes the filename prefix (seed-data/NN-<entity>.json). Parents need a LOWER number than their children. Default: next free slot."
+  ),
+  fileName: external_exports.string().optional().describe("Override the generated filename (without directory). Rarely needed.")
+};
+function seedAdd(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const entityPath = path12.join(paths.entitiesDir, `${args.entity}.json`);
+  if (!fs9.existsSync(entityPath)) {
+    throw new Error(
+      `Entity '${args.entity}' not found at entities/${args.entity}.json. Existing entities: ${Object.keys(manifest.entities ?? {}).join(", ") || "(none)"}.`
+    );
+  }
+  const entity = readJson(entityPath);
+  const fields = entity.fields ?? {};
+  const traits2 = entity.traits ?? [];
+  const pk = `${args.entity}_id`;
+  const warnings = [];
+  const seenPks = /* @__PURE__ */ new Set();
+  args.records.forEach((r, i) => {
+    if (!Object.prototype.hasOwnProperty.call(r, pk)) {
+      const wrong = ["id", "ID", `${args.entity}Id`].find(
+        (k) => Object.prototype.hasOwnProperty.call(r, k)
+      );
+      throw new Error(
+        `Record ${i} has no '${pk}'${wrong ? ` (found '${wrong}' instead)` : ""}. Seed records need an explicit numeric PK under '{entity}_id' \u2014 the identity trait names it '${pk}', never 'id'.`
+      );
+    }
+    const v = r[pk];
+    if (typeof v !== "number" || !Number.isInteger(v)) {
+      throw new Error(
+        `Record ${i}'s '${pk}' is ${JSON.stringify(v)} \u2014 it must be an INTEGER. The cuid type is int8, not a UUID or string.`
+      );
+    }
+    if (seenPks.has(v)) throw new Error(`Duplicate '${pk}' value ${v} across the seed records.`);
+    seenPks.add(v);
+  });
+  if (traits2.includes("audit-full")) {
+    const missing = args.records.map((r, i) => ({ i, r })).filter(({ r }) => r.created_by === void 0 || r.last_updated_by === void 0).map(({ i }) => i);
+    if (missing.length > 0) {
+      throw new Error(
+        `'${args.entity}' uses the 'audit-full' trait, whose created_by / last_updated_by columns are REQUIRED with no default \u2014 records [${missing.join(", ")}] set neither. Install fails with "required column 'created_by' \u2026 is not present in seed records". Set both to ${SYSTEM_USER} (the System user) on every record, switch the entity to the 'audit' trait, or don't seed it.`
+      );
+    }
+  }
+  assertKnownTraits(traits2, args.entity);
+  const traitFields = expandTraits(traits2, args.entity);
+  const known = /* @__PURE__ */ new Set([...Object.keys(fields), ...Object.keys(traitFields)]);
+  known.add(pk);
+  const unknown2 = /* @__PURE__ */ new Set();
+  for (const r of args.records) {
+    for (const k of Object.keys(r)) if (!known.has(k)) unknown2.add(k);
+  }
+  if (unknown2.size > 0) {
+    const traitCols = Object.keys(traitFields);
+    throw new Error(
+      `Seed records set column(s) not defined on '${args.entity}': ${[...unknown2].join(", ")}. Its columns are: ${Object.keys(fields).join(", ") || "(none authored)"}` + (traitCols.length > 0 ? `, plus these from traits [${traits2.join(", ")}]: ${traitCols.join(", ")}.` : ".")
+    );
+  }
+  for (const [fname, f] of Object.entries(fields)) {
+    if (f?.columnType !== "R") continue;
+    const used = args.records.some((r) => r[fname] !== void 0);
+    if (used) {
+      const thisKey = f.link?.thisKey;
+      throw new Error(
+        `'${fname}' is a Reference column (virtual \u2014 it owns no physical column), so it can't be seeded. Set the hidden FK '${String(thisKey ?? `${fname}_id`)}' to the parent's numeric PK instead.`
+      );
+    }
+  }
+  for (const [fname, f] of Object.entries(fields)) {
+    const flags = typeof f?.flags === "string" ? f.flags : "";
+    const isVirtual = f?.columnType === "R" || f?.columnType === "S" || f?.columnType === "F" || f?.columnType === "G";
+    if (isVirtual || !flags.includes("M") || f?.formula !== void 0) continue;
+    const missing = args.records.map((r, i) => r[fname] === void 0 ? i : -1).filter((i) => i >= 0);
+    if (missing.length > 0) {
+      warnings.push(
+        `required column '${fname}' is unset on record(s) [${missing.join(", ")}] \u2014 install may reject the row.`
+      );
+    }
+  }
+  const seedFiles = fs9.existsSync(paths.seedDataDir) ? fs9.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json")).sort() : [];
+  const seededPks = {};
+  for (const f of seedFiles) {
+    try {
+      const data = JSON.parse(fs9.readFileSync(path12.join(paths.seedDataDir, f), "utf8"));
+      const ec = data?.entityCode;
+      if (typeof ec !== "string" || !Array.isArray(data.records)) continue;
+      const set2 = seededPks[ec] ?? (seededPks[ec] = /* @__PURE__ */ new Set());
+      for (const r of data.records) {
+        const v = r?.[`${ec}_id`];
+        if (typeof v === "number") set2.add(v);
+      }
+    } catch {
+    }
+  }
+  seededPks[args.entity] = seenPks;
+  const refs = entity.references ?? {};
+  for (const r of Object.values(refs)) {
+    const fromField = r?.from?.field;
+    const toEntity = r?.to?.entity;
+    if (!fromField || !toEntity || toEntity.includes(".")) continue;
+    const parentPks = seededPks[toEntity];
+    for (const [i, rec] of args.records.entries()) {
+      const v = rec[fromField];
+      if (v === void 0 || v === null) continue;
+      if (typeof v !== "number") {
+        warnings.push(`record ${i}: FK '${fromField}' is ${JSON.stringify(v)} \u2014 expected a numeric PK.`);
+        continue;
+      }
+      if (!parentPks || !parentPks.has(v)) {
+        warnings.push(
+          `record ${i}: FK '${fromField}' = ${v}, but no seeded '${toEntity}' record has that PK \u2014 seed '${toEntity}' first (with a LOWER order prefix) or the install hits an FK violation.`
+        );
+      }
+    }
+  }
+  let order = args.order;
+  if (order === void 0) {
+    const mine = seedFiles.find((f) => f.replace(/^\d+-/, "") === `${args.entity}.json`);
+    if (mine) {
+      order = parseInt(mine.slice(0, 2), 10);
+    } else {
+      const used = seedFiles.map((f) => parseInt(f.slice(0, 2), 10)).filter((n) => !Number.isNaN(n));
+      order = (used.length ? Math.max(...used) : 0) + 1;
+    }
+  }
+  const fileName = args.fileName ?? `${String(order).padStart(2, "0")}-${args.entity}.json`;
+  const seedPath = path12.join(paths.seedDataDir, fileName);
+  const payload = { entityCode: args.entity, records: args.records };
+  return makeResult(
+    `Seeded ${args.records.length} '${args.entity}' record(s) \u2192 seed-data/${fileName} (load order ${order}).`,
+    {
+      [rel(paths.root, seedPath)]: jsonText(payload),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    },
+    warnings.length > 0 ? `Seed warnings:
+${warnings.map((w) => `  \u2022 ${w}`).join("\n")}` : void 0
+  );
+}
+
 // src/tools/adds.ts
 var reportAddSchema = {
   moduleDir: external_exports.string(),
@@ -33725,10 +35175,13 @@ function folderAdd(args) {
     }
     cursor = children2[seg];
   }
-  const children = cursor.children ?? {};
-  if (children[args.code]) {
-    throw new Error(`Folder '${args.code}' already exists at '${args.parentPath || "(root)"}'.`);
+  const clash = walkFolders(root).find((f) => f.code === args.code);
+  if (clash) {
+    throw new Error(
+      `Folder code '${args.code}' is already used at '${clash.path}'. Folder codes must be unique across the whole tree \u2014 role rights reference a folder as 'folder:${args.code}' with no path, so a duplicate is ambiguous. Pick a distinct code (e.g. 'east_central').`
+    );
   }
+  const children = cursor.children ?? {};
   children[args.code] = args.folder;
   cursor.children = children;
   return makeResult(
@@ -33809,8 +35262,8 @@ function roleRightSet(args) {
 }
 
 // src/tools/module-inspect.ts
-var fs7 = __toESM(require("fs"));
-var path9 = __toESM(require("path"));
+var fs10 = __toESM(require("fs"));
+var path13 = __toESM(require("path"));
 var moduleInspectSchema = {
   moduleDir: external_exports.string()
 };
@@ -33818,7 +35271,7 @@ function moduleInspect(args) {
   const { paths, manifest } = loadManifest(args.moduleDir);
   const entities = manifest.entities ?? {};
   const entitySummaries = Object.entries(entities).map(([name, relPath]) => {
-    const abs = path9.join(paths.root, relPath.replace(/^\.\//, ""));
+    const abs = path13.join(paths.root, relPath.replace(/^\.\//, ""));
     const e = readJsonOrDefault(abs, {});
     const fields = e.fields ?? {};
     return {
@@ -33828,7 +35281,11 @@ function moduleInspect(args) {
       fieldCount: Object.keys(fields).length,
       fields: Object.keys(fields),
       hasNumberSequence: Boolean(e.numberSequence),
-      toString: e.toString
+      // Read as an OWN property — `toString` is inherited from
+      // Object.prototype, so a plain `e.toString` reports the built-in
+      // function (which JSON.stringify then silently drops) for every
+      // entity that doesn't declare a template.
+      toString: Object.prototype.hasOwnProperty.call(e, "toString") ? e.toString : null
     };
   });
   const views = readJsonOrDefault(paths.dataViews, {});
@@ -33854,15 +35311,47 @@ function moduleInspect(args) {
   const actions = readJsonOrDefault(paths.actions, {});
   const actionSummaries = Object.entries(actions).map(([code2, a]) => ({
     code: code2,
-    entity: a.entity ?? "?",
-    mode: a.mode ?? "single",
-    background: Boolean(a.background)
+    entityCode: a.entityCode ?? a.entity ?? "?",
+    executionMode: a.executionMode ?? a.mode ?? "single",
+    isAsync: Boolean(a.isAsync ?? a.background),
+    script: a.script ?? code2
+  }));
+  const triggerFile = readJsonOrDefault(
+    paths.triggers,
+    {}
+  );
+  const triggerSummaries = (triggerFile.triggers ?? []).map((t) => ({
+    code: t.code ?? "?",
+    entity: t.entity ?? "?",
+    event: t.event ?? "?",
+    action: t.action ?? "?",
+    async: Boolean(t.async)
+  }));
+  const webhookFile = readJsonOrDefault(
+    paths.webhooks,
+    {}
+  );
+  const webhookSummaries = (webhookFile.subscriptions ?? []).map((w) => ({
+    code: w.code ?? "?",
+    entity: w.entity ?? "?",
+    event: w.event ?? "?",
+    endpointUrl: w.endpointUrl ?? "?"
   }));
   const reports = Object.keys(readJsonOrDefault(paths.reports, {}));
   const settings = Object.keys(readJsonOrDefault(paths.settings, {}));
-  const jobs = Object.keys(readJsonOrDefault(paths.jobs, {}));
-  const seedFiles = fs7.existsSync(paths.seedDataDir) ? fs7.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json")).sort() : [];
-  const translations = fs7.existsSync(paths.translationsDir) ? fs7.readdirSync(paths.translationsDir).filter((f) => f.endsWith(".json")).sort() : [];
+  const jobsFile = readJsonOrDefault(paths.jobs, {});
+  const jobSummaries = (jobsFile.jobs ?? []).map((j) => ({
+    code: j.code ?? "?",
+    action: j.action ?? "?",
+    schedule: j.schedule ?? "?"
+  }));
+  const queries = Object.keys(readJsonOrDefault(paths.queries, {}));
+  const printTemplates = Object.keys(
+    readJsonOrDefault(paths.printTemplates, {})
+  );
+  const domains = Object.keys(readJsonOrDefault(paths.domains, {}));
+  const seedFiles = fs10.existsSync(paths.seedDataDir) ? fs10.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json")).sort() : [];
+  const translations = fs10.existsSync(paths.translationsDir) ? fs10.readdirSync(paths.translationsDir).filter((f) => f.endsWith(".json")).sort() : [];
   const summary = {
     module: {
       code: manifest.code,
@@ -33879,14 +35368,20 @@ function moduleInspect(args) {
     menus: menuSummaries,
     roles: roleSummaries,
     actions: actionSummaries,
+    triggers: triggerSummaries,
+    webhooks: webhookSummaries,
     reports,
     settings,
-    jobs,
+    jobs: jobSummaries,
+    queries,
+    printTemplates,
+    domains,
     seedFiles,
-    translations
+    translations,
+    supportedLocales: Array.isArray(manifest.supportedLocales) ? manifest.supportedLocales.filter((l) => typeof l === "string") : []
   };
   return {
-    summary: `Module '${manifest.code}' v${manifest.version}: ${entitySummaries.length} entities, ${viewSummaries.length} views, ${roleSummaries.length} roles, ${actionSummaries.length} actions, ${reports.length} reports.`,
+    summary: `Module '${manifest.code}' v${manifest.version}: ${entitySummaries.length} entities, ${viewSummaries.length} views, ${roleSummaries.length} roles, ${actionSummaries.length} actions, ${triggerSummaries.length} triggers, ${jobSummaries.length} jobs, ${reports.length} reports.`,
     files: { "_inspect.json": JSON.stringify(summary, null, "	") + "\n" }
   };
 }
@@ -33900,8 +35395,8 @@ function computeDepth(folder, current = 1) {
 }
 
 // src/tools/module-validate.ts
-var fs8 = __toESM(require("fs"));
-var path10 = __toESM(require("path"));
+var fs11 = __toESM(require("fs"));
+var path14 = __toESM(require("path"));
 var moduleValidateSchema = {
   moduleDir: external_exports.string().describe("Path to the module root. Run this after authoring and before dforge_module_pack.")
 };
@@ -33921,12 +35416,12 @@ function hasVisibleScalarColumn(fields) {
   return false;
 }
 function resolveTranslationFile(translationsDir, locale) {
-  const exact = path10.join(translationsDir, `${locale}.json`);
-  if (fs8.existsSync(exact)) return exact;
-  if (!fs8.existsSync(translationsDir)) return void 0;
+  const exact = path14.join(translationsDir, `${locale}.json`);
+  if (fs11.existsSync(exact)) return exact;
+  if (!fs11.existsSync(translationsDir)) return void 0;
   const want = `${locale}.json`.toLowerCase();
-  for (const f of fs8.readdirSync(translationsDir)) {
-    if (f.toLowerCase() === want) return path10.join(translationsDir, f);
+  for (const f of fs11.readdirSync(translationsDir)) {
+    if (f.toLowerCase() === want) return path14.join(translationsDir, f);
   }
   return void 0;
 }
@@ -33954,14 +35449,14 @@ function moduleValidate(args) {
   const fieldDefsOf = {};
   for (const [name, relPath] of Object.entries(entityMap)) {
     if (name.includes(".")) continue;
-    const abs = path10.join(paths.root, relPath.replace(/^\.\//, ""));
-    if (!fs8.existsSync(abs)) {
+    const abs = path14.join(paths.root, relPath.replace(/^\.\//, ""));
+    if (!fs11.existsSync(abs)) {
       err(`manifest.entities.${name}`, `points to '${relPath}' which does not exist on disk`);
       continue;
     }
     let e;
     try {
-      e = JSON.parse(fs8.readFileSync(abs, "utf8"));
+      e = JSON.parse(fs11.readFileSync(abs, "utf8"));
     } catch (ex) {
       err(`entities/${name}.json`, `invalid JSON: ${ex.message}`);
       continue;
@@ -33969,13 +35464,16 @@ function moduleValidate(args) {
     entities[name] = e;
     const fields = e.fields ?? {};
     const cols = new Set(Object.keys(fields));
-    let traitFields = {};
     const traits2 = e.traits ?? [];
-    try {
-      traitFields = expandTraits(traits2, name);
-      for (const c of Object.keys(traitFields)) cols.add(c);
-    } catch {
+    const badTraits = unknownTraits(traits2);
+    if (badTraits.length > 0) {
+      err(
+        `entities/${name}.json`,
+        `declares unknown trait(s): ${badTraits.join(", ")}. Valid: ${TRAIT_CODES.join(", ")}. An unrecognized trait is ignored when columns are expanded, so its columns are missing from this entity \u2014 expect knock-on 'not a column' errors below.`
+      );
     }
+    const traitFields = expandTraits(traits2, name);
+    for (const c of Object.keys(traitFields)) cols.add(c);
     columnsOf[name] = cols;
     fieldDefsOf[name] = { ...traitFields, ...fields };
   }
@@ -33989,7 +35487,7 @@ function moduleValidate(args) {
     }
     return false;
   };
-  const pkOf = (code2) => {
+  const pkOf2 = (code2) => {
     if (code2 in SYSTEM_ENTITY_PK) return SYSTEM_ENTITY_PK[code2];
     const e = entities[code2];
     if (e && (e.traits ?? []).includes("identity")) return `${code2}_id`;
@@ -34009,7 +35507,7 @@ function moduleValidate(args) {
       if (thisKey && !columnsOf[name].has(thisKey)) {
         err(where, `link.thisKey '${thisKey}' is not a column on '${name}' \u2014 the hidden FK column is missing (FK+Reference is two columns)`);
       }
-      const pk = target ? pkOf(target) : void 0;
+      const pk = target ? pkOf2(target) : void 0;
       if (pk && link.otherKey && link.otherKey !== pk) {
         warn(where, `link.otherKey '${link.otherKey}' \u2014 expected '${pk}' (the target entity's PK)`);
       }
@@ -34058,7 +35556,7 @@ function moduleValidate(args) {
       const defs = fieldDefsOf[ent];
       if (!defs) continue;
       if (hasVisibleScalarColumn(defs)) continue;
-      const key = `${vcode}\0${ent}`;
+      const key = compositeKey(vcode, ent);
       if (vcSeen.has(key)) continue;
       vcSeen.add(key);
       err(
@@ -34133,7 +35631,7 @@ function moduleValidate(args) {
         const abs = resolveTranslationFile(paths.translationsDir, locale);
         if (abs) {
           try {
-            tx = JSON.parse(fs8.readFileSync(abs, "utf8"));
+            tx = JSON.parse(fs11.readFileSync(abs, "utf8"));
           } catch {
             tx = null;
           }
@@ -34149,6 +35647,236 @@ function moduleValidate(args) {
       }
     }
   }
+  for (const [name, e] of Object.entries(entities)) {
+    const fields = e.fields ?? {};
+    for (const [fname, f] of Object.entries(fields)) {
+      for (const issue2 of checkFieldSpec(`${name}.${fname}`, f)) {
+        issues.push({ level: issue2.level, where: `entities/${name}.json`, message: issue2.message });
+      }
+    }
+  }
+  for (const [name, e] of Object.entries(entities)) {
+    const isExtension = typeof e.extends === "string" && e.extends.length > 0;
+    const ts = Object.prototype.hasOwnProperty.call(e, "toString") ? e.toString : void 0;
+    if (ts === void 0 || ts === null || typeof ts === "string" && ts.trim() === "") {
+      if (!isExtension) {
+        warn(
+          `entities/${name}.json`,
+          `has no 'toString' template \u2014 every entity should have one, e.g. "toString": "{name}" (extension entities use null to inherit the base).`
+        );
+      }
+      continue;
+    }
+    if (typeof ts !== "string") {
+      err(`entities/${name}.json`, `'toString' must be a string template, got ${typeof ts}.`);
+      continue;
+    }
+    const braces = [...ts.matchAll(/\{([a-z][a-z0-9_]*)\}/gi)].map((m) => m[1]);
+    if (braces.length === 0) {
+      warn(
+        `entities/${name}.json`,
+        `'toString' is "${ts}" with no {column} placeholder \u2014 every record will render the same label.`
+      );
+    }
+    for (const b of braces) {
+      if (!columnsOf[name].has(b)) {
+        err(
+          `entities/${name}.json`,
+          `'toString' references {${b}}, which is not a column on '${name}'.`
+        );
+      }
+    }
+  }
+  for (const [name, e] of Object.entries(entities)) {
+    const fields = e.fields ?? {};
+    for (const [fname, f] of Object.entries(fields)) {
+      const formula = typeof f?.formula === "string" ? f.formula : "";
+      if (!formula) continue;
+      const agg = parseSetAggregate(formula);
+      if (!agg) continue;
+      const where = `entities/${name}.json \u2192 ${fname}`;
+      if (f.columnType === "F") {
+        err(
+          where,
+          `is a Formula ('F') column with a set aggregate ${agg.agg}([${agg.setField}].[${agg.childField}]) \u2014 an F set-aggregate is unsupported and silently renders empty. Use a Generated ('G') column with dbDatatype + formula instead. (See dforge://reference/column-types.)`
+        );
+        continue;
+      }
+      if (f.columnType !== "G") continue;
+      const setCol = fields[agg.setField] ?? fieldDefsOf[name]?.[agg.setField];
+      if (!setCol) {
+        err(where, `aggregates over '[${agg.setField}]', which is not a column on '${name}'.`);
+        continue;
+      }
+      if (setCol.columnType !== "S") {
+        warn(
+          where,
+          `aggregates over '[${agg.setField}]', which is not a set column (columnType 'S') on '${name}'.`
+        );
+        continue;
+      }
+      const childEntity = setCol.link?.entity;
+      if (!childEntity) continue;
+      const childDefs = fieldDefsOf[childEntity];
+      if (!childDefs) continue;
+      const childCol = childDefs[agg.childField];
+      if (!childCol) {
+        err(
+          where,
+          `aggregates '[${agg.setField}].[${agg.childField}]' but '${agg.childField}' is not a column on child entity '${childEntity}'.`
+        );
+        continue;
+      }
+      const childType = typeof childCol.columnType === "string" ? childCol.columnType : "D";
+      if (childType === "F" || childType === "R" || childType === "S") {
+        err(
+          where,
+          `aggregates '[${agg.setField}].[${agg.childField}]', but '${childEntity}.${agg.childField}' is a virtual '${childType}' column. A Generated aggregate reads the child's PHYSICAL column \u2014 install fails with \`column old.${agg.childField} does not exist\`. Aggregate a 'D' (or same-row 'G') child column instead.`
+        );
+      }
+    }
+  }
+  for (const [acode, a] of Object.entries(actions)) {
+    const act = a ?? {};
+    const where = `actions \u2192 ${acode}`;
+    const script = typeof act.script === "string" ? act.script : "";
+    if (!script) {
+      err(where, "has no 'script' \u2014 it must be the bare DSL filename (no path, no .dsl extension).");
+    } else if (script.includes("/") || script.includes("\\") || script.endsWith(".dsl")) {
+      err(
+        where,
+        `script '${script}' must be a BARE filename \u2014 no path, no '.dsl' extension (e.g. "script": "${script.replace(/\.dsl$/, "").split(/[\\/]/).pop()}").`
+      );
+    } else if (!fs11.existsSync(path14.join(paths.logicDir, "actions", `${script}.dsl`))) {
+      err(where, `script '${script}' has no file at logic/actions/${script}.dsl.`);
+    }
+    const ent = act.entityCode ?? act.entity;
+    if (ent && !isKnownEntity(ent)) {
+      err(where, `targets entity '${ent}', which is not a known entity.`);
+    }
+  }
+  const isKnownAction = (code2) => {
+    if (code2 in actions) return true;
+    const dot = code2.indexOf(".");
+    if (dot > 0) {
+      const mod = code2.slice(0, dot);
+      return deps.has(mod) || mod === manifest.code;
+    }
+    return false;
+  };
+  const triggerFile = readJsonOrDefault(
+    paths.triggers,
+    {}
+  );
+  for (const t of triggerFile.triggers ?? []) {
+    const where = `triggers \u2192 ${String(t.code ?? "?")}`;
+    const act = t.action;
+    if (act && !isKnownAction(act)) {
+      err(where, `fires action '${act}', which is not in ui/actions.json (add it with dforge_action_add first).`);
+    }
+    const ent = t.entity;
+    if (ent && !isKnownEntity(ent)) err(where, `is bound to entity '${ent}', which is not a known entity.`);
+  }
+  const jobFile = readJsonOrDefault(paths.jobs, {});
+  for (const j of jobFile.jobs ?? []) {
+    const where = `jobs \u2192 ${String(j.code ?? "?")}`;
+    const act = j.action;
+    if (act && !isKnownAction(act)) {
+      err(where, `schedules action '${act}', which is not in ui/actions.json.`);
+    }
+    if (act && act in actions) {
+      const script = actions[act]?.script;
+      if (typeof script === "string") {
+        const dslPath = path14.join(paths.logicDir, "actions", `${script}.dsl`);
+        if (fs11.existsSync(dslPath)) {
+          let body = "";
+          try {
+            body = fs11.readFileSync(dslPath, "utf8");
+          } catch {
+          }
+          for (const issue2 of checkDsl(body, { viaJob: true })) {
+            if (issue2.rule !== "job-record-context") continue;
+            issues.push({ level: issue2.level, where, message: issue2.message });
+          }
+        }
+      }
+    }
+  }
+  const webhookFile = readJsonOrDefault(
+    paths.webhooks,
+    {}
+  );
+  for (const w of webhookFile.subscriptions ?? []) {
+    const ent = w.entity;
+    if (ent && !isKnownEntity(ent)) {
+      err(`webhooks \u2192 ${String(w.code ?? "?")}`, `is bound to entity '${ent}', which is not a known entity.`);
+    }
+  }
+  for (const [acode, a] of Object.entries(actions)) {
+    const script = a?.script;
+    if (typeof script !== "string" || !script) continue;
+    const dslPath = path14.join(paths.logicDir, "actions", `${script}.dsl`);
+    if (!fs11.existsSync(dslPath)) continue;
+    let body;
+    try {
+      body = fs11.readFileSync(dslPath, "utf8");
+    } catch {
+      continue;
+    }
+    const mode = a.executionMode ?? a.mode;
+    for (const issue2 of checkDsl(body, { executionMode: mode })) {
+      issues.push({
+        level: issue2.level,
+        where: `logic/actions/${script}.dsl`,
+        message: `[${acode}] ${issue2.message}`
+      });
+    }
+  }
+  const folderRoot = readJsonOrDefault(paths.folders, {});
+  for (const [code2, dupPaths] of duplicateFolderCodes(folderRoot)) {
+    err(
+      "ui/folders.json",
+      `folder code '${code2}' is used ${dupPaths.length} times (${dupPaths.join(", ")}). Codes must be unique across the whole tree: role rights say 'folder:${code2}' with no path, and translations key on 'folders.${code2}.label', so duplicates are ambiguous and silently collide.`
+    );
+  }
+  const 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) {
+    const locale = raw.trim();
+    if (!locale) continue;
+    if (!resolveTranslationFile(paths.translationsDir, locale)) {
+      err(
+        "translations",
+        `manifest.supportedLocales lists '${locale}' but translations/${locale}.json does not exist \u2014 install fails translation completeness validation.`
+      );
+    }
+  }
+  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 {
+      tx = JSON.parse(fs11.readFileSync(path14.join(paths.translationsDir, file2), "utf8"));
+    } catch (ex) {
+      err(`translations/${file2}`, `invalid JSON: ${ex.message}`);
+      continue;
+    }
+    const txRoles = tx.roles ?? {};
+    const missing = roleCodes.filter((rc) => {
+      const entry = txRoles[rc];
+      return !entry || typeof entry.label !== "string" || entry.label.trim() === "";
+    });
+    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>'."`
+      );
+    }
+  }
   const errors = issues.filter((i) => i.level === "error");
   const warnings = issues.filter((i) => i.level === "warning");
   const clean = errors.length === 0 && warnings.length === 0;
@@ -34314,11 +36042,72 @@ function webhookAdd(args) {
   );
 }
 
+// src/tools/apply.ts
+var fs12 = __toESM(require("fs"));
+var path15 = __toESM(require("path"));
+var applyInput = {
+  apply: external_exports.boolean().default(false).describe(
+    "When true, WRITE the resulting files to disk (and remove any `deletes`) instead of returning their contents for the client to write. The response then lists the paths touched. Use it for routine patches the user isn't reviewing line-by-line; leave it false when you want to preview a diff first."
+  )
+};
+var isReportPayload = (relPath) => path15.basename(relPath).startsWith("_");
+function resolveInside(root, relPath) {
+  const abs = path15.resolve(root, relPath);
+  const rel2 = path15.relative(root, abs);
+  if (rel2.startsWith("..") || path15.isAbsolute(rel2)) {
+    throw new Error(
+      `Refusing to write '${relPath}' \u2014 it resolves outside the module directory (${abs}).`
+    );
+  }
+  return abs;
+}
+function applyToDisk(moduleDir, result) {
+  const root = path15.resolve(moduleDir);
+  const written = [];
+  const skipped = [];
+  for (const [relPath, contents] of Object.entries(result.files ?? {})) {
+    if (isReportPayload(relPath)) {
+      skipped.push(relPath);
+      continue;
+    }
+    const abs = resolveInside(root, relPath);
+    fs12.mkdirSync(path15.dirname(abs), { recursive: true });
+    fs12.writeFileSync(abs, contents, "utf8");
+    written.push(relPath);
+  }
+  const deleted = [];
+  for (const relPath of result.deletes ?? []) {
+    const abs = resolveInside(root, relPath);
+    let stat;
+    try {
+      stat = fs12.lstatSync(abs);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      throw new Error(
+        `Refusing to delete '${relPath}': it is a directory, and \`deletes\` is a file-only contract (it exists to remove a renamed entity's old JSON or an orphaned seed file). Remove the directory by hand if that is really what you want.`
+      );
+    }
+    fs12.rmSync(abs, { force: true });
+    deleted.push(relPath);
+  }
+  const out = {
+    summary: result.summary,
+    applied: true,
+    written: written.sort(),
+    deleted: deleted.sort()
+  };
+  if (skipped.length > 0) out.skipped = skipped.sort();
+  if (result.warning) out.warning = result.warning;
+  return out;
+}
+
 // src/resources/index.ts
-var fs9 = __toESM(require("fs"));
-var path11 = __toESM(require("path"));
-var RESOURCES_DIR = path11.resolve(__dirname, "..", "resources");
-var SKILL_DIR = path11.resolve(__dirname, "..", "skills", "dforge-mcp-author");
+var fs13 = __toESM(require("fs"));
+var path16 = __toESM(require("path"));
+var RESOURCES_DIR = path16.resolve(__dirname, "..", "resources");
+var SKILL_DIR = path16.resolve(__dirname, "..", "skills", "dforge-mcp-author");
 function schema(name, label, description) {
   return {
     uri: `dforge://schema/${name}`,
@@ -34366,6 +36155,11 @@ var resources = [
     "Entity JSON schema",
     "JSON Schema for entity files under entities/*.json (description, dbObject, toString, traits, fields)."
   ),
+  schema(
+    "domains",
+    "Column domains JSON schema",
+    'JSON Schema for domains.json \u2014 reusable column domains (base datatype + control + sizing + shared option list) referenced from a field via "domain": "module_cd.domain_cd".'
+  ),
   schema(
     "data-views",
     "Data view JSON schema",
@@ -34444,6 +36238,7 @@ var resources = [
   reference("field-types", "Field types \u2014 fieldTypeCd (UI control) vs dbDatatype (SQL type), and the correct value for each. Load before adding any field."),
   reference("flags", "Column flags \u2014 only V/I/E/M/H; valid combos (VEM/VE/V/EM/I) and why 'VEMHI' is invalid. Load before setting any flags."),
   reference("column-types", "The FK + Reference two-column pattern (the #1 source of broken modules) and Set columns. Load before any relation."),
+  reference("column-domains", "Column domains: a reusable field type (datatype + control + shared option list) referenced via a single `domain` key. Use when the same enum/type repeats across columns. Load before authoring domains.json or a domain-backed column."),
   reference("formulas", "Formula columns (columnType 'F'): baseDatatypeCd, no dbDatatype, flags 'V', and the formula expression grammar."),
   reference("traits", "Entity traits (identity, audit, audit-full, ...). identity \u2192 PK is '{entity}_id'; don't redefine trait columns."),
   reference("data-views", "Data views: dataSources array, columns, the order string-array ('order': ['-col','col']), and specialized view configs."),
@@ -34455,6 +36250,7 @@ var resources = [
   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."),
+  reference("document-extraction", "OCR / document extraction: ocrExtract() (v2 schema-driven + profile forms), logic/extraction_profiles.json, and the detectDocument() doc-type auto-detect built-in. Load before wiring any OCR/intake action."),
   reference("print-templates", "Liquid HTML print templates."),
   reference("translations", "Translation files: locale-keyed, every trait-provided field needs an entry."),
   reference("queries", "Pre-built saved queries."),
@@ -34489,53 +36285,53 @@ var resources = [
   matrixExample("seed-data/01-categories.json", "Matrix example seed: row-axis category records.")
 ];
 function readVendored(rel2) {
-  const p = path11.join(RESOURCES_DIR, rel2);
-  if (!fs9.existsSync(p)) {
+  const p = path16.join(RESOURCES_DIR, rel2);
+  if (!fs13.existsSync(p)) {
     return `// Resource missing at build time: ${rel2}
 // Run scripts/vendor-resources.sh in dforge-mcp to refresh from dForge-core.`;
   }
-  return fs9.readFileSync(p, "utf8");
+  return fs13.readFileSync(p, "utf8");
 }
 function readSkill(rel2) {
-  const p = path11.join(SKILL_DIR, rel2);
-  if (!fs9.existsSync(p)) {
+  const p = path16.join(SKILL_DIR, rel2);
+  if (!fs13.existsSync(p)) {
     return `// Skill resource missing: ${rel2}
 // Expected under skills/dforge-mcp-author/ \u2014 check the package 'files' list.`;
   }
-  return fs9.readFileSync(p, "utf8");
+  return fs13.readFileSync(p, "utf8");
 }
 
 // src/server.ts
 var server = new McpServer({
   name: "dforge-mcp",
-  version: "0.1.0"
+  version: "0.2.0"
 });
 function envelope(fn) {
   return async (args) => {
     try {
-      const r = fn(args);
+      if (args.apply && !args.moduleDir) {
+        throw new Error(
+          "apply: true requires `moduleDir` \u2014 it's the root the file map is written relative to. Pass moduleDir, or omit `apply` to get the file map back for the client to write."
+        );
+      }
+      const result = fn(args);
+      const payload = args.apply ? applyToDisk(args.moduleDir, result) : result;
       return {
-        content: [{ type: "text", text: JSON.stringify(r, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
       };
     } catch (e) {
       return {
-        content: [
-          { type: "text", text: `Error: ${e.message}` }
-        ],
+        content: [{ type: "text", text: `Error: ${e.message}` }],
         isError: true
       };
     }
   };
 }
-server.tool(
-  "dforge_module_plan",
-  "Phase 0 owner \u2014 CALL THIS FIRST for any new or resumed module task. Drives the full Phase 0 workflow: 'check' returns current state and exact next steps; 'write_identity' (0a) writes CLAUDE.md; 'write_requirements' (0b) confirms docs/REQUIREMENTS.md (already written to disk by the agent) after user confirms YES and ticks CLAUDE.md; 'write_design' (0c) confirms docs/DESIGN.md (already written to disk by the agent) after user confirms YES and ticks CLAUDE.md; 'validate' (0d) runs pre-scaffold checks and writes docs/VALIDATION.md when all pass. dforge_module_create is blocked until this tool reports readyToScaffold: true.",
-  planModuleSchema,
-  async (args) => {
+function serialize(fn) {
+  return async (args) => {
     try {
-      const result = planModule(args);
       return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(fn(args), null, 2) }]
       };
     } catch (e) {
       return {
@@ -34543,218 +36339,356 @@ server.tool(
         isError: true
       };
     }
-  }
+  };
+}
+var READ_ONLY = { readOnlyHint: true, idempotentHint: true };
+var DESTRUCTIVE = { destructiveHint: true };
+var EXTERNAL = { openWorldHint: true };
+server.registerTool(
+  "dforge_module_plan",
+  {
+    title: "Plan module (lifecycle orchestrator)",
+    description: "Lifecycle owner \u2014 CALL THIS FIRST for any new or resumed module task. 'check' returns the current phase, the exact next steps, and which authoring skill to run next (design \u2192 build \u2192 ship). Phase 0: 'write_identity' (0a) writes CLAUDE.md; 'write_requirements' (0b) confirms docs/REQUIREMENTS.md (already written to disk by the agent) after the user confirms YES and ticks CLAUDE.md; 'write_design' (0c) confirms docs/DESIGN.md the same way; 'validate' (0d) runs pre-scaffold checks and writes docs/VALIDATION.md when all pass. Phases 1-6: 'complete_phase' records a phase as done or deliberately skipped, so a resumed session never re-proposes finished work. dforge_module_create is blocked until this tool reports readyToScaffold: true.",
+    inputSchema: planModuleSchema
+  },
+  serialize(planModule)
 );
-server.tool(
+server.registerTool(
   "dforge_module_create",
-  "Scaffold a new dForge module (Phase 1). \u26D4 REQUIRES Phase 0 complete \u2014 call dforge_module_plan first. Blocked until CLAUDE.md, docs/REQUIREMENTS.md, docs/DESIGN.md, and docs/VALIDATION.md (all-pass) exist in moduleDir. Returns { files: { '<relPath>': '<contents>' } } \u2014 always preview with user before writing.",
-  createModuleSchema,
-  async (args) => {
+  {
+    title: "Scaffold a new module",
+    description: "Scaffold a new dForge module (Phase 1). \u26D4 REQUIRES Phase 0 complete \u2014 call dforge_module_plan first. Blocked until CLAUDE.md, docs/REQUIREMENTS.md, docs/DESIGN.md, and docs/VALIDATION.md (all-pass) exist in moduleDir. Returns { files: { '<relPath>': '<contents>' } } \u2014 preview with the user before writing, or pass apply: true to write directly.",
+    inputSchema: { ...createModuleSchema, ...applyInput }
+  },
+  envelope((args) => {
     const files = createModuleFiles(args);
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(
-            {
-              summary: `Generated ${Object.keys(files).length} files for module '${args.code}' (preset: ${args.preset}, ${args.entities.length} entit${args.entities.length === 1 ? "y" : "ies"}).`,
-              files
-            },
-            null,
-            2
-          )
-        }
-      ]
-    };
-  }
+    return makeResult(
+      `Generated ${Object.keys(files).length} files for module '${args.code}' (preset: ${args.preset}, ${args.entities.length} entit${args.entities.length === 1 ? "y" : "ies"}).`,
+      files
+    );
+  })
 );
-server.tool(
+server.registerTool(
   "dforge_module_inspect",
-  "Read the current state of an existing module from disk and return a structured summary. Call this BEFORE any patch tool so you know what entities/views/roles already exist and don't try to re-create them.",
-  moduleInspectSchema,
-  envelope(moduleInspect)
+  {
+    title: "Inspect module state",
+    description: "Read the current state of an existing module from disk and return a structured summary \u2014 entities + fields, views + sources, roles + rights, actions, triggers, jobs, webhooks, reports, settings, queries, print templates, domains, seed files, translations. Call this BEFORE any patch tool so you know what already exists. The full structured state is in files['_inspect.json']; `summary` is one-line stats.",
+    inputSchema: moduleInspectSchema,
+    annotations: READ_ONLY
+  },
+  serialize(moduleInspect)
 );
-server.tool(
+server.registerTool(
   "dforge_module_validate",
-  "Validate the whole module OFFLINE before packing/installing: checks cross-references the per-field tools can't see \u2014 dangling FK/reference targets, a missing hidden-FK column, view dataSources/columns pointing at unknown entities/fields, menu dataViewCode \u2192 missing view, role rights keyed on unknown entities/actions/reports, and entities with no Select grant. Returns errors + warnings in _validate.json. Run this after authoring and fix every error BEFORE dforge_module_pack \u2014 it saves a slow pack/install round trip.",
-  moduleValidateSchema,
-  envelope(moduleValidate)
+  {
+    title: "Validate module (offline)",
+    description: "Validate the whole module OFFLINE before packing/installing. Runs every check the per-field tools can't see: dangling FK/reference targets, a missing hidden-FK column, view dataSources/columns pointing at unknown entities/fields, menu dataViewCode \u2192 missing view, role rights on unknown objects, entities with no Select grant, field-spec rules re-run across EVERY field (catching anything that entered via import or a hand edit), toString templates, Formula-vs-Generated set aggregates over virtual child columns, action script files missing from disk, triggers/jobs firing actions that don't exist, DSL static checks, and translation completeness (role labels are install-blocking). Returns errors + warnings in _validate.json. Fix every error BEFORE dforge_module_pack \u2014 it saves a slow pack/install round trip.",
+    inputSchema: moduleValidateSchema,
+    annotations: READ_ONLY
+  },
+  serialize(moduleValidate)
 );
-server.tool(
+server.registerTool(
   "dforge_module_pack",
-  "Pack a module directory into a .dforge tarball. Uses the bundled dforge-cli package, PATH fallback, or DFORGE_CLI_BINARY override.",
-  packModuleSchema,
-  async (args) => {
-    const result = packModule(args);
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-  }
+  {
+    title: "Pack module to .dforge",
+    description: "Pack a module directory into a .dforge tarball. Uses the bundled dforge-cli package, PATH fallback, or DFORGE_CLI_BINARY override. Refuses to build if any entity lacks a role granting Select (the Phase 5a gate).",
+    inputSchema: packModuleSchema,
+    annotations: EXTERNAL
+  },
+  serialize(packModule)
 );
-server.tool(
+server.registerTool(
   "dforge_module_install",
-  "PHASE 6: Install a module (directory or .dforge tarball) to a running tenant. Runs the FULL server-side validator \u2014 the only real validator. Reads DFORGE_URL / DFORGE_TOKEN env if not passed as args. Always returns raw CLI output, exitCode, and command so the agent can fix module defects and retry.",
-  installModuleSchema,
+  {
+    title: "Install module to a tenant",
+    description: "PHASE 6: Install a module (directory or .dforge tarball) to a running tenant. Runs the FULL server-side validator \u2014 the only real validator. Reads DFORGE_URL / DFORGE_TOKEN env if not passed as args. Always returns raw CLI output, exitCode, and command so the agent can fix module defects and retry.",
+    inputSchema: installModuleSchema,
+    annotations: { ...EXTERNAL, ...DESTRUCTIVE }
+  },
   async (args) => {
-    const result = installModule(args);
-    return {
-      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-      isError: !result.ok
-    };
+    try {
+      const result = installModule(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        isError: !result.ok
+      };
+    } catch (e) {
+      return {
+        content: [{ type: "text", text: `Error: ${e.message}` }],
+        isError: true
+      };
+    }
   }
 );
-server.tool(
+server.registerTool(
   "dforge_entity_add",
-  "PHASE 2: Add an entity to an existing module. Reads manifest from disk, returns the updated file map (manifest + new entity + regenerated UI/security). Other files on disk are NOT touched.",
-  addEntitySchema,
-  async (args) => {
+  {
+    title: "Add an entity",
+    description: "PHASE 1: Add an entity to an existing module. Reads manifest from disk, returns the updated file map (manifest + new entity + regenerated UI/security). Other files on disk are NOT touched.",
+    inputSchema: { ...addEntitySchema, ...applyInput }
+  },
+  envelope((args) => {
     const { files, warning } = addEntityFiles(args);
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(
-            {
-              summary: `Adds entity '${args.entity.name}' to ${args.moduleDir}.`,
-              warning,
-              files
-            },
-            null,
-            2
-          )
-        }
-      ]
-    };
-  }
+    return makeResult(`Adds entity '${args.entity.name}' to ${args.moduleDir}.`, files, warning);
+  })
 );
-server.tool(
+server.registerTool(
   "dforge_module_import",
-  "Import a normalized table-spec (tables \u2192 columns \u2192 relationships) into an existing module as entities. Infers each column's fieldTypeCd from an explicit code, a source SQL type (sqlType), sample values, and name heuristics (validated against the metadata registry; dbDatatype derived), and generates the FK+Reference two-column pattern for each relationship. The front-end that produces the table-spec can be DBML/SQL, an Excel/CSV upload, or hand-authored. Scaffold a minimal module first; this ADDS entities and regenerates default views/menus/roles. Review inferred types and run dforge_module_validate after.",
-  moduleImportSchema,
+  {
+    title: "Import a table-spec as entities",
+    description: "Import a normalized table-spec (tables \u2192 columns \u2192 relationships) into an existing module as entities. Infers each column's fieldTypeCd from an explicit code, a source SQL type (sqlType), sample values, and name heuristics (validated against the metadata registry; dbDatatype derived), and generates the FK+Reference two-column pattern for each relationship. The front-end that produces the table-spec can be DBML/SQL, an Excel/CSV upload, or hand-authored. Scaffold a minimal module first; this ADDS entities and regenerates default views/menus/roles. Review inferred types and run dforge_module_validate after.",
+    inputSchema: { ...moduleImportSchema, ...applyInput }
+  },
   envelope(moduleImport)
 );
-server.tool(
+server.registerTool(
   "dforge_entity_rename",
-  "Refactor-safe rename of an entity code. Moves the entity file (old is listed in the response's `deletes` \u2014 delete it), renames the manifest key, cascades the identity PK {old}_id \u2192 {new}_id wherever an FK targets it, and repoints every reference: other entities' link.entity / references.to, view entityCode, role rights keys, action entity, folder bindings, and seed-data entityCode + PK keys. Reports/translations/menu labels/DSL are NOT rewritten (warned). Apply `files` AND `deletes`, then run dforge_module_validate.",
-  entityRenameSchema,
+  {
+    title: "Rename an entity (refactor-safe)",
+    description: "Refactor-safe rename of an entity code. Moves the entity file (old is listed in the response's `deletes` \u2014 delete it), renames the manifest key, cascades the identity PK {old}_id \u2192 {new}_id wherever an FK targets it, and repoints every reference: other entities' link.entity / references.to, view entityCode, role rights keys, action entity, folder bindings, and seed-data entityCode + PK keys. Reports/translations/menu labels/DSL are NOT rewritten (warned). Apply `files` AND `deletes` (or pass apply: true), then run dforge_module_validate.",
+    inputSchema: { ...entityRenameSchema, ...applyInput },
+    annotations: DESTRUCTIVE
+  },
   envelope(entityRename)
 );
-server.tool(
+server.registerTool(
   "dforge_entity_delete",
-  "Refactor-safe deletion of an entity. Removes the entity file + its seed files (listed in `deletes`), drops the manifest entry, role rights key, folder binding, and data-view sources (deleting a view left with no source). Cross-entity FKs targeting it, actions on it, and menus pointing at removed views are surfaced as warnings \u2014 fix those by hand. Apply `files` AND `deletes`, then run dforge_module_validate.",
-  entityDeleteSchema,
+  {
+    title: "Delete an entity (refactor-safe)",
+    description: "Refactor-safe deletion of an entity. Removes the entity file + its seed files (listed in `deletes`), drops the manifest entry, role rights key, folder binding, and data-view sources (deleting a view left with no source). Cross-entity FKs targeting it, actions on it, and menus pointing at removed views are surfaced as warnings \u2014 fix those by hand. Apply `files` AND `deletes` (or pass apply: true), then run dforge_module_validate.",
+    inputSchema: { ...entityDeleteSchema, ...applyInput },
+    annotations: DESTRUCTIVE
+  },
   envelope(entityDelete)
 );
-server.tool(
+server.registerTool(
   "dforge_entity_field_add",
-  "PHASE 2 / backtrack: Add a single new field to an existing entity. Use this (not entity_add) when refining an existing entity \u2014 preserves the rest of the entity definition.",
-  entityFieldAddSchema,
+  {
+    title: "Add a field",
+    description: "PHASE 1 / backtrack: Add a single new field to an existing entity. Use this (not entity_add) when refining an existing entity \u2014 it preserves the rest of the definition. For a RELATION, a ROLL-UP total, or a STATUS column, prefer the composite tools (dforge_entity_reference_add / _rollup_add / _status_add): each of those concepts spans several coordinated keys, and the composite tools emit the whole shape so the broken variants aren't representable.",
+    inputSchema: { ...entityFieldAddSchema, ...applyInput }
+  },
   envelope(entityFieldAdd)
 );
-server.tool(
+server.registerTool(
   "dforge_entity_field_modify",
-  "PHASE 2 / backtrack: Replace an existing field's spec on an entity. Pass the full desired field shape, not a partial diff.",
-  entityFieldModifySchema,
+  {
+    title: "Modify a field",
+    description: "PHASE 1 / backtrack: Replace an existing field's spec on an entity. Pass the full desired field shape, not a partial diff.",
+    inputSchema: { ...entityFieldModifySchema, ...applyInput }
+  },
   envelope(entityFieldModify)
 );
-server.tool(
+server.registerTool(
   "dforge_entity_field_remove",
-  "Refactor-safe field removal. Removes the field AND cascade-cleans the safe dependents: the paired Reference column when you remove its hidden FK, the references entry, view columns + order, and seed-data keys. Formula references and other entities' FKs pointing at the field are surfaced as warnings (not auto-deleted). Run dforge_module_validate after.",
-  entityFieldRemoveSchema,
+  {
+    title: "Remove a field (refactor-safe)",
+    description: "Refactor-safe field removal. Removes the field AND cascade-cleans the safe dependents: the paired Reference column when you remove its hidden FK, the references entry, view columns + order, and seed-data keys. Formula references and other entities' FKs pointing at the field are surfaced as warnings (not auto-deleted). Run dforge_module_validate after.",
+    inputSchema: { ...entityFieldRemoveSchema, ...applyInput },
+    annotations: DESTRUCTIVE
+  },
   envelope(entityFieldRemove)
 );
-server.tool(
+server.registerTool(
   "dforge_entity_field_rename",
-  "Refactor-safe rename of a field. Unlike field_modify, this PROPAGATES the new name to every reference: the paired Reference column's link.thisKey + references block, same-entity formula columns ([oldName] \u2192 [newName]), data view columns + order arrays, seed-data records for the entity, and OTHER entities' FKs that target this field. Returns the full set of changed files; review then write, and run dforge_module_validate after to confirm nothing dangles.",
-  entityFieldRenameSchema,
+  {
+    title: "Rename a field (refactor-safe)",
+    description: "Refactor-safe rename of a field. Unlike field_modify, this PROPAGATES the new name to every reference: the paired Reference column's link.thisKey + references block, same-entity formula columns ([oldName] \u2192 [newName]), data view columns + order arrays, seed-data records for the entity, and OTHER entities' FKs that target this field. Returns the full set of changed files; review then write, and run dforge_module_validate after to confirm nothing dangles.",
+    inputSchema: { ...entityFieldRenameSchema, ...applyInput }
+  },
   envelope(entityFieldRename)
 );
-server.tool(
+server.registerTool(
+  "dforge_entity_reference_add",
+  {
+    title: "Add a relation (FK + Reference)",
+    description: "PHASE 1: Add a relation between two entities in ONE call. Emits the complete FK+Reference pattern \u2014 the documented #1 source of broken modules \u2014 as all three of its parts: the hidden FK column (dbDatatype 'cuid', flags 'EM', no fieldTypeCd), the visible Reference column (columnType 'R', fieldTypeCd 'lookup', flags VEM/VE, link{entity,thisKey,otherKey}), and the `references` block entry. Use this instead of two dforge_entity_field_add calls \u2014 it can't emit the one-column form that fails install.",
+    inputSchema: { ...entityReferenceAddSchema, ...applyInput }
+  },
+  envelope(entityReferenceAdd)
+);
+server.registerTool(
+  "dforge_entity_rollup_add",
+  {
+    title: "Add a roll-up total",
+    description: "PHASE 1: Add a roll-up total over child rows (SUM/COUNT/AVG/MIN/MAX) in ONE call. Emits a GENERATED ('G') column \u2014 never a Formula ('F'), whose set-aggregates silently render empty \u2014 and creates the parent's Set column if it doesn't exist yet. Refuses to aggregate a virtual F/R/S child column, the documented `column old.<field> does not exist` install failure.",
+    inputSchema: { ...entityRollupAddSchema, ...applyInput }
+  },
+  envelope(entityRollupAdd)
+);
+server.registerTool(
+  "dforge_entity_status_add",
+  {
+    title: "Add a status column",
+    description: "PHASE 1: Add a status/stage column in ONE call. Emits a dropdown with params.options ({value,label} objects, never bare strings at the field root) and the initial value as a `formula` \u2014 entity fields have NO defaultValue key, which the entity schema rejects outright. An entity with a 3+ value status is also the objective trigger for a kanban view in Phase 3.",
+    inputSchema: { ...entityStatusAddSchema, ...applyInput }
+  },
+  envelope(entityStatusAdd)
+);
+server.registerTool(
   "dforge_action_add",
-  "PHASE 2: Add a DSL action targeting an entity. Writes logic/actions/<code>.dsl plus an entry in ui/actions.json. **Load dforge://docs/dsl before authoring.**",
-  actionAddSchema,
+  {
+    title: "Add a DSL action",
+    description: "PHASE 2: Add a DSL action targeting an entity. Writes logic/actions/<code>.dsl plus an entry in ui/actions.json, and runs the DSL static checker first \u2014 errors reject the call. **Load dforge://docs/dsl before authoring.**",
+    inputSchema: { ...actionAddSchema, ...applyInput }
+  },
   envelope(actionAdd)
 );
-server.tool(
+server.registerTool(
+  "dforge_action_check",
+  {
+    title: "Check action DSL",
+    description: "PHASE 2: Statically check an action's DSL \u2014 either a draft `dslBody` BEFORE calling dforge_action_add, or an `actionCode` already on disk. Catches the documented install/runtime failures without a tenant round trip: TODAY()/NOW() inside execute: ('TODAY is not defined'), [field] record-context in batch mode or a scheduled job, block order/duplication, top-level return, ':param' SQL placeholders (dForge binds '@param'), and unknown host functions. Read files['_action_check.json'].",
+    inputSchema: actionCheckSchema,
+    annotations: READ_ONLY
+  },
+  serialize(actionCheck)
+);
+server.registerTool(
   "dforge_trigger_add",
-  "PHASE 2: Add a trigger that fires an action on a DB event (insert/update/delete/status_change/any) optionally gated by a condition formula. Appends to logic/triggers.json. **Use trigger when the platform should react to data changes WITHOUT user interaction**; use jobs for cron-driven; use webhooks for outbound HTTP.",
-  triggerAddSchema,
+  {
+    title: "Add a DB-event trigger",
+    description: "PHASE 2: Add a trigger that fires an action on a DB event (insert/update/delete/status_change/any) optionally gated by a condition formula. Appends to logic/triggers.json. **Use a trigger when the platform should react to data changes WITHOUT user interaction**; use jobs for cron-driven; use webhooks for outbound HTTP. The target action must already exist in ui/actions.json.",
+    inputSchema: { ...triggerAddSchema, ...applyInput }
+  },
   envelope(triggerAdd)
 );
-server.tool(
+server.registerTool(
   "dforge_job_add",
-  "PHASE 2: Schedule an existing action to fire on a 5-field cron. Appends to logic/jobs.json. Action must NOT use record-context (`[field]`) syntax \u2014 scheduled jobs run as system user with no current record.",
-  jobAddSchema,
+  {
+    title: "Schedule a job",
+    description: "PHASE 2: Schedule an existing action to fire on a 5-field cron. Appends to logic/jobs.json. The action must NOT use record-context (`[field]`) syntax \u2014 scheduled jobs run as the system user with no current record (dforge_module_validate flags this).",
+    inputSchema: { ...jobAddSchema, ...applyInput }
+  },
   envelope(jobAdd)
 );
-server.tool(
+server.registerTool(
   "dforge_webhook_add",
-  "PHASE 2: Subscribe an outbound HTTP endpoint to a DB event. Appends to logic/webhooks.json. Use for integrations with external systems (Slack, Zapier, custom dashboards).",
-  webhookAddSchema,
+  {
+    title: "Add an outbound webhook",
+    description: "PHASE 2: Subscribe an outbound HTTP endpoint to a DB event. Appends to logic/webhooks.json. Use for integrations with external systems (Slack, Zapier, custom dashboards).",
+    inputSchema: { ...webhookAddSchema, ...applyInput }
+  },
   envelope(webhookAdd)
 );
-server.tool(
+server.registerTool(
   "dforge_view_add",
-  "PHASE 4: Add a data view to ui/data_views.json. viewType-specific viewConfig is supplied verbatim \u2014 pull dforge://schema/data-views first to know the shape.",
-  viewAddSchema,
+  {
+    title: "Add a data view",
+    description: "PHASE 3: Add a data view to ui/data_views.json. viewType-specific viewConfig is supplied verbatim \u2014 pull dforge://schema/data-views first to know the shape. Every entity needs a default grid before any specialized view.",
+    inputSchema: { ...viewAddSchema, ...applyInput }
+  },
   envelope(viewAdd)
 );
-server.tool(
+server.registerTool(
   "dforge_view_modify",
-  "PHASE 4 / backtrack: Replace an existing view spec. Pass the full desired shape.",
-  viewModifySchema,
+  {
+    title: "Modify a data view",
+    description: "PHASE 3 / backtrack: Replace an existing view spec. Pass the full desired shape.",
+    inputSchema: { ...viewModifySchema, ...applyInput }
+  },
   envelope(viewModify)
 );
-server.tool(
+server.registerTool(
+  "dforge_menu_add",
+  {
+    title: "Add a menu item",
+    description: "PHASE 3: Add a leaf or section to ui/menus.json. Pass dataViewCode for a leaf (validated against ui/data_views.json, and emitted with itemType 'V'); omit it for a section node (which correctly omits itemType). Bootstrap icon names are normalized to the bare form menus require \u2014 a leading 'bi-' is stripped, unlike action icons which keep it.",
+    inputSchema: { ...menuAddSchema, ...applyInput }
+  },
+  envelope(menuAdd)
+);
+server.registerTool(
   "dforge_report_add",
-  "PHASE 4: Add a report to ui/reports.json. Read dforge://schema/reports for the layout/datasets/parameters shape.",
-  reportAddSchema,
+  {
+    title: "Add a report",
+    description: "PHASE 3: Add a report to ui/reports.json. Read dforge://schema/reports for the layout/datasets/parameters shape.",
+    inputSchema: { ...reportAddSchema, ...applyInput }
+  },
   envelope(reportAdd)
 );
-server.tool(
+server.registerTool(
   "dforge_setting_add",
-  "PHASE 4 (polish): Add a configurable module-level setting to settings.json. Settings are folder-scoped at runtime \u2014 values inherit through the folder tree.",
-  settingAddSchema,
+  {
+    title: "Add a module setting",
+    description: "PHASE 4 (polish): Add a configurable module-level setting to settings.json. Settings are folder-scoped at runtime \u2014 values inherit through the folder tree.",
+    inputSchema: { ...settingAddSchema, ...applyInput }
+  },
   envelope(settingAdd)
 );
-server.tool(
+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.",
+    inputSchema: { ...translationSyncSchema, ...applyInput }
+  },
+  envelope(translationSync)
+);
+server.registerTool(
+  "dforge_seed_add",
+  {
+    title: "Add seed data",
+    description: "PHASE 4: Write a seed-data file for one entity. Enforces the four documented seed traps: an explicit NUMERIC PK under '{entity}_id' (cuid is int8, not a UUID), parent-before-child load order via the NN- filename prefix, created_by/last_updated_by = 0 (System user) on every record of an audit-full entity, and FK values that point at an already-seeded parent. Also rejects seeding a virtual Reference column instead of its hidden FK.",
+    inputSchema: { ...seedAddSchema, ...applyInput }
+  },
+  envelope(seedAdd)
+);
+server.registerTool(
   "dforge_role_add",
-  "PHASE 5: Add a role to security/roles.json. Roles are namespaced (e.g. 'crm.admin'). Rights are S/I/U/D/C for entities, E for actions/reports.",
-  roleAddSchema,
+  {
+    title: "Add a role",
+    description: "PHASE 5: Add a role to security/roles.json. Roles are namespaced (e.g. 'crm.admin'). Rights are S/I/U/D/C for entities, E for actions/reports/folders (which use a COLON prefix). Derive roles from the intake's user types \u2014 never a generic admin/contributor/viewer taxonomy the user didn't ask for.",
+    inputSchema: { ...roleAddSchema, ...applyInput }
+  },
   envelope(roleAdd)
 );
-server.tool(
+server.registerTool(
   "dforge_role_right_set",
-  "PHASE 5 / backtrack: Grant or revoke a single right on a single object for a role. Cheaper than role_add when iterating on rights matrix.",
-  roleRightSetSchema,
+  {
+    title: "Grant or revoke one right",
+    description: "PHASE 5 / backtrack: Grant or revoke a single right on a single object for a role. Cheaper than role_add when iterating on the rights matrix, and the correct tool for amending the scaffolded admin role (role_add fails on an existing code).",
+    inputSchema: { ...roleRightSetSchema, ...applyInput }
+  },
   envelope(roleRightSet)
 );
-server.tool(
+server.registerTool(
   "dforge_folder_add",
-  "PHASE 5 (optional): Add a sub-folder to ui/folders.json. Folders are SECURITY boundaries (row-level filters + per-folder role mappings). Most modules don't need any beyond the root \u2014 only use when intake said data must be separated per folder.",
-  folderAddSchema,
+  {
+    title: "Add a security folder",
+    description: "PHASE 5 (optional): Add a sub-folder to ui/folders.json. Folders are SECURITY boundaries (row-level filters + per-folder role mappings). Most modules don't need any beyond the root \u2014 only use when intake said data must be separated per folder.",
+    inputSchema: { ...folderAddSchema, ...applyInput }
+  },
   envelope(folderAdd)
 );
-server.tool(
+server.registerTool(
   "dforge_dependency_add",
-  "Add a dependency on another dForge module to manifest.json. Use the entities list form when only specific entities are imported (smaller coupling).",
-  dependencyAddSchema,
+  {
+    title: "Add a module dependency",
+    description: "Add a dependency on another dForge module to manifest.json. Use the entities list form when only specific entities are imported (smaller coupling).",
+    inputSchema: { ...dependencyAddSchema, ...applyInput }
+  },
   envelope(dependencyAdd)
 );
-server.tool(
+server.registerTool(
   "dforge_dbml_import",
-  "Generate entities from DBML schema text (a front-end to dforge_module_import). Parses Table blocks, typed columns with [settings], inline [ref: > t.c] and top-level Ref: lines; drops the source PK (the identity trait provides {entity}_id), infers field types via the metadata registry, and builds the FK+Reference pair per relationship. Pass `module` when the dir has no manifest (greenfield). Review inferred types + run dforge_module_validate after.",
-  dbmlImportSchema,
+  {
+    title: "Import entities from DBML",
+    description: "Generate entities from DBML schema text (a front-end to dforge_module_import). Parses Table blocks, typed columns with [settings], inline [ref: > t.c] and top-level Ref: lines; drops the source PK (the identity trait provides {entity}_id), infers field types via the metadata registry, and builds the FK+Reference pair per relationship. Pass `module` when the dir has no manifest (greenfield). Review inferred types + run dforge_module_validate after.",
+    inputSchema: { ...dbmlImportSchema, ...applyInput }
+  },
   envelope(dbmlImport)
 );
 for (const res of resources) {
-  server.resource(res.name, res.uri, async (uri) => ({
-    contents: [
-      {
-        uri: uri.href,
-        mimeType: res.mimeType,
-        text: res.read()
-      }
-    ]
-  }));
+  server.registerResource(
+    res.name,
+    res.uri,
+    { description: res.description, mimeType: res.mimeType },
+    async (uri) => ({
+      contents: [{ uri: uri.href, mimeType: res.mimeType, text: res.read() }]
+    })
+  );
 }
 (async () => {
   const transport = new StdioServerTransport();