@prorigo/protrak-forge 0.3.3 → 0.3.5

package/bin/protrak-forge.js

@@ -3223,8 +3223,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path14) {
-      let input = path14;
+    function removeDotSegments(path17) {
+      let input = path17;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3423,8 +3423,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path14, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path14 && path14 !== "/" ? path14 : void 0;
+        const [path17, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path17 && path17 !== "/" ? path17 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -6786,12 +6786,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs18, exportName) {
+    function addFormats(ajv, list, fs21, exportName) {
       var _a2;
       var _b;
       (_a2 = (_b = ajv.opts.code).formats) !== null && _a2 !== void 0 ? _a2 : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs18[f]);
+        ajv.addFormat(f, fs21[f]);
     }
     module2.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -7158,8 +7158,8 @@ function getErrorMap() {
 
 // node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path14, errorMaps, issueData } = params;
-  const fullPath = [...path14, ...issueData.path || []];
+  const { data, path: path17, errorMaps, issueData } = params;
+  const fullPath = [...path17, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -7274,11 +7274,11 @@ var errorUtil;
 
 // node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path14, key) {
+  constructor(parent, value, path17, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path14;
+    this._path = path17;
     this._key = key;
   }
   get path() {
@@ -10924,10 +10924,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path14) {
-  if (!path14)
+function getElementAtPath(obj, path17) {
+  if (!path17)
     return obj;
-  return path14.reduce((acc, key) => acc?.[key], obj);
+  return path17.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -11310,11 +11310,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path14, issues) {
+function prefixIssues(path17, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path14);
+    iss.path.unshift(path17);
     return iss;
   });
 }
@@ -20869,7 +20869,8 @@ function makeWorkspace(root, namespace) {
     formsDir: path.join(root, "Forms"),
     typeWidgetsDir: path.join(root, "TypeWidgets"),
     layoutTemplatesDir: path.join(root, "LayoutTemplates"),
-    homeLayoutsDir: path.join(root, "HomeLayouts")
+    homeLayoutsDir: path.join(root, "HomeLayouts"),
+    notificationTemplatesDir: path.join(root, "NotificationTemplates")
   };
 }
 function extractNamespace(csprojPath) {
@@ -21430,9 +21431,9 @@ var SearchableMap = class _SearchableMap {
     if (!prefix.startsWith(this._prefix)) {
       throw new Error("Mismatched prefix");
     }
-    const [node, path14] = trackDown(this._tree, prefix.slice(this._prefix.length));
+    const [node, path17] = trackDown(this._tree, prefix.slice(this._prefix.length));
     if (node === void 0) {
-      const [parentNode, key] = last(path14);
+      const [parentNode, key] = last(path17);
       for (const k of parentNode.keys()) {
         if (k !== LEAF && k.startsWith(key)) {
           const node2 = /* @__PURE__ */ new Map();
@@ -21652,18 +21653,18 @@ var SearchableMap = class _SearchableMap {
     return _SearchableMap.from(Object.entries(object3));
   }
 };
-var trackDown = (tree, key, path14 = []) => {
+var trackDown = (tree, key, path17 = []) => {
   if (key.length === 0 || tree == null) {
-    return [tree, path14];
+    return [tree, path17];
   }
   for (const k of tree.keys()) {
     if (k !== LEAF && key.startsWith(k)) {
-      path14.push([tree, k]);
-      return trackDown(tree.get(k), key.slice(k.length), path14);
+      path17.push([tree, k]);
+      return trackDown(tree.get(k), key.slice(k.length), path17);
     }
   }
-  path14.push([tree, key]);
-  return trackDown(void 0, "", path14);
+  path17.push([tree, key]);
+  return trackDown(void 0, "", path17);
 };
 var lookup = (tree, key) => {
   if (key.length === 0 || tree == null) {
@@ -21705,38 +21706,38 @@ var createPath = (node, key) => {
   return node;
 };
 var remove = (tree, key) => {
-  const [node, path14] = trackDown(tree, key);
+  const [node, path17] = trackDown(tree, key);
   if (node === void 0) {
     return;
   }
   node.delete(LEAF);
   if (node.size === 0) {
-    cleanup(path14);
+    cleanup(path17);
   } else if (node.size === 1) {
     const [key2, value] = node.entries().next().value;
-    merge2(path14, key2, value);
+    merge2(path17, key2, value);
   }
 };
-var cleanup = (path14) => {
-  if (path14.length === 0) {
+var cleanup = (path17) => {
+  if (path17.length === 0) {
     return;
   }
-  const [node, key] = last(path14);
+  const [node, key] = last(path17);
   node.delete(key);
   if (node.size === 0) {
-    cleanup(path14.slice(0, -1));
+    cleanup(path17.slice(0, -1));
   } else if (node.size === 1) {
     const [key2, value] = node.entries().next().value;
     if (key2 !== LEAF) {
-      merge2(path14.slice(0, -1), key2, value);
+      merge2(path17.slice(0, -1), key2, value);
     }
   }
 };
-var merge2 = (path14, key, value) => {
-  if (path14.length === 0) {
+var merge2 = (path17, key, value) => {
+  if (path17.length === 0) {
     return;
   }
-  const [node, nodeKey] = last(path14);
+  const [node, nodeKey] = last(path17);
   node.set(nodeKey + key, value);
   node.delete(nodeKey);
 };
@@ -23318,7 +23319,7 @@ function getClient() {
 }
 
 // src/version.ts
-var PACKAGE_VERSION = "0.3.3";
+var PACKAGE_VERSION = "0.3.5";
 
 // src/tools/_schema-write-utils.ts
 var fs4 = __toESM(require("fs"));
@@ -23364,6 +23365,12 @@ function humanise(name) {
   if (!name) return "";
   return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").trim();
 }
+function readJsonFile(filePath) {
+  return JSON.parse(fs4.readFileSync(filePath, "utf8"));
+}
+function writeJsonFilePath(filePath, data) {
+  fs4.writeFileSync(filePath, JSON.stringify(data, null, JSON_INDENT), "utf8");
+}
 function writeJsonFile(dir, fileName, data, overwrite) {
   if (!fs4.existsSync(dir)) {
     fs4.mkdirSync(dir, { recursive: true });
@@ -23395,7 +23402,7 @@ __export(get_program_context_exports, {
   TOOL_DEF: () => TOOL_DEF,
   handle: () => handle
 });
-var fs7 = __toESM(require("fs"));
+var fs8 = __toESM(require("fs"));
 
 // src/interface-contracts.ts
 var INTERFACE_CONTRACTS = {
@@ -23808,11 +23815,67 @@ function getOrCreateIndex(workspace) {
   return idx;
 }
 
+// src/tools/_program-utils.ts
+var fs7 = __toESM(require("fs"));
+var path6 = __toESM(require("path"));
+function readProgramByName(provider, programName) {
+  const programsDir = provider.ws.programsDir;
+  const csPath = path6.join(programsDir, `${programName}.cs`);
+  if (!fs7.existsSync(csPath)) {
+    const available = listAvailablePrograms(programsDir);
+    return {
+      kind: "not_found",
+      message: `Program '${programName}' not found at ${csPath}`,
+      available_programs: available
+    };
+  }
+  const parsed = parseFile(csPath);
+  if (!parsed) {
+    const source = fs7.readFileSync(csPath, "utf8");
+    return {
+      kind: "parse_failed",
+      data: {
+        file_path: csPath,
+        source,
+        program_type: "Unknown",
+        services_used: [],
+        patterns_detected: [],
+        class_name: ""
+      }
+    };
+  }
+  const jsonPath = path6.join(programsDir, `${programName}.json`);
+  let metadata = {};
+  if (fs7.existsSync(jsonPath)) {
+    try {
+      metadata = JSON.parse(fs7.readFileSync(jsonPath, "utf8"));
+    } catch {
+    }
+  }
+  return {
+    kind: "success",
+    data: {
+      file_path: csPath,
+      source: parsed.fullSource,
+      program_type: String(metadata["programType"] ?? parsed.programType ?? ""),
+      services_used: parsed.servicesUsed,
+      patterns_detected: parsed.patterns,
+      class_name: parsed.className
+    }
+  };
+}
+function listAvailablePrograms(programsDir) {
+  if (!fs7.existsSync(programsDir) || !fs7.statSync(programsDir).isDirectory()) {
+    return [];
+  }
+  return fs7.readdirSync(programsDir).filter((f) => f.endsWith(".cs")).map((f) => path6.basename(f, ".cs")).sort();
+}
+
 // src/tools/get-program-context.ts
 var DETAIL_MODES = ["full", "summary", "schema_only", "patterns_only"];
 var TOOL_DEF = {
   name: "get_protrak_program_context",
-  description: "REQUIRED: Call this BEFORE writing any Protrak C# program. Returns everything needed in one call: type schema (attributes, lifecycle, relations), the C# interface to implement, relevant coding patterns with examples, similar existing programs from the workspace, and query definitions available for IQueryBuilderService. Use detail=summary on follow-up calls when you only need attribute/state names (skips heavy patterns/similar-programs payload). This is the primary tool for Protrak program generation.",
+  description: "REQUIRED: Call this BEFORE writing OR refactoring any Protrak C# program. NEW PROGRAM: omit program_name. Returns type schema, C# interface, patterns, similar programs, and query definitions in one call. REFACTOR: pass program_name to load the existing program's source, services, and detected patterns alongside the same context \u2014 no need to chain read_protrak_program separately. Use detail=summary on follow-up calls when you only need attribute/state names. This is the primary tool for Protrak program work.",
   inputSchema: {
     type: "object",
     properties: {
@@ -23824,6 +23887,10 @@ var TOOL_DEF = {
         type: "string",
         description: "The program type to implement: PreCreate, PostCreate, PreUpdate, PostUpdate, PreDelete, PostDelete, PostConnect, PromoteAction, PromoteActionCommand, Scheduler, Common, Report"
       },
+      program_name: {
+        type: "string",
+        description: "OMIT for new-program creation. Provide an existing program name (e.g. 'CalculateNextInvoiceDate') to switch to refactor mode \u2014 response will include existing_source, existing_services_used, existing_patterns_detected, existing_class_name, existing_file_path, and refactor_mode:true. The validation_step will still reference validate_protrak_program with the program_type you passed."
+      },
       description: {
         type: "string",
         description: "What the program should do (e.g. 'validate that Title is not empty', 'send email when status changes'). Optional \u2014 patterns are still searched without it."
@@ -23848,13 +23915,23 @@ function buildSummarySchema(schema) {
     relation_names: schema.relations.map((r) => r.relation_type_name)
   };
 }
-function buildValidationStep(programType, namespace, typeName) {
+function buildValidationStep({
+  programType,
+  namespace,
+  typeName,
+  refactorMode,
+  existingProgramName
+}) {
+  if (refactorMode) {
+    return `After editing this ${programType || "program"}, call validate_protrak_program(code='<your edited source>', program_type='${programType}') to check for Protrak-specific gotchas (deadlocks, async void, DI shape, interface compliance). Then write the edited source back to Programs/${existingProgramName}.cs. Use namespace ${namespace}.`;
+  }
   const fileName = typeName && programType ? `${typeName}${programType}.cs` : "<ProgramName>.cs";
-  return `After writing this ${programType || "program"} program, call validate_protrak_program(program_path='Programs/${fileName}') to check for errors. Use namespace ${namespace}.`;
+  return `After writing this ${programType || "program"}, call validate_protrak_program(code='<your source>', program_type='${programType}') to check for errors. Once it passes, call generate_protrak_program(program_name='${typeName}${programType}', program_type='${programType}', source='<your source>') to write Programs/${fileName} and its companion JSON. Use namespace ${namespace}.`;
 }
 function handle(provider, args) {
   const typeName = args["type_name"] ?? "";
   const programType = args["program_type"] ?? "";
+  const programName = args["program_name"] ?? "";
   const description = args["description"] ?? "";
   const detailRaw = args["detail"] ?? "full";
   if (!DETAIL_MODES.includes(detailRaw)) {
@@ -23864,6 +23941,33 @@ function handle(provider, args) {
   }
   const detail = detailRaw;
   const result = { detail };
+  let refactorMode = false;
+  const warnings = [];
+  if (programName) {
+    const existing = readProgramByName(provider, programName);
+    if (existing.kind === "not_found") {
+      return errorResponse(existing.message, {
+        available_programs: existing.available_programs
+      });
+    }
+    refactorMode = true;
+    result["refactor_mode"] = true;
+    result["existing_file_path"] = existing.data.file_path;
+    result["existing_source"] = existing.data.source;
+    result["existing_class_name"] = existing.data.class_name;
+    result["existing_services_used"] = existing.data.services_used;
+    result["existing_patterns_detected"] = existing.data.patterns_detected;
+    if (existing.kind === "success" && existing.data.program_type && programType && existing.data.program_type !== programType) {
+      warnings.push(
+        `program_type mismatch \u2014 existing program implements '${existing.data.program_type}' but you passed '${programType}'. Refactor proceeds with the program_type you passed; verify the interface in existing_source matches before editing.`
+      );
+    }
+    if (existing.kind === "parse_failed") {
+      warnings.push(
+        `Could not parse existing source for '${programName}'. existing_source is the raw file contents; services_used and patterns_detected are empty.`
+      );
+    }
+  }
   const schema = provider.getTypeSchema(typeName);
   const wantsSchema = detail === "full" || detail === "summary" || detail === "schema_only";
   const wantsInterface = detail === "full" || detail === "summary" || detail === "schema_only";
@@ -23906,7 +24010,7 @@ function handle(provider, args) {
   }
   if (wantsSimilar) {
     const programsDir = provider.ws.programsDir;
-    if (fs7.existsSync(programsDir) && fs7.statSync(programsDir).isDirectory()) {
+    if (fs8.existsSync(programsDir) && fs8.statSync(programsDir).isDirectory()) {
       try {
         const index = getOrCreateIndex(provider.ws);
         const similar = index.search(description, 3);
@@ -23926,7 +24030,7 @@ function handle(provider, args) {
   }
   if (wantsQueries) {
     const qdDir = provider.ws.queryDefinitionsDir;
-    if (fs7.existsSync(qdDir) && fs7.statSync(qdDir).isDirectory()) {
+    if (fs8.existsSync(qdDir) && fs8.statSync(qdDir).isDirectory()) {
       const queries = provider.getQueryDefinitionsForType(typeName);
       if (detail === "summary") {
         result["query_definition_names"] = queries.map((q) => q.name);
@@ -23953,7 +24057,16 @@ function handle(provider, args) {
       "Return raw C# code only \u2014 no markdown, no code fences."
     ];
   }
-  result["validation_step"] = buildValidationStep(programType, provider.ws.namespace, typeName);
+  result["validation_step"] = buildValidationStep({
+    programType,
+    namespace: provider.ws.namespace,
+    typeName,
+    refactorMode,
+    existingProgramName: programName
+  });
+  if (warnings.length > 0) {
+    result["warnings"] = warnings;
+  }
   return JSON.stringify(result, null, 2);
 }
 
@@ -23965,8 +24078,8 @@ __export(get_layout_context_exports, {
 });
 
 // src/layout-provider.ts
-var fs8 = __toESM(require("fs"));
-var path6 = __toESM(require("path"));
+var fs9 = __toESM(require("fs"));
+var path7 = __toESM(require("path"));
 var LocalLayoutProvider = class {
   ws;
   _forms = null;
@@ -23977,17 +24090,19 @@ var LocalLayoutProvider = class {
   _layoutTemplateMeta = null;
   _homeLayouts = null;
   _homeLayoutMeta = null;
+  _notificationTemplates = null;
+  _notificationTemplateMeta = null;
   constructor(ws) {
     this.ws = ws;
   }
   loadLayoutDir(dir, map2, meta3, keyField, buildMeta, logLabel) {
-    if (!fs8.existsSync(dir) || !fs8.statSync(dir).isDirectory()) return;
-    for (const entry of fs8.readdirSync(dir).sort()) {
+    if (!fs9.existsSync(dir) || !fs9.statSync(dir).isDirectory()) return;
+    for (const entry of fs9.readdirSync(dir).sort()) {
       if (!entry.endsWith(".json")) continue;
-      const fp = path6.join(dir, entry);
+      const fp = path7.join(dir, entry);
       try {
-        const data = JSON.parse(fs8.readFileSync(fp, "utf8"));
-        const name = data[keyField] ?? path6.basename(entry, ".json");
+        const data = JSON.parse(fs9.readFileSync(fp, "utf8"));
+        const name = data[keyField] ?? path7.basename(entry, ".json");
         map2.set(name, data);
         meta3.push(buildMeta(data, name, fp));
       } catch (e) {
@@ -24047,6 +24162,34 @@ var LocalLayoutProvider = class {
       "home layout"
     );
   }
+  ensureNotificationTemplates() {
+    if (this._notificationTemplates !== null) return;
+    this._notificationTemplates = /* @__PURE__ */ new Map();
+    this._notificationTemplateMeta = [];
+    const dir = this.ws.notificationTemplatesDir;
+    if (!fs9.existsSync(dir) || !fs9.statSync(dir).isDirectory()) return;
+    for (const entry of fs9.readdirSync(dir).sort()) {
+      if (!entry.endsWith(".json")) continue;
+      const fp = path7.join(dir, entry);
+      try {
+        const data = JSON.parse(fs9.readFileSync(fp, "utf8"));
+        const name = path7.basename(entry, ".json");
+        const htmlPath = path7.join(dir, `${name}.html`);
+        this._notificationTemplates.set(name, data);
+        this._notificationTemplateMeta.push({
+          name,
+          title: String(data["title"] ?? name),
+          target: String(data["target"] ?? ""),
+          templateState: String(data["templateState"] ?? ""),
+          hasEmailBody: fs9.existsSync(htmlPath),
+          hasMessageText: Boolean(data["messageText"]),
+          filePath: fp
+        });
+      } catch (e) {
+        log("warn", `Failed to load notification template ${fp}: ${e}`);
+      }
+    }
+  }
   formsForType(typeName, mode) {
     this.ensureForms();
     return this._formMeta.filter(
@@ -24069,6 +24212,12 @@ var LocalLayoutProvider = class {
     this.ensureHomeLayouts();
     return this._homeLayoutMeta;
   }
+  notificationTemplatesForType(typeName) {
+    this.ensureNotificationTemplates();
+    if (!typeName) return this._notificationTemplateMeta;
+    const lower = typeName.toLowerCase();
+    return this._notificationTemplateMeta.filter((t) => t.title.toLowerCase().includes(lower));
+  }
   getLayoutJson(layoutType, name) {
     switch (layoutType) {
       case "form":
@@ -24119,6 +24268,10 @@ var LocalLayoutProvider = class {
         this._homeLayouts = null;
         this._homeLayoutMeta = null;
         break;
+      case "notificationTemplate":
+        this._notificationTemplates = null;
+        this._notificationTemplateMeta = null;
+        break;
     }
   }
 };
@@ -25232,8 +25385,8 @@ __export(validate_program_exports, {
   TOOL_DEF: () => TOOL_DEF8,
   handle: () => handle8
 });
-var fs9 = __toESM(require("fs"));
-var path7 = __toESM(require("path"));
+var fs10 = __toESM(require("fs"));
+var path8 = __toESM(require("path"));
 var os = __toESM(require("os"));
 var crypto = __toESM(require("crypto"));
 var import_child_process = require("child_process");
@@ -25377,7 +25530,7 @@ function runStaticChecks(code, programType) {
 // src/tools/validate-program.ts
 var TOOL_DEF8 = {
   name: "validate_protrak_program",
-  description: "ALWAYS call this after writing a Protrak C# program. Validates the code with static analysis (interface compliance, async patterns, service declarations, null-check patterns). Optionally runs 'dotnet build' for full compilation check.",
+  description: "Static analysis for Protrak C# programs. Catches Protrak-specific gotchas that look fine to a generic reader but break in production: (1) `.Result` / `.Wait()` on tasks \u2014 deadlocks under Protrak's async context. (2) `async void` methods \u2014 exceptions escape silently. (3) Services declared as private/readonly fields \u2014 Protrak DI requires PUBLIC PROPERTIES. (4) Missing interface implementation \u2014 e.g. PreCreate must implement IPreCreateTriggerProgramAsync<T>. (5) `*Async()` calls without `await` or `return` \u2014 silent fire-and-forget. (6) Service usage where the service isn't declared as a public property. (7) Missing namespace declaration. ALWAYS call this after writing OR editing a Protrak program \u2014 these failures are not visible to a syntactic read of the file. Optionally runs 'dotnet build' for full compilation check.",
   inputSchema: {
     type: "object",
     properties: {
@@ -25399,18 +25552,18 @@ var TOOL_DEF8 = {
   }
 };
 function runDotnetBuild(workspaceRoot, code) {
-  const csprojFiles = fs9.readdirSync(workspaceRoot).filter((e) => e.endsWith(".csproj"));
+  const csprojFiles = fs10.readdirSync(workspaceRoot).filter((e) => e.endsWith(".csproj"));
   if (csprojFiles.length === 0) {
     return { success: false, errors: ["No .csproj file found in workspace"] };
   }
-  const programsDir = path7.join(workspaceRoot, "Programs");
+  const programsDir = path8.join(workspaceRoot, "Programs");
   const tmpName = `_protrakgen_validate_${crypto.randomBytes(4).toString("hex")}.cs`;
-  const tmpPath = fs9.existsSync(programsDir) && fs9.statSync(programsDir).isDirectory() ? path7.join(programsDir, tmpName) : path7.join(os.tmpdir(), tmpName);
+  const tmpPath = fs10.existsSync(programsDir) && fs10.statSync(programsDir).isDirectory() ? path8.join(programsDir, tmpName) : path8.join(os.tmpdir(), tmpName);
   try {
-    fs9.writeFileSync(tmpPath, code, "utf8");
+    fs10.writeFileSync(tmpPath, code, "utf8");
     const result = (0, import_child_process.spawnSync)(
       "dotnet",
-      ["build", path7.join(workspaceRoot, csprojFiles[0]), "--no-restore", "-v", "quiet"],
+      ["build", path8.join(workspaceRoot, csprojFiles[0]), "--no-restore", "-v", "quiet"],
       { cwd: workspaceRoot, encoding: "utf8", timeout: 3e4 }
     );
     if (result.error) {
@@ -25419,7 +25572,7 @@ function runDotnetBuild(workspaceRoot, code) {
       }
       return { success: false, errors: [result.error.message] };
     }
-    const tmpStem = path7.basename(tmpPath, ".cs");
+    const tmpStem = path8.basename(tmpPath, ".cs");
     const allOutput = [result.stdout ?? "", result.stderr ?? ""].join("\n");
     const errors = allOutput.split("\n").filter((line) => (line.includes(": error ") || line.includes(": warning ")) && line.includes(tmpStem)).map((line) => line.trim());
     return { success: result.status === 0, errors };
@@ -25427,7 +25580,7 @@ function runDotnetBuild(workspaceRoot, code) {
     return { success: false, errors: [String(e)] };
   } finally {
     try {
-      fs9.unlinkSync(tmpPath);
+      fs10.unlinkSync(tmpPath);
     } catch {
     }
   }
@@ -25452,7 +25605,7 @@ function handle8(provider, args) {
     `Fix the listed errors. For interface/coding-rule violations, re-read the contract via get_protrak_program_context(type_name='<TypeName>', program_type='${programType}', detail='schema_only') and adjust the program.`,
     "Re-run validate_protrak_program after fixing."
   ] : [
-    "Validation clean \u2014 write the file to Programs/<TypeName><ProgramType>.cs and proceed."
+    `Validation clean. For a NEW program: call generate_protrak_program(program_name='<TypeName><ProgramType>', program_type='${programType}', source='<your code>') to write Programs/<name>.cs and its companion JSON. For a REFACTOR: write the edited source back to the existing Programs/<name>.cs file.`
   ];
   return JSON.stringify(response, null, 2);
 }
@@ -25463,7 +25616,7 @@ __export(search_protrak_knowledge_exports, {
   TOOL_DEF: () => TOOL_DEF9,
   handle: () => handle9
 });
-var fs10 = __toESM(require("fs"));
+var fs11 = __toESM(require("fs"));
 var SCOPES = ["patterns", "api", "programs", "all"];
 var TOOL_DEF9 = {
   name: "search_protrak_knowledge",
@@ -25532,7 +25685,7 @@ function searchApi(query, programType, services, topK) {
 }
 function searchPrograms(provider, query, topK) {
   const programsDir = provider.ws.programsDir;
-  if (!fs10.existsSync(programsDir) || !fs10.statSync(programsDir).isDirectory()) {
+  if (!fs11.existsSync(programsDir) || !fs11.statSync(programsDir).isDirectory()) {
     return {
       results: [],
       note: `No Programs directory found at '${programsDir}'.`
@@ -25847,7 +26000,7 @@ __export(list_query_definitions_exports, {
   TOOL_DEF: () => TOOL_DEF14,
   handle: () => handle14
 });
-var fs11 = __toESM(require("fs"));
+var fs12 = __toESM(require("fs"));
 var TOOL_DEF14 = {
   name: "list_protrak_queries",
   description: "List Protrak query definitions available in the workspace. Call this when writing a program that uses IQueryBuilderService to see what query definitions exist and can be passed to GetQueryDefinitionResultByNameAsync. Filter by type_name to get only queries for the relevant entity type.",
@@ -25864,7 +26017,7 @@ var TOOL_DEF14 = {
 function handle14(provider, args) {
   const typeName = args["type_name"] || void 0;
   const qdDir = provider.ws.queryDefinitionsDir;
-  if (!fs11.existsSync(qdDir) || !fs11.statSync(qdDir).isDirectory()) {
+  if (!fs12.existsSync(qdDir) || !fs12.statSync(qdDir).isDirectory()) {
     return JSON.stringify({
       query_definitions: [],
       note: `QueryDefinitions directory not found at '${qdDir}'.`
@@ -25913,8 +26066,8 @@ __export(list_protrak_programs_exports, {
   TOOL_DEF: () => TOOL_DEF16,
   handle: () => handle16
 });
-var fs12 = __toESM(require("fs"));
-var path8 = __toESM(require("path"));
+var fs13 = __toESM(require("fs"));
+var path9 = __toESM(require("path"));
 var TOOL_DEF16 = {
   name: "list_protrak_programs",
   description: "List Protrak C# programs in the workspace. Each entry includes the program name, the entity type it targets (when available from JSON metadata), and the program type (PreCreate, PostCreate, etc.). Filter by type_name and/or program_type to narrow. For relevance-ranked search by description use search_protrak_knowledge with scope='programs' instead.",
@@ -25936,7 +26089,7 @@ function handle16(provider, args) {
   const typeFilter = args["type_name"] || void 0;
   const programTypeFilter = args["program_type"] || void 0;
   const programsDir = provider.ws.programsDir;
-  if (!fs12.existsSync(programsDir) || !fs12.statSync(programsDir).isDirectory()) {
+  if (!fs13.existsSync(programsDir) || !fs13.statSync(programsDir).isDirectory()) {
     return JSON.stringify(
       {
         programs: [],
@@ -25948,18 +26101,18 @@ function handle16(provider, args) {
   }
   const entries = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const entry of fs12.readdirSync(programsDir).sort()) {
+  for (const entry of fs13.readdirSync(programsDir).sort()) {
     if (!entry.endsWith(".json") && !entry.endsWith(".cs")) continue;
-    const programName = path8.basename(entry, path8.extname(entry));
+    const programName = path9.basename(entry, path9.extname(entry));
     if (seen.has(programName)) continue;
     seen.add(programName);
-    const csPath = path8.join(programsDir, `${programName}.cs`);
-    const jsonPath = path8.join(programsDir, `${programName}.json`);
+    const csPath = path9.join(programsDir, `${programName}.cs`);
+    const jsonPath = path9.join(programsDir, `${programName}.json`);
     let programType = "";
     let typeName = "";
-    if (fs12.existsSync(jsonPath)) {
+    if (fs13.existsSync(jsonPath)) {
       try {
-        const meta3 = JSON.parse(fs12.readFileSync(jsonPath, "utf8"));
+        const meta3 = JSON.parse(fs13.readFileSync(jsonPath, "utf8"));
         programType = meta3["programType"] ?? "";
         typeName = meta3["typeName"] ?? meta3["entityTypeName"] ?? meta3["entityType"] ?? "";
       } catch {
@@ -25969,8 +26122,8 @@ function handle16(provider, args) {
       program_name: programName,
       program_type: programType,
       type_name: typeName,
-      has_source: fs12.existsSync(csPath),
-      file_path: fs12.existsSync(csPath) ? csPath : jsonPath
+      has_source: fs13.existsSync(csPath),
+      file_path: fs13.existsSync(csPath) ? csPath : jsonPath
     });
   }
   let filtered = entries;
@@ -25992,11 +26145,9 @@ __export(get_program_source_exports, {
   TOOL_DEF: () => TOOL_DEF17,
   handle: () => handle17
 });
-var fs13 = __toESM(require("fs"));
-var path9 = __toESM(require("path"));
 var TOOL_DEF17 = {
   name: "read_protrak_program",
-  description: "Read the source code of a specific Protrak C# program from the workspace. Use this to inspect existing programs for reference, understand implementation patterns, or check what services a program uses.",
+  description: "Read the source code of a specific Protrak C# program from the workspace. Use this to inspect existing programs for reference, understand implementation patterns, or check what services a program uses. For refactoring, prefer get_protrak_program_context with program_name set \u2014 it returns the source AND the schema/interface/patterns context in one call.",
   inputSchema: {
     type: "object",
     properties: {
@@ -26010,32 +26161,15 @@ var TOOL_DEF17 = {
 };
 function handle17(provider, args) {
   const programName = args["program_name"] ?? "";
-  const programsDir = provider.ws.programsDir;
-  const csPath = path9.join(programsDir, `${programName}.cs`);
-  if (!fs13.existsSync(csPath)) {
-    return errorResponse(`Program '${programName}' not found at ${csPath}`);
-  }
-  const parsed = parseFile(csPath);
-  if (!parsed) {
-    const source = fs13.readFileSync(csPath, "utf8");
-    return JSON.stringify({ file_path: csPath, source, program_type: "Unknown", services_used: [] }, null, 2);
+  const result = readProgramByName(provider, programName);
+  if (result.kind === "not_found") {
+    return errorResponse(result.message, { available_programs: result.available_programs });
   }
-  const jsonPath = path9.join(programsDir, `${programName}.json`);
-  let metadata = {};
-  if (fs13.existsSync(jsonPath)) {
-    try {
-      metadata = JSON.parse(fs13.readFileSync(jsonPath, "utf8"));
-    } catch {
-    }
+  if (result.kind === "parse_failed") {
+    const { file_path, source, program_type, services_used } = result.data;
+    return JSON.stringify({ file_path, source, program_type, services_used }, null, JSON_INDENT);
   }
-  return JSON.stringify({
-    file_path: csPath,
-    source: parsed.fullSource,
-    program_type: metadata["programType"] ?? parsed.programType,
-    services_used: parsed.servicesUsed,
-    patterns_detected: parsed.patterns,
-    class_name: parsed.className
-  }, null, 2);
+  return JSON.stringify(result.data, null, JSON_INDENT);
 }
 
 // src/tools/generate-query-definition.ts
@@ -26711,14 +26845,105 @@ function handle21(provider, args) {
   return successResponse({ file_path: result.filePath, template_name: templateName }, { nextSteps });
 }
 
-// src/tools/attach-attribute-to-type.ts
-var attach_attribute_to_type_exports = {};
-__export(attach_attribute_to_type_exports, {
+// src/tools/generate-program.ts
+var generate_program_exports = {};
+__export(generate_program_exports, {
   TOOL_DEF: () => TOOL_DEF22,
   handle: () => handle22
 });
 var fs15 = __toESM(require("fs"));
 var path11 = __toESM(require("path"));
+var TOOL_DEF22 = {
+  name: "generate_protrak_program",
+  description: "Write a Protrak C# program to disk. Creates BOTH Programs/<name>.cs (your source) AND Programs/<name>.json (companion metadata required by Protrak's import flow). The programHashCode is intentionally empty \u2014 Protrak recomputes it on import. ALWAYS call validate_protrak_program on the source FIRST before invoking this tool. Refuses to overwrite existing files unless overwrite:true.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      program_name: {
+        type: "string",
+        description: "PascalCase basename of the file (e.g. 'CalculateNextInvoiceDate'). Used as the file name for both .cs and .json. Must match the class name inside the source."
+      },
+      program_type: {
+        type: "string",
+        description: "Protrak's canonical programType value, written verbatim into the .json file. Common values seen in production workspaces: 'PreCreateTrigger', 'PostCreateTrigger', 'PreUpdateTrigger', 'PostUpdateTrigger', 'PreConnectTrigger', 'PostConnectTrigger', 'PromoteActionCommand', 'Scheduler', 'Common', 'Report', 'Workflow'. Inspect existing programs via list_protrak_programs / read_protrak_program to confirm the value Protrak expects in this workspace."
+      },
+      source: {
+        type: "string",
+        description: "Full C# source code for the program. Should already have passed validate_protrak_program. Written verbatim to Programs/<name>.cs."
+      },
+      overwrite: {
+        type: "boolean",
+        description: "When true, overwrite existing files. Default: false (errors on conflict).",
+        default: false
+      }
+    },
+    required: ["program_name", "program_type", "source"]
+  }
+};
+function buildCompanionJson(programName, programType) {
+  return {
+    programName,
+    programType,
+    programCode: null,
+    programHashCode: "",
+    programStage: "Published"
+  };
+}
+function handle22(provider, args) {
+  const programName = args["program_name"] ?? "";
+  const programType = args["program_type"] ?? "";
+  const source = args["source"] ?? "";
+  const overwrite = args["overwrite"] === true;
+  if (!programName) return errorResponse("program_name is required");
+  if (!isPascalCase(programName)) {
+    return errorResponse(pascalCaseError("program_name", programName));
+  }
+  if (!programType) return errorResponse("program_type is required");
+  if (!source) return errorResponse("source is required");
+  const programsDir = provider.ws.programsDir;
+  if (!fs15.existsSync(programsDir)) {
+    fs15.mkdirSync(programsDir, { recursive: true });
+  }
+  const csPath = path11.join(programsDir, `${programName}.cs`);
+  const jsonPath = path11.join(programsDir, `${programName}.json`);
+  if (!overwrite) {
+    const existing = [];
+    if (fs15.existsSync(csPath)) existing.push(csPath);
+    if (fs15.existsSync(jsonPath)) existing.push(jsonPath);
+    if (existing.length > 0) {
+      return errorResponse(
+        `Refusing to overwrite existing file(s): ${existing.join(", ")}. Pass overwrite:true to replace.`,
+        { existing_paths: existing }
+      );
+    }
+  }
+  fs15.writeFileSync(csPath, source, "utf8");
+  const companion = buildCompanionJson(programName, programType);
+  fs15.writeFileSync(jsonPath, JSON.stringify(companion, null, JSON_INDENT), "utf8");
+  const nextSteps = [
+    `Verify with read_protrak_program(program_name='${programName}').`,
+    "On import, Protrak recomputes programHashCode automatically \u2014 leaving it empty here is intentional."
+  ];
+  return successResponse(
+    {
+      program_name: programName,
+      program_type: programType,
+      cs_path: csPath,
+      json_path: jsonPath,
+      companion_json: companion
+    },
+    { nextSteps }
+  );
+}
+
+// src/tools/attach-attribute-to-type.ts
+var attach_attribute_to_type_exports = {};
+__export(attach_attribute_to_type_exports, {
+  TOOL_DEF: () => TOOL_DEF23,
+  handle: () => handle23
+});
+var fs16 = __toESM(require("fs"));
+var path12 = __toESM(require("path"));
 
 // src/tools/_visibility-utils.ts
 function applyAttributeVisibility(lifecycleData, attributeName, visibleSet, opts) {
@@ -26773,7 +26998,7 @@ function applyAttributeVisibility(lifecycleData, attributeName, visibleSet, opts
 
 // src/tools/attach-attribute-to-type.ts
 var VISIBILITY_ALL = "all";
-var TOOL_DEF22 = {
+var TOOL_DEF23 = {
   name: "attach_protrak_attribute_to_type",
   description: "Bind an existing Attribute to an existing Type without regenerating either file. Appends { name, index, isRequired } to the Type's attributes array with correct auto-indexing. Also ensures lifecycle visibility \u2014 by default the attribute is made visible in ALL lifecycle states (any state with viewableAttributesType=Specific has the attribute added to its viewableAttributes/editableAttributes lists). Pass replace:true to update an existing binding's isRequired flag in place. Use this instead of generate_protrak_type with overwrite:true when adding attributes to an existing Type \u2014 overwrite clobbers unrelated edits.",
   inputSchema: {
@@ -26809,12 +27034,12 @@ var TOOL_DEF22 = {
   }
 };
 function readJson(filePath) {
-  return JSON.parse(fs15.readFileSync(filePath, "utf8"));
+  return JSON.parse(fs16.readFileSync(filePath, "utf8"));
 }
 function writeJson(filePath, data) {
-  fs15.writeFileSync(filePath, JSON.stringify(data, null, JSON_INDENT), "utf8");
+  fs16.writeFileSync(filePath, JSON.stringify(data, null, JSON_INDENT), "utf8");
 }
-function handle22(provider, args) {
+function handle23(provider, args) {
   const typeName = args["type_name"] ?? "";
   const attrName = args["attribute_name"] ?? "";
   const required2 = args["required"] === true;
@@ -26837,8 +27062,8 @@ function handle22(provider, args) {
       "lifecycle_states_visibility must be 'all' or an array of state names."
     );
   }
-  const typeFilePath = path11.join(provider.ws.typesDir, `${typeName}.json`);
-  if (!fs15.existsSync(typeFilePath)) {
+  const typeFilePath = path12.join(provider.ws.typesDir, `${typeName}.json`);
+  if (!fs16.existsSync(typeFilePath)) {
     const available = Object.keys(provider.types).sort();
     return errorResponse(`Type '${typeName}' was not found in ${provider.ws.typesDir}.`, {
       available_types: available
@@ -26873,8 +27098,8 @@ function handle22(provider, args) {
   let lifecyclePath = null;
   let visibilityChanges = [];
   if (lifecycleName) {
-    const lifecycleFilePath = path11.join(provider.ws.lifecyclesDir, `${lifecycleName}.json`);
-    if (!fs15.existsSync(lifecycleFilePath)) {
+    const lifecycleFilePath = path12.join(provider.ws.lifecyclesDir, `${lifecycleName}.json`);
+    if (!fs16.existsSync(lifecycleFilePath)) {
       warnings.push(
         `Lifecycle '${lifecycleName}' (referenced by type '${typeName}') was not found in ${provider.ws.lifecyclesDir}. Visibility was not updated.`
       );
@@ -26928,12 +27153,12 @@ function handle22(provider, args) {
 // src/tools/attach-attribute-to-layout.ts
 var attach_attribute_to_layout_exports = {};
 __export(attach_attribute_to_layout_exports, {
-  TOOL_DEF: () => TOOL_DEF23,
-  handle: () => handle23
+  TOOL_DEF: () => TOOL_DEF24,
+  handle: () => handle24
 });
-var fs16 = __toESM(require("fs"));
-var path12 = __toESM(require("path"));
-var TOOL_DEF23 = {
+var fs17 = __toESM(require("node:fs"));
+var path13 = __toESM(require("node:path"));
+var TOOL_DEF24 = {
   name: "attach_protrak_attribute_to_layout",
   description: "Add an attribute reference to a Layout Template's underlying form or type widget without regenerating either file. Resolves the layout's widget by templateWidgetKey (or null = first widget) and follows it to the underlying Form (formWidgetName) or TypeWidget (typeWidgetName) JSON, then inserts the attribute reference there with the canonical shape. For Form widgets, you may pass a container_id (formContainerKey) to pick a specific container; otherwise the attribute is added to the first container. Pass replace:true to overwrite an existing field with the same attributeName. Use this instead of regenerating the form/widget when adding a single attribute to an existing layout.",
   inputSchema: {
@@ -26964,16 +27189,10 @@ var TOOL_DEF23 = {
     required: ["layout_name", "attribute_name"]
   }
 };
-function readJson2(filePath) {
-  return JSON.parse(fs16.readFileSync(filePath, "utf8"));
-}
-function writeJson2(filePath, data) {
-  fs16.writeFileSync(filePath, JSON.stringify(data, null, JSON_INDENT), "utf8");
-}
 function findWidget(widgets, widgetId) {
   if (widgets.length === 0) return null;
   if (widgetId === null) return widgets[0];
-  return widgets.find((w) => String(w["templateWidgetKey"] ?? "") === widgetId) ?? null;
+  return widgets.find((w) => (w["templateWidgetKey"] ?? "") === widgetId) ?? null;
 }
 function makeFormField(attrName) {
   return {
@@ -27002,11 +27221,11 @@ function makeWidgetColumn(attrName, attrType) {
   };
 }
 function attachToForm(ws, formName, attrName, containerId, replace) {
-  const filePath = path12.join(ws.formsDir, `${formName}.json`);
-  if (!fs16.existsSync(filePath)) {
+  const filePath = path13.join(ws.formsDir, `${formName}.json`);
+  if (!fs17.existsSync(filePath)) {
     return { error: `Form '${formName}' was not found in ${ws.formsDir}.` };
   }
-  const formData = readJson2(filePath);
+  const formData = readJsonFile(filePath);
   const config2 = formData["formConfiguration"] ?? {};
   const containers = Array.isArray(config2["containers"]) ? config2["containers"] : [];
   if (containers.length === 0) {
@@ -27016,16 +27235,16 @@ function attachToForm(ws, formName, attrName, containerId, replace) {
   if (containerId === void 0) {
     target = containers[0];
   } else {
-    target = containers.find((c) => String(c["formContainerKey"] ?? "") === containerId);
+    target = containers.find((c) => (c["formContainerKey"] ?? "") === containerId);
     if (!target) {
       return {
         error: `Container '${containerId}' not found in form '${formName}'.`,
-        available_containers: containers.map((c) => String(c["formContainerKey"] ?? ""))
+        available_containers: containers.map((c) => c["formContainerKey"] ?? "")
       };
     }
   }
   const fields = Array.isArray(target["fields"]) ? target["fields"] : [];
-  const existingIdx = fields.findIndex((f) => String(f["attributeName"] ?? "") === attrName);
+  const existingIdx = fields.findIndex((f) => (f["attributeName"] ?? "") === attrName);
   let action;
   if (existingIdx >= 0) {
     if (!replace) {
@@ -27040,28 +27259,28 @@ function attachToForm(ws, formName, attrName, containerId, replace) {
     action = "inserted";
   }
   target["fields"] = fields;
-  writeJson2(filePath, formData);
+  writeJsonFilePath(filePath, formData);
   return {
     result: {
       filePath,
       formName,
-      containerKey: String(target["formContainerKey"] ?? ""),
+      containerKey: target["formContainerKey"] ?? "",
       action
     }
   };
 }
 function attachToTypeWidget(provider, widgetName, attrName, replace) {
-  const filePath = path12.join(provider.ws.typeWidgetsDir, `${widgetName}.json`);
-  if (!fs16.existsSync(filePath)) {
+  const filePath = path13.join(provider.ws.typeWidgetsDir, `${widgetName}.json`);
+  if (!fs17.existsSync(filePath)) {
     return { error: `TypeWidget '${widgetName}' was not found in ${provider.ws.typeWidgetsDir}.` };
   }
-  const widgetData = readJson2(filePath);
+  const widgetData = readJsonFile(filePath);
   const isRelation = widgetData["widgetType"] === "Relation";
   const configKey = isRelation ? "relationWidgetConfig" : "dashboardWidgetConfig";
   const config2 = widgetData[configKey] ?? {};
   const fields = Array.isArray(config2["fields"]) ? config2["fields"] : [];
   const attrType = String(provider.attributes[attrName]?.["attributeType"] ?? "Text");
-  const existingIdx = fields.findIndex((f) => String(f["attributeName"] ?? "") === attrName);
+  const existingIdx = fields.findIndex((f) => (f["attributeName"] ?? "") === attrName);
   let action;
   if (existingIdx >= 0) {
     if (!replace) {
@@ -27082,10 +27301,57 @@ function attachToTypeWidget(provider, widgetName, attrName, replace) {
   }
   config2["fields"] = fields;
   widgetData[configKey] = config2;
-  writeJson2(filePath, widgetData);
+  writeJsonFilePath(filePath, widgetData);
   return { result: { filePath, widgetName, action } };
 }
-function handle23(provider, args) {
+function resolveTypeWidgetTarget(provider, widget, attrName, containerId, replace, warnings) {
+  const typeWidgetName = widget["typeWidgetName"] ?? null;
+  const widgetKey = widget["templateWidgetKey"] ?? "";
+  if (!typeWidgetName) {
+    return { error: `Layout widget '${widgetKey}' has widgetType=TypeWidget but no typeWidgetName.` };
+  }
+  if (containerId !== void 0) {
+    warnings.push("container_id is only meaningful for Form widgets; ignored for TypeWidget.");
+  }
+  const out = attachToTypeWidget(provider, typeWidgetName, attrName, replace);
+  if (out.error) {
+    return { error: out.error };
+  }
+  return {
+    target: {
+      kind: "typeWidget",
+      filePath: out.result.filePath,
+      payload: { type_widget_name: out.result.widgetName, action: out.result.action }
+    }
+  };
+}
+function resolveTarget(provider, widget, attrName, containerId, replace, warnings) {
+  const widgetKind = widget["widgetType"] ?? "";
+  const formWidgetName = widget["formWidgetName"] ?? null;
+  const typeWidgetName = widget["typeWidgetName"] ?? null;
+  const widgetKey = widget["templateWidgetKey"] ?? "";
+  if (widgetKind === "Form" || formWidgetName && !typeWidgetName) {
+    if (!formWidgetName) {
+      return { error: `Layout widget '${widgetKey}' has widgetType=Form but no formWidgetName.` };
+    }
+    const out = attachToForm(provider.ws, formWidgetName, attrName, containerId, replace);
+    if (out.error) {
+      return { error: out.error, extra: out.available_containers ? { available_containers: out.available_containers } : void 0 };
+    }
+    return {
+      target: {
+        kind: "form",
+        filePath: out.result.filePath,
+        payload: { form_name: out.result.formName, container_id: out.result.containerKey, action: out.result.action }
+      }
+    };
+  }
+  if (widgetKind === "TypeWidget" || typeWidgetName && !formWidgetName) {
+    return resolveTypeWidgetTarget(provider, widget, attrName, containerId, replace, warnings);
+  }
+  return { error: `Layout widget '${widgetKey}' has unsupported widgetType='${widgetKind}'.` };
+}
+function handle24(provider, args) {
   const layoutName = args["layout_name"] ?? "";
   const widgetIdArg = args["widget_id"];
   const attrName = args["attribute_name"] ?? "";
@@ -27094,19 +27360,15 @@ function handle23(provider, args) {
   if (!layoutName) return errorResponse("layout_name is required");
   if (!attrName) return errorResponse("attribute_name is required");
   if (!isPascalCase(attrName)) return errorResponse(pascalCaseError("attribute_name", attrName));
-  let widgetId;
-  if (widgetIdArg === null || widgetIdArg === void 0) {
-    widgetId = null;
-  } else if (typeof widgetIdArg === "string") {
-    widgetId = widgetIdArg;
-  } else {
+  if (widgetIdArg !== null && widgetIdArg !== void 0 && typeof widgetIdArg !== "string") {
     return errorResponse("widget_id must be a string templateWidgetKey or null.");
   }
-  const layoutPath = path12.join(provider.ws.layoutTemplatesDir, `${layoutName}.json`);
-  if (!fs16.existsSync(layoutPath)) {
+  const widgetId = widgetIdArg ?? null;
+  const layoutPath = path13.join(provider.ws.layoutTemplatesDir, `${layoutName}.json`);
+  if (!fs17.existsSync(layoutPath)) {
     return errorResponse(`Layout template '${layoutName}' was not found in ${provider.ws.layoutTemplatesDir}.`);
   }
-  const layoutData = readJson2(layoutPath);
+  const layoutData = readJsonFile(layoutPath);
   const config2 = layoutData["configuration"] ?? {};
   const widgets = Array.isArray(config2["widgets"]) ? config2["widgets"] : [];
   if (widgets.length === 0) {
@@ -27114,12 +27376,9 @@ function handle23(provider, args) {
   }
   const widget = findWidget(widgets, widgetId);
   if (!widget) {
-    return errorResponse(
-      `widget_id '${widgetId}' not found in layout '${layoutName}'.`,
-      {
-        available_widget_ids: widgets.map((w) => String(w["templateWidgetKey"] ?? ""))
-      }
-    );
+    return errorResponse(`widget_id '${widgetId}' not found in layout '${layoutName}'.`, {
+      available_widget_ids: widgets.map((w) => w["templateWidgetKey"] ?? "")
+    });
   }
   const warnings = [];
   if (!provider.attributes[attrName]) {
@@ -27127,53 +27386,11 @@ function handle23(provider, args) {
       `Attribute '${attrName}' is not defined in ${provider.ws.attributesDir}. The reference will still be inserted; create the attribute or fix the name to resolve.`
     );
   }
-  const widgetKind = String(widget["widgetType"] ?? "");
-  const formWidgetName = widget["formWidgetName"] ?? null;
-  const typeWidgetName = widget["typeWidgetName"] ?? null;
-  let target;
-  if (widgetKind === "Form" || formWidgetName && !typeWidgetName) {
-    if (!formWidgetName) {
-      return errorResponse(`Layout widget '${String(widget["templateWidgetKey"])}' has widgetType=Form but no formWidgetName.`);
-    }
-    if (containerId !== void 0) {
-    }
-    const out = attachToForm(provider.ws, formWidgetName, attrName, containerId, replace);
-    if (out.error) {
-      return errorResponse(out.error, out.available_containers ? { available_containers: out.available_containers } : void 0);
-    }
-    target = {
-      kind: "form",
-      filePath: out.result.filePath,
-      payload: {
-        form_name: out.result.formName,
-        container_id: out.result.containerKey,
-        action: out.result.action
-      }
-    };
-  } else if (widgetKind === "TypeWidget" || typeWidgetName && !formWidgetName) {
-    if (!typeWidgetName) {
-      return errorResponse(`Layout widget '${String(widget["templateWidgetKey"])}' has widgetType=TypeWidget but no typeWidgetName.`);
-    }
-    if (containerId !== void 0) {
-      warnings.push("container_id is only meaningful for Form widgets; ignored for TypeWidget.");
-    }
-    const out = attachToTypeWidget(provider, typeWidgetName, attrName, replace);
-    if (out.error) {
-      return errorResponse(out.error);
-    }
-    target = {
-      kind: "typeWidget",
-      filePath: out.result.filePath,
-      payload: {
-        type_widget_name: out.result.widgetName,
-        action: out.result.action
-      }
-    };
-  } else {
-    return errorResponse(
-      `Layout widget '${String(widget["templateWidgetKey"])}' has unsupported widgetType='${widgetKind}'.`
-    );
+  const resolved = resolveTarget(provider, widget, attrName, containerId, replace, warnings);
+  if ("error" in resolved) {
+    return errorResponse(resolved.error, resolved.extra);
   }
+  const { target } = resolved;
   const nextSteps = [
     `Verify with read_protrak_layout(layout_name='${layoutName}').`,
     `If the attribute is not yet bound to the type, call attach_protrak_attribute_to_type to bind it.`
@@ -27182,7 +27399,7 @@ function handle23(provider, args) {
     {
       layout_name: layoutName,
       layout_path: layoutPath,
-      widget_id: String(widget["templateWidgetKey"] ?? ""),
+      widget_id: widget["templateWidgetKey"] ?? "",
       target_kind: target.kind,
       target_path: target.filePath,
       ...target.payload
@@ -27194,12 +27411,12 @@ function handle23(provider, args) {
 // src/tools/set-attribute-state-visibility.ts
 var set_attribute_state_visibility_exports = {};
 __export(set_attribute_state_visibility_exports, {
-  TOOL_DEF: () => TOOL_DEF24,
-  handle: () => handle24
+  TOOL_DEF: () => TOOL_DEF25,
+  handle: () => handle25
 });
-var fs17 = __toESM(require("fs"));
-var path13 = __toESM(require("path"));
-var TOOL_DEF24 = {
+var fs18 = __toESM(require("fs"));
+var path14 = __toESM(require("path"));
+var TOOL_DEF25 = {
   name: "set_protrak_attribute_state_visibility",
   description: "Set the per-state lifecycle visibility of a single attribute on a Type. Pass visible_states to specify exactly which states the attribute is visible in; omit visible_states to default to 'visible in every state'. Adds the attribute to viewableAttributes/editableAttributes of any Specific-mode state in the visible list, removes it from Specific-mode states not in the list, and converts All-mode states to Specific to enforce hiding when needed (preserving every other type attribute's visibility). Use this to retune visibility on an already-bound attribute; use attach_protrak_attribute_to_type to add a brand-new attribute binding.",
   inputSchema: {
@@ -27222,13 +27439,13 @@ var TOOL_DEF24 = {
     required: ["type_name", "attribute_name"]
   }
 };
-function readJson3(filePath) {
-  return JSON.parse(fs17.readFileSync(filePath, "utf8"));
+function readJson2(filePath) {
+  return JSON.parse(fs18.readFileSync(filePath, "utf8"));
 }
-function writeJson3(filePath, data) {
-  fs17.writeFileSync(filePath, JSON.stringify(data, null, JSON_INDENT), "utf8");
+function writeJson2(filePath, data) {
+  fs18.writeFileSync(filePath, JSON.stringify(data, null, JSON_INDENT), "utf8");
 }
-function handle24(provider, args) {
+function handle25(provider, args) {
   const typeName = args["type_name"] ?? "";
   const attrName = args["attribute_name"] ?? "";
   const hasVisibleStatesArg = Object.prototype.hasOwnProperty.call(args, "visible_states");
@@ -27248,14 +27465,14 @@ function handle24(provider, args) {
     }
     visibleStates = new Set(rawVisible);
   }
-  const typeFilePath = path13.join(provider.ws.typesDir, `${typeName}.json`);
-  if (!fs17.existsSync(typeFilePath)) {
+  const typeFilePath = path14.join(provider.ws.typesDir, `${typeName}.json`);
+  if (!fs18.existsSync(typeFilePath)) {
     const available = Object.keys(provider.types).sort();
     return errorResponse(`Type '${typeName}' was not found in ${provider.ws.typesDir}.`, {
       available_types: available
     });
   }
-  const typeData = readJson3(typeFilePath);
+  const typeData = readJson2(typeFilePath);
   const typeAttributes = Array.isArray(typeData["attributes"]) ? typeData["attributes"] : [];
   const knownTypeAttributes = typeAttributes.map((a) => a.name);
   const warnings = [];
@@ -27268,13 +27485,13 @@ function handle24(provider, args) {
   if (!lifecycleName) {
     return errorResponse(`Type '${typeName}' has no lifecycleName set; cannot adjust visibility.`);
   }
-  const lifecycleFilePath = path13.join(provider.ws.lifecyclesDir, `${lifecycleName}.json`);
-  if (!fs17.existsSync(lifecycleFilePath)) {
+  const lifecycleFilePath = path14.join(provider.ws.lifecyclesDir, `${lifecycleName}.json`);
+  if (!fs18.existsSync(lifecycleFilePath)) {
     return errorResponse(
       `Lifecycle '${lifecycleName}' (referenced by type '${typeName}') was not found in ${provider.ws.lifecyclesDir}.`
     );
   }
-  const lifecycleData = readJson3(lifecycleFilePath);
+  const lifecycleData = readJson2(lifecycleFilePath);
   const stateNames = (lifecycleData["states"] ?? []).map(
     (s) => String(s["name"] ?? "")
   );
@@ -27291,7 +27508,7 @@ function handle24(provider, args) {
     knownTypeAttributes
   });
   if (changed) {
-    writeJson3(lifecycleFilePath, lifecycleData);
+    writeJson2(lifecycleFilePath, lifecycleData);
   }
   const nextSteps = [
     `Verify with read_protrak_schema_element(kind='lifecycle', name='${lifecycleName}').`,
@@ -27311,6 +27528,194 @@ function handle24(provider, args) {
   );
 }
 
+// src/tools/get-notification-context.ts
+var get_notification_context_exports = {};
+__export(get_notification_context_exports, {
+  TOOL_DEF: () => TOOL_DEF26,
+  VALID_TARGETS: () => VALID_TARGETS,
+  handle: () => handle26
+});
+var fs19 = __toESM(require("fs"));
+var path15 = __toESM(require("path"));
+var DATA_DIR2 = path15.join(__dirname, "..", "..", "data");
+var NOTIFICATION_TEMPLATE_REFERENCE_PATH = path15.join(
+  DATA_DIR2,
+  "patterns",
+  "notification-template-reference.md"
+);
+var VALID_TARGETS = [
+  "PromoteNotification",
+  "AccountNotification",
+  "WorkflowNotification",
+  "WorkflowTaskNotification"
+];
+var TARGET_DESCRIPTIONS = {
+  PromoteNotification: "Triggered by a lifecycle promote action. Link the template in the lifecycle Send Notification command.",
+  AccountNotification: "Triggered by user creation or password reset. Link in Tenant Settings \u2192 Notifications.",
+  WorkflowNotification: "Triggered by a workflow Notification Activity. Link in Workflow \u2192 Notification Activity.",
+  WorkflowTaskNotification: "Triggered by workflow Input/Checklist Task Activity creation. Link in Workflow \u2192 Input/Checklist Task Activity."
+};
+var TOOL_DEF26 = {
+  name: "get_protrak_notification_context",
+  description: "RECOMMENDED first call when creating a Protrak notification template. Returns existing templates from the workspace (optionally filtered by type name) and the full @Model variable reference for all target types. Templates use Razor syntax (@Model.*), NOT {{}} placeholders. Email notifications require two separate templates: one for Subject, one for Body. Missing notificationTemplates/ directory returns an empty list without error.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      type_name: {
+        type: "string",
+        description: "Optional. Filter existing templates whose title contains this name (e.g. 'Invoice'). Omit to return all templates."
+      },
+      target: {
+        type: "string",
+        description: "Optional. Filter by target type: 'PromoteNotification', 'AccountNotification', 'WorkflowNotification', or 'WorkflowTaskNotification'. Omit to return all."
+      }
+    },
+    required: []
+  }
+};
+function handle26(provider, args) {
+  const typeName = args["type_name"] || void 0;
+  const targetFilter = args["target"] || void 0;
+  const lp = getOrCreateProvider(provider.ws);
+  let templates = lp.notificationTemplatesForType(typeName);
+  if (targetFilter) {
+    templates = templates.filter((t) => t.target === targetFilter);
+  }
+  let variableReference = "";
+  try {
+    variableReference = fs19.readFileSync(NOTIFICATION_TEMPLATE_REFERENCE_PATH, "utf8");
+  } catch {
+    variableReference = "Variable reference file not found.";
+  }
+  const targetTypes = VALID_TARGETS.map((t) => ({
+    value: t,
+    description: TARGET_DESCRIPTIONS[t]
+  }));
+  const nextSteps = [];
+  if (templates.length > 0) {
+    nextSteps.push(
+      "Review existing_templates above for naming conventions and patterns used in this workspace."
+    );
+  }
+  nextSteps.push(
+    "Call generate_protrak_notification_template(name='<Title> Body', target='PromoteNotification', email_html='<Razor HTML>') to write both .json and .html files.",
+    "For email notifications, also call generate_protrak_notification_template for the subject: name='<Title> Subject', email_html='<one-line subject>'."
+  );
+  const result = {
+    existing_templates: templates,
+    target_types: targetTypes,
+    variable_reference: variableReference,
+    next_steps: nextSteps
+  };
+  return JSON.stringify(result, null, 2);
+}
+
+// src/tools/generate-notification-template.ts
+var generate_notification_template_exports = {};
+__export(generate_notification_template_exports, {
+  TOOL_DEF: () => TOOL_DEF27,
+  handle: () => handle27
+});
+var fs20 = __toESM(require("fs"));
+var path16 = __toESM(require("path"));
+function buildTemplateJson(name, target, messageText) {
+  return {
+    title: name,
+    target,
+    emailText: null,
+    hashCode: "",
+    messageText: messageText ?? null,
+    templateState: "Published"
+  };
+}
+var TOOL_DEF27 = {
+  name: "generate_protrak_notification_template",
+  description: "Write a Protrak notification template to disk. Creates NotificationTemplates/<name>.json (metadata) and, when email_html is provided, NotificationTemplates/<name>.html (Razor HTML email body). hashCode is left empty \u2014 Protrak recomputes it on import. Templates use @Model.* Razor syntax (NOT {{}} placeholders). For a full email notification, call this tool twice: once for the Subject template (name='<Title> Subject') and once for the Body template (name='<Title> Body'). Call get_protrak_notification_context first to see existing templates and variable reference.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description: "Template title and filename (e.g. 'Invoice Sent Body', 'Invoice Sent Subject'). Spaces are allowed \u2014 matches MIS.Customization naming convention. Subject templates end with 'Subject'; body templates end with 'Body'."
+      },
+      target: {
+        type: "string",
+        description: "Notification event type. One of: 'PromoteNotification' (lifecycle promote), 'AccountNotification' (user creation/password reset), 'WorkflowNotification' (workflow notification activity), 'WorkflowTaskNotification' (workflow input/checklist task)."
+      },
+      email_html: {
+        type: "string",
+        description: "Razor HTML content for the email template. Written to <name>.html. Use @Model.* variables (see get_protrak_notification_context for the full reference). Omit if this is a push-only template."
+      },
+      message_text: {
+        type: "string",
+        description: "Short plain-text push notification content. Stored in the JSON as messageText. Razor syntax is supported. Omit if this is an email-only template."
+      },
+      overwrite: {
+        type: "boolean",
+        description: "When true, overwrite existing files. Default: false (errors on conflict).",
+        default: false
+      }
+    },
+    required: ["name", "target"]
+  }
+};
+function handle27(provider, args) {
+  const name = args["name"] ?? "";
+  const target = args["target"] ?? "";
+  const emailHtml = args["email_html"] || void 0;
+  const messageText = args["message_text"] || void 0;
+  const overwrite = args["overwrite"] === true;
+  if (!name) return errorResponse("name is required");
+  if (!target) return errorResponse("target is required");
+  if (!VALID_TARGETS.includes(target)) {
+    return errorResponse(
+      `Unknown target '${target}'. Valid values: ${VALID_TARGETS.join(", ")}.`,
+      { valid_targets: [...VALID_TARGETS] }
+    );
+  }
+  if (!emailHtml && !messageText) {
+    return errorResponse(
+      "At least one of email_html or message_text must be provided."
+    );
+  }
+  const dir = provider.ws.notificationTemplatesDir;
+  if (!fs20.existsSync(dir)) {
+    fs20.mkdirSync(dir, { recursive: true });
+  }
+  const jsonPath = path16.join(dir, `${name}.json`);
+  const htmlPath = emailHtml ? path16.join(dir, `${name}.html`) : null;
+  if (!overwrite) {
+    const existing = [];
+    if (fs20.existsSync(jsonPath)) existing.push(jsonPath);
+    if (htmlPath && fs20.existsSync(htmlPath)) existing.push(htmlPath);
+    if (existing.length > 0) {
+      return errorResponse(
+        `Refusing to overwrite existing file(s): ${existing.join(", ")}. Pass overwrite:true to replace.`,
+        { existing_paths: existing }
+      );
+    }
+  }
+  const templateJson = buildTemplateJson(name, target, messageText);
+  fs20.writeFileSync(jsonPath, JSON.stringify(templateJson, null, JSON_INDENT), "utf8");
+  if (emailHtml && htmlPath) {
+    fs20.writeFileSync(htmlPath, emailHtml, "utf8");
+  }
+  const nextSteps = [
+    `Verify by calling get_protrak_notification_context(type_name='${name.split(" ")[0]}').`,
+    "On import, Protrak recomputes hashCode automatically \u2014 leaving it empty here is intentional."
+  ];
+  return successResponse(
+    {
+      name,
+      target,
+      json_path: jsonPath,
+      ...htmlPath ? { html_path: htmlPath } : {},
+      written_json: templateJson
+    },
+    { nextSteps }
+  );
+}
+
 // src/index.ts
 function semverGte(a, b) {
   const parse3 = (v) => v.split(".").map((n) => parseInt(n, 10) || 0);
@@ -27324,6 +27729,7 @@ var TOOLS = [
   // Workflow entry points (call these first)
   get_program_context_exports,
   get_layout_context_exports,
+  get_notification_context_exports,
   scaffold_entity_exports,
   validate_program_exports,
   // Knowledge search (patterns / api / programs)
@@ -27346,6 +27752,8 @@ var TOOLS = [
   generate_form_exports,
   generate_type_widget_exports,
   generate_layout_template_exports,
+  generate_program_exports,
+  generate_notification_template_exports,
   // Surgical mutators — modify existing files without regeneration/clobber
   attach_attribute_to_type_exports,
   attach_attribute_to_layout_exports,
@@ -27385,11 +27793,18 @@ Restart VS Code (or reload the window) so npx can fetch the latest version.
   log("info", `Protrak Forge MCP ready \u2014 ${TOOLS.length} tools | workspace: ${workspace.namespace} | types: ${typeCount} | programs: ${programCount}`);
   const SERVER_INSTRUCTIONS = `You are working in a Protrak customization workspace. Protrak programs are C# classes that implement trigger interfaces (PreCreate, PostCreate, PreUpdate, PromoteActionCommand, Scheduler, etc.).
 
-WORKFLOW for writing Protrak programs:
+WORKFLOW for writing a NEW Protrak program:
 1. ALWAYS call get_protrak_program_context first \u2014 it returns the type schema, interface contract, coding patterns, similar programs, and available query definitions (for IQueryBuilderService) in one call.
 2. Write the C# program following the interface contract and patterns.
 3. If the program uses IQueryBuilderService: pick a query name from the query_definitions returned by get_protrak_program_context, or call generate_protrak_query_definition to create a new one before writing the program.
 4. ALWAYS call validate_protrak_program after writing to check for errors.
+5. Once validation is clean, call generate_protrak_program(program_name, program_type, source) \u2014 this writes BOTH Programs/<name>.cs AND Programs/<name>.json (the companion metadata Protrak's import flow needs). Do NOT use the filesystem Write tool for new programs \u2014 you will skip the .json companion and the program will not import.
+
+WORKFLOW for REFACTORING an existing Protrak program:
+1. Call get_protrak_program_context with program_name set to the existing program name. This returns the current source AND the schema/interface/patterns context in ONE call (no need to chain read_protrak_program separately).
+2. Edit the C# source.
+3. Call validate_protrak_program(code, program_type) \u2014 same as for new programs.
+4. Write the edited source back to the existing Programs/<name>.cs file. Do NOT call generate_protrak_program for refactors \u2014 the companion .json already exists.
 
 WORKFLOW for creating a QueryDefinition (no program needed):
 1. Call read_protrak_schema_element with kind='type' to get attribute names and valid state names.
@@ -27405,6 +27820,13 @@ WORKFLOW for scaffolding schema elements (Types, Lifecycles, Attributes, Relatio
 6. All schema names must be PascalCase. Aliases are allowed for attribute_type: Number\u2192Numeric, File\u2192Attachment.
 7. All generators refuse to overwrite an existing file unless overwrite:true.
 
+WORKFLOW for writing a notification template:
+1. Call get_protrak_notification_context first \u2014 returns existing templates and the full @Model variable reference.
+2. Write the Razor HTML email body using @Model.* syntax (NOT {{}} placeholders).
+3. Call generate_protrak_notification_template for the Body template (name="<Title> Body", target, email_html).
+4. Call generate_protrak_notification_template again for the Subject template (name="<Title> Subject", email_html="<one-liner subject>").
+5. For push-only notifications, omit email_html and provide message_text instead.
+
 WORKFLOW for designing a Design Studio layout:
 1. Call get_protrak_layout_context first \u2014 returns type schema and all existing layouts for the type+mode.
 2. Use list_protrak_layouts to browse all artifacts; use read_protrak_layout to read a specific one's full JSON.