@enfyra/mcp-server 0.1.69 → 0.1.71

package/dist/lib/workflow-definitions.js

@@ -0,0 +1,703 @@
+export const WORKFLOW_SURFACES = [
+    'api-endpoint',
+    'extension',
+    'schema',
+    'record-data',
+    'dynamic-script',
+    'route-access',
+    'guards-permissions-rules',
+    'flow',
+    'websocket',
+    'graphql',
+    'storage-file',
+    'oauth',
+    'identity-access',
+    'platform-config',
+    'package',
+    'cache',
+    'logs-debug',
+    'auth-context',
+];
+export const ALL_DETAILS = ['summary', 'plan', 'full'];
+export const WORKFLOW_SURFACES_BY_PROFILE = {
+    extension: ['extension'],
+    schema: ['schema', 'record-data'],
+    runtime: ['api-endpoint', 'dynamic-script', 'route-access', 'guards-permissions-rules', 'flow', 'websocket', 'graphql'],
+    operations: ['storage-file', 'oauth', 'identity-access', 'platform-config', 'package', 'cache', 'logs-debug', 'auth-context'],
+};
+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.',
+            'Exposing a third-party or external integration contract whose policy must not change canonical table CRUD.',
+        ],
+        keywords: ['endpoint', 'api', 'route handler', 'handler', 'webhook', 'custom route', 'rest path', 'third-party api', 'third party api', 'external integration'],
+        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_tables',
+                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.',
+            },
+            {
+                tool: 'create_pre_hook',
+                when: 'the requirement is third-party-only owner/tenant/business policy',
+                useInstead: 'api_endpoint_workflow with policy in the handler',
+                reason: 'A canonical route pre-hook affects every consumer of that canonical CRUD route, including eApp. Keep endpoint-specific policy inside the separate endpoint contract.',
+            },
+        ],
+        requiredAck: ['globalRulesAckKey', 'dynamicCodeAckKey when saving handler source'],
+        exampleCategories: ['handlers-hooks', 'permissions-rls'],
+        nextStepTemplate: [
+            'For an ambiguous, high-risk, or approval-gated change, inspect the route or run api_endpoint_workflow with apply=false.',
+            'Read required knowledge before applying.',
+            'Use secure explicit repositories in custom handlers, inspect their live metadata, and keep TypeORM-style data: @BODY unless the business contract requires validation or server-owned field overrides.',
+            'For a fully specified non-destructive endpoint, use applyAll after the required narrow reads; otherwise apply one reviewed pending step.',
+            'Verify the endpoint with test_rest_endpoint or run_admin_test.',
+        ],
+        recommendedScope: 'dynamic-code',
+    },
+    {
+        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', 'search_admin_extensions'],
+        inspectTools: ['search_admin_extensions(mode=search)', 'search_admin_extensions(mode=inspect)', 'search_runtime_zone(mode=search, zone=admin_ui)'],
+        knowledgeTools: ['get_enfyra_required_knowledge', 'get_extension_theme_contract', 'build_extension_ui'],
+        writeTools: ['extension_workflow', 'ensure_menu', 'reorder_menus', 'patch_extension_code', 'update_extension_code', 'ensure_page_extension', 'ensure_global_extension', 'ensure_widget_extension', 'delete_records'],
+        verifyTools: ['verify_extension_runtime', 'build_extension_ui(kind=runtime_review|theme_review|review)', 'search_admin_extensions(mode=search)', 'search_runtime_zone(mode=search, zone=admin_ui)'],
+        avoidTools: [
+            {
+                tool: 'create_records/update_records on enfyra_extension',
+                when: 'creating or changing extension code',
+                useInstead: 'update_extension_code for an existing extension id/name, or extension_workflow/ensure_*_extension for create/wire flows',
+                reason: 'Extension operation tools validate local guards plus /enfyra_extension/preview and save only after validation succeeds.',
+            },
+            {
+                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.',
+            },
+            {
+                tool: 'update_records/PATCH enfyra_menu for order or parent changes',
+                when: 'drag-and-drop or programmatic menu ordering changes sibling order or parent',
+                useInstead: 'reorder_menus',
+                reason: 'The Enfyra 2.2.6 /admin/menu/reorder route validates menu hierarchy constraints and emits menu cache invalidation.',
+            },
+        ],
+        requiredAck: ['globalRulesAckKey', 'extensionAckKey when saving extension code'],
+        exampleCategories: ['extensions'],
+        nextStepTemplate: [
+            'Call get_extension_theme_contract before writing or reviewing UI.',
+            'Use search_admin_extensions to locate the existing menu/extension/global shell registration, then inspect one candidate before editing.',
+            'Use extension_workflow with apply=false only when page/menu wiring is ambiguous or needs approval; use applyAll after narrow inspection when the requested create/wire contract is fully specified.',
+            'Use reorder_menus for menu order/parent changes instead of patching individual enfyra_menu records.',
+            'For temporary extension cleanup, inspect the exact extension id, preview delete_records on enfyra_extension with confirm=false, repeat with confirm=true, then verify absence with search_admin_extensions.',
+            '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.',
+        ],
+        recommendedScope: 'extension',
+    },
+    {
+        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', 'get_schema_design_context', 'inspect_table', 'get_all_tables'],
+        inspectTools: ['get_schema_design_context', 'inspect_table', 'get_table_metadata', 'get_all_tables'],
+        knowledgeTools: ['get_enfyra_required_knowledge', 'get_schema_design_context', 'get_enfyra_examples'],
+        writeTools: ['create_tables', 'update_tables', 'delete_tables', 'create_columns', 'update_columns', 'delete_columns', 'create_relations', 'delete_relations', 'ensure_column_rule'],
+        verifyTools: ['inspect_table', 'get_table_metadata'],
+        avoidTools: [
+            {
+                tool: 'create_records/update_records 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: [
+            'Call get_schema_design_context and read liveColumnTypes plus metadata input attributes before choosing column/table/relation shapes.',
+            '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.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        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'],
+        writeTools: ['create_records', 'update_records', 'delete_records'],
+        verifyTools: ['find_one_record', 'query_table', 'count_records', 'debug_field_exposure'],
+        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: 'single-record CRUD tools',
+                when: 'creating, updating, or deleting one row',
+                useInstead: 'plural tools with a one-item array',
+                reason: 'MCP write tools are bulk envelopes; they accept native arrays, preflight arrays, and run sequentially even for one item.',
+            },
+            {
+                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.',
+            },
+            {
+                tool: 'route-local pre-hook or frontend hiding',
+                when: 'REST fields/deep appears to return an isPublished=false field',
+                useInstead: 'debug_field_exposure',
+                reason: 'Unpublished field exposure is a core contract issue; first produce a compact repro and escalation shape.',
+            },
+        ],
+        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 suspected hidden/private field leaks through fields/deep, run debug_field_exposure and escalate core exposure instead of patching UI/hooks.',
+            'For writes, read required knowledge and use plural mutation tools with native array inputs, even for one item.',
+            'Re-read with explicit fields after mutation when saved shape matters.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        key: 'dynamic-script',
+        title: 'Dynamic server code: handlers, hooks, scripts, or source patches',
+        useWhen: [
+            'Writing or reviewing handler, hook, flow step, websocket, 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', 'build_dynamic_repository_usage', 'search_runtime_zone'],
+        inspectTools: ['search_runtime_zone(mode=search, zone=api_runtime|flow_runtime|websocket_runtime)', 'search_runtime_zone(mode=inspect)', 'trace_metadata_usage', 'discover_script_contexts'],
+        knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts', 'build_dynamic_repository_usage'],
+        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_records 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.',
+            'Generate repository access with build_dynamic_repository_usage instead of composing secure/trusted syntax from memory.',
+            'Use the source artifact returned by search_runtime_zone(mode=inspect) or trace_metadata_usage 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.',
+        ],
+        recommendedScope: 'dynamic-code',
+    },
+    {
+        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.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        key: 'guards-permissions-rules',
+        title: 'Guards, field permissions, and column validation rules',
+        useWhen: [
+            'Adding route guards, guard rules, field permissions, or column rules.',
+            'Adding request rate limits or throttling to a route.',
+            'Restricting field read/write behavior.',
+            'Adding body validation rules at metadata level.',
+        ],
+        keywords: ['guard', 'rate limit', 'throttle', '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_route_rate_limit', 'ensure_guard', 'ensure_field_permission', 'ensure_column_rule', 'create_pre_hook'],
+        verifyTools: ['test_rest_endpoint', 'query_table', 'run_admin_test'],
+        avoidTools: [
+            {
+                tool: 'raw create_records on guard/rule tables',
+                when: 'a dedicated ensure_* operation exists',
+                useInstead: 'ensure_route_rate_limit, ensure_guard, ensure_field_permission, or ensure_column_rule',
+                reason: 'Ensure tools resolve ids and preserve the current rule contract.',
+            },
+            {
+                tool: 'create_pre_hook',
+                when: 'the requirement is request throttling or rate limiting',
+                useInstead: 'ensure_route_rate_limit',
+                reason: 'Rate limits belong to the built-in guard engine, not custom pre-hook scripts.',
+            },
+            {
+                tool: 'ensure_field_permission',
+                when: 'the requirement is owner/tenant row scoping or RLS query filtering',
+                useInstead: 'create_pre_hook for canonical shared policy, or api_endpoint_workflow for third-party-only policy',
+                reason: 'Field permissions protect field visibility. Canonical shared row ownership belongs in a route pre-hook; endpoint-specific ownership belongs in the custom handler.',
+            },
+        ],
+        requiredAck: ['globalRulesAckKey'],
+        exampleCategories: ['permissions-rls', 'schema-relations'],
+        nextStepTemplate: [
+            'Inspect the target table/route and decide the security boundary first.',
+            'Use a canonical route pre-hook for row filters shared by every canonical CRUD consumer. Use api_endpoint_workflow when the owner/tenant/business policy belongs only to a third-party custom contract.',
+            'Use the specific ensure_* operation for guard, field, or column rule surfaces.',
+            'Verify with the route/query behavior the rule is meant to protect.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        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', 'flow_workflow', 'plan_flow_steps', 'discover_script_contexts'],
+        inspectTools: ['inspect_feature', 'query_table'],
+        knowledgeTools: ['get_enfyra_required_knowledge', 'discover_script_contexts'],
+        writeTools: ['flow_workflow', 'plan_flow_steps'],
+        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: 'flow_workflow or plan_flow_steps',
+                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 flow_workflow with apply=false for multi-step flows; use plan_flow_steps only for dry-run step selection.',
+            'Prefer fixed step types for static config. Fixed-step config is not template-transformed; use one focused script step for @FLOW_PAYLOAD/@FLOW_LAST/@FLOW values.',
+            'In scripts call @LOGS(message, details?); @LOGS has no .info/.warn/.error/.debug methods.',
+            'Validate/test script or condition steps before relying on the flow.',
+            'Trigger manually only after the saved steps are verified.',
+        ],
+        recommendedScope: 'flow',
+    },
+    {
+        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(kind=websocket_event|websocket_connection) to capture emitted calls. This validates runtime script behavior but does not prove a real Socket.IO client transport/handshake.',
+        ],
+        recommendedScope: 'dynamic-code',
+    },
+    {
+        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'],
+        writeTools: ['set_table_graphql', 'update_tables'],
+        verifyTools: ['test_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: ['graphql'],
+        nextStepTemplate: [
+            'Inspect the table and GraphQL enablement state.',
+            'Use set_table_graphql for enablement changes.',
+            'Hide a field from generated GraphQL with table metadata isPublished=false. Use ensure_field_permission only when an explicit role/user subject is part of the requirement.',
+            'Run test_graphql with an authenticated query and inspect GraphQL errors as data.',
+            'Remember GraphQL table data requires Bearer auth even when REST is public.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        key: 'storage-file',
+        title: 'Files, folders, storage configuration, and file permissions',
+        useWhen: [
+            'Inspecting or configuring storage providers and folders.',
+            'Managing file metadata, public state, or file permissions.',
+            'Building browser upload behavior and progress handling.',
+        ],
+        keywords: ['file upload', 'upload progress', 'storage config', 'storage provider', 'folder', 'file permission', 'asset'],
+        firstTools: ['search_runtime_zone', 'get_enfyra_examples'],
+        inspectTools: ['search_runtime_zone(mode=search, zone=storage_file)', 'search_runtime_zone(mode=inspect)', 'inspect_table', 'query_table'],
+        knowledgeTools: ['get_enfyra_required_knowledge', 'get_enfyra_examples(category=files)'],
+        writeTools: ['create_records', 'update_records', 'delete_records'],
+        verifyTools: ['search_runtime_zone', 'query_table'],
+        avoidTools: [
+            {
+                tool: 'create_records on enfyra_file for binary upload',
+                when: 'uploading file bytes from a browser or dynamic script',
+                useInstead: 'multipart /enfyra/enfyra_file or @STORAGE helpers',
+                reason: 'File metadata CRUD does not provide object upload, rollback, or progress behavior.',
+            },
+        ],
+        requiredAck: ['globalRulesAckKey for metadata writes'],
+        exampleCategories: ['files'],
+        nextStepTemplate: [
+            'Search storage_file runtime state, then inspect the selected record/table.',
+            'Use the files examples for browser proxy, multipart, progress, and @STORAGE contracts.',
+            'Use generic record tools only for metadata/configuration rows, never as a binary upload substitute.',
+            'The guided MCP does not expose a binary/multipart upload input tool. For an execute-now upload request, report that capability boundary before creating metadata-only file artifacts; browser code must use multipart /enfyra/enfyra_file and dynamic code must use @STORAGE.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        key: 'oauth',
+        title: 'Connect a third app, then configure its OAuth provider',
+        useWhen: [
+            'Connecting a third app to Enfyra before creating or updating Google, Facebook, or GitHub OAuth.',
+            'Seeding OAuth client credentials and returning the exact provider callback URI.',
+            'Continuing third-app OAuth integration after the user confirms the provider console callback.',
+        ],
+        keywords: [
+            'oauth',
+            'google login',
+            'google oauth',
+            'social login',
+            'oauth provider',
+            'provider callback',
+            'authorized redirect uri',
+            'client id client secret',
+            'đăng nhập google',
+            'cấu hình oauth',
+            'tích hợp oauth',
+        ],
+        firstTools: ['get_enfyra_api_context', 'get_enfyra_examples'],
+        inspectTools: ['get_enfyra_api_context'],
+        knowledgeTools: ['get_enfyra_required_knowledge', 'get_enfyra_examples'],
+        writeTools: ['setup_oauth_provider'],
+        verifyTools: ['test_rest_endpoint', 'search_runtime_zone', 'query_table'],
+        avoidTools: [
+            {
+                tool: 'provider state reads before credentials',
+                when: 'the third app is connected but clientId or clientSecret is absent from the current user request',
+                useInstead: 'stop and ask only for clientId and clientSecret',
+                reason: 'setup_oauth_provider owns the existing-row upsert and runtime verification. Pre-reading provider state cannot replace user-supplied credentials and must not trigger an early callback handoff.',
+            },
+            {
+                tool: 'create_records / update_records',
+                when: 'the user asked to configure a built-in OAuth provider',
+                useInstead: 'setup_oauth_provider',
+                reason: 'The OAuth front door upserts credentials, derives the callback, verifies runtime activation, redacts secrets, and returns the provider-console handoff in one operation.',
+            },
+            {
+                tool: 'custom ESV login/logout/me routes',
+                when: 'the third app can proxy a stable prefix to the Enfyra app /api bridge',
+                useInstead: 'the built-in Enfyra auth endpoints through the framework-specific third-app proxy',
+                reason: 'Do not replace Enfyra identity behavior. The Enfyra app bridge already owns cookie storage, refresh, and Bearer forwarding to ESV.',
+            },
+        ],
+        requiredAck: ['globalRulesAckKey for OAuth configuration writes'],
+        exampleCategories: ['connect', 'oauth-setup'],
+        nextStepTemplate: [
+            'Load category=connect and inspect or implement the third-app connection before asking for provider credentials.',
+            'Once the app connection is verified, stop and ask only for clientId and clientSecret. Never inspect provider state or stored credential values, and do not present callbackUri before setup_oauth_provider returns.',
+            'Present callbackUri and providerConsole.field, then stop until the user confirms that callback was added in the provider console.',
+            'After confirmation, complete a real OAuth login through the existing app button and verify /me before reporting setup success.',
+        ],
+        recommendedScope: 'operations',
+    },
+    {
+        key: 'identity-access',
+        title: 'Users, roles, sessions, and application identity access',
+        useWhen: [
+            'Inspecting or managing Enfyra users and roles.',
+            'Designing application login, session, refresh, and role access behavior.',
+        ],
+        keywords: ['user role', 'oauth account', 'login flow', 'session refresh', 'identity access'],
+        firstTools: ['search_runtime_zone', 'get_enfyra_examples'],
+        inspectTools: ['search_runtime_zone(mode=search, zone=auth_security)', 'search_runtime_zone(mode=inspect)', 'query_table', 'get_permission_profile'],
+        knowledgeTools: ['get_enfyra_required_knowledge', 'get_enfyra_examples(category=oauth-setup|connect)'],
+        writeTools: ['create_records', 'update_records', 'delete_records', 'ensure_route_access'],
+        verifyTools: ['query_table', 'get_permission_profile', 'test_rest_endpoint'],
+        avoidTools: [
+            {
+                tool: 'custom login/logout/me routes',
+                when: 'a browser app can use the Enfyra same-origin proxy and cookies',
+                useInstead: 'the built-in /login, /me, /logout, refresh, and OAuth routes through /enfyra',
+                reason: 'Custom token-cookie routes duplicate the supported identity lifecycle and are easier to get wrong.',
+            },
+        ],
+        requiredAck: ['globalRulesAckKey for identity metadata writes'],
+        exampleCategories: ['connect'],
+        nextStepTemplate: [
+            'Separate MCP token context from application user/role/OAuth configuration.',
+            'Inspect auth_security runtime records and the live table contract before writes.',
+            'Verify built-in auth behavior through the app-origin proxy or the narrow REST endpoint.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        key: 'platform-config',
+        title: 'Platform settings and CORS origins',
+        useWhen: [
+            'Inspecting or changing enfyra_setting values.',
+            'Adding, updating, or removing allowed CORS origins.',
+            'Checking runtime platform configuration before application integration.',
+        ],
+        keywords: ['cors', 'allowed origin', 'platform setting', 'enfyra_setting', 'enfyra_cors_origin'],
+        firstTools: ['inspect_table', 'query_table'],
+        inspectTools: ['inspect_table', 'query_table', 'discover_runtime_context'],
+        knowledgeTools: ['get_enfyra_required_knowledge'],
+        writeTools: ['create_records', 'update_records', 'delete_records'],
+        verifyTools: ['query_table', 'discover_runtime_context'],
+        avoidTools: [
+            {
+                tool: 'inventing setting keys or CORS fields',
+                when: 'live metadata has not been inspected',
+                useInstead: 'inspect_table for enfyra_setting or enfyra_cors_origin',
+                reason: 'Platform configuration is metadata-backed and field names must come from the current Enfyra version.',
+            },
+        ],
+        requiredAck: ['globalRulesAckKey for writes'],
+        exampleCategories: [],
+        nextStepTemplate: [
+            'Inspect the exact configuration table and current row first.',
+            'Apply a focused generic record mutation with acknowledgement.',
+            'Re-read the same row and verify application behavior before manual reloads.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        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_records 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.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        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'],
+        writeTools: [],
+        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.',
+            'If stale evidence truly requires manual reload, switch to ENFYRA_MCP_TOOLSET=full and choose the narrowest reload surface.',
+            'Re-verify the same narrow behavior after reload.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        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: ['search_logs', 'tail_log'],
+        inspectTools: ['search_logs', 'tail_log'],
+        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.',
+        ],
+        recommendedScope: 'schema',
+    },
+    {
+        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: ['connect', '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.',
+        ],
+        recommendedScope: 'schema',
+    },
+];
+//# sourceMappingURL=workflow-definitions.js.map