@enfyra/mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -244,15 +244,20 @@ 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.
+
 ## 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.
 - 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.
+- Dynamic script guidance distinguishes secure repositories (`@REPOS.main`, `@REPOS.secure.<table>`) from trusted internal repositories (`@REPOS.<table>`), and tells agents not to return raw trusted records to users.
 - `compiledCode` is generated from `sourceCode` and may differ textually because macros are expanded; the MCP server never accepts hand-written `compiledCode`.
+- Long source/code values in read responses are written to `/tmp/enfyra-mcp-sources` and returned as length/hash/preview/tmpFile metadata so LLM callers can inspect full source from the file path without truncating tool output.
 - JSON responses include `compressionStats` with estimated token savings. Arrays of objects are converted to columnar form only when the compact shape is smaller than raw JSON.
 - Relation tools reject physical FK/junction names and resolve table ids from exact table names or aliases before schema mutation.
 - Generated code should use relation property names such as `conversation`, `sender`, and `member` instead of physical FK fields such as `conversationId`, `senderId`, or `memberId`.
@@ -295,7 +300,7 @@ Do not create custom login/logout/me routes that manually set Enfyra token cooki
 
 ## Tool Summary
 
-The MCP server exposes tools for metadata discovery, examples, query/CRUD, method management, route lifecycle, route access audit/grant, routes, handlers, hooks, tables, columns, relations, cache reloads, logs, users, roles, packages, menus, extensions, scripts, flows, websocket, files, and `get_enfyra_api_context`.
+The MCP server exposes tools for metadata discovery, required knowledge, examples, query/CRUD, method management, route lifecycle, route access audit/grant, routes, handlers, hooks, tables, columns, relations, cache reloads, logs, users, roles, packages, menus, extensions, scripts, flows, websocket, files, `get_enfyra_api_context`, and `get_enfyra_required_knowledge`.
 
 Routes have two separate controls. `isEnabled` controls runtime registration: disabled routes return `404`. Use `enable_route` and `disable_route` for this lifecycle. `publicMethods` controls anonymous access for enabled routes; use `public_route_methods` and `private_route_methods` for that access boundary.
 

package/package.json

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

package/src/lib/mcp-examples.js

@@ -894,7 +894,8 @@ 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.',
-          'The aggregate field must be a real non-encrypted scalar field on the related table.',
+          '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.',
           'deep.messages.sort only orders the loaded message rows inside each ticket, so keep parent sort and child pagination as separate concerns.',
         ],
@@ -943,6 +944,7 @@ const found = await #integrations.find({
   routeId: "<route_id>",
   method: "POST",
   scriptLanguage: "javascript",
+  knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
   sourceCode: \`const email = @BODY.email
 if (!email) @THROW400("Email is required")
 
@@ -950,6 +952,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.',
           '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.',
         ],
@@ -1030,6 +1033,7 @@ const scope = {
   name: "strip_email_verification_fields",
   methods: ["PATCH"],
   priority: -10,
+  knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
   code: \`delete @BODY.emailVerifiedAt
 delete @BODY.emailVerificationStatus
 delete @BODY.emailVerificationSentAt\`
@@ -1047,6 +1051,7 @@ delete @BODY.emailVerificationSentAt\`
   name: "shape_display_title",
   methods: ["GET"],
   priority: 0,
+  knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
   code: \`if (@ERROR) {
   @LOGS("Request failed", @ERROR.message)
   return
@@ -1320,7 +1325,7 @@ const socket = io("/chat", {
         code: `const conversationId = @BODY.conversationId
 if (!conversationId) @THROW400("conversationId is required")
 
