@enfyra/mcp-server 0.1.4 → 0.1.6

package/README.md

@@ -244,14 +244,14 @@ Use `get_enfyra_examples` from the MCP tool list when asking an LLM to generate
 - files and storage
 - Enfyra admin extensions
 
-Use `get_enfyra_required_knowledge` before asking an LLM to save dynamic server code or Enfyra extension code. It returns short required contracts plus acknowledgement keys that code-writing tools verify before saving.
+Use `get_enfyra_required_knowledge` before asking an LLM to mutate metadata, schema, routes, permissions, menus, packages, cache state, dynamic server code, or Enfyra extension code. It returns global rules plus acknowledgement keys that write tools verify before saving. Dynamic server code also requires the dynamic-code acknowledgement key, and extension code also requires the extension acknowledgement key.
 
 ## Runtime Safety
 
 The MCP server includes safety guards for LLM callers:
 
 - Generic record mutations validate fields against live metadata.
-- Code-writing tools require `get_enfyra_required_knowledge` acknowledgement before saving dynamic scripts or extension code. Discovery, validation, and preview tools remain available without the acknowledgement so agents can read and plan first.
+- Write tools require `get_enfyra_required_knowledge` acknowledgement before mutating Enfyra state. Discovery, validation, and preview tools remain available without the acknowledgement so agents can read and plan first. If the acknowledgement is missing, the tool error tells the caller to read `get_enfyra_required_knowledge` and pass the required key.
 - Script-backed records validate `sourceCode` through `/admin/script/validate` before saving.
 - `validate_dynamic_script` checks handler, hook, flow, websocket, GraphQL, and bootstrap script source without saving.
 - `validate_extension_code` checks Enfyra admin extension code through `/enfyra_extension/preview` without saving.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -1,7 +1,15 @@
