@enfyra/mcp-server 0.1.47 → 0.1.49

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 such as drawers, modals, page shell headers/actions, permission gates, empty states, resource lists, FormEditor, Widget, menu/account panel registries, tabs, upload modals, and 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 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 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,kjBAAkjB;QACljB,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,ioBAAioB;QACjoB,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

@@ -88,16 +88,30 @@ export declare function reviewExtensionUiContract(code: any): {
     }[];
     nextSteps: string[];
 };
+export declare function reviewExtensionThemeContract(code: any): {
+    action: string;
+    valid: boolean;
+    issueCount: number;
+    issues: {
+        severity: "error" | "warning";
+        rule: string;
+        message: string;
+        suggestion: string;
+    }[];
+    nextSteps: string[];
+};
 export declare function buildExtensionUiSnippet(kind: string, input?: AnyRecord): any;
 export declare function validateExtensionCodeLocally(code: any): {
     componentCasing: string;
     fieldWidth: string;
+    themeContract: string;
 };
 export declare function validateExtensionCode(apiUrl: any, code: any, name: any): Promise<{
     valid: boolean;
     localChecks: {
         componentCasing: string;
         fieldWidth: string;
+        themeContract: string;
     };
     extensionId: any;
     compiledLength: any;

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

@@ -881,6 +881,174 @@ export function reviewExtensionUiContract(code) {
             : ['Snippet matches the checked modal/drawer contract rules. Still validate the final SFC before saving.'],
     };
 }
