@enfyra/mcp-server 0.1.48 → 0.1.50

package/dist/lib/mcp-instructions.js

@@ -22,7 +22,7 @@ export function buildMcpServerInstructions(apiBaseUrl, options = {}) {
         '- For target sanity checks, call `get_enfyra_api_context`; do not load broad metadata only to confirm the API base.',
         '- When the goal is clear but the tool path is not, call `discover_enfyra_workflows` with intent/risk/surface. Use `detail: "plan"` before writes, follow `primaryPath`, and treat `avoidTools` as hard negative-routing boundaries.',
         '- Discover before deciding, then inspect narrowly. Use `inspect_table`, `inspect_route`, `inspect_feature`, `search_admin_extensions`, or `search_runtime_zone` for the exact table/route/feature/runtime artifact. Run broad discovery tools sequentially, not in parallel.',
-        '- Load examples only when needed with `get_enfyra_examples`. For OAuth use `get_enfyra_examples({ category: "oauth-setup" })`. For extension UI, call `get_extension_theme_contract` before writing or reviewing UI, use `build_extension_ui` after the extension acknowledgement for high-contract components and theme decisions such as drawers, modals, page shell headers/actions, permission gates, empty states, resource lists, FormEditor, Widget, menu/account panel registries, tabs, upload modals, theme classes/review, and full review, and call `get_theme_class_reference` only when exact classes are needed.',
+        '- Load examples only when needed with `get_enfyra_examples`. For OAuth use `get_enfyra_examples({ category: "oauth-setup" })`. For extension UI, call `get_extension_theme_contract` before writing or reviewing UI, use `build_extension_ui` after the extension acknowledgement for high-contract components, app composables, and theme decisions such as drawers, modals, page shell headers/actions, permission gates, empty states, resource lists, FormEditor, Widget, menu/account panel registries, tabs, upload modals, api usage, notify, runtime/theme classes/review, and full review, and call `get_theme_class_reference` only for theme internals or an explicitly requested full class map.',
         '- Prefer the most specific business operation tool over raw metadata CRUD.',
         '- Before any write, call `get_enfyra_required_knowledge({ scope })` with the right scope and pass returned ack keys into write tools. Choose scope by task domain:',
         '  • `schema` — table, column, relation, record CRUD, route permission, guard, field permission, column rule, cache reload, GraphQL enablement, log debug.',

package/dist/lib/mcp-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-instructions.js","sourceRoot":"","sources":["../../src/lib/mcp-instructions.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,UAAU;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO;QACL,cAAc,EAAE,GAAG,IAAI,UAAU;QACjC,gBAAgB,EAAE,GAAG,IAAI,iBAAiB;KAC3C,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,0BAA0B,CAAC,UAAU,EAAE,UAAiC,EAAE;IACxF,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC1E,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;IAEvD,OAAO;QACL,eAAe;QACf,EAAE;QACF,gCAAgC,IAAI,KAAK;QACzC,wBAAwB,cAAc,YAAY,gBAAgB,KAAK;QACvE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,EAAE;QACF,qBAAqB;QACrB,qJAAqJ;QACrJ,qHAAqH;QACrH,qOAAqO;QACrO,8QAA8Q;QAC9Q,imBAAimB;QACjmB,4EAA4E;QAC5E,oKAAoK;QACpK,2JAA2J;QAC3J,uJAAuJ;QACvJ,8IAA8I;QAC9I,yDAAyD;QACzD,4EAA4E;QAC5E,sMAAsM;QACtM,mLAAmL;QACnL,8LAA8L;QAC9L,EAAE;QACF,0BAA0B;QAC1B,uHAAuH;QACvH,sLAAsL;QACtL,gLAAgL;QAChL,iLAAiL;QACjL,yLAAyL;QACzL,kKAAkK;QAClK,0HAA0H;QAC1H,4LAA4L;QAC5L,EAAE;QACF,+BAA+B;QAC/B,4HAA4H;QAC5H,4GAA4G;QAC5G,mIAAmI;QACnI,kJAAkJ;QAClJ,oNAAoN;QACpN,iKAAiK;QACjK,gIAAgI;QAChI,EAAE;QACF,+BAA+B;QAC/B,iIAAiI;QACjI,uJAAuJ;QACvJ,yOAAyO;QACzO,+JAA+J;QAC/J,iMAAiM;QACjM,wSAAwS;QACxS,qLAAqL;QACrL,kPAAkP;QAClP,+PAA+P;QAC/P,EAAE;QACF,4BAA4B;QAC5B,0MAA0M;QAC1M,oHAAoH;QACpH,kIAAkI;QAClI,8MAA8M;QAC9M,kNAAkN;QAClN,wLAAwL;QACxL,EAAE;QACF,uIAAuI;KACxI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"mcp-instructions.js","sourceRoot":"","sources":["../../src/lib/mcp-instructions.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,UAAU;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO;QACL,cAAc,EAAE,GAAG,IAAI,UAAU;QACjC,gBAAgB,EAAE,GAAG,IAAI,iBAAiB;KAC3C,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,0BAA0B,CAAC,UAAU,EAAE,UAAiC,EAAE;IACxF,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC1E,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;IAEvD,OAAO;QACL,eAAe;QACf,EAAE;QACF,gCAAgC,IAAI,KAAK;QACzC,wBAAwB,cAAc,YAAY,gBAAgB,KAAK;QACvE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,EAAE;QACF,qBAAqB;QACrB,qJAAqJ;QACrJ,qHAAqH;QACrH,qOAAqO;QACrO,8QAA8Q;QAC9Q,8qBAA8qB;QAC9qB,4EAA4E;QAC5E,oKAAoK;QACpK,2JAA2J;QAC3J,uJAAuJ;QACvJ,8IAA8I;QAC9I,yDAAyD;QACzD,4EAA4E;QAC5E,sMAAsM;QACtM,mLAAmL;QACnL,8LAA8L;QAC9L,EAAE;QACF,0BAA0B;QAC1B,uHAAuH;QACvH,sLAAsL;QACtL,gLAAgL;QAChL,iLAAiL;QACjL,yLAAyL;QACzL,kKAAkK;QAClK,0HAA0H;QAC1H,4LAA4L;QAC5L,EAAE;QACF,+BAA+B;QAC/B,4HAA4H;QAC5H,4GAA4G;QAC5G,mIAAmI;QACnI,kJAAkJ;QAClJ,oNAAoN;QACpN,iKAAiK;QACjK,gIAAgI;QAChI,EAAE;QACF,+BAA+B;QAC/B,iIAAiI;QACjI,uJAAuJ;QACvJ,yOAAyO;QACzO,+JAA+J;QAC/J,iMAAiM;QACjM,wSAAwS;QACxS,qLAAqL;QACrL,kPAAkP;QAClP,+PAA+P;QAC/P,EAAE;QACF,4BAA4B;QAC5B,0MAA0M;QAC1M,oHAAoH;QACpH,kIAAkI;QAClI,8MAA8M;QAC9M,kNAAkN;QAClN,wLAAwL;QACxL,EAAE;QACF,uIAAuI;KACxI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/lib/platform-operation-tools.d.ts

@@ -76,6 +76,16 @@ export declare function buildExtensionUploadModalSnippet(input: any): {
     companionSnippet: string;
     contract: string[];
 };
+export declare function buildExtensionApiUsageSnippet(input?: AnyRecord): {
+    action: string;
+    snippet: string;
+    contract: string[];
+};
+export declare function buildExtensionNotifySnippet(input?: AnyRecord): {
+    action: string;
+    snippet: string;
+    contract: string[];
+};
 export declare function reviewExtensionUiContract(code: any): {
     action: string;
     valid: boolean;
@@ -88,6 +98,18 @@ export declare function reviewExtensionUiContract(code: any): {
     }[];
     nextSteps: string[];
 };
+export declare function reviewExtensionRuntimeContract(code: any): {
+    action: string;
+    valid: boolean;
+    issueCount: number;
+    issues: {
+        severity: "error" | "warning";
+        rule: string;
+        message: string;
+        suggestion: string;
+    }[];
+    nextSteps: string[];
+};
 export declare function reviewExtensionThemeContract(code: any): {
     action: string;
     valid: boolean;
@@ -105,6 +127,7 @@ export declare function validateExtensionCodeLocally(code: any): {
     componentCasing: string;
     fieldWidth: string;
     themeContract: string;
+    runtimeContract: string;
 };
 export declare function validateExtensionCode(apiUrl: any, code: any, name: any): Promise<{
     valid: boolean;
@@ -112,6 +135,7 @@ export declare function validateExtensionCode(apiUrl: any, code: any, name: any)
         componentCasing: string;
         fieldWidth: string;
         themeContract: string;
+        runtimeContract: string;
     };
     extensionId: any;
     compiledLength: any;

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

@@ -836,6 +836,88 @@ export function buildExtensionUploadModalSnippet(input) {
         ],
     };
 }
+function toPascalIdentifier(value, fallback = 'Items') {
+    const raw = String(value || fallback)
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+        .join('');
+    return raw || fallback;
+}
+export function buildExtensionApiUsageSnippet(input = {}) {
+    const resource = String(input.resource || input.name || 'items');
+    const pascal = toPascalIdentifier(resource, 'Items');
+    const path = input.path || `/${resource}`;
+    const method = String(input.method || 'GET').toUpperCase();
+    const responseName = input.responseName || `${resource}Response`;
+    const pendingName = input.pendingName || `${resource}Pending`;
+    const errorName = input.errorName || `${resource}Error`;
+    const executeName = input.executeName || (method === 'GET' ? `load${pascal}` : `${method.toLowerCase()}${pascal}`);
+    const refreshName = input.refreshName || `refresh${pascal}`;
+    const options = [];
+    if (method !== 'GET')
+        options.push(`method: ${quoteJsString(method)}`);
+    if (input.queryExpression)
+        options.push(`query: ${input.queryExpression}`);
+    if (input.bodyExpression)
+        options.push(`body: ${input.bodyExpression}`);
+    if (input.errorContext)
+        options.push(`errorContext: ${quoteJsString(input.errorContext)}`);
+    if (input.onErrorExpression)
+        options.push(`onError: ${input.onErrorExpression}`);
+    const optionsLiteral = options.length ? `, {\n  ${options.join(',\n  ')}\n}` : '';
+    const lines = [
+        `const { data: ${responseName}, pending: ${pendingName}, error: ${errorName}, execute: ${executeName}, refresh: ${refreshName} } = useApi(${quoteJsString(path)}${optionsLiteral});`,
+    ];
+    if (method === 'GET') {
+        const rowsName = input.rowsName || resource;
+        lines.push(`const ${rowsName} = computed(() => ${responseName}.value?.data || []);`);
+        if (input.autoLoad !== false) {
+            lines.push(`onMounted(() => { ${executeName}(); });`);
+        }
+    }
+    else {
+        const handlerName = input.handlerName || `${method.toLowerCase()}${pascal}Record`;
+        lines.push(...[
+            '',
+            `async function ${handlerName}(payload) {`,
+            `  const response = await ${executeName}({ body: payload });`,
+            '  if (!response) return null;',
+            '  return response;',
+            '}',
+        ]);
+    }
+    return {
+        action: 'extension_api_usage_built',
+        snippet: lines.join('\n'),
+        contract: [
+            'useApi returns refs plus execute/refresh; it does not auto-run.',
+            'Pass query/body as objects or computed objects, not JSON.stringify strings.',
+            'Read normal list rows from data.value?.data or from the direct execute() response.',
+            'For mutations, call execute({ body }), execute({ id, body }), execute({ id }), or execute({ ids }) from a user action.',
+        ],
+    };
+}
+export function buildExtensionNotifySnippet(input = {}) {
+    const kind = ['success', 'error', 'warning', 'info'].includes(input.kind) ? input.kind : 'success';
+    const title = input.title || (kind === 'success' ? 'Saved' : 'Notice');
+    const description = input.description || '';
+    const args = description ? `${quoteJsString(title)}, ${quoteJsString(description)}` : quoteJsString(title);
+    return {
+        action: 'extension_notify_usage_built',
+        snippet: [
+            'const notify = useNotify();',
+            `await notify.${kind}(${args});`,
+        ].join('\n'),
+        contract: [
+            'useNotify exposes success/error/warning/info(title, description?) helpers.',
+            'Do not pass Nuxt toast object payloads and do not call notify.add().',
+            'The helpers are async; await them inside submit/mutation handlers when ordering matters.',
+        ],
+    };
+}
 export function reviewExtensionUiContract(code) {
     const source = String(code || '');
     const issues = [];
@@ -881,6 +963,45 @@ export function reviewExtensionUiContract(code) {
             : ['Snippet matches the checked modal/drawer contract rules. Still validate the final SFC before saving.'],
     };
 }
+function collectExtensionRuntimeIssues(code) {
+    const source = String(code || '');
+    const issues = [];
+    const push = (severity, rule, message, suggestion) => issues.push({ severity, rule, message, suggestion });
+    if (/(?:^|[>\n;])\s*import(?:\s.+?\sfrom\s+|\s*['"])/m.test(source)) {
+        push('error', 'static-import', 'Static import statements are not allowed in enfyra_extension.code.', 'Use injected globals/components directly, or load app packages with getPackages(["package-name"]) inside runtime code.');
+    }
+    if (/\buseToast\s*\(/.test(source)) {
+        push('error', 'use-toast-directly', 'Dynamic extensions should not call useToast() directly.', 'Use useNotify() and call success/error/warning/info(title, description?).');
+    }
+    if (/\buseNotify\s*\(\s*\)\s*\.add\s*\(/.test(source) || /\b\w+\s*\.add\s*\(\s*\{\s*title\s*:/.test(source)) {
+        push('error', 'use-notify-add', 'useNotify() does not accept Nuxt toast object payloads through add().', 'Call notify.success/error/warning/info(title, description?) instead.');
+    }
+    if (/\b(?:query|body|filter|deep|aggregate)\s*:\s*JSON\.stringify\s*\(/.test(source)) {
+        push('error', 'use-api-json-stringify-options', 'useApi query/body/filter/deep/aggregate options must be plain objects or computed objects, not JSON strings.', 'Pass the object directly to useApi or execute().');
+    }
+    if (/\bawait\s+useApi\s*\(/.test(source)) {
+        push('error', 'await-use-api', 'useApi() is a composable that returns refs plus execute/refresh; it should not be awaited.', 'Destructure execute/refresh from useApi(), then await execute() inside onMounted, watchers, or user actions.');
+    }
+    if (/\buseApi\s*\(/.test(source) && !/\bexecute\s*:/.test(source) && !/\brefresh\s*:/.test(source) && !/\.\s*(?:execute|refresh)\s*\(/.test(source)) {
+        push('warning', 'use-api-no-execute-alias', 'useApi() appears without an execute/refresh alias or call.', 'Remember useApi does not auto-run; destructure execute/refresh and call execute() deliberately.');
+    }
+    if (/\buseNotify\s*\(/.test(source) && !/\bnotify\.(?:success|error|warning|info)\s*\(/.test(source) && !/\b(?:success|error|warning|info)\s*:\s*\w+/.test(source)) {
+        push('warning', 'use-notify-no-helper-call', 'useNotify() appears without a success/error/warning/info helper call.', 'Use the semantic helper methods instead of low-level toast payloads.');
+    }
+    return issues;
+}
+export function reviewExtensionRuntimeContract(code) {
+    const issues = collectExtensionRuntimeIssues(code);
+    return {
+        action: 'extension_runtime_contract_reviewed',
+        valid: issues.every((issue) => issue.severity !== 'error'),
+        issueCount: issues.length,
+        issues,
+        nextSteps: issues.length
+            ? ['Use build_extension_ui kind=api_usage or kind=notify for known-good snippets, then patch/update the extension.']
+            : ['Snippet matches the checked runtime composable/package rules. Still validate the final SFC before saving.'],
+    };
+}
 const THEME_CLASS_INTENTS = {
     neutral_surface: {
         classes: 'eapp-surface-card eapp-radius-panel border eapp-divider',
@@ -1088,6 +1209,18 @@ export function buildExtensionUiSnippet(kind, input = {}) {
         case 'upload_modal':
             result = buildExtensionUploadModalSnippet(input);
             break;
+        case 'api_usage':
+            result = buildExtensionApiUsageSnippet(input);
+            break;
+        case 'notify':
+            result = buildExtensionNotifySnippet(input);
+            break;
+        case 'runtime_review':
+            if (!input?.code) {
+                throw new Error('build_extension_ui kind=runtime_review requires input.code.');
+            }
+            result = reviewExtensionRuntimeContract(input.code);
+            break;
         case 'theme_classes':
             result = buildExtensionThemeClasses(input);
             break;
@@ -1103,12 +1236,14 @@ export function buildExtensionUiSnippet(kind, input = {}) {
             }
             const uiReview = reviewExtensionUiContract(input.code);
             const themeReview = reviewExtensionThemeContract(input.code);
+            const runtimeReview = reviewExtensionRuntimeContract(input.code);
             result = {
-                action: 'extension_ui_and_theme_contract_reviewed',
-                valid: uiReview.valid && themeReview.valid,
-                issueCount: uiReview.issueCount + themeReview.issueCount,
+                action: 'extension_ui_theme_runtime_contract_reviewed',
+                valid: uiReview.valid && themeReview.valid && runtimeReview.valid,
+                issueCount: uiReview.issueCount + themeReview.issueCount + runtimeReview.issueCount,
                 ui: uiReview,
                 theme: themeReview,
+                runtime: runtimeReview,
             };
             break;
         default:
@@ -1131,72 +1266,51 @@ function getExtensionThemeContract() {
             'The extension is already mounted inside the Enfyra app shell. Do not add a duplicate page header, centered page wrapper, or root-level page padding.',
             'Page extensions should be full-bleed, responsive, and split large operations into focused pages or UTabs.',
             'Use usePageHeaderRegistry for the shell title and useHeaderActionRegistry/useSubHeaderActionRegistry for page actions.',
-            'Use build_extension_menu_notification for sidebar menu notification registration snippets.',
+            'Use build_extension_ui kind=menu_notification for sidebar menu notification registration snippets.',
             'For shell menu notifications, first decide the signal source. Use a count only when the source already owns an exact count, such as a notification summary endpoint or bounded unread-notification query. Use a dot when a realtime event only proves that something new exists. Do not poll a domain list such as messages, tickets, orders, or jobs solely to decorate the menu; the destination page owns domain fetching.',
-            'Use build_extension_account_panel_item for account panel row registration snippets.',
+            'Use build_extension_ui kind=account_panel_item for account panel row registration snippets.',
             'For detail/form workflows that should stay left-aligned with empty space on the right, wrap the body in eapp-page-constrained; use eapp-page-constrained-wide only when the workflow genuinely needs more width.',
             'Card/list grids inside the default shell must account for the 280px desktop sidebar. Do not switch general card grids to three columns at lg; use md:grid-cols-2 xl:grid-cols-3 unless a local container proves three columns have enough width.',
         ],
         theme: [
-            'Use eApp theme class tokens, not hardcoded light/dark colors and not raw CSS variables inside extension templates. The app owns the CSS variable implementation; generated extensions should choose class tokens by intent.',
-            'Primary color is runtime-configurable through the app color picker and must affect extension identity UI. For Nuxt UI components, choose color="primary" by semantic intent and let the app map it through the primary contract; do not choose a concrete palette. For custom extension UI, first choose whether the element is neutral surface, runtime-primary identity, or status. Regular panels, KPI cards, list rows, and large content blocks should use eapp-surface-card, eapp-surface-muted, eapp-surface-flat, eapp-surface-hover, eapp-divide-y, and eapp-text-* classes. Entity identity, selected/current state, active progress, primary tiles, primary icons, and primary CTA fills should use eapp-primary-surface, eapp-primary-soft, eapp-primary-subtle, eapp-primary-solid, eapp-primary-text, eapp-primary-border, or eapp-primary-ring so the color picker controls them.',
-            'Use eapp-primary-surface only for larger entity/feature blocks, selected/current cards, tiles, or cards that should read like normal app cards with a very subtle active-primary tint; it supplies selected identity color but does not replace card chrome, so keep normal border/radius classes such as border plus eapp-radius-panel on the element. It is not a saturated selected-state fill and must not be applied broadly to every KPI/list wrapper. Add eapp-primary-surface-hover when that block is clickable. Use eapp-primary-soft for compact selected entity chips, pills, square icon tiles using eapp-icon-tile, and identity callouts; add eapp-primary-soft-hover when compact surfaces are clickable; use eapp-primary-subtle for a slightly stronger selected fill; use eapp-primary-solid only for primary identity fills; use eapp-primary-text for identity icons or inline text. eapp-identity-* remains an alias for the same runtime-primary intent, but eapp-primary-* is preferred in new extension code.',
-            'Nuxt UI secondary is still a valid semantic color when the product intentionally wants a secondary action or state. Do not use color="secondary", from-secondary-*, bg-secondary-*, text-secondary-*, or cyan/purple/green palette utilities merely to approximate an entity accent; use eapp-primary-* and let the app decide the color.',
-            'The app runs on Tailwind v4. Short Tailwind color utilities are the canonical way to apply contract colors and ARE allowed: bg-primary, text-primary, border-primary, ring-primary, bg-success, text-error, etc., including opacity modifiers (bg-primary/10, ring-success/20) which v4 resolves via color-mix. They are generated from the token-backed config (primary -> --md-primary runtime, success/error/warning/info -> --st-* status, secondary -> --md-tertiary) so they follow the color picker and dark theme. Do NOT use raw CSS-variable utilities (text-[var(--*)], bg-[var(--*)], border-[var(--*)]), hardcoded hex, inline style colors, or concrete palette substitution (color="violet", from-cyan-*, text-violet-*, bg-green-*, bg-emerald-*, text-green-*, dark:bg-zinc-950). For intent surfaces with no Tailwind equivalent (selected identity block, soft/solid/subtle surface, divider, radius, modal chrome) use the eapp-* classes below; the app owns how they map to the active color picker value.',
-            'Use UButton color="primary" only for the single main action for the current scope. Refresh, back, navigation, filters, and secondary actions should be neutral variants unless they are the main mutation.',
-            'PageHeader gradient must be "none" for generated operational extensions unless the user explicitly asks for a decorative page accent. Do not hardcode cyan, violet, purple, blue, or green PageHeader gradients to force color variety.',
-            'Do not inject global CSS, create theme guards, redefine the app palette, or solve one extension by overriding the whole app shell.',
-            'For panels/cards, prefer eapp-surface-card, eapp-surface-hover, eapp-surface-muted, eapp-surface-flat, and eapp-divide-y. Use eapp-text-primary, eapp-text-secondary, eapp-text-tertiary, or eapp-text-quaternary for copy.',
-            'Never use Nuxt UI neutral semantic classes such as bg-default, bg-muted, border-default, divide-default, text-muted, text-dimmed, or hardcoded dark palettes such as dark:bg-zinc-950, bg-slate-*, text-gray-*, border-black, or black.',
-            'Never use bare border/divide-y for panels or rows: pair borders with eapp-divider or use eapp-divide-y for row separators.',
-            'Use radius tokens or mapped rounded utilities consistently: --radius-card for cards, --radius-panel for nested panels, --radius-control for buttons/inputs, --radius-subcontrol for compact inner controls, and --radius-pill for pills.',
-            'Status colors must remain readable in both themes and must stay scoped to badges, small icons, or short status text. Use UBadge/UAlert semantic colors or eapp-status-success-soft/text/border, eapp-status-warning-soft/text/border, eapp-status-danger-soft/text/border, eapp-status-info-soft/text/border, and eapp-status-neutral-soft/text/border. Do not read --badge-* variables directly from extension templates. Do not color large panels, alert-like success blocks, KPI cards, list containers, or reconciliation/attention blocks green/yellow/red because the status is good/warning/error; use neutral app surfaces for the block and place a small status badge/icon inside.',
-            'Keep dark and light contrast comparable. Do not make dark mode more neon or lower-contrast than light mode; prefer muted soft backgrounds with clear text and visible borders.',
+            'Do not choose theme classes from memory. Decide the UI intent, then call build_extension_ui kind=theme_classes with that intent to receive the exact class/prop contract.',
+            'Call build_extension_ui kind=theme_review or kind=review before saving extension UI; validate_extension_code and extension write tools also reject hard theme violations.',
+            'Never fix one extension by injecting global CSS, redefining the app palette, or adding theme guards.',
+            'Use get_theme_class_reference only when debugging theme internals or when the user explicitly asks for the full theme/class map.',
         ],
-        decisionCases: [
-            {
-                intent: 'Normal accent, decorative icon, feature icon, non-state tile, active tab fill, progress fill, selected segment, primary metric accent, or primary action.',
-                colorContract: 'Use runtime primary so the app color picker controls the color.',
-                use: 'UButton/UBadge color="primary", eapp-primary-soft, eapp-primary-subtle, eapp-primary-solid, eapp-primary-text, or eapp-primary-surface when the whole block is selected/current identity.',
-                avoid: 'Do not pick cyan, purple, green, amber, secondary, or concrete Tailwind palettes just because they look good.',
-            },
-            {
-                intent: 'True semantic state: error, danger, destructive, warning, pending attention, success, healthy, running, failed, info, or notice.',
-                colorContract: 'Use the matching state/status color because the color communicates meaning, not brand identity.',
-                use: 'UAlert/UBadge color="error|warning|success|info|neutral", or eapp-status-success|warning|danger|info|neutral soft/text/border classes for custom compact status chips/icons.',
-                avoid: 'Do not force semantic state UI to primary; an error must stay error, a warning must stay warning, success can stay success when it is a badge/icon/short status.',
-            },
-            {
-                intent: 'Large ordinary surface: KPI card, list container, table panel, detail panel, summary block, empty state panel, reconciliation block, or attention block.',
-                colorContract: 'Use neutral app surfaces first; large surfaces should not become state-colored or arbitrary accent-colored.',
-                use: 'eapp-surface-card, eapp-surface-hover, eapp-surface-muted, eapp-surface-flat, eapp-divide-y, and eapp-text-* classes.',
-                avoid: 'Do not color large blocks green/yellow/red because their content says healthy/warning/error; place a status badge/icon inside the neutral block instead.',
-            },
-            {
-                intent: 'Selected/current entity or user-selected option where the whole block is the active identity.',
-                colorContract: 'Use runtime primary identity surface, but subtly.',
-                use: 'eapp-primary-surface plus optional eapp-primary-surface-hover; eapp-primary-soft/text for the icon or chip inside.',
-                avoid: 'Do not use eapp-primary-surface for every card in a grid/list or as a broad page background.',
-            },
+        themeIntents: [
+            'neutral_surface',
+            'muted_surface',
+            'flat_surface',
+            'hover_row',
+            'primary_identity',
+            'primary_soft_icon_tile',
+            'primary_progress',
+            'status_success',
+            'status_warning',
+            'status_danger',
+            'status_info',
+            'primary_action',
+            'secondary_action',
+            'ghost_navigation_action',
+            'danger_action',
+            'divider',
+            'text',
         ],
         components: [
             'Use Nuxt UI/eApp components for normal controls: UButton, UInput, UTextarea, USelectMenu/USelect, USwitch, UCheckbox, UTabs, UBadge, UModal, and CommonDrawer when available.',
             'Use auto-injected components directly in the template with PascalCase names. Do not call resolveComponent() to manually resolve Nuxt UI/eApp components inside extension SFCs; it can compile but render unresolved lowercase DOM tags such as <ubutton>.',
             'Buttons should have stable geometry: hover may change color, border, or shadow but must not move the button or resize its content. Disabled buttons keep disabled cursor/visual state.',
             'Inputs and textareas should not add hover movement or decorative hover states; focus, invalid, disabled, and loading states must be explicit.',
-            'For drawers, modals, page shell headers/actions, permission gates, empty states, resource lists, form editors, widgets, menu/account panel registries, tabs, and upload modals, call build_extension_ui with the matching kind after extension acknowledgement before patching raw Vue.',
-            'Use build_extension_ui kind=theme_classes for theme classes by intent, and kind=theme_review or kind=review before saving generated snippets that include high-contract UI, theme classes, or native buttons.',
+            'For drawers, modals, page shell headers/actions, permission gates, empty states, resource lists, form editors, widgets, menu/account panel registries, tabs, upload modals, api_usage, notify, and runtime/theming reviews, call build_extension_ui with the matching kind after extension acknowledgement before patching raw Vue.',
+            'Use build_extension_ui kind=theme_classes for theme classes by intent, and kind=runtime_review, theme_review, or review before saving generated snippets that include composables, theme classes, high-contract UI, or native buttons.',
             'Extension validation rejects UInput, UTextarea, USelect, USelectMenu, UInputMenu, UInputNumber, UInputTags, UInputTime, and UInputDate without class="w-full" unless marked data-compact or data-inline.',
             'Use UBadge or token-backed badge spans for status. Keep badges legible in both themes with tokenized background, text, and border.',
         ],
         appComposables: [
-            'useApi(url, options) returns refs: data, error, pending, status, plus async execute(options?) and refresh(). execute returns the response object or null.',
-            'useApi does not auto-run; call execute() in onMounted, a watcher, or a user action.',
-            'Pass query/body as plain objects or computed objects. Do not JSON.stringify filter, deep, or aggregate in extension/app code.',
-            'Normal Enfyra list responses are available as data.value?.data, and the direct execute() response as response?.data. Avoid double-unwrapping data?.value?.data unless explicitly supporting an older nested response shape.',
-            'For mutations, set method in useApi options and call execute({ body }), execute({ id, body }), execute({ id }), or execute({ ids }) as appropriate.',
-            'Use errorContext for readable default failures. Return true from onError only when the component fully handles the error locally.',
-            'useNotify() provides async success/error/warning/info(title, description?) methods plus dismiss/clear. Do not use Nuxt toast object payloads with it.',
+            'Do not write useApi/useNotify shapes from memory. Use build_extension_ui kind=api_usage or kind=notify for known-good snippets.',
+            'Use build_extension_ui kind=runtime_review or kind=review before saving extension code that includes useApi, useNotify, getPackages, or package loading.',
+            'validate_extension_code and extension write tools reject static imports, useToast/useNotify.add misuse, JSON.stringify useApi options, and await useApi().',
         ],
         shellComponentContracts: {
             CommonDrawer: [
@@ -1216,7 +1330,7 @@ function getExtensionThemeContract() {
                 'The builder owns numeric id usage, reactive prop/event wiring, and page/widget ownership warnings.',
             ],
             actionButtons: [
-                'Use build_extension_ui kind=review for generated snippets with native buttons.',
+                'Use build_extension_ui kind=review for generated snippets with native buttons or theme classes.',
                 'Validation/review catches missing type="button" and high-contract component mistakes before saving.',
             ],
         },
@@ -1236,60 +1350,12 @@ function getExtensionThemeContract() {
             'UI checks are only guidance; handlers/hooks must independently enforce owner/root-admin authorization.',
             'Use the most specific business route or MCP tool. Do not write directly to raw tables when a domain route exists.',
         ],
-        patternExamples: [
-            {
-                useWhen: 'Ordinary KPI, metric, or summary card where the whole card is not selected/current identity.',
-                use: 'Neutral card surface; put runtime-primary only on a small identity icon tile, progress fill, or main CTA inside the card.',
-                snippet: '<article class="eapp-surface-card p-4"><div class="flex items-start justify-between gap-3"><div><p class="text-sm eapp-text-tertiary">Metric</p><p class="mt-2 text-2xl font-semibold eapp-text-primary">{{ value }}</p></div><span class="eapp-primary-soft eapp-icon-tile"><UIcon name="lucide:square-stack" class="size-5 eapp-primary-text" /></span></div></article>',
-            },
-            {
-                useWhen: 'Selected/current entity, active plan, chosen package, or the single block that represents the active identity.',
-                use: 'eapp-primary-surface for the selected/current block, with eapp-primary-soft/text for compact icon parts.',
-                snippet: '<article class="eapp-primary-surface eapp-primary-surface-hover eapp-radius-panel border p-4"><div class="flex items-center gap-3"><span class="eapp-primary-soft eapp-icon-tile"><UIcon name="lucide:box" class="size-5 eapp-primary-text" /></span><div><p class="font-semibold eapp-text-primary">{{ name }}</p><p class="text-sm eapp-text-tertiary">Currently selected</p></div></div></article>',
-            },
-            {
-                useWhen: 'Progress, active tab indicator, selected segment fill, or primary visual meter.',
-                use: 'Neutral track plus eapp-primary-solid fill so the app color picker controls the fill.',
-                snippet: '<div class="h-1.5 overflow-hidden eapp-radius-pill eapp-surface-muted"><div class="eapp-primary-solid h-full" :style="{ width: progressWidth }"></div></div>',
-            },
-            {
-                useWhen: 'Success, warning, error, info, healthy, running, failed, pending, or attention status.',
-                use: 'UBadge/status badge tokens and optionally a small icon only. Keep large alert/panel/card backgrounds neutral unless the whole block is an identity block.',
-                snippet: '<section class="eapp-surface-card p-4"><div class="flex items-center justify-between gap-3"><p class="font-semibold eapp-text-primary">Reconciliation</p><UBadge color="success" variant="soft">Healthy</UBadge></div><p class="mt-1 text-sm eapp-text-tertiary">Latest report found no mismatches.</p></section>',
-            },
-            {
-                useWhen: 'List rows, table-like records, history rows, and secondary navigation rows.',
-                use: 'Neutral row surface, tokenized dividers, hover surface-muted, with small status/identity chips inside.',
-                snippet: '<div class="eapp-surface-card eapp-divide-y"><button class="flex w-full items-center justify-between px-4 py-3 text-left eapp-surface-hover"><span class="text-sm font-medium eapp-text-primary">{{ row.name }}</span><UBadge color="neutral" variant="soft">{{ row.state }}</UBadge></button></div>',
-            },
-            {
-                useWhen: 'Primary action for the current scope, such as create/save/apply/open-current.',
-                use: 'UButton color="primary" variant="solid"; secondary actions stay neutral.',
-                snippet: '<div class="flex justify-end gap-2"><UButton color="neutral" variant="outline">Cancel</UButton><UButton color="primary" variant="solid" icon="lucide:save">Save</UButton></div>',
-            },
-        ],
-        compactExample: '<template><section class="min-h-full w-full space-y-4"><article class="eapp-surface-card p-4"><div class="flex items-start justify-between gap-3"><div><p class="text-sm eapp-text-tertiary">Neutral KPI</p><p class="mt-2 text-2xl font-semibold eapp-text-primary">24</p></div><span class="eapp-primary-soft eapp-icon-tile"><UIcon name="lucide:square-stack" class="size-5 eapp-primary-text" /></span></div><div class="mt-3 h-1.5 overflow-hidden eapp-radius-pill eapp-surface-muted"><div class="eapp-primary-solid h-full w-1/2"></div></div></article><section class="eapp-surface-card p-4"><div class="flex items-center justify-between gap-3"><p class="font-semibold eapp-text-primary">Status block stays neutral</p><UBadge color="success" variant="soft">Healthy</UBadge></div></section></section></template>',
         shellNotificationContract: {
             menu: 'useMenuNotificationRegistry().register({ id, target: { id?, path?, route? }, value?, color?, title?, order? }). value renders a count/chip; omitting value renders a dot. Parent menus sum numeric child values.',
             accountPanel: 'useAccountPanelRegistry().register({ id, label, description, icon, count?, badge?, badgeColor?, expanded?, onToggle?, contentComponent? }). count is preferred over badge and the account trigger sums numeric visible item counts, capped at 99+.',
             lifecycle: 'Register from global extensions for app-wide notification state; stable ids replace previous registrations and component-owned registrations are removed on unmount.',
             reasoning: 'Counts and dots are different promises. A count says the shell knows an exact or bounded number from an appropriate notification/summary source. A dot says the shell only knows that new attention exists. Avoid fetching the destination domain list just to make a menu badge more precise.',
         },
-        contractAuthority: [
-            'This is the authoritative Enfyra theme & color contract. Source of truth: documents/app/theme-color-contract.md. The app owns color through app/utils/primary-colors.ts (Material You seed-to-role generation), app/assets/css/theme.css (semantic variables and Nuxt UI ramps), app/assets/css/main.css (extension-safe semantic utilities), and app/app.config.ts (Nuxt UI component mapping). Pages and extensions only CONSUME classes/Nuxt UI props; they never define colors.',
-            'Every color flows from two base layers: --md-* (Material You, runtime primary picker) and --st-* (status). Runtime primary roles are generated with SchemeTonalSpot. Success/warning/info stay fixed status quarts; error follows the generated Material error role through the single --danger-* lane. All Nuxt UI semantic colors (primary/secondary/success/warning/error/info/neutral) are re-pointed to these, so Nuxt UI is used per its docs but colors are decided by Enfyra. This applies to the shell, system pages, and compiled dynamic extensions.',
-            'Call get_theme_class_reference for the full class->variable->Nuxt UI table when you need the exact class name or variable.',
-        ],
-        classReference: {
-            surfaces: ['eapp-surface-card (default card; --card-bg/--card-border)', 'eapp-surface-muted (recessed/track; --surface-muted)', 'eapp-surface-flat (flush; --surface-default)', 'eapp-surface-hover (clickable row hover)'],
-            text: ['eapp-text-primary', 'eapp-text-secondary', 'eapp-text-tertiary', 'eapp-text-quaternary'],
-            primaryIdentity: ['eapp-primary-solid (solid fill/meter)', 'eapp-primary-text (inline/icon)', 'eapp-primary-soft + -hover (compact chip/tile)', 'eapp-primary-subtle (stronger selected fill)', 'eapp-primary-surface + -hover (large selected identity block)', 'eapp-primary-border', 'eapp-primary-ring'],
-            status: ['eapp-status-success|warning|danger|info|neutral -soft/-text/-border (badges/small icons/short text only)'],
-            radius: ['eapp-radius-card', 'eapp-radius-panel', 'eapp-radius-control', 'eapp-radius-subcontrol', 'eapp-radius-pill'],
-            dividers: ['eapp-divider', 'eapp-divide-y'],
-            modal: ['eapp-modal-surface (modal content chrome; never surface-card)'],
-            nuxtUiMapping: 'primary=--md-primary(runtime), secondary=--md-tertiary(runtime), success=--st-success, warning=--st-warning, error=--st-error, info=--st-info, neutral=neutral surfaces',
-        },
     };
 }
 function getThemeClassReference() {
@@ -1465,7 +1531,12 @@ export function validateExtensionCodeLocally(code) {
     if (firstThemeError) {
         throw new Error(`Invalid extension theme contract: ${firstThemeError.message} Rule: ${firstThemeError.rule}. ${firstThemeError.suggestion}`);
     }
-    return { componentCasing: 'passed', fieldWidth: 'passed', themeContract: 'passed' };
+    const runtimeReview = reviewExtensionRuntimeContract(code);
+    const firstRuntimeError = runtimeReview.issues.find((issue) => issue.severity === 'error');
+    if (firstRuntimeError) {
+        throw new Error(`Invalid extension runtime contract: ${firstRuntimeError.message} Rule: ${firstRuntimeError.rule}. ${firstRuntimeError.suggestion}`);
+    }
+    return { componentCasing: 'passed', fieldWidth: 'passed', themeContract: 'passed', runtimeContract: 'passed' };
 }
 export async function validateExtensionCode(apiUrl, code, name) {
     const localChecks = validateExtensionCodeLocally(code);
@@ -2652,10 +2723,8 @@ async function runExtensionWorkflow(apiUrl, opts) {
         nextSteps: latestState.nextSteps,
         guidance: [
             'Call get_extension_theme_contract before generating or reviewing extension UI.',
-            'useApi returns refs { data, error, pending, status } plus execute/refresh; it does not auto-run. Pass query/body/filter/deep/aggregate as objects or computed objects, not JSON strings.',
-            'useNotify exposes success/error/warning/info(title, description?) async helpers; do not pass Nuxt toast object payloads to it.',
-            'For high-contract UI, call build_extension_ui after extension acknowledgement before patching raw Vue: drawer, modal, page shell, permission gate, empty state, resource list, form editor, widget, menu notification, account panel item, tabs, upload modal, theme classes, theme review, or full review.',
-            'Use build_extension_ui kind=theme_classes for theme classes by intent, and kind=theme_review or kind=review before saving generated snippets that include drawers, modals, fields, lists, tabs, upload modals, shell registry code, theme classes, or native buttons.',
+            'For high-contract UI/runtime code, call build_extension_ui after extension acknowledgement before patching raw Vue: drawer, modal, page shell, permission gate, empty state, resource list, form editor, widget, menu notification, account panel item, tabs, upload modal, api usage, notify, runtime review, theme classes, theme review, or full review.',
+            'Use build_extension_ui kind=api_usage, notify, theme_classes, runtime_review, theme_review, or review instead of hand-writing those contracts from memory.',
             'Extension validation rejects common field controls without class="w-full" unless intentionally marked data-compact or data-inline.',
             'PermissionGate renders the permitted slot directly and is UX-only; backend permissions and owner checks remain authoritative.',
             'For menu/account-panel notifications, use counts only when the signal source already owns an exact count; otherwise use a dot/chip for new attention.',
@@ -2765,7 +2834,7 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     server.tool('build_extension_ui', [
         'Lazy gateway for Enfyra admin extension UI builders.',
         'Use this after get_enfyra_required_knowledge(scope="extension") when a high-contract extension UI snippet is needed.',
-        'It keeps guided startup small by dispatching drawer, modal, page_shell, permission_gate, empty_state, resource_list, form_editor, widget, menu_notification, account_panel_item, tabs, upload_modal, theme_classes, theme_review, or review internally instead of exposing every builder tool up front.',
+        'It keeps guided startup small by dispatching drawer, modal, page_shell, permission_gate, empty_state, resource_list, form_editor, widget, menu_notification, account_panel_item, tabs, upload_modal, api_usage, notify, runtime_review, theme_classes, theme_review, or review internally instead of exposing every builder tool up front.',
     ].join(' '), {
         kind: z.enum([
             'drawer',
@@ -2780,11 +2849,14 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
             'account_panel_item',
             'tabs',
             'upload_modal',
+            'api_usage',
+            'notify',
+            'runtime_review',
             'theme_classes',
             'theme_review',
             'review',
         ]).describe('Which extension UI contract builder/reviewer to run.'),
-        input: z.record(z.any()).optional().default({}).describe('Builder input object. For kind=theme_classes, pass { intent }. For kind=theme_review/review, pass { code }.'),
+        input: z.record(z.any()).optional().default({}).describe('Builder input object. For kind=api_usage, pass { path, resource, method? }. For kind=notify, pass { kind, title, description? }. For kind=theme_classes, pass { intent }. For kind=runtime_review/theme_review/review, pass { code }.'),
         extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
     }, async ({ kind, input, extensionKnowledgeAckKey }) => {
         assertExtensionKnowledgeAck(extensionKnowledgeAckKey);