+export const EXAMPLE_REASONING_GUIDE = [
+  'Examples are reasoning anchors, not templates to copy blindly. Preserve the platform contract, then adapt table names, route paths, relation names, fields, UI labels, and lifecycle triggers to the live app.',
+  'First identify the invariant being demonstrated: security boundary, query shape, shell registry contract, schema relation direction, runtime lifecycle, or browser proxy pattern.',
+  'Then identify what is illustrative: chat/order/report/cloud paths, sample field names, icons, labels, menu order, and specific notification kinds.',
+  'When a note says do not, treat it as a contract or safety boundary unless live metadata proves a different supported contract. When a note says for example, map the idea to the current domain instead of copying the literal names.',
+  'Before applying an example, inspect live metadata/routes/features and choose the closest supported tool. Use the smallest example that proves the decision, then compose with other examples only when the task truly needs multiple contracts.',
+];
+
 export const EXAMPLE_CATEGORIES = {
   'ssr-app-auth': {
     title: 'SSR app auth, OAuth, refresh, and proxy setup',
-    useWhen: 'Use when building Nuxt, Next, or another browser app that should rely on Enfyra cookies through an app-origin proxy.',
+    useWhen: 'Use when building Nuxt, Next, or another browser app that should rely on Enfyra cookies through an app-origin proxy; adapt the framework-specific wrapper while preserving the same-origin proxy and cookie boundary.',
     examples: [
       {
         name: 'Nuxt routeRules for REST and Socket.IO',
@@ -543,6 +551,7 @@ update_record({
         name: 'Create a chat conversation table',
         code: `create_table({
   name: "chat_conversation",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   columns: JSON.stringify([
     { name: "kind", type: "varchar", isNullable: false, defaultValue: "dm" },
     { name: "title", type: "varchar", isNullable: true },
@@ -550,6 +559,7 @@ update_record({
   ])
 })`,
         notes: [
+          'Chat is the illustrative domain here. For another domain, keep the same modeling question: what is the parent entity, what is stored on the parent, and what belongs on child rows?',
           'create_table creates the default route for /chat_conversation.',
           'Keep the latest message as a relation named lastMessage after chat_message exists; do not duplicate last message text/date columns.',
           'Do not create tables just to get custom paths; use create_route for that.',
@@ -559,6 +569,7 @@ update_record({
         name: 'Create relations directly to enfyra_user',
         code: `create_table({
   name: "chat_message",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   columns: JSON.stringify([
     { name: "text", type: "text", isNullable: false },
     { name: "persistStatus", type: "varchar", defaultValue: "persisted" }
@@ -584,6 +595,7 @@ update_record({
   ])
 })`,
         notes: [
+          'The relation names conversation and sender are examples of domain language; choose relation property names that match the entity model users reason about.',
           'Use enfyra_user as the user table.',
           'Use table ids for targetTable when already known; MCP can also resolve exact table names such as "enfyra_user" before schema mutation.',
           'Do not add inverse relations on enfyra_user unless a concrete user-to-record response, UI, or deep query will use it.',
@@ -597,6 +609,7 @@ update_record({
         code: `create_relation({
   sourceTableId: "chat_message",
   targetTableId: "chat_conversation",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   propertyName: "conversation",
   inversePropertyName: "messages",
   type: "many-to-one",
@@ -606,6 +619,7 @@ update_record({
         notes: [
           'Use inversePropertyName only when the parent table will actually expose, deep-load, count, or sort by that child collection.',
           'For example, conversation.messages is justified if a conversation detail response loads the latest message page with deep.messages limit/sort, or if a list sorts by _max(messages.createdAt).',
+          'Translate this to the current domain by asking whether the parent screen needs a child collection or aggregate; if not, keep the relation one-directional.',
           'If the app only filters chat_message by conversation.id, omit inversePropertyName and keep the schema one-directional.',
           'Before creating an inverse, inspect existing relations and state why the reverse traversal is needed.',
         ],
@@ -614,6 +628,7 @@ update_record({
         name: 'Add chat_conversation.lastMessage after chat_message exists',
         code: `update_table({
   tableId: "<chat_conversation_id>",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   relations: JSON.stringify([
     {
       propertyName: "createdBy",
@@ -640,6 +655,7 @@ update_record({
         name: 'Unread/read table with unique and indexes',
         code: `create_table({
   name: "chat_message_read",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   columns: JSON.stringify([
     { name: "isRead", type: "boolean", defaultValue: false },
     { name: "readAt", type: "datetime", isNullable: true }
@@ -666,6 +682,7 @@ update_record({
         code: `create_column({
   tableId: "<enfyra_user_table_id>",
   name: "emailVerifiedAt",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "datetime",
   isNullable: true,
   isPublished: true,
@@ -675,6 +692,7 @@ update_record({
 create_column({
   tableId: "<enfyra_user_table_id>",
   name: "emailVerificationStatus",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "varchar",
   isNullable: false,
   defaultValue: "pending",
@@ -685,6 +703,7 @@ create_column({
 create_column({
   tableId: "<integration_secret_table_id>",
   name: "value",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "text",
   isNullable: false,
   isPublished: false,
@@ -711,6 +730,7 @@ create_column({
 create_column({
   tableId: "<table_id>",
   name: "api_secret",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "text",
   isPublished: false,
   isEncrypted: true
@@ -754,6 +774,7 @@ create_column({
           'Use a conversation read pre-hook/RLS boundary so the route only returns conversations visible to @USER.',
           'lastMessage is a relation to chat_message; do not duplicate preview fields on chat_conversation.',
           'all: true tells MCP to send REST limit=0 and load all matching conversation rows.',
+          'This is a small bounded user inbox example. For larger inventories, prefer pagination even when RLS scopes the records.',
           'Do not fetch messages for every conversation on initial list load; load messages after selecting a conversation.',
         ],
       },
@@ -807,6 +828,7 @@ GET /enfyra/post?filter={"<primaryKeyFromMetadata>":{"_eq":123}}&limit=1`,
         notes: [
           'Use fields with dotted relation paths when you only need scalar fields from related records.',
           'This is enough for simple many-to-one or one-to-one relation display such as owner.email, customer.name, or lastMessage.text.',
+          'Treat order/customer as placeholders; the transferable idea is "show parent rows with a few scalar relation fields".',
           'Do not add deep when fields alone can express the relation data you need.',
         ],
       },
@@ -894,6 +916,7 @@ query_table({
         notes: [
           'Use _max(relation.field) for latest-child ordering, _min(relation.field) for earliest-child ordering, and _count(relation) for child-count ordering.',
           'Aggregate sort helpers only work on direct one-to-many or many-to-many list relations.',
+          'Support tickets and messages are illustrative. Apply this when a parent list must be ordered by child recency or child volume.',
           'The aggregate field must be a real published, non-encrypted scalar field on the related table for user-facing APIs.',
           'Do not use _max, _min, or _count on private relations or unpublished fields unless the endpoint intentionally exposes that fact.',
           'Do not use raw sort=-messages.createdAt for parent ordering; it is ambiguous and rejected.',
@@ -909,6 +932,7 @@ GET /enfyra/integrations?filter={"api_token":{"_eq":"plaintext-token"}}
 create_column({
   tableId: "<integrations_table_id>",
   name: "api_token_lookup_sha256",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   type: "varchar",
   isNullable: false,
   isPublished: false
@@ -944,6 +968,7 @@ const found = await #integrations.find({
   routeId: "<route_id>",
   method: "POST",
   scriptLanguage: "javascript",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
   sourceCode: \`const email = @BODY.email
 if (!email) @THROW400("Email is required")
@@ -952,7 +977,7 @@ return { ok: true, email }\`
 })`,
         notes: [
           'Use sourceCode, not logic. The server generates compiledCode.',
-          'Call get_enfyra_required_knowledge before saving dynamic code and pass dynamicCodeAckKey as knowledgeAckKey.',
+          'Call get_enfyra_required_knowledge before saving dynamic code, pass globalRulesAckKey as globalRulesAckKey, and pass dynamicCodeAckKey as knowledgeAckKey.',
           'Use method for one handler, or methods only when the same sourceCode should be saved for multiple methods.',
           'Do not pass name to enfyra_route_handler; one handler is identified by route + method.',
         ],
@@ -1006,6 +1031,7 @@ const scope = {
         name: 'Encrypted field table definition',
         code: `create_table({
   name: "integrations",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   columns: JSON.stringify([
     { name: "name", type: "varchar", isNullable: false },
     {
@@ -1033,6 +1059,7 @@ const scope = {
   name: "strip_email_verification_fields",
   methods: ["PATCH"],
   priority: -10,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
   code: \`delete @BODY.emailVerifiedAt
 delete @BODY.emailVerificationStatus
@@ -1051,6 +1078,7 @@ delete @BODY.emailVerificationSentAt\`
   name: "shape_display_title",
   methods: ["GET"],
   priority: 0,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
   code: \`if (@ERROR) {
   @LOGS("Request failed", @ERROR.message)
@@ -1510,7 +1538,7 @@ return saved`,
   },
   extensions: {
     title: 'Dynamic app extensions and menus',
-    useWhen: 'Use when adding custom UI pages to the Enfyra app.',
+    useWhen: 'Use when adding custom Enfyra admin UI pages, widgets, global shell integrations, menu entries, account-panel rows, or shell attention signals.',
     examples: [
       {
         name: 'Create or update HTTP method colors',
@@ -1544,6 +1572,7 @@ update_method({
   icon: "lucide:bar-chart-3",
   order: 20,
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   permission: JSON.stringify({
     or: [
       { route: "/reports", methods: ["GET"] },
@@ -1559,15 +1588,17 @@ ensure_page_extension({
   menuId: "<created-menu-id>",
   code: "<template><section class=\\"min-h-full w-full space-y-4\\"><div class=\\"grid gap-4 md:grid-cols-2 xl:grid-cols-3\\"><article class=\\"eapp-surface-card p-4\\"><div class=\\"flex items-start justify-between gap-3\\"><div><p class=\\"text-sm font-medium eapp-text-tertiary\\">Total</p><p class=\\"mt-2 text-2xl font-semibold eapp-text-primary\\">0</p></div><span class=\\"eapp-primary-soft eapp-icon-tile\\"><span class=\\"eapp-primary-text\\">◆</span></span></div><div class=\\"mt-3 h-1.5 overflow-hidden eapp-radius-pill eapp-surface-muted\\"><div class=\\"eapp-primary-solid h-full w-1/2\\"></div></div></article><article class=\\"eapp-primary-surface eapp-radius-panel border p-4\\"><p class=\\"text-sm font-semibold eapp-text-primary\\">Selected report</p><p class=\\"mt-1 text-sm eapp-text-tertiary\\">Only selected/current identity blocks use identity surface.</p></article></div></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); const { register: registerHeaderActions } = useHeaderActionRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'none', variant: 'minimal' }); registerHeaderActions([{ id: 'refresh-reports', label: 'Refresh', icon: 'lucide:refresh-cw', color: 'neutral', variant: 'outline', onClick: () => {}, order: 80 }])</script>",
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
+          'Reports is an illustrative page. Keep the shell/page contracts, but choose the real route, menu label, icon, permissions, and body layout from the operator workflow.',
           'Menu provides navigation; extension provides content.',
           'Use enfyra_menu.label, not title.',
           'Sensitive admin menus should include a permission condition at creation time.',
           'For page extensions, create the menu first with ensure_menu and pass its id to ensure_page_extension.',
           'Call get_extension_theme_contract before writing or reviewing page/widget/global extension UI.',
-          'Call get_enfyra_required_knowledge before saving extension code and pass extensionAckKey as extensionKnowledgeAckKey.',
+          'Call get_enfyra_required_knowledge before saving extension code, pass globalRulesAckKey as globalRulesAckKey, and pass extensionAckKey as extensionKnowledgeAckKey.',
           'Page extensions must register the app-shell PageHeader with usePageHeaderRegistry instead of rendering a custom top header.',
           'Use variant: "minimal" for operational pages unless a larger header is intentionally needed.',
           'Do not put ordinary KPI cards in PageHeader.stats; render metrics in the extension body.',
@@ -1633,6 +1664,7 @@ ensure_widget_extension({
   description: "Report status summary cards",
   code: reportStatusWidgetCode,
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })
 
@@ -1642,9 +1674,11 @@ ensure_page_extension({
   menuId: "<reports-menu-id>",
   code: "<template><section class=\\"min-h-full w-full space-y-4\\"><Widget :id=\\"<report-status-widget-id>\\" :total=\\"totalReports\\" :rows=\\"reportRows\\" :open-details=\\"openReportDetails\\" @refresh=\\"refresh\\" /><Widget :id=\\"<report-table-widget-id>\\" :rows=\\"reportRows\\" @refresh=\\"refresh\\" /></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'none', variant: 'minimal' }); const totalReports = ref(0); const reportRows = ref([]); function refresh() {} function openReportDetails(row) { navigateTo('/data/report?filter=' + encodeURIComponent(JSON.stringify({ id: { _eq: row.id } }))) }</script>",
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
+          'This shows composition mechanics. Replace reports/status/table with domain sections that are independently reusable or complex enough to deserve widgets.',
           'Use widgets for bulky or reusable sections such as operation panels, timelines, tables, sidebars, and status cards.',
           'Embed widgets by their numeric enfyra_extension id, not by extensionId/name.',
           'Props and listeners pass through the Widget wrapper. Widget defineProps values update reactively when the parent refs/computed values change.',
@@ -1735,11 +1769,13 @@ ensure_global_extension({
   description: "Registers the app-wide notification bell in the account panel",
   code: notificationBellCode,
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
           'Global extensions are mounted invisibly by Enfyra admin UI during layout init; do not create a menu and do not embed them with Widget.',
           'Use them for shell-level registrations, realtime listeners, notification counters, account panel rows, and background refresh bridges.',
+          'The notification center is only one possible shell integration. The transferable shape is invisible global extension -> shell registry -> cleanup on unmount.',
           'Use useMenuNotificationRegistry for sidebar menu counts/dots when notification state should be visible in the menu as well as the notification center.',
           'Choose value only when the signal source already owns an exact count. Omit value for a dot when realtime only proves that something new exists.',
           'Do not fetch the destination domain list just to decorate a menu. A mail page fetches mail; a support page fetches tickets; the shell should use notification or summary signals.',
@@ -1892,14 +1928,16 @@ ensure_global_extension({
   description: "Routes notification signals into account-panel and sidebar menu attention markers without polling destination lists",
   code: signalBridgeCode,
   isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
   extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
-          'Use this pattern when the shell should show attention but the destination page owns the expensive or domain-specific list fetch.',
+          'Use this reasoning pattern when the shell should show attention but the destination page owns the expensive or domain-specific list fetch.',
           'This example fetches only the notification source of truth, not the email, support, order, or job tables. Substitute your own notification or summary endpoint when available.',
           'Omitting value on registerMenuNotification renders a dot. That is the right promise when the shell knows "new work exists" but not an exact count.',
           'If a backend summary event already includes an exact unread count, use value for a count chip. If the event only says one record changed, use a dot and let the page fetch details.',
           'Map notification kinds to menu targets by product meaning, not by copying these paths. For example, approval_required could target /reviews, failed_job could target /operations/jobs, and quota_warning could target /billing.',
+          'Generalize the lifecycle: seed from a bounded signal source, react to realtime events, clear local attention when the user reaches the owning page, and avoid duplicating that page\'s data fetch.',
           'Clear local dot signals when the user enters the destination route or when the notification center marks the underlying notification as read.',
         ],
       },
@@ -1939,6 +1977,7 @@ register({
 </script>`,
         notes: [
           'Prefer this contract for shell/account-panel items: data fields for the row, optional contentComponent for the expanded body.',
+          'Notifications is illustrative. Account-panel rows can represent any account-scoped attention or shortcut, such as approvals, billing, deployments, or personal tasks.',
           'Use count for the primary visible badge value. badge remains supported as a legacy alias, but count is what the account trigger aggregates.',
           'Do not draw a custom full row with page-scale cards, hero headings, large whitespace, or nested buttons unless the shell contract cannot express the UI.',
           'Let the Enfyra admin UI handle the row button, icon container, label, microcopy, badge, chevron, hover state, spacing, and expanded wrapper.',
@@ -1993,6 +2032,7 @@ registerHeaderActions([
 </script>`,
         notes: [
           'Use PageHeader for the title strip; do not render a duplicate header inside extension body.',
+          'The exact actions are illustrative. Choose action prominence from user intent: navigation, secondary utility, primary mutation, or destructive confirmation.',
           'Use gradient: "none" for generated operational pages; hardcoded named gradients are decorative and should be explicit user intent.',
           'Back/navigation actions should be neutral ghost so they read as navigation, not a primary operation.',
           'Visible secondary operations should be neutral outline; soft is only for low-emphasis chrome actions.',
@@ -2032,7 +2072,7 @@ registerHeaderActions([
       },
       {
         name: 'Plan an admin dashboard as multiple pages',
-        code: `// Recommended menu shape for an operations surface:
+        code: `// Illustrative menu shape for an operations surface:
 ensure_menu({
   type: "Dropdown Menu",
   label: "Operations",
@@ -2058,6 +2098,7 @@ ensure_menu({
 // For admin record management, link to /data/<table>, e.g. /data/report, not public website paths.`,
         notes: [
           'Design the menu/page split before generating dashboard code.',
+          'Operations/jobs/orders/reports/settings are examples of separating mental models. Replace them with the real domains users navigate between.',
           'Permission-gate sensitive parent dropdown menus too, using any child page route or backing route that represents read access.',
           'Keep /dashboard as a summary and distribution page, not a detailed operations table.',
           'Use focused pages for operational domains.',
@@ -2089,6 +2130,7 @@ onMounted(() => fetchOrders())
         notes: [
           'Use app-provided composables in extensions.',
           'useApi does not auto-run; call execute() on mounted or through an action.',
+          'The /order path is illustrative; inspect routes and fetch the smallest data shape the extension needs.',
           'Keep extension UI focused; move backend logic into handlers/hooks when needed.',
         ],
       },
@@ -2144,7 +2186,8 @@ console.log(ok, requiredTerms.has('terms'), loaded, label, date)
         name: 'Install and use an app package in an extension',
         code: `install_package({
   name: "dayjs",
-  type: "App"
+  type: "App",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>"
 })
 
 // Then in extension code:
@@ -2215,6 +2258,7 @@ onMounted(() => Promise.all([flowStats.execute(), orderStats.execute()]))
           'Aggregate keys must be real fields or relations.',
           'Read results from response.meta.aggregate.',
           'Use top-level filter for time windows and cross-field conditions.',
+          'The flow/order pair is illustrative. Choose aggregates that answer the page question, such as failed work, pending approvals, unread support, quota pressure, or revenue.',
           'Only aggregate fields and relations that the dashboard is allowed to expose; aggregate values can reveal hidden data even when rows omit that field.',
           'sum/avg require numeric fields; amount_usd must be a real float/numeric SQL column, not metadata-only float over a varchar physical column.',
         ],
@@ -2234,6 +2278,7 @@ export function listExampleCategories() {
 export function getExamples(category) {
   if (!category) {
     return {
+      reasoningGuide: EXAMPLE_REASONING_GUIDE,
       categories: listExampleCategories(),
       hint: 'Call get_enfyra_examples with one category key to retrieve concrete examples for that area.',
     };
@@ -2249,6 +2294,7 @@ export function getExamples(category) {
 
   return {
     category,
+    reasoningGuide: EXAMPLE_REASONING_GUIDE,
     ...entry,
   };
 }

package/src/lib/mcp-instructions.js

@@ -29,7 +29,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Inspect narrowly. Use `inspect_table`, `inspect_route`, and `inspect_feature` for the table/route/feature being changed instead of loading broad metadata.',
     '- Load examples only when needed. Use `get_enfyra_examples` by category. Before extension UI, call `get_extension_theme_contract`; call `get_theme_class_reference` for exact eapp/Nuxt UI theme classes.',
     '- For server scripts, call `discover_script_contexts` before writing or reviewing handler/hook/flow/websocket/GraphQL logic.',
-    '- Before writing dynamic server or extension code, call `get_enfyra_required_knowledge` and pass the matching acknowledgement key into write tools.',
+    '- Before mutating metadata, schema, routes, permissions, menus, packages, cache state, dynamic code, or extension UI, call `get_enfyra_required_knowledge`, read the global rules, and pass `globalRulesAckKey` into write tools. Dynamic server code also requires `dynamicCodeAckKey`; extension code also requires `extensionAckKey`.',
     '- With non-root API tokens, call `get_permission_profile` before relying on admin helper tools or when debugging 403s. MCP admin helpers require ordinary route permissions for static admin routes such as `/admin/script/validate`, `/admin/test/run`, `/admin/flow/trigger/:id`, and `/admin/reload/*`.',
     '- Prefer the most specific business operation tool over raw metadata CRUD: `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `add_route_methods`, `public_route_methods`, `set_table_graphql`, guard/permission/rule tools, websocket tools, flow tools, and `ensure_page_extension`/menu tools.',
     '- Before saving standalone dynamic script or extension code, call `validate_dynamic_script` or `validate_extension_code` unless the chosen ensure/update tool already validates the code.',

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)),
@@ -1423,9 +1456,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);
@@ -1733,9 +1768,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 +1802,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 +1841,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 +1864,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 +1874,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       maxExecutions,
       isEnabled,
       description,
+      globalRulesAckKey,
     })),
   );
 
@@ -1870,6 +1913,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 +1935,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 +1955,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 +1974,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 +1993,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 +2012,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 +2031,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 +2050,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 +2069,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 +2088,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 +2108,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 +2126,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 +2144,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 +2162,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, 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',

package/src/lib/table-tools.js

@@ -4,6 +4,7 @@
 import { z } from 'zod';
 import { fetchAPI } from './fetch.js';
 import { jsonContent } from './response-format.js';
+import { assertGlobalRulesAck, globalRulesAckParam } from './required-knowledge.js';
 
 let schemaQueue = Promise.resolve();
 
@@ -308,6 +309,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
   const apiBase = ENFYRA_API_URL.replace(/\/$/, '');
 
   async function appendColumnToTable(args) {
+    assertGlobalRulesAck(args.globalRulesAckKey);
     return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, args.tableId);
     if (!tableData) {
@@ -330,6 +332,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
   }
 
   async function appendRelationToTable(args) {
+    assertGlobalRulesAck(args.globalRulesAckKey);
     return withSchemaQueue(async () => {
     assertNoForbiddenRelationKeys(args);
     const { sourceTableId, targetTableId, type, propertyName, inversePropertyName, mappedBy, isNullable, onDelete, description } = args;
@@ -359,7 +362,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     });
   }
 
-  async function removeColumnFromTable({ tableId, columnId, confirm }) {
+  async function removeColumnFromTable({ tableId, columnId, confirm, globalRulesAckKey }) {
     return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
     if (!tableData) {
@@ -385,6 +388,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         }, null, 2) }],
       };
     }
+    assertGlobalRulesAck(globalRulesAckKey);
 
     const columns = existingColumns
       .filter(col => String(getId(col)) !== String(columnId))
@@ -401,7 +405,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     });
   }
 
-  async function removeRelationFromTable({ tableId, relationId, confirm }) {
+  async function removeRelationFromTable({ tableId, relationId, confirm, globalRulesAckKey }) {
     return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
     if (!tableData) {
@@ -427,6 +431,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         }, null, 2) }],
       };
     }
+    assertGlobalRulesAck(globalRulesAckKey);
 
     const relations = existingRelations
       .filter(rel => String(getId(rel)) !== String(relationId))
@@ -458,6 +463,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     defaultValue: z.string().optional().describe('Default value as JSON string or backend-supported literal.'),
     description: z.string().optional().describe('Column description.'),
     options: z.string().optional().describe('Column options as JSON string (e.g., enum values).'),
+    globalRulesAckKey: globalRulesAckParam(z),
   };
 
   const relationCreateSchema = {
@@ -477,18 +483,21 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     targetColumn: z.never().optional().describe('Forbidden. Use propertyName only; Enfyra derives FK columns.'),
     junctionSourceColumn: z.never().optional().describe('Forbidden. Use relation property names only; Enfyra derives junction columns.'),
     junctionTargetColumn: z.never().optional().describe('Forbidden. Use relation property names only; Enfyra derives junction columns.'),
+    globalRulesAckKey: globalRulesAckParam(z),
   };
 
   const columnDeleteSchema = {
     tableId: z.string().describe('Table definition ID.'),
     columnId: z.string().describe('Column definition ID to delete.'),
     confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
+    globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
   };
 
   const relationDeleteSchema = {
     tableId: z.string().describe('Table definition ID (source table of the relation).'),
     relationId: z.string().describe('Relation definition ID to delete.'),
     confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
+    globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
   };
 
   // ─── READ ───
@@ -565,8 +574,10 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       relations: z.string().optional().describe('JSON array of relation definitions to create with the table in the same cascade call. Each relation: { targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete?, description? }. targetTable can be an id, {"id": <id>}, or an exact table name that MCP resolves to an id before mutation. Do not include physical FK/junction columns such as fkCol, foreignKeyColumn, sourceColumn, targetColumn, junctionSourceColumn, or junctionTargetColumn; Enfyra derives them and hides FK columns from app schema. Omit inversePropertyName unless a concrete response, UI, deep query, aggregate sort/count, or parent-to-child traversal needs the reverse field. Example only when parent posts are queried: [{"targetTable":2,"type":"many-to-one","propertyName":"author","inversePropertyName":"posts","isNullable":false,"onDelete":"CASCADE"}]'),
       indexes: z.string().optional().describe('JSON array of logical index field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Relation property names are allowed. Example: [["member","isRead","conversation"],["conversation","member","isRead"]]'),
       uniques: z.string().optional().describe('JSON array of logical unique field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Example: [["message","member"]]'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ name, description, isSingleRecord, columns: columnsJson, relations: relationsJson, indexes: indexesJson, uniques: uniquesJson }) => withSchemaQueue(async () => {
+    async ({ name, description, isSingleRecord, columns: columnsJson, relations: relationsJson, indexes: indexesJson, uniques: uniquesJson, globalRulesAckKey }) => withSchemaQueue(async () => {
+      assertGlobalRulesAck(globalRulesAckKey);
       const idColumn = { name: 'id', type: 'int', isPrimary: true, isGenerated: true, isNullable: false };
       const userColumns = parseJsonArrayParam('columns', columnsJson);
       const parsedRelations = parseJsonArrayParam('relations', relationsJson).map(normalizeRelationForTablePatch);
@@ -627,8 +638,10 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       graphqlEnabled: z.boolean().optional().describe('Enable or disable GraphQL for this table by syncing enfyra_graphql.isEnabled. GraphQL table data still requires Bearer auth; anonymous root or schema probes may return 200.'),
       indexes: z.string().optional().describe('Complete JSON array of logical index field groups to store on enfyra_table.indexes. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current indexes; pass [] to clear.'),
       uniques: z.string().optional().describe('Complete JSON array of logical unique field groups to store on enfyra_table.uniques. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current uniques; pass [] to clear.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ tableId, name, alias, description, isSingleRecord, graphqlEnabled, indexes: indexesJson, uniques: uniquesJson }) => withSchemaQueue(async () => {
+    async ({ tableId, name, alias, description, isSingleRecord, graphqlEnabled, indexes: indexesJson, uniques: uniquesJson, globalRulesAckKey }) => withSchemaQueue(async () => {
+      assertGlobalRulesAck(globalRulesAckKey);
       const body = {};
       if (name !== undefined) body.name = name;
       if (alias !== undefined) body.alias = alias;
@@ -657,8 +670,9 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     {
       tableId: z.string().describe('Table definition ID to delete.'),
       confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
+      globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
     },
-    async ({ tableId, confirm }) => withSchemaQueue(async () => {
+    async ({ tableId, confirm, globalRulesAckKey }) => withSchemaQueue(async () => {
       const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
       if (!confirm) {
         return {
@@ -673,6 +687,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
           }, null, 2) }],
         };
       }
+      assertGlobalRulesAck(globalRulesAckKey);
       const result = await fetchAPI(ENFYRA_API_URL, `/enfyra_table/${tableId}`, {
         method: 'DELETE',
       });
@@ -720,8 +735,10 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       defaultValue: z.string().optional().describe('New default value as JSON string.'),
       description: z.string().optional().describe('New description.'),
       options: z.string().optional().describe('New options as JSON string.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ tableId, columnId, name, type, isNullable, isPublished, isUpdatable, defaultValue, description, options }) => withSchemaQueue(async () => {
+    async ({ tableId, columnId, name, type, isNullable, isPublished, isUpdatable, defaultValue, description, options, globalRulesAckKey }) => withSchemaQueue(async () => {
+      assertGlobalRulesAck(globalRulesAckKey);
       const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
       if (!tableData) {
         return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };

package/src/mcp-server-entry.mjs

@@ -27,9 +27,11 @@ import {
   assertDynamicCodeKnowledgeAck,
   assertDynamicCodeKnowledgeAckIf,
   assertExtensionKnowledgeAckIf,
+  assertGlobalRulesAck,
   buildRequiredKnowledgePayload,
   dynamicCodeKnowledgeAckParam,
   extensionKnowledgeAckParam,
+  globalRulesAckParam,
 } from './lib/required-knowledge.js';
 import { validateMainTableRoutePath } from './lib/route-guards.js';
 import { installColumnarToolFormatter, jsonContent } from './lib/response-format.js';
@@ -1471,9 +1473,11 @@ server.tool('create_record', 'Create a new record in any route-backed table. The
   tableName: z.string().describe('Table name to insert into'),
   data: z.string().describe('Record data as JSON string'),
   queryParams: z.string().optional().describe('Optional query params as JSON object string, e.g. {"expired_at":"2026-09-20"}. Use for route contracts that intentionally keep workflow fields out of the validated body.'),
+  globalRulesAckKey: globalRulesAckParam(z),
   knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required only when data contains sourceCode. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
   extensionKnowledgeAckKey: extensionKnowledgeAckParam(z).optional().describe('Required only when tableName is enfyra_extension and data contains code. Use extensionAckKey from get_enfyra_required_knowledge.'),
-}, async ({ tableName, data, queryParams, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+}, async ({ tableName, data, queryParams, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   validateTableName(tableName);
   assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey });
   const prepared = await prepareGenericMutation(tableName, data);
@@ -1490,9 +1494,11 @@ server.tool('update_record', 'Update an existing record by ID using PATCH. The t
   id: z.string().describe('Record ID to update'),
   data: z.string().describe('Fields to update as JSON string'),
   queryParams: z.string().optional().describe('Optional query params as JSON object string for route contracts that intentionally keep workflow fields out of the validated body.'),
+  globalRulesAckKey: globalRulesAckParam(z),
   knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required only when data contains sourceCode. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
   extensionKnowledgeAckKey: extensionKnowledgeAckParam(z).optional().describe('Required only when tableName is enfyra_extension and data contains code. Use extensionAckKey from get_enfyra_required_knowledge.'),
-}, async ({ tableName, id, data, queryParams, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+}, async ({ tableName, id, data, queryParams, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   validateTableName(tableName);
   assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey });
   const prepared = await prepareGenericMutation(tableName, data);
@@ -1548,9 +1554,10 @@ server.tool(
     expectedSourceSha256: z.string().optional().describe('Optional SHA-256 from get_script_source; fails if source changed.'),
     scriptLanguage: z.string().optional().describe('Script language to save. Defaults to existing scriptLanguage or javascript.'),
     apply: z.boolean().optional().default(false).describe('false returns preview only; true validates and saves.'),
+    globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when apply=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required when apply=true. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
   },
-  async ({ tableName, id, oldText, newText, occurrence, expectedSourceSha256, scriptLanguage, apply, knowledgeAckKey }) => {
+  async ({ tableName, id, oldText, newText, occurrence, expectedSourceSha256, scriptLanguage, apply, globalRulesAckKey, knowledgeAckKey }) => {
     const { record, sourceField, sourceCode } = await fetchScriptRecord(tableName, id);
     if (sourceField !== 'sourceCode') {
       throw new Error(`patch_script_source only saves sourceCode records. Record uses "${sourceField}"; use update_record intentionally for this legacy field.`);
@@ -1581,6 +1588,7 @@ server.tool(
     if (!apply) {
       return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
     }
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const language = scriptLanguage || record.scriptLanguage || 'javascript';
     const prepared = await prepareGenericMutation(
@@ -1623,9 +1631,11 @@ server.tool(
     id: z.string().describe('Record ID to update'),
     sourceCode: z.string().describe('Editable script sourceCode. Pass the raw code string; do not JSON-escape it yourself.'),
     scriptLanguage: z.string().optional().default('javascript').describe('Script language, usually javascript or typescript'),
+    globalRulesAckKey: globalRulesAckParam(z),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ tableName, id, sourceCode, scriptLanguage, knowledgeAckKey }) => {
+  async ({ tableName, id, sourceCode, scriptLanguage, globalRulesAckKey, knowledgeAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     validateTableName(tableName);
     const prepared = await prepareGenericMutation(
@@ -1652,7 +1662,8 @@ server.tool('delete_record', 'Delete a record by ID', {
   id: z.string().describe('Record ID to delete'),
   queryParams: z.string().optional().describe('Optional query params as JSON object string for route-specific confirmation contracts.'),
   confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
-}, async ({ tableName, id, queryParams, confirm }) => {
+  globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
+}, async ({ tableName, id, queryParams, confirm, globalRulesAckKey }) => {
   validateTableName(tableName);
   const primaryKey = await getPrimaryFieldName(tableName);
   if (!confirm) {
@@ -1673,6 +1684,7 @@ server.tool('delete_record', 'Delete a record by ID', {
       next: 'Call delete_record again with confirm=true to delete this route-backed record.',
     }, null, 2) }] };
   }
+  assertGlobalRulesAck(globalRulesAckKey);
   const query = parseQueryParamsArg(queryParams);
   const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${id}`, query), { method: 'DELETE' });
   return { content: [{ type: 'text', text: JSON.stringify({
@@ -1713,8 +1725,10 @@ server.tool(
     buttonColor: z.string().describe('Badge background color as full hex, e.g. #dbeafe.'),
     textColor: z.string().describe('Badge text color as full hex, e.g. #1d4ed8.'),
     isSystem: z.boolean().optional().default(false).describe('Set true only for built-in/runtime-owned methods. Normal app methods should leave this false.'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ method, buttonColor, textColor, isSystem }) => {
+  async ({ method, buttonColor, textColor, isSystem, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     const normalizedMethod = normalizeMethodNameInput(method);
     const existing = await findMethodRecordByName(normalizedMethod);
     if (existing) {
@@ -1747,8 +1761,10 @@ server.tool(
     method: z.string().optional().describe('Existing method name to find, or new name when id is provided.'),
     buttonColor: z.string().optional().describe('Badge background color as full hex, e.g. #dbeafe.'),
     textColor: z.string().optional().describe('Badge text color as full hex, e.g. #1d4ed8.'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ id, method, buttonColor, textColor }) => {
+  async ({ id, method, buttonColor, textColor, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     let targetId = id;
     let existing = null;
     if (!targetId) {
@@ -1793,8 +1809,9 @@ server.tool(
     id: z.string().optional().describe('Method record id. If omitted, method is used to find the record.'),
     method: z.string().optional().describe('Method name to find when id is omitted.'),
     confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
+    globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
   },
-  async ({ id, method, confirm }) => {
+  async ({ id, method, confirm, globalRulesAckKey }) => {
     let targetId = id;
     let target = null;
     if (!targetId) {
@@ -1820,6 +1837,7 @@ server.tool(
         next: 'Call delete_method again with confirm=true to delete.',
       }, null, 2) }] };
     }
+    assertGlobalRulesAck(globalRulesAckKey);
     const result = await fetchAPI(ENFYRA_API_URL, `/enfyra_method/${encodeURIComponent(String(targetId))}`, { method: 'DELETE' });
     _methodMap = null;
     return { content: [{ type: 'text', text: JSON.stringify({
@@ -2449,8 +2467,10 @@ server.tool(
       .describe('Methods accessible WITHOUT auth token. Omit = all methods require auth.'),
     isEnabled: z.boolean().optional().default(true).describe('Enable route immediately'),
     description: z.string().optional().describe('Route description'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ path: routePath, mainTableId, methods, publicMethods, isEnabled, description }) => {
+  async ({ path: routePath, mainTableId, methods, publicMethods, isEnabled, description, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     const methodMap = await getMethodMap();
     const normalizedPath = normalizeRestPath(routePath);
 
@@ -2513,9 +2533,11 @@ server.tool(
     sourceCode: z.string().describe('Handler JavaScript sourceCode. Do not use logic; backend CRUD rejects logic.'),
     scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language for compiler. Default javascript.'),
     timeout: z.number().optional().describe('Timeout in ms (default: system DEFAULT_HANDLER_TIMEOUT, usually 30000)'),
+    globalRulesAckKey: globalRulesAckParam(z),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ routeId, method, methods, sourceCode, scriptLanguage, timeout, knowledgeAckKey }) => {
+  async ({ routeId, method, methods, sourceCode, scriptLanguage, timeout, globalRulesAckKey, knowledgeAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const methodNames = methods && methods.length > 0 ? methods : method ? [method] : [];
     if (methodNames.length === 0) throw new Error('Provide method or methods');
@@ -2576,9 +2598,11 @@ server.tool(
       .describe('Method names this hook applies to. Default: built-in REST methods GET, POST, PATCH, DELETE.'),
     priority: z.number().optional().default(0).describe('Execution order (lower = first)'),
     isEnabled: z.boolean().optional().default(true).describe('Enable hook immediately'),
+    globalRulesAckKey: globalRulesAckParam(z),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, knowledgeAckKey }) => {
+  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, globalRulesAckKey, knowledgeAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const methodMap = await getMethodMap();
     const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
@@ -2632,9 +2656,11 @@ server.tool(
       .describe('Method names this hook applies to. Default: built-in REST methods GET, POST, PATCH, DELETE.'),
     priority: z.number().optional().default(0).describe('Execution order (lower = first)'),
     isEnabled: z.boolean().optional().default(true).describe('Enable hook immediately'),
+    globalRulesAckKey: globalRulesAckParam(z),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, knowledgeAckKey }) => {
+  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, globalRulesAckKey, knowledgeAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const methodMap = await getMethodMap();
     const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
@@ -2751,8 +2777,10 @@ server.tool(
     mode: z.enum(['merge', 'replace']).optional().default('merge').describe('merge adds methods to an existing permission; replace overwrites methods on the matched permission.'),
     description: z.string().optional().describe('Admin note'),
     isEnabled: z.boolean().optional().default(true).describe('Enable the permission'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ path, routeId, methods, roleId, roleName, allowedUserIds, mode, description, isEnabled }) => {
+  async ({ path, routeId, methods, roleId, roleName, allowedUserIds, mode, description, isEnabled, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     if (!path && !routeId) throw new Error('Provide path or routeId.');
     if (path && routeId) throw new Error('Provide path or routeId, not both.');
     if (roleId && roleName) throw new Error('Provide roleId or roleName, not both.');
@@ -2852,22 +2880,34 @@ registerPlatformOperationTools(server, ENFYRA_API_URL);
 // CACHE & SYSTEM TOOLS
 // ============================================================================
 
-server.tool('reload_all', 'Reload all caches (metadata, routes, GraphQL)', {}, async () => {
+server.tool('reload_all', 'Reload all caches (metadata, routes, GraphQL)', {
+  globalRulesAckKey: globalRulesAckParam(z),
+}, async ({ globalRulesAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload', { method: 'POST' });
   return { content: [{ type: 'text', text: `System reloaded:\n${JSON.stringify(result, null, 2)}` }] };
 });
 
-server.tool('reload_metadata', 'Reload metadata cache only', {}, async () => {
+server.tool('reload_metadata', 'Reload metadata cache only', {
+  globalRulesAckKey: globalRulesAckParam(z),
+}, async ({ globalRulesAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/metadata', { method: 'POST' });
   return { content: [{ type: 'text', text: `Metadata reloaded:\n${JSON.stringify(result, null, 2)}` }] };
 });
 
-server.tool('reload_routes', 'Reload routes cache only', {}, async () => {
+server.tool('reload_routes', 'Reload routes cache only', {
+  globalRulesAckKey: globalRulesAckParam(z),
+}, async ({ globalRulesAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' });
   return { content: [{ type: 'text', text: `Routes reloaded:\n${JSON.stringify(result, null, 2)}` }] };
 });
 
-server.tool('reload_graphql', 'Reload GraphQL schema', {}, async () => {
+server.tool('reload_graphql', 'Reload GraphQL schema', {
+  globalRulesAckKey: globalRulesAckParam(z),
+}, async ({ globalRulesAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/graphql', { method: 'POST' });
   return { content: [{ type: 'text', text: `GraphQL reloaded:\n${JSON.stringify(result, null, 2)}` }] };
 });
@@ -3015,8 +3055,10 @@ server.tool(
     name: z.string().describe('Exact NPM package name (e.g., "node-ssh", "axios")'),
     type: z.enum(['Server', 'App']).default('Server').describe('Where to install: Server (handlers/hooks) or App (extensions)'),
     version: z.string().optional().describe('Specific version. If omitted, fetches latest from NPM.'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ name, type, version }) => {
+  async ({ name, type, version, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     // Step 1: Get package info from NPM if version not specified
     let pkgVersion = version;
     let pkgDescription = '';