@enfyra/mcp-server 0.1.6 → 0.1.8

package/README.md

@@ -244,6 +244,8 @@ Use `get_enfyra_examples` from the MCP tool list when asking an LLM to generate
 - files and storage
 - Enfyra admin extensions
 
+Use `discover_enfyra_workflows` when an LLM knows the goal but may not know the right Enfyra tool path. It returns progressive-disclosure workflow matches with first tools, required acknowledgements, verification tools, relevant example categories, and `avoidTools` boundaries that prevent near-correct but unsafe tool choices.
+
 Use `get_enfyra_required_knowledge` before asking an LLM to mutate metadata, schema, routes, permissions, menus, packages, cache state, dynamic server code, or Enfyra extension code. It returns global rules plus acknowledgement keys that write tools verify before saving. Dynamic server code also requires the dynamic-code acknowledgement key, and extension code also requires the extension acknowledgement key.
 
 ## Runtime Safety
@@ -262,6 +264,7 @@ The MCP server includes safety guards for LLM callers:
 - Relation tools reject physical FK/junction names and resolve table ids from exact table names or aliases before schema mutation.
 - Generated code should use relation property names such as `conversation`, `sender`, and `member` instead of physical FK fields such as `conversationId`, `senderId`, or `memberId`.
 - Custom route tools reject `mainTableId` unless the route is the canonical table route.
+- `discover_enfyra_workflows` maps task intent to workflow surfaces before the agent loads detailed examples or guesses between similar tools.
 - Platform operation tools such as `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `add_route_methods`, `set_table_graphql`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `choose_flow_step_tool`, fixed-type flow step tools, `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
 - Schema changes are serialized.
 - Destructive deletes return a preview before requiring `confirm=true`.
