@enfyra/mcp-server 0.1.5 → 0.1.7

package/src/lib/platform-operation-tools.js

@@ -6,8 +6,10 @@ import {
   assertDynamicCodeKnowledgeAck,
   assertDynamicCodeKnowledgeAckIf,
   assertExtensionKnowledgeAck,
+  assertGlobalRulesAck,
   dynamicCodeKnowledgeAckParam,
   extensionKnowledgeAckParam,
+  globalRulesAckParam,
 } from './required-knowledge.js';
 
 function unwrapData(result) {
@@ -111,7 +113,8 @@ async function resolveRoute(apiUrl, { path, routeId }) {
   return { route, routes, path: route.path };
 }
 
-async function updateRouteMethods(apiUrl, { path, routeId, methods, mode, isEnabled }) {
+async function updateRouteMethods(apiUrl, { path, routeId, methods, mode, isEnabled, globalRulesAckKey }) {
+  assertGlobalRulesAck(globalRulesAckKey);
   const [{ route }, { methodMap, methodIdNameMap }] = await Promise.all([
     resolveRoute(apiUrl, { path, routeId }),
     getMethodContext(apiUrl),
@@ -141,7 +144,8 @@ async function updateRouteMethods(apiUrl, { path, routeId, methods, mode, isEnab
   };
 }
 
-async function updateRoutePublicMethods(apiUrl, { path, routeId, methods, mode }) {
+async function updateRoutePublicMethods(apiUrl, { path, routeId, methods, mode, globalRulesAckKey }) {
+  assertGlobalRulesAck(globalRulesAckKey);
   const [{ route }, { methodMap, methodIdNameMap }] = await Promise.all([
     resolveRoute(apiUrl, { path, routeId }),
     getMethodContext(apiUrl),
@@ -171,7 +175,8 @@ async function updateRoutePublicMethods(apiUrl, { path, routeId, methods, mode }
   };
 }
 
-async function setRouteEnabled(apiUrl, { path, routeId, isEnabled }) {
+async function setRouteEnabled(apiUrl, { path, routeId, isEnabled, globalRulesAckKey }) {
+  assertGlobalRulesAck(globalRulesAckKey);
   const { route } = await resolveRoute(apiUrl, { path, routeId });
   const before = route?.isEnabled !== false;
   if (before === isEnabled) {
@@ -235,7 +240,7 @@ async function deleteRows(apiUrl, tableName, rows) {
   return deleted;
 }
 
-async function deleteRoute(apiUrl, { path, routeId, expectedPath, confirm }) {
+async function deleteRoute(apiUrl, { path, routeId, expectedPath, confirm, globalRulesAckKey }) {
   const { route } = await resolveRoute(apiUrl, { path, routeId });
   if (expectedPath && route.path !== normalizeRestPath(expectedPath)) {
     throw new Error(`Route path mismatch: resolved ${route.path}, expected ${normalizeRestPath(expectedPath)}.`);
@@ -255,6 +260,7 @@ async function deleteRoute(apiUrl, { path, routeId, expectedPath, confirm }) {
       next: 'Call delete_route again with confirm=true and expectedPath set to this route path to delete the route and related handlers/hooks/permissions/guards.',
     };
   }
+  assertGlobalRulesAck(globalRulesAckKey);
 
   await deleteRows(apiUrl, 'enfyra_route_handler', dependencies.handlers);
   await deleteRows(apiUrl, 'enfyra_pre_hook', dependencies.preHooks);
@@ -641,7 +647,9 @@ async function ensureMenu(apiUrl, {
   permission,
   description,
   isEnabled = true,
+  globalRulesAckKey,
 }) {
+  assertGlobalRulesAck(globalRulesAckKey);
   const normalizedPath = path ? normalizeRestPath(path) : undefined;
   const existing = normalizedPath
     ? await findRecord(apiUrl, 'enfyra_menu', { path: { _eq: normalizedPath } }, 'id,_id,path,label')
@@ -673,8 +681,10 @@ async function ensureExtension(apiUrl, {
   description,
   isEnabled = true,
   version = '1.0.0',
+  globalRulesAckKey,
   extensionKnowledgeAckKey,
 }) {
+  assertGlobalRulesAck(globalRulesAckKey);
   assertExtensionKnowledgeAck(extensionKnowledgeAckKey);
   if (type === 'page' && !menuId) {
     throw new Error('menuId is required for page extensions. Use ensure_menu first, then ensure_page_extension.');
@@ -711,7 +721,9 @@ async function ensureFlow(apiUrl, {
   maxExecutions = 100,
   isEnabled = true,
   description,
+  globalRulesAckKey,
 }) {
+  assertGlobalRulesAck(globalRulesAckKey);
   const existing = await findRecord(apiUrl, 'enfyra_flow', { name: { _eq: name } }, 'id,_id,name');
   const operation = await createOrPatch(apiUrl, 'enfyra_flow', existing, {
     name,
@@ -737,8 +749,10 @@ async function ensureFlowStep(apiUrl, {
   scriptLanguage,
   timeout,
   isEnabled,
+  globalRulesAckKey,
   knowledgeAckKey,
 }) {
+  assertGlobalRulesAck(globalRulesAckKey);
   if (!flowName && !flowId) throw new Error('Provide flowName or flowId.');
   if (flowName && flowId) throw new Error('Provide flowName or flowId, not both.');
   const flow = flowId
@@ -1124,6 +1138,7 @@ async function runApiEndpointWorkflow(apiUrl, opts) {
   const operations = [];
   let completedEphemeralStepId = null;
   if (opts.apply || opts.applyAll) {
+    assertGlobalRulesAck(opts.globalRulesAckKey);
     if (opts.applyAll && state.steps.some((item) => item.id === 'save_handler' && ['pending', 'waiting'].includes(item.status))) {
       assertDynamicCodeKnowledgeAck(opts.knowledgeAckKey);
     }
@@ -1227,8 +1242,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     {
       tableName: z.string().describe('Table name, alias, or id.'),
       isEnabled: z.boolean().describe('Desired GraphQL enabled state for the table.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ tableName, isEnabled }) => {
+    async ({ tableName, isEnabled, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       const table = resolveTable(await getMetadataTables(ENFYRA_API_URL), tableName);
       const existing = await findRecord(ENFYRA_API_URL, 'enfyra_graphql', { table: { id: { _eq: getId(table) } } }, 'id,_id,table.id,isEnabled');
       const operation = await createOrPatch(ENFYRA_API_URL, 'enfyra_graphql', existing, {
@@ -1254,13 +1271,15 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
       methods: z.array(z.string()).min(1).describe('HTTP method names to add.'),
       isEnabled: z.boolean().optional().describe('Optionally enable/disable the route in the same safe patch.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ path, routeId, methods, isEnabled }) => jsonText(await updateRouteMethods(ENFYRA_API_URL, {
+    async ({ path, routeId, methods, isEnabled, globalRulesAckKey }) => jsonText(await updateRouteMethods(ENFYRA_API_URL, {
       path,
       routeId,
       methods,
       mode: 'merge',
       isEnabled,
+      globalRulesAckKey,
     })),
   );
 
@@ -1272,13 +1291,15 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
       methods: z.array(z.string()).min(1).describe('Exact HTTP method names for availableMethods.'),
       isEnabled: z.boolean().optional().describe('Optionally enable/disable the route in the same safe patch.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ path, routeId, methods, isEnabled }) => jsonText(await updateRouteMethods(ENFYRA_API_URL, {
+    async ({ path, routeId, methods, isEnabled, globalRulesAckKey }) => jsonText(await updateRouteMethods(ENFYRA_API_URL, {
       path,
       routeId,
       methods,
       mode: 'replace',
       isEnabled,
+      globalRulesAckKey,
     })),
   );
 
@@ -1290,13 +1311,15 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
       methods: z.array(z.string()).min(1).describe('HTTP method names to remove.'),
       isEnabled: z.boolean().optional().describe('Optionally enable/disable the route in the same safe patch.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ path, routeId, methods, isEnabled }) => jsonText(await updateRouteMethods(ENFYRA_API_URL, {
+    async ({ path, routeId, methods, isEnabled, globalRulesAckKey }) => jsonText(await updateRouteMethods(ENFYRA_API_URL, {
       path,
       routeId,
       methods,
       mode: 'remove',
       isEnabled,
+      globalRulesAckKey,
     })),
   );
 
@@ -1306,11 +1329,13 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     {
       path: z.string().optional().describe('Route path, e.g. /sum. Use either path or routeId.'),
       routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ path, routeId }) => jsonText(await setRouteEnabled(ENFYRA_API_URL, {
+    async ({ path, routeId, globalRulesAckKey }) => jsonText(await setRouteEnabled(ENFYRA_API_URL, {
       path,
       routeId,
       isEnabled: true,
+      globalRulesAckKey,
     })),
   );
 
@@ -1320,11 +1345,13 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     {
       path: z.string().optional().describe('Route path, e.g. /sum. Use either path or routeId.'),
       routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ path, routeId }) => jsonText(await setRouteEnabled(ENFYRA_API_URL, {
+    async ({ path, routeId, globalRulesAckKey }) => jsonText(await setRouteEnabled(ENFYRA_API_URL, {
       path,
       routeId,
       isEnabled: false,
+      globalRulesAckKey,
     })),
   );
 
@@ -1336,6 +1363,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
       expectedPath: z.string().optional().describe('Optional safety check. When confirm=true, pass the path returned by the preview.'),
       confirm: z.boolean().optional().default(false).describe('false returns a dependency preview only; true deletes the route and related route-owned records.'),
+      globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
     },
     async (input) => jsonText(await deleteRoute(ENFYRA_API_URL, input)),
   );
@@ -1347,12 +1375,14 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       path: z.string().optional().describe('Route path, e.g. /sum. Use either path or routeId.'),
       routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
       methods: z.array(z.string()).min(1).describe('HTTP method names to make public. They must already be available on the route.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ path, routeId, methods }) => jsonText(await updateRoutePublicMethods(ENFYRA_API_URL, {
+    async ({ path, routeId, methods, globalRulesAckKey }) => jsonText(await updateRoutePublicMethods(ENFYRA_API_URL, {
       path,
       routeId,
       methods,
       mode: 'merge',
+      globalRulesAckKey,
     })),
   );
 
@@ -1363,12 +1393,14 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       path: z.string().optional().describe('Route path, e.g. /sum. Use either path or routeId.'),
       routeId: z.union([z.string(), z.number()]).optional().describe('Route id. Use either path or routeId.'),
       methods: z.array(z.string()).min(1).describe('HTTP method names to remove from publicMethods.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ path, routeId, methods }) => jsonText(await updateRoutePublicMethods(ENFYRA_API_URL, {
+    async ({ path, routeId, methods, globalRulesAckKey }) => jsonText(await updateRoutePublicMethods(ENFYRA_API_URL, {
       path,
       routeId,
       methods,
       mode: 'remove',
+      globalRulesAckKey,
     })),
   );
 
@@ -1399,6 +1431,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       apply: z.boolean().optional().default(false).describe('false returns plan only; true applies exactly the next pending step.'),
       applyAll: z.boolean().optional().default(false).describe('true applies all safe pending steps in order. Prefer apply=true for production changes.'),
       stepId: z.string().optional().describe('Optional pending step id to apply. Omit to apply the next pending step.'),
+      globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when apply/applyAll mutates metadata. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
       knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required when apply/applyAll reaches the save_handler step. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
     },
     async (input) => jsonText(await runApiEndpointWorkflow(ENFYRA_API_URL, input)),
@@ -1408,7 +1441,8 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     'create_api_endpoint',
     [
       'Business operation: create or update a custom REST endpoint with a handler in one safe operation.',
-      'Use this when the user asks for a new route/endpoint/API path that computes or orchestrates behavior, such as GET /sum or POST /webhook.',
+      'Prefer api_endpoint_workflow when route access, role/user permissions, overwrite decisions, or multi-step planning matter.',
+      'Use this one-shot helper only when the endpoint contract is already clear and no authenticated route-permission step is needed in the same operation, such as a simple public webhook or private admin-only utility that will be granted separately.',
       'It creates the route without mainTableId, ensures the method is available, validates sourceCode, creates or overwrites the route handler, optionally makes the method public, reloads routes, and can smoke-test the endpoint.',
       'Use table/schema tools separately when the user needs persisted data. This tool is for custom behavior endpoints.',
     ].join(' '),
@@ -1423,9 +1457,11 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       overwrite: z.boolean().optional().default(false).describe('If a handler already exists for route+method, false fails; true updates its sourceCode.'),
       smokeTestQuery: z.string().optional().describe('Optional query JSON object for a smoke test after save, e.g. {"a":"1","b":"2"}.'),
       smokeTestBody: z.string().optional().describe('Optional body JSON object for a smoke test after save.'),
+      globalRulesAckKey: globalRulesAckParam(z),
       knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
     },
-    async ({ path, method, sourceCode, scriptLanguage, public: makePublic, description, timeout, overwrite, smokeTestQuery, smokeTestBody, knowledgeAckKey }) => {
+    async ({ path, method, sourceCode, scriptLanguage, public: makePublic, description, timeout, overwrite, smokeTestQuery, smokeTestBody, globalRulesAckKey, knowledgeAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       assertDynamicCodeKnowledgeAck(knowledgeAckKey);
       const normalizedPath = normalizeRestPath(path);
       const methodName = normalizeMethodName(method);
@@ -1556,8 +1592,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       message: z.string().optional().describe('Custom validation error message.'),
       description: z.string().optional().describe('Admin note.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable the rule.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ tableName, columnName, ruleType, value, message, description, isEnabled }) => {
+    async ({ tableName, columnName, ruleType, value, message, description, isEnabled, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       const table = resolveTable(await getMetadataTables(ENFYRA_API_URL), tableName);
       const column = resolveColumn(table, columnName);
       const existing = await findRecord(ENFYRA_API_URL, 'enfyra_column_rule', {
@@ -1597,8 +1635,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       condition: z.string().optional().describe('Condition JSON object using field permission DSL.'),
       description: z.string().optional().describe('Admin note.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable the permission.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ tableName, columnName, relationName, action, effect, roleId, roleName, allowedUserIds, condition, description, isEnabled }) => {
+    async ({ tableName, columnName, relationName, action, effect, roleId, roleName, allowedUserIds, condition, description, isEnabled, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       if (!!columnName === !!relationName) throw new Error('Provide exactly one of columnName or relationName.');
       assertOneScope({ roleId, roleName, allowedUserIds });
       const [tables, role] = await Promise.all([
@@ -1656,8 +1696,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       description: z.string().optional().describe('Admin note.'),
       rules: z.string().optional().describe('Rules JSON array: [{type, config, priority, isEnabled, description, userIds}].'),
       rulesMode: z.enum(['append', 'replace', 'none']).optional().default('append').describe('append creates rules, replace disables existing rules first, none leaves rules unchanged.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ name, guardId, position, routeId, path, methods, combinator, priority, isGlobal, isEnabled, description, rules, rulesMode }) => {
+    async ({ name, guardId, position, routeId, path, methods, combinator, priority, isGlobal, isEnabled, description, rules, rulesMode, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       if (path && routeId) throw new Error('Provide path or routeId, not both.');
       const ruleInputs = parseJsonArrayArg('rules', rules, []);
       if (position === 'pre_auth') {
@@ -1733,9 +1775,11 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language for connection handler.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable gateway.'),
       description: z.string().optional().describe('Admin note.'),
+      globalRulesAckKey: globalRulesAckParam(z),
       knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required when sourceCode is provided. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
     },
-    async ({ path, sourceCode, scriptLanguage, isEnabled, description, knowledgeAckKey }) => {
+    async ({ path, sourceCode, scriptLanguage, isEnabled, description, globalRulesAckKey, knowledgeAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       assertDynamicCodeKnowledgeAckIf(sourceCode !== undefined, knowledgeAckKey);
       const normalizedPath = normalizeRestPath(path);
       const validation = sourceCode === undefined
@@ -1765,9 +1809,11 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable event.'),
       description: z.string().optional().describe('Admin note.'),
+      globalRulesAckKey: globalRulesAckParam(z),
       knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
     },
-    async ({ gatewayPath, gatewayId, eventName, sourceCode, scriptLanguage, isEnabled, description, knowledgeAckKey }) => {
+    async ({ gatewayPath, gatewayId, eventName, sourceCode, scriptLanguage, isEnabled, description, globalRulesAckKey, knowledgeAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       assertDynamicCodeKnowledgeAck(knowledgeAckKey);
       if (!gatewayPath && !gatewayId) throw new Error('Provide gatewayPath or gatewayId.');
       if (gatewayPath && gatewayId) throw new Error('Provide gatewayPath or gatewayId, not both.');
@@ -1802,14 +1848,16 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       maxExecutions: z.number().int().positive().optional().default(100).describe('Execution history cap.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable flow.'),
       description: z.string().optional().describe('Admin note.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ name, timeout, maxExecutions, isEnabled, description }) => jsonText(await ensureFlow(ENFYRA_API_URL, {
+    async ({ name, timeout, maxExecutions, isEnabled, description, globalRulesAckKey }) => jsonText(await ensureFlow(ENFYRA_API_URL, {
       name,
       triggerType: 'manual',
       timeout,
       maxExecutions,
       isEnabled,
       description,
+      globalRulesAckKey,
     })),
   );
 
@@ -1823,8 +1871,9 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       maxExecutions: z.number().int().positive().optional().default(100).describe('Execution history cap.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable flow.'),
       description: z.string().optional().describe('Admin note.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ name, triggerConfig, timeout, maxExecutions, isEnabled, description }) => jsonText(await ensureFlow(ENFYRA_API_URL, {
+    async ({ name, triggerConfig, timeout, maxExecutions, isEnabled, description, globalRulesAckKey }) => jsonText(await ensureFlow(ENFYRA_API_URL, {
       name,
       triggerType: 'schedule',
       triggerConfig,
@@ -1832,6 +1881,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       maxExecutions,
       isEnabled,
       description,
+      globalRulesAckKey,
     })),
   );
 
@@ -1870,6 +1920,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
       knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
@@ -1891,6 +1942,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
       knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
@@ -1910,6 +1962,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -1928,6 +1981,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -1946,6 +2000,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -1964,6 +2019,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -1982,6 +2038,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -2000,6 +2057,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -2018,6 +2076,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -2036,6 +2095,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       order: z.number().optional().default(0).describe('Step order. Saved as enfyra_flow_step.stepOrder.'),
       timeout: z.number().int().positive().optional().describe('Step timeout in ms.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable step.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -2055,6 +2115,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       permission: z.string().optional().describe('Menu permission JSON object.'),
       description: z.string().optional().describe('Admin note.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable menu.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
     async (input) => jsonText({
       action: 'menu_ensured',
@@ -2072,6 +2133,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       description: z.string().optional().describe('Extension description.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable extension.'),
       version: z.string().optional().default('1.0.0').describe('Extension version.'),
+      globalRulesAckKey: globalRulesAckParam(z),
       extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
     },
     async (input) => jsonText({
@@ -2089,6 +2151,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       description: z.string().optional().describe('Extension description.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable extension.'),
       version: z.string().optional().default('1.0.0').describe('Extension version.'),
+      globalRulesAckKey: globalRulesAckParam(z),
       extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
     },
     async (input) => jsonText({
@@ -2106,6 +2169,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       description: z.string().optional().describe('Extension description.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable extension.'),
       version: z.string().optional().default('1.0.0').describe('Extension version.'),
+      globalRulesAckKey: globalRulesAckParam(z),
       extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
     },
     async (input) => jsonText({

package/src/lib/required-knowledge.js

@@ -1,7 +1,12 @@
+export const GLOBAL_RULES_ACK_KEY = 'EFYRA::GLOBAL-RULES::READ-LIVE-CONTEXT-FIRST::2bW-20260701';
 export const DYNAMIC_CODE_KNOWLEDGE_ACK_KEY = 'EFYRA::SECURE-REPO-CONTRACT::R9x-kelp-42Q::NO-RAW-TRUSTED';
 export const EXTENSION_KNOWLEDGE_ACK_KEY = 'EFYRA::EXTENSION-THEME-CONTRACT::VIOLET-IS-NOT-A-PLAN::7mQ';
 
-const REQUIRED_KNOWLEDGE_VERSION = '2026-06-30.secure-repo-v1';
+const REQUIRED_KNOWLEDGE_VERSION = '2026-07-01.global-rules-v1';
+
+export function globalRulesAckParam(z) {
+  return z.string().describe('Required global-rules acknowledgement key from get_enfyra_required_knowledge. Call that tool, read the global Enfyra MCP rules, then pass globalRulesAckKey exactly.');
+}
 
 export function dynamicCodeKnowledgeAckParam(z) {
   return z.string().describe('Required dynamic-code acknowledgement key from get_enfyra_required_knowledge. Call that tool, read the dynamic server code knowledge, then pass dynamicCodeAckKey exactly.');
@@ -11,6 +16,16 @@ export function extensionKnowledgeAckParam(z) {
   return z.string().describe('Required extension acknowledgement key from get_enfyra_required_knowledge. Call that tool, read the extension/theme knowledge, then pass extensionAckKey exactly.');
 }
 
+export function assertGlobalRulesAck(key) {
+  if (key !== GLOBAL_RULES_ACK_KEY) {
+    throw new Error('Missing or invalid global-rules acknowledgement. Call get_enfyra_required_knowledge, read the global Enfyra MCP rules, then pass globalRulesAckKey as globalRulesAckKey.');
+  }
+}
+
+export function assertGlobalRulesAckIf(condition, key) {
+  if (condition) assertGlobalRulesAck(key);
+}
+
 export function assertDynamicCodeKnowledgeAck(key) {
   if (key !== DYNAMIC_CODE_KNOWLEDGE_ACK_KEY) {
     throw new Error('Missing or invalid dynamic-code knowledge acknowledgement. Call get_enfyra_required_knowledge, read the dynamic server code contracts, then pass dynamicCodeAckKey as knowledgeAckKey.');
@@ -34,13 +49,59 @@ export function assertExtensionKnowledgeAckIf(condition, key) {
 export function buildRequiredKnowledgePayload() {
   return {
     version: REQUIRED_KNOWLEDGE_VERSION,
-    purpose: 'Read this before generating or saving Enfyra dynamic server code through MCP.',
+    purpose: 'Read this before mutating Enfyra metadata, schema, routes, permissions, menus, packages, cache state, dynamic server code, or extension UI through MCP.',
+    globalRulesAckKey: GLOBAL_RULES_ACK_KEY,
     dynamicCodeAckKey: DYNAMIC_CODE_KNOWLEDGE_ACK_KEY,
     extensionAckKey: EXTENSION_KNOWLEDGE_ACK_KEY,
     usage: [
+      'Pass globalRulesAckKey exactly as globalRulesAckKey when calling MCP tools that mutate Enfyra metadata, schema, routes, permissions, menus, packages, cache state, dynamic code, or extension UI.',
       'Pass dynamicCodeAckKey exactly as knowledgeAckKey when calling MCP tools that create or update dynamic server code.',
       'Pass extensionAckKey exactly as extensionKnowledgeAckKey when calling MCP tools that create or update Enfyra extension code.',
     ],
+    globalRules: [
+      {
+        id: 'examples-are-reasoning-anchors',
+        rules: [
+          'Examples explain transferable decisions, not copy-paste mandates.',
+          'Preserve platform contracts and safety boundaries, then adapt names, routes, fields, menus, labels, and lifecycle to live metadata and the user goal.',
+          'When examples use chat, order, report, cloud, email, or support domains, treat those as analogies unless the current task is exactly that domain.',
+        ],
+      },
+      {
+        id: 'discover-before-changing',
+        rules: [
+          'Inspect live metadata/routes/features before schema, route, permission, extension, flow, or handler changes.',
+          'Use narrow inspection tools for the table, route, feature, or script being changed instead of broad discovery after the target is known.',
+          'Read sourceCode, not compiledCode, for editable dynamic scripts.',
+        ],
+      },
+      {
+        id: 'mutations-are-intentional',
+        rules: [
+          'Prefer business operation tools over generic CRUD when a specific tool exists.',
+          'Destructive operations are preview-first; pass confirm=true only after explicit user approval.',
+          'Do not manually reload caches unless natural partial reload is proven stale or a concrete reload error requires it.',
+          'Never fabricate ids, field names, relation names, paths, package names, or permission scopes.',
+        ],
+      },
+      {
+        id: 'security-first',
+        rules: [
+          'Treat permission and owner/tenant scope as the first design step for any route, handler, hook, flow, extension, websocket, or data surface.',
+          'Route permission only lets authenticated users reach a route after RoleGuard; handlers, hooks, RLS, and scripts still enforce record ownership and tenant/project scope.',
+          'Do not expose unpublished fields, private relation facts, secret values, token hashes, stack traces, SQL, provider payloads, or generated passwords to user-facing clients.',
+        ],
+      },
+      {
+        id: 'shell-signals',
+        rules: [
+          'For app shell menu/account-panel notifications, decide the signal source before choosing count or dot.',
+          'Use a count only when the shell receives an exact or bounded count from a notification/summary source.',
+          'Use a dot when realtime only proves new attention exists.',
+          'Do not fetch destination domain lists such as messages, tickets, orders, or jobs solely to decorate the menu; the destination page owns domain fetching.',
+        ],
+      },
+    ],
     dynamicServerCode: [
       {
         id: 'secure-vs-trusted-repositories',