@enfyra/mcp-server 0.0.123 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # Enfyra MCP Server
 
-Manage Enfyra instances from MCP-compatible coding tools such as **Codex**, **Claude Code**, **Cursor**, MCP Inspector, and other STDIO MCP hosts.
+Manage Enfyra instances from MCP-compatible coding tools such as **Codex**, **Claude Code**, **Cursor**, **VS Code / GitHub Copilot**, **Google Antigravity**, MCP Inspector, and other STDIO MCP hosts.
 
 This package is the MCP bridge only. Assistant rules, schema behavior, dynamic script guidance, and examples are served through the MCP server itself from `src/lib/mcp-instructions.js`, `src/lib/mcp-examples.js`, and tool descriptions in `src/mcp-server-entry.mjs`.
 
@@ -12,7 +12,7 @@ From your project root:
 npx @enfyra/mcp-server config
 ```
 
-The config command writes project config for Codex, Claude Code, and Cursor. It preserves other MCP servers and replaces only the `enfyra` entry.
+The config command writes project config for Codex, Claude Code, Cursor, VS Code / GitHub Copilot, and Google Antigravity. It preserves other MCP servers and replaces only the `enfyra` entry.
 
 Interactive setup asks for your Enfyra app/admin URL, then guides you to the token page when needed and asks for `ENFYRA_API_TOKEN`.
 
@@ -25,6 +25,8 @@ npx @enfyra/mcp-server config --yes \
 # One or more clients
 npx @enfyra/mcp-server config --codex
 npx @enfyra/mcp-server config --cursor --claude-code
+npx @enfyra/mcp-server config --vscode
+npx @enfyra/mcp-server config --antigravity
 ```
 
 Equivalent in this repo:
@@ -40,7 +42,9 @@ yarn mcp:config
 | Codex | `npx @enfyra/mcp-server config --codex` | `.codex/config.toml` |
 | Claude Code | `npx @enfyra/mcp-server config --claude-code` | `.mcp.json` |
 | Cursor | `npx @enfyra/mcp-server config --cursor` | `.cursor/mcp.json` |
-| MCP Inspector / other hosts | Paste the shared STDIO config below | Host-specific `mcpServers` config |
+| VS Code / GitHub Copilot | `npx @enfyra/mcp-server config --vscode` | `.vscode/mcp.json` |
+| Google Antigravity | `npx @enfyra/mcp-server config --antigravity` | `.agents/mcp_config.json` |
+| MCP Inspector / other project-scoped hosts | Paste the shared STDIO config below | Host-specific project config |
 
 <details>
 <summary><strong>Codex setup</strong></summary>