-const membership = await @REPOS.chat_conversation_member.find({
+const membership = await @REPOS.secure.chat_conversation_member.find({
   filter: {
     conversation: { id: { _eq: conversationId } },
     member: { id: { _eq: @USER.id } }
@@ -1336,6 +1341,7 @@ if (!membership.data[0]) @THROW403("Not a conversation member")
           'Join conversation rooms, not member-id rooms.',
           'conversationId is a request/room identifier; DB filters still use the relation property conversation.',
           'Check membership server-side; do not trust the client.',
+          'Use @REPOS.secure.<table> for explicit table access in user-facing websocket scripts.',
         ],
       },
       {
@@ -1343,7 +1349,7 @@ if (!membership.data[0]) @THROW403("Not a conversation member")
         code: `const { conversationId, text, clientId } = @BODY
 if (!conversationId || !text) @THROW400("conversationId and text are required")
 
-const membership = await @REPOS.chat_conversation_member.find({
+const membership = await @REPOS.secure.chat_conversation_member.find({
   filter: {
     conversation: { id: { _eq: conversationId } },
     member: { id: { _eq: @USER.id } }
@@ -1352,7 +1358,7 @@ const membership = await @REPOS.chat_conversation_member.find({
 })
 if (!membership.data[0]) @THROW403("Not a conversation member")
 
-const created = await @REPOS.chat_message.create({
+const created = await @REPOS.secure.chat_message.create({
   data: {
     conversation: { id: conversationId },
     sender: { id: @USER.id },
@@ -1363,7 +1369,7 @@ const created = await @REPOS.chat_message.create({
 
 const message = created.data?.[0] ?? null
 if (message?.id) {
-  await @REPOS.chat_conversation.update({
+  await @REPOS.secure.chat_conversation.update({
     id: conversationId,
     data: { lastMessage: { id: message.id }, updatedAt: message.createdAt || new Date().toISOString() }
   })
@@ -1378,6 +1384,7 @@ return { ok: true, message }`,
           'Do not ask the client for senderId. The sender relation is derived from @USER.id.',
           'conversationId is accepted only as the room/business identifier; persistence uses relation properties conversation and sender, not physical FK fields.',
           'Event scripts should explicitly emit replies/broadcasts.',
+          'Use @REPOS.secure.<table> for explicit table access in user-facing websocket scripts; trusted @REPOS.<table> is only for internal/admin logic that will sanitize output.',
         ],
       },
     ],
@@ -1551,7 +1558,8 @@ ensure_page_extension({
   description: "Reports dashboard",
   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
+  isEnabled: true,
+  extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
           'Menu provides navigation; extension provides content.',
@@ -1559,6 +1567,7 @@ ensure_page_extension({
           '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.',
           '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.',
@@ -1623,7 +1632,8 @@ ensure_widget_extension({
   name: "ReportStatusWidget",
   description: "Report status summary cards",
   code: reportStatusWidgetCode,
-  isEnabled: true
+  isEnabled: true,
+  extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })
 
 // Read the created widget record id, then embed it from the page extension.
@@ -1631,7 +1641,8 @@ ensure_page_extension({
   name: "ReportsPage",
   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
+  isEnabled: true,
+  extensionKnowledgeAckKey: "<extensionAckKey from get_enfyra_required_knowledge>"
 })`,
         notes: [
           'Use widgets for bulky or reusable sections such as operation panels, timelines, tables, sidebars, and status cards.',
@@ -1707,7 +1718,8 @@ ensure_global_extension({
   name: "NotificationBellGlobal",
   description: "Registers the app-wide notification bell in the account panel",
   code: notificationBellCode,
-  isEnabled: true
+  isEnabled: true,
+  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.',
@@ -2030,6 +2042,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.',
+          '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.',
         ],
       },

package/src/lib/mcp-instructions.js

@@ -27,25 +27,30 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- For a quick target/base sanity check, call `get_enfyra_api_context`; do not call broad discovery just to confirm which instance this MCP is connected to.',
     '- Discover before deciding. For architecture/capability questions call `discover_enfyra_system`; for DB/pk/runtime/cache context call `discover_runtime_context`; for filters/deep/sort/relation query shape call `discover_query_capabilities`. Run broad discovery tools sequentially, not in parallel.',
     '- 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. Before generating schemas, app connection code, OAuth, Socket.IO, handlers/hooks, flows, files, guards, permissions, or extensions, call `get_enfyra_examples` with the matching category. Before extension UI work, call `get_extension_theme_contract` and follow the app-shell/theme/security contract. For the exact class name or Nuxt UI color mapping, call `get_theme_class_reference`; this is the authoritative theme & color contract and must be followed exactly - never use raw CSS variables, Tailwind palette accents, or concrete palettes like color="violet".',
+    '- 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.',
     '- 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` for step-by-step endpoint work; `create_api_endpoint` only when a one-shot endpoint operation is clearly safe; route tools such as `enable_route`, `disable_route`, `delete_route`, `add_route_methods`, `public_route_methods`, and `private_route_methods`; `set_table_graphql`; `ensure_guard`; permission/rule tools; websocket tools; flow tools such as `ensure_manual_flow`, `ensure_scheduled_flow`, `choose_flow_step_tool`, and fixed-type flow step tools; and extension tools such as `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension`.',
+    '- 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.',
     '- For existing script-backed records, use `trace_metadata_usage` then `get_script_source`; edit with `patch_script_source` or `update_script_source` so source is hash-checked and validated.',
     '- Validate behavior with `test_rest_endpoint`, `run_admin_test`, `test_flow_step`, or the route-specific tool before claiming a dynamic feature works.',
     '',
     '### Core Contracts',
-    '- Tool JSON responses use `responseFormat: "json+columnar-v1"`. Large arrays of objects may be encoded as `{ format: "columnar-v1", columns: [...], rows: [[...]], rowCount }` only when that is smaller than raw JSON; read each row value by matching `columns[index]` to `rows[n][index]`. Do not guess object keys inside `rows`. `compressionStats` estimates token savings and includes whether compression was applied; use it only when the user asks about savings.',
+    '- Tool JSON responses use `responseFormat: "json+columnar-v1"`. If rows are columnar, read values by matching `columns[index]` to `rows[n][index]`; do not guess row keys.',
     '- `query_table`, `get_all_routes`, and `get_all_tables` require explicit intent: pass `limit` for bounded reads or `all: true` for a complete list. Do not invent arbitrary limits such as 30 or 50.',
     '- Read tools are minimal by default. Pass explicit `fields`; use metadata inspection before guessing field/relation names. Field exclusion mode exists: `fields=-compiledCode`, and `fields=id,-compiledCode` still means all readable fields except `compiledCode`.',
     '- Mutations return ids/status by default. Re-read with `find_one_record` or `query_table` and explicit `fields` when the saved row matters.',
-    '- Dynamic repository reads use `filter`, not `where`: `@REPOS.table.find({ filter: {...} })`, `#table.find({ filter: {...} })`, and `exists(filter)`.',
+    '- Dynamic repository reads use `filter`, not `where`: `@REPOS.table.find({ filter: {...} })`, `@REPOS.secure.table.find({ filter: {...} })`, `#table.find({ filter: {...} })`, and `exists(filter)`.',
+    '- Dynamic repositories have two trust paths. Use secure `@REPOS.main` or `@REPOS.secure.<table>` for user-facing data. `@REPOS.<table>` is trusted/internal and can see hidden fields; never return raw trusted rows to users.',
+    '- Secure repository choice is not a substitute for authorization. Handlers and hooks still need route access, owner/tenant filters, and explicit checks before returning or mutating records.',
+    '- Filters, sort helpers, counts, and aggregates over unpublished fields/private relations are sensitive data surfaces; do not expose them in user-facing endpoints.',
     '- Use `enfyra_user` as the user table. Model record links as real relations using relation `propertyName` values, not physical FK fields like `userId`, `conversationId`, `senderId`, or `memberId` in generated DB code.',
     '- Relation design must stay minimal. Create the owning relation needed for writes/filters first; add `inversePropertyName` only when a concrete response, UI, deep query, aggregate sort/count, or parent-to-child traversal will use that reverse field. For schema work, explicitly review existing relations and mention which inverses are intentionally present or intentionally omitted.',
     '- Do not call internal/no-route system tables such as `enfyra_column` or `enfyra_session` through generic CRUD. Use table/column/relation tools and route-backed tables discovered from metadata.',
     '- Custom API paths use `api_endpoint_workflow` when a handler is needed and the model should follow returned nextSteps. Use lower-level `create_route` without `mainTableId` only when intentionally creating a route shell; `create_table` is only for new persisted data.',
     '- For canonical table reads and RLS, preserve client-controlled query shape: do not override `@QUERY.fields`, `@QUERY.deep`, `@QUERY.sort`, `@QUERY.limit`, `@QUERY.page`, `@QUERY.meta`, `@QUERY.aggregate`, or `debugMode`. Merge only security filters into `@QUERY.filter`.',
+    '- If a REST read returns a column or relation marked `isPublished=false`, including through dotted relation fields such as `fields=owner.secret` or equivalent `deep` projections, treat it as an Enfyra core support issue. Confirm the minimal repro with `test_rest_endpoint`, tell the user to send a Cloud/support ticket with the table, field path, and response shape, and do not present route-local pre-hooks or frontend hiding as the real fix.',
     '- Script source is `sourceCode`; `compiledCode` is generated and may differ textually because macros expand. Do not warn about source/compiled mismatch unless validation or runtime behavior proves the compiled artifact is stale.',
     '- For intentional user/domain errors in scripts use `@THROW400`-style helpers or `$ctx.$throw[...]`, not `throw new Error(...)`.',
     '- Destructive operations are preview-first. Do not pass `confirm=true` until the user explicitly approves.',

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

@@ -2,6 +2,13 @@ import { z } from 'zod';
 
 import { fetchAPI } from './fetch.js';
 import { validateScriptSourceIfPresent } from './mutation-guards.js';
+import {
+  assertDynamicCodeKnowledgeAck,
+  assertDynamicCodeKnowledgeAckIf,
+  assertExtensionKnowledgeAck,
+  dynamicCodeKnowledgeAckParam,
+  extensionKnowledgeAckParam,
+} from './required-knowledge.js';
 
 function unwrapData(result) {
   return Array.isArray(result?.data) ? result.data : [];
@@ -656,7 +663,9 @@ async function ensureExtension(apiUrl, {
   description,
   isEnabled = true,
   version = '1.0.0',
+  extensionKnowledgeAckKey,
 }) {
+  assertExtensionKnowledgeAck(extensionKnowledgeAckKey);
   if (type === 'page' && !menuId) {
     throw new Error('menuId is required for page extensions. Use ensure_menu first, then ensure_page_extension.');
   }
@@ -718,6 +727,7 @@ async function ensureFlowStep(apiUrl, {
   scriptLanguage,
   timeout,
   isEnabled,
+  knowledgeAckKey,
 }) {
   if (!flowName && !flowId) throw new Error('Provide flowName or flowId.');
   if (flowName && flowId) throw new Error('Provide flowName or flowId, not both.');
@@ -726,6 +736,7 @@ async function ensureFlowStep(apiUrl, {
     : await findRecord(apiUrl, 'enfyra_flow', { name: { _eq: flowName } }, 'id,_id,name');
   if (!flow) throw new Error(`Flow not found: ${flowId || flowName}`);
   const parsedConfig = parseJsonObjectArg('config', config, {});
+  assertDynamicCodeKnowledgeAckIf(Boolean(sourceCode && ['script', 'condition'].includes(type)), knowledgeAckKey);
   const validation = sourceCode && ['script', 'condition'].includes(type)
     ? await validateDynamicScript(apiUrl, sourceCode, scriptLanguage)
     : { validated: false, reason: 'no script validation required' };
@@ -971,7 +982,12 @@ async function resolveApiEndpointWorkflowState(apiUrl, opts) {
     nextSteps: blocked
       ? [{ tool: 'api_endpoint_workflow', input: { path: normalizedPath, method: methodName, overwrite: true }, reason: blocked.reason }]
       : firstRunnable
-        ? [{ tool: 'api_endpoint_workflow', input: { path: normalizedPath, method: methodName, apply: true }, stepId: firstRunnable.id }]
+        ? [{
+          tool: 'api_endpoint_workflow',
+          input: { path: normalizedPath, method: methodName, apply: true },
+          stepId: firstRunnable.id,
+          requiresKnowledgeAck: firstRunnable.id === 'save_handler' ? 'dynamicCodeAckKey from get_enfyra_required_knowledge' : undefined,
+        }]
         : [],
   };
 }
@@ -1020,6 +1036,7 @@ async function applyApiEndpointWorkflowStep(apiUrl, state, opts, stepId) {
   }
 
   if (selectedStep.id === 'save_handler') {
+    assertDynamicCodeKnowledgeAck(opts.knowledgeAckKey);
     if (!endpoint.routeId) throw new Error('Route must exist before saving handler.');
     const body = {
       sourceCode: opts.sourceCode,
@@ -1097,6 +1114,9 @@ async function runApiEndpointWorkflow(apiUrl, opts) {
   const operations = [];
   let completedEphemeralStepId = null;
   if (opts.apply || opts.applyAll) {
+    if (opts.applyAll && state.steps.some((item) => item.id === 'save_handler' && ['pending', 'waiting'].includes(item.status))) {
+      assertDynamicCodeKnowledgeAck(opts.knowledgeAckKey);
+    }
     const maxSteps = opts.applyAll ? 10 : 1;
     for (let i = 0; i < maxSteps; i += 1) {
       if (state.blocked || !state.firstRunnable) break;
@@ -1369,6 +1389,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.'),
+      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)),
   );
@@ -1392,8 +1413,10 @@ 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.'),
+      knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
     },
-    async ({ path, method, sourceCode, scriptLanguage, public: makePublic, description, timeout, overwrite, smokeTestQuery, smokeTestBody }) => {
+    async ({ path, method, sourceCode, scriptLanguage, public: makePublic, description, timeout, overwrite, smokeTestQuery, smokeTestBody, knowledgeAckKey }) => {
+      assertDynamicCodeKnowledgeAck(knowledgeAckKey);
       const normalizedPath = normalizeRestPath(path);
       const methodName = normalizeMethodName(method);
       const { methodMap, methodIdNameMap } = await getMethodContext(ENFYRA_API_URL);
@@ -1700,8 +1723,10 @@ 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.'),
+      knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required when sourceCode is provided. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
     },
-    async ({ path, sourceCode, scriptLanguage, isEnabled, description }) => {
+    async ({ path, sourceCode, scriptLanguage, isEnabled, description, knowledgeAckKey }) => {
+      assertDynamicCodeKnowledgeAckIf(sourceCode !== undefined, knowledgeAckKey);
       const normalizedPath = normalizeRestPath(path);
       const validation = sourceCode === undefined
         ? { validated: false, reason: 'no sourceCode' }
@@ -1730,8 +1755,10 @@ 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.'),
+      knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
     },
-    async ({ gatewayPath, gatewayId, eventName, sourceCode, scriptLanguage, isEnabled, description }) => {
+    async ({ gatewayPath, gatewayId, eventName, sourceCode, scriptLanguage, isEnabled, description, knowledgeAckKey }) => {
+      assertDynamicCodeKnowledgeAck(knowledgeAckKey);
       if (!gatewayPath && !gatewayId) throw new Error('Provide gatewayPath or gatewayId.');
       if (gatewayPath && gatewayId) throw new Error('Provide gatewayPath or gatewayId, not both.');
       const gateway = gatewayId
@@ -1833,6 +1860,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.'),
+      knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -1853,6 +1881,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.'),
+      knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
     },
     async (input) => jsonText(await ensureFlowStep(ENFYRA_API_URL, {
       ...input,
@@ -2033,6 +2062,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.'),
+      extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
     },
     async (input) => jsonText({
       action: 'page_extension_ensured',
@@ -2049,6 +2079,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.'),
+      extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
     },
     async (input) => jsonText({
       action: 'global_extension_ensured',
@@ -2065,6 +2096,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.'),
+      extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
     },
     async (input) => jsonText({
       action: 'widget_extension_ensured',

package/src/lib/required-knowledge.js

@@ -0,0 +1,116 @@
+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';
+
+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.');
+}
+
+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 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.');
+  }
+}
+
+export function assertDynamicCodeKnowledgeAckIf(condition, key) {
+  if (condition) assertDynamicCodeKnowledgeAck(key);
+}
+
+export function assertExtensionKnowledgeAck(key) {
+  if (key !== EXTENSION_KNOWLEDGE_ACK_KEY) {
+    throw new Error('Missing or invalid extension knowledge acknowledgement. Call get_enfyra_required_knowledge, read the extension/theme contracts, then pass extensionAckKey as extensionKnowledgeAckKey.');
+  }
+}
+
+export function assertExtensionKnowledgeAckIf(condition, key) {
+  if (condition) assertExtensionKnowledgeAck(key);
+}
+
+export function buildRequiredKnowledgePayload() {
+  return {
+    version: REQUIRED_KNOWLEDGE_VERSION,
+    purpose: 'Read this before generating or saving Enfyra dynamic server code through MCP.',
+    dynamicCodeAckKey: DYNAMIC_CODE_KNOWLEDGE_ACK_KEY,
+    extensionAckKey: EXTENSION_KNOWLEDGE_ACK_KEY,
+    usage: [
+      '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.',
+    ],
+    dynamicServerCode: [
+      {
+        id: 'secure-vs-trusted-repositories',
+        rules: [
+          '@REPOS.main is the secure repository for the current route main table and preserves normal route query behavior.',
+          '@REPOS.secure.<table> is the secure explicit-table repository. Use it for public/user-facing custom handlers, hooks, websocket scripts, flows that return data, and third-party app integrations.',
+          '@REPOS.<table> is the trusted internal repository. It may read/write hidden fields and is only for server-owned maintenance/admin logic that intentionally needs that access.',
+          'Never return raw trusted-repository records to users. Project or sanitize output before returning it.',
+        ],
+      },
+      {
+        id: 'authorization-is-separate',
+        rules: [
+          'Secure repository selection does not prove the user is allowed to access a record.',
+          'Handlers and hooks still need route access, owner/tenant filters, membership checks, and explicit mutation authorization.',
+          'For canonical table reads and RLS, merge security filters into @QUERY.filter and preserve @QUERY.fields, @QUERY.deep, @QUERY.sort, @QUERY.limit, @QUERY.page, @QUERY.meta, @QUERY.aggregate, and debugMode.',
+        ],
+      },
+      {
+        id: 'hidden-field-query-surfaces',
+        rules: [
+          'Unpublished fields and private relations are sensitive even when the field is not selected.',
+          'Do not expose filter predicate-oracle behavior over hidden fields in user-facing endpoints.',
+          'Do not expose aggregate, _max, _min, _count, sort helpers, or counts over unpublished fields/private relations unless the endpoint intentionally exposes that fact.',
+          'If a normal REST read returns an isPublished=false field through fields/deep/dotted projection, treat it as an Enfyra core bug and verify the minimal REST repro.',
+        ],
+      },
+      {
+        id: 'dynamic-script-shape',
+        rules: [
+          'Use sourceCode and scriptLanguage; never send compiledCode.',
+          'Prefer macros such as @BODY, @QUERY, @PARAMS, @USER, @REQ, @RES, @REPOS, @HELPERS, @STORAGE, @SOCKET, and @THROW* when available.',
+          'Repository reads use filter, not where.',
+          'Create/update repository calls return collection-shaped data arrays; read result.data?.[0] for a single row.',
+        ],
+      },
+    ],
+    extensions: [
+      {
+        id: 'theme-contract-first',
+        rules: [
+          'Call get_extension_theme_contract before writing or reviewing page, widget, or global extension UI.',
+          'Call get_theme_class_reference when an exact eapp-* class or Nuxt UI color mapping is needed.',
+          'Use eapp-surface-*, eapp-text-*, eapp-divide-y, and eapp-divider for neutral app-shell surfaces.',
+          'Use eapp-primary-* or Nuxt UI primary only for runtime-primary identity/accent intent controlled by the app color picker.',
+          'Use semantic state colors only for true status/error/warning/success/info indicators, not for large KPI/list containers.',
+          'Do not use raw CSS variable utilities such as text-[var(...)], bg-[var(...)], or border-[var(...)] when class tokens exist.',
+          'Do not hard-code concrete palettes such as color="violet" or Tailwind palette accents for themeable UI.',
+        ],
+      },
+      {
+        id: 'extension-shell-boundary',
+        rules: [
+          'Extension roots render inside the Enfyra admin app shell. Do not add root-level page padding such as p-4 sm:p-6 xl:p-8.',
+          'Page extensions should be full-bleed by default and responsive from the first version.',
+          'Do not wrap whole pages in decorative cards; use cards only for repeated items, modals, or genuinely framed tools.',
+          'Use NuxtLink or Nuxt UI components with :to for visible navigation links; reserve navigateTo for imperative side effects.',
+          'Admin extension links for record management should point to /data/<table>, not public website paths stored on records.',
+        ],
+      },
+      {
+        id: 'extension-runtime-contract',
+        rules: [
+          'Save extensions as enfyra_extension Vue SFC records; no static import statements in extension code.',
+          'Load app packages with getPackages(["package-name"]) inside extension runtime code.',
+          'Prefer FormEditor/FormEditorLazy for direct table-backed forms when the form maps to metadata fields.',
+          'For long admin setup workflows, open CommonDrawer immediately and show loading/error/content inside it.',
+          'Use Widget with numeric enfyra_extension widget ids; pass safe reactive props/events and keep page-level mutation ownership in the page unless the widget intentionally owns the workflow.',
+        ],
+      },
+    ],
+  };
+}

package/src/lib/source-artifacts.js

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const DEFAULT_PREVIEW_CHARS = 1200;
+const DEFAULT_INLINE_LIMIT = 1400;
+const SOURCE_FIELD_NAMES = new Set([
+  'sourceCode',
+  'code',
+  'compiledCode',
+  'handlerScript',
+  'connectionHandlerScript',
+]);
+
+function sha256(value) {
+  return createHash('sha256').update(String(value), 'utf8').digest('hex');
+}
+
+function safePart(value) {
+  const source = String(value || 'source').trim();
+  return source.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'source';
+}
+
+function extensionForField(fieldName) {
+  if (fieldName === 'code') return '.vue';
+  return '.js';
+}
+
+export function writeSourceArtifact({ tableName, id, fieldName, source }) {
+  const hash = sha256(source);
+  const dir = join(tmpdir(), 'enfyra-mcp-sources');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const fileName = [
+    safePart(tableName),
+    safePart(id),
+    safePart(fieldName),
+    hash.slice(0, 12),
+  ].join('-') + extensionForField(fieldName);
+  const path = join(dir, fileName);
+  writeFileSync(path, source, { mode: 0o600 });
+  return {
+    tmpFile: path,
+    length: source.length,
+    sha256: hash,
+    preview: source.length > DEFAULT_PREVIEW_CHARS
+      ? `${source.slice(0, DEFAULT_PREVIEW_CHARS)}...`
+      : source,
+  };
+}
+
+export function compactSourceField({ tableName, id, fieldName, source, alwaysWrite = false }) {
+  if (typeof source !== 'string') return source;
+  if (!alwaysWrite && source.length <= DEFAULT_INLINE_LIMIT) return source;
+  return writeSourceArtifact({ tableName, id, fieldName, source });
+}
+
+export function compactSourceFields(value, { tableName, idField = 'id', alwaysWrite = false } = {}) {
+  if (Array.isArray(value)) {
+    return value.map((item) => compactSourceFields(item, { tableName, idField, alwaysWrite }));
+  }
+  if (!value || typeof value !== 'object') return value;
+
+  const recordId = value[idField] ?? value._id ?? value.id ?? 'record';
+  const out = {};
+  for (const [key, fieldValue] of Object.entries(value)) {
+    if (SOURCE_FIELD_NAMES.has(key) && typeof fieldValue === 'string') {
+      out[key] = compactSourceField({
+        tableName,
+        id: recordId,
+        fieldName: key,
+        source: fieldValue,
+        alwaysWrite,
+      });
+    } else if (fieldValue && typeof fieldValue === 'object') {
+      out[key] = compactSourceFields(fieldValue, { tableName, idField, alwaysWrite });
+    } else {
+      out[key] = fieldValue;
+    }
+  }
+  return out;
+}

package/src/mcp-server-entry.mjs

@@ -22,9 +22,18 @@ import { buildMcpServerInstructions, buildGraphqlUrls } from './lib/mcp-instruct
 import { getExamples, listExampleCategories } from './lib/mcp-examples.js';
 import { registerTableTools } from './lib/table-tools.js';
 import { registerPlatformOperationTools } from './lib/platform-operation-tools.js';
-import { prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
+import { parseRecordData, prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
+import {
+  assertDynamicCodeKnowledgeAck,
+  assertDynamicCodeKnowledgeAckIf,
+  assertExtensionKnowledgeAckIf,
+  buildRequiredKnowledgePayload,
+  dynamicCodeKnowledgeAckParam,
+  extensionKnowledgeAckParam,
+} from './lib/required-knowledge.js';
 import { validateMainTableRoutePath } from './lib/route-guards.js';
 import { installColumnarToolFormatter, jsonContent } from './lib/response-format.js';
+import { compactSourceFields, writeSourceArtifact } from './lib/source-artifacts.js';
 import {
   findRoutePermission,
   mergeMethodNames,
@@ -208,6 +217,7 @@ const SCRIPT_BACKED_TABLES = [
   'enfyra_graphql',
   'enfyra_bootstrap_script',
 ];
+const SCRIPT_BACKED_TABLE_SET = new Set(SCRIPT_BACKED_TABLES);
 
 const SCRIPT_SOURCE_FIELDS = [
   'sourceCode',
@@ -596,6 +606,12 @@ async function prepareGenericMutation(tableName, data) {
   });
 }
 
+function assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey }) {
+  const payload = parseRecordData(data);
+  assertDynamicCodeKnowledgeAckIf(SCRIPT_BACKED_TABLE_SET.has(tableName) && typeof payload.sourceCode === 'string', knowledgeAckKey);
+  assertExtensionKnowledgeAckIf(tableName === 'enfyra_extension' && typeof payload.code === 'string', extensionKnowledgeAckKey);
+}
+
 function parseQueryParamsArg(queryParams) {
   const parsed = parseJsonArg(queryParams, {});
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
@@ -775,6 +791,16 @@ installColumnarToolFormatter(server);
 // METADATA TOOLS
 // ============================================================================
 
+server.tool(
+  'get_enfyra_required_knowledge',
+  [
+    'Return required Enfyra knowledge and acknowledgement keys for MCP code-writing tools.',
+    'Call this before creating or updating dynamic server code or Enfyra extension code. Read the returned contracts and pass the matching ack key into write tools.',
+  ].join(' '),
+  {},
+  async () => jsonContent(buildRequiredKnowledgePayload()),
+);
+
 server.tool('get_all_metadata', 'Get concise metadata summary for all tables. Use get_table_metadata or inspect_table for detail.', {
   includeFull: z.boolean().optional().default(false).describe('Return full raw metadata. Default false to keep MCP context small.'),
   search: z.string().optional().describe('Optional table-name/alias substring filter.'),
@@ -1051,6 +1077,7 @@ server.tool(
         deep: 'Nested relation fetch object keyed by relation propertyName.',
       },
       countPattern: 'For counts, query only fields=id with limit=1 and request meta. Use meta=totalCount without a filter, or meta=filterCount when a filter is supplied. MCP count_records wraps this pattern.',
+      security: 'Filters, sorts, counts, and aggregate values can leak information even when a field is not selected. In generated public/user-facing APIs, do not filter, sort, count, or aggregate unpublished fields or private relations unless the endpoint intentionally exposes that fact.',
       deep: {
         shape: '{ [relationName]: { fields?, filter?, sort?, limit?, page?, deep? } }',
         rules: [
@@ -1180,7 +1207,7 @@ server.tool(
         },
         handler: {
           runs: 'Main route logic, or canonical CRUD if no handler overrides.',
-          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REQ', '@RES when response streaming is available', '@UPLOADED_FILE for multipart request file metadata', '@REPOS.main', '@REPOS.<table>', '@CACHE', '@HELPERS', '@FETCH', '@STORAGE', '@PKGS', '@SOCKET global emit helpers/roomSize', '@TRIGGER'],
+          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REQ', '@RES when response streaming is available', '@UPLOADED_FILE for multipart request file metadata', '@REPOS.main secure route main table repo', '@REPOS.secure.<table> secure explicit table repo', '@REPOS.<table> trusted internal table repo', '@CACHE', '@HELPERS', '@FETCH', '@STORAGE', '@PKGS', '@SOCKET global emit helpers/roomSize', '@TRIGGER'],
           queryContract: 'When a handler wraps a canonical table read, pass through client fields/deep/sort/page/limit/meta/aggregate/debugMode unless the route is a clearly custom summary or workflow endpoint.',
           returnBehavior: 'Return value becomes response body unless post-hook changes it.',
         },
@@ -1217,7 +1244,9 @@ server.tool(
       },
       helpers: {
         repos: {
-          scopes: '$repos.main is the canonical repository for the route main table and preserves normal route query behavior. $repos.<table> is an explicit internal repository for table-specific logic. Do not generate $repos.secure.<table>; current runtime does not expose table methods there.',
+          scopes: '$repos.main is the secure repository for the route main table and preserves normal route query behavior. $repos.secure.<table> is the secure repository for explicit table access in public/user-facing custom handlers, hooks, websocket scripts, flows that return data, and third-party app integrations. $repos.<table> is a trusted internal repository for server-owned maintenance/admin logic that intentionally needs hidden fields; never return raw trusted-repo records to users.',
+          security: 'Secure repos enforce the normal field visibility/projection path, including unpublished columns and relations. Trusted repos bypass that exposure boundary; if trusted access is necessary, project or sanitize the result before returning it. Authorization is still required in either path: enforce route access plus owner/tenant filters or membership checks.',
+          sensitiveQuerySurface: 'Filters, sort helpers, counts, and aggregate values on unpublished fields or private relations can leak information even when the value is not selected. Do not expose aggregate, _max, _min, _count, or predicate-oracle behavior over hidden fields in generated user-facing endpoints.',
           mutationReturnShape: '$repos.<table>.create({ data }) and $repos.<table>.update({ id, data }) return a collection-shaped result: { data: [...], count? }. data is always an array for create/update, even for one created/updated record. If a script needs the single record object, it must read result.data[0] or result.data?.[0] ?? null.',
           preferredExample: 'const result = await @REPOS.main.create({ data: @BODY }); const record = result.data?.[0] ?? null; return record;',
           wrongSingleRecordAccess: 'Do not use result.data.id, do not return result.data when one object is expected, and do not assume create/update returns the bare row object.',
@@ -1288,7 +1317,7 @@ server.tool('query_table', 'Query any route-backed table. Response is minimal un
   fields: z.array(z.string()).optional().describe('Fields to select. If omitted, MCP selects only the table primary key to avoid oversized responses.'),
   meta: z.string().optional().describe('Optional REST meta request, e.g. "totalCount", "filterCount", or aggregate modes supported by the route. Use count_records for simple counts.'),
   deep: z.string().optional().describe('Optional deep relation fetch object as JSON string. Keys must be relation propertyName values.'),
-  aggregate: z.string().optional().describe('Optional aggregate object as JSON string, keyed by real fields/relations. Results are returned in response.meta.aggregate when supported.'),
+  aggregate: z.string().optional().describe('Optional aggregate object as JSON string, keyed by real fields/relations. Results are returned in response.meta.aggregate when supported. Do not request aggregates over hidden fields/private relations in user-facing APIs.'),
 }, async ({ tableName, filter, sort, page, limit, all, fields, meta, deep, aggregate }) => {
   if (!all && limit === undefined) {
     throw new Error('query_table requires either limit or all=true. Do not rely on implicit default page sizes.');
@@ -1329,7 +1358,7 @@ server.tool('query_table', 'Query any route-backed table. Response is minimal un
     },
     minimalDefaultApplied: !(fields && fields.length > 0),
     meta: result?.meta,
-    data: result?.data || [],
+    data: compactSourceFields(result?.data || [], { tableName }),
     detailHint: fields && fields.length > 0
       ? undefined
       : 'Only the primary key was returned because fields was omitted. Re-run query_table with explicit fields for details, or use inspect_table to find valid field names.',
@@ -1410,7 +1439,7 @@ server.tool(
         tableName,
         primaryKey,
         fields: selectedFields,
-        data: one,
+        data: compactSourceFields(one, { tableName }),
         detailHint: fields && fields.length > 0 ? undefined : 'Only the primary key was returned. Pass fields for details.',
       }, null, 2) }] };
     }
@@ -1428,7 +1457,7 @@ server.tool(
     return { content: [{ type: 'text', text: JSON.stringify({
       tableName,
       fields: selectedFields,
-      data: result.data?.[0] || null,
+      data: compactSourceFields(result.data?.[0] || null, { tableName }),
       detailHint: fields && fields.length > 0 ? undefined : 'Only the primary key was returned. Pass fields for details.',
     }, null, 2) }] };
   },
@@ -1442,8 +1471,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.'),
-}, async ({ tableName, data, queryParams }) => {
+  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 }) => {
   validateTableName(tableName);
+  assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey });
   const prepared = await prepareGenericMutation(tableName, data);
   const query = parseQueryParamsArg(queryParams);
   const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}`, query), { method: 'POST', body: JSON.stringify(prepared.payload) });
@@ -1458,8 +1490,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.'),
-}, async ({ tableName, id, data, queryParams }) => {
+  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 }) => {
   validateTableName(tableName);
+  assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey });
   const prepared = await prepareGenericMutation(tableName, data);
   const query = parseQueryParamsArg(queryParams);
   const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${id}`, query), { method: 'PATCH', body: JSON.stringify(prepared.payload) });
@@ -1481,12 +1516,14 @@ server.tool(
   },
   async ({ tableName, id }) => {
     const { primaryKey, record, sourceField, sourceCode } = await fetchScriptRecord(tableName, id);
+    const sourceArtifact = writeSourceArtifact({ tableName, id, fieldName: sourceField, source: sourceCode });
     return { content: [{ type: 'text', text: JSON.stringify({
       tableName,
       id,
       primaryKey,
       sourceField,
-      sourceCode,
+      sourceFile: sourceArtifact.tmpFile,
+      sourcePreview: sourceArtifact.preview,
       sourceLength: sourceCode.length,
       sourceSha256: sha256(sourceCode),
       scriptLanguage: record.scriptLanguage || record.language || null,
@@ -1511,8 +1548,9 @@ 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.'),
+    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 }) => {
+  async ({ tableName, id, oldText, newText, occurrence, expectedSourceSha256, scriptLanguage, apply, 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.`);
@@ -1543,6 +1581,7 @@ server.tool(
     if (!apply) {
       return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
     }
+    assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const language = scriptLanguage || record.scriptLanguage || 'javascript';
     const prepared = await prepareGenericMutation(
       tableName,
@@ -1584,8 +1623,10 @@ 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'),
+    knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ tableName, id, sourceCode, scriptLanguage }) => {
+  async ({ tableName, id, sourceCode, scriptLanguage, knowledgeAckKey }) => {
+    assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     validateTableName(tableName);
     const prepared = await prepareGenericMutation(
       tableName,
@@ -2472,8 +2513,10 @@ 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)'),
+    knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ routeId, method, methods, sourceCode, scriptLanguage, timeout }) => {
+  async ({ routeId, method, methods, sourceCode, scriptLanguage, timeout, knowledgeAckKey }) => {
+    assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const methodNames = methods && methods.length > 0 ? methods : method ? [method] : [];
     if (methodNames.length === 0) throw new Error('Provide method or methods');
     const methodMap = await getMethodMap();
@@ -2533,8 +2576,10 @@ 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'),
+    knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled }) => {
+  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, knowledgeAckKey }) => {
+    assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const methodMap = await getMethodMap();
     const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
     const scriptValidation = await validateScriptSourceIfPresent(fetchAPI, ENFYRA_API_URL, 'enfyra_pre_hook', {
@@ -2587,8 +2632,10 @@ 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'),
+    knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled }) => {
+  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, knowledgeAckKey }) => {
+    assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const methodMap = await getMethodMap();
     const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
     const scriptValidation = await validateScriptSourceIfPresent(fetchAPI, ENFYRA_API_URL, 'enfyra_post_hook', {