@@ -300,7 +303,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, 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`.
+The MCP server exposes tools for workflow routing, metadata discovery, required knowledge, examples, query/CRUD, method management, route lifecycle, route access audit/grant, routes, handlers, hooks, tables, columns, relations, cache reloads, logs, users, roles, packages, menus, extensions, scripts, flows, websocket, files, `get_enfyra_api_context`, and `get_enfyra_required_knowledge`.
 
 Routes have two separate controls. `isEnabled` controls runtime registration: disabled routes return `404`. Use `enable_route` and `disable_route` for this lifecycle. `publicMethods` controls anonymous access for enabled routes; use `public_route_methods` and `private_route_methods` for that access boundary.
 

package/package.json

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

package/src/lib/mcp-examples.js

@@ -1597,26 +1597,14 @@ ensure_page_extension({
           'Use enfyra_menu.label, not title.',
           'Sensitive admin menus should include a permission condition at creation time.',
           'For page extensions, create the menu first with ensure_menu and pass its id to ensure_page_extension.',
-          'Call get_extension_theme_contract before writing or reviewing page/widget/global extension UI.',
+          'Call get_extension_theme_contract before writing or reviewing page/widget/global extension UI; that tool is the authority for theme, color, layout, modal, drawer, and shell registry details.',
           'Call get_enfyra_required_knowledge before saving extension code, pass globalRulesAckKey as globalRulesAckKey, and pass extensionAckKey as extensionKnowledgeAckKey.',
           'Page extensions must register the app-shell PageHeader with usePageHeaderRegistry instead of rendering a custom top header.',
-          'Use variant: "minimal" for operational pages unless a larger header is intentionally needed.',
-          'Do not put ordinary KPI cards in PageHeader.stats; render metrics in the extension body.',
           'Put page-level actions in useHeaderActionRegistry or useSubHeaderActionRegistry, destructure register first, then call it with one action or an array.',
-          'Page extensions should be full-bleed by default and responsive from the first version.',
-          'The extension root is already inside Enfyra admin page main; do not add root-level page padding.',
-          'Use eApp theme class tokens for panels, rows, badges, borders, controls, radius, and text. Generated extension templates should prefer eapp-surface-*, eapp-text-*, eapp-radius-*, eapp-divide-y, and eapp-primary-* over raw CSS variable utilities.',
-          'Treat primary color as runtime-configurable by the app color picker. For Nuxt UI components, choose color="primary" by semantic intent. For custom extension UI, decide whether each element is neutral surface, runtime-primary identity, or status: regular panels/KPI cards/list rows use eapp-surface-card/eapp-surface-muted/eapp-surface-hover/eapp-divide-y and eapp-text-* classes, while selected/current identity blocks, primary tiles, progress fills, primary icons, and primary CTA fills use eapp-primary-surface, eapp-primary-soft, eapp-primary-subtle, eapp-primary-solid, or eapp-primary-text so the color picker controls them. eapp-primary-surface supplies selected identity color but does not replace card chrome; keep border/radius classes on selected blocks.',
-          'Decision cases: normal decorative accents, feature icons, non-state tiles, active tabs, progress fills, selected segments, and primary actions use runtime primary/identity classes; true semantic states use their matching status colors such as error, warning, success, or info; large ordinary surfaces stay neutral and carry only small badges/icons for status; selected/current entity blocks may use eapp-primary-surface.',
-          'Pattern examples: KPI/metric cards should be eapp-surface-card with a small icon tile using eapp-primary-soft eapp-icon-tile; selected/current entity cards may use eapp-primary-surface; progress bars use eapp-surface-muted tracks plus eapp-primary-solid fills; list rows use eapp-surface-card/eapp-divide-y/eapp-surface-hover and only small chips inside; primary scope actions use UButton color="primary" variant="solid"; secondary actions use neutral variants.',
-          'Status colors belong only in UBadge/UAlert semantic colors or eapp-status-*-soft/text/border classes for badges, small icons, or short status text. Do not read --badge-* variables directly in extension templates. Do not color large panels, alert-like success blocks, KPI cards, list containers, or attention/reconciliation blocks green/yellow/red because of state; keep the block neutral and place the status badge/icon inside.',
-          'Use PageHeader gradient: "none" for generated operational pages unless the user explicitly asks for a decorative page accent; do not hardcode cyan/violet/purple/blue/green gradients.',
-          'For general card grids inside the shell, use md:grid-cols-2 xl:grid-cols-3 instead of lg:grid-cols-3 because the desktop sidebar leaves tablet-width content at 1024px.',
-          'Do not use Nuxt UI neutral semantic classes such as bg-default, text-muted, text-dimmed, border-default, or divide-default inside extension code; use eApp class tokens instead. Do not write text-[var(...)], bg-[var(...)], or border-[var(...)] in generated extension templates unless no class token exists for that exact primitive.',
-          'Do not pass ui.content: "eapp-surface-card" to UModal/CommonModal; modal content uses the app modal surface and caller content classes should only append z-index or width.',
-          'CommonModal and CommonDrawer own action-only footers through cancelAction, primaryAction, dangerAction, leadingActions, and footerHint. Pass action intent through props instead of styling footer buttons manually; cancelAction defaults to neutral outline, dangerAction is for irreversible destructive work, and Keep editing should use tone: "primary" in discard dialogs.',
-          'Use UTabs for page sections instead of custom tab bars so the app-level active/inactive indicators, spacing, focus rings, and theme contrast stay consistent.',
-          'Do not inject global CSS, create theme guards, redefine the app palette, or solve one extension by overriding the whole app shell.',
+          'Page extensions should be full-bleed and responsive from the first version; the extension root is already inside the Enfyra admin page main.',
+          'Render ordinary metrics and lists in the body, not PageHeader.stats, unless the user explicitly wants a compact overview header.',
+          'Use app theme tokens and Nuxt UI semantic colors by intent; do not hard-code concrete palettes or redefine the app palette inside extension code.',
+          'Use app-owned primitives such as UTabs, CommonModal, CommonDrawer, Widget, useMenuNotificationRegistry, and useAccountPanelRegistry when the workflow matches them.',
           'Keep list selection local and fetch detail rows only; do not refetch the whole list after a row click unless the list data changed.',
           'Page extension paths are admin app UI routes. Do not verify them with test_rest_endpoint against ENFYRA_API_URL unless inspect_route shows an API route with the same path.',
           'After saving, open Enfyra admin tabs should update through the server/Enfyra admin UI realtime reload contract; do not tell the user to refresh unless that contract is proven broken.',

package/src/lib/mcp-instructions.js

@@ -25,13 +25,14 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### Work Flow',
     '- 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.',
+    '- When the task intent is clear but the right tool path is not, call `discover_enfyra_workflows` with the intent, risk, and optional surface. Use `detail: "plan"` before writes to get firstTools, required acknowledgements, verify tools, and avoidTools.',
     '- 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. 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 mutating metadata, schema, routes, permissions, menus, packages, cache state, dynamic code, or extension UI, call `get_enfyra_required_knowledge`, read the global rules, and pass `globalRulesAckKey` into write tools. Dynamic server code also requires `dynamicCodeAckKey`; extension code also requires `extensionAckKey`.',
     '- With non-root API tokens, call `get_permission_profile` before relying on admin helper tools or when debugging 403s. MCP admin helpers require ordinary route permissions for static admin routes such as `/admin/script/validate`, `/admin/test/run`, `/admin/flow/trigger/:id`, and `/admin/reload/*`.',
-    '- Prefer the most specific business operation tool over raw metadata CRUD: `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `add_route_methods`, `public_route_methods`, `set_table_graphql`, guard/permission/rule tools, websocket tools, flow tools, and `ensure_page_extension`/menu tools.',
+    '- Prefer the most specific business operation tool over raw metadata CRUD. `discover_enfyra_workflows` provides the current operation-tool map and negative-routing avoidTools.',
     '- 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.',

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

@@ -1441,7 +1441,8 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     'create_api_endpoint',
     [
       'Business operation: create or update a custom REST endpoint with a handler in one safe operation.',
-      'Use this when the user asks for a new route/endpoint/API path that computes or orchestrates behavior, such as GET /sum or POST /webhook.',
+      'Prefer api_endpoint_workflow when route access, role/user permissions, overwrite decisions, or multi-step planning matter.',
+      'Use this one-shot helper only when the endpoint contract is already clear and no authenticated route-permission step is needed in the same operation, such as a simple public webhook or private admin-only utility that will be granted separately.',
       'It creates the route without mainTableId, ensures the method is available, validates sourceCode, creates or overwrites the route handler, optionally makes the method public, reloads routes, and can smoke-test the endpoint.',
       'Use table/schema tools separately when the user needs persisted data. This tool is for custom behavior endpoints.',
     ].join(' '),
@@ -1591,8 +1592,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       message: z.string().optional().describe('Custom validation error message.'),
       description: z.string().optional().describe('Admin note.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable the rule.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ tableName, columnName, ruleType, value, message, description, isEnabled }) => {
+    async ({ tableName, columnName, ruleType, value, message, description, isEnabled, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       const table = resolveTable(await getMetadataTables(ENFYRA_API_URL), tableName);
       const column = resolveColumn(table, columnName);
       const existing = await findRecord(ENFYRA_API_URL, 'enfyra_column_rule', {
@@ -1632,8 +1635,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       condition: z.string().optional().describe('Condition JSON object using field permission DSL.'),
       description: z.string().optional().describe('Admin note.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable the permission.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ tableName, columnName, relationName, action, effect, roleId, roleName, allowedUserIds, condition, description, isEnabled }) => {
+    async ({ tableName, columnName, relationName, action, effect, roleId, roleName, allowedUserIds, condition, description, isEnabled, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       if (!!columnName === !!relationName) throw new Error('Provide exactly one of columnName or relationName.');
       assertOneScope({ roleId, roleName, allowedUserIds });
       const [tables, role] = await Promise.all([
@@ -1691,8 +1696,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       description: z.string().optional().describe('Admin note.'),
       rules: z.string().optional().describe('Rules JSON array: [{type, config, priority, isEnabled, description, userIds}].'),
       rulesMode: z.enum(['append', 'replace', 'none']).optional().default('append').describe('append creates rules, replace disables existing rules first, none leaves rules unchanged.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ name, guardId, position, routeId, path, methods, combinator, priority, isGlobal, isEnabled, description, rules, rulesMode }) => {
+    async ({ name, guardId, position, routeId, path, methods, combinator, priority, isGlobal, isEnabled, description, rules, rulesMode, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       if (path && routeId) throw new Error('Provide path or routeId, not both.');
       const ruleInputs = parseJsonArrayArg('rules', rules, []);
       if (position === 'pre_auth') {

package/src/lib/required-knowledge.js

@@ -49,7 +49,7 @@ export function assertExtensionKnowledgeAckIf(condition, key) {
 export function buildRequiredKnowledgePayload() {
   return {
     version: REQUIRED_KNOWLEDGE_VERSION,
-    purpose: 'Read this before mutating Enfyra metadata, schema, routes, permissions, dynamic server code, or extension UI through MCP.',
+    purpose: 'Read this before mutating Enfyra metadata, schema, routes, permissions, menus, packages, cache state, dynamic server code, or extension UI through MCP.',
     globalRulesAckKey: GLOBAL_RULES_ACK_KEY,
     dynamicCodeAckKey: DYNAMIC_CODE_KNOWLEDGE_ACK_KEY,
     extensionAckKey: EXTENSION_KNOWLEDGE_ACK_KEY,

package/src/lib/table-tools.js

@@ -313,7 +313,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, args.tableId);
     if (!tableData) {
-      return { content: [{ type: 'text', text: `Error: Table with ID ${args.tableId} not found.` }] };
+      throw new Error(`Table with ID ${args.tableId} not found.`);
     }
 
     const existingColumns = getPatchableColumns(tableData.columns);
@@ -325,9 +325,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       columnName: args.name,
     });
 
-    return {
-      content: [{ type: 'text', text: `Column "${args.name}" added to table ${args.tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
-    };
+    return jsonContent({
+      action: 'column_created',
+      tableId: args.tableId,
+      columnName: args.name,
+      result,
+    });
     });
   }
 
@@ -341,7 +344,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     const resolvedTargetTableId = resolveTableIdentifierFromMetadata(metadata, targetTableId, 'targetTableId');
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, resolvedSourceTableId);
     if (!tableData) {
-      return { content: [{ type: 'text', text: `Error: Table ${sourceTableId} not found.` }] };
+      throw new Error(`Table ${sourceTableId} not found.`);
     }
     const existingRelations = (tableData.relations || []).map(sanitizeExistingRelationForTablePatch);
     const beforeIds = existingRelations.map((relation) => String(getId(relation))).filter((id) => id !== 'null');
@@ -356,9 +359,11 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       action: 'create',
       propertyName,
     });
-    return {
-      content: [{ type: 'text', text: `Relation created: ${propertyName} (${type}) from table ${resolvedSourceTableId} → ${resolvedTargetTableId}.\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
-    };
+    return jsonContent({
+      action: 'relation_created',
+      relation: { propertyName, type, sourceTableId: resolvedSourceTableId, targetTableId: resolvedTargetTableId },
+      result,
+    });
     });
   }
 
@@ -366,7 +371,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
     if (!tableData) {
-      return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
+      throw new Error(`Table with ID ${tableId} not found.`);
     }
 
     const existingColumns = getPatchableColumns(tableData.columns);
@@ -399,9 +404,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       columnId,
     });
 
-    return {
-      content: [{ type: 'text', text: `Column ${columnId} deleted from table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
-    };
+    return jsonContent({
+      action: 'column_deleted',
+      tableId,
+      columnId,
+      result,
+    });
     });
   }
 
@@ -409,7 +417,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
     if (!tableData) {
-      return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
+      throw new Error(`Table with ID ${tableId} not found.`);
     }
 
     const existingRelations = (tableData.relations || []).map(sanitizeExistingRelationForTablePatch);
@@ -442,9 +450,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       relationId,
     });
 
-    return {
-      content: [{ type: 'text', text: `Relation ${relationId} deleted from table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
-    };
+    return jsonContent({
+      action: 'relation_deleted',
+      tableId,
+      relationId,
+      result,
+    });
     });
   }
 
@@ -613,9 +624,25 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         indexes.length ? `Index group(s): ${indexes.length}.` : null,
         uniques.length ? `Unique group(s): ${uniques.length}.` : null,
       ].filter(Boolean).join(' ');
-      return {
-        content: [{ type: 'text', text: `${colHint}\n${relHint}${constraintHint ? `\n${constraintHint}` : ''}\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
-      };
+      return jsonContent({
+        action: 'table_created',
+        table: { id: createdTableId, name, routePath },
+        summary: {
+          columnCount: userColumns.length + 1,
+          createdColumnCount: userColumns.length,
+          relationCount: userRelations.length,
+          indexGroupCount: indexes.length,
+          uniqueGroupCount: uniques.length,
+        },
+        rest: {
+          base,
+          routePath,
+          operations: ['GET /<table>', 'POST /<table>', 'PATCH /<table>/:id', 'DELETE /<table>/:id'],
+          noGetById: true,
+        },
+        message: [colHint, relHint, constraintHint, restHint].filter(Boolean).join('\n'),
+        result,
+      });
     })
   );
 
@@ -652,9 +679,11 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       if (uniquesJson !== undefined) body.uniques = normalizeConstraintGroups('uniques', parseJsonArrayParam('uniques', uniquesJson));
 
       const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, body);
-      return {
-        content: [{ type: 'text', text: `Table ${tableId} updated.\n\n${JSON.stringify(result, null, 2)}` }],
-      };
+      return jsonContent({
+        action: 'table_updated',
+        tableId,
+        result,
+      });
     })
   );
 
@@ -691,9 +720,11 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       const result = await fetchAPI(ENFYRA_API_URL, `/enfyra_table/${tableId}`, {
         method: 'DELETE',
       });
-      return {
-        content: [{ type: 'text', text: `Table ${tableId} deleted.\n\n${JSON.stringify(result, null, 2)}` }],
-      };
+      return jsonContent({
+        action: 'table_deleted',
+        tableId,
+        result,
+      });
     })
   );
 
@@ -741,7 +772,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       assertGlobalRulesAck(globalRulesAckKey);
       const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
       if (!tableData) {
-        return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
+        throw new Error(`Table with ID ${tableId} not found.`);
       }
 
       const existingColumns = getPatchableColumns(tableData.columns);
@@ -771,9 +802,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         columnId,
       });
 
-      return {
-        content: [{ type: 'text', text: `Column ${columnId} updated on table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
-      };
+      return jsonContent({
+        action: 'column_updated',
+        tableId,
+        columnId,
+        result,
+      });
     })
   );
 

package/src/lib/tool-routing.js

@@ -0,0 +1,581 @@
+export const WORKFLOW_SURFACES = [
+  'api-endpoint',
+  'extension',
+  'schema',
+  'record-data',
+  'dynamic-script',
+  'route-access',
+  'guards-permissions-rules',
+  'flow',
+  'websocket',
+  'graphql',
+  'package',
+  'cache',
+  'logs-debug',
+  'auth-context',
+];
+
+const ALL_DETAILS = ['summary', 'plan', 'full'];
+
+export const TOOL_WORKFLOWS = [
+  {
+    key: 'api-endpoint',
+    title: 'Custom REST endpoint with handler',
+    useWhen: [
+      'Creating or changing a custom API path with handler behavior.',
+      'Changing public/private method access on a custom endpoint.',
+      'Adding route permissions for endpoint access.',
+    ],
+    keywords: ['endpoint', 'api', 'route handler', 'handler', 'webhook', 'custom route', 'rest path'],
+    firstTools: ['get_enfyra_required_knowledge', 'discover_script_contexts', 'inspect_route'],
+    inspectTools: ['inspect_route', 'get_all_routes', 'trace_metadata_usage'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts'],
+    writeTools: ['api_endpoint_workflow', 'create_api_endpoint', 'enable_route', 'public_route_methods', 'private_route_methods', 'ensure_route_access'],
+    verifyTools: ['test_rest_endpoint', 'run_admin_test'],
+    avoidTools: [
+      {
+        tool: 'create_route',
+        when: 'a handler-backed endpoint or route permission plan is needed',
+        useInstead: 'api_endpoint_workflow',
+        reason: 'The workflow validates source, reads live route/handler/access state, applies one safe step at a time, and returns nextSteps.',
+      },
+      {
+        tool: 'create_table',
+        when: 'the user asked for custom behavior at an API path',
+        useInstead: 'api_endpoint_workflow',
+        reason: 'Tables create persisted data models; custom route handlers own behavior endpoints.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'dynamicCodeAckKey when saving handler source'],
+    exampleCategories: ['handlers-hooks', 'permissions-rls'],
+    nextStepTemplate: [
+      'Inspect the route or run api_endpoint_workflow with apply=false.',
+      'Read required knowledge before apply/applyAll.',
+      'Apply one pending step or use applyAll only when the plan is fully understood.',
+      'Verify the endpoint with test_rest_endpoint or run_admin_test.',
+    ],
+  },
+  {
+    key: 'extension',
+    title: 'Admin extension, menu, shell notification, or account panel UI',
+    useWhen: [
+      'Creating or changing Enfyra admin page/widget/global extensions.',
+      'Adding menu entries, menu notification dots/counts, account panel rows, or shell actions.',
+      'Reviewing extension UI theme/layout/component usage.',
+    ],
+    keywords: ['extension', 'menu', 'account panel', 'notification', 'chip', 'badge', 'sidebar', 'shell', 'page ui', 'widget'],
+    firstTools: ['get_enfyra_required_knowledge', 'get_extension_theme_contract', 'inspect_feature'],
+    inspectTools: ['inspect_feature', 'trace_metadata_usage', 'get_script_source'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'get_extension_theme_contract', 'get_theme_class_reference'],
+    writeTools: ['ensure_menu', 'ensure_page_extension', 'ensure_global_extension', 'ensure_widget_extension'],
+    verifyTools: ['validate_extension_code', 'inspect_feature'],
+    avoidTools: [
+      {
+        tool: 'create_record/update_record on enfyra_extension',
+        when: 'creating or changing extension code',
+        useInstead: 'ensure_page_extension, ensure_global_extension, or ensure_widget_extension',
+        reason: 'Ensure tools validate extension code and preserve extension/menu contracts before saving.',
+      },
+      {
+        tool: 'query_table on destination domain lists',
+        when: 'decorating menu/account panel notifications',
+        useInstead: 'notification summary/realtime shell signal plus destination-page fetch on click',
+        reason: 'Shell notifications should not fetch messages, tickets, orders, or jobs lists solely for a badge.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'extensionAckKey when saving extension code'],
+    exampleCategories: ['extensions'],
+    nextStepTemplate: [
+      'Call get_extension_theme_contract before writing or reviewing UI.',
+      'Inspect the existing menu/extension/global shell registration.',
+      'Choose count only when the source already owns an exact count; choose dot/chip for new-attention signals.',
+      'Validate extension code or use an ensure_*_extension tool that validates before saving.',
+    ],
+  },
+  {
+    key: 'schema',
+    title: 'Table, column, relation, validation, or schema metadata change',
+    useWhen: [
+      'Creating or changing tables, columns, relations, indexes, or validation metadata.',
+      'Designing relation direction or inverse relation exposure.',
+      'Changing GraphQL/table schema flags alongside metadata.',
+    ],
+    keywords: ['schema', 'table', 'column', 'relation', 'field', 'index', 'validation', 'inverse'],
+    firstTools: ['get_enfyra_required_knowledge', 'inspect_table', 'get_all_tables'],
+    inspectTools: ['inspect_table', 'get_table_metadata', 'get_all_tables'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'get_enfyra_examples'],
+    writeTools: ['create_table', 'update_table', 'delete_table', 'create_column', 'update_column', 'delete_column', 'create_relation', 'delete_relation', 'ensure_column_rule'],
+    verifyTools: ['inspect_table', 'get_table_metadata'],
+    avoidTools: [
+      {
+        tool: 'create_record/update_record on enfyra_column or enfyra_relation',
+        when: 'changing schema metadata',
+        useInstead: 'table/column/relation schema tools',
+        reason: 'Schema tools resolve table ids, preserve relation contracts, and reject physical FK names.',
+      },
+      {
+        tool: 'manual inversePropertyName',
+        when: 'there is no concrete response/UI/deep-query/aggregate need for reverse traversal',
+        useInstead: 'owning relation only',
+        reason: 'Relation design stays minimal unless the reverse field is actually used.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey'],
+    exampleCategories: ['schema-relations'],
+    nextStepTemplate: [
+      'Inspect the existing table and relations.',
+      'Decide owner relation and whether an inverse is actually needed.',
+      'Apply schema tool changes with globalRulesAckKey.',
+      'Re-inspect metadata instead of assuming the saved shape.',
+    ],
+  },
+  {
+    key: 'record-data',
+    title: 'Route-backed table data query or CRUD',
+    useWhen: [
+      'Reading or mutating normal route-backed records.',
+      'Counting records or finding one row by filter.',
+      'Testing filters, fields, deep relations, pagination, or aggregate query shape.',
+    ],
+    keywords: ['record', 'crud', 'query', 'count', 'filter', 'aggregate', 'deep', 'sort', 'pagination'],
+    firstTools: ['inspect_table', 'discover_query_capabilities'],
+    inspectTools: ['inspect_table', 'get_table_metadata', 'discover_query_capabilities'],
+    knowledgeTools: ['get_enfyra_required_knowledge for writes'],
+    writeTools: ['create_record', 'update_record', 'delete_record'],
+    verifyTools: ['find_one_record', 'query_table', 'count_records'],
+    avoidTools: [
+      {
+        tool: 'query_table without limit or all=true',
+        when: 'listing records',
+        useInstead: 'query_table with a bounded limit or all=true for intentional complete reads',
+        reason: 'List/query tools require explicit paging intent.',
+      },
+      {
+        tool: 'generic CRUD on internal/no-route system tables',
+        when: 'changing schema, sessions, columns, or other no-route internals',
+        useInstead: 'specific schema/platform tools',
+        reason: 'Generic CRUD is for route-backed tables only.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey for writes', 'dynamicCodeAckKey for script-backed sourceCode writes', 'extensionAckKey for extension code writes'],
+    exampleCategories: ['queries-deep'],
+    nextStepTemplate: [
+      'Inspect table metadata and choose fields explicitly.',
+      'Use bounded pagination or all=true deliberately.',
+      'For writes, read required knowledge and use metadata-backed field names only.',
+      'Re-read with explicit fields after mutation when saved shape matters.',
+    ],
+  },
+  {
+    key: 'dynamic-script',
+    title: 'Dynamic server code: handlers, hooks, scripts, or source patches',
+    useWhen: [
+      'Writing or reviewing handler, hook, flow step, websocket, GraphQL, or bootstrap sourceCode.',
+      'Editing an existing script-backed metadata record.',
+      'Debugging macro, repository, or validation behavior.',
+    ],
+    keywords: ['sourcecode', 'script', 'hook', 'pre hook', 'post hook', 'compiledcode', 'macro', 'repos', 'bootstrap'],
+    firstTools: ['get_enfyra_required_knowledge', 'discover_script_contexts', 'trace_metadata_usage'],
+    inspectTools: ['trace_metadata_usage', 'get_script_source', 'discover_script_contexts'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts'],
+    writeTools: ['patch_script_source', 'update_script_source', 'create_handler', 'create_pre_hook', 'create_post_hook', 'api_endpoint_workflow'],
+    verifyTools: ['validate_dynamic_script', 'run_admin_test', 'test_rest_endpoint', 'test_flow_step'],
+    avoidTools: [
+      {
+        tool: 'update_record with compiledCode',
+        when: 'editing dynamic scripts',
+        useInstead: 'patch_script_source or update_script_source with sourceCode',
+        reason: 'compiledCode is generated and may differ because macros expand.',
+      },
+      {
+        tool: 'throw new Error for intentional user/domain failures',
+        when: 'writing generated dynamic server code',
+        useInstead: '@THROW400-style macros or native $ctx.$throw helpers',
+        reason: 'Intentional domain errors should use the platform error contract.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'dynamicCodeAckKey'],
+    exampleCategories: ['handlers-hooks'],
+    nextStepTemplate: [
+      'Discover script context macros for the surface.',
+      'Read existing source through trace_metadata_usage/get_script_source when patching.',
+      'Validate source before save unless the chosen write tool already validates.',
+      'Verify behavior with the route/test runner that matches the script surface.',
+    ],
+  },
+  {
+    key: 'route-access',
+    title: 'Authenticated route access and public/private method state',
+    useWhen: [
+      'Debugging 403/401 route access.',
+      'Granting role/user access to a route method.',
+      'Changing publicMethods or availableMethods.',
+    ],
+    keywords: ['permission', '403', '401', 'role', 'route access', 'public method', 'private method', 'available method'],
+    firstTools: ['get_permission_profile', 'inspect_route', 'audit_route_access'],
+    inspectTools: ['get_permission_profile', 'inspect_route', 'audit_route_access'],
+    knowledgeTools: ['get_enfyra_required_knowledge'],
+    writeTools: ['ensure_route_access', 'add_route_methods', 'replace_route_methods', 'remove_route_methods', 'public_route_methods', 'private_route_methods', 'enable_route', 'disable_route'],
+    verifyTools: ['audit_route_access', 'test_rest_endpoint'],
+    avoidTools: [
+      {
+        tool: 'raw enfyra_route_permission CRUD',
+        when: 'granting route access',
+        useInstead: 'ensure_route_access',
+        reason: 'The operation tool resolves roles/methods and merges existing method grants safely.',
+      },
+      {
+        tool: 'public_route_methods',
+        when: 'the desired behavior is authenticated user access',
+        useInstead: 'ensure_route_access',
+        reason: 'publicMethods grants anonymous access; route permissions grant authenticated access.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey for writes'],
+    exampleCategories: ['permissions-rls'],
+    nextStepTemplate: [
+      'Inspect route and permission profile before changing access.',
+      'Decide anonymous publicMethods versus authenticated route permission.',
+      'Use route operation tools instead of raw permission CRUD.',
+      'Audit and test the route after the change.',
+    ],
+  },
+  {
+    key: 'guards-permissions-rules',
+    title: 'Guards, field permissions, and column validation rules',
+    useWhen: [
+      'Adding route guards, guard rules, field permissions, or column rules.',
+      'Restricting field read/write behavior.',
+      'Adding body validation rules at metadata level.',
+    ],
+    keywords: ['guard', 'field permission', 'column rule', 'validation rule', 'rule', 'rls'],
+    firstTools: ['get_enfyra_required_knowledge', 'inspect_table', 'inspect_route'],
+    inspectTools: ['inspect_table', 'inspect_route', 'discover_query_capabilities'],
+    knowledgeTools: ['get_enfyra_required_knowledge'],
+    writeTools: ['ensure_guard', 'ensure_field_permission', 'ensure_column_rule'],
+    verifyTools: ['test_rest_endpoint', 'query_table', 'run_admin_test'],
+    avoidTools: [
+      {
+        tool: 'raw create_record on guard/rule tables',
+        when: 'a dedicated ensure_* operation exists',
+        useInstead: 'ensure_guard, ensure_field_permission, or ensure_column_rule',
+        reason: 'Ensure tools resolve ids and preserve the current rule contract.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey'],
+    exampleCategories: ['permissions-rls', 'schema-relations'],
+    nextStepTemplate: [
+      'Inspect the target table/route and decide the security boundary first.',
+      'Use the specific ensure_* operation for the rule surface.',
+      'Verify with the route/query behavior the rule is meant to protect.',
+    ],
+  },
+  {
+    key: 'flow',
+    title: 'Flow, scheduled/manual flow, or flow step',
+    useWhen: [
+      'Creating or changing manual/scheduled flows.',
+      'Choosing or writing a flow step.',
+      'Testing or triggering a flow.',
+    ],
+    keywords: ['flow', 'scheduled', 'manual flow', 'flow step', 'trigger flow', 'workflow'],
+    firstTools: ['get_enfyra_required_knowledge', 'choose_flow_step_tool', 'discover_script_contexts'],
+    inspectTools: ['inspect_feature', 'query_table'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts'],
+    writeTools: ['ensure_manual_flow', 'ensure_scheduled_flow', 'ensure_query_flow_step', 'ensure_create_flow_step', 'ensure_update_flow_step', 'ensure_delete_flow_step', 'ensure_http_flow_step', 'ensure_sleep_flow_step', 'ensure_trigger_flow_step', 'ensure_log_flow_step', 'ensure_condition_flow_step', 'ensure_script_flow_step'],
+    verifyTools: ['test_flow_step', 'run_admin_test', 'trigger_flow'],
+    avoidTools: [
+      {
+        tool: 'ensure_script_flow_step',
+        when: 'a fixed query/create/update/delete/http/sleep/trigger/log step can express the operation',
+        useInstead: 'choose_flow_step_tool then the fixed-type ensure_*_flow_step',
+        reason: 'Atomic step types are easier to inspect, test, and maintain than oversized scripts.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'dynamicCodeAckKey for script or condition source'],
+    exampleCategories: ['flows'],
+    nextStepTemplate: [
+      'Use choose_flow_step_tool before mutating when step type is unclear.',
+      'Prefer fixed-type flow step tools over script steps.',
+      'Validate/test script or condition steps before relying on the flow.',
+      'Trigger manually only after the saved steps are verified.',
+    ],
+  },
+  {
+    key: 'websocket',
+    title: 'Socket.IO gateway or websocket event',
+    useWhen: [
+      'Creating or changing websocket gateways/events.',
+      'Writing websocket handler source.',
+      'Testing websocket event logic.',
+    ],
+    keywords: ['websocket', 'socket', 'socket.io', 'gateway', 'realtime', 'room'],
+    firstTools: ['get_enfyra_required_knowledge', 'discover_script_contexts', 'inspect_feature'],
+    inspectTools: ['inspect_feature', 'discover_script_contexts'],
+    knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts'],
+    writeTools: ['ensure_websocket_gateway', 'ensure_websocket_event'],
+    verifyTools: ['run_admin_test'],
+    avoidTools: [
+      {
+        tool: 'raw CRUD on enfyra_websocket_event',
+        when: 'saving websocket event source',
+        useInstead: 'ensure_websocket_event',
+        reason: 'The operation tool validates script source and preserves gateway/event linkage.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey', 'dynamicCodeAckKey when saving event source'],
+    exampleCategories: ['websocket'],
+    nextStepTemplate: [
+      'Discover websocket script context before writing source.',
+      'Ensure gateway first, then event.',
+      'Use run_admin_test for event/connection scripts where possible.',
+    ],
+  },
+  {
+    key: 'graphql',
+    title: 'GraphQL enablement and query surface',
+    useWhen: [
+      'Enabling/disabling GraphQL for a table.',
+      'Checking GraphQL endpoint/schema behavior.',
+      'Clarifying REST route methods versus GraphQL table exposure.',
+    ],
+    keywords: ['graphql', 'gql', 'schema endpoint'],
+    firstTools: ['discover_enfyra_system', 'inspect_table'],
+    inspectTools: ['discover_enfyra_system', 'inspect_table'],
+    knowledgeTools: ['get_enfyra_required_knowledge for writes'],
+    writeTools: ['set_table_graphql', 'update_table'],
+    verifyTools: ['reload_graphql', 'discover_enfyra_system'],
+    avoidTools: [
+      {
+        tool: 'public_route_methods',
+        when: 'trying to expose GraphQL table data',
+        useInstead: 'set_table_graphql plus GraphQL auth planning',
+        reason: 'REST publicMethods do not make GraphQL table data anonymous.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey for writes'],
+    exampleCategories: ['queries-deep'],
+    nextStepTemplate: [
+      'Inspect the table and GraphQL enablement state.',
+      'Use set_table_graphql for enablement changes.',
+      'Remember GraphQL table data requires Bearer auth even when REST is public.',
+    ],
+  },
+  {
+    key: 'package',
+    title: 'Runtime package install or package-backed extension/script support',
+    useWhen: [
+      'Installing npm packages for dynamic code or extension runtime use.',
+      'Checking package availability before using getPackages in extensions.',
+    ],
+    keywords: ['package', 'npm', 'install', 'dependency', 'getpackages'],
+    firstTools: ['search_npm', 'get_enfyra_required_knowledge'],
+    inspectTools: ['search_npm', 'query_table'],
+    knowledgeTools: ['get_enfyra_required_knowledge'],
+    writeTools: ['install_package'],
+    verifyTools: ['query_table'],
+    avoidTools: [
+      {
+        tool: 'raw create_record on enfyra_package',
+        when: 'installing packages',
+        useInstead: 'install_package',
+        reason: 'The package tool resolves package metadata and avoids duplicate package records.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey'],
+    exampleCategories: ['extensions', 'handlers-hooks'],
+    nextStepTemplate: [
+      'Search package metadata first.',
+      'Install with install_package and globalRulesAckKey.',
+      'Use getPackages inside extension runtime code rather than static imports.',
+    ],
+  },
+  {
+    key: 'cache',
+    title: 'Cache reload or stale metadata/runtime diagnosis',
+    useWhen: [
+      'Diagnosing stale routes, metadata, GraphQL, or full runtime cache.',
+      'Manually reloading only after natural partial reload appears stale.',
+    ],
+    keywords: ['cache', 'reload', 'stale', 'refresh metadata', 'reload routes'],
+    firstTools: ['inspect_table', 'inspect_route', 'get_enfyra_api_context'],
+    inspectTools: ['inspect_table', 'inspect_route', 'get_enfyra_api_context'],
+    knowledgeTools: ['get_enfyra_required_knowledge for manual reloads'],
+    writeTools: ['reload_metadata', 'reload_routes', 'reload_graphql', 'reload_all'],
+    verifyTools: ['inspect_table', 'inspect_route', 'discover_enfyra_system'],
+    avoidTools: [
+      {
+        tool: 'manual reload tools',
+        when: 'a successful metadata mutation already triggered natural partial reload and no stale evidence exists',
+        useInstead: 'verify behavior first with inspect/test tools',
+        reason: 'Manual reloads should be evidence-driven, not reflexive.',
+      },
+    ],
+    requiredAck: ['globalRulesAckKey for manual reload tools'],
+    exampleCategories: [],
+    nextStepTemplate: [
+      'Verify stale behavior with narrow inspect/test tools.',
+      'Choose the narrowest reload surface if stale evidence exists.',
+      'Re-verify the same narrow behavior after reload.',
+    ],
+  },
+  {
+    key: 'logs-debug',
+    title: 'Logs, runtime diagnostics, and test runner debugging',
+    useWhen: [
+      'Reading app/error logs.',
+      'Searching logs for route, flow, websocket, or dynamic script failures.',
+      'Running admin tests for supported runtime surfaces.',
+    ],
+    keywords: ['log', 'debug', 'error', 'trace', 'tail', 'diagnostic', 'test runner'],
+    firstTools: ['get_log_files', 'search_logs'],
+    inspectTools: ['get_log_files', 'get_log_content', 'tail_log', 'search_logs'],
+    knowledgeTools: [],
+    writeTools: [],
+    verifyTools: ['run_admin_test', 'test_flow_step', 'test_rest_endpoint'],
+    avoidTools: [
+      {
+        tool: 'broad metadata discovery',
+        when: 'the problem is a concrete runtime error with known log text',
+        useInstead: 'search_logs or tail_log',
+        reason: 'Log tools are narrower and cheaper for runtime debugging.',
+      },
+    ],
+    requiredAck: [],
+    exampleCategories: [],
+    nextStepTemplate: [
+      'Search or tail the narrowest log first.',
+      'Use the matching test tool to reproduce once the failing surface is known.',
+      'Patch only after the failing step is identified.',
+    ],
+  },
+  {
+    key: 'auth-context',
+    title: 'MCP target, auth token, current user, and permission profile',
+    useWhen: [
+      'Confirming which Enfyra instance MCP is connected to.',
+      'Debugging API-token exchange or current MCP user permissions.',
+      'Checking whether non-root tokens can call admin helper routes.',
+    ],
+    keywords: ['auth', 'token', 'current user', 'permission profile', 'target', 'api base', '403', 'exchange'],
+    firstTools: ['get_enfyra_api_context', 'get_current_user', 'get_permission_profile'],
+    inspectTools: ['get_enfyra_api_context', 'get_current_user', 'get_permission_profile'],
+    knowledgeTools: [],
+    writeTools: ['login'],
+    verifyTools: ['get_current_user', 'get_permission_profile'],
+    avoidTools: [
+      {
+        tool: 'discover_enfyra_system',
+        when: 'only confirming the connected API base',
+        useInstead: 'get_enfyra_api_context',
+        reason: 'Target sanity checks should be cheap and should not load broad metadata.',
+      },
+    ],
+    requiredAck: [],
+    exampleCategories: ['ssr-app-auth', 'oauth-setup'],
+    nextStepTemplate: [
+      'Use get_enfyra_api_context for target sanity checks.',
+      'Use get_permission_profile before assuming admin helper route access with non-root tokens.',
+      'Use login only when an interactive credential login is explicitly needed.',
+    ],
+  },
+];
+
+function compactWorkflow(workflow) {
+  return {
+    key: workflow.key,
+    title: workflow.title,
+    useWhen: workflow.useWhen,
+  };
+}
+
+function planWorkflow(workflow) {
+  return {
+    ...compactWorkflow(workflow),
+    firstTools: workflow.firstTools,
+    inspectTools: workflow.inspectTools,
+    knowledgeTools: workflow.knowledgeTools,
+    writeTools: workflow.writeTools,
+    verifyTools: workflow.verifyTools,
+    requiredAck: workflow.requiredAck,
+    exampleCategories: workflow.exampleCategories,
+    nextSteps: workflow.nextStepTemplate,
+    avoidTools: workflow.avoidTools,
+  };
+}
+
+function fullWorkflow(workflow) {
+  return {
+    ...planWorkflow(workflow),
+    keywords: workflow.keywords,
+  };
+}
+
+function normalize(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function scoreWorkflow(workflow, { intent, surface, risk }) {
+  let score = 0;
+  const text = normalize(intent);
+  if (surface && workflow.key === surface) score += 20;
+  if (surface && workflow.key.includes(surface)) score += 8;
+  if (text) {
+    for (const keyword of workflow.keywords || []) {
+      if (text.includes(keyword)) score += 4;
+    }
+    for (const phrase of workflow.useWhen || []) {
+      const words = normalize(phrase).split(/\W+/).filter((word) => word.length > 3);
+      if (words.some((word) => text.includes(word))) score += 1;
+    }
+  }
+  if (risk === 'debug' && workflow.key === 'logs-debug') score += 6;
+  if (risk === 'write' && workflow.writeTools.length) score += 2;
+  if (risk === 'destructive' && workflow.avoidTools.some((item) => normalize(item.when).includes('delete'))) score += 2;
+  return score;
+}
+
+export function listWorkflowSurfaces() {
+  return TOOL_WORKFLOWS.map(compactWorkflow);
+}
+
+export function discoverWorkflowRoutes({
+  intent = '',
+  surface,
+  risk = 'unknown',
+  detail = 'summary',
+  limit = 5,
+} = {}) {
+  const normalizedSurface = surface ? normalize(surface) : undefined;
+  const normalizedDetail = ALL_DETAILS.includes(detail) ? detail : 'summary';
+  const normalizedRisk = normalize(risk) || 'unknown';
+  const formatter = normalizedDetail === 'full'
+    ? fullWorkflow
+    : normalizedDetail === 'plan'
+      ? planWorkflow
+      : compactWorkflow;
+  const scored = TOOL_WORKFLOWS
+    .map((workflow) => ({ workflow, score: scoreWorkflow(workflow, { intent, surface: normalizedSurface, risk: normalizedRisk }) }))
+    .filter((item) => !normalizedSurface || item.workflow.key === normalizedSurface || item.score > 0)
+    .sort((a, b) => b.score - a.score || a.workflow.key.localeCompare(b.workflow.key));
+  const selected = (scored.length ? scored : TOOL_WORKFLOWS.map((workflow) => ({ workflow, score: 0 })))
+    .slice(0, Math.max(1, Math.min(Number(limit) || 5, 10)));
+  return {
+    action: 'enfyra_workflows_discovered',
+    intent: intent || null,
+    requestedSurface: surface || null,
+    risk: normalizedRisk,
+    detail: normalizedDetail,
+    matchedWorkflowCount: scored.length,
+    workflows: selected.map((item) => ({
+      score: item.score,
+      ...formatter(item.workflow),
+    })),
+    surfaces: normalizedDetail === 'summary' ? WORKFLOW_SURFACES : undefined,
+    guidance: [
+      'Use this as progressive disclosure: pick the closest workflow, then call its firstTools instead of loading every Enfyra tool/example.',
+      'For writes, call get_enfyra_required_knowledge and pass the returned acknowledgement keys into write tools.',
+      'Treat avoidTools as negative routing boundaries; they prevent near-correct tool choices from crossing the wrong platform contract.',
+    ],
+  };
+}

package/src/mcp-server-entry.mjs

@@ -20,6 +20,7 @@ import { exchangeApiToken, refreshAccessToken, getValidToken, resetTokens, getTo
 import { fetchAPI, validateFilter, validateTableName } from './lib/fetch.js';
 import { buildMcpServerInstructions, buildGraphqlUrls } from './lib/mcp-instructions.js';
 import { getExamples, listExampleCategories } from './lib/mcp-examples.js';
+import { WORKFLOW_SURFACES, discoverWorkflowRoutes } from './lib/tool-routing.js';
 import { registerTableTools } from './lib/table-tools.js';
 import { registerPlatformOperationTools } from './lib/platform-operation-tools.js';
 import { parseRecordData, prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
@@ -331,7 +332,7 @@ function summarizeRoutes(routesResult) {
   }));
 }
 
-function summarizeMetadata(metadata, { search, limit } = {}) {
+function summarizeMetadata(metadata, { search, limit, all = false } = {}) {
   const tables = normalizeTables(metadata);
   const q = search ? search.toLowerCase() : null;
   const summarized = tables.map((table) => ({
@@ -346,11 +347,13 @@ function summarizeMetadata(metadata, { search, limit } = {}) {
   const matched = q
     ? summarized.filter((table) => JSON.stringify(table).toLowerCase().includes(q))
     : summarized;
-  const outputLimit = limit || 30;
+  const outputLimit = all ? matched.length : (limit || 30);
   return {
     tableCount: tables.length,
     matchedTableCount: matched.length,
     returnedTableCount: Math.min(matched.length, outputLimit),
+    complete: all || outputLimit >= matched.length,
+    hardCap: all ? null : outputLimit,
     search: search || null,
     tables: matched.slice(0, outputLimit),
   };
@@ -807,15 +810,21 @@ server.tool('get_all_metadata', 'Get concise metadata summary for all tables. Us
   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.'),
   limit: z.number().optional().describe('Maximum tables returned after search. Default 30.'),
-}, async ({ includeFull, search, limit }) => {
+  all: z.boolean().optional().default(false).describe('Return every matched table summary. Use when a complete table list is required.'),
+}, async ({ includeFull, search, limit, all }) => {
+  if (all && limit !== undefined) {
+    throw new Error('get_all_metadata accepts either all=true or limit, not both.');
+  }
   const result = await fetchAPI(ENFYRA_API_URL, '/metadata');
   const payload = includeFull
     ? result
     : {
         statusCode: result?.statusCode,
         success: result?.success,
-        ...summarizeMetadata(result, { search, limit }),
-        detailHint: 'Default response is capped and minimal. Call get_table_metadata({ tableName }) or inspect_table({ tableName }) for columns, relations, and route context.',
+        ...summarizeMetadata(result, { search, limit, all }),
+        detailHint: all
+          ? 'Complete summary returned. Call get_table_metadata({ tableName }) or inspect_table({ tableName }) for columns, relations, and route context.'
+          : 'Default response is capped and minimal. Pass all=true for a complete summary, or call get_table_metadata({ tableName }) / inspect_table({ tableName }) for detail.',
       };
   return jsonContent(payload);
 });
@@ -852,6 +861,23 @@ server.tool(
   },
 );
 
+server.tool(
+  'discover_enfyra_workflows',
+  [
+    'Progressive-disclosure router for the Enfyra MCP tool surface.',
+    'Call this when the task intent is clear but the right Enfyra tool path is not.',
+    'Returns matched workflows, first tools, required acknowledgement keys, verification tools, and avoidTools negative-routing boundaries.',
+  ].join(' '),
+  {
+    intent: z.string().optional().describe('Plain-language task goal, e.g. "add a menu chip when support tickets arrive".'),
+    surface: z.enum(WORKFLOW_SURFACES).optional().describe('Known surface when the caller can classify the task. Omit to infer from intent.'),
+    risk: z.enum(['read', 'write', 'destructive', 'debug', 'unknown']).optional().default('unknown').describe('Highest expected operation risk.'),
+    detail: z.enum(['summary', 'plan', 'full']).optional().default('summary').describe('summary lists candidate workflows; plan adds tool sequence and avoidTools; full also includes matching keywords.'),
+    limit: z.number().int().positive().max(10).optional().default(5).describe('Maximum workflows to return.'),
+  },
+  async (input) => jsonContent(discoverWorkflowRoutes(input)),
+);
+
 server.tool(
   'discover_enfyra_system',
   [
@@ -2109,16 +2135,11 @@ server.tool(
     tableName: z.string().describe('Table name or alias to inspect'),
   },
   async ({ tableName }) => {
-    let state = await collectRestDefinitionState();
-    let table = state.tables.find((item) => item?.name === tableName || item?.alias === tableName);
+    const state = await collectRestDefinitionState();
+    const table = state.tables.find((item) => item?.name === tableName || item?.alias === tableName);
     if (!table) {
-      await fetchAPI(ENFYRA_API_URL, '/admin/reload/metadata', { method: 'POST' }).catch(() => {});
-      await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
-      await new Promise((resolve) => setTimeout(resolve, 150));
-      state = await collectRestDefinitionState();
-      table = state.tables.find((item) => item?.name === tableName || item?.alias === tableName);
+      throw new Error(`Unknown table "${tableName}". Use get_all_tables({ search, limit }) or get_all_metadata({ search, all: true }) to confirm the table name. If a just-created table is missing, verify the create response/reload event before calling manual reload tools.`);
     }
-    if (!table) throw new Error(`Unknown table "${tableName}"`);
     const tableId = getId(table);
     const columnIds = new Set((table.columns || []).map((column) => String(getId(column))));
     const relationIds = new Set((table.relations || []).map((relation) => String(getId(relation))));
@@ -2420,7 +2441,7 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Every
   const queryParams = new URLSearchParams({
     filter: JSON.stringify(filter),
     fields: 'id,path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled',
-    limit: '1000',
+    limit: all ? '0' : '1000',
   });
   const result = await fetchAPI(ENFYRA_API_URL, `/enfyra_route?${queryParams.toString()}`);
   const q = search ? search.toLowerCase() : null;
@@ -2439,6 +2460,8 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Every
     matchedRouteCount: matchedRoutes.length,
     returnedRouteCount: Math.min(matchedRoutes.length, routeLimit),
     all: !!all,
+    complete: all || routeLimit >= matchedRoutes.length,
+    hardCap: all ? null : routeLimit,
     search: search || null,
     routes: matchedRoutes.slice(0, routeLimit),
     detailHint: matchedRoutes.length > routeLimit
@@ -2885,7 +2908,7 @@ server.tool('reload_all', 'Reload all caches (metadata, routes, GraphQL)', {
 }, async ({ globalRulesAckKey }) => {
   assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload', { method: 'POST' });
-  return { content: [{ type: 'text', text: `System reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_all', result });
 });
 
 server.tool('reload_metadata', 'Reload metadata cache only', {
@@ -2893,7 +2916,7 @@ server.tool('reload_metadata', 'Reload metadata cache only', {
 }, async ({ globalRulesAckKey }) => {
   assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/metadata', { method: 'POST' });
-  return { content: [{ type: 'text', text: `Metadata reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_metadata', result });
 });
 
 server.tool('reload_routes', 'Reload routes cache only', {
@@ -2901,7 +2924,7 @@ server.tool('reload_routes', 'Reload routes cache only', {
 }, async ({ globalRulesAckKey }) => {
   assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' });
-  return { content: [{ type: 'text', text: `Routes reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_routes', result });
 });
 
 server.tool('reload_graphql', 'Reload GraphQL schema', {
@@ -2909,7 +2932,7 @@ server.tool('reload_graphql', 'Reload GraphQL schema', {
 }, async ({ globalRulesAckKey }) => {
   assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/graphql', { method: 'POST' });
-  return { content: [{ type: 'text', text: `GraphQL reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_graphql', result });
 });
 
 // ============================================================================
@@ -3080,12 +3103,15 @@ server.tool(
     const checkFilter = JSON.stringify({ name: { _eq: name }, type: { _eq: type } });
     const existing = await fetchAPI(ENFYRA_API_URL, `/enfyra_package?filter=${encodeURIComponent(checkFilter)}&limit=1`);
     if (existing.data && existing.data.length > 0) {
-      return {
-        content: [{
-          type: 'text',
-          text: `Package "${name}" is already installed (version: ${existing.data[0].version}, type: ${existing.data[0].type}).\n${JSON.stringify(existing.data[0], null, 2)}`,
-        }],
-      };
+      return jsonContent({
+        action: 'package_already_installed',
+        package: {
+          name,
+          version: existing.data[0].version,
+          type: existing.data[0].type,
+        },
+        record: existing.data[0],
+      });
     }
 
     // Step 3: Get current user for installedBy
@@ -3107,12 +3133,11 @@ server.tool(
       body: JSON.stringify(body),
     });
 
-    return {
-      content: [{
-        type: 'text',
-        text: `Package "${name}@${pkgVersion}" installed successfully (type: ${type}).\n${JSON.stringify(result, null, 2)}`,
-      }],
-    };
+    return jsonContent({
+      action: 'package_installed',
+      package: { name, version: pkgVersion, type },
+      result,
+    });
   },
 );