@@ -108,10 +112,71 @@ Official reference: [Cursor MCP](https://cursor.com/docs/context/mcp).
 
 </details>
 
+<details>
+<summary><strong>VS Code / GitHub Copilot setup</strong></summary>
+
+```bash
+npx @enfyra/mcp-server config --vscode
+```
+
+VS Code workspace config is written to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "enfyra": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@enfyra/mcp-server"],
+      "env": {
+        "ENFYRA_API_URL": "http://localhost:3000/api",
+        "ENFYRA_API_TOKEN": "efy_pat_your-token"
+      }
+    }
+  }
+}
+```
+
+Use the VS Code command `MCP: List Servers` to inspect or start the server after setup. This is a workspace config, so it stays tied to the current project.
+
+Official references: [VS Code MCP servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) and [VS Code MCP configuration](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
+
+</details>
+
+<details>
+<summary><strong>Google Antigravity setup</strong></summary>
+
+```bash
+npx @enfyra/mcp-server config --antigravity
+```
+
+Antigravity project config is written to `.agents/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "enfyra": {
+      "command": "npx",
+      "args": ["-y", "@enfyra/mcp-server"],
+      "env": {
+        "ENFYRA_API_URL": "http://localhost:3000/api",
+        "ENFYRA_API_TOKEN": "efy_pat_your-token"
+      }
+    }
+  }
+}
+```
+
+Antigravity also documents a shared user config at `~/.gemini/config/mcp_config.json`; this helper intentionally writes the project-local `.agents/mcp_config.json` file so Enfyra URL and token stay scoped to the current workspace.
+
+Official reference: [Antigravity MCP](https://antigravity.google/docs/mcp).
+
+</details>
+
 <details>
 <summary><strong>Other MCP hosts and MCP Inspector</strong></summary>
 
-Use the shared STDIO config with any host that accepts an `mcpServers` JSON block:
+Use the shared STDIO config with any project-scoped host that accepts an `mcpServers` JSON block:
 
 ```json
 {
@@ -145,11 +210,12 @@ npx @enfyra/mcp-server config [options]
 | `--app-url` | Set the Enfyra app/admin URL |
 | `--api-token`, `-t` | Set `ENFYRA_API_TOKEN` |
 | `--yes` | Non-interactive mode for CI/scripts |
-| `--global` | Write global/user config instead of project config |
 | `--reconfig` | Prompt for target clients again and replace the existing `enfyra` entry |
 | `--codex` | Write Codex config |
 | `--claude-code`, `--claude` | Write Claude Code config |
 | `--cursor` | Write Cursor config |
+| `--vscode`, `--copilot` | Write VS Code / GitHub Copilot config |
+| `--antigravity` | Write Google Antigravity config |
 | `-h`, `--help` | Show CLI help |
 
 Without a target flag, interactive mode asks which client to configure. Non-interactive mode defaults to all supported clients.
@@ -178,14 +244,18 @@ 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`.
 - 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.
@@ -229,7 +299,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.0.123",
+  "version": "0.1.1",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/index.mjs

@@ -11,15 +11,17 @@ if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
 
 Usage:
   npx @enfyra/mcp-server                 Start the MCP stdio server
-  npx @enfyra/mcp-server config [flags]  Write local MCP host config
+  npx @enfyra/mcp-server config [flags]  Write project-local MCP host config
 
 Common config flags:
-  --codex             Write ~/.codex/config.toml
+  --codex             Write ./.codex/config.toml
   --claude-code       Write ./.mcp.json
   --cursor            Write ./.cursor/mcp.json
+  --vscode            Write ./.vscode/mcp.json
+  --antigravity       Write ./.agents/mcp_config.json
   --reconfig          Prompt for host and credentials again, replacing the enfyra entry
   --yes               Non-interactive
-  -a, --api-url       ENFYRA_API_URL
+  --app-url           ENFYRA_APP_URL
   -t, --api-token     ENFYRA_API_TOKEN
   -h, --help          Show config help
 

package/src/lib/config-local.mjs

@@ -3,7 +3,6 @@ import { createInterface } from 'node:readline/promises';
 import { emitKeypressEvents } from 'node:readline';
 import { stdin as input, stdout as output, cwd } from 'node:process';
 import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
 
 const SERVER_KEY = 'enfyra';
 const forceColor = process.env.FORCE_COLOR != null && process.env.FORCE_COLOR !== '0';
@@ -36,6 +35,16 @@ const clients = {
     path: './.cursor/mcp.json',
     color: style.cyan,
   },
+  vscode: {
+    label: 'VS Code / Copilot',
+    path: './.vscode/mcp.json',
+    color: style.blue,
+  },
+  antigravity: {
+    label: 'Antigravity',
+    path: './.agents/mcp_config.json',
+    color: style.yellow,
+  },
 };
 
 function statusIcon(kind) {
@@ -55,7 +64,7 @@ function exitCancelled() {
 
 function printHelp() {
   console.log(`${style.bold('Enfyra MCP config')}
-${style.dim('Write local MCP client config for Enfyra.')}
+${style.dim('Write project-local MCP client config for Enfyra.')}
 
 ${style.bold('Usage')}
   npx @enfyra/mcp-server config [options]
@@ -64,12 +73,12 @@ ${style.bold('Supported clients')}
   Codex        ./.codex/config.toml
   Claude Code  ./.mcp.json
   Cursor       ./.cursor/mcp.json
-  Other MCP hosts can use the shared stdio JSON from the README.
+  VS Code      ./.vscode/mcp.json
+  Antigravity  ./.agents/mcp_config.json
 
 ${style.bold('Options')}
   --app-url <url>          Enfyra app/admin URL, for example https://demo.enfyra.io
   --api-token, -t <secret>  ENFYRA_API_TOKEN
-  --global                Write global/user config for selected clients instead of project config
   --reconfig              Always choose target again in interactive mode and replace the old enfyra config for that target
   --yes                   Non-interactive: no prompts (CI / scripts); use CLI, env, existing file, then defaults
 
@@ -79,20 +88,23 @@ ${style.bold('Client selection')}
   --claude-code, --claude, --claude-only   Only ./.mcp.json (Claude Code project scope)
   --cursor, --cursor-only                  Only ./.cursor/mcp.json (Cursor)
   --codex, --codex-only                    Only ./.codex/config.toml (Codex project scope)
+  --vscode, --copilot, --vscode-only       Only ./.vscode/mcp.json (VS Code / Copilot)
+  --antigravity, --antigravity-only        Only ./.agents/mcp_config.json (Antigravity)
   Passing multiple target flags writes each selected target.
 
   -h, --help              Show this help
 
 ${style.bold('Interactive mode')}
-  Choose Codex, Claude Code, Cursor, or all clients; then enter ENFYRA_APP_URL and ENFYRA_API_TOKEN.
+  Choose Codex, Claude Code, Cursor, VS Code, Antigravity, or all clients; then enter ENFYRA_APP_URL and ENFYRA_API_TOKEN.
   Existing Enfyra config and environment variables are used as defaults. Re-run anytime to update.
 
 ${style.bold('Examples')}
   npx @enfyra/mcp-server config
   npx @enfyra/mcp-server config --yes
   npx @enfyra/mcp-server config --codex --cursor
+  npx @enfyra/mcp-server config --vscode
+  npx @enfyra/mcp-server config --antigravity
   npx @enfyra/mcp-server config --claude-code
-  npx @enfyra/mcp-server config --global --codex
   npx @enfyra/mcp-server config --reconfig
   npx @enfyra/mcp-server config --app-url http://localhost:3000 -t 'efy_pat_...'
   ENFYRA_APP_URL=https://demo.enfyra.io ENFYRA_API_TOKEN=efy_pat_... npx @enfyra/mcp-server config --yes
@@ -109,11 +121,14 @@ function parseArgs(argv) {
     help: false,
     yes: false,
     reconfig: false,
-    global: false,
+    vscode: true,
+    antigravity: true,
   };
   let pickClaude = false;
   let pickCursor = false;
   let pickCodex = false;
+  let pickVscode = false;
+  let pickAntigravity = false;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     const next = () => {
@@ -126,7 +141,6 @@ function parseArgs(argv) {
     else if (a === 'help') out.help = true;
     else if (a === '--yes') out.yes = true;
     else if (a === '--reconfig') out.reconfig = true;
-    else if (a === '--global') out.global = true;
     else if (a === '--app-url') out.appUrl = next();
     else if (a === '--api-url' || a === '-a') {
       throw new Error(`${a} is no longer supported for setup; use --app-url instead`);
@@ -138,13 +152,17 @@ function parseArgs(argv) {
     else if (a === '--claude-only' || a === '--claude-code' || a === '--claude') pickClaude = true;
     else if (a === '--cursor-only' || a === '--cursor') pickCursor = true;
     else if (a === '--codex-only' || a === '--codex') pickCodex = true;
+    else if (a === '--vscode-only' || a === '--vscode' || a === '--copilot') pickVscode = true;
+    else if (a === '--antigravity-only' || a === '--antigravity') pickAntigravity = true;
     else throw new Error(`Unknown argument: ${a}`);
   }
-  out.targetExplicit = pickClaude || pickCursor || pickCodex;
+  out.targetExplicit = pickClaude || pickCursor || pickCodex || pickVscode || pickAntigravity;
   if (out.targetExplicit) {
     out.claude = pickClaude;
     out.cursor = pickCursor;
     out.codex = pickCodex;
+    out.vscode = pickVscode;
+    out.antigravity = pickAntigravity;
   }
   return out;
 }
@@ -193,9 +211,7 @@ async function mergeMcpFile(absPath, serverEntry) {
   try {
     const raw = await readFile(absPath, 'utf8');
     const parsed = JSON.parse(raw);
-    if (parsed && typeof parsed === 'object' && parsed.mcpServers && typeof parsed.mcpServers === 'object') {
-      data.mcpServers = { ...parsed.mcpServers };
-    } else if (parsed && typeof parsed === 'object') {
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
       data = { ...parsed, mcpServers: parsed.mcpServers && typeof parsed.mcpServers === 'object' ? { ...parsed.mcpServers } : {} };
     }
   } catch (e) {
@@ -207,6 +223,31 @@ async function mergeMcpFile(absPath, serverEntry) {
   await writeFile(absPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
 }
 
+async function mergeVscodeMcpFile(absPath, serverEntry) {
+  let data = { servers: {} };
+  try {
+    const raw = await readFile(absPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') {
+      data = {
+        ...parsed,
+        servers: parsed.servers && typeof parsed.servers === 'object' ? { ...parsed.servers } : {},
+      };
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  data.servers = {
+    ...data.servers,
+    [SERVER_KEY]: {
+      type: 'stdio',
+      ...serverEntry,
+    },
+  };
+  await mkdir(dirname(absPath), { recursive: true });
+  await writeFile(absPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
 function tomlString(value) {
   return JSON.stringify(String(value ?? ''));
 }
@@ -285,50 +326,69 @@ async function readCodexEnfyraEnv(absPath) {
   return null;
 }
 
-function getCodexConfigPath(root, globalScope) {
-  return globalScope ? join(homedir(), '.codex', 'config.toml') : join(root, '.codex', 'config.toml');
+function getCodexConfigPath(root) {
+  return join(root, '.codex', 'config.toml');
+}
+
+function getClaudeConfigPath(root) {
+  return join(root, '.mcp.json');
+}
+
+function getCursorConfigPath(root) {
+  return join(root, '.cursor', 'mcp.json');
 }
 
-function getClaudeConfigPath(root, globalScope) {
-  return globalScope ? join(homedir(), '.mcp.json') : join(root, '.mcp.json');
+function getVscodeConfigPath(root) {
+  return join(root, '.vscode', 'mcp.json');
 }
 
-function getCursorConfigPath(root, globalScope) {
-  return globalScope ? join(homedir(), '.cursor', 'mcp.json') : join(root, '.cursor', 'mcp.json');
+function getAntigravityConfigPath(root) {
+  return join(root, '.agents', 'mcp_config.json');
 }
 
-function getClientPath(client, root, globalScope) {
-  if (client === 'claude') return getClaudeConfigPath(root, globalScope);
-  if (client === 'cursor') return getCursorConfigPath(root, globalScope);
-  if (client === 'codex') return getCodexConfigPath(root, globalScope);
+function getClientPath(client, root) {
+  if (client === 'claude') return getClaudeConfigPath(root);
+  if (client === 'cursor') return getCursorConfigPath(root);
+  if (client === 'codex') return getCodexConfigPath(root);
+  if (client === 'vscode') return getVscodeConfigPath(root);
+  if (client === 'antigravity') return getAntigravityConfigPath(root);
   throw new Error(`Unknown MCP client: ${client}`);
 }
 
-async function loadExistingEnfyraEnv(root, readClaude, readCursor, readCodex, globalScope) {
+async function readMcpServerEnv(absPath, serverRootKey) {
+  try {
+    const raw = await readFile(absPath, 'utf8');
+    const j = JSON.parse(raw);
+    const e = j?.[serverRootKey]?.[SERVER_KEY]?.env;
+    if (e && typeof e === 'object' && (e.ENFYRA_API_URL || e.ENFYRA_API_TOKEN)) {
+      return {
+        apiUrl: typeof e.ENFYRA_API_URL === 'string' ? e.ENFYRA_API_URL : '',
+        apiToken: typeof e.ENFYRA_API_TOKEN === 'string' ? e.ENFYRA_API_TOKEN : '',
+      };
+    }
+  } catch {
+    /* */
+  }
+  return null;
+}
+
+async function loadExistingEnfyraEnv(root, readClaude, readCursor, readCodex, readVscode, readAntigravity) {
   const paths = [];
-  if (readClaude) paths.push(getClaudeConfigPath(root, globalScope));
-  if (readCursor) paths.push(getCursorConfigPath(root, globalScope));
-  if (!globalScope && !readClaude && readCursor) paths.push(join(root, '.mcp.json'));
+  if (readClaude) paths.push({ path: getClaudeConfigPath(root), rootKey: 'mcpServers' });
+  if (readCursor) paths.push({ path: getCursorConfigPath(root), rootKey: 'mcpServers' });
+  if (!readClaude && readCursor) paths.push({ path: getClaudeConfigPath(root), rootKey: 'mcpServers' });
+  if (readVscode) paths.push({ path: getVscodeConfigPath(root), rootKey: 'servers' });
+  if (readAntigravity) paths.push({ path: getAntigravityConfigPath(root), rootKey: 'mcpServers' });
   const seen = new Set();
-  for (const p of paths) {
-    if (seen.has(p)) continue;
-    seen.add(p);
-    try {
-      const raw = await readFile(p, 'utf8');
-      const j = JSON.parse(raw);
-      const e = j?.mcpServers?.[SERVER_KEY]?.env;
-      if (e && typeof e === 'object' && (e.ENFYRA_API_URL || e.ENFYRA_API_TOKEN)) {
-        return {
-          apiUrl: typeof e.ENFYRA_API_URL === 'string' ? e.ENFYRA_API_URL : '',
-          apiToken: typeof e.ENFYRA_API_TOKEN === 'string' ? e.ENFYRA_API_TOKEN : '',
-        };
-      }
-    } catch {
-      /* */
-    }
+  for (const entry of paths) {
+    const key = `${entry.rootKey}:${entry.path}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const env = await readMcpServerEnv(entry.path, entry.rootKey);
+    if (env) return env;
   }
   if (readCodex) {
-    const codex = await readCodexEnfyraEnv(getCodexConfigPath(root, globalScope));
+    const codex = await readCodexEnfyraEnv(getCodexConfigPath(root));
     if (codex) return codex;
   }
   return { apiUrl: '', apiToken: '' };
@@ -338,23 +398,31 @@ async function promptTargetChoice() {
   const choices = [
     {
       client: 'codex',
-      value: { claude: false, cursor: false, codex: true },
+      value: { claude: false, cursor: false, codex: true, vscode: false, antigravity: false },
     },
     {
       client: 'claude',
-      value: { claude: true, cursor: false, codex: false },
+      value: { claude: true, cursor: false, codex: false, vscode: false, antigravity: false },
     },
     {
       client: 'cursor',
-      value: { claude: false, cursor: true, codex: false },
+      value: { claude: false, cursor: true, codex: false, vscode: false, antigravity: false },
+    },
+    {
+      client: 'vscode',
+      value: { claude: false, cursor: false, codex: false, vscode: true, antigravity: false },
+    },
+    {
+      client: 'antigravity',
+      value: { claude: false, cursor: false, codex: false, vscode: false, antigravity: true },
     },
     {
       client: 'all',
-      value: { claude: true, cursor: true, codex: true },
+      value: { claude: true, cursor: true, codex: true, vscode: true, antigravity: true },
     },
   ];
   if (input.setRawMode && output.isTTY) {
-    return promptTargetSelect(choices, 3);
+    return promptTargetSelect(choices, 5);
   }
 
   const rl = createInterface({ input, output });
@@ -363,23 +431,31 @@ async function promptTargetChoice() {
       + '  [1] Codex        ./.codex/config.toml\n'
       + '  [2] Claude Code  ./.mcp.json\n'
       + '  [3] Cursor       ./.cursor/mcp.json\n'
-      + '  [4] All [default]\n'
-      + 'Choice [4]: ',
+      + '  [4] VS Code      ./.vscode/mcp.json\n'
+      + '  [5] Antigravity  ./.agents/mcp_config.json\n'
+      + '  [6] All [default]\n'
+      + 'Choice [6]: ',
   )).trim().toLowerCase();
   await rl.close();
-  if (line === '' || line === '4' || line === 'all' || line === 'a') {
-    return { claude: true, cursor: true, codex: true };
+  if (line === '' || line === '6' || line === 'all' || line === 'a') {
+    return { claude: true, cursor: true, codex: true, vscode: true, antigravity: true };
   }
   if (line === '1' || line === 'codex' || line === 'x') {
-    return { claude: false, cursor: false, codex: true };
+    return { claude: false, cursor: false, codex: true, vscode: false, antigravity: false };
   }
   if (line === '2' || line === 'claude' || line === 'claude-code') {
-    return { claude: true, cursor: false, codex: false };
+    return { claude: true, cursor: false, codex: false, vscode: false, antigravity: false };
   }
   if (line === '3' || line === 'cursor' || line === 'u') {
-    return { claude: false, cursor: true, codex: false };
+    return { claude: false, cursor: true, codex: false, vscode: false, antigravity: false };
+  }
+  if (line === '4' || line === 'vscode' || line === 'vs-code' || line === 'copilot') {
+    return { claude: false, cursor: false, codex: false, vscode: true, antigravity: false };
+  }
+  if (line === '5' || line === 'antigravity') {
+    return { claude: false, cursor: false, codex: false, vscode: false, antigravity: true };
   }
-  return { claude: true, cursor: true, codex: true };
+  return { claude: true, cursor: true, codex: true, vscode: true, antigravity: true };
 }
 
 async function promptTargetSelect(choices, initialIndex = 0) {
@@ -392,7 +468,7 @@ async function promptTargetSelect(choices, initialIndex = 0) {
     if (choice.client === 'all') {
       const label = active ? style.bold(style.underline('All supported clients')) : 'All supported clients';
       const paddedLabel = label + ' '.repeat(22 - 'All supported clients'.length);
-      const hint = active ? style.cyan('Codex + Claude Code + Cursor') : style.dim('Codex + Claude Code + Cursor');
+      const hint = active ? style.cyan('Codex + Claude Code + Cursor + VS Code + Antigravity') : style.dim('Codex + Claude Code + Cursor + VS Code + Antigravity');
       return `${accent} ${indicator} ${paddedLabel} ${hint}`;
     }
 
@@ -545,14 +621,18 @@ export async function runLocalConfig(argv) {
   let writeClaude = opts.claude;
   let writeCursor = opts.cursor;
   let writeCodex = opts.codex;
+  let writeVscode = opts.vscode;
+  let writeAntigravity = opts.antigravity;
   if (usePrompt && (!opts.targetExplicit || opts.reconfig)) {
     const t = await promptTargetChoice();
     writeClaude = t.claude;
     writeCursor = t.cursor;
     writeCodex = t.codex;
+    writeVscode = t.vscode;
+    writeAntigravity = t.antigravity;
   }
 
-  const existing = await loadExistingEnfyraEnv(root, writeClaude, writeCursor, writeCodex, opts.global);
+  const existing = await loadExistingEnfyraEnv(root, writeClaude, writeCursor, writeCodex, writeVscode, writeAntigravity);
 
   let apiUrl;
   let apiToken;
@@ -578,23 +658,32 @@ export async function runLocalConfig(argv) {
   const written = [];
 
   if (writeCodex) {
-    const p = getClientPath('codex', root, opts.global);
+    const p = getClientPath('codex', root);
     await mergeCodexConfig(p, apiUrl, apiToken);
     written.push({ client: 'codex', path: p });
   }
   if (writeClaude) {
-    const p = getClientPath('claude', root, opts.global);
+    const p = getClientPath('claude', root);
     await mergeMcpFile(p, serverEntry);
     written.push({ client: 'claude', path: p });
   }
   if (writeCursor) {
-    const p = getClientPath('cursor', root, opts.global);
+    const p = getClientPath('cursor', root);
     await mergeMcpFile(p, serverEntry);
     written.push({ client: 'cursor', path: p });
   }
+  if (writeVscode) {
+    const p = getClientPath('vscode', root);
+    await mergeVscodeMcpFile(p, serverEntry);
+    written.push({ client: 'vscode', path: p });
+  }
+  if (writeAntigravity) {
+    const p = getClientPath('antigravity', root);
+    await mergeMcpFile(p, serverEntry);
+    written.push({ client: 'antigravity', path: p });
+  }
 
-  const scopeLabel = opts.global ? 'global/user' : 'project';
-  console.log(`${statusIcon('success')} ${style.bold(style.green('Enfyra MCP config updated'))} ${style.dim(`(${scopeLabel})`)}\n`);
+  console.log(`${statusIcon('success')} ${style.bold(style.green('Enfyra MCP config updated'))} ${style.dim('(project)')}\n`);
   for (const entry of written) {
     const meta = clients[entry.client];
     console.log(`  ${style.cyan('•')} ${style.bold(meta.color(meta.label))}`);
@@ -612,6 +701,12 @@ export async function runLocalConfig(argv) {
   if (selectedClients.has('cursor')) {
     console.log('  - Cursor: restart Cursor or reload MCP, then confirm the server under Settings -> MCP.');
   }
+  if (selectedClients.has('vscode')) {
+    console.log('  - VS Code / Copilot: run MCP: List Servers or reload the workspace, then start the Enfyra server if prompted.');
+  }
+  if (selectedClients.has('antigravity')) {
+    console.log('  - Antigravity: reopen the workspace or reload MCP servers so ./.agents/mcp_config.json is picked up.');
+  }
   console.log('  - Re-run this command anytime to update the same Enfyra entries.');
   if (!apiToken) {
     console.log(`\n${statusIcon('warn')} ${style.yellow('ENFYRA_API_TOKEN is empty; tools will not authenticate until it is set.')}`);

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/mcp-server-entry.mjs

@@ -22,7 +22,15 @@ 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 {
@@ -208,6 +216,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 +605,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 +790,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 +1076,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 +1206,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 +1243,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 +1316,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.');
@@ -1442,8 +1470,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 +1489,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) });
@@ -1511,8 +1545,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 +1578,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 +1620,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 +2510,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 +2573,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 +2629,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', {