@enfyra/mcp-server 0.0.58 → 0.0.59

package/README.md

@@ -186,7 +186,7 @@ Use this block in any host-specific `mcp.json` / `mcpServers` merge (adjust env
 
 Schema and script tools include safety guards for LLM callers: generic record mutations validate request fields against live metadata, script-backed records must validate `sourceCode` before save through `/admin/script/validate` and fail closed if validation is unavailable, relation metadata rejects physical FK/junction inputs, custom routes reject `mainTableId` unless the path is the canonical table route, schema tools serialize table/column/relation changes, and destructive deletes require `confirm=true` after returning a preview.
 
-For route contracts that intentionally keep workflow fields out of request bodies, generic `create_record`, `update_record`, and `delete_record` accept optional `queryParams` as a JSON object string. For example, Cloud admin project creation can keep `expired_at=YYYY-MM-DD` in the URL query while `validateBody` remains enabled for the table body.
+For route contracts that intentionally keep workflow fields out of request bodies, generic `create_record`, `update_record`, and `delete_record` accept optional `queryParams` as a JSON object string. For example, a renewal workflow can keep `expires_at=YYYY-MM-DD` in the URL query while `validateBody` remains enabled for the table body.
 
 ### `ENFYRA_API_URL` — use the app proxy
 
@@ -200,7 +200,7 @@ The Enfyra backend is private infrastructure. MCP, browser code, SSR routes, Gra
 
 ### SSR app auth pattern
 
-When an LLM builds a Nuxt, Next, or other SSR frontend for Enfyra, follow the Enfyra Cloud pattern:
+When an LLM builds a Nuxt, Next, or other SSR frontend for Enfyra, follow the same-origin proxy pattern:
 
 - Browser code calls a same-origin proxy such as `{{ appOrigin }}/enfyra/**`, never the raw Enfyra backend URL.
 - Nuxt can proxy it with `routeRules: { "/enfyra/**": { proxy: { to: `${API_URL}/**`, fetchOptions: { redirect: "manual" } } } }`. Keep redirects manual so OAuth set-cookie redirects reach the browser as real HTTP redirects with `Set-Cookie`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.58",
+  "version": "0.0.59",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -206,13 +206,13 @@ create_column({
 })
 
 create_column({
-  tableId: "<project_env_table_id>",
+  tableId: "<integration_secret_table_id>",
   name: "value",
   type: "text",
   isNullable: false,
   isPublished: false,
   isEncrypted: true,
-  description: "Encrypted environment value."
+  description: "Encrypted secret value."
 })`,
         notes: [
           'Run schema-changing calls sequentially. Do not parallelize create_column calls.',
@@ -221,6 +221,30 @@ create_column({
           'Use hooks or field permissions to prevent clients from updating server-owned fields.',
         ],
       },
+      {
+        name: 'Patch table schema from metadata only',
+        code: `// Safe schema patch process used by create_column/update_column/delete_column:
+// 1. Read GET /metadata and find the target table.
+// 2. Keep only persisted column rows with id/_id.
+// 3. Add, change, or remove the intended column.
+// 4. PATCH /table_definition/:id with the full preserved columns array.
+// 5. If the backend returns requiredConfirmHash, resend with ?schemaConfirmHash=<hash>.
+// 6. Re-read metadata and verify unrelated column ids still exist.
+
+create_column({
+  tableId: "<table_id>",
+  name: "api_secret",
+  type: "text",
+  isPublished: false,
+  isEncrypted: true
+})`,
+        notes: [
+          'Do not rebuild schema cascade payloads from table_definition?fields=columns.*; nested fields can be truncated or relation-derived.',
+          'Generated projections such as createdAt, updatedAt, and relation FK display fields without id/_id are not valid column_definition rows.',
+          'Never delete or omit unrelated persisted columns when adding one field.',
+          'Run schema-changing calls sequentially; migration locks are backend-owned.',
+        ],
+      },
     ],
   },
   'queries-deep': {
@@ -253,10 +277,18 @@ create_column({
       },
       {
         name: 'Fetch one record by id',
-        code: `GET /enfyra/post?filter={"id":{"_eq":123}}&limit=1`,
+        code: `find_one_record({
+  tableName: "post",
+  id: "123",
+  fields: ["id", "title", "createdAt"]
+})
+
+// REST equivalent after inspecting metadata primary key:
+GET /enfyra/post?filter={"<primaryKeyFromMetadata>":{"_eq":123}}&limit=1`,
         notes: [
           'There is no dynamic GET /<table>/<id> route.',
-          'Use filter + limit=1 or MCP find_one_record.',
+          'Prefer MCP find_one_record because it resolves the primary key from live metadata.',
+          'If writing raw REST, inspect metadata first and use the real primary key field; do not assume id on every backend.',
         ],
       },
       {
@@ -288,6 +320,38 @@ create_column({
           'Do not invent deep keys like members unless members is a relation on that table.',
         ],
       },
+      {
+        name: 'Encrypted fields are not lookup fields',
+        code: `// Bad: api_token is isEncrypted=true, so filter/sort cannot use it.
+GET /enfyra/integrations?filter={"api_token":{"_eq":"plaintext-token"}}
+
+// Good: store a separate non-secret lookup hash if lookup is needed.
+create_column({
+  tableId: "<integrations_table_id>",
+  name: "api_token_lookup_sha256",
+  type: "varchar",
+  isNullable: false,
+  isPublished: false
+})
+
+// In the create/update handler or pre-hook, hash plaintext before it is encrypted.
+if (@BODY.api_token) {
+  @BODY.api_token_lookup_sha256 = @HELPERS.$crypto.sha256(@BODY.api_token)
+}
+
+// Lookup by the hash, never by the encrypted field.
+const lookup = @HELPERS.$crypto.sha256(@BODY.api_token)
+const found = await #integrations.find({
+  filter: { api_token_lookup_sha256: { _eq: lookup } },
+  limit: 1
+})`,
+        notes: [
+          'isEncrypted values are encrypted at rest and decrypted after select.',
+          'Do not filter, sort, or deep-filter by encrypted fields.',
+          'Use a separate deterministic non-secret hash/lookup column when the product needs secret-derived lookup.',
+          'Do not ask clients to submit enc:v1: ciphertext.',
+        ],
+      },
     ],
   },
   'handlers-hooks': {
@@ -356,23 +420,27 @@ const scope = {
         ],
       },
       {
-        name: 'Pre-hook encrypted field normalization',
-        code: `create_pre_hook({
-  routeId: "<route_id>",
-  name: "encrypt_api_token",
-  methods: ["POST", "PATCH"],
-  priority: 0,
-  code: \`const value = @BODY.api_token_encrypted
-if (value && value.slice(0, 7) !== "enc:v1:") {
-  @BODY.api_token_encrypted = @HELPERS.$encrypt.encrypt(value)
-}\`
+        name: 'Encrypted field table definition',
+        code: `create_table({
+  name: "integrations",
+  columns: JSON.stringify([
+    { name: "name", type: "varchar", isNullable: false },
+    {
+      name: "api_token",
+      type: "varchar",
+      isNullable: false,
+      isPublished: false,
+      isEncrypted: true
+    }
+  ])
 })`,
         notes: [
-          'MCP create_pre_hook accepts code as the tool argument, then persists it to Enfyra as sourceCode with scriptLanguage.',
-          'Do not call raw create_record with a code field for pre_hook_definition or post_hook_definition; backend CRUD rejects code.',
-          'Use Enfyra pre-hooks for request-body normalization before canonical CRUD persists the record.',
-          'Do not implement encrypted field normalization as a Knex/database hook.',
-          'Use isEncrypted columns for database encryption and $helpers.$crypto.generateSshKeyPair for SSH key generation; do not use $helpers.$ssh or $helpers.$secrets.',
+          'Use isEncrypted=true for values that must be encrypted at rest.',
+          'Scripts and REST callers read and write plaintext values; Enfyra encrypts on write and decrypts after select.',
+          'Set isPublished=false for secret fields that should not be exposed by default.',
+          'isEncrypted does not imply immutability; add isUpdatable=false separately only when the value must not change.',
+          'Do not generate manual $encrypt hooks or accept caller-supplied enc:v1: ciphertext for normal app data.',
+          'Encrypted fields cannot be filtered or sorted.',
         ],
       },
       {
@@ -471,35 +539,35 @@ return @DATA\`
         name: 'Admin menu and extension permission gates',
         code: `<template>
   <section class="space-y-4">
-    <PermissionGate :condition="canReadCloudProjects">
+    <PermissionGate :condition="canReadReports">
       <template #default>
         <div class="flex items-center justify-between gap-3">
-          <h2 class="text-lg font-semibold">Cloud projects</h2>
+          <h2 class="text-lg font-semibold">Reports</h2>
 
-          <PermissionGate :condition="canCreateCloudProject">
-            <UButton icon="i-lucide-plus" label="Create project" @click="openCreate = true" />
+          <PermissionGate :condition="canCreateReport">
+            <UButton icon="i-lucide-plus" label="Create report" @click="openCreate = true" />
           </PermissionGate>
         </div>
 
-        <div v-for="project in projects" :key="project.id" class="rounded-lg border p-4">
-          <NuxtLink :to="\`/cloud/projects/\${project.id}\`" class="font-medium">
-            {{ project.name }}
+        <div v-for="report in reports" :key="report.id" class="rounded-lg border p-4">
+          <NuxtLink :to="\`/reports/\${report.id}\`" class="font-medium">
+            {{ report.title }}
           </NuxtLink>
 
           <div class="mt-3 flex gap-2">
-            <PermissionGate :condition="canUpdateCloudProject">
-              <UButton icon="i-lucide-pause" variant="soft" label="Disable" @click="openDisable(project)" />
+            <PermissionGate :condition="canUpdateReport">
+              <UButton icon="i-lucide-pencil" variant="outline" label="Edit" @click="openEdit(report)" />
             </PermissionGate>
 
-            <PermissionGate :condition="canDeleteCloudProject">
-              <UButton icon="i-lucide-trash-2" color="error" variant="soft" label="Delete" @click="openDelete(project)" />
+            <PermissionGate :condition="canDeleteReport">
+              <UButton icon="i-lucide-trash-2" color="error" variant="outline" label="Delete" @click="openDelete(report)" />
             </PermissionGate>
           </div>
         </div>
       </template>
 
       <template #fallback>
-        <EmptyState title="No access" description="You do not have permission to view Cloud projects." />
+        <EmptyState title="No access" description="You do not have permission to view reports." />
       </template>
     </PermissionGate>
   </section>
@@ -508,28 +576,28 @@ return @DATA\`
 <script setup>
 const { checkPermissionCondition } = usePermissions()
 
-const canReadCloudProjects = computed(() => checkPermissionCondition({
+const canReadReports = computed(() => checkPermissionCondition({
   or: [
-    { route: '/cloud/projects', methods: ['GET'] },
-    { route: '/cloud_projects', methods: ['GET'] }
+    { route: '/reports', methods: ['GET'] },
+    { route: '/report_definition', methods: ['GET'] }
   ]
 }))
 
-const canCreateCloudProject = computed(() => checkPermissionCondition({
-  or: [{ route: '/cloud_projects', methods: ['POST'] }]
+const canCreateReport = computed(() => checkPermissionCondition({
+  or: [{ route: '/report_definition', methods: ['POST'] }]
 }))
 
-const canUpdateCloudProject = computed(() => checkPermissionCondition({
-  or: [{ route: '/cloud_projects', methods: ['PATCH'] }]
+const canUpdateReport = computed(() => checkPermissionCondition({
+  or: [{ route: '/report_definition', methods: ['PATCH'] }]
 }))
 
-const canDeleteCloudProject = computed(() => checkPermissionCondition({
-  or: [{ route: '/cloud_projects', methods: ['DELETE'] }]
+const canDeleteReport = computed(() => checkPermissionCondition({
+  or: [{ route: '/report_definition', methods: ['DELETE'] }]
 }))
 </script>`,
         notes: [
           'This is menu/extension visibility, not row-level RLS.',
-          'Set menu_definition.permission on every sensitive admin menu. Example for /cloud/hosts: { or: [{ route: "/cloud/admin/hosts", methods: ["GET"] }, { route: "/cloud_servers", methods: ["GET"] }] }.',
+          'Set menu_definition.permission on every sensitive admin menu. Example for /reports: { or: [{ route: "/reports", methods: ["GET"] }, { route: "/report_definition", methods: ["GET"] }] }.',
           'Admin pages are sensitive. Use permission gates by default, not as an optional polish step.',
           'Menus should only be visible when the user has at least GET permission for the page route or backing data route.',
           'Inside the extension, gate each action by its own route/method: GET for page visibility, POST for create/flow-trigger buttons, PATCH for normal record edits, DELETE for native delete routes.',
@@ -725,7 +793,13 @@ return {
   path: "/reports",
   icon: "lucide:bar-chart-3",
   order: 20,
-  isEnabled: true
+  isEnabled: true,
+  permission: JSON.stringify({
+    or: [
+      { route: "/reports", methods: ["GET"] },
+      { route: "/report_definition", methods: ["GET"] }
+    ]
+  })
 })
 
 // Read the created menu id from the tool response, then:
@@ -734,12 +808,13 @@ create_extension({
   name: "ReportsPage",
   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-3\\"><UCard><p class=\\"text-sm text-muted\\">Total</p><p class=\\"mt-2 text-2xl font-semibold\\">0</p></UCard></div></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'cyan', variant: 'minimal' }); useHeaderActionRegistry({ id: 'refresh-reports', label: 'Refresh', icon: 'lucide:refresh-cw', onClick: () => {}, order: 0 })</script>",
+  code: "<template><section class=\\"min-h-full w-full space-y-4\\"><div class=\\"grid gap-4 md:grid-cols-3\\"><UCard><p class=\\"text-sm text-muted\\">Total</p><p class=\\"mt-2 text-2xl font-semibold\\">0</p></UCard></div></section></template><script setup>const { registerPageHeader } = usePageHeaderRegistry(); registerPageHeader({ title: 'Reports', description: 'Operational report overview.', leadingIcon: 'lucide:bar-chart-3', gradient: 'cyan', variant: 'minimal' }); useHeaderActionRegistry([{ id: 'refresh-reports', label: 'Refresh', icon: 'lucide:refresh-cw', onClick: () => {}, order: 0 }])</script>",
   isEnabled: true
 })`,
         notes: [
           'Menu provides navigation; extension provides content.',
           'Use menu_definition.label, not title.',
+          'Sensitive admin menus should include a permission condition at creation time.',
           'For page extensions, create the menu first and pass menuId to create_extension.',
           '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.',
@@ -756,35 +831,35 @@ create_extension({
 const { registerPageHeader } = usePageHeaderRegistry()
 
 registerPageHeader({
-  title: 'Host detail',
-  description: 'Provider state, capacity, projects, and reconciliation status.',
-  leadingIcon: 'lucide:server',
+  title: 'Report detail',
+  description: 'Review status, schedule, and delivery history.',
+  leadingIcon: 'lucide:file-text',
   gradient: 'cyan',
   variant: 'minimal'
 })
 
 useHeaderActionRegistry([
   {
-    id: 'back-to-hosts',
-    label: 'Hosts',
+    id: 'back-to-reports',
+    label: 'Reports',
     icon: 'lucide:arrow-left',
     color: 'neutral',
     variant: 'ghost',
     order: 0,
-    onClick: () => navigateTo('/cloud/hosts')
+    onClick: () => navigateTo('/reports')
   },
   {
-    id: 'run-host-check',
-    label: 'Run check',
-    icon: 'lucide:scan-search',
+    id: 'send-test-report',
+    label: 'Send test',
+    icon: 'lucide:send',
     color: 'neutral',
     variant: 'outline',
     order: 1,
-    permission: { or: [{ route: '/cloud/admin/hosts/reconcile', methods: ['POST'] }] },
-    onClick: runCheck
+    permission: { or: [{ route: '/reports/send-test', methods: ['POST'] }] },
+    onClick: sendTest
   },
   {
-    id: 'refresh-host',
+    id: 'refresh-report',
     label: 'Refresh',
     icon: 'lucide:refresh-cw',
     color: 'primary',
@@ -832,33 +907,39 @@ useHeaderActionRegistry([
         ],
       },
       {
-        name: 'Plan a Cloud admin dashboard as multiple pages',
+        name: 'Plan an admin dashboard as multiple pages',
         code: `// Recommended menu shape for an operations surface:
 create_menu({
   type: "Dropdown Menu",
-  label: "Cloud",
-  path: "/cloud",
-  icon: "lucide:cloud",
+  label: "Operations",
+  path: "/operations",
+  icon: "lucide:layout-dashboard",
   order: 2,
-  isEnabled: true
+  isEnabled: true,
+  permission: JSON.stringify({
+    or: [
+      { route: "/operations/jobs", methods: ["GET"] },
+      { route: "/flow_execution_definition", methods: ["GET"] }
+    ]
+  })
 })
 
 // Child page extensions should be focused:
 // /dashboard            compact summary/routing hub: KPIs, current signal, attention queue, navigation cards
-// /cloud/projects      project status and drill-downs
-// /cloud/provisioning  project/run grouped provisioning status, current step, meaning, next action
-// /cloud/billing       orders/subscriptions/refunds
-// /cloud/infrastructure hosts/capacity/plans/system credential readiness
-// /cloud/readiness     legal/Paddle/landing launch checklist
+// /operations/jobs      background jobs, current step, meaning, next action
+// /operations/orders    order/payment status and drill-downs
+// /operations/reports   report configuration and delivery history
+// /operations/settings  system readiness and configuration
 // Use UTabs inside large pages instead of placing every section in one dashboard.
-// For admin record management, link to /data/<table>, e.g. /data/landing_terms, not public landing paths.`,
+// For admin record management, link to /data/<table>, e.g. /data/report_definition, not public website paths.`,
         notes: [
           'Design the menu/page split before generating dashboard code.',
+          'Permission-gate sensitive parent dropdown menus too, using any child page route or backing route that represents read access.',
           'Keep /dashboard as a summary and distribution page, not a detailed operations table.',
           'Use focused pages for operational domains.',
           'Each page extension must use usePageHeaderRegistry for the app-shell title strip and should not render a duplicate top header in the body.',
           'PageHeader.stats is reserved for deliberate overview headers; operational KPIs belong in body cards/tables.',
-          'Provisioning pages should not show raw history rows as the primary UI; group by project/run and translate step keys into operator-facing labels.',
+          'Operational history pages should not show raw event rows as the primary UI; group by entity/run and translate step keys into operator-facing labels.',
           'Operational lists should use pagination plus search/filter controls; do not rely on arbitrary fixed limits such as limit=50.',
           'UTabs is available in eApp extension runtime for page-level sections.',
           'Admin links for editing or inspecting records should point to /data/<table> routes.',
@@ -887,22 +968,93 @@ onMounted(() => fetchOrders())
           'Keep extension UI focused; move backend logic into handlers/hooks when needed.',
         ],
       },
+      {
+        name: 'Modal and drawer buttons do not submit accidentally',
+        code: `<template>
+  <CommonModal v-model:open="open">
+    <template #header>
+      <h3 class="text-lg font-semibold">Update version</h3>
+    </template>
+
+    <template #body>
+      <UInput v-model="version" />
+      <UButton
+        type="button"
+        icon="i-lucide-refresh-cw"
+        label="Check version"
+        @click.stop.prevent="checkVersion"
+      />
+    </template>
+
+    <template #footer>
+      <UButton
+        type="button"
+        color="neutral"
+        variant="ghost"
+        label="Cancel"
+        @click.stop.prevent="open = false"
+      />
+      <UButton
+        type="button"
+        color="primary"
+        label="Update version"
+        :disabled="!canSubmit"
+        @click.stop.prevent="submit"
+      />
+    </template>
+  </CommonModal>
+</template>`,
+        notes: [
+          'Every trigger/footer/action button inside CommonModal, CommonDrawer, or UModal should use type="button" unless it intentionally submits a form.',
+          'Use @click.stop.prevent on modal/drawer action buttons so clicks do not bubble to row/page triggers.',
+          'Open modal/drawer shells immediately, then load content inside them; do not close and reopen after an API call.',
+          'Keep destructive final actions disabled until all confirmation inputs are valid.',
+        ],
+      },
       {
         name: 'Extension can use modern browser APIs',
         code: `<script setup lang="ts">
 const statuses = ['active', 'ready']
 const ok = statuses.includes('active')
-const requiredTerms = new Set(['cloud-terms', 'privacy-policy', 'refund-policy'])
+const requiredTerms = new Set(['terms', 'privacy'])
 const loaded = await Promise.all([Promise.resolve(1), Promise.resolve(2)])
 const label = String('pending_payment').replace(/_/g, ' ')
 const date = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric' }).format(new Date())
-console.log(ok, requiredTerms.has('cloud-terms'), loaded, label, date)
+console.log(ok, requiredTerms.has('terms'), loaded, label, date)
 </script>`,
         notes: [
           'Do not rewrite extension code to ES5 when tooling rejects modern APIs.',
           'If diagnostics complain about these APIs, fix eApp extension TypeScript lib/runtime contract.',
         ],
       },
+      {
+        name: 'Install and use an app package in an extension',
+        code: `install_package({
+  name: "dayjs",
+  type: "App"
+})
+
+// Then in extension code:
+<script setup>
+const formatted = ref('')
+
+onMounted(async () => {
+  const pkgs = await getPackages(['dayjs'])
+  const dayjs = pkgs.dayjs
+  formatted.value = dayjs().format('YYYY-MM-DD')
+})
+</script>
+
+<template>
+  <span>{{ formatted }}</span>
+</template>`,
+        notes: [
+          'Install browser-side extension dependencies as type: "App".',
+          'Do not use static import statements in extension_definition.code.',
+          'Load app packages with getPackages([...]) inside the extension runtime.',
+          'Use onMounted or an explicit action for package loading when the UI can render a loading state.',
+        ],
+      },
       {
         name: 'Dashboard aggregate stats with a time range',
         code: `<script setup>
@@ -929,7 +1081,7 @@ const flowStats = useApi('/flow_execution_definition', {
   }))
 })
 
-const orderStats = useApi('/cloud_payment_orders', {
+const orderStats = useApi('/order_definition', {
   query: computed(() => ({
     fields: 'id',
     limit: 1,

package/src/lib/mcp-instructions.js

@@ -17,7 +17,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
   const base = String(apiBaseUrl || '').replace(/\/$/, '');
   const { graphqlHttpUrl, graphqlSchemaUrl } = buildGraphqlUrls(apiBaseUrl);
   const getList = `${base}/<table_name>`;
-  const getOneById = `${base}/<table_name>?filter={"id":{"_eq":"<id>"}}&limit=1`;
+  const getOneById = `${base}/<table_name>?filter={"<primaryKeyFromMetadata>":{"_eq":"<id>"}}&limit=1`;
   const patchOne = `${base}/<table_name>/<id>`;
   const delOne = `${base}/<table_name>/<id>`;
   const examplePost = `${base}/post`;
@@ -59,20 +59,20 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### When the user asks how to connect a Nuxt/Next/SSR app to Enfyra',
     '- This is guidance for the assistant to answer users and generate app code. It is not a separate MCP tool workflow.',
-    '- Follow the Enfyra Cloud app pattern by default: expose one same-origin proxy prefix such as **`/enfyra/**`** and route it to the hidden Enfyra API base, e.g. Nuxt `routeRules: { "/enfyra/**": { proxy: { to: `${API_URL}/**`, fetchOptions: { redirect: "manual" } } } }`. Browser/generated app code calls `/enfyra/...`, not the raw Enfyra backend URL. Keep redirects manual so OAuth set-cookie redirects reach the browser with their `Set-Cookie` headers.',
-    '- Do **not** generate custom login/logout/me server routes that manually set `accessToken`, `refreshToken`, or `expTime` cookies when a Cloud-style proxy is enough. Let the proxied Enfyra API own its auth response and cookies.',
-    '- Password login in generated Cloud-style Nuxt code is **`POST /enfyra/login`**, not `/enfyra/auth/login` and not a custom SSR `/api/login` wrapper.',
+    '- Follow the app-origin proxy pattern by default: expose one same-origin proxy prefix such as **`/enfyra/**`** and route it to the hidden Enfyra API base, e.g. Nuxt `routeRules: { "/enfyra/**": { proxy: { to: `${API_URL}/**`, fetchOptions: { redirect: "manual" } } } }`. Browser/generated app code calls `/enfyra/...`, not the raw Enfyra backend URL. Keep redirects manual so OAuth set-cookie redirects reach the browser with their `Set-Cookie` headers.',
+    '- Do **not** generate custom login/logout/me server routes that manually set `accessToken`, `refreshToken`, or `expTime` cookies when a same-origin proxy is enough. Let the proxied Enfyra API own its auth response and cookies.',
+    '- Password login in generated Nuxt code is **`POST /enfyra/login`**, not `/enfyra/auth/login` and not a custom SSR `/api/login` wrapper.',
     '- Fetch the current user with **`GET /enfyra/me`** and logout with **`POST /enfyra/logout`**. Browser fetches stay same-origin and credentials/cookies flow through the proxy. Do not read JWTs in browser JavaScript for this mode.',
     '- OAuth starts on the same proxy prefix, e.g. **`GET /enfyra/auth/{provider}?redirect=<absoluteReturnUrl>&cookieBridgePrefix=/enfyra`**. `redirect` must be an absolute `http(s)` URL with the app origin. `cookieBridgePrefix` is the third app proxy prefix that forwards to the Enfyra API; Enfyra normalizes it, so `enfyra`, `/enfyra`, and `/enfyra/` all mean `/enfyra`. Use token-query callback handling only when the app intentionally manages tokens itself.',
     '- Socket.IO uses the app bridge too. Browser clients should connect to the gateway namespace with the Socket.IO transport path on the app origin, e.g. `io("/chat", { path: "/socket.io", withCredentials: true })`, while Nuxt proxies `/socket.io/**` to the Enfyra app bridge `/ws/socket.io/**`. Do not connect browser code directly to the hidden backend Socket.IO endpoint.',
-    '- If a project explicitly standardizes on `/api/**` instead of `/enfyra/**`, keep the same Cloud-style behavior under that prefix: proxy to the Enfyra API and avoid generated cookie-management routes unless the user asks for a custom auth boundary.',
+    '- If a project explicitly standardizes on `/api/**` instead of `/enfyra/**`, keep the same proxy behavior under that prefix: proxy to the Enfyra API and avoid generated cookie-management routes unless the user asks for a custom auth boundary.',
     '- If you are explaining MCP\'s own internal authentication, that is separate: this MCP server exchanges `ENFYRA_API_TOKEN` against `{ENFYRA_API_URL}/auth/token/exchange` before authenticated tool calls. The raw `efy_pat_*` token is never a Bearer token. For normal app work, `ENFYRA_API_URL` must still be the app proxy base such as `{{ nuxtApp }}/api`.',
     '',
     '### Routes vs tables (custom endpoints, handlers, hooks)',
     '- REST-first workflow for any feature: **`inspect_feature`** to locate candidates → **`inspect_table`** for table/field/relation/rule context → **`inspect_route`** for handlers/hooks/guards/permissions → **`test_rest_endpoint`** to verify the actual HTTP behavior.',
     '- Use **`create_column_rule`** for standard request validation, **`create_field_permission`** for per-field read/create/update rules, **`create_route_permission`** for authenticated route access, and **`create_guard`** for pre/post-auth request gates.',
     '- Prefer these REST inspection/operator tools over raw `query_table` on system tables when changing route behavior. They resolve ids, methods, route paths, code previews, and cache reloads for the model.',
-    '- If the user asks for a **new route**, **URL path**, **custom API endpoint**, **handler**, **pre-hook**, **post-hook**, or to **test** that kind of logic: use MCP **`create_route`** and **omit `mainTableId`**. `mainTable` is only a marker for canonical table routes like `/orders`; custom paths such as `/orders/stats`, `/cloud/admin/hosts`, `/auth/login`, or `/me` must not set it.',
+    '- If the user asks for a **new route**, **URL path**, **custom API endpoint**, **handler**, **pre-hook**, **post-hook**, or to **test** that kind of logic: use MCP **`create_route`** and **omit `mainTableId`**. `mainTable` is only a marker for canonical table routes like `/orders`; custom paths such as `/orders/stats`, `/reports/summary`, `/auth/login`, or `/me` must not set it.',
     '- **Wrong pattern:** calling **`create_table`** just to get an HTTP path, then overriding handlers on the **default** auto route `/{table_name}`. That adds unnecessary schema and breaks the usual CRUD surface for that table.',
     '- **`create_table`** is only when the user needs **new persisted data** (new entity + columns). It is **not** the right tool when the goal is only a new path or custom script.',
     '- **Right pattern:** **`create_route`** without `mainTableId` → optional **`create_handler`** / **`create_pre_hook`** / **`create_post_hook`** on **that route’s id** (from **`get_all_routes`** after create). Handler/hook code must query explicit repos such as `$ctx.$repos.orders`; do not rely on `$repos.main` for custom routes.',
@@ -129,7 +129,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Each route has **publishedMethods** (which HTTP verbs are “public”) and **routePermissions** (roles/users for protected access).',
     '- If the **current request method** is listed in **publishedMethods** for that route, the server allows the call **without** a Bearer token (`RoleGuard`).',
     '- Otherwise the client must send an **Authorization** header with **Bearer** JWT from login. Then the user must satisfy **routePermissions** (unless root admin).',
-    '- Cloud owner-scoped GET handlers must keep normal users filtered to their own `cloud_projects.owner`, but root admin operational views must bypass that owner filter with `@USER.isRootAdmin`. Apply this consistently to `cloud_projects`, `cloud_subscriptions`, `cloud_payment_orders`, `cloud_provisioning_history`, and `/cloud/projects` so admin data routes match admin summary APIs.',
+    '- Owner-scoped GET handlers must preserve caller filters and merge the owner scope for normal users, while root admin operational views may bypass that owner scope with `@USER.isRootAdmin` when the product explicitly needs global admin visibility.',
     '- MCP tools that use `fetchAPI` authenticate with the configured `ENFYRA_API_TOKEN`. Explain to users that **direct HTTP** calls need a Bearer token unless the route/method is published.',
     '',
     '### Post-hooks (REST)',
@@ -137,15 +137,14 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- You may **mutate** `@DATA` / `$ctx.$data` in place, or **return** a value: a non-`undefined` return replaces `$ctx.$data` as the response body.',
     '',
     '### Dynamic script syntax preference',
-    '- When writing server-side Enfyra scripts, prefer template macros over raw `$ctx` access: use `@BODY`, `@QUERY`, `@PARAMS`, `@USER`, `@REPOS`, `@HELPERS`, `@SOCKET`, `@TRIGGER`, `@DATA`, `@ERROR`, and `@THROW400`–`@THROW503`.',
+    '- When writing server-side Enfyra scripts, prefer template macros over raw `$ctx` access: use `@BODY`, `@QUERY`, `@PARAMS`, `@USER`, `@REPOS`, `@HELPERS`, `@SOCKET`, `@TRIGGER`, `@DATA`, `@ERROR`, and `@THROW400`–`@THROW503`. `$ctx.$env` currently has no macro; access it directly when needed.',
     '- Use Enfyra native throw helpers for intentional errors: `@THROW400("message")`, `@THROW403()`, `@THROW404("resource", id)`, or `$ctx.$throw[400]("message")`. Do not generate `throw new Error(...)` for user/domain errors in handlers, hooks, flows, websocket events, OAuth scripts, or admin-generated scripts.',
-    '- For regular app data that must be encrypted at rest, create the column with `isEncrypted=true`; Enfyra database-query hooks will encrypt on insert/update and decrypt after select. `isEncrypted` does not imply immutability; use `isUpdatable=false` separately only when the field itself must be immutable. Do not filter or sort on encrypted fields. Legacy Cloud control-plane fields named `*_encrypted` may still use route pre-hooks until migrated.',
+    '- For regular app data that must be encrypted at rest, create the column with `isEncrypted=true`; Enfyra database-query hooks will encrypt on insert/update and decrypt after select. `isEncrypted` does not imply immutability; use `isUpdatable=false` separately only when the field itself must be immutable. Do not filter or sort on encrypted fields. Do not generate new route pre-hooks for manual encryption.',
     '- Enfyra scripts use `$helpers.$crypto` for bounded crypto helpers such as `randomUUID()`, `randomBytes(size, encoding)`, `sha256(value, encoding)`, `hmacSha256(value, secret, encoding)`, and `generateSshKeyPair(comment)`. Do not generate legacy `$helpers.$ssh` or `$helpers.$secrets` usage.',
+    '- `$ctx.$env` exposes only a sanitized process env snapshot. Current OSS deny keys are exact matches: `DB_URI`, `DB_REPLICA_URIS`, `REDIS_URI`, `SECRET_KEY`, and `ADMIN_PASSWORD`. Do not read secrets from `$ctx.$env`; model app secrets as unpublished `isEncrypted=true` fields instead.',
     '- Script-backed records use one shared persistence contract: `sourceCode` is the editable source, `scriptLanguage` controls compilation, and `compiledCode` is generated by the server from `sourceCode`. Do not hand-edit or send stale `compiledCode` from generated tools; save `sourceCode`/`scriptLanguage` through `PATCH /<script_table>/<id>` and let the server persist generated `compiledCode` internally. Public metadata may mark `compiledCode` non-updatable, but the server engine must still preserve the generated value after normalization.',
     '- For route handlers specifically, the field is also `sourceCode`. Older names such as `logic` are wrong for current Enfyra REST CRUD and will be rejected. Use MCP `create_handler` so it writes `sourceCode` and resolves method ids correctly.',
     '- MCP `create_pre_hook` and `create_post_hook` accept a user-facing `code` argument but persist it as `sourceCode` with `scriptLanguage`. Do not call raw `create_record` with a `code` field for hook tables; backend request validation rejects `code` on REST CRUD.',
-    '- Enfyra Cloud host provisioning with PgBouncer must preserve tenant database isolation. PgBouncer should use per-tenant `DATABASE_URLS` entries with each tenant `db_user`, `db_password`, and `db_name`, and PostgreSQL 16/SCRAM hosts need `AUTH_TYPE=plain`. Do not route all tenants through PostgreSQL `postgres` just to make PgBouncer connect; that bypasses tenant DB permissions.',
-    '- Enfyra Cloud Docker health checks must compare exact healthy states. `true healthy` passes, `true starting` keeps waiting, and `true unhealthy` fails. Do not use broad substring logic where `unhealthy` accidentally counts as healthy.',
     '- Before saving generated script code, validate it with `POST /admin/script/validate` when available. It compiles with the server kernel and parses the executable async body without running side effects. Enfyra App `FormCodeEditor` also exposes a `Validate` action for this endpoint; use it before save/run when editing through the UI. If unavailable, use `run_admin_test`/`test_flow_step` as the closest validation path before saving.',
     '- Do not coerce dynamic script values with `String(...)`, `Number(...)`, or `Boolean(...)`. Enfyra payloads, user ids, record ids, and relation ids should keep their runtime type; validate required values and pass them through directly.',
     '- Use raw `$ctx` only when there is no template macro for the field or helper you need.',
@@ -180,14 +179,14 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Enfyra exposes OAuth callback at **`{ENFYRA_API_URL}/auth/{provider}/callback`**. Example when `ENFYRA_API_URL` is `http://localhost:3000/api`: **Google** callback URL is **`http://localhost:3000/api/auth/google/callback`** — i.e. `{ENFYRA_API_URL}/auth/google/callback` (same pattern for Facebook/GitHub: `.../auth/facebook/callback`, `.../auth/github/callback`).',
     '- **Google Cloud Console** → OAuth client → **Authorized redirect URIs**: register **exactly** that URL (scheme + host + path, no typo, no extra slash).',
     '- **Enfyra** (`oauth_config_definition` / OAuth settings): field **`redirectUri`** must be the **same string** as in Google Console — byte-for-byte. If they differ, Google or the server will reject the flow.',
-    '- **Cloud-style proxy mode:** generated Nuxt/Next apps should start OAuth through the same-origin proxy, e.g. `/enfyra/auth/google?redirect=<absoluteReturnUrl>&cookieBridgePrefix=/enfyra`, and let Enfyra handle the auth response. Do not generate a set-cookie route unless the user explicitly chooses a custom SSR auth boundary.',
+    '- **Same-origin proxy mode:** generated Nuxt/Next apps should start OAuth through the same-origin proxy, e.g. `/enfyra/auth/google?redirect=<absoluteReturnUrl>&cookieBridgePrefix=/enfyra`, and let Enfyra handle the auth response. Do not generate a set-cookie route unless the user explicitly chooses a custom SSR auth boundary.',
     '- **Manual token mode only:** `appCallbackUrl` is the frontend URL where Enfyra redirects after OAuth with `accessToken`, `refreshToken`, etc. in query. Use this only when the app intentionally manages tokens itself; it is not the preferred Nuxt/Next SSR pattern.',
     '',
     '**Server flow (for answering users or designing FE):**',
-    '1. **Start login (redirect user in browser):** Cloud-style apps use `GET /enfyra/auth/{provider}?redirect=<URL_ENCODED_ABSOLUTE_RETURN_URL>&cookieBridgePrefix=/enfyra` from the app origin; direct/manual apps may use `GET {base}/auth/{provider}?redirect=<URL_ENCODED>`. `redirect` is required and is where to send the user after the whole flow.',
+    '1. **Start login (redirect user in browser):** proxy-mode apps use `GET /enfyra/auth/{provider}?redirect=<URL_ENCODED_ABSOLUTE_RETURN_URL>&cookieBridgePrefix=/enfyra` from the app origin; direct/manual apps may use `GET {base}/auth/{provider}?redirect=<URL_ENCODED>`. `redirect` is required and is where to send the user after the whole flow.',
     '2. Server **302** to Google/Facebook/GitHub authorization page.',
     '3. Provider calls back: `GET {base}/auth/{provider}/callback?code=...&state=...` (server exchanges code, creates/links user, issues JWT).',
-    '4. In Cloud-style proxy mode, Enfyra redirects to `{redirect.origin}{cookieBridgePrefix}/auth/set-cookies?...&redirect=<originalRedirect>`. That request goes through the third app proxy to Enfyra, Enfyra returns `Set-Cookie`, then the browser is redirected to the original `redirect`. In manual token mode, backend redirects to `appCallbackUrl` with token query params. On failure, redirect includes `?error=...`.',
+    '4. In same-origin proxy mode, Enfyra redirects to `{redirect.origin}{cookieBridgePrefix}/auth/set-cookies?...&redirect=<originalRedirect>`. That request goes through the app proxy to Enfyra, Enfyra returns `Set-Cookie`, then the browser is redirected to the original `redirect`. In manual token mode, backend redirects to `appCallbackUrl` with token query params. On failure, redirect includes `?error=...`.',
     '',
     '**Frontend build checklist:**',
     '- Nuxt/Next generated apps: implement a same-origin API proxy such as `/enfyra/**` to the Enfyra API. Browser code never stores JWTs.',
@@ -294,37 +293,31 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **CRITICAL:** MUST call `create_record` or `update_record` on `extension_definition` — outputting Vue code in chat does NOT save it. User will NOT see it.',
     '- **Code format:** Vue SFC only. Structure: `<template>...</template>` + `<script setup>...</script>`. Server auto-compiles; if compile fails, fix and retry.',
     '- **NO import statements.** All APIs are injected globally (see full list below).',
-    '- **Design first for dashboards:** before creating/updating a dashboard extension, define the menu/page split, time range controls, tabs, and drill-down links. Keep `/dashboard` as a compact summary and routing hub only: KPIs, current signal, attention queue, and navigation cards. Put detailed lists/tables/timelines into focused pages such as projects, provisioning, billing, infrastructure, and readiness.',
-    '- **Operational page modeling:** model admin operational pages around the operator mental entity, not raw database/event rows. For provisioning, group history by project/run, translate internal step keys into readable labels, show current step, operator meaning, and next action, and keep raw history as a secondary `/data` shortcut.',
-    '- **Operational list data loading:** do not use arbitrary fixed limits such as `limit=50` as the whole data strategy for admin pages. Use pagination, expose result count when the API supports `meta=filterCount`, and add search/filter controls for natural lookup keys such as project id, name, and subdomain.',
+    '- **Design first for dashboards:** before creating/updating a dashboard extension, define the menu/page split, time range controls, tabs, and drill-down links. Keep `/dashboard` as a compact summary and routing hub only: KPIs, current signal, attention queue, and navigation cards. Put detailed lists/tables/timelines into focused pages such as jobs, orders, reports, integrations, and settings.',
+    '- **Operational page modeling:** model admin operational pages around the operator mental entity, not raw database/event rows. For long-running jobs, group history by entity/run, translate internal step keys into readable labels, show current step, operator meaning, and next action, and keep raw history as a secondary `/data` shortcut.',
+    '- **Operational list data loading:** do not use arbitrary fixed limits such as `limit=50` as the whole data strategy for admin pages. Use pagination, expose result count when the API supports `meta=filterCount`, and add search/filter controls for natural lookup keys such as id, name, slug, status, email, or external reference.',
     '- **ESV aggregate contract:** aggregate query must be an object keyed by a real field or relation, for example `aggregate: { id: { count: true }, status: { count: { _eq: "failed" } }, amount: { sum: true } }`. Results are returned in `response.meta.aggregate`. Time windows and cross-field conditions belong in top-level `filter`, not inside a field aggregate condition. Field aggregate conditions only support operators on that same field; relation aggregates use `countRecords`.',
     '- **Aggregate numeric rule:** `sum` and `avg` require a numeric field in ESV. Do not aggregate money stored as varchar/text. Use a numeric money field such as `amount_usd` with type `float`, `amount_cents`, or `amount` for revenue stats, or build a dedicated stats route that normalizes legacy values explicitly. If metadata says `float` but SQL aggregate still fails with `sum(character varying)`, the Enfyra Server physical schema is stale or missing the SQL float DDL mapping and must be redeployed/healed before relying on aggregate.',
     '- **Partial reload default:** ESV/ASV automatically triggers partial reloads for metadata, routes, menus, extensions, flows, handlers, and related caches after successful writes. Do not reflexively call `/admin/reload`, `/admin/reload/metadata`, or `/admin/reload/routes` after each change. Verify naturally first; use manual reload only when verification shows stale behavior, a reload event failed, or a concrete error indicates the partial reload did not apply.',
     '- **Menu/extension realtime reload contract:** `menu_definition` and `extension_definition` writes are runtime UI changes, not plain CRUD. The server cache orchestrator must emit `$system:reload` through the admin Socket.IO channel with identifiers that eApp handles; eApp must refetch menus/rebuild the menu registry for menu reloads and invalidate dynamic extension caches for extension reloads. Menu reloads can change route-to-extension mapping, so they should also invalidate extension cache. If an open admin tab does not reflect menu/extension changes, debug this two-sided reload contract before telling the user to refresh.',
-    '- **Dashboard stats:** time range buttons must change the query filter and reload stats. Cloud dashboard should summarize flow execution errors from `flow_execution_definition` and billing stats from order/subscription records; successful/no-error flow runs do not need a standalone provisioning menu.',
+    '- **Dashboard stats:** time range buttons must change the query filter and reload stats. Dashboards should summarize actionable errors and high-level activity; successful/no-error background runs usually do not need a standalone page unless there is a real workflow to manage.',
     '- **Page layout default:** page extensions should render full-bleed inside the app shell by default. The extension root is already inside the eApp page `<main>`, so do not add root-level page padding such as `p-4 sm:p-6 xl:p-8`; use spacing between internal sections only. Do not wrap the entire page in a centered card/container unless explicitly requested. Use responsive grids/stacks from the first version so the page works on desktop, tablet, and mobile.',
     '- **PageHeader is mandatory for page extensions:** eApp already renders `CommonPageHeader` from `usePageHeaderRegistry()` in the app shell. Page extensions must call `const { registerPageHeader } = usePageHeaderRegistry()` and register app-level context such as `{ title, description, leadingIcon, gradient, variant }` instead of rendering their own top `<header>` inside extension content. Use `variant: "minimal"` for operational/admin detail pages unless the page intentionally needs a larger title strip.',
-    '- **Do not misuse PageHeader stats:** `PageHeader.stats` renders prominent stat cards inside the shell header. Do not put normal operational KPIs, host capacity, billing totals, or detail metrics there by default; keep those as body cards/tables where the operator can scan them with the page content. Only use PageHeader stats for a deliberately compact overview page where the stats are truly header-level context.',
-    '- **Page actions belong in registries:** Move page-level buttons into `useHeaderActionRegistry` or `useSubHeaderActionRegistry`; keep the extension body for operational content only. Sensitive registry actions must include a `permission` condition, for example `{ id: "create", label: "Create project", permission: { and: [{ route: "/cloud_projects", methods: ["POST"] }] }, onClick }`.',
+    '- **Do not misuse PageHeader stats:** `PageHeader.stats` renders prominent stat cards inside the shell header. Do not put normal operational KPIs, capacity totals, billing totals, or detail metrics there by default; keep those as body cards/tables where the operator can scan them with the page content. Only use PageHeader stats for a deliberately compact overview page where the stats are truly header-level context.',
+    '- **Page actions belong in registries:** Move page-level buttons into `useHeaderActionRegistry` or `useSubHeaderActionRegistry`; keep the extension body for operational content only. Sensitive registry actions must include a `permission` condition, for example `{ id: "create", label: "Create report", permission: { and: [{ route: "/report_definition", methods: ["POST"] }] }, onClick }`.',
     '- **Header action button variants:** choose the button variant by intent. Use `color: "primary", variant: "solid"` for the main page action. Use `color: "neutral", variant: "ghost"` for back/navigation actions and `color: "neutral", variant: "outline"` for visible secondary actions. `variant: "soft"` is only for low-emphasis secondary/chrome actions; do not use soft for critical or primary header actions just because it looks acceptable in dark mode.',
     '- **Extension navigation:** prefer `NuxtLink` or Nuxt UI components with `:to` for visible navigation links and drill-down cards/buttons. Use `navigateTo(...)` only for imperative navigation after submit, confirm, mutation, or another side effect.',
-    '- **Extension runtime scope:** eApp exposes Vue APIs and injected Nuxt/Enfyra composables both to script global scope and Vue app `globalProperties`. Template expressions may call injected helpers directly, for example after a save handler can call `navigateTo("/data/cloud_projects")`, because Vue compiles template helpers to `_ctx.*`.',
+    '- **Extension runtime scope:** eApp exposes Vue APIs and injected Nuxt/Enfyra composables both to script global scope and Vue app `globalProperties`. Template expressions may call injected helpers directly, for example after a save handler can call `navigateTo("/data/report_definition")`, because Vue compiles template helpers to `_ctx.*`.',
     '- **Extension CSS affects shell utility ordering:** dynamic extension CSS is injected after the app shell CSS. Shell/page-header code must not put conflicting plain Tailwind utilities on the same element, such as `flex-col` plus `flex-row`, `items-start` plus `items-center`, or `text-left` plus `text-center`. Choose one mutually exclusive class per state; otherwise extension CSS can change which utility wins and shift shell layout.',
-    '- **Admin record links:** when an admin extension links to backend records for management or inspection, point to eApp data routes such as `/data/landing_terms`, `/data/cloud_projects`, or `/data/cloud_payment_orders`. Do not use public landing-page paths from record fields such as `/cloud-terms` unless the explicit intent is previewing the public website.',
-    '- **Admin menu visibility is permission-driven, not RLS:** Cloud/admin menu entries are sensitive and must set `menu_definition.permission` so they are visible only to users who have at least GET permission for the backing route or table. Permission conditions use HTTP `methods`, not CRUD `actions`. Do not show a Cloud menu merely because an extension exists or because the path is hardcoded. Example: `/cloud/hosts` menu should require `{ or: [{ route: "/cloud/admin/hosts", methods: ["GET"] }, { route: "/cloud_servers", methods: ["GET"] }] }`.',
+    '- **Admin record links:** when an admin extension links to backend records for management or inspection, point to eApp data routes such as `/data/report_definition` or `/data/order_definition`. Do not use public website paths from record fields unless the explicit intent is previewing the public website.',
+    '- **Admin menu visibility is permission-driven, not RLS:** admin menu entries are sensitive and must set `menu_definition.permission` so they are visible only to users who have at least GET permission for the backing route or table. Permission conditions use HTTP `methods`, not CRUD `actions`. Do not show an admin menu merely because an extension exists or because the path is hardcoded. Example: `/reports` menu can require `{ or: [{ route: "/reports", methods: ["GET"] }, { route: "/report_definition", methods: ["GET"] }] }`.',
     '- **PermissionGate is mandatory inside admin extensions:** every sensitive action button, form, mutation, destructive workflow, and data shortcut must be wrapped in `PermissionGate` or guarded with `usePermissions()` before rendering/enabling. Default gates: list/detail visibility needs `methods: ["GET"]`; create and custom flow-trigger routes usually need `methods: ["POST"]`; native record edits need `methods: ["PATCH"]`; native delete routes need `methods: ["DELETE"]`. Root admin still passes through normal permission helpers, but extension code must not rely on root-only assumptions.',
     '- **Extension permission UX:** if the current user can read a page but cannot perform an action, hide the action by default. If hiding would confuse the workflow, render a disabled state with a short reason. Never let the button render active and depend only on the server rejection; server permissions are the final boundary, not the UI contract.',
-    '- **Cloud project admin operations:** use canonical `cloud_projects` table routes as the single source of truth. Admin manual create uses `POST /cloud_projects` with schema-safe body fields such as `owner: { id }`, `plan: { id }`, and `status: "creating"`; expiry is passed as query `expired_at=YYYY-MM-DD`, not body `expiredAt`. The UI searches/selects `user_definition` by email and selects a plan by card; do not ask the operator to type raw user ids, plan ids, project names, subdomains, tenant admin emails, or passwords when the handler can derive them server-side. Project detail is the place for destructive lifecycle actions. Disable uses `PATCH /cloud_projects/:id` with body `{ status: "disabled" }` and `confirm_tenant_id`/`confirm_hash` in query params. Enable uses `PATCH /cloud_projects/:id` with body `{ status: "running" }`. Renew uses the canonical renew flow/query contract and writes `cloud_project_renewals`; do not add expiry columns to `cloud_projects`. Delete uses `DELETE /cloud_projects/:id` with typed `confirm_tenant_id`, returned `requiredConfirmHash`, and the matching hash before triggering `cloud-delete-project`. Do not create separate one-off `/cloud/admin/projects/*` action routes for create/disable/enable/delete when the canonical table route can own the workflow.',
-    '- **Cloud admin terminology:** in Cloud admin UI, call physical tenant workloads "projects" everywhere. Do not label creation or details as "instance" unless the user explicitly asks for that word.',
-    '- **Cloud project create UI:** manual Cloud project creation should use `CommonDrawer`, not a wide modal. Let the operator search/select `user_definition` by email and select a plan with cards; do not expose duplicate free-text `user id` or `plan id` inputs when selectors exist. Prefer sending only the selected owner id and plan id in the schema-safe body; pass expiry as query `expired_at=YYYY-MM-DD` when the canonical handler requires it and let the handler derive customer email, project name, subdomain, and password. Expiry selection should use quick presets plus a manual calendar (`UCalendar` when available, loaded through `install_package`/`getPackages` if an app package is needed).',
-    '- **Cloud host settings and creation UI:** host settings store only provider selection codes Enfyra controls, currently location and server type. Do not expose or save provider-derived RAM, disk, vCPU, or cost values by hand. Query the provider catalog route, show real package/location cards, support load-more/search when the list is long, and snapshot provider facts onto `cloud_servers` only during host creation.',
     '- **Flow schedule UI:** schedule trigger editors must keep the server contract as `triggerConfig.cron` and `triggerConfig.timezone`, but the UI should not be a bare cron field plus giant timezone dropdown. Provide common cadence presets, readable current-schedule summary, searchable access to all IANA timezones, suggested timezone shortcuts, and a custom cron escape hatch so operators can configure recurring checks without remembering cron syntax.',
-    '- **Admin operation UI:** use eApp `CommonModal` for compact create, disable, delete, and multi-field confirmation workflows. Use `CommonDrawer` for longer setup workflows such as Cloud host settings, host creation, project creation, and provider/package selection. Open the modal/drawer immediately on click, then render loading/error/content inside it; do not wait for async fetches to finish before showing the shell.',
-    '- **FormEditor is preferred for table-record forms:** when an extension creates or edits a concrete table record such as `cloud_host_settings`, `cloud_servers`, or `cloud_projects`, use `FormEditor`/`FormEditorLazy` inside the modal/page when the form is a direct table edit. Customize layout with `sections`, `includes`, and `field-map`; reserve custom inputs only for workflow-specific fields that are not table columns.',
+    '- **Admin operation UI:** use eApp `CommonModal` for compact create, disable, delete, and multi-field confirmation workflows. Use `CommonDrawer` for longer setup workflows such as multi-step create/edit forms and provider/package selection. Open the modal/drawer immediately on click, then render loading/error/content inside it; do not wait for async fetches to finish before showing the shell.',
+    '- **FormEditor is preferred for table-record forms:** when an extension creates or edits a concrete table record such as `report_definition`, `order_definition`, or another table-backed entity, use `FormEditor`/`FormEditorLazy` inside the modal/page when the form is a direct table edit. Customize layout with `sections`, `includes`, and `field-map`; reserve custom inputs only for workflow-specific fields that are not table columns.',
     '- **Modal form layout:** inside `CommonModal`, stack each form control vertically with label text above a full-width input/control. Use a small grid/space stack such as `grid gap-4`, `p.text-sm.font-medium`, then `UInput class="mt-2 w-full"`. Do not place modal labels and inputs side by side unless the user explicitly asks for a dense horizontal form.',
-    '- **Confirmation modal flow:** destructive/admin confirmation modals must read top-to-bottom as the operator workflow. For server-hash confirmations, render: tenant/id input first, then a full-width `Request hash` button, then a disabled hash input that is auto-filled by the server response, then the final destructive action in the footer. The final action stays disabled until the typed id matches and the server hash has been requested. Do not ask operators to manually type or edit the hash.',
-    '- **Cloud host deletion:** do not delete `cloud_servers` directly from an extension or custom route. Root admin host deletion must be detail-only from `/cloud/hosts/:id`, call `POST /cloud/admin/hosts/delete`, require typed `confirm_host_id`, block when any project is running or attached, return a server-generated `requiredConfirmHash` for an empty host, and require the hash back via `confirmHash` query before triggering `cloud-delete-host`.',
-    '- **Cloud host reconciliation is host-rooted:** use `cloud_reconciliation_reports` as the persisted audit source for host/control-plane/runtime mismatch checks, and use `cloud_servers.projects` as the canonical inverse list of physical projects attached to a host. Do not model reconciliation from the project side or make projects manage themselves; the host owns capacity and runtime scan responsibility. `cloud-reconcile-hosts` is a scheduled flow using `triggerConfig.cron`/`timezone`; `POST /cloud/admin/hosts/reconcile` should only trigger that flow for a host and return job metadata. Host list/detail pages should consume `/cloud/admin/hosts`, which includes the latest `reconciliation_report`, instead of querying raw report rows separately.',
+    '- **Confirmation modal flow:** destructive/admin confirmation modals must read top-to-bottom as the operator workflow. For server-hash confirmations, render: id input first, then a full-width `Request hash` button, then a disabled hash input that is auto-filled by the server response, then the final destructive action in the footer. The final action stays disabled until the typed id matches and the server hash has been requested. Do not ask operators to manually type or edit the hash.',
     '- **Do not downgrade extension code to ES5 to appease tooling.** eApp extension runtime should support normal browser/runtime APIs such as `Array.includes`, `Set`, `Promise.all`, `String.replace`, `Intl.DateTimeFormat`, and `Intl.NumberFormat`. If diagnostics reject these, fix eApp extension checker/runtime contract instead of rewriting generated extension code around the limitation. Vue extension diagnostics should only TypeScript-check `<script setup lang="ts">`; plain `<script setup>` extension code is JavaScript and must not emit TypeScript diagnostics into the form.',
     '',
     '#### Injected Vue API functions:',
@@ -378,7 +371,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '#### Extension types:',
     '- **FormEditor field-map:** Customize fields via `:field-map`. Options: `label`, `description`, `hideLabel`, `hideDescription`, `component`, `componentProps`, `type`, `disabled`, `placeholder`, `permission`, `excludedOptions`/`includedOptions`, `fieldProps` (e.g. grid `class: \'md:col-span-2\'` when `layout=\'grid\'`), `booleanWrapperClass`, `fieldWrapperClass`. Optional `:sections` — array of `{ id, title?, hideHeading?, headingClass?, class?, rootClass?, fields: string[] }`; field order follows `fields`; unlisted columns render after. Custom input component: `modelValue` / `update:modelValue`.',
-    '- **type "page":** Full-page extension. Requires `menu: { id }` — create menu first (`create_menu` or `create_record` on `menu_definition`), find by path/label, then create extension with `menu: { id: menuId }`. `menu_definition` uses **label** not name — filter by `label` or `path`.',
+    '- **type "page":** Full-page extension. Requires `menu: { id }` — create menu first (`create_menu` or `create_record` on `menu_definition`), find by path/label, then create extension with `menu: { id: menuId }`. `menu_definition` uses **label** not name — filter by `label` or `path`. Sensitive/admin menus should pass a `permission` JSON object string to `create_menu` so visibility is permission-gated from creation.',
     '- **type "widget":** Widget extension. No menu required. Embed via `<Widget :id="extensionId" />` in other extensions or pages.',
     '- **Existing pages:** if a menu already has a page extension, update that `extension_definition` record instead of creating a duplicate menu/extension. For example `/dashboard` is menu-driven and may already have an extension attached.',
     '',

package/src/lib/table-tools.js

@@ -377,7 +377,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
 
   const columnCreateSchema = {
     tableId: z.string().describe('Table definition ID (from get_all_tables or create_table).'),
-    name: z.string().describe('Column name (e.g., "title", "payment_confirm_secret_encrypted"). Lowercase with underscores.'),
+    name: z.string().describe('Column name (e.g., "title", "webhook_secret"). Lowercase with underscores.'),
     type: z.string().describe('Column type: varchar, int, text, boolean, datetime, json, decimal, timestamp, uuid, bigint, float, longtext, richtext, simple-json, code, enum, array-select, date.'),
     isNullable: z.boolean().optional().default(true).describe('Set to false if column cannot be null.'),
     isUnique: z.boolean().optional().default(false).describe('Set to true for unique constraint.'),
@@ -444,7 +444,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       'Schema operations (create/update/delete table, add column) must run one at a time — migration locks DB; parallel calls will fail.',
       'Enfyra auto-creates a default REST route at path `/<table_name>` (same segment as `name`, not alias).',
       'REST surface for that route (matches server route engine): 4 HTTP operations — GET `/<table>` (list/filter), POST `/<table>` (create), PATCH `/<table>/:id` (update), DELETE `/<table>/:id` (delete).',
-      'There is NO `GET /<table>/:id`. To fetch one row by id, use GET `/<table>?filter={"id":{"_eq":"<id>"}}&limit=1` or tool query_table / find_one_record.',
+      'There is NO `GET /<table>/:id`. To fetch one row by id, use find_one_record or inspect metadata first and call GET `/<table>?filter={"<primaryKeyFromMetadata>":{"_eq":"<id>"}}&limit=1`.',
       'Set `isSingleRecord: true` directly in create_table for settings/config tables that should keep only one record.',
       `Full URLs: ${apiBase}/<table_name> (example table post: ${apiBase}/post).`,
       'GraphQL is enabled separately per table through `gql_definition` or `update_table` with `graphqlEnabled`; it is not controlled by route availableMethods.',

package/src/mcp-server-entry.mjs

@@ -705,14 +705,15 @@ server.tool(
         },
         throws: '@THROW400 through @THROW503 and @THROW map to $ctx.$throw helpers.',
         helpers: {
-          crypto: '$ctx.$helpers.$crypto exposes bounded runtime crypto helpers: randomUUID(), randomBytes(size, encoding), sha256(value, encoding), hmacSha256(value, secret, encoding), and generateSshKeyPair(comment). Use generateSshKeyPair for Cloud host SSH keys. Do not use legacy $ctx.$helpers.$ssh.',
+          crypto: '$ctx.$helpers.$crypto exposes bounded runtime crypto helpers: randomUUID(), randomBytes(size, encoding), sha256(value, encoding), hmacSha256(value, secret, encoding), and generateSshKeyPair(comment). Use generateSshKeyPair for SSH key material. Do not use legacy $ctx.$helpers.$ssh.',
         },
+        env: '$ctx.$env exposes a sanitized process env snapshot with exact sensitive keys removed: DB_URI, DB_REPLICA_URIS, REDIS_URI, SECRET_KEY, and ADMIN_PASSWORD. Store app secrets in unpublished isEncrypted fields instead of reading them from $env.',
       },
       contexts: {
         preHook: {
           runs: 'Before handler.',
           data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REPOS', '@CACHE', '@HELPERS', '@THROW*', '@SOCKET emit helpers'],
-          queryContract: '@QUERY.filter is initialized as an object. When adding RLS or tenant filters in pre-hooks, merge directly with _and; do not add defensive type checks around @QUERY.filter.',
+          queryContract: '@QUERY.filter is initialized as an object. When adding RLS/scope filters in pre-hooks, merge directly with _and; do not add defensive type checks around @QUERY.filter.',
           rlsPattern: 'For relation-scoped reads, mutate @QUERY.filter instead of returning data. Example: const incomingFilter = @QUERY.filter; const scope = { memberships: { member: { id: { _eq: @USER.id } } } }; @QUERY.filter = Object.keys(incomingFilter).length ? { _and: [incomingFilter, scope] } : scope;',
           returnBehavior: 'Returning a non-undefined value skips handler and becomes response data.',
         },
@@ -799,7 +800,7 @@ server.tool(
       examples: {
         listOrCreate: `${base}/<table_name>`,
         updateOrDelete: `${base}/<table_name>/<id>`,
-        oneRowById: `${base}/<table_name>?filter={"id":{"_eq":"<id>"}}&limit=1`,
+        oneRowById: `${base}/<table_name>?filter={"<primaryKeyFromMetadata>":{"_eq":"<id>"}}&limit=1`,
       },
       auth: {
         publishedMethods: 'If the HTTP method is published for that route, no Bearer required; else Bearer JWT and routePermissions apply.',
@@ -1458,7 +1459,7 @@ server.tool(
   'create_route',
   [
     '**Use this when the user wants a new REST API route or path** — not `create_table`. Custom routes must omit `mainTableId`.',
-    '`mainTableId` is only a marker for canonical table routes such as `/orders`; do not set it for `/orders/stats`, `/cloud/admin/hosts`, `/auth/login`, or any custom path.',
+    '`mainTableId` is only a marker for canonical table routes such as `/orders`; do not set it for `/orders/stats`, `/reports/summary`, `/auth/login`, or any custom path.',
     'Do NOT create a new table_definition only to expose an endpoint; create a route without `mainTableId`, then have the handler/hook query explicit repos such as `$ctx.$repos.orders`.',
     'availableMethods = which REST verbs the route responds to. publishedMethods = which REST verbs are public (no auth). GraphQL is enabled separately through gql_definition/update_table graphqlEnabled.',
     'After creation the tool auto-reloads routes. Then create handlers for specific methods via create_handler on this route id.',
@@ -2094,17 +2095,24 @@ server.tool(
 // MENU & EXTENSION TOOLS
 // ============================================================================
 
-server.tool('create_menu', 'Create a menu item in the navigation', {
+server.tool('create_menu', 'Create a menu item in the navigation. Use permission JSON for sensitive menu visibility; successful writes should trigger the app menu reload contract.', {
   label: z.string().describe('Menu label'),
   type: z.enum(['Menu', 'Dropdown Menu']).default('Menu').describe('Menu type: "Menu" for leaf items, "Dropdown Menu" for items with children'),
   icon: z.string().optional().describe('Lucide icon name'),
-  path: z.string().optional().describe('Route path for type=route'),
-  externalUrl: z.string().optional().describe('External URL for type=link'),
+  path: z.string().optional().describe('App route path for a clickable menu item, e.g. "/reports".'),
+  externalUrl: z.string().optional().describe('External URL for a menu item when the backend supports external links.'),
   order: z.number().optional().default(0).describe('Display order'),
   isEnabled: z.boolean().optional().default(true).describe('Enable menu'),
   description: z.string().optional().describe('Menu description'),
+  permission: z.string().optional().describe('Optional menu visibility permission JSON object string, e.g. {"or":[{"route":"/reports","methods":["GET"]}]}'),
 }, async (data) => {
   const body = { ...data };
+  if (body.permission !== undefined) {
+    body.permission = parseJsonArg(body.permission);
+    if (!body.permission || typeof body.permission !== 'object' || Array.isArray(body.permission)) {
+      throw new Error('permission must be a JSON object string.');
+    }
+  }
   if (body.path && !body.path.startsWith('/')) {
     body.path = '/' + body.path;
   }