+const THEME_CLASS_INTENTS = {
+    neutral_surface: {
+        classes: 'eapp-surface-card eapp-radius-panel border eapp-divider',
+        use: 'Ordinary cards, panels, KPI containers, list containers, detail blocks, and status blocks that should stay neutral.',
+    },
+    muted_surface: {
+        classes: 'eapp-surface-muted eapp-radius-panel',
+        use: 'Recessed areas, tracks, secondary panels, or subdued containers.',
+    },
+    flat_surface: {
+        classes: 'eapp-surface-flat',
+        use: 'Flush content areas that should follow the app surface without card chrome.',
+    },
+    hover_row: {
+        classes: 'eapp-surface-hover eapp-divider',
+        use: 'Clickable rows inside lists or tables.',
+    },
+    primary_identity: {
+        classes: 'eapp-primary-surface eapp-radius-panel border',
+        use: 'A selected/current entity, active plan, active package, or the single larger block representing current identity.',
+    },
+    primary_soft_icon_tile: {
+        classes: 'eapp-primary-soft eapp-icon-tile',
+        childClasses: 'eapp-primary-text',
+        use: 'Compact runtime-primary icon tiles, selected chips, and small identity accents.',
+    },
+    primary_progress: {
+        trackClasses: 'eapp-surface-muted eapp-radius-pill',
+        fillClasses: 'eapp-primary-solid',
+        use: 'Progress or meter fill controlled by the runtime primary color.',
+    },
+    status_success: {
+        classes: 'eapp-status-success-soft eapp-status-success-text eapp-status-success-border',
+        nuxtUi: { color: 'success', variant: 'soft' },
+        use: 'Small success/healthy badges, chips, or icons only.',
+    },
+    status_warning: {
+        classes: 'eapp-status-warning-soft eapp-status-warning-text eapp-status-warning-border',
+        nuxtUi: { color: 'warning', variant: 'soft' },
+        use: 'Small warning/attention badges, chips, or icons only.',
+    },
+    status_danger: {
+        classes: 'eapp-status-danger-soft eapp-status-danger-text eapp-status-danger-border',
+        nuxtUi: { color: 'error', variant: 'soft' },
+        use: 'Small danger/error/destructive badges, chips, or icons only.',
+    },
+    status_info: {
+        classes: 'eapp-status-info-soft eapp-status-info-text eapp-status-info-border',
+        nuxtUi: { color: 'info', variant: 'soft' },
+        use: 'Small informational badges, chips, or icons only.',
+    },
+    primary_action: {
+        nuxtUi: { color: 'primary', variant: 'solid' },
+        use: 'The single main action for the current scope.',
+    },
+    secondary_action: {
+        nuxtUi: { color: 'neutral', variant: 'outline' },
+        use: 'Visible secondary actions, refresh, filters, cancel, and navigation alternatives.',
+    },
+    ghost_navigation_action: {
+        nuxtUi: { color: 'neutral', variant: 'ghost' },
+        use: 'Back/navigation/icon actions that should not compete with the primary action.',
+    },
+    danger_action: {
+        nuxtUi: { color: 'error', variant: 'solid' },
+        use: 'Final destructive actions such as Delete or Remove.',
+    },
+    divider: {
+        classes: 'eapp-divider',
+        listClasses: 'eapp-divide-y',
+        use: 'Borders and row separators in extension UI.',
+    },
+    text: {
+        primary: 'eapp-text-primary',
+        secondary: 'eapp-text-secondary',
+        tertiary: 'eapp-text-tertiary',
+        quaternary: 'eapp-text-quaternary',
+        use: 'Copy hierarchy in extension UI.',
+    },
+};
+function buildExtensionThemeClasses(input = {}) {
+    const intent = String(input.intent || '').trim();
+    if (!intent || !(intent in THEME_CLASS_INTENTS)) {
+        return {
+            action: 'extension_theme_classes_listed',
+            validIntents: Object.keys(THEME_CLASS_INTENTS),
+            note: 'Call again with one intent to get the exact classes/props for that theme contract.',
+        };
+    }
+    const contract = THEME_CLASS_INTENTS[intent];
+    return {
+        action: 'extension_theme_classes_built',
+        intent,
+        contract,
+        hardRules: [
+            'Do not use raw CSS variable utilities such as text-[var(...)], bg-[var(...)], or border-[var(...)] in extension templates.',
+            'Do not use hardcoded Tailwind palettes such as bg-violet-*, text-cyan-*, bg-green-*, dark:bg-zinc-*, or hex/rgb/hsl colors.',
+            'Use status classes only for compact badges/icons/short text; keep large panels neutral.',
+        ],
+    };
+}
+function collectExtensionThemeIssues(code) {
+    const source = String(code || '');
+    const issues = [];
+    const push = (severity, rule, message, suggestion) => issues.push({ severity, rule, message, suggestion });
+    const concretePalettes = [
+        'slate', 'gray', 'zinc', 'neutral', 'stone',
+        'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan', 'sky', 'blue', 'indigo',
+        'violet', 'purple', 'fuchsia', 'pink', 'rose',
+    ].join('|');
+    const paletteClassPattern = new RegExp(`(?:^|[\\s"'])(?:dark:)?(?:bg|text|border|ring|divide|from|via|to)-(${concretePalettes})-(?:\\d{2,3}|950)(?:\\/\\d+)?`, 'i');
+    const rawCssVarPattern = /\b(?:bg|text|border|ring|divide|from|via|to)-\[\s*var\(--/i;
+    const neutralSemanticClassPattern = /\b(?:bg-default|bg-muted|border-default|divide-default|text-muted|text-dimmed)\b/;
+    const concreteNuxtUiColors = [
+        'slate', 'gray', 'zinc', 'stone',
+        'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan', 'sky', 'blue', 'indigo',
+        'violet', 'purple', 'fuchsia', 'pink', 'rose',
+    ].join('|');
+    const concreteNuxtColorPattern = new RegExp(`\\bcolor\\s*=\\s*["'](${concreteNuxtUiColors})["']`, 'i');
+    if (rawCssVarPattern.test(source)) {
+        push('error', 'raw-css-var-utility', 'Raw CSS variable utility classes are not allowed in generated extension templates.', 'Use eapp-* class tokens or Nuxt UI semantic color props by intent.');
+    }
+    if (paletteClassPattern.test(source)) {
+        push('error', 'hardcoded-tailwind-palette', 'Hardcoded Tailwind palette classes are not allowed in themeable extension UI.', 'Use eapp-surface-*, eapp-primary-*, eapp-status-*, or Nuxt UI semantic colors.');
+    }
+    if (neutralSemanticClassPattern.test(source)) {
+        push('error', 'nuxt-neutral-class', 'Nuxt UI neutral shortcut classes are not part of the extension theme contract.', 'Use eapp-surface-* and eapp-text-* classes instead.');
+    }
+    if (concreteNuxtColorPattern.test(source)) {
+        push('error', 'concrete-nuxt-color', 'Concrete Nuxt UI palette colors are not allowed in generated extension UI.', 'Use color="primary|neutral|success|warning|error|info" by semantic intent.');
+    }
+    if (/#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})\b/i.test(source) || /\b(?:rgba?|hsla?|oklch|lab|lch)\s*\(/i.test(source)) {
+        push('error', 'hardcoded-color-value', 'Hardcoded color values are not allowed in extension UI.', 'Use the Enfyra theme class contract instead of hex/rgb/hsl/oklch/lab/lch values.');
+    }
+    if (/\bstyle\s*=\s*["'][^"']*(?:color|background(?:-color)?|border-color)\s*:/i.test(source)) {
+        push('error', 'inline-color-style', 'Inline color styles bypass the app theme contract.', 'Use eapp-* classes or Nuxt UI semantic props instead of inline color/background/border-color.');
+    }
+    if (/\bgradient\s*:\s*['"](?!none['"])[^'"]+['"]/.test(source) || /\bgradient\s*=\s*['"](?!none['"])[^'"]+['"]/.test(source)) {
+        push('error', 'page-header-gradient', 'Generated operational extension pages must use PageHeader gradient "none" unless the user explicitly requests decoration.', 'Set gradient: "none" in usePageHeaderRegistry or omit decorative gradients.');
+    }
+    if (/<(?:article|section|div)\b[^>]*class=["'][^"']*(?:eapp-status-(?:success|warning|danger|info)-soft|bg-(?:success|warning|error|info)(?:\b|\/))/i.test(source)) {
+        push('warning', 'large-status-surface', 'Status color appears on a large container.', 'Keep large panels neutral and put status color on a compact UBadge/icon/short text inside.');
+    }
+    const primaryActionCount = (source.match(/\bcolor\s*=\s*["']primary["']/g) || []).length;
+    if (primaryActionCount > 2) {
+        push('warning', 'primary-overuse', 'Many primary-colored controls were found.', 'Use primary only for the main action or identity accent; use neutral variants for secondary actions.');
+    }
+    const primarySurfaceCount = (source.match(/\beapp-primary-surface\b/g) || []).length;
+    if (primarySurfaceCount > 3) {
+        push('warning', 'primary-surface-overuse', 'eapp-primary-surface appears many times.', 'Use eapp-primary-surface only for selected/current identity blocks, not every card in a list/grid.');
+    }
+    if (/<(?:article|section|div)\b[^>]*class=["'][^"']*\bborder\b(?![^"']*\beapp-divider\b)/i.test(source)) {
+        push('warning', 'bare-border-token', 'A bordered panel is missing eapp-divider.', 'Pair intentional borders with eapp-divider so borders follow the app theme contract.');
+    }
+    return issues;
+}
+export function reviewExtensionThemeContract(code) {
+    const issues = collectExtensionThemeIssues(code);
+    return {
+        action: 'extension_theme_contract_reviewed',
+        valid: issues.every((issue) => issue.severity !== 'error'),
+        issueCount: issues.length,
+        issues,
+        nextSteps: issues.length
+            ? ['Use build_extension_ui kind=theme_classes to choose classes/props by intent, then patch/update the extension.']
+            : ['Snippet matches the checked theme contract rules. Still validate the final SFC before saving.'],
+    };
+}
 export function buildExtensionUiSnippet(kind, input = {}) {
     let result;
     switch (kind) {
@@ -920,11 +1088,28 @@ export function buildExtensionUiSnippet(kind, input = {}) {
         case 'upload_modal':
             result = buildExtensionUploadModalSnippet(input);
             break;
+        case 'theme_classes':
+            result = buildExtensionThemeClasses(input);
+            break;
+        case 'theme_review':
+            if (!input?.code) {
+                throw new Error('build_extension_ui kind=theme_review requires input.code.');
+            }
+            result = reviewExtensionThemeContract(input.code);
+            break;
         case 'review':
             if (!input?.code) {
                 throw new Error('build_extension_ui kind=review requires input.code.');
             }
-            result = reviewExtensionUiContract(input.code);
+            const uiReview = reviewExtensionUiContract(input.code);
+            const themeReview = reviewExtensionThemeContract(input.code);
+            result = {
+                action: 'extension_ui_and_theme_contract_reviewed',
+                valid: uiReview.valid && themeReview.valid,
+                issueCount: uiReview.issueCount + themeReview.issueCount,
+                ui: uiReview,
+                theme: themeReview,
+            };
             break;
         default:
             throw new Error(`Unsupported extension UI builder kind: ${kind}`);
@@ -946,53 +1131,36 @@ 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.',
@@ -1000,7 +1168,7 @@ function getExtensionThemeContract() {
             '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=review before saving generated snippets that include high-contract UI or native buttons.',
+            '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.',
             '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.',
         ],
@@ -1031,7 +1199,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.',
             ],
         },
@@ -1051,60 +1219,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() {
@@ -1275,7 +1395,12 @@ export function validateExtensionCodeLocally(code) {
         const first = missingFullWidthFields[0];
         throw new Error(`Invalid extension field width: <${first.tag}> must include class="w-full" in Enfyra extensions unless it is intentionally compact with data-compact or data-inline. First offending snippet: ${first.snippet}`);
     }
-    return { componentCasing: 'passed', fieldWidth: 'passed' };
+    const themeReview = reviewExtensionThemeContract(code);
+    const firstThemeError = themeReview.issues.find((issue) => issue.severity === 'error');
+    if (firstThemeError) {
+        throw new Error(`Invalid extension theme contract: ${firstThemeError.message} Rule: ${firstThemeError.rule}. ${firstThemeError.suggestion}`);
+    }
+    return { componentCasing: 'passed', fieldWidth: 'passed', themeContract: 'passed' };
 }
 export async function validateExtensionCode(apiUrl, code, name) {
     const localChecks = validateExtensionCodeLocally(code);
@@ -2464,8 +2589,8 @@ async function runExtensionWorkflow(apiUrl, opts) {
             '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, or review.',
-            'Use build_extension_ui kind=review before saving generated snippets that include drawers, modals, fields, lists, tabs, upload modals, shell registry code, or native buttons.',
+            '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.',
             '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.',
@@ -2575,7 +2700,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, 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, theme_classes, theme_review, or review internally instead of exposing every builder tool up front.',
     ].join(' '), {
         kind: z.enum([
             'drawer',
@@ -2590,9 +2715,11 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
             'account_panel_item',
             'tabs',
             'upload_modal',
+            '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=review, pass { code }.'),
+        input: z.record(z.any()).optional().default({}).describe('Builder input object. For kind=theme_classes, pass { intent }. For kind=theme_review/review, pass { code }.'),
         extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
     }, async ({ kind, input, extensionKnowledgeAckKey }) => {
         assertExtensionKnowledgeAck(extensionKnowledgeAckKey);