@dforge-core/dforge-mcp 0.1.0-rc.9 → 0.1.2

package/dist/server.js

@@ -59,9 +59,9 @@ var require_code = __commonJS({
     };
     exports2.Name = Name;
     var _Code = class extends _CodeOrName {
-      constructor(code) {
+      constructor(code2) {
         super();
-        this._items = typeof code === "string" ? [code] : code;
+        this._items = typeof code2 === "string" ? [code2] : code2;
       }
       toString() {
         return this.str;
@@ -88,13 +88,13 @@ var require_code = __commonJS({
     exports2._Code = _Code;
     exports2.nil = new _Code("");
     function _(strs, ...args) {
-      const code = [strs[0]];
+      const code2 = [strs[0]];
       let i = 0;
       while (i < args.length) {
-        addCodeArg(code, args[i]);
-        code.push(strs[++i]);
+        addCodeArg(code2, args[i]);
+        code2.push(strs[++i]);
       }
-      return new _Code(code);
+      return new _Code(code2);
     }
     exports2._ = _;
     var plus = new _Code("+");
@@ -110,13 +110,13 @@ var require_code = __commonJS({
       return new _Code(expr);
     }
     exports2.str = str;
-    function addCodeArg(code, arg) {
+    function addCodeArg(code2, arg) {
       if (arg instanceof _Code)
-        code.push(...arg._items);
+        code2.push(...arg._items);
       else if (arg instanceof Name)
-        code.push(arg);
+        code2.push(arg);
       else
-        code.push(interpolate(arg));
+        code2.push(interpolate(arg));
     }
     exports2.addCodeArg = addCodeArg;
     function optimize(expr) {
@@ -300,7 +300,7 @@ var require_scope = __commonJS({
         }, usedValues, getCode);
       }
       _reduceValues(values, valueCode, usedValues = {}, getCode) {
-        let code = code_1.nil;
+        let code2 = code_1.nil;
         for (const prefix in values) {
           const vs = values[prefix];
           if (!vs)
@@ -313,16 +313,16 @@ var require_scope = __commonJS({
             let c = valueCode(name);
             if (c) {
               const def = this.opts.es5 ? exports2.varKinds.var : exports2.varKinds.const;
-              code = (0, code_1._)`${code}${def} ${name} = ${c};${this.opts._n}`;
+              code2 = (0, code_1._)`${code2}${def} ${name} = ${c};${this.opts._n}`;
             } else if (c = getCode === null || getCode === void 0 ? void 0 : getCode(name)) {
-              code = (0, code_1._)`${code}${c}${this.opts._n}`;
+              code2 = (0, code_1._)`${code2}${c}${this.opts._n}`;
             } else {
               throw new ValueError(name);
             }
             nameSet.set(name, UsedValueState.Completed);
           });
         }
-        return code;
+        return code2;
       }
     };
     exports2.ValueScope = ValueScope;
@@ -482,9 +482,9 @@ var require_codegen = __commonJS({
       }
     };
     var AnyCode = class extends Node {
-      constructor(code) {
+      constructor(code2) {
         super();
-        this.code = code;
+        this.code = code2;
       }
       render({ _n }) {
         return `${this.code};` + _n;
@@ -506,7 +506,7 @@ var require_codegen = __commonJS({
         this.nodes = nodes;
       }
       render(opts) {
-        return this.nodes.reduce((code, n) => code + n.render(opts), "");
+        return this.nodes.reduce((code2, n) => code2 + n.render(opts), "");
       }
       optimizeNodes() {
         const { nodes } = this;
@@ -554,10 +554,10 @@ var require_codegen = __commonJS({
         this.condition = condition;
       }
       render(opts) {
-        let code = `if(${this.condition})` + super.render(opts);
+        let code2 = `if(${this.condition})` + super.render(opts);
         if (this.else)
-          code += "else " + this.else.render(opts);
-        return code;
+          code2 += "else " + this.else.render(opts);
+        return code2;
       }
       optimizeNodes() {
         super.optimizeNodes();
@@ -678,12 +678,12 @@ var require_codegen = __commonJS({
     Return.kind = "return";
     var Try = class extends BlockNode {
       render(opts) {
-        let code = "try" + super.render(opts);
+        let code2 = "try" + super.render(opts);
         if (this.catch)
-          code += this.catch.render(opts);
+          code2 += this.catch.render(opts);
         if (this.finally)
-          code += this.finally.render(opts);
-        return code;
+          code2 += this.finally.render(opts);
+        return code2;
       }
       optimizeNodes() {
         var _a3, _b;
@@ -800,18 +800,18 @@ var require_codegen = __commonJS({
       }
       // returns code for object literal for the passed argument list of key-value pairs
       object(...keyValues) {
-        const code = ["{"];
+        const code2 = ["{"];
         for (const [key, value] of keyValues) {
-          if (code.length > 1)
-            code.push(",");
-          code.push(key);
+          if (code2.length > 1)
+            code2.push(",");
+          code2.push(key);
           if (key !== value || this.opts.es5) {
-            code.push(":");
-            (0, code_1.addCodeArg)(code, value);
+            code2.push(":");
+            (0, code_1.addCodeArg)(code2, value);
           }
         }
-        code.push("}");
-        return new code_1._Code(code);
+        code2.push("}");
+        return new code_1._Code(code2);
       }
       // `if` clause (or statement if `thenBody` and, optionally, `elseBody` are passed)
       if(condition, thenBody, elseBody) {
@@ -2981,7 +2981,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve5.call(this, root, ref);
+      let _sch = resolve7.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 resolve5(root, ref) {
+    function resolve7(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3111,22 +3111,22 @@ var require_utils = __commonJS({
     var isPathCharacter = RegExp.prototype.test.bind(/^[\da-z\-._~!$&'()*+,;=:@/]$/iu);
     function stringArrayToHexStripped(input) {
       let acc = "";
-      let code = 0;
+      let code2 = 0;
       let i = 0;
       for (i = 0; i < input.length; i++) {
-        code = input[i].charCodeAt(0);
-        if (code === 48) {
+        code2 = input[i].charCodeAt(0);
+        if (code2 === 48) {
           continue;
         }
-        if (!(code >= 48 && code <= 57 || code >= 65 && code <= 70 || code >= 97 && code <= 102)) {
+        if (!(code2 >= 48 && code2 <= 57 || code2 >= 65 && code2 <= 70 || code2 >= 97 && code2 <= 102)) {
           return "";
         }
         acc += input[i];
         break;
       }
       for (i += 1; i < input.length; i++) {
-        code = input[i].charCodeAt(0);
-        if (!(code >= 48 && code <= 57 || code >= 65 && code <= 70 || code >= 97 && code <= 102)) {
+        code2 = input[i].charCodeAt(0);
+        if (!(code2 >= 48 && code2 <= 57 || code2 >= 65 && code2 <= 70 || code2 >= 97 && code2 <= 102)) {
           return "";
         }
         acc += input[i];
@@ -3226,8 +3226,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path8) {
-      let input = path8;
+    function removeDotSegments(path12) {
+      let input = path12;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3479,8 +3479,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path8, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path8 && path8 !== "/" ? path8 : void 0;
+        const [path12, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path12 && path12 !== "/" ? path12 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -3639,7 +3639,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve5(baseURI, relativeURI, options) {
+    function resolve7(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;
@@ -3897,7 +3897,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve5,
+      resolve: resolve7,
       resolveComponent,
       equal,
       serialize,
@@ -6145,8 +6145,8 @@ var require_format = __commonJS({
             }
           }
           function getFormat(fmtDef) {
-            const code = fmtDef instanceof RegExp ? (0, codegen_1.regexpCode)(fmtDef) : opts.code.formats ? (0, codegen_1._)`${opts.code.formats}${(0, codegen_1.getProperty)(schema2)}` : void 0;
-            const fmt = gen.scopeValue("formats", { key: schema2, ref: fmtDef, code });
+            const code2 = fmtDef instanceof RegExp ? (0, codegen_1.regexpCode)(fmtDef) : opts.code.formats ? (0, codegen_1._)`${opts.code.formats}${(0, codegen_1.getProperty)(schema2)}` : void 0;
+            const fmt = gen.scopeValue("formats", { key: schema2, ref: fmtDef, code: code2 });
             if (typeof fmtDef == "object" && !(fmtDef instanceof RegExp)) {
               return [fmtDef.type || "string", fmtDef.validate, (0, codegen_1._)`${fmt}.validate`];
             }
@@ -6873,12 +6873,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs6, exportName) {
+    function addFormats(ajv, list, fs10, 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, fs6[f]);
+        ajv.addFormat(f, fs10[f]);
     }
     module2.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -7245,8 +7245,8 @@ function getErrorMap() {
 
 // node_modules/.pnpm/zod@4.4.3/node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path8, errorMaps, issueData } = params;
-  const fullPath = [...path8, ...issueData.path || []];
+  const { data, path: path12, errorMaps, issueData } = params;
+  const fullPath = [...path12, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -7361,11 +7361,11 @@ var errorUtil;
 
 // node_modules/.pnpm/zod@4.4.3/node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path8, key) {
+  constructor(parent, value, path12, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path8;
+    this._path = path12;
     this._key = key;
   }
   get path() {
@@ -11285,10 +11285,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema2) {
   return mergeDefs(schema2._zod.def);
 }
-function getElementAtPath(obj, path8) {
-  if (!path8)
+function getElementAtPath(obj, path12) {
+  if (!path12)
     return obj;
-  return path8.reduce((acc, key) => acc?.[key], obj);
+  return path12.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -11697,11 +11697,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path8, issues) {
+function prefixIssues(path12, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path8);
+    iss.path.unshift(path12);
     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, path8 = []) => {
+  const processError = (error52, path12 = []) => {
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path8, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path12, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path8, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path8, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
       } else {
-        const fullpath = [...path8, ...issue2.path];
+        const fullpath = [...path12, ...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, path8 = []) => {
+  const processError = (error52, path12 = []) => {
     var _a3, _b;
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path8, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path12, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path8, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path8, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path12, ...issue2.path]);
       } else {
-        const fullpath = [...path8, ...issue2.path];
+        const fullpath = [...path12, ...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 path8 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path8) {
+  const path12 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path12) {
     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 path8 = ref.slice(1).split("/").filter(Boolean);
-  if (path8.length === 0) {
+  const path12 = ref.slice(1).split("/").filter(Boolean);
+  if (path12.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path8[0] === defsKey) {
-    const key = path8[1];
+  if (path12[0] === defsKey) {
+    const key = path12[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -26967,23 +26967,23 @@ var ServerResultSchema = union([
   CreateTaskResultSchema
 ]);
 var McpError = class _McpError extends Error {
-  constructor(code, message, data) {
-    super(`MCP error ${code}: ${message}`);
-    this.code = code;
+  constructor(code2, message, data) {
+    super(`MCP error ${code2}: ${message}`);
+    this.code = code2;
     this.data = data;
     this.name = "McpError";
   }
   /**
    * Factory method to create the appropriate error type based on the error code and data
    */
-  static fromError(code, message, data) {
-    if (code === ErrorCode.UrlElicitationRequired && data) {
+  static fromError(code2, message, data) {
+    if (code2 === ErrorCode.UrlElicitationRequired && data) {
       const errorData = data;
       if (errorData.elicitations) {
         return new UrlElicitationRequiredError(errorData.elicitations, message);
       }
     }
-    return new _McpError(code, message, data);
+    return new _McpError(code2, message, data);
   }
 };
 var UrlElicitationRequiredError = class extends McpError {
@@ -28828,7 +28828,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve5) => setTimeout(resolve5, pollInterval));
+        await new Promise((resolve7) => setTimeout(resolve7, 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((resolve5, reject) => {
+    return new Promise((resolve7, reject) => {
       const earlyReject = (error51) => {
         reject(error51);
       };
@@ -28923,7 +28923,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve5(parseResult.data);
+            resolve7(parseResult.data);
           }
         } catch (error51) {
           reject(error51);
@@ -29184,12 +29184,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve5, reject) => {
+    return new Promise((resolve7, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve5, interval);
+      const timeoutId = setTimeout(resolve7, 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((resolve5) => setTimeout(resolve5, pollInterval));
+      await new Promise((resolve7) => setTimeout(resolve7, 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((resolve5) => {
+    return new Promise((resolve7) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve5();
+        resolve7();
       } else {
-        this._stdout.once("drain", resolve5);
+        this._stdout.once("drain", resolve7);
       }
     });
   }
@@ -30951,8 +30951,10 @@ var StdioServerTransport = class {
 
 // src/tools/create-module.ts
 var import_node_crypto = require("crypto");
+var fs2 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.1.2/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.2/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -30979,12 +30981,12 @@ function buildManifest(opts, moduleId) {
   return manifest;
 }
 function buildEntity(entity) {
-  const traits = entity.traits === "identity+audit" ? ["identity", "audit"] : ["identity"];
+  const traits2 = entity.traits === "identity+audit" ? ["identity", "audit"] : ["identity"];
   return {
     description: entity.label,
     dbObject: entity.name,
     toString: "{id}",
-    traits,
+    traits: traits2,
     fields: {}
   };
 }
@@ -31113,8 +31115,412 @@ function buildZedSettings() {
   };
 }
 
+// src/tools/_helpers.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+
+// node_modules/.pnpm/@dforge-core+metadata@0.0.2/node_modules/@dforge-core/metadata/dist/aggregation.js
+var AggType = {
+  Sum: "sum",
+  Count: "count",
+  Avg: "avg",
+  Min: "min",
+  Max: "max",
+  Group: "group"
+};
+var AGG_TYPE_LIST = Object.values(AggType);
+
+// node_modules/.pnpm/@dforge-core+metadata@0.0.2/node_modules/@dforge-core/metadata/dist/field-types.js
+var fieldTypes = [
+  { cd: "text", name: "Text", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "email", name: "Email", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "phone", name: "Phone", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "url", name: "URL", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "textarea", name: "Multiline Text", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "number", name: "Number", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: null, useStringInFilter: false, defParams: { min: 0, max: 1e4 } },
+  { cd: "currency", name: "Currency", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: 2, useStringInFilter: false, defParams: { min: 0, max: 1e6 } },
+  { cd: "percent", name: "Percent", columnType: "D", baseDatatypeCd: "number", supportedAgg: "CAM", maxLen: null, precision: 2, useStringInFilter: false, defParams: { min: 0, max: 100 } },
+  { cd: "checkbox", name: "Checkbox", columnType: "D", baseDatatypeCd: "bool", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "date", name: "Date", columnType: "D", baseDatatypeCd: "date", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "datetime", name: "Date & Time", columnType: "D", baseDatatypeCd: "timestamp", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "time", name: "Time", columnType: "D", baseDatatypeCd: "time", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "dropdown", name: "Dropdown", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "flags", name: "Flags", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true, defParams: { style: "buttons" } },
+  { cd: "json", name: "JSON Editor", columnType: "D", baseDatatypeCd: "json", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "hidden", name: "Hidden", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "color", name: "Color Picker", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: 20, precision: null, useStringInFilter: false },
+  { cd: "image", name: "Image", columnType: "D", baseDatatypeCd: "binary", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "file", name: "File", columnType: "D", baseDatatypeCd: "binary", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "richtext", name: "Rich Text Editor", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "lookup", name: "Lookup", columnType: "R", baseDatatypeCd: "guid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "user", name: "User Picker", columnType: "D", baseDatatypeCd: "cuid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "grid", name: "Detail Grid", columnType: "S", baseDatatypeCd: "set", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "tags", name: "Tags", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "entitylink", name: "Entity Link", columnType: "D", baseDatatypeCd: "json", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "code", name: "Code Editor", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false }
+];
+var byCd = new Map(fieldTypes.map((ft) => [ft.cd, ft]));
+var fieldTypeCds = new Set(fieldTypes.map((ft) => ft.cd));
+function isFieldTypeCd(cd) {
+  return cd != null && fieldTypeCds.has(cd);
+}
+function getFieldType(cd) {
+  return byCd.get(cd);
+}
+
+// node_modules/.pnpm/@dforge-core+metadata@0.0.2/node_modules/@dforge-core/metadata/dist/base-datatypes.js
+var BASE_TO_DB = {
+  binary: "bytea",
+  bool: "bool",
+  culture: "varchar",
+  cuid: "cuid",
+  date: "date",
+  guid: "uuid",
+  json: "jsonb",
+  link: null,
+  number: "numeric",
+  project: "varchar",
+  ref: null,
+  set: null,
+  string: "varchar",
+  time: "time",
+  timestamp: "timestamptz",
+  xml: "xml"
+};
+function baseToDbDatatype(base) {
+  return BASE_TO_DB[base] ?? null;
+}
+
+// node_modules/.pnpm/@dforge-core+metadata@0.0.2/node_modules/@dforge-core/metadata/dist/column-types.js
+var columnTypes = [
+  { cd: "D", name: "Value", description: "A plain data column stored on this entity." },
+  { cd: "R", name: "Reference", description: "An N:1 lookup to another entity (foreign key)." },
+  { cd: "S", name: "Child list", description: "A 1:N collection of child records from another entity." },
+  { cd: "F", name: "Formula", description: "A virtual value calculated from a formula expression." },
+  { cd: "G", name: "Generated", description: "A physical column auto-maintained by the database (aggregate or expression)." },
+  { cd: "A", name: "Accumulation register", description: "Posts this document into a balance entity (single direction)." },
+  { cd: "L", name: "Ledger register", description: "Posts document lines into movements + balances (double entry)." }
+];
+var byCd2 = new Map(columnTypes.map((ct) => [ct.cd, ct]));
+function getColumnType(cd) {
+  return byCd2.get(cd);
+}
+
+// node_modules/.pnpm/@dforge-core+metadata@0.0.2/node_modules/@dforge-core/metadata/dist/traits.js
+var traits = [
+  {
+    cd: "identity",
+    description: "Primary Key",
+    fields: {
+      "{entity}_id": { dbDatatype: "cuid", flags: "I", isPk: true, isIdentity: true, isNullable: false, orderNum: 1, description: "{Entity} ID" }
+    }
+  },
+  {
+    cd: "audit",
+    description: "Creation and update timestamps",
+    fields: {
+      created_date: { dbDatatype: "timestamptz", fieldTypeCd: "datetime", flags: "I", isNullable: false, formula: "NOW()", orderNum: 9901, description: "Created Date" },
+      last_updated: { dbDatatype: "timestamptz", fieldTypeCd: "datetime", flags: "I", isNullable: false, formula: "NOW()", orderNum: 9902, description: "Last Updated" }
+    }
+  },
+  {
+    cd: "audit-full",
+    description: "Full audit with user tracking",
+    includes: ["audit"],
+    fields: {
+      created_by: { dbDatatype: "cuid", flags: "I", isNullable: false, orderNum: 9903, description: "Created By User ID" },
+      created_by_user: { columnType: "R", fieldTypeCd: "lookup", flags: "I", orderNum: 9904, description: "Created By", link: { entity: "user", thisKey: "created_by", otherKey: "user_id" } },
+      last_updated_by: { dbDatatype: "cuid", flags: "I", isNullable: false, orderNum: 9905, description: "Last Updated By User ID" },
+      last_updated_by_user: { columnType: "R", fieldTypeCd: "lookup", flags: "I", orderNum: 9906, description: "Last Updated By", link: { entity: "user", thisKey: "last_updated_by", otherKey: "user_id" } }
+    },
+    references: {
+      "FK_{Entity}_CreatedBy": { from: { field: "created_by" }, to: { entity: "user", field: "user_id" } },
+      "FK_{Entity}_LastUpdatedBy": { from: { field: "last_updated_by" }, to: { entity: "user", field: "user_id" } }
+    }
+  },
+  {
+    cd: "soft-delete",
+    description: "Soft delete flag",
+    fields: {
+      active: { dbDatatype: "bool", fieldTypeCd: "checkbox", flags: "", isNullable: false, formula: "true", orderNum: 9910, description: "Active" }
+    }
+  },
+  {
+    cd: "sorting",
+    description: "Display order",
+    fields: {
+      order_num: { dbDatatype: "int4", fieldTypeCd: "number", flags: "VEM", orderNum: 9920, description: "Order" }
+    }
+  },
+  { cd: "postable", description: "Document posting support (marker trait \u2014 actual state managed by A/L columns)", fields: {} },
+  { cd: "accumulation", description: "Accumulation register (marker trait \u2014 config in A-type column params)", fields: {} },
+  { cd: "ledger", description: "Double-entry ledger (marker trait \u2014 config in L-type column params)", fields: {} },
+  {
+    cd: "period",
+    description: "Period entity with key format, closed flag, date range",
+    fields: {
+      period_key: { dbDatatype: "varchar", fieldTypeCd: "text", flags: "VEM", isPk: true, isNullable: false, maxLen: 20, orderNum: 1, description: "Period Key" },
+      description: { dbDatatype: "varchar", fieldTypeCd: "text", flags: "VEM", maxLen: 100, orderNum: 30, description: "Description" },
+      closed: { dbDatatype: "bool", fieldTypeCd: "checkbox", flags: "VEM", isNullable: false, formula: "false", orderNum: 40, description: "Closed" },
+      start_date: { dbDatatype: "date", fieldTypeCd: "date", flags: "VEM", orderNum: 50, description: "Start Date" },
+      end_date: { dbDatatype: "date", fieldTypeCd: "date", flags: "VEM", orderNum: 60, description: "End Date" }
+    }
+  }
+];
+var byCd3 = new Map(traits.map((t) => [t.cd, t]));
+function titleCaseEntity(entity) {
+  const local = entity.split(".").pop() ?? entity;
+  return local.split(/[_\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function applyTemplate(value, entity) {
+  const local = entity.split(".").pop() ?? entity;
+  return value.replace(/\{entity\}/g, local).replace(/\{Entity\}/g, titleCaseEntity(entity));
+}
+function templateFields(fields, entity) {
+  const out = {};
+  for (const [name, def] of Object.entries(fields)) {
+    const key = applyTemplate(name, entity);
+    const next = { ...def };
+    if (typeof next.description === "string")
+      next.description = applyTemplate(next.description, entity);
+    out[key] = next;
+  }
+  return out;
+}
+function expandTrait(traitCd, entityName) {
+  const trait = byCd3.get(traitCd);
+  if (!trait)
+    return {};
+  const result = {};
+  for (const included of trait.includes ?? []) {
+    Object.assign(result, expandTrait(included, entityName));
+  }
+  Object.assign(result, templateFields(trait.fields, entityName));
+  return result;
+}
+function expandTraits(traitCds, entityName) {
+  const result = {};
+  for (const cd of traitCds)
+    Object.assign(result, expandTrait(cd, entityName));
+  return result;
+}
+
+// node_modules/.pnpm/@dforge-core+metadata@0.0.2/node_modules/@dforge-core/metadata/dist/derive.js
+var NUMERIC_TOTAL = 18;
+var TEXT_BACKED = /* @__PURE__ */ new Set(["textarea", "richtext", "code"]);
+function deriveDbDatatype(fieldTypeCd, options = {}) {
+  const ft = getFieldType(fieldTypeCd);
+  if (!ft)
+    return "varchar";
+  if (ft.columnType === "R" || ft.columnType === "S")
+    return null;
+  const base = baseToDbDatatype(ft.baseDatatypeCd);
+  if (base === null)
+    return null;
+  if (ft.baseDatatypeCd === "number") {
+    const precision = options.precision ?? ft.precision;
+    return precision != null ? `numeric(${NUMERIC_TOTAL},${precision})` : "numeric";
+  }
+  if (ft.baseDatatypeCd === "string") {
+    if (TEXT_BACKED.has(ft.cd))
+      return "text";
+    const maxLen = options.maxLen ?? ft.maxLen;
+    return maxLen != null ? `varchar(${maxLen})` : "varchar";
+  }
+  return base;
+}
+
+// src/tools/_helpers.ts
+function modulePaths(moduleDir) {
+  const root = path.resolve(moduleDir);
+  return {
+    root,
+    manifest: path.join(root, "manifest.json"),
+    entitiesDir: path.join(root, "entities"),
+    uiDir: path.join(root, "ui"),
+    securityDir: path.join(root, "security"),
+    logicDir: path.join(root, "logic"),
+    seedDataDir: path.join(root, "seed-data"),
+    translationsDir: path.join(root, "translations"),
+    dataViews: path.join(root, "ui", "data_views.json"),
+    folders: path.join(root, "ui", "folders.json"),
+    menus: path.join(root, "ui", "menus.json"),
+    actions: path.join(root, "ui", "actions.json"),
+    reports: path.join(root, "ui", "reports.json"),
+    queries: path.join(root, "ui", "queries.json"),
+    printTemplates: path.join(root, "ui", "print_templates.json"),
+    roles: path.join(root, "security", "roles.json"),
+    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")
+  };
+}
+function readJson(absPath) {
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`Not found: ${absPath}`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8"));
+  } catch (e) {
+    throw new Error(`${absPath}: ${e.message}`);
+  }
+}
+function readJsonOrDefault(absPath, dflt) {
+  if (!fs.existsSync(absPath)) return dflt;
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8"));
+  } catch (e) {
+    throw new Error(`${absPath}: ${e.message}`);
+  }
+}
+function jsonText(obj) {
+  return JSON.stringify(obj, null, "	") + "\n";
+}
+function rel(root, abs) {
+  return path.relative(root, abs);
+}
+function loadManifest(moduleDir) {
+  const paths = modulePaths(moduleDir);
+  if (!fs.existsSync(paths.manifest)) {
+    throw new Error(
+      `No manifest.json at ${paths.manifest} \u2014 is this a dForge module directory?`
+    );
+  }
+  const manifest = readJson(paths.manifest);
+  if (!manifest.code) {
+    throw new Error("manifest.json has no `code` field \u2014 corrupt module?");
+  }
+  return { manifest, paths };
+}
+function makeResult(summary, files, warning, deletes) {
+  const out = { summary, files };
+  if (warning) out.warning = warning;
+  if (deletes && deletes.length) out.deletes = deletes;
+  return out;
+}
+function withTodayStamp(manifest) {
+  return { ...manifest, updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10) };
+}
+var PHASE_STATE_FILE = "docs/phase.json";
+function phaseStateJson(state) {
+  return JSON.stringify(state, null, "	") + "\n";
+}
+function readPhaseState(moduleDir) {
+  const p = path.join(path.resolve(moduleDir), PHASE_STATE_FILE);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isReadyToScaffold(moduleDir) {
+  const state = readPhaseState(moduleDir);
+  if (state && typeof state.readyToScaffold === "boolean") return state.readyToScaffold;
+  const v = path.join(path.resolve(moduleDir), "docs", "VALIDATION.md");
+  return fs.existsSync(v) && fs.readFileSync(v, "utf8").includes("readyToScaffold: true");
+}
+var RIGHTS_ENTITY = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
+var RIGHTS_OBJECT = /^(action|report|folder):[a-z][a-z0-9_]*$/;
+var RIGHTS_OBJECT_DOT = /^(action|report|folder)\.[a-z]/;
+function assertValidRightKey(key) {
+  if (RIGHTS_OBJECT_DOT.test(key)) {
+    const fixed = key.replace(".", ":");
+    throw new Error(
+      `Rights key '${key}' uses a dot for an action/report/folder \u2014 use a colon: '${fixed}'. (A dot is only for cross-module entities like 'fin.invoice'.)`
+    );
+  }
+  if (RIGHTS_OBJECT.test(key) || RIGHTS_ENTITY.test(key)) return;
+  throw new Error(
+    `Invalid rights key '${key}'. Use a same-module entity ('product'), a cross-module entity ('fin.invoice'), or a colon-prefixed object ('action:approve', 'report:summary', 'folder:east').`
+  );
+}
+function assertValidRightValue(key, value, allowEmpty) {
+  if (value === "") {
+    if (allowEmpty) return;
+    throw new Error(
+      `Rights on '${key}' is an empty string. To deny access, omit the key entirely; to grant, use rights letters.`
+    );
+  }
+  if (!/^[SIUDCE]+$/.test(value)) {
+    throw new Error(
+      `Invalid rights '${value}' on '${key}'. Use S/I/U/D/C for entities, or 'E' for actions/reports/folders.`
+    );
+  }
+  const isObject2 = /^(action|report|folder):/.test(key);
+  if (isObject2 && value !== "E") {
+    throw new Error(`Object '${key}' takes 'E' (Execute), got '${value}'.`);
+  }
+  if (!isObject2 && value.includes("E")) {
+    throw new Error(
+      `'${key}' is granted 'E' but has no action:/report:/folder: prefix \u2014 entity rights are S/I/U/D/C. If '${key}' is an action or report, prefix it (e.g. 'action:${key}' or 'report:${key}').`
+    );
+  }
+}
+function assertValidRights(rights) {
+  for (const [key, value] of Object.entries(rights)) {
+    assertValidRightKey(key);
+    assertValidRightValue(key, value, false);
+  }
+}
+function checkSecurityCoverage(moduleDir) {
+  const { manifest, paths } = loadManifest(moduleDir);
+  const entities = Object.keys(manifest.entities ?? {}).filter((k) => !k.includes("."));
+  const roles = readJsonOrDefault(paths.roles, {});
+  const grantedSelect = /* @__PURE__ */ new Set();
+  const grantedExec = /* @__PURE__ */ new Set();
+  for (const role of Object.values(roles)) {
+    for (const [obj, r] of Object.entries(role?.rights ?? {})) {
+      if (typeof r !== "string") continue;
+      if (r.includes("S")) grantedSelect.add(obj);
+      if (r.includes("E")) grantedExec.add(obj);
+    }
+  }
+  const uncoveredEntities = entities.filter((e) => !grantedSelect.has(e));
+  const actions = Object.keys(readJsonOrDefault(paths.actions, {}));
+  const reports = Object.keys(readJsonOrDefault(paths.reports, {}));
+  const uncoveredObjects = [
+    ...actions.filter((a) => !grantedExec.has(`action:${a}`)).map((a) => `action:${a}`),
+    ...reports.filter((r) => !grantedExec.has(`report:${r}`)).map((r) => `report:${r}`)
+  ];
+  return { uncoveredEntities, uncoveredObjects };
+}
+function assertSecurityCoverage(moduleDir) {
+  const { uncoveredEntities, uncoveredObjects } = checkSecurityCoverage(moduleDir);
+  if (uncoveredEntities.length > 0) {
+    throw new Error(
+      `Phase 5a (security) incomplete \u2014 no role grants Select (S) on: ${uncoveredEntities.join(", ")}. Every entity must appear in at least one role's rights with at least 'S'. Add or extend roles with dforge_role_add / dforge_role_right_set, then re-pack.`
+    );
+  }
+  if (uncoveredObjects.length > 0) {
+    return `Security note \u2014 no role grants Execute (E) on: ${uncoveredObjects.join(", ")}. Add 'E' grants if a role should run these.`;
+  }
+  return void 0;
+}
+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) => {
+  for (const cd of arr) {
+    if (!TRAIT_CODE_SET.has(cd)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        message: `trait '${cd}' is not a valid trait. Valid: ${TRAIT_CODES.join(", ")}. (See dforge://reference/traits.)`
+      });
+    }
+  }
+}).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 withTraits(entity, traitCodes) {
+  return { ...entity, traits: [...traitCodes] };
+}
+
 // src/tools/create-module.ts
 var createModuleSchema = {
+  moduleDir: external_exports.string().describe(
+    "Absolute path to the directory where the module will be written. Phase 0 must be validated first \u2014 dforge_module_plan validate writes a docs/phase.json marker that this gate reads (readyToScaffold: true)."
+  ),
   code: external_exports.string().regex(/^[a-z][a-z0-9_-]*$/).describe("Module code, e.g. 'crm' or 'hr-admin'. Lowercase, digits, underscore, hyphen; first char a letter."),
   displayName: external_exports.string().min(1).describe("Human-readable module name."),
   description: external_exports.string().optional().describe("Optional short description."),
@@ -31122,18 +31528,50 @@ var createModuleSchema = {
   license: external_exports.string().default("MIT"),
   version: external_exports.string().regex(/^\d+\.\d+\.\d+(-[\w.]+)?$/).default("0.1.0"),
   dbSchemaVersion: external_exports.string().regex(/^\d+\.\d+\.\d+(-[\w.]+)?$/).default("0.0.1"),
-  dependencies: external_exports.array(external_exports.string()).default(["admin", "metadata"]).describe("System modules this module depends on. Usually ['admin', 'metadata']."),
+  dependencies: external_exports.array(external_exports.string()).default([]).describe("Other modules this one requires, by code (e.g. ['parties']). Leave empty unless it genuinely depends on another module. Do NOT list 'admin' or 'metadata' \u2014 they're system modules present in every tenant, so depending on them is redundant (the check always passes and never affects install order)."),
   preset: external_exports.enum(["minimal", "minimal-plus", "full"]).default("minimal").describe("'minimal' = manifest+entity+UI+role only. 'full' = also settings/translations/seed-data/logic stubs. 'minimal-plus' behaves like 'minimal' here since MCP can't loop; pass all entities up-front."),
   entities: external_exports.array(
     external_exports.object({
       name: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Entity code, e.g. 'customer'. Lowercase, digits, underscore; first char a letter."),
       label: external_exports.string().min(1),
-      traits: external_exports.enum(["identity", "identity+audit"]).default("identity+audit")
+      traits: traitsInput
     })
   ).min(1).describe("At least one entity. Each entity gets a stub JSON, a default grid view, a menu item, and rights in the admin role.")
 };
+function assertPhase0Complete(moduleDir) {
+  const root = path2.resolve(moduleDir);
+  const required2 = [
+    { rel: "CLAUDE.md", phase: "0a" },
+    { rel: "docs/REQUIREMENTS.md", phase: "0b" },
+    { rel: "docs/DESIGN.md", phase: "0c" },
+    { rel: "docs/VALIDATION.md", phase: "0d" }
+  ];
+  const missing = required2.filter((f) => !fs2.existsSync(path2.join(root, f.rel)));
+  if (missing.length > 0) {
+    const lines = missing.map((f) => `  \u2717 Phase ${f.phase}: ${f.rel}`).join("\n");
+    throw new Error(
+      `Phase 0 incomplete \u2014 cannot scaffold yet.
+${lines}
+
+Run dforge_module_plan({ action: "check", moduleDir: "${moduleDir}" }) to see what's needed.`
+    );
+  }
+  if (!isReadyToScaffold(root)) {
+    throw new Error(
+      `Phase 0 incomplete \u2014 design validation has not passed (no readyToScaffold marker in ${PHASE_STATE_FILE} or docs/VALIDATION.md).
+
+Run dforge_module_plan({ action: "validate", moduleDir: "${moduleDir}" }) to complete Phase 0d.`
+    );
+  }
+}
 function createModuleFiles(args) {
+  assertPhase0Complete(args.moduleDir);
   const moduleId = (0, import_node_crypto.randomUUID)();
+  const traitsByName = {};
+  const specEntities = args.entities.map((e) => {
+    traitsByName[e.name] = e.traits;
+    return { name: e.name, label: e.label, traits: "identity" };
+  });
   const opts = {
     path: "",
     // unused: builders don't write paths into output
@@ -31146,7 +31584,7 @@ function createModuleFiles(args) {
     dbSchemaVersion: args.dbSchemaVersion,
     dependencies: args.dependencies,
     preset: args.preset,
-    entities: args.entities
+    entities: specEntities
   };
   const files = {};
   const write = (rel2, obj) => {
@@ -31157,7 +31595,7 @@ function createModuleFiles(args) {
   };
   write("manifest.json", buildManifest(opts, moduleId));
   for (const e of opts.entities) {
-    write(`entities/${e.name}.json`, buildEntity(e));
+    write(`entities/${e.name}.json`, withTraits(buildEntity(e), traitsByName[e.name]));
   }
   write("ui/data_views.json", buildDataViews(opts.entities));
   write("ui/folders.json", buildFolders(opts));
@@ -31178,72 +31616,639 @@ function createModuleFiles(args) {
   return files;
 }
 
-// src/tools/add-entity.ts
-var fs = __toESM(require("fs"));
-var path = __toESM(require("path"));
-var addEntitySchema = {
-  moduleDir: external_exports.string().describe("Absolute or relative path to an existing module directory (contains manifest.json)."),
-  entity: external_exports.object({
-    name: external_exports.string().regex(/^[a-z][a-z0-9_]*$/),
-    label: external_exports.string().min(1),
-    traits: external_exports.enum(["identity", "identity+audit"]).default("identity+audit")
-  })
+// src/tools/plan-module.ts
+var fs3 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+var P0 = {
+  identity: "CLAUDE.md",
+  requirements: "docs/REQUIREMENTS.md",
+  design: "docs/DESIGN.md",
+  validation: "docs/VALIDATION.md",
+  phaseState: PHASE_STATE_FILE
+};
+var DESIGN_TEMPLATE = `# Design Document
+<!-- written after Phase 0c approval \u2014 edit with care -->
+
+## Entity List
+<name \u2014 one-line purpose, ordered least- to most-dependent>
+
+## Fields per Entity
+### <EntityName>
+<key fields, status values, formulas, number sequences>
+
+## Relationship Map
+<!-- crow's-foot cardinality: ||--o{ = required N:1 (child must have a parent); |o--o{ = optional N:1. One edge per FK; replace names with your entities. -->
+\`\`\`mermaid
+erDiagram
+    parent_entity ||--o{ child_entity : "verb"
+    lookup_entity |o--o{ child_entity : "verb"
+\`\`\`
+
+| Relationship (child FK \u2192 parent PK) | Required |
+|-------------------------------------|----------|
+| child_entity.parent_id \u2192 parent_entity.id | required |
+| child_entity.lookup_id \u2192 lookup_entity.id | optional |
+
+Total FKs: <N>
+
+## Status Machines
+### <EntityName>
+| Status | Transitions via | canExecute guard | Recovery |
+|--------|----------------|-----------------|----------|
+
+## Actions
+| Name | Target Entity | Description | Params |
+|------|--------------|-------------|--------|
+
+## Seed Data
+<entity name \u2014 rows needed, in parent-before-child order>
+
+## Number Sequences
+<column \u2192 pattern, or "None">
+
+## Reports & Queries
+<report/query name \u2014 entity, key columns; or "None">
+
+## Special Behaviors
+<entity \u2014 soft-delete? sorting? webhooks? print templates? \u2014 or "None">
+
+## Gaps & Proposals
+<findings from the gap detection pass, or omit this section if none>
+
+---
+*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."
+  ),
+  moduleDir: external_exports.string().describe(
+    "Absolute path to the module directory. Ask the user for this before the first call."
+  ),
+  // ── write_identity fields (Phase 0a) ────────────────────────────────
+  displayName: external_exports.string().optional().describe("[write_identity] Human-readable module name, e.g. 'Purchase Orders'."),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe(
+    "[write_identity] snake_case module code, e.g. 'purchase_orders'. Becomes the DB schema name."
+  ),
+  dependencies: external_exports.array(external_exports.string()).optional().describe(
+    "[write_identity] Other dForge module codes this module depends on. admin + metadata are always implicit."
+  ),
+  locales: external_exports.array(external_exports.string()).optional().describe("[write_identity] Locale codes, e.g. ['en-US', 'de-DE']. Default: ['en-US']."),
+  preset: external_exports.enum(["minimal", "minimal-plus", "full"]).optional().describe(
+    "[write_identity] Scaffold depth: minimal = entities + views + role; full = + settings + translations + seed-data stubs."
+  ),
+  // ── write_requirements / write_design fields (Phase 0b / 0c) ────────
+  userConfirmed: external_exports.boolean().optional().describe(
+    "[write_requirements, write_design] MUST be true \u2014 only set after the user has reviewed the on-disk draft (docs/REQUIREMENTS.md / docs/DESIGN.md, already written by you) and explicitly confirmed (replied YES / 'looks good' / 'confirmed')."
+  ),
+  // ── validate fields (Phase 0d) ───────────────────────────────────────
+  checkResults: external_exports.array(
+    external_exports.object({
+      check: external_exports.string().describe("Check name, e.g. 'Persona \u2192 entity coverage'."),
+      pass: external_exports.boolean(),
+      detail: external_exports.string().describe("One sentence explaining the pass or failure.")
+    })
+  ).optional().describe(
+    "[validate] Semantic check results from agent evaluation. Omit on the first call (structural pre-check only). Provide after evaluating the returned semanticChecks."
+  )
 };
-function addEntityFiles(args) {
-  const root = path.resolve(args.moduleDir);
-  const manifestPath = path.join(root, "manifest.json");
-  if (!fs.existsSync(manifestPath)) {
-    throw new Error(`No manifest.json found at ${manifestPath}`);
+function planModule(rawArgs) {
+  const root = path3.resolve(rawArgs.moduleDir);
+  switch (rawArgs.action) {
+    case "check":
+      return handleCheck(root);
+    case "write_identity":
+      return handleWriteIdentity(root, rawArgs);
+    case "write_requirements":
+      return handleWriteRequirements(root, rawArgs);
+    case "write_design":
+      return handleWriteDesign(root, rawArgs);
+    case "validate":
+      return handleValidate(root, rawArgs);
+  }
+}
+function handleCheck(root) {
+  const claudePath = path3.join(root, P0.identity);
+  const reqPath = path3.join(root, P0.requirements);
+  const designPath = path3.join(root, P0.design);
+  const has0a = fileExists(claudePath);
+  const claudeContent = has0a ? readFile(claudePath) : "";
+  const has0b = has0a && /- \[x\] \*\*0b\*\*/.test(claudeContent);
+  const has0c = has0b && /- \[x\] \*\*0c\*\*/.test(claudeContent);
+  const has0d = has0c && isReadyToScaffold(root);
+  const completed = [];
+  if (has0a) completed.push("0a");
+  if (has0b) completed.push("0b");
+  if (has0c) completed.push("0c");
+  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."
+    };
   }
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-  if (!manifest.code) {
-    throw new Error("manifest.json has no `code` field \u2014 corrupt module?");
+  if (!has0a) {
+    return {
+      summary: "Phase 0 not started.",
+      currentPhase: "0a",
+      completed,
+      pending,
+      readyToScaffold: false,
+      nextStep: "Phase 0a \u2014 Module Identity. Ask the user these questions ONE AT A TIME. After each answer, restate what you understood and confirm before continuing.",
+      questions: [
+        `What's the module's display name? (e.g. "Purchase Orders", "HR Leave Requests")`,
+        "What code should it use? (snake_case, letters + digits + underscores \u2014 becomes the DB schema name; suggest a default derived from the display name)",
+        "Does this module depend on any other dForge modules \u2014 e.g. needing entities from 'crm' or 'parties'? (admin and metadata are platform-implicit; list any others, or say None)",
+        "English only, or any other locales the module needs to ship with translations for?",
+        "How complete should the initial scaffold be? (minimal = entities + default views + single admin role; minimal-plus = + settings/translation stubs; full = + logic stubs + seed data structure)"
+      ],
+      writeAction: "Once all answers are collected and reflected back, call dforge_module_plan({ action: 'write_identity', moduleDir, displayName, code, dependencies, locales, preset })."
+    };
   }
-  const newName = args.entity.name;
-  if (manifest.entities && manifest.entities[newName]) {
+  if (!has0b) {
+    if (fileExists(reqPath)) {
+      return {
+        summary: "Phase 0a complete. A draft docs/REQUIREMENTS.md exists on disk but hasn't been confirmed yet.",
+        currentPhase: "0b",
+        completed,
+        pending,
+        readyToScaffold: false,
+        nextStep: "Read docs/REQUIREMENTS.md. Give the user a short outline (section headings + counts) and gap status (open items, or 'No gaps'), then ask them to review the file and reply YES, or describe what to change. If they request changes, edit docs/REQUIREMENTS.md directly (targeted edits), summarize the change in one line, and ask again. Once they reply YES, call dforge_module_plan({ action: 'write_requirements', moduleDir, userConfirmed: true })."
+      };
+    }
+    return {
+      summary: "Phase 0a complete. Proceed to Phase 0b intake.",
+      currentPhase: "0b",
+      completed,
+      pending,
+      readyToScaffold: false,
+      nextStep: "Phase 0b \u2014 Intake. Ask the user these questions ONE AT A TIME in free-form prose. After each answer, restate what you understood and confirm before continuing. Do NOT use pickers or predefined options.",
+      questions: [
+        "In one sentence, what does this module do?",
+        "Who will use this, and what does each type DO with it? (Capture as verb-led sentences, e.g. 'Department managers approve or reject pending requests'. NOT role labels like 'Approver \u2014 approves requests'. Push back on vague answers like 'admins and users' \u2014 ask what each type does that the other can't.)"
+      ],
+      followUpNote: "After answers 1-2: ask any domain ambiguity questions that remain open (e.g. 'What counts as a closed item?', 'Can anonymous users submit?'). Continue one at a time until no open questions remain. Dependencies and locales are confirmed from Phase 0a \u2014 carry them into REQUIREMENTS.md without re-asking.",
+      writeAction: "Draft REQUIREMENTS.md and write it directly to docs/REQUIREMENTS.md on disk (do not paste it into chat). Tell the user it's ready: give a short outline (section headings + counts) and gap status ('No gaps' or a one-line list), then ask them to review and reply YES, or describe what to change. If they request changes, edit the file directly and ask again. Once they reply YES ('yes', 'looks good', 'confirmed', 'LGTM'), call dforge_module_plan({ action: 'write_requirements', moduleDir, userConfirmed: true })."
+    };
+  }
+  if (!has0c) {
+    if (fileExists(designPath)) {
+      return {
+        summary: "Phase 0b complete. A draft docs/DESIGN.md exists on disk but hasn't been confirmed yet.",
+        currentPhase: "0c",
+        completed,
+        pending,
+        readyToScaffold: false,
+        nextStep: "Read docs/DESIGN.md. Give the user a short outline (entity/status-machine counts, section headings) and Gaps & Proposals status (open items, or 'No gaps'), then ask them to review the file and reply YES, or describe what to change. If they request changes, edit docs/DESIGN.md directly (targeted edits), summarize the change in one line, and ask again. Once they reply YES, call dforge_module_plan({ action: 'write_design', moduleDir, userConfirmed: true })."
+      };
+    }
+    return {
+      summary: "Phase 0b complete. Proceed to Phase 0c design.",
+      currentPhase: "0c",
+      completed,
+      pending,
+      readyToScaffold: false,
+      nextStep: "Phase 0c \u2014 Design. Re-read REQUIREMENTS.md, then draft DESIGN.md (use the designTemplate below) with all 8 design items in a single message.",
+      designTemplate: DESIGN_TEMPLATE,
+      designItems: [
+        "1. Entity list (ordered least-dependent \u2192 most-dependent, one-line purpose each)",
+        "2. Fields per entity (key fields, status values, lookups, formulas, sequences)",
+        "3. Relationship map (Mermaid erDiagram + FK table with required/optional column)",
+        "4. Status machines (per-entity: values, transitions, canExecute guards, recovery paths)",
+        "5. Actions (name, target entity, description, params)",
+        "6. Seed data (entities needing initial rows, parent-before-child order)",
+        "7. Reports & queries",
+        "8. Special behaviors (soft-delete, sorting, webhooks, print templates)"
+      ],
+      gapDetection: "After drafting: run gap detection pass (FK optionality, status recovery, boolean-to-status smell, set aggregation risk, deep navigation, self-referential FK, security coverage, seed data circular refs). Add a 'Gaps & Proposals' section for each issue found. ALL gaps must be resolved before Phase 0d.",
+      writeAction: "Once gaps are resolved, write docs/DESIGN.md directly to disk (do not paste it into chat). Tell the user it's ready: give a short outline (entity/status-machine counts, section headings) and Gaps & Proposals status ('No gaps' or a one-line summary), then ask them to review and reply YES, or describe what to change. If they request changes, edit the file directly and ask again. Once they reply YES, call dforge_module_plan({ action: 'write_design', moduleDir, userConfirmed: true })."
+    };
+  }
+  return {
+    summary: "Phase 0c complete. Proceed to Phase 0d validation.",
+    currentPhase: "0d",
+    completed,
+    pending,
+    readyToScaffold: false,
+    nextStep: "Phase 0d \u2014 Validation. Call dforge_module_plan({ action: 'validate', moduleDir }) to run structural checks. If all pass, evaluate the returned semantic checks, then call validate again with checkResults."
+  };
+}
+function handleWriteIdentity(root, args) {
+  const { displayName, code: code2, dependencies = [], locales = ["en-US"], preset = "minimal" } = args;
+  if (!displayName) throw new Error("displayName is required for write_identity.");
+  if (!code2) throw new Error("code is required for write_identity.");
+  const depsText = dependencies.length > 0 ? dependencies.join(", ") : "None";
+  const localesText = locales.join(", ");
+  const claudeMd = buildClaudeMd({ root, displayName, code: code2, depsText, localesText, preset });
+  return {
+    summary: `Phase 0a complete \u2014 CLAUDE.md prepared for module '${code2}'.`,
+    files: { [P0.identity]: claudeMd },
+    nextStep: "Write CLAUDE.md to disk. Then start Phase 0b intake: ask the user (1) 'In one sentence, what does this module do?' (2) 'Who will use this, and what does each type DO with it?' \u2014 capture as verb-led sentences, not role labels. Ask domain ambiguity follow-ups until no open questions remain. Draft REQUIREMENTS.md and write it directly to docs/REQUIREMENTS.md on disk, give the user a short outline + gap status, wait for explicit YES, then call write_requirements with userConfirmed: true."
+  };
+}
+function buildClaudeMd(opts) {
+  const { root, displayName, code: code2, depsText, localesText, preset } = opts;
+  return `# ${displayName} \u2014 dForge Module
+
+## For AI assistants
+
+- All structural changes go through dforge-mcp tools \u2014 do not hand-edit entity/UI/security JSON files.
+- Read \`docs/DESIGN.md\` before proposing any changes to entities, fields, or relationships.
+- Run \`dforge_module_plan({ action: "check", moduleDir: "..." })\` to check Phase 0 status before any other tool.
+- Do NOT call \`dforge_module_create\` until \`dforge_module_plan\` validate returns \`readyToScaffold: true\`.
+
+## Module identity
+
+| Field | Value |
+|-------|-------|
+| Code | \`${code2}\` |
+| Display name | ${displayName} |
+| Dependencies | ${depsText} |
+| Locales | ${localesText} |
+| Preset | ${preset} |
+
+## Module status
+
+- [x] **0a** Identity \u2014 \`CLAUDE.md\`
+- [ ] **0b** Requirements \u2014 \`docs/REQUIREMENTS.md\`
+- [ ] **0c** Design \u2014 \`docs/DESIGN.md\`
+- [ ] **0d** Validation \u2014 \`docs/VALIDATION.md\`
+- [ ] **1** Scaffolded \u2014 \`manifest.json\`
+
+**Next step:** Phase 0b \u2014 run intake questions (purpose, user types, domain ambiguities), draft \`docs/REQUIREMENTS.md\` and write it to disk, get explicit user YES, then call \`dforge_module_plan({ action: "write_requirements", moduleDir, userConfirmed: true })\`.
+
+## Pack and install (after Phase 0 complete)
+
+\`\`\`
+dforge_module_pack({ moduleDir: "${root}" })
+dforge_module_install({ moduleDir: "${root}" })
+\`\`\`
+`;
+}
+function handleWriteRequirements(root, args) {
+  const reqPath = path3.join(root, P0.requirements);
+  assertDocReady(reqPath, P0.requirements);
+  if (!args.userConfirmed) {
     throw new Error(
-      `Entity '${newName}' already exists in this module. Edit entities/${newName}.json directly, or pick a different name.`
+      'User confirmation required \u2014 ask the user to review docs/REQUIREMENTS.md (already written to disk) and wait for an explicit YES ("yes", "looks good", "confirmed", "LGTM", or equivalent) before calling write_requirements with userConfirmed: true.'
     );
   }
-  const existingEntities = Object.keys(manifest.entities ?? {}).map(
-    (name) => ({
-      name,
-      label: tryReadEntityLabel(root, name) ?? name,
-      // Traits — we don't read them from disk because they don't matter
-      // for view/menu/role generation. Use a sentinel.
-      traits: "identity+audit"
-    })
+  const claudePath = path3.join(root, P0.identity);
+  if (!fileExists(claudePath)) {
+    throw new Error("CLAUDE.md not found \u2014 complete Phase 0a (write_identity) first.");
+  }
+  const updatedClaude = tickChecklist(
+    readFile(claudePath),
+    "0b",
+    'Phase 0c \u2014 design docs/DESIGN.md (8 design items + gap detection pass), write it to disk, get explicit user YES, then call `dforge_module_plan({ action: "write_design", moduleDir, userConfirmed: true })`.'
   );
-  const newEntity = {
-    name: args.entity.name,
-    label: args.entity.label,
-    traits: args.entity.traits
-  };
-  const allEntities = [...existingEntities, newEntity];
-  const opts = {
-    path: root,
-    code: manifest.code,
-    displayName: manifest.displayName ?? manifest.code,
-    description: manifest.description ?? "",
-    author: manifest.author?.name ?? "",
-    license: manifest.license ?? "MIT",
-    version: manifest.version ?? "0.1.0",
-    dbSchemaVersion: manifest.dbSchemaVersion ?? "0.0.1",
-    dependencies: Object.keys(manifest.dependencies ?? {}),
-    preset: "minimal",
-    entities: allEntities
-  };
-  const newManifest = {
-    ...manifest,
-    entities: {
-      ...manifest.entities ?? {},
-      [newEntity.name]: `./entities/${newEntity.name}.json`
+  return {
+    summary: "Phase 0b complete \u2014 docs/REQUIREMENTS.md confirmed.",
+    files: {
+      [P0.identity]: updatedClaude
     },
-    updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+    designTemplate: DESIGN_TEMPLATE,
+    nextStep: "Write the updated CLAUDE.md to disk. Now design DESIGN.md using the designTemplate above: 8 design items (entity list, fields per entity, relationship map, status machines, actions, seed data, reports, special behaviors). Run gap detection pass, add Gaps & Proposals section, resolve all gaps. Write docs/DESIGN.md to disk, give the user a short outline (entity/status-machine counts, section headings) plus Gaps & Proposals status, wait for explicit YES, then call write_design with userConfirmed: true."
   };
-  const files = {};
+}
+function handleWriteDesign(root, args) {
+  const designPath = path3.join(root, P0.design);
+  assertDocReady(designPath, P0.design);
+  if (!args.userConfirmed) {
+    throw new Error(
+      "User confirmation required \u2014 ask the user to review docs/DESIGN.md (already written to disk, including the Gaps & Proposals section) and wait for an explicit YES before calling write_design with userConfirmed: true. Ensure all Gaps & Proposals items are resolved."
+    );
+  }
+  const claudePath = path3.join(root, P0.identity);
+  if (!fileExists(claudePath)) throw new Error("CLAUDE.md not found \u2014 complete Phase 0a first.");
+  if (!fileExists(path3.join(root, P0.requirements))) {
+    throw new Error("docs/REQUIREMENTS.md not found \u2014 complete Phase 0b first.");
+  }
+  const updatedClaude = tickChecklist(
+    readFile(claudePath),
+    "0c",
+    'Phase 0d \u2014 call `dforge_module_plan({ action: "validate", moduleDir: "..." })` to run structural checks, then provide semantic checkResults.'
+  );
+  return {
+    summary: "Phase 0c complete \u2014 docs/DESIGN.md confirmed.",
+    files: {
+      [P0.identity]: updatedClaude
+    },
+    nextStep: "Write the updated CLAUDE.md to disk. Now run Phase 0d validation: call dforge_module_plan({ action: 'validate', moduleDir }) for the structural pre-check, evaluate the returned semantic checks, then call validate again with all checkResults."
+  };
+}
+var SEMANTIC_CHECK_DESCRIPTIONS = [
+  {
+    name: "Locale coverage",
+    description: "Do the locales listed in CLAUDE.md match the translation scope implied in REQUIREMENTS.md?"
+  },
+  {
+    name: "Persona \u2192 entity coverage",
+    description: "Does every user persona listed in REQUIREMENTS.md map to at least one entity in DESIGN.md that they interact with?"
+  },
+  {
+    name: "Core process coverage",
+    description: "Does every process in REQUIREMENTS.md Core Processes have a corresponding entity, action, or status machine in DESIGN.md?"
+  },
+  {
+    name: "Entity traceability",
+    description: "Can every entity in DESIGN.md Entity List be traced to a stated need in REQUIREMENTS.md? No invented entities."
+  },
+  {
+    name: "Status machine completeness",
+    description: "Does every entity with a status field have a fully documented machine (all values, transitions, guards, recovery path)?"
+  },
+  {
+    name: "Action completeness",
+    description: "Does every verb in REQUIREMENTS.md Core Processes that implies a user-triggered operation appear in DESIGN.md Actions table?"
+  },
+  {
+    name: "Seed data coverage",
+    description: "If REQUIREMENTS.md implies initial reference data or starting state, is it covered in DESIGN.md Seed Data section?"
+  }
+];
+function runStructuralChecks(root) {
+  const claudePath = path3.join(root, P0.identity);
+  const reqPath = path3.join(root, P0.requirements);
+  const designPath = path3.join(root, P0.design);
+  const missingDocs = [];
+  if (!fileExists(claudePath)) missingDocs.push("CLAUDE.md");
+  if (!fileExists(reqPath)) missingDocs.push("docs/REQUIREMENTS.md");
+  if (!fileExists(designPath)) missingDocs.push("docs/DESIGN.md");
+  if (missingDocs.length > 0) {
+    return [
+      {
+        check: "Docs present & substantive",
+        pass: false,
+        detail: `Missing: ${missingDocs.join(", ")}`
+      }
+    ];
+  }
+  const reqContent = readFile(reqPath);
+  const designContent = readFile(designPath);
+  const emptyDocs = [];
+  if (reqContent.trim().length < 100) emptyDocs.push("docs/REQUIREMENTS.md");
+  if (designContent.trim().length < 100) emptyDocs.push("docs/DESIGN.md");
+  if (emptyDocs.length > 0) {
+    return [
+      {
+        check: "Docs present & substantive",
+        pass: false,
+        detail: `Appears empty or too short (under 100 chars): ${emptyDocs.join(", ")}`
+      }
+    ];
+  }
+  const results = [
+    { check: "Docs present & substantive", pass: true, detail: "All 3 docs exist with content." }
+  ];
+  const claudeContent = readFile(claudePath);
+  const codeMatch = claudeContent.match(/\|\s*Code\s*\|\s*`([^`]+)`/);
+  const nameMatch = claudeContent.match(/\|\s*Display name\s*\|\s*([^\n|]+)/);
+  const code2 = codeMatch?.[1]?.trim();
+  const displayName = nameMatch?.[1]?.trim();
+  if (!code2 || !displayName) {
+    results.push({
+      check: "Identity consistency",
+      pass: false,
+      detail: "Could not extract code or display name from CLAUDE.md Module identity table \u2014 was it hand-edited?"
+    });
+  } else {
+    const reqLower = reqContent.toLowerCase();
+    const found = reqLower.includes(code2.toLowerCase()) || reqLower.includes(displayName.toLowerCase());
+    results.push({
+      check: "Identity consistency",
+      pass: found,
+      detail: found ? `Module identity (${code2} / ${displayName}) referenced in REQUIREMENTS.md.` : `Module code '${code2}' and display name '${displayName}' not found in REQUIREMENTS.md. Verify both docs describe the same module.`
+    });
+  }
+  const entityListMatch = designContent.match(/## Entity List\n([\s\S]*?)(?=\n##|$)/);
+  const entityListText = entityListMatch?.[1] ?? "";
+  const knownEntities = /* @__PURE__ */ new Set();
+  for (const line of entityListText.split("\n")) {
+    const m = line.match(/^[-*]\s+(?:\*\*)?([a-z][a-z0-9_]*)(?:\*\*)?/);
+    if (m) knownEntities.add(m[1]);
+  }
+  const relMapMatch = designContent.match(/## Relationship Map\n([\s\S]*?)(?=\n##|$)/);
+  const relMapText = relMapMatch?.[1] ?? "";
+  const referencedEntities = [];
+  for (const line of relMapText.split("\n")) {
+    const entityDef = line.match(/^\s{4}([a-z][a-z0-9_]*)\s*\{/);
+    if (entityDef) referencedEntities.push(entityDef[1]);
+    const relLine = line.match(/\b([a-z][a-z0-9_]*)\s+[|o]{2}[-]{2}[|o{]{2}\s+([a-z][a-z0-9_]*)\b/);
+    if (relLine) {
+      referencedEntities.push(relLine[1]);
+      referencedEntities.push(relLine[2]);
+    }
+  }
+  if (knownEntities.size === 0 || referencedEntities.length === 0) {
+    results.push({
+      check: "Relationship completeness",
+      pass: true,
+      detail: "Entity List or Relationship Map section not found \u2014 skipped cross-check. Verify manually."
+    });
+  } else {
+    const missing = [...new Set(referencedEntities.filter((e) => !knownEntities.has(e)))];
+    results.push({
+      check: "Relationship completeness",
+      pass: missing.length === 0,
+      detail: missing.length === 0 ? "All entities in Relationship Map appear in Entity List." : `Entities in Relationship Map not found in Entity List: ${missing.join(", ")}`
+    });
+  }
+  const gapsMatch = designContent.match(/## Gaps & Proposals\n([\s\S]*?)(?=\n##|$)/i);
+  if (!gapsMatch) {
+    results.push({
+      check: "Gap resolution",
+      pass: true,
+      detail: "No Gaps & Proposals section in DESIGN.md."
+    });
+  } else {
+    const gapsText = gapsMatch[1];
+    const openPatterns = [/\bTBD\b/i, /\bto be determined\b/i, /\bunresolved\b/i, /\bopen:\b/i, /\bneeds clarification\b/i];
+    const found = openPatterns.filter((p) => p.test(gapsText)).map((p) => p.source);
+    results.push({
+      check: "Gap resolution",
+      pass: found.length === 0,
+      detail: found.length === 0 ? "Gaps & Proposals section present with no open-item markers." : `Possible unresolved gaps (matched: ${found.join(", ")}). Resolve all gaps before Phase 0d.`
+    });
+  }
+  return results;
+}
+function handleValidate(root, args) {
+  const structuralResults = runStructuralChecks(root);
+  const structuralFailed = structuralResults.filter((r) => !r.pass);
+  if (!args.checkResults) {
+    if (structuralFailed.length > 0) {
+      return {
+        summary: `Structural pre-check: ${structuralFailed.length} check(s) failed. Fix before proceeding.`,
+        structuralChecks: structuralResults,
+        nextStep: "Fix the structural failures listed above, update the relevant document(s), then call dforge_module_plan({ action: 'validate', moduleDir }) again."
+      };
+    }
+    return {
+      summary: "Structural checks passed. Evaluate the semantic checks below against the Phase 0 docs, then call validate with checkResults.",
+      structuralChecks: structuralResults,
+      semanticChecks: SEMANTIC_CHECK_DESCRIPTIONS,
+      nextStep: "Evaluate each semantic check against the Phase 0 docs \u2014 read docs/REQUIREMENTS.md and docs/DESIGN.md from disk (and CLAUDE.md) if they aren't already in your context \u2014 then call dforge_module_plan({ action: 'validate', moduleDir, checkResults: [...] }) with your results for all 7 checks."
+    };
+  }
+  if (structuralFailed.length > 0) {
+    return {
+      summary: `Structural checks still failing \u2014 fix documents first.`,
+      structuralChecks: structuralResults
+    };
+  }
+  const allResults = [...structuralResults, ...args.checkResults];
+  const failedAll = allResults.filter((r) => !r.pass);
+  if (failedAll.length > 0) {
+    return {
+      summary: `Validation failed: ${failedAll.length} check(s) did not pass.`,
+      failures: failedAll,
+      nextStep: "Fix the issues above in the relevant Phase 0 documents. Then call validate again (starting from the first call, without checkResults, to re-run structural checks)."
+    };
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const rows = allResults.map((r, i) => `| ${i + 1} | ${r.check} | ${r.pass ? "\u2705 PASS" : "\u274C FAIL"} | ${r.detail} |`).join("\n");
+  const validationMd = `# Validation Report
+
+*Generated: ${today}*
+
+## Phase 0 Pre-Scaffold Design-Doc Checks
+
+| # | Check | Result | Detail |
+|---|-------|--------|--------|
+${rows}
+
+**Result: \u2705 ALL DESIGN-DOC CHECKS PASSED**
+
+> Scope: these checks validate the **Phase 0 design documents** only (identity, requirements,
+> design consistency). They do **not** inspect generated entity / UI / security / DSL artifacts \u2014
+> those are validated by the platform at install (Phase 6). A pass here unlocks scaffolding; it is
+> not a guarantee the module installs. Use the Phase 6 pre-pack self-review before packing.
+
+readyToScaffold: true
+`;
+  const claudePath = path3.join(root, P0.identity);
+  const updatedClaude = tickChecklist(
+    readFile(claudePath),
+    "0d",
+    'Phase 0 complete \u2014 call `dforge_module_create({ moduleDir: "...", ... })` to scaffold the module.'
+  );
+  return {
+    summary: "Phase 0d complete \u2014 design docs validated (readyToScaffold: true). Note: this validates the design docs only; generated artifacts are checked by the platform at install.",
+    readyToScaffold: true,
+    files: {
+      [P0.identity]: updatedClaude,
+      [P0.validation]: validationMd,
+      // Machine-readable gate marker — the scaffold check parses this, not the
+      // Markdown report above.
+      [P0.phaseState]: phaseStateJson({ phase: "0d", readyToScaffold: true, validatedAt: today })
+    },
+    nextStep: "Write both files to disk. Phase 0 is complete. Now call dforge_module_create({ moduleDir, code, displayName, entities, preset }) to scaffold the module."
+  };
+}
+function fileExists(absPath) {
+  return fs3.existsSync(absPath);
+}
+function readFile(absPath) {
+  return fs3.readFileSync(absPath, "utf8");
+}
+function assertDocReady(absPath, relPath) {
+  if (!fileExists(absPath)) {
+    throw new Error(
+      `${relPath} not found \u2014 write the draft to disk first (using your file-write tool), then ask the user to review it before calling this action with userConfirmed: true.`
+    );
+  }
+  if (readFile(absPath).trim().length < 100) {
+    throw new Error(
+      `${relPath} appears empty or too short (under 100 chars) \u2014 write the full draft to disk first.`
+    );
+  }
+}
+function tickChecklist(claudeMd, phase, nextStep) {
+  const ticked = claudeMd.replace(
+    new RegExp(`- \\[ \\] (\\*\\*${phase}\\*\\*)`),
+    "- [x] $1"
+  );
+  return ticked.replace(
+    /\*\*Next step:\*\* .+/,
+    `**Next step:** ${nextStep}`
+  );
+}
+
+// src/tools/add-entity.ts
+var fs4 = __toESM(require("fs"));
+var path4 = __toESM(require("path"));
+var addEntitySchema = {
+  moduleDir: external_exports.string().describe("Absolute or relative path to an existing module directory (contains manifest.json)."),
+  entity: external_exports.object({
+    name: external_exports.string().regex(/^[a-z][a-z0-9_]*$/),
+    label: external_exports.string().min(1),
+    traits: traitsInput
+  })
+};
+function addEntityFiles(args) {
+  const root = path4.resolve(args.moduleDir);
+  const manifestPath = path4.join(root, "manifest.json");
+  if (!fs4.existsSync(manifestPath)) {
+    throw new Error(`No manifest.json found at ${manifestPath}`);
+  }
+  const manifest = JSON.parse(fs4.readFileSync(manifestPath, "utf8"));
+  if (!manifest.code) {
+    throw new Error("manifest.json has no `code` field \u2014 corrupt module?");
+  }
+  const newName = args.entity.name;
+  if (manifest.entities && manifest.entities[newName]) {
+    throw new Error(
+      `Entity '${newName}' already exists in this module. Edit entities/${newName}.json directly, or pick a different name.`
+    );
+  }
+  const existingEntities = Object.keys(manifest.entities ?? {}).map(
+    (name) => ({
+      name,
+      label: tryReadEntityLabel(root, name) ?? name,
+      // Traits — we don't read them from disk because they don't matter
+      // for view/menu/role generation. Use a sentinel.
+      traits: "identity+audit"
+    })
+  );
+  const newEntity = {
+    name: args.entity.name,
+    label: args.entity.label,
+    // Placeholder preset for the view/menu/role builders (they ignore traits);
+    // the real validated trait codes are applied to the entity JSON below.
+    traits: "identity"
+  };
+  const allEntities = [...existingEntities, newEntity];
+  const opts = {
+    path: root,
+    code: manifest.code,
+    displayName: manifest.displayName ?? manifest.code,
+    description: manifest.description ?? "",
+    author: manifest.author?.name ?? "",
+    license: manifest.license ?? "MIT",
+    version: manifest.version ?? "0.1.0",
+    dbSchemaVersion: manifest.dbSchemaVersion ?? "0.0.1",
+    dependencies: Object.keys(manifest.dependencies ?? {}),
+    preset: "minimal",
+    entities: allEntities
+  };
+  const newManifest = {
+    ...manifest,
+    entities: {
+      ...manifest.entities ?? {},
+      [newEntity.name]: `./entities/${newEntity.name}.json`
+    },
+    updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  };
+  const files = {};
   files["manifest.json"] = JSON.stringify(newManifest, null, "	") + "\n";
-  files[`entities/${newEntity.name}.json`] = JSON.stringify(buildEntity(newEntity), null, "	") + "\n";
+  files[`entities/${newEntity.name}.json`] = JSON.stringify(withTraits(buildEntity(newEntity), 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";
@@ -31257,7 +32262,7 @@ function addEntityFiles(args) {
 function tryReadEntityLabel(root, name) {
   try {
     const e = JSON.parse(
-      fs.readFileSync(path.join(root, "entities", `${name}.json`), "utf8")
+      fs4.readFileSync(path4.join(root, "entities", `${name}.json`), "utf8")
     );
     return e.description;
   } catch {
@@ -31265,38 +32270,395 @@ function tryReadEntityLabel(root, name) {
   }
 }
 
+// src/tools/import.ts
+var import_node_crypto2 = require("crypto");
+var moduleIdentitySchema = external_exports.object({
+  code: codeReLazy(),
+  displayName: external_exports.string().optional(),
+  version: external_exports.string().optional(),
+  dbSchemaVersion: external_exports.string().optional(),
+  license: external_exports.string().optional()
+}).optional();
+function codeReLazy() {
+  return external_exports.string().regex(/^[a-z][a-z0-9_]*$/);
+}
+function ensureManifest(moduleDir, identity) {
+  try {
+    return loadManifest(moduleDir).manifest;
+  } catch {
+    if (!identity?.code) {
+      throw new Error(`No manifest.json in '${moduleDir}'. Pass module.code (and module.displayName) to start a new module from this import.`);
+    }
+    return {
+      packageFormat: 1,
+      moduleId: (0, import_node_crypto2.randomUUID)(),
+      code: identity.code,
+      version: identity.version ?? "0.1.0",
+      dbSchemaVersion: identity.dbSchemaVersion ?? "0.0.1",
+      displayName: identity.displayName ?? identity.code,
+      license: identity.license ?? "MIT",
+      entities: {}
+    };
+  }
+}
+function buildImportFiles(manifest, tables) {
+  const existing = new Set(Object.keys(manifest.entities ?? {}));
+  const files = {};
+  const added = [];
+  const manifestEntities = { ...manifest.entities ?? {} };
+  for (const table of tables) {
+    if (existing.has(table.name)) {
+      throw new Error(`Entity '${table.name}' already exists \u2014 import only ADDS new entities. Remove it from the spec or edit the entity directly.`);
+    }
+    files[`entities/${table.name}.json`] = jsonText(buildImportedEntity(table));
+    manifestEntities[table.name] = `./entities/${table.name}.json`;
+    added.push(table.name);
+  }
+  manifest.entities = manifestEntities;
+  const allSpecs = Object.keys(manifestEntities).filter((n) => !n.includes(".")).map((n) => ({ name: n, label: titleCase(n), traits: "identity" }));
+  const opts = {
+    path: "",
+    code: manifest.code,
+    displayName: manifest.displayName ?? manifest.code,
+    description: manifest.description ?? "",
+    author: "",
+    license: manifest.license ?? "MIT",
+    version: manifest.version ?? "0.1.0",
+    dbSchemaVersion: manifest.dbSchemaVersion ?? "0.0.1",
+    dependencies: Object.keys(manifest.dependencies ?? {}),
+    preset: "minimal",
+    entities: allSpecs
+  };
+  files["ui/data_views.json"] = jsonText(buildDataViews(allSpecs));
+  files["ui/folders.json"] = jsonText(buildFolders(opts));
+  files["ui/menus.json"] = jsonText(buildMenus(opts));
+  files["security/roles.json"] = jsonText(buildRoles(opts));
+  files["manifest.json"] = jsonText(withTodayStamp(manifest));
+  return { files, added };
+}
+var codeRe = external_exports.string().regex(/^[a-z][a-z0-9_]*$/);
+var columnSpec = external_exports.object({
+  name: codeRe.describe("Column code (snake_case)."),
+  label: external_exports.string().optional(),
+  fieldTypeCd: external_exports.string().optional().describe("Explicit field type; omit to infer."),
+  sqlType: external_exports.string().optional().describe("Source SQL type hint, e.g. varchar(50), int, numeric(18,2), timestamptz, bool."),
+  sampleValues: external_exports.array(external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean()])).optional().describe("A few example cell values \u2014 used to infer the type when no sqlType is given."),
+  required: external_exports.boolean().optional()
+});
+var tableSpec = external_exports.object({
+  name: codeRe.describe("Entity code (snake_case)."),
+  label: external_exports.string().optional(),
+  columns: external_exports.array(columnSpec).min(1),
+  references: external_exports.array(
+    external_exports.object({
+      column: codeRe.describe("FK column on THIS table (a hidden cuid column is generated for it)."),
+      toTable: codeRe.describe("Target entity code."),
+      toColumn: codeRe.optional().describe("Target PK column; defaults to {toTable}_id.")
+    })
+  ).optional()
+});
+var moduleImportSchema = {
+  moduleDir: external_exports.string().describe("Path to the module dir. If it has no manifest, pass `module` to start a new module (greenfield import)."),
+  tables: external_exports.array(tableSpec).min(1).describe("Normalized table-spec, produced from DBML/SQL, an Excel/CSV upload (read by the AI), or hand-authored."),
+  module: moduleIdentitySchema.describe("New-module identity \u2014 required only when moduleDir has no manifest yet.")
+};
+var SQL_TYPE_MAP = {
+  varchar: "text",
+  nvarchar: "text",
+  char: "text",
+  bpchar: "text",
+  string: "text",
+  text: "textarea",
+  ntext: "textarea",
+  clob: "textarea",
+  int: "number",
+  integer: "number",
+  int2: "number",
+  int4: "number",
+  int8: "number",
+  bigint: "number",
+  smallint: "number",
+  tinyint: "number",
+  serial: "number",
+  bigserial: "number",
+  numeric: "number",
+  decimal: "number",
+  float: "number",
+  float8: "number",
+  double: "number",
+  real: "number",
+  money: "currency",
+  bool: "checkbox",
+  boolean: "checkbox",
+  bit: "checkbox",
+  date: "date",
+  timestamp: "datetime",
+  timestamptz: "datetime",
+  datetime: "datetime",
+  datetime2: "datetime",
+  time: "time",
+  timetz: "time",
+  json: "json",
+  jsonb: "json",
+  uuid: "text"
+};
+function titleCase(code2) {
+  return code2.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function inferFromSamples(samples) {
+  const vals = samples.filter((v) => v !== null && v !== "");
+  if (!vals.length) return "text";
+  if (vals.every((v) => typeof v === "boolean" || /^(true|false|yes|no)$/i.test(String(v)))) return "checkbox";
+  if (vals.every((v) => typeof v === "number" || /^-?\d+(\.\d+)?$/.test(String(v)))) return "number";
+  if (vals.every((v) => /^\d{4}-\d{2}-\d{2}/.test(String(v)))) return "date";
+  return "text";
+}
+function inferFieldType(col) {
+  if (col.fieldTypeCd) return { fieldTypeCd: col.fieldTypeCd };
+  let base;
+  if (col.sqlType) {
+    base = SQL_TYPE_MAP[col.sqlType.toLowerCase().replace(/\(.*$/, "").trim()];
+  }
+  if (!base && col.sampleValues?.length) base = inferFromSamples(col.sampleValues);
+  base = base ?? "text";
+  const n = col.name.toLowerCase();
+  if (base === "text" || base === "textarea") {
+    if (/email/.test(n)) base = "email";
+    else if (/phone|tel|mobile|fax/.test(n)) base = "phone";
+    else if (/url|website|homepage/.test(n)) base = "url";
+  }
+  if (base === "number" && /price|amount|cost|total|salary|fee|balance|revenue|payment|wage/.test(n)) {
+    base = "currency";
+  }
+  if (base === "text" && col.sampleValues && col.sampleValues.length >= 3) {
+    const distinct = [...new Set(col.sampleValues.map(String))];
+    if (distinct.length <= 8 && distinct.length < col.sampleValues.length) {
+      return { fieldTypeCd: "dropdown", params: { options: distinct.map((v) => ({ value: v, label: v })) } };
+    }
+  }
+  return { fieldTypeCd: base };
+}
+function buildImportedEntity(table) {
+  const fields = {};
+  const refColumns = new Set((table.references ?? []).map((r) => r.column));
+  let order = 10;
+  let toStringField;
+  for (const col of table.columns) {
+    if (refColumns.has(col.name)) continue;
+    const inf = inferFieldType(col);
+    if (!isFieldTypeCd(inf.fieldTypeCd)) {
+      throw new Error(`Inferred an invalid fieldTypeCd '${inf.fieldTypeCd}' for ${table.name}.${col.name} \u2014 pass an explicit fieldTypeCd.`);
+    }
+    const field = {
+      fieldTypeCd: inf.fieldTypeCd,
+      flags: col.required ? "VEM" : "VE",
+      orderNum: order,
+      description: col.label ?? titleCase(col.name)
+    };
+    const db = deriveDbDatatype(inf.fieldTypeCd);
+    if (db) field.dbDatatype = db;
+    if (inf.params) field.params = inf.params;
+    fields[col.name] = field;
+    if (!toStringField && inf.fieldTypeCd === "text") toStringField = col.name;
+    order += 10;
+  }
+  const references = {};
+  for (const ref of table.references ?? []) {
+    const otherKey = ref.toColumn ?? `${ref.toTable}_id`;
+    fields[ref.column] = { dbDatatype: "cuid", flags: "EM", orderNum: order, description: titleCase(ref.column) };
+    order += 10;
+    const refName = ref.column.endsWith("_id") ? ref.column.slice(0, -3) : `${ref.column}_ref`;
+    fields[refName] = {
+      columnType: "R",
+      fieldTypeCd: "lookup",
+      flags: "VEM",
+      orderNum: order,
+      description: titleCase(refName),
+      link: { entity: ref.toTable, thisKey: ref.column, otherKey }
+    };
+    order += 10;
+    references[`FK_${titleCase(table.name).replace(/\s+/g, "")}_${ref.column}`] = {
+      from: { field: ref.column },
+      to: { entity: ref.toTable, field: otherKey }
+    };
+  }
+  const entity = {
+    description: table.label ?? titleCase(table.name),
+    dbObject: table.name,
+    toString: toStringField ? `{${toStringField}}` : null,
+    traits: ["identity", "audit"],
+    fields
+  };
+  if (Object.keys(references).length) entity.references = references;
+  return entity;
+}
+var IMPORT_WARNING = "Review the inferred field types (especially dropdown vs text, and currency vs number) and the generated default grids \u2014 refine views to surface the imported columns. Cross-table references resolve only if both tables are in this import or already in the module. Run dforge_module_validate after writing.";
+function moduleImport(args) {
+  const manifest = ensureManifest(args.moduleDir, args.module);
+  const { files, added } = buildImportFiles(manifest, args.tables);
+  return makeResult(
+    `Imported ${added.length} entit${added.length === 1 ? "y" : "ies"} (${added.join(", ")}) with inferred field types + FK+Reference pairs; regenerated default views/folders/menus/roles.`,
+    files,
+    IMPORT_WARNING
+  );
+}
+var dbmlImportSchema = {
+  moduleDir: external_exports.string().describe("Path to the module dir. If empty, pass `module` to start a new module."),
+  dbml: external_exports.string().describe("DBML source text (https://dbml.dbdiagram.io)."),
+  module: moduleIdentitySchema.describe("New-module identity \u2014 required only when moduleDir has no manifest yet.")
+};
+function snake(name) {
+  const base = name.includes(".") ? name.split(".").pop() : name;
+  return base.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").replace(/^([0-9])/, "_$1");
+}
+function parseDbmlTableBody(rawName, body) {
+  const t = { name: snake(rawName), columns: [], refs: [] };
+  for (const raw of body.split("\n")) {
+    const line = raw.trim();
+    if (!line || /^(note|indexes|Note|Indexes)\b/.test(line)) continue;
+    const m = line.match(/^"?([A-Za-z_][\w]*)"?\s+"?([A-Za-z_][\w]*(?:\([^)]*\))?)"?\s*(\[[^\]]*\])?/);
+    if (!m) continue;
+    const colName = snake(m[1]);
+    const sqlType = m[2];
+    const settings = (m[3] ?? "").toLowerCase();
+    const isPk = /\bpk\b|\bprimary key\b/.test(settings);
+    const required2 = /\bnot null\b/.test(settings);
+    if (isPk && !t.pk) t.pk = colName;
+    const refM = settings.match(/ref\s*:?\s*[<>-]\s*"?([A-Za-z_][\w.]*)"?\.\s*"?([A-Za-z_]\w*)"?/);
+    if (refM) t.refs.push({ column: colName, toTable: snake(refM[1]), toColumn: snake(refM[2]) });
+    if (!isPk) t.columns.push({ name: colName, sqlType, required: required2 });
+  }
+  return t;
+}
+function parseDbml(dbml) {
+  const src = dbml.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+  const tables = [];
+  const tableRe = /Table\s+"?([\w.]+)"?\s*(?:as\s+\w+\s*)?\{/gi;
+  let tm;
+  while (tm = tableRe.exec(src)) {
+    const start = tableRe.lastIndex;
+    let depth = 1;
+    let i = start;
+    while (i < src.length && depth > 0) {
+      if (src[i] === "{") depth++;
+      else if (src[i] === "}") depth--;
+      i++;
+    }
+    tables.push(parseDbmlTableBody(tm[1], src.slice(start, i - 1)));
+    tableRe.lastIndex = i;
+  }
+  const byName = new Map(tables.map((t) => [t.name, t]));
+  const refRe = /Ref\s*\w*\s*:?\s*"?([\w.]+)"?\.\s*"?(\w+)"?\s*([<>-])\s*"?([\w.]+)"?\.\s*"?(\w+)"?/gi;
+  let rm;
+  while (rm = refRe.exec(src)) {
+    const [, aT, aC, op, bT, bC] = rm;
+    const aTable = snake(aT), aCol = snake(aC), bTable = snake(bT), bCol = snake(bC);
+    const fkOnLeft = op === ">" || op === "-";
+    const fk = fkOnLeft ? { table: aTable, col: aCol, toTable: bTable, toCol: bCol } : { table: bTable, col: bCol, toTable: aTable, toCol: aCol };
+    const owner = byName.get(fk.table);
+    if (owner && !owner.refs.some((r) => r.column === fk.col)) {
+      owner.refs.push({ column: fk.col, toTable: fk.toTable, toColumn: fk.toCol });
+    }
+  }
+  return tables.map((t) => {
+    const refColNames = new Set(t.refs.map((r) => r.column));
+    const references = t.refs.map((r) => {
+      const targetPk = byName.get(r.toTable)?.pk;
+      const toColumn = targetPk && r.toColumn === targetPk ? void 0 : r.toColumn;
+      return { column: r.column, toTable: r.toTable, ...toColumn ? { toColumn } : {} };
+    });
+    const columns = t.columns.filter((c) => !refColNames.has(c.name));
+    const spec = { name: t.name, columns: columns.length ? columns : [{ name: "name", sqlType: "varchar" }] };
+    if (references.length) spec.references = references;
+    return spec;
+  });
+}
+function dbmlImport(args) {
+  const tables = parseDbml(args.dbml);
+  if (!tables.length) throw new Error("No `Table` blocks found in the DBML source.");
+  const manifest = ensureManifest(args.moduleDir, args.module);
+  const { files, added } = buildImportFiles(manifest, tables);
+  return makeResult(
+    `Parsed ${tables.length} table(s) from DBML and imported ${added.length} as entities (${added.join(", ")}).`,
+    files,
+    IMPORT_WARNING
+  );
+}
+
 // src/tools/native-shell.ts
 var import_node_child_process = require("child_process");
-var fs2 = __toESM(require("fs"));
-var path2 = __toESM(require("path"));
+var import_node_module = require("module");
+var fs5 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
+var require2 = (0, import_node_module.createRequire)(__filename);
+function needsWindowsCommandShell(bin) {
+  if (process.platform !== "win32") return false;
+  if (/\.(?:cmd|bat)$/i.test(bin)) return true;
+  return !bin.includes("\\") && !bin.includes("/");
+}
+function quoteWinArg(arg) {
+  if (arg.length > 0 && !/[\s"&|<>^()%!]/.test(arg)) {
+    return arg;
+  }
+  let quoted = '"';
+  let backslashes = 0;
+  for (const ch of arg) {
+    if (ch === "\\") {
+      backslashes++;
+      continue;
+    }
+    if (ch === '"') {
+      quoted += "\\".repeat(backslashes * 2 + 1) + '"';
+    } else {
+      quoted += "\\".repeat(backslashes) + ch;
+    }
+    backslashes = 0;
+  }
+  quoted += "\\".repeat(backslashes * 2) + '"';
+  return quoted;
+}
+function spawnCli(cli, args, options = {}) {
+  const fullArgs = [...cli.argsPrefix, ...args];
+  if (needsWindowsCommandShell(cli.bin)) {
+    const commandLine = [cli.bin, ...fullArgs].map(quoteWinArg).join(" ");
+    return (0, import_node_child_process.spawnSync)(commandLine, { encoding: "utf8", shell: true, ...options });
+  }
+  return (0, import_node_child_process.spawnSync)(cli.bin, fullArgs, { encoding: "utf8", shell: false, ...options });
+}
 function resolveDforgeCli() {
   const override = process.env.DFORGE_CLI_BINARY;
   if (override) {
-    if (!fs2.existsSync(override)) {
+    if (!fs5.existsSync(override)) {
       throw new Error(
         `DFORGE_CLI_BINARY points at non-existent path: ${override}`
       );
     }
-    return override;
+    return { bin: override, argsPrefix: [], display: override };
   }
-  return "dforge-cli";
+  try {
+    const cliEntry = require2.resolve("@dforge-core/dforge-cli");
+    return {
+      bin: process.execPath,
+      argsPrefix: [cliEntry],
+      display: `node ${cliEntry}`
+    };
+  } catch {
+  }
+  return { bin: "dforge-cli", argsPrefix: [], display: "dforge-cli" };
 }
 function run(args, cwd) {
-  const bin = resolveDforgeCli();
-  const r = (0, import_node_child_process.spawnSync)(bin, args, {
-    encoding: "utf8",
-    cwd,
-    shell: false
-  });
+  const cli = resolveDforgeCli();
+  const r = spawnCli(cli, args, { cwd });
   if (r.error) {
     throw new Error(
-      `Failed to exec ${bin}: ${r.error.message}. Install with: npm install -g @dforge-core/dforge-cli (or set DFORGE_CLI_BINARY=/path/to/binary).`
+      `Failed to exec ${cli.display}: ${r.error.message}. Install with: npm install -g @dforge-core/dforge-cli (or set DFORGE_CLI_BINARY=/path/to/binary).`
     );
   }
   return {
     stdout: r.stdout ?? "",
     stderr: r.stderr ?? "",
-    code: r.status ?? 1
+    code: r.status ?? 1,
+    command: [cli.display, ...args].join(" ")
   };
 }
 var packModuleSchema = {
@@ -31304,6 +32666,7 @@ var packModuleSchema = {
   outPath: external_exports.string().optional().describe("Output file or directory. Defaults to cwd, naming the file <code>-<version>.dforge.")
 };
 function packModule(args) {
+  const securityWarning = assertSecurityCoverage(args.moduleDir);
   const argList = ["module", "pack", args.moduleDir];
   if (args.outPath) {
     argList.push("-o", args.outPath);
@@ -31313,13 +32676,39 @@ function packModule(args) {
     throw new Error(`pack failed (exit ${r.code}):
 ${r.stderr || r.stdout}`);
   }
-  const m = r.stdout.match(/([\w./-]+\.dforge)/);
-  const tarballPath = m ? path2.resolve(m[1]) : args.outPath ? path2.resolve(args.outPath) : "";
+  const candidates = [];
+  if (args.outPath && args.outPath.toLowerCase().endsWith(".dforge")) {
+    candidates.push(args.outPath);
+  }
+  const quoted = r.stdout.match(/["']([^"'\r\n]+\.dforge)["']/i);
+  if (quoted) candidates.push(quoted[1]);
+  for (const m of r.stdout.matchAll(/(\S+\.dforge)\b/gi)) candidates.push(m[1]);
+  if (args.outPath) candidates.push(args.outPath);
+  const clean = (s) => s.replace(/^[\s'"([{<]+/, "").replace(/[\s'"),.;:\]}>]+$/, "");
+  const fileSize = (p) => {
+    try {
+      const st = fs5.statSync(p);
+      return st.isFile() ? st.size : void 0;
+    } catch {
+      return void 0;
+    }
+  };
+  let tarballPath = "";
   let sizeBytes = 0;
-  if (tarballPath && fs2.existsSync(tarballPath)) {
-    sizeBytes = fs2.statSync(tarballPath).size;
+  for (const c of candidates) {
+    const resolved = path5.resolve(clean(c));
+    const size = fileSize(resolved);
+    if (size !== void 0) {
+      tarballPath = resolved;
+      sizeBytes = size;
+      break;
+    }
   }
-  return { tarballPath, sizeBytes, output: r.stdout };
+  if (!tarballPath && candidates.length) tarballPath = path5.resolve(clean(candidates[0]));
+  const output = securityWarning ? `${securityWarning}
+
+${r.stdout}` : r.stdout;
+  return { tarballPath, sizeBytes, output };
 }
 var installModuleSchema = {
   pathOrTarball: external_exports.string().describe("Module directory OR path to a .dforge tarball."),
@@ -31335,104 +32724,50 @@ function installModule(args) {
   const env = {};
   if (args.tenantUrl) env.DFORGE_URL = args.tenantUrl;
   if (args.token) env.DFORGE_TOKEN = args.token;
-  const bin = resolveDforgeCli();
-  const r = (0, import_node_child_process.spawnSync)(bin, argList, {
-    encoding: "utf8",
-    env: { ...process.env, ...env },
-    shell: false
-  });
+  const cli = resolveDforgeCli();
+  const r = spawnCli(cli, argList, { env: { ...process.env, ...env } });
   if (r.error) {
-    throw new Error(`Failed to exec ${bin}: ${r.error.message}`);
+    throw new Error(`Failed to exec ${cli.display}: ${r.error.message}`);
   }
   const ok = r.status === 0;
   const output = (r.stdout ?? "") + (r.stderr ?? "");
-  return { ok, output };
-}
-var dbmlImportSchema = {
-  dbmlText: external_exports.string().describe("DBML source text."),
-  moduleCode: external_exports.string().regex(/^[a-z][a-z0-9_-]*$/).describe("Module code for the generated module.")
-};
-function dbmlImport(_args) {
   return {
-    ok: false,
-    message: "dbml-import is not yet implemented in dforge-cli. The CLI command `dforge-cli dbml-import --from-dbml <file>` is a stub. When it lands, this tool will shell out to it and return the generated module file map."
+    ok,
+    exitCode: r.status ?? 1,
+    command: [cli.display, ...argList].join(" "),
+    output
   };
 }
 
 // src/tools/entity-field.ts
-var path4 = __toESM(require("path"));
-
-// src/tools/_helpers.ts
-var fs3 = __toESM(require("fs"));
-var path3 = __toESM(require("path"));
-function modulePaths(moduleDir) {
-  const root = path3.resolve(moduleDir);
-  return {
-    root,
-    manifest: path3.join(root, "manifest.json"),
-    entitiesDir: path3.join(root, "entities"),
-    uiDir: path3.join(root, "ui"),
-    securityDir: path3.join(root, "security"),
-    logicDir: path3.join(root, "logic"),
-    seedDataDir: path3.join(root, "seed-data"),
-    translationsDir: path3.join(root, "translations"),
-    dataViews: path3.join(root, "ui", "data_views.json"),
-    folders: path3.join(root, "ui", "folders.json"),
-    menus: path3.join(root, "ui", "menus.json"),
-    actions: path3.join(root, "ui", "actions.json"),
-    reports: path3.join(root, "ui", "reports.json"),
-    roles: path3.join(root, "security", "roles.json"),
-    jobs: path3.join(root, "logic", "jobs.json"),
-    settings: path3.join(root, "settings.json")
-  };
-}
-function readJson(absPath) {
-  if (!fs3.existsSync(absPath)) {
-    throw new Error(`Not found: ${absPath}`);
-  }
-  try {
-    return JSON.parse(fs3.readFileSync(absPath, "utf8"));
-  } catch (e) {
-    throw new Error(`${absPath}: ${e.message}`);
-  }
-}
-function readJsonOrDefault(absPath, dflt) {
-  if (!fs3.existsSync(absPath)) return dflt;
-  try {
-    return JSON.parse(fs3.readFileSync(absPath, "utf8"));
-  } catch (e) {
-    throw new Error(`${absPath}: ${e.message}`);
-  }
-}
-function jsonText(obj) {
-  return JSON.stringify(obj, null, "	") + "\n";
-}
-function rel(root, abs) {
-  return path3.relative(root, abs);
-}
-function loadManifest(moduleDir) {
-  const paths = modulePaths(moduleDir);
-  if (!fs3.existsSync(paths.manifest)) {
-    throw new Error(
-      `No manifest.json at ${paths.manifest} \u2014 is this a dForge module directory?`
-    );
-  }
-  const manifest = readJson(paths.manifest);
-  if (!manifest.code) {
-    throw new Error("manifest.json has no `code` field \u2014 corrupt module?");
-  }
-  return { manifest, paths };
-}
-function makeResult(summary, files, warning) {
-  const out = { summary, files };
-  if (warning) out.warning = warning;
-  return out;
-}
-function withTodayStamp(manifest) {
-  return { ...manifest, updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10) };
+var path6 = __toESM(require("path"));
+var FIELD_TYPE_ALIASES = {
+  integer: "number",
+  int: "number",
+  decimal: "number",
+  float: "number",
+  string: "text",
+  varchar: "text",
+  boolean: "checkbox",
+  bool: "checkbox",
+  reference: "lookup",
+  autocomplete: "lookup",
+  fk: "lookup",
+  datepicker: "date",
+  timestamp: "datetime",
+  select: "dropdown",
+  multiselect: "flags"
+};
+function finalizeField(field) {
+  const ftc = field.fieldTypeCd;
+  if (typeof ftc !== "string" || field.dbDatatype !== void 0) return field;
+  const derived = deriveDbDatatype(ftc, {
+    maxLen: typeof field.maxLen === "number" ? field.maxLen : void 0,
+    precision: typeof field.precision === "number" ? field.precision : void 0
+  });
+  if (derived == null) return field;
+  return { ...field, dbDatatype: derived };
 }
-
-// src/tools/entity-field.ts
 var fieldSchema = external_exports.object({
   dbDatatype: external_exports.string().optional(),
   fieldTypeCd: external_exports.string().optional(),
@@ -31443,12 +32778,51 @@ var fieldSchema = external_exports.object({
   maxLen: external_exports.number().int().optional(),
   orderNum: external_exports.number().int().optional(),
   description: external_exports.string().optional(),
-  defaultValue: external_exports.unknown().optional(),
   formula: external_exports.string().optional(),
   link: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
   params: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
-}).passthrough().describe(
-  "Field spec. Common keys: dbDatatype, fieldTypeCd, flags (VEMHI letters), isNullable, maxLen, orderNum, description, link ({entity, otherKey}) for refs, formula for computed columns. Pass through whatever the entity.schema.json allows."
+}).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)) {
+    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.)`
+    });
+  }
+}).describe(
+  `Field spec. RULES (load dforge://reference/flags, /field-types, /column-types first):
+\u2022 flags = a subset of V/E/M only. NEVER combine I or H with them. VEM = required+visible; VE = optional+visible; V = read-only/formula; EM = hidden FK. 'VEMHI' is INVALID.
+\u2022 dbDatatype is AUTO-DERIVED from fieldTypeCd when omitted (e.g. currency \u2192 numeric(18,2), text \u2192 varchar) \u2014 only set it to override. Values: bool, varchar, text, int, bigint, numeric, timestamptz, date, time, cuid, json. NOT boolean/string/datetime/integer/timestamp/number \u2014 'number' is a fieldTypeCd, not a dbDatatype.
+\u2022 A relation is TWO fields: hidden FK (dbDatatype:'cuid', flags:'EM', NO fieldTypeCd) + a Reference (columnType:'R', fieldTypeCd:'lookup', flags:'VEM', link:{entity,thisKey,otherKey}). otherKey = the target entity's PK ('{entity}_id'), never 'id'.
+\u2022 Formula column: columnType:'F', baseDatatypeCd set, NO dbDatatype, flags:'V'.
+\u2022 Column DEFAULTS use 'formula' (e.g. "'draft'" or "TODAY()"), NOT 'defaultValue' (settings-only).
+\u2022 dropdown options go under params.options = [{value,label}] objects, never at the field root and never bare strings.`
 );
 var entityFieldAddSchema = {
   moduleDir: external_exports.string().describe("Path to the module root."),
@@ -31458,7 +32832,7 @@ var entityFieldAddSchema = {
 };
 function entityFieldAdd(args) {
   const { paths, manifest } = loadManifest(args.moduleDir);
-  const entityPath = path4.join(paths.entitiesDir, `${args.entityName}.json`);
+  const entityPath = path6.join(paths.entitiesDir, `${args.entityName}.json`);
   const entity = readJson(entityPath);
   const fields = entity.fields ?? {};
   if (Object.prototype.hasOwnProperty.call(fields, args.fieldName)) {
@@ -31466,7 +32840,7 @@ function entityFieldAdd(args) {
       `Field '${args.fieldName}' already exists on entity '${args.entityName}'. Use entity_field_modify to change it.`
     );
   }
-  entity.fields = { ...fields, [args.fieldName]: args.field };
+  entity.fields = { ...fields, [args.fieldName]: finalizeField(args.field) };
   const files = {
     [rel(paths.root, entityPath)]: jsonText(entity),
     "manifest.json": jsonText(withTodayStamp(manifest))
@@ -31484,55 +32858,562 @@ var entityFieldModifySchema = {
     "Replacement spec. Replaces the existing field entirely \u2014 pass the full desired shape, not a partial patch."
   )
 };
-function entityFieldModify(args) {
+function entityFieldModify(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const entityPath = path6.join(paths.entitiesDir, `${args.entityName}.json`);
+  const entity = readJson(entityPath);
+  const fields = entity.fields ?? {};
+  if (!Object.prototype.hasOwnProperty.call(fields, args.fieldName)) {
+    throw new Error(
+      `Field '${args.fieldName}' not found on entity '${args.entityName}'.`
+    );
+  }
+  entity.fields = { ...fields, [args.fieldName]: finalizeField(args.field) };
+  return makeResult(
+    `Modified field '${args.fieldName}' on entity '${args.entityName}'.`,
+    {
+      [rel(paths.root, entityPath)]: jsonText(entity),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+
+// src/tools/refactor.ts
+var fs6 = __toESM(require("fs"));
+var path7 = __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."),
+  entityName: code.describe("Entity that owns the field."),
+  fieldName: code.describe("Current field code."),
+  newName: code.describe("New field code.")
+};
+function renameKey(obj, oldK, newK) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) out[k === oldK ? newK : k] = v;
+  return out;
+}
+function entityFieldRename(args) {
+  const { entityName, fieldName: oldName, newName } = args;
+  if (oldName === newName) throw new Error("newName must differ from fieldName.");
+  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 entity = readJson(entityPath);
+  const fields = entity.fields ?? {};
+  if (!(oldName in fields)) throw new Error(`Field '${oldName}' not found on entity '${entityName}'.`);
+  if (newName in fields) throw new Error(`Field '${newName}' already exists on entity '${entityName}'. Pick another name.`);
+  const changes = [];
+  const files = {};
+  entity.fields = renameKey(fields, oldName, newName);
+  changes.push(`field '${oldName}' \u2192 '${newName}'`);
+  const oldToken = `[${oldName}]`;
+  const newToken = `[${newName}]`;
+  for (const [fname, f] of Object.entries(entity.fields)) {
+    const link = f.link;
+    if (link && link.thisKey === oldName) {
+      link.thisKey = newName;
+      changes.push(`${fname}.link.thisKey`);
+    }
+    if (typeof f.formula === "string" && f.formula.includes(oldToken)) {
+      f.formula = f.formula.split(oldToken).join(newToken);
+      changes.push(`formula in ${fname}`);
+    }
+  }
+  const refs = entity.references ?? {};
+  for (const [rname, r] of Object.entries(refs)) {
+    const from = r.from;
+    if (from && from.field === oldName) {
+      from.field = newName;
+      changes.push(`references.${rname}.from.field`);
+    }
+  }
+  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(/^\.\//, ""));
+    if (!fs6.existsSync(op)) continue;
+    const oe = readJson(op);
+    let touched = false;
+    for (const [fn, f] of Object.entries(oe.fields ?? {})) {
+      const link = f.link;
+      if (link && link.entity === entityName && link.otherKey === oldName) {
+        link.otherKey = newName;
+        touched = true;
+        changes.push(`${oname}.${fn}.link.otherKey`);
+      }
+    }
+    for (const [rn, r] of Object.entries(oe.references ?? {})) {
+      const to = r.to;
+      if (to && to.entity === entityName && to.field === oldName) {
+        to.field = newName;
+        touched = true;
+        changes.push(`${oname}.references.${rn}.to.field`);
+      }
+    }
+    if (touched) files[rel(paths.root, op)] = jsonText(oe);
+  }
+  const views = readJsonOrDefault(paths.dataViews, {});
+  let viewsTouched = false;
+  for (const v of Object.values(views)) {
+    for (const s of v.dataSources ?? []) {
+      if (s.entityCode !== entityName) continue;
+      for (const c of s.columns ?? []) {
+        if (c.column_cd === oldName) {
+          c.column_cd = newName;
+          viewsTouched = true;
+        }
+      }
+      if (Array.isArray(s.order)) {
+        s.order = s.order.map((o) => {
+          if (o === oldName) {
+            viewsTouched = true;
+            return newName;
+          }
+          if (o === "-" + oldName) {
+            viewsTouched = true;
+            return "-" + newName;
+          }
+          return o;
+        });
+      }
+    }
+  }
+  if (viewsTouched) {
+    files[rel(paths.root, paths.dataViews)] = jsonText(views);
+    changes.push("data_views.json (columns/order)");
+  }
+  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);
+      let data;
+      try {
+        data = JSON.parse(fs6.readFileSync(fp, "utf8"));
+      } catch {
+        continue;
+      }
+      if (data?.entityCode !== entityName || !Array.isArray(data.records)) continue;
+      let touched = false;
+      data.records = data.records.map((rec) => {
+        if (rec && typeof rec === "object" && oldName in rec) {
+          touched = true;
+          return renameKey(rec, oldName, newName);
+        }
+        return rec;
+      });
+      if (touched) {
+        files[rel(paths.root, fp)] = jsonText(data);
+        changes.push(`seed-data/${file2}`);
+      }
+    }
+  }
+  files["manifest.json"] = jsonText(withTodayStamp(manifest));
+  return makeResult(
+    `Renamed '${entityName}.${oldName}' \u2192 '${newName}', propagated to ${changes.length} location(s): ${changes.join("; ")}.`,
+    files,
+    "Review the returned files before writing \u2014 this rewrites every file that referenced the field. Run dforge_module_validate after writing to confirm no references were missed."
+  );
+}
+var entityFieldRemoveSchema = {
+  moduleDir: external_exports.string().describe("Path to the module root."),
+  entityName: code.describe("Entity that owns the field."),
+  fieldName: code.describe("Field code to remove.")
+};
+function entityFieldRemove(args) {
+  const { entityName, fieldName } = 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 entity = readJson(entityPath);
+  const fields = entity.fields ?? {};
+  if (!(fieldName in fields)) throw new Error(`Field '${fieldName}' not found on entity '${entityName}'.`);
+  const removed = /* @__PURE__ */ new Set([fieldName]);
+  const changes = [];
+  const warnings = [];
+  const files = {};
+  for (const [fn, f] of Object.entries(fields)) {
+    const link = f.link;
+    if (fn !== fieldName && link && link.thisKey === fieldName) {
+      removed.add(fn);
+      changes.push(`paired reference column '${fn}'`);
+    }
+  }
+  const newFields = {};
+  for (const [k, v] of Object.entries(fields)) if (!removed.has(k)) newFields[k] = v;
+  entity.fields = newFields;
+  changes.push(`field '${fieldName}'`);
+  const refs = entity.references ?? {};
+  for (const [rn, r] of Object.entries(refs)) {
+    const from = r.from;
+    if (from && removed.has(from.field)) {
+      delete refs[rn];
+      changes.push(`references.${rn}`);
+    }
+  }
+  files[rel(paths.root, entityPath)] = jsonText(entity);
+  for (const [fn, f] of Object.entries(entity.fields)) {
+    if (typeof f.formula !== "string") continue;
+    for (const r of removed) {
+      if (f.formula.includes(`[${r}]`)) {
+        warnings.push(`formula in '${fn}' still references removed '[${r}]'`);
+      }
+    }
+  }
+  const views = readJsonOrDefault(paths.dataViews, {});
+  let viewsTouched = false;
+  for (const v of Object.values(views)) {
+    for (const s of v.dataSources ?? []) {
+      if (s.entityCode !== entityName) continue;
+      if (Array.isArray(s.columns)) {
+        const cols = s.columns;
+        const filtered = cols.filter((c) => !removed.has(c.column_cd));
+        if (filtered.length !== cols.length) {
+          s.columns = filtered;
+          viewsTouched = true;
+        }
+      }
+      if (Array.isArray(s.order)) {
+        const ord = s.order;
+        const filtered = ord.filter((o) => !removed.has(o.replace(/^-/, "")));
+        if (filtered.length !== ord.length) {
+          s.order = filtered;
+          viewsTouched = true;
+        }
+      }
+    }
+  }
+  if (viewsTouched) {
+    files[rel(paths.root, paths.dataViews)] = jsonText(views);
+    changes.push("data_views.json (columns/order)");
+  }
+  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);
+      let data;
+      try {
+        data = JSON.parse(fs6.readFileSync(fp, "utf8"));
+      } catch {
+        continue;
+      }
+      if (data?.entityCode !== entityName || !Array.isArray(data.records)) continue;
+      let touched = false;
+      data.records = data.records.map((rec) => {
+        const out = {};
+        let changed = false;
+        for (const [k, val] of Object.entries(rec)) {
+          if (removed.has(k)) changed = true;
+          else out[k] = val;
+        }
+        if (changed) touched = true;
+        return changed ? out : rec;
+      });
+      if (touched) {
+        files[rel(paths.root, fp)] = jsonText(data);
+        changes.push(`seed-data/${file2}`);
+      }
+    }
+  }
+  for (const [oname, orel] of Object.entries(manifest.entities ?? {})) {
+    if (oname === entityName || oname.includes(".")) continue;
+    const op = path7.join(paths.root, orel.replace(/^\.\//, ""));
+    if (!fs6.existsSync(op)) continue;
+    let oe;
+    try {
+      oe = readJson(op);
+    } catch {
+      continue;
+    }
+    for (const [fn, f] of Object.entries(oe.fields ?? {})) {
+      const link = f.link;
+      if (link && link.entity === entityName && removed.has(link.otherKey)) {
+        warnings.push(`'${oname}.${fn}' references removed '${entityName}.${link.otherKey}' \u2014 its FK now dangles`);
+      }
+    }
+  }
+  files["manifest.json"] = jsonText(withTodayStamp(manifest));
+  const warnText = [
+    warnings.length ? `Manual follow-up: ${warnings.join("; ")}.` : "",
+    "Run dforge_module_validate after writing to confirm nothing dangles."
+  ].filter(Boolean).join(" ");
+  return makeResult(
+    `Removed '${entityName}.${fieldName}'${removed.size > 1 ? ` (+${removed.size - 1} paired column)` : ""}; cascade-cleaned ${changes.length} location(s).`,
+    files,
+    warnText
+  );
+}
+var SYSTEM_ENTITIES = /* @__PURE__ */ new Set(["user", "document", "menu_item", "resource"]);
+var entityRenameSchema = {
+  moduleDir: external_exports.string().describe("Path to the module root."),
+  entityName: code.describe("Current entity code."),
+  newName: code.describe("New entity code.")
+};
+function entityRename(args) {
+  const { entityName: oldE, newName: newE } = args;
+  if (oldE === newE) throw new Error("newName must differ from entityName.");
+  if (SYSTEM_ENTITIES.has(newE)) throw new Error(`'${newE}' is a reserved system entity name.`);
   const { paths, manifest } = loadManifest(args.moduleDir);
-  const entityPath = path4.join(paths.entitiesDir, `${args.entityName}.json`);
-  const entity = readJson(entityPath);
-  const fields = entity.fields ?? {};
-  if (!Object.prototype.hasOwnProperty.call(fields, args.fieldName)) {
-    throw new Error(
-      `Field '${args.fieldName}' not found on entity '${args.entityName}'.`
-    );
+  const entityMap = manifest.entities ?? {};
+  if (!(oldE in entityMap)) throw new Error(`Entity '${oldE}' is not in the manifest.`);
+  if (newE in entityMap) throw new Error(`Entity '${newE}' already exists in this module.`);
+  const files = {};
+  const deletes = [];
+  const changes = [];
+  const oldPath = path7.join(paths.root, entityMap[oldE].replace(/^\.\//, ""));
+  const entity = readJson(oldPath);
+  const usesIdentity = (entity.traits ?? []).includes("identity");
+  const oldPk = `${oldE}_id`;
+  const newPk = `${newE}_id`;
+  if (entity.dbObject === oldE) {
+    entity.dbObject = newE;
+    changes.push("entity.dbObject");
+  }
+  const newPath = path7.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`);
+  manifest.entities = renameKey(entityMap, oldE, newE);
+  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(/^\.\//, ""));
+    if (!fs6.existsSync(op)) continue;
+    const oe = readJson(op);
+    let touched = false;
+    for (const [fn, f] of Object.entries(oe.fields ?? {})) {
+      const link = f.link;
+      if (link && link.entity === oldE) {
+        link.entity = newE;
+        touched = true;
+        changes.push(`${oname}.${fn}.link.entity`);
+        if (usesIdentity && link.otherKey === oldPk) link.otherKey = newPk;
+      }
+    }
+    for (const [rn, r] of Object.entries(oe.references ?? {})) {
+      const to = r.to;
+      if (to && to.entity === oldE) {
+        to.entity = newE;
+        touched = true;
+        changes.push(`${oname}.references.${rn}.to.entity`);
+        if (usesIdentity && to.field === oldPk) to.field = newPk;
+      }
+    }
+    if (touched) files[rel(paths.root, op)] = jsonText(oe);
   }
-  entity.fields = { ...fields, [args.fieldName]: args.field };
-  return makeResult(
-    `Modified field '${args.fieldName}' on entity '${args.entityName}'.`,
-    {
-      [rel(paths.root, entityPath)]: jsonText(entity),
-      "manifest.json": jsonText(withTodayStamp(manifest))
+  const views = readJsonOrDefault(paths.dataViews, {});
+  let viewsTouched = false;
+  for (const v of Object.values(views)) {
+    for (const s of v.dataSources ?? []) {
+      if (s.entityCode === oldE) {
+        s.entityCode = newE;
+        viewsTouched = true;
+      }
     }
+  }
+  if (viewsTouched) {
+    files[rel(paths.root, paths.dataViews)] = jsonText(views);
+    changes.push("data_views.json (entityCode)");
+  }
+  const roles = readJsonOrDefault(paths.roles, {});
+  let rolesTouched = false;
+  for (const r of Object.values(roles)) {
+    const rights = r.rights;
+    if (rights && oldE in rights) {
+      r.rights = renameKey(rights, oldE, newE);
+      rolesTouched = true;
+    }
+  }
+  if (rolesTouched) {
+    files[rel(paths.root, paths.roles)] = jsonText(roles);
+    changes.push("roles.json (rights keys)");
+  }
+  const actions = readJsonOrDefault(paths.actions, {});
+  let actionsTouched = false;
+  for (const a of Object.values(actions)) {
+    if (a.entity === oldE) {
+      a.entity = newE;
+      actionsTouched = true;
+    }
+    if (a.entityCode === oldE) {
+      a.entityCode = newE;
+      actionsTouched = true;
+    }
+  }
+  if (actionsTouched) {
+    files[rel(paths.root, paths.actions)] = jsonText(actions);
+    changes.push("actions.json (entity)");
+  }
+  const folders = readJsonOrDefault(paths.folders, {});
+  let foldersTouched = false;
+  const walkFolders = (node) => {
+    if (!node || typeof node !== "object") return;
+    const rec = node;
+    const ents = rec.entities;
+    if (ents && oldE in ents) {
+      rec.entities = renameKey(ents, oldE, newE);
+      foldersTouched = true;
+    }
+    const children = rec.children;
+    if (children) for (const c of Object.values(children)) walkFolders(c);
+  };
+  walkFolders(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);
+      let data;
+      try {
+        data = JSON.parse(fs6.readFileSync(fp, "utf8"));
+      } catch {
+        continue;
+      }
+      if (data?.entityCode !== oldE) continue;
+      data.entityCode = newE;
+      if (usesIdentity && Array.isArray(data.records)) {
+        data.records = data.records.map((r) => oldPk in r ? renameKey(r, oldPk, newPk) : r);
+      }
+      files[rel(paths.root, fp)] = jsonText(data);
+      changes.push(`seed-data/${file2}`);
+    }
+  }
+  files["manifest.json"] = jsonText(withTodayStamp(manifest));
+  return makeResult(
+    `Renamed entity '${oldE}' \u2192 '${newE}'${usesIdentity ? ` (PK ${oldPk} \u2192 ${newPk})` : ""}; propagated to ${changes.length} location(s). Old entity file deleted.`,
+    files,
+    `Reports datasets, translation files, menu labels, and DSL bodies are NOT rewritten \u2014 check anything referencing '${oldE}'. Run dforge_module_validate after writing.`,
+    deletes
   );
 }
-var entityFieldRemoveSchema = {
-  moduleDir: external_exports.string(),
-  entityName: external_exports.string().regex(/^[a-z][a-z0-9_]*$/),
-  fieldName: external_exports.string().regex(/^[a-z][a-z0-9_]*$/)
+var entityDeleteSchema = {
+  moduleDir: external_exports.string().describe("Path to the module root."),
+  entityName: code.describe("Entity code to delete.")
 };
-function entityFieldRemove(args) {
+function entityDelete(args) {
+  const { entityName: target } = args;
   const { paths, manifest } = loadManifest(args.moduleDir);
-  const entityPath = path4.join(paths.entitiesDir, `${args.entityName}.json`);
-  const entity = readJson(entityPath);
-  const fields = entity.fields ?? {};
-  if (!Object.prototype.hasOwnProperty.call(fields, args.fieldName)) {
-    throw new Error(
-      `Field '${args.fieldName}' not found on entity '${args.entityName}'.`
-    );
+  const entityMap = manifest.entities ?? {};
+  if (!(target in entityMap)) throw new Error(`Entity '${target}' is not in the manifest.`);
+  const files = {};
+  const deletes = [];
+  const changes = [];
+  const warnings = [];
+  const ePath = path7.join(paths.root, entityMap[target].replace(/^\.\//, ""));
+  if (fs6.existsSync(ePath)) deletes.push(rel(paths.root, ePath));
+  const { [target]: _dropped, ...restEntities } = entityMap;
+  void _dropped;
+  manifest.entities = restEntities;
+  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(/^\.\//, ""));
+    if (!fs6.existsSync(op)) continue;
+    let oe;
+    try {
+      oe = readJson(op);
+    } catch {
+      continue;
+    }
+    for (const [fn, f] of Object.entries(oe.fields ?? {})) {
+      const link = f.link;
+      if (link && link.entity === target) {
+        warnings.push(`'${oname}.${fn}' references deleted entity '${target}' \u2014 remove or repoint it`);
+      }
+    }
+  }
+  const roles = readJsonOrDefault(paths.roles, {});
+  let rolesTouched = false;
+  for (const r of Object.values(roles)) {
+    const rights = r.rights;
+    if (rights && target in rights) {
+      delete rights[target];
+      rolesTouched = true;
+    }
+  }
+  if (rolesTouched) {
+    files[rel(paths.root, paths.roles)] = jsonText(roles);
+    changes.push("roles.json (rights key)");
+  }
+  const folders = readJsonOrDefault(paths.folders, {});
+  let foldersTouched = false;
+  const walkFolders = (node) => {
+    if (!node || typeof node !== "object") return;
+    const rec = node;
+    const ents = rec.entities;
+    if (ents && target in ents) {
+      delete ents[target];
+      foldersTouched = true;
+    }
+    const children = rec.children;
+    if (children) for (const c of Object.values(children)) walkFolders(c);
+  };
+  walkFolders(folders);
+  if (foldersTouched) {
+    files[rel(paths.root, paths.folders)] = jsonText(folders);
+    changes.push("folders.json (binding)");
+  }
+  const views = readJsonOrDefault(paths.dataViews, {});
+  let viewsTouched = false;
+  const removedViews = [];
+  for (const [vcode, v] of Object.entries(views)) {
+    const ds = v.dataSources;
+    if (!Array.isArray(ds)) continue;
+    const filtered = ds.filter((s) => s.entityCode !== target);
+    if (filtered.length === ds.length) continue;
+    viewsTouched = true;
+    if (filtered.length === 0) {
+      delete views[vcode];
+      removedViews.push(vcode);
+    } else {
+      v.dataSources = filtered;
+    }
+  }
+  if (viewsTouched) {
+    files[rel(paths.root, paths.dataViews)] = jsonText(views);
+    changes.push("data_views.json (sources)");
+  }
+  if (removedViews.length) {
+    warnings.push(`deleted view(s) ${removedViews.join(", ")} (no sources left) \u2014 check menus pointing at them`);
+  }
+  const actions = readJsonOrDefault(paths.actions, {});
+  for (const [acode, a] of Object.entries(actions)) {
+    if (a.entity === target || a.entityCode === target) {
+      warnings.push(`action '${acode}' targets deleted entity '${target}'`);
+    }
+  }
+  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);
+      let data;
+      try {
+        data = JSON.parse(fs6.readFileSync(fp, "utf8"));
+      } catch {
+        continue;
+      }
+      if (data?.entityCode === target) {
+        deletes.push(rel(paths.root, fp));
+        changes.push(`seed-data/${file2}`);
+      }
+    }
   }
-  const { [args.fieldName]: _removed, ...rest } = fields;
-  void _removed;
-  entity.fields = rest;
+  files["manifest.json"] = jsonText(withTodayStamp(manifest));
+  const warnText = [
+    warnings.length ? `Manual follow-up: ${warnings.join("; ")}.` : "",
+    "Run dforge_module_validate after writing."
+  ].filter(Boolean).join(" ");
   return makeResult(
-    `Removed field '${args.fieldName}' from entity '${args.entityName}'. Note: dependent views / formulas referencing this field will break \u2014 review them.`,
-    {
-      [rel(paths.root, entityPath)]: jsonText(entity),
-      "manifest.json": jsonText(withTodayStamp(manifest))
-    },
-    "Removing fields can break dependent views, role rights, formulas, action DSL, and seed data. Run `dforge_module_inspect` after writing to spot broken references."
+    `Deleted entity '${target}'; cleaned ${changes.length} artifact(s)${deletes.length > 1 ? `, removed ${deletes.length} file(s)` : ""}.`,
+    files,
+    warnText,
+    deletes
   );
 }
 
 // src/tools/action-add.ts
-var path5 = __toESM(require("path"));
+var path8 = __toESM(require("path"));
 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)."),
@@ -31540,16 +33421,30 @@ var actionAddSchema = {
     "Entity this action targets. May be cross-module via dot notation ('fin.invoice')."
   ),
   label: external_exports.string().min(1).describe("Display label in the action menu."),
-  mode: external_exports.enum(["single", "each", "batch"]).default("single").describe(
-    "Execution mode. 'single' = whole selection at once, 'each' = per-record, 'batch' = explicit `for x in records` loop in DSL."
+  description: external_exports.string().optional().describe("Tooltip / description text. Defaults to the label if omitted."),
+  executionMode: external_exports.enum(["single", "each", "batch"]).default("single").describe(
+    "Execution mode (emitted as `executionMode`). 'single' = whole selection at once, 'each' = per-record, 'batch' = explicit `for x in records` loop in DSL."
+  ),
+  icon: external_exports.string().optional().describe(
+    "Bootstrap icon name. The `bi-` prefix is added automatically if missing (e.g. 'check-circle' \u2192 'bi-check-circle'). NOTE: action icons keep the prefix; menu icons drop it."
   ),
-  icon: external_exports.string().optional().describe("Bootstrap icon class (e.g. 'play-fill')."),
-  background: external_exports.boolean().default(false).describe("Run asynchronously (queues to background_action table)."),
+  isAsync: external_exports.boolean().default(false).describe("Run asynchronously in the background (emitted as `isAsync`)."),
   dslBody: external_exports.string().describe(
     "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)) {
+    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).`
+    );
+  }
+}
 function actionAdd(args) {
+  assertNoFormulaDateInExecute(args.dslBody, args.code);
   const { paths, manifest } = loadManifest(args.moduleDir);
   const actionsJson = readJsonOrDefault(paths.actions, {});
   if (Object.prototype.hasOwnProperty.call(actionsJson, args.code)) {
@@ -31558,18 +33453,21 @@ function actionAdd(args) {
     );
   }
   const actionEntry = {
-    entity: args.entityCode,
     label: args.label,
-    mode: args.mode,
-    background: args.background,
-    dsl: `./logic/actions/${args.code}.dsl`
+    description: args.description ?? args.label,
+    entityCode: args.entityCode,
+    executionMode: args.executionMode,
+    script: args.code,
+    isAsync: args.isAsync
   };
-  if (args.icon) actionEntry.icon = args.icon;
+  if (args.icon) {
+    actionEntry.icon = args.icon.startsWith("bi-") ? args.icon : `bi-${args.icon}`;
+  }
   actionsJson[args.code] = actionEntry;
-  const dslPath = path5.join(paths.logicDir, "actions", `${args.code}.dsl`);
+  const dslPath = path8.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}' (mode=${args.mode}${args.background ? ", background" : ""}).`,
+    `Added action '${args.code}' targeting entity '${args.entityCode}' (executionMode=${args.executionMode}${args.isAsync ? ", async" : ""}).`,
     {
       [rel(paths.root, paths.actions)]: jsonText(actionsJson),
       [rel(paths.root, dslPath)]: dslBody,
@@ -31598,7 +33496,8 @@ var dataViewSchema = external_exports.object({
     "tree-grid",
     "diagram",
     "master-detail",
-    "library"
+    "library",
+    "matrix"
   ]),
   label: external_exports.string().optional(),
   description: external_exports.string().optional(),
@@ -31689,7 +33588,15 @@ var settingAddSchema = {
     formula: external_exports.string().optional(),
     required: external_exports.boolean().optional(),
     params: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
-  }).passthrough()
+  }).passthrough().superRefine((val, ctx) => {
+    const ftc = val.fieldTypeCd;
+    if (typeof ftc === "string" && !isFieldTypeCd(ftc)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        message: `fieldTypeCd '${ftc}' is not a valid field type. Valid codes: ${[...fieldTypeCds].sort().join(", ")}. (See dforge://reference/field-types.)`
+      });
+    }
+  })
 };
 function settingAdd(args) {
   const { paths, manifest } = loadManifest(args.moduleDir);
@@ -31710,10 +33617,11 @@ var roleAddSchema = {
   ),
   description: external_exports.string(),
   rights: external_exports.record(external_exports.string(), external_exports.string()).describe(
-    "Map: entityCode (or actionCode/reportCode) \u2192 rights string. For entities: any combination of 'S' (Select), 'I' (Insert), 'U' (Update), 'D' (Delete), 'C' (Clone), e.g. 'SIUDC' for full. For actions/reports: 'E' (Execute)."
+    "Map: object code \u2192 rights string. Keys: same-module entity bare ('product'), cross-module entity dotted ('fin.invoice'), action/report/folder with a COLON prefix ('action:approve', 'report:summary', 'folder:east') \u2014 never a dot. Values: entities use 'S'/'I'/'U'/'D'/'C' (e.g. 'SIUDC'); actions/reports/folders use 'E'. To deny, omit the key (never map to '')."
   )
 };
 function roleAdd(args) {
+  assertValidRights(args.rights);
   const { paths, manifest } = loadManifest(args.moduleDir);
   const roles = readJsonOrDefault(paths.roles, {});
   if (Object.prototype.hasOwnProperty.call(roles, args.code)) {
@@ -31809,13 +33717,15 @@ var roleRightSetSchema = {
   moduleDir: external_exports.string(),
   roleCode: external_exports.string().describe("Role code as it appears in security/roles.json (e.g. 'crm.admin')."),
   object: external_exports.string().describe(
-    "Entity / action / report code to grant rights on. For cross-module rights, use dotted form ('fin.invoice')."
+    "Object to grant rights on. Same-module entity: bare ('product'). Cross-module entity: dotted ('fin.invoice'). Action/report/folder: COLON prefix ('action:approve', 'report:summary', 'folder:east') \u2014 never a dot."
   ),
   rights: external_exports.string().describe(
-    "Rights string. Entities: any combination of S/I/U/D/C (use '' to revoke all). Actions/reports: 'E' or ''."
+    "Rights string. Entities: any combination of S/I/U/D/C (use '' to revoke all). Actions/reports/folders: 'E' or '' to revoke."
   )
 };
 function roleRightSet(args) {
+  assertValidRightKey(args.object);
+  assertValidRightValue(args.object, args.rights, true);
   const { paths, manifest } = loadManifest(args.moduleDir);
   const roles = readJson(paths.roles);
   const role = roles[args.roleCode];
@@ -31842,8 +33752,8 @@ function roleRightSet(args) {
 }
 
 // src/tools/module-inspect.ts
-var fs4 = __toESM(require("fs"));
-var path6 = __toESM(require("path"));
+var fs7 = __toESM(require("fs"));
+var path9 = __toESM(require("path"));
 var moduleInspectSchema = {
   moduleDir: external_exports.string()
 };
@@ -31851,7 +33761,7 @@ function moduleInspect(args) {
   const { paths, manifest } = loadManifest(args.moduleDir);
   const entities = manifest.entities ?? {};
   const entitySummaries = Object.entries(entities).map(([name, relPath]) => {
-    const abs = path6.join(paths.root, relPath.replace(/^\.\//, ""));
+    const abs = path9.join(paths.root, relPath.replace(/^\.\//, ""));
     const e = readJsonOrDefault(abs, {});
     const fields = e.fields ?? {};
     return {
@@ -31865,8 +33775,8 @@ function moduleInspect(args) {
     };
   });
   const views = readJsonOrDefault(paths.dataViews, {});
-  const viewSummaries = Object.entries(views).map(([code, v]) => ({
-    code,
+  const viewSummaries = Object.entries(views).map(([code2, v]) => ({
+    code: code2,
     viewType: v.viewType ?? "?",
     sources: (v.dataSources ?? []).map(
       (s) => s.entityCode ?? "?"
@@ -31875,18 +33785,18 @@ function moduleInspect(args) {
   const foldersTree = readJsonOrDefault(paths.folders, {});
   const folderDepth = computeDepth(foldersTree);
   const menus = readJsonOrDefault(paths.menus, {});
-  const menuSummaries = Object.entries(menus).map(([code, m]) => ({
-    code,
+  const menuSummaries = Object.entries(menus).map(([code2, m]) => ({
+    code: code2,
     itemCount: Object.keys(m.items ?? {}).length
   }));
   const rolesJson = readJsonOrDefault(paths.roles, {});
-  const roleSummaries = Object.entries(rolesJson).map(([code, r]) => {
+  const roleSummaries = Object.entries(rolesJson).map(([code2, r]) => {
     const rights = r.rights ?? {};
-    return { code, objectCount: Object.keys(rights).length, rights };
+    return { code: code2, objectCount: Object.keys(rights).length, rights };
   });
   const actions = readJsonOrDefault(paths.actions, {});
-  const actionSummaries = Object.entries(actions).map(([code, a]) => ({
-    code,
+  const actionSummaries = Object.entries(actions).map(([code2, a]) => ({
+    code: code2,
     entity: a.entity ?? "?",
     mode: a.mode ?? "single",
     background: Boolean(a.background)
@@ -31894,8 +33804,8 @@ function moduleInspect(args) {
   const reports = Object.keys(readJsonOrDefault(paths.reports, {}));
   const settings = Object.keys(readJsonOrDefault(paths.settings, {}));
   const jobs = Object.keys(readJsonOrDefault(paths.jobs, {}));
-  const seedFiles = fs4.existsSync(paths.seedDataDir) ? fs4.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json")).sort() : [];
-  const translations = fs4.existsSync(paths.translationsDir) ? fs4.readdirSync(paths.translationsDir).filter((f) => f.endsWith(".json")).sort() : [];
+  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 summary = {
     module: {
       code: manifest.code,
@@ -31932,10 +33842,325 @@ function computeDepth(folder, current = 1) {
   return childDepths.length === 0 ? current : Math.max(...childDepths);
 }
 
+// src/tools/module-validate.ts
+var fs8 = __toESM(require("fs"));
+var path10 = __toESM(require("path"));
+var moduleValidateSchema = {
+  moduleDir: external_exports.string().describe("Path to the module root. Run this after authoring and before dforge_module_pack.")
+};
+var SYSTEM_ENTITY_PK = {
+  user: "user_id",
+  document: "document_id",
+  menu_item: "menu_item_id",
+  resource: "resource_id"
+};
+function moduleValidate(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const issues = [];
+  const err = (where, message) => issues.push({ level: "error", where, message });
+  const warn = (where, message) => issues.push({ level: "warning", where, message });
+  const entityMap = manifest.entities ?? {};
+  const entities = {};
+  const columnsOf = {};
+  for (const [name, relPath] of Object.entries(entityMap)) {
+    if (name.includes(".")) continue;
+    const abs = path10.join(paths.root, relPath.replace(/^\.\//, ""));
+    if (!fs8.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"));
+    } catch (ex) {
+      err(`entities/${name}.json`, `invalid JSON: ${ex.message}`);
+      continue;
+    }
+    entities[name] = e;
+    const fields = e.fields ?? {};
+    const cols = new Set(Object.keys(fields));
+    const traits2 = e.traits ?? [];
+    try {
+      for (const c of Object.keys(expandTraits(traits2, name))) cols.add(c);
+    } catch {
+    }
+    columnsOf[name] = cols;
+  }
+  const deps = new Set(Object.keys(manifest.dependencies ?? {}));
+  const isKnownEntity = (code2) => {
+    if (code2 in entities || code2 in SYSTEM_ENTITY_PK) 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 pkOf = (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`;
+    return void 0;
+  };
+  for (const [name, e] of Object.entries(entities)) {
+    const fields = e.fields ?? {};
+    for (const [fname, f] of Object.entries(fields)) {
+      if (!f || f.columnType !== "R" || !f.link) continue;
+      const link = f.link;
+      const where = `entities/${name}.json \u2192 ${fname}.link`;
+      const target = link.entity;
+      if (!target || !isKnownEntity(target)) {
+        err(where, `link.entity '${target}' is not a known entity (same-module, system, or cross-module dependency)`);
+      }
+      const thisKey = link.thisKey;
+      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;
+      if (pk && link.otherKey && link.otherKey !== pk) {
+        warn(where, `link.otherKey '${link.otherKey}' \u2014 expected '${pk}' (the target entity's PK)`);
+      }
+    }
+    const refs = e.references ?? {};
+    for (const [rname, r] of Object.entries(refs)) {
+      const fromField = r?.from?.field;
+      if (fromField && !columnsOf[name].has(fromField)) {
+        err(`entities/${name}.json \u2192 references.${rname}`, `from.field '${fromField}' is not a column on '${name}'`);
+      }
+      const toEntity = r?.to?.entity;
+      if (toEntity && !isKnownEntity(toEntity)) {
+        err(`entities/${name}.json \u2192 references.${rname}`, `to.entity '${toEntity}' is not a known entity`);
+      }
+    }
+  }
+  const views = readJsonOrDefault(paths.dataViews, {});
+  const viewCodes = new Set(Object.keys(views));
+  for (const [vcode, v] of Object.entries(views)) {
+    const sources = v.dataSources ?? [];
+    for (const s of sources) {
+      const ent = s.entityCode;
+      if (!ent || !isKnownEntity(ent)) {
+        err(`data_views \u2192 ${vcode}`, `dataSource entityCode '${ent}' is not a known entity`);
+        continue;
+      }
+      const cols = columnsOf[ent];
+      if (!cols) continue;
+      for (const c of s.columns ?? []) {
+        const cc = c.column_cd;
+        if (cc && !cols.has(cc)) {
+          err(`data_views \u2192 ${vcode}`, `column '${cc}' is not a field on entity '${ent}'`);
+        }
+      }
+    }
+  }
+  const menus = readJsonOrDefault(paths.menus, {});
+  const walk = (node, where) => {
+    if (!node || typeof node !== "object") return;
+    const rec = node;
+    const dvc = rec.dataViewCode;
+    if (typeof dvc === "string" && !viewCodes.has(dvc)) {
+      err(where, `dataViewCode '${dvc}' has no matching view in data_views.json`);
+    }
+    for (const [k, child] of Object.entries(rec)) {
+      if (child && typeof child === "object") walk(child, `${where} \u2192 ${k}`);
+    }
+  };
+  for (const [mcode, m] of Object.entries(menus)) walk(m, `menus \u2192 ${mcode}`);
+  const roles = readJsonOrDefault(paths.roles, {});
+  const actions = readJsonOrDefault(paths.actions, {});
+  const reports = readJsonOrDefault(paths.reports, {});
+  for (const [rcode, r] of Object.entries(roles)) {
+    const rights = r.rights ?? {};
+    for (const key of Object.keys(rights)) {
+      if (key.startsWith("action:")) {
+        const a = key.slice("action:".length);
+        if (!(a in actions)) err(`roles \u2192 ${rcode}`, `grants on 'action:${a}' but no such action exists`);
+      } else if (key.startsWith("report:")) {
+        const rp = key.slice("report:".length);
+        if (!(rp in reports)) err(`roles \u2192 ${rcode}`, `grants on 'report:${rp}' but no such report exists`);
+      } else if (key.startsWith("folder:")) {
+      } else if (!isKnownEntity(key)) {
+        err(`roles \u2192 ${rcode}`, `grants rights on '${key}', which is not a known entity (same-module, system, or a declared cross-module dependency)`);
+      }
+    }
+  }
+  try {
+    const { uncoveredEntities } = checkSecurityCoverage(args.moduleDir);
+    for (const e of uncoveredEntities) {
+      warn("security", `entity '${e}' has no role granting Select (S) \u2014 it will be inaccessible`);
+    }
+  } catch {
+  }
+  const errors = issues.filter((i) => i.level === "error");
+  const warnings = issues.filter((i) => i.level === "warning");
+  const clean = errors.length === 0 && warnings.length === 0;
+  const summary = clean ? `\u2713 ${manifest.code}: no cross-reference issues found across ${Object.keys(entities).length} entities, ${viewCodes.size} views, ${Object.keys(roles).length} roles.` : `${manifest.code}: ${errors.length} error(s), ${warnings.length} warning(s).${errors.length ? ` First error: ${errors[0].where} \u2014 ${errors[0].message}` : ""}`;
+  return {
+    summary,
+    files: {
+      "_validate.json": JSON.stringify({ ok: errors.length === 0, errors, warnings }, null, "	") + "\n"
+    },
+    warning: errors.length ? `${errors.length} validation error(s) \u2014 fix before dforge_module_pack / dforge_module_install. Details in _validate.json.` : void 0
+  };
+}
+
+// src/tools/behavior.ts
+var triggerAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Trigger code, unique within the module."),
+  entity: external_exports.string().describe(
+    "Entity whose events fire this trigger. Cross-module dotted form supported ('fin.invoice')."
+  ),
+  event: external_exports.enum(["insert", "update", "delete", "status_change", "any"]).describe(
+    "insert/update/delete are obvious. status_change fires only when status field changes value. 'any' fires for all insert/update/delete."
+  ),
+  action: external_exports.string().describe("Action code to invoke. Cross-module dotted form ('module.action') supported."),
+  description: external_exports.string().optional(),
+  condition: external_exports.string().optional().describe(
+    "Optional formula expression (same shape as canExecute) using `[field]` syntax. Single-line boolean. If omitted, trigger fires on every matching event."
+  ),
+  params: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
+    "Static params merged into the action invocation alongside auto-injected record_id."
+  ),
+  async: external_exports.boolean().default(false).describe(
+    "When true, the action runs in background (recommended for slow actions). When false, runs in the same transaction \u2014 action failure rolls back the original DB change."
+  )
+};
+function triggerAdd(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const file2 = readJsonOrDefault(
+    paths.triggers,
+    { triggers: [] }
+  );
+  if (file2.triggers.some((t) => t.code === args.code)) {
+    throw new Error(`Trigger '${args.code}' already exists.`);
+  }
+  const entry = {
+    code: args.code,
+    entity: args.entity,
+    event: args.event,
+    action: args.action,
+    async: args.async
+  };
+  if (args.description) entry.description = args.description;
+  if (args.condition) entry.condition = args.condition;
+  if (args.params) entry.params = args.params;
+  file2.triggers.push(entry);
+  return makeResult(
+    `Added trigger '${args.code}' on ${args.entity}.${args.event} \u2192 action '${args.action}'${args.async ? " (async)" : ""}.`,
+    {
+      [rel(paths.root, paths.triggers)]: jsonText(file2),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+var jobAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Job code, unique within the module."),
+  action: external_exports.string().describe(
+    "Action code to invoke on schedule. MUST NOT use record-context (`[field]`) syntax \u2014 scheduled jobs run as system user with no current record. Wrap record-context actions in a thin action that queries first."
+  ),
+  schedule: external_exports.string().describe(
+    "5-field cron expression (minute hour day-of-month month day-of-week). Evaluated in the tenant's time zone (auth.tenant.time_zone) or per-job override."
+  ),
+  timeout: external_exports.number().int().min(1).max(3600).describe(
+    "Hard kill timeout in seconds. Required. If > 300, you must also set `class: 'long_running'`."
+  ),
+  description: external_exports.string().optional(),
+  concurrency: external_exports.number().int().min(1).default(1).describe("Max overlapping executions. Default 1 (skip new fire if previous still running)."),
+  jobClass: external_exports.enum(["standard", "long_running"]).default("standard").describe(
+    "Required to be 'long_running' when timeout > 300. Affects scheduler thread-pool routing."
+  ),
+  paused: external_exports.boolean().default(false)
+};
+function jobAdd(args) {
+  if (args.timeout > 300 && args.jobClass !== "long_running") {
+    throw new Error(
+      "Jobs with timeout > 300s must set jobClass: 'long_running' \u2014 see logic/jobs.json convention."
+    );
+  }
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const file2 = readJsonOrDefault(
+    paths.jobs,
+    { jobs: [] }
+  );
+  if (file2.jobs.some((j) => j.code === args.code)) {
+    throw new Error(`Job '${args.code}' already exists.`);
+  }
+  const entry = {
+    code: args.code,
+    action: args.action,
+    schedule: args.schedule,
+    timeout: args.timeout,
+    concurrency: args.concurrency,
+    class: args.jobClass
+  };
+  if (args.description) entry.description = args.description;
+  if (args.paused) entry.paused = true;
+  file2.jobs.push(entry);
+  return makeResult(
+    `Added job '${args.code}' (schedule '${args.schedule}', timeout ${args.timeout}s) \u2192 action '${args.action}'.`,
+    {
+      [rel(paths.root, paths.jobs)]: jsonText(file2),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+var webhookAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Subscription code, unique within the module."),
+  entity: external_exports.string().describe("Entity whose events fire this webhook."),
+  event: external_exports.enum(["insert", "update", "delete", "status_change", "any"]).describe("Same event taxonomy as triggers."),
+  endpointUrl: external_exports.string().url().describe("Destination URL \u2014 receives POST with the payload."),
+  description: external_exports.string().optional(),
+  condition: external_exports.string().optional().describe("Optional formula filter; fires only when true. Same shape as trigger condition."),
+  payload: external_exports.object({
+    include: external_exports.array(external_exports.string()).optional().describe("Whitelist of field codes to include. Omit to send all fields."),
+    exclude: external_exports.array(external_exports.string()).optional().describe("Blacklist (applied after include). Use for stripping sensitive cols."),
+    includeOld: external_exports.boolean().optional().describe(
+      "For update/status_change events, also include the pre-change record as `old`."
+    )
+  }).optional().describe(
+    "Payload shape. If omitted, sends full new record. The platform always wraps in `{ event, entity, record, old?, occurred_at }`."
+  ),
+  headers: external_exports.record(external_exports.string(), external_exports.string()).optional().describe(
+    "Extra HTTP headers (e.g. authentication tokens). Use `getSecret(...)` semantics: header values starting with `$secret:` are resolved at fire time."
+  )
+};
+function webhookAdd(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const file2 = readJsonOrDefault(
+    paths.webhooks,
+    { subscriptions: [] }
+  );
+  if (file2.subscriptions.some((s) => s.code === args.code)) {
+    throw new Error(`Webhook subscription '${args.code}' already exists.`);
+  }
+  const entry = {
+    code: args.code,
+    entity: args.entity,
+    event: args.event,
+    endpointUrl: args.endpointUrl
+  };
+  if (args.description) entry.description = args.description;
+  if (args.condition) entry.condition = args.condition;
+  if (args.payload) entry.payload = args.payload;
+  if (args.headers) entry.headers = args.headers;
+  file2.subscriptions.push(entry);
+  return makeResult(
+    `Added webhook subscription '${args.code}' on ${args.entity}.${args.event} \u2192 POST ${args.endpointUrl}.`,
+    {
+      [rel(paths.root, paths.webhooks)]: jsonText(file2),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+
 // src/resources/index.ts
-var fs5 = __toESM(require("fs"));
-var path7 = __toESM(require("path"));
-var RESOURCES_DIR = path7.resolve(__dirname, "..", "resources");
+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");
 function schema(name, label, description) {
   return {
     uri: `dforge://schema/${name}`,
@@ -31945,6 +34170,33 @@ function schema(name, label, description) {
     read: () => readVendored(`schemas/${name}.schema.json`)
   };
 }
+function reference(name, description) {
+  return {
+    uri: `dforge://reference/${name}`,
+    name: `Reference: ${name}`,
+    description,
+    mimeType: "text/markdown",
+    read: () => readSkill(`references/${name}.md`)
+  };
+}
+function example(relPath, description) {
+  return {
+    uri: `dforge://example/${relPath}`,
+    name: `Example: ${relPath}`,
+    description,
+    mimeType: relPath.endsWith(".json") ? "application/json" : "text/plain",
+    read: () => readSkill(`examples/simple-todo/${relPath}`)
+  };
+}
+function matrixExample(relPath, description) {
+  return {
+    uri: `dforge://example/matrix-budget/${relPath}`,
+    name: `Example: matrix-budget/${relPath}`,
+    description,
+    mimeType: relPath.endsWith(".json") ? "application/json" : "text/plain",
+    read: () => readSkill(`examples/matrix-budget/${relPath}`)
+  };
+}
 var resources = [
   schema(
     "manifest",
@@ -31994,7 +34246,17 @@ var resources = [
   schema(
     "webhooks",
     "Webhooks JSON schema",
-    "JSON Schema for ui/webhooks.json \u2014 outbound webhook definitions."
+    "JSON Schema for logic/webhooks.json \u2014 outbound webhook subscriptions: entity + event filter \u2192 POST to endpointUrl with selected fields."
+  ),
+  schema(
+    "triggers",
+    "Triggers JSON schema",
+    "JSON Schema for logic/triggers.json \u2014 intra-tenant DB-event \u2192 action invocation: entity + event + optional condition formula \u2192 fires an action (sync or async)."
+  ),
+  schema(
+    "print-templates",
+    "Print templates JSON schema",
+    "JSON Schema for ui/print_templates.json \u2014 Liquid HTML print templates and reusable snippets, bound to entities for the print menu."
   ),
   schema(
     "settings",
@@ -32012,15 +34274,77 @@ var resources = [
     description: "Markdown summary of module structure, field types, view conventions, and security model. Reference this before creating non-trivial modules.",
     mimeType: "text/markdown",
     read: () => readVendored("docs/conventions.md")
-  }
+  },
+  {
+    uri: "dforge://docs/dsl",
+    name: "dForge action DSL reference",
+    description: "Full reference for the dForge action DSL (logic/actions/*.dsl files): block structure (params/canExecute/onBeforeStart/execute), execution modes (single/each/batch), field-access syntax ([field], params[name], [ref].[field], records.*), all 30 built-in host functions (query/insert/error/exit/now/sendEmail/...), supported JS subset (ES5 via Esprima/Jint), common patterns, and pitfalls. **Load this before authoring any DSL action (Phase 2 of the wizard).**",
+    mimeType: "text/markdown",
+    read: () => readVendored("docs/dsl-reference.md")
+  },
+  // ── Per-element authoring references (skills/.../references/*.md) ──────
+  reference("field-types", "Field types \u2014 fieldTypeCd (UI control) vs dbDatatype (SQL type), and the correct value for each. Load before adding any field."),
+  reference("flags", "Column flags \u2014 only V/I/E/M/H; valid combos (VEM/VE/V/EM/I) and why 'VEMHI' is invalid. Load before setting any flags."),
+  reference("column-types", "The FK + Reference two-column pattern (the #1 source of broken modules) and Set columns. Load before any relation."),
+  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."),
+  reference("menus", "Menus: leaf items use dataViewCode; section nodes omit itemType; icons are Bootstrap names WITHOUT the bi- prefix."),
+  reference("action-dsl", "Action DSL grammar + 'Registering the action' (ui/actions.json: entityCode/executionMode/script/isAsync/bi- icon)."),
+  reference("filters", "Canonical filter shape for views, folders, and reports."),
+  reference("security", "Security roles + rights matrix: 'rights' key, SIUDC for entities, E for actions/reports/folders."),
+  reference("reports", "Reports: layout panels + datasets (Query or Stored Procedure)."),
+  reference("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("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."),
+  reference("schema-import", "Importing entities from DBML/SQL (use dforge_dbml_import for the parse)."),
+  reference("excel-import", "Importing a data model from a spreadsheet (.xlsx/.csv): decode the binary xlsx with the bundled stdlib Python extractor (dforge://script/xlsx-to-model), build a table-spec, call dforge_module_import. Load before handling any spreadsheet upload."),
+  {
+    uri: "dforge://script/xlsx-to-model",
+    name: "xlsx \u2192 model extractor (Python, stdlib)",
+    description: "Pure standard-library Python 3 script (no pip needed) that extracts each sheet's headers + sample rows from an .xlsx into JSON. Write it to a temp file and run `python3 <tmp>.py <file.xlsx>`. See dforge://reference/excel-import for the full flow.",
+    mimeType: "text/x-python",
+    read: () => readSkill("scripts/xlsx_to_model.py")
+  },
+  reference("data-migration", "Migrating data from a legacy database."),
+  reference("manifest", "manifest.json shape: moduleId UUID, semver, entities map, locale-keyed translations, security block."),
+  reference("validation-checklist", "Final pre-pack self-review checklist covering every file type."),
+  // ── Canonical example module (skills/.../examples/simple-todo) ────────
+  example("manifest.json", "Canonical manifest.json."),
+  example("entities/todo_item.json", "Canonical entity: traits, flags (VEM/VE), dropdown options as {value,label}, FK+Reference pattern (otherKey = '{entity}_id'), references block, toString uses a business field."),
+  example("entities/todo_list.json", "Canonical parent/lookup entity."),
+  example("ui/actions.json", "Canonical ui/actions.json: label/description/icon('bi-...')/entityCode/executionMode/script(bare)/isAsync."),
+  example("ui/data_views.json", "Canonical data views: dataSources array + order string-array."),
+  example("ui/menus.json", "Canonical menus: dataViewCode leaves, bi-less icons."),
+  example("security/roles.json", "Canonical roles: rights with SIUDC / E."),
+  example("seed-data/01-lists.json", "Canonical seed data: PK key is '{entity}_id' (not 'id'), parent-before-child via numeric prefix."),
+  example("logic/actions/mark_done.dsl", "Canonical action DSL body (params/canExecute/execute)."),
+  // ── Matrix view example module (skills/.../examples/matrix-budget) ────
+  matrixExample("ui/data_views.json", "Canonical MATRIX data view: viewType 'matrix' + viewConfig with a dataset rowAxis (categories), a dropdown colAxis ('budget_line.quarter'), and an editable cell mapping rowKey/colKey/fields onto the budget_line entity."),
+  matrixExample("entities/budget_line.json", "Matrix CELL entity: one record per (category, quarter) \u2014 FK+Reference to the row-axis entity plus the dropdown column that is the col axis, with the editable 'amount' value column."),
+  matrixExample("entities/budget_category.json", "Matrix row-axis (dataset) entity."),
+  matrixExample("manifest.json", "Matrix example manifest (entities + dataViews + roles + seed)."),
+  matrixExample("security/roles.json", "Matrix example roles: S on the axis entity, SIUD on the editable cell entity."),
+  matrixExample("seed-data/01-categories.json", "Matrix example seed: row-axis category records.")
 ];
 function readVendored(rel2) {
-  const p = path7.join(RESOURCES_DIR, rel2);
-  if (!fs5.existsSync(p)) {
+  const p = path11.join(RESOURCES_DIR, rel2);
+  if (!fs9.existsSync(p)) {
     return `// Resource missing at build time: ${rel2}
 // Run scripts/vendor-resources.sh in dforge-mcp to refresh from dForge-core.`;
   }
-  return fs5.readFileSync(p, "utf8");
+  return fs9.readFileSync(p, "utf8");
+}
+function readSkill(rel2) {
+  const p = path11.join(SKILL_DIR, rel2);
+  if (!fs9.existsSync(p)) {
+    return `// Skill resource missing: ${rel2}
+// Expected under skills/dforge-mcp-author/ \u2014 check the package 'files' list.`;
+  }
+  return fs9.readFileSync(p, "utf8");
 }
 
 // src/server.ts
@@ -32045,9 +34369,27 @@ function envelope(fn) {
     }
   };
 }
+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) => {
+    try {
+      const result = planModule(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (e) {
+      return {
+        content: [{ type: "text", text: `Error: ${e.message}` }],
+        isError: true
+      };
+    }
+  }
+);
 server.tool(
   "dforge_module_create",
-  "PHASE 1: Build the file map for a brand-new dForge module. Returns { files: { '<relPath>': '<contents>' } } \u2014 the client decides whether to write them. Always preview the file map with the user before writing.",
+  "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) => {
     const files = createModuleFiles(args);
@@ -32074,9 +34416,15 @@ server.tool(
   moduleInspectSchema,
   envelope(moduleInspect)
 );
+server.tool(
+  "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)
+);
 server.tool(
   "dforge_module_pack",
-  "Pack a module directory into a .dforge tarball. Requires the dforge-cli native binary on PATH (or set DFORGE_CLI_BINARY).",
+  "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);
@@ -32085,7 +34433,7 @@ server.tool(
 );
 server.tool(
   "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.",
+  "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,
   async (args) => {
     const result = installModule(args);
@@ -32119,6 +34467,24 @@ server.tool(
     };
   }
 );
+server.tool(
+  "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,
+  envelope(moduleImport)
+);
+server.tool(
+  "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,
+  envelope(entityRename)
+);
+server.tool(
+  "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,
+  envelope(entityDelete)
+);
 server.tool(
   "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.",
@@ -32133,16 +34499,40 @@ server.tool(
 );
 server.tool(
   "dforge_entity_field_remove",
-  "PHASE 2 / backtrack: Remove a field from an entity. WARNING: may break dependent views, role rights, formulas, action DSL, seed data \u2014 re-run dforge_module_inspect after.",
+  "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,
   envelope(entityFieldRemove)
 );
+server.tool(
+  "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,
+  envelope(entityFieldRename)
+);
 server.tool(
   "dforge_action_add",
-  "PHASE 3: Add a DSL action targeting an entity. Writes logic/actions/<code>.dsl plus an entry in ui/actions.json. Phase 3 is optional \u2014 only call when business logic genuinely requires custom actions.",
+  "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,
   envelope(actionAdd)
 );
+server.tool(
+  "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,
+  envelope(triggerAdd)
+);
+server.tool(
+  "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,
+  envelope(jobAdd)
+);
+server.tool(
+  "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,
+  envelope(webhookAdd)
+);
 server.tool(
   "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.",
@@ -32193,15 +34583,9 @@ server.tool(
 );
 server.tool(
   "dforge_dbml_import",
-  "Generate a module from DBML schema text. Currently a stub \u2014 underlying dforge-cli command is not implemented.",
+  "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,
-  async (args) => {
-    const result = dbmlImport(args);
-    return {
-      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-      isError: true
-    };
-  }
+  envelope(dbmlImport)
 );
 for (const res of resources) {
   server.resource(res.name, res.uri, async (uri) => ({