@astralkit/mcp 1.8.0 → 1.9.0

package/dist/server.js

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { configure, listComponents, getComponent, getCategories, listBoosters, getBooster, ApiError } from './api.js';
-import { validatePremiumAccess, canAccessBoosters, AuthError } from './auth.js';
+import { validateAccess, canAccessBoosters, AuthError } from './auth.js';
 import { DESIGN_TOKENS } from './data/tokens.js';
 import { CODING_STANDARDS } from './data/rules.js';
 import { PHOSPHOR_ICONS, PHOSPHOR_ICON_NAMES } from './data/icons.js';
@@ -11,10 +11,13 @@ import { CROSSWALK, nearestToken } from './data/crosswalk.js';
 import { buildPolishGuide, ARCHETYPE_KEYS } from './data/polish.js';
 import { buildStandardsGuide, BUILD_STANDARD_TOPICS } from './data/build-standards.js';
 import { buildScreenBlueprint, SCREEN_TYPES } from './data/screens.js';
+import { buildArtDirection } from './data/art-direction.js';
+import { THEMING } from './data/theming.js';
 import { reviewApp } from './review.js';
 import { captureScreenshot, BrowserUnavailableError, CaptureError, VIEWPORTS } from './capture.js';
+import { auditPage } from './audit.js';
 import { buildVisualVerdictGuide, buildVisualSelfReviewGuide, buildBrowserFallbackGuide } from './data/visual.js';
-const VERSION = '1.8.0';
+const VERSION = '1.9.0';
 /** Build "raw → ak" suggestions for a list of flagged raw classes (for validate_code). */
 function tokenSuggestions(classes) {
     const seen = new Set();
@@ -31,30 +34,25 @@ function tokenSuggestions(classes) {
 }
 // The golden path — surfaced as server `instructions` so even a naive agent
 // (one that just gets "build X") self-guides to design-system-quality output.
-const SERVER_INSTRUCTIONS = `AstralKit builds polished, accessible, on-brand UI. The AstralKit COMPONENT LIBRARY is the source of truth — build FROM real library components; do NOT freestyle UI. Hand-writing a component the library already provides is a failure, even if it is token-compliant.
-
-GOLDEN PATH — for ANY UI request (build, redesign, or improve a page/section/component):
-1. get_coding_standards — the mandatory rules. Read first.
-2. get_design_tokens — use ONLY ak-* tokens. NEVER raw Tailwind colors (bg-gray-*), NEVER arbitrary values (p-[1rem]).
-3. search_components — ALWAYS do this before writing any UI. Find the closest real component(s) for what you are building; never skip straight to JSX.
-4. get_preview — SEE candidates (returns an image) and pick the best-looking fit.
-5. get_component (mode:"recipe") — get the real component and REUSE it: keep its structure, layout, and polish. "Adapt" = RE-CONTENT, not rebuild — swap its placeholder copy, nav items, logo, and sample data for the app's real content, and match the app's theme. Do NOT regenerate the layout into something generic, and do NOT freestyle a replacement.
-6. install_component — install the chosen component(s) into the project (e.g. components/ui) and import them. The library piece is what ships; your job is to wire it in + re-content it.
-7. get_icons — confirm Phosphor names exist (never guess). get_setup — the CSS imports + font-load step.
-8. validate_code + review_app — fix every issue, then BUILD (run tsc / next build — validate_code is NOT a compiler; it won't catch syntax errors).
-9. verify_visual — the FINAL gate. With the dev server running, pass your route URL + the reference slug: it screenshots YOUR render and returns it next to the reference preview with a comparison rubric. Code checks cannot see a banner with no image, a shrunken logo, an unintended dark band, or an unloaded font — only this step can. Fix every FAIL and re-run until clean.
-
-IF NOTHING FITS EXACTLY: still start from the CLOSEST component's recipe and modify it (adjust layout/content as needed) — NEVER from a blank file. The reference sets the quality bar; match it.
-
-REDESIGN / IMPROVE AN EXISTING APP: for each bespoke piece (sidebar, top bar, cards, forms, hero…) search the AstralKit equivalent, install it, and REPLACE the bespoke one — then RE-CONTENT it with the app's real nav, logo, copy, and data. PRESERVE the app's existing theme: if the app is dark, keep it dark (set the matching data-ak-theme — never flip dark↔light). Never invent colors. ("*-light" showcase components are LIGHT demos — match them to the app's theme, don't drag the app to light.)
-
-TOKENIZE (source already well-designed, only needs ak-* tokens): get_coding_standards → get_design_tokens (raw-Tailwind→ak CROSSWALK) → map every raw class → swap icons to Phosphor → validate_code → build. PRESERVE the source theme — the crosswalk assumes a LIGHT source, so for a dark app map to dark surfaces / inverse roles, not the light defaults (mapping a dark app naively flips it to a broken light theme).
-
-POLISH / REVAMP (weak hierarchy, cramped spacing, off-brand surfaces): call polish_ui FIRST. It keeps the original layout, content, and behavior. Finish with screenshot_ui (or verify_visual with a reference slug) to SEE the result before declaring done.
-
-BUILD IT RIGHT (architecture & screen UX): get_build_standards (atomic design, separation of concerns, the loading/empty/error/populated state contract, error handling, responsive/mobile-menu, radix; pass a topic). For a specific screen call get_screen_blueprint(screen_type) — it tells you WHICH AstralKit components to install for that screen + the must-haves. Audit existing/AI-generated code with review_app.
-
-Hard rules: build from library components, never freestyle; 16px body floor (text-ak-base); 48px touch targets; Phosphor icons only; semantic color tokens; PRESERVE the app's theme; never declare UI work done without the verify_visual/screenshot_ui eyes-on check. Prefer the resources astralkit://tokens, ://rules, ://icons, ://setup, ://standards if your client supports them.`;
+//
+// ⚠ KEEP THIS SHORT. MCP clients TRUNCATE long server instructions — the
+// 2026-08-23 bakeoff proved an agent never saw the theming/verify rules because
+// they sat below the truncation point. Detail lives in tool RESPONSES (which
+// always arrive intact): search_components.nextSteps, recipe.afterInstall,
+// install_component.instructions, validate_code.summary.
+const SERVER_INSTRUCTIONS = `AstralKit builds polished, accessible, on-brand UI. The LIBRARY is the source of truth: NEVER freestyle a component the library provides — search, install, re-content.
+
+GOLDEN PATH for ANY UI request:
+1. get_coding_standards + get_design_tokens (ak-* tokens ONLY; no raw Tailwind colors, no arbitrary values).
+2. get_theming — pick one of the 16 palettes to match the brand; shipping the bare black-and-white default is a FAILURE.
+3. get_screen_blueprint(type) for dashboards/nav/auth/settings/onboarding/pricing/marketing.
+4. search_components PER REGION → get_preview → get_component (recipe) → install_component → RUN the command → RE-CONTENT (swap copy/nav/logo/data; keep structure and polish). A real screen composes SEVERAL installed components.
+5. validate_code + build (tsc + next build) — validate_code is not a compiler.
+6. VERIFY (never skip, never declare done without it): screenshot at desktop AND tablet(768) AND mobile(390); use clickSelector to OPEN every dropdown/modal/menu and check overlay surfaces (bg-ak-elevated + border + shadow-lg); run audit_page (FREE, no key needed — reflow, contrast, tap targets, font-size histogram); re-query the recipe and diff feature-by-feature for anything dropped (mobile menu, click-outside, keyboard nav). Fix, re-capture, iterate (max 3 rounds).
+
+Every tool response carries its own nextSteps — FOLLOW them. Sizing: you have a trained bias toward tiny text/icons; body floor 16px, meaningful icons 20-24px; when uncertain size UP. Preserve the app theme (dark stays dark). Phosphor icons only. If imagery is needed, get_art_direction + your image tools; search_logos for brand marks.
+
+ACCESS: free tier = standards, tokens, theming, search/previews, validate_code, blueprints, art direction, audit_page + free components. Pro key (ASTRALKIT_API_KEY) unlocks polish_ui, review_app, verify_visual, screenshot_ui, premium components. If a premium tool declines, continue with the free tools — audit_page ALWAYS runs — and never fabricate a declined tool's output.`;
 // ─── Security: Input validation ───────────────────────────────────────────────
 const MAX_QUERY_LENGTH = 200;
 const MAX_SLUG_LENGTH = 100;
@@ -93,26 +91,36 @@ class AuthGuard {
     lastCheck;
     apiKey;
     revoked = false;
-    constructor(apiKey) {
+    current;
+    constructor(apiKey, initial) {
         this.apiKey = apiKey;
+        this.current = initial;
         this.lastCheck = Date.now();
     }
+    get auth() {
+        return this.current;
+    }
     async check() {
+        // Anonymous sessions have no key to revalidate — free surface only.
+        if (!this.apiKey)
+            return;
         if (this.revoked) {
-            throw new AuthError('Your AstralKit subscription has been revoked or expired.\n' +
+            throw new AuthError('Your AstralKit API key is no longer valid.\n' +
                 'Restart the MCP server after renewing at https://astralkit.com/pricing');
         }
         if (Date.now() - this.lastCheck < REVALIDATION_INTERVAL_MS)
             return;
         try {
-            await validatePremiumAccess(this.apiKey);
+            // Plan changes (upgrade or downgrade) take effect on the next
+            // revalidation without a restart.
+            this.current = await validateAccess(this.apiKey);
             this.lastCheck = Date.now();
         }
         catch (err) {
             if (err instanceof AuthError) {
-                // Genuine auth failure (invalid key / plan downgrade) — revoke immediately.
+                // Genuine auth failure (invalid key) — revoke immediately.
                 this.revoked = true;
-                console.error('[astralkit-mcp] Subscription revalidation failed — access revoked.');
+                console.error('[astralkit-mcp] Key revalidation failed — access revoked.');
                 throw err;
             }
             // Transient (network/timeout, ApiError). Do NOT revoke: keep serving on the
@@ -124,6 +132,21 @@ class AuthGuard {
             throw err;
         }
     }
+    /** Gate for premium-only tools (polish_ui, review_app, verify_visual, screenshot_ui). */
+    async requirePremium(feature) {
+        await this.check();
+        if (this.current.level === 'premium')
+            return;
+        if (this.current.level === 'anonymous') {
+            throw new AuthError(`${feature} is a premium tool.\n` +
+                'Set the ASTRALKIT_API_KEY environment variable with a Pro key and restart the MCP server.\n' +
+                'Get your key at https://astralkit.com/settings — plans at https://astralkit.com/pricing\n' +
+                'Meanwhile, continue the golden path with the free tools (search, previews, tokens, validate_code).');
+        }
+        throw new AuthError(`${feature} requires a Pro or higher subscription.\n` +
+            `Your current plan: ${this.current.tier}\n` +
+            'Upgrade at https://astralkit.com/pricing');
+    }
 }
 // ─── Security: API key redaction ──────────────────────────────────────────────
 function redactApiKey(text, apiKey) {
@@ -256,6 +279,12 @@ function createServer(auth, guard, apiKey) {
                     frameworks: c.supported_frameworks,
                     previewImage: c.previewImage,
                 })),
+                nextSteps: [
+                    'get_preview(slug) to SEE candidates, then get_component (recipe) + install_component (RUN the command) for the best fit.',
+                    'A real screen usually composes SEVERAL components — search per region (shell, table, dialog, empty state), not once.',
+                    'Have you applied a palette yet? get_theming lists the 16 — shipping the bare black-and-white default theme is a failure.',
+                    'Building a known screen type? get_screen_blueprint(dashboard|nav|auth|settings|onboarding|pricing|marketing) first.',
+                ],
             });
         }
         catch (err) {
@@ -384,7 +413,14 @@ function createServer(auth, guard, apiKey) {
                 slug: result.slug,
                 framework: fw,
                 previewImage: result.previewImage,
-                howToAdapt: 'REUSE this component — install it into the project and keep its structure, layout, spacing, and polish (watermarks, display type, complex layout, effects ARE the premium character). ADAPT = RE-CONTENT only: replace placeholder copy, nav items, logo, and sample data with the real app content, and match the app theme (preserve dark/light — never flip it). Do NOT regenerate the layout into something generic, and do NOT freestyle a replacement. If it is not an exact fit, modify THIS recipe rather than building from a blank file.',
+                howToAdapt: `INSTALL this component first: run the install_command below in your terminal (or call install_component). The component is NOT available until the command executes. Then REUSE it — keep its structure, layout, spacing, and polish (watermarks, display type, complex layout, effects ARE the premium character). ADAPT = RE-CONTENT only: replace placeholder copy, nav items, logo, and sample data with the real app content, and match the app theme (preserve dark/light — never flip it). Do NOT regenerate the layout into something generic, and do NOT freestyle a replacement. If it is not an exact fit, modify THIS recipe rather than building from a blank file. COMPLETENESS CHECK: after adapting, call get_component for this SAME slug again and compare your output against the recipe feature-by-feature. Common omissions: responsive/mobile menu (hamburger + Radix Dialog), click-outside dismiss, keyboard navigation, focus trapping, active/hover/focus states, overlay surface treatment (bg-ak-elevated + border + shadow-lg on dropdowns), animations/transitions. If the recipe has it and yours doesn't, add it — partial extraction is a failure.`,
+                afterInstall: [
+                    '1. RUN the install_command — the component is NOT available until it executes.',
+                    '2. RE-CONTENT: swap copy/nav/logo/data; keep structure, spacing, polish. Apply a palette (get_theming) — bare black-and-white default = unfinished.',
+                    '3. VERIFY (mandatory): screenshot at desktop + tablet(768) + mobile(390); clickSelector to OPEN every dropdown/modal/menu in this component and check overlay surfaces (bg-ak-elevated + border + shadow-lg) and that nothing deforms the layout.',
+                    '4. audit_page on the route (FREE, no key): reflow, contrast, tap targets, font-size histogram. Fix errors.',
+                    '5. Re-fetch this recipe and diff your build against it feature-by-feature — mobile menu, click-outside dismiss, keyboard nav, hover/active states. Partial extraction is a failure.',
+                ],
                 intendedFont: 'Inter via font-ak-sans (load with next/font and wire to --font-ak-sans — see get_setup)',
                 tokensUsed,
                 iconsUsed: icons.used,
@@ -403,8 +439,12 @@ function createServer(auth, guard, apiKey) {
             if (err instanceof AuthError)
                 return errorResult(err.message);
             if (err instanceof ApiError && err.code === 'PRO_REQUIRED') {
-                return errorResult(`Component "${slug}" requires a Pro subscription for ${framework ?? 'react'} framework.\n` +
-                    'Upgrade at https://astralkit.com/pricing');
+                return errorResult(`Component "${slug}" is a premium component.\n` +
+                    (guard.auth.level === 'anonymous'
+                        ? 'Set ASTRALKIT_API_KEY with a Pro key (https://astralkit.com/settings) and restart the MCP server.\n'
+                        : '') +
+                    'Upgrade at https://astralkit.com/pricing\n' +
+                    'Free components remain available — search_components shows is_pro per result.');
             }
             return errorResult(`Failed to get component: ${err instanceof Error ? redactApiKey(err.message, apiKey) : 'Unknown error'}`);
         }
@@ -433,7 +473,7 @@ function createServer(auth, guard, apiKey) {
             'font sizes/weights, and surface treatment so it looks like part of the library, while KEEPING ' +
             'its layout, content, and app behavior. Use this (not just tokenizing) when the source design ' +
             'is mediocre and needs design-quality elevation, not only ak-* token translation. Returns a ' +
-            '6-phase procedure, a design-smell rubric, allowed/forbidden structural changes, a self-check, ' +
+            '7-phase procedure, a design-smell rubric, allowed/forbidden structural changes, a self-check, ' +
             'and per-region reference targets. Pass the UI regions you see (e.g. ["kanban-card","sidebar","form"]).',
         inputSchema: {
             archetypes: z.array(z.string().max(MAX_QUERY_LENGTH)).max(40).optional()
@@ -441,7 +481,7 @@ function createServer(auth, guard, apiKey) {
         },
     }, async ({ archetypes }) => {
         try {
-            await guard.check();
+            await guard.requirePremium('polish_ui');
         }
         catch (err) {
             if (err instanceof AuthError)
@@ -512,6 +552,46 @@ function createServer(auth, guard, apiKey) {
         }
         return textResult(buildScreenBlueprint(screen_type));
     });
+    server.registerTool('get_art_direction', {
+        title: 'Get Art Direction',
+        description: 'Get art direction guidance for a screen or component — what assets to generate, style/mood hints, ' +
+            'which tools to use (e.g. generate_image, generate_video, search_logos), quality gates, and anti-patterns. ' +
+            'Call this BEFORE building screens that need imagery (heroes, landing pages, dashboards with empty states, ' +
+            'marketing sections, auth pages). The MCP cannot generate assets itself, but it tells you exactly what to ' +
+            'generate with your other connected tools and how to verify the result.',
+        inputSchema: {
+            context: z.string().max(MAX_QUERY_LENGTH)
+                .describe('What you are building — e.g. "hero section for SaaS landing page", "pricing page", "dashboard", "auth login", "marketing landing page"'),
+        },
+    }, async ({ context }) => {
+        try {
+            await guard.check();
+        }
+        catch (err) {
+            if (err instanceof AuthError)
+                return errorResult(err.message);
+            throw err;
+        }
+        return textResult(buildArtDirection(context));
+    });
+    server.registerTool('get_theming', {
+        title: 'Get Theming (palette catalog)',
+        description: 'Get the 16 designed AstralKit palettes (9 light, 7 dark) with mood descriptors and the 2-step application ' +
+            '(import astralkit/palettes + data-ak-theme="<id>"). Call this for EVERY new screen/app build and pick a palette ' +
+            'that fits the brand mood — shipping the bare default black-and-white theme reads as an unfinished template. ' +
+            'One palette per app; preserve an existing app\'s light/dark mode; 60-30-10 still applies within a palette.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            await guard.check();
+        }
+        catch (err) {
+            if (err instanceof AuthError)
+                return errorResult(err.message);
+            throw err;
+        }
+        return textResult(THEMING);
+    });
     server.registerTool('get_setup', {
         title: 'Get Setup',
         description: 'Get the exact project setup AstralKit needs to RENDER correctly: the CSS imports (theme + utilities), ' +
@@ -644,7 +724,7 @@ function createServer(auth, guard, apiKey) {
     });
     // ─── Visual verification (capture → compare → iterate) ───────────────
     const viewportSchema = z.enum(Object.keys(VIEWPORTS)).optional().default('desktop')
-        .describe('Viewport to render at: "desktop" (1440x900, default) or "mobile" (390x844). Run desktop first, mobile after it passes.');
+        .describe('Viewport to render at: "desktop" (1440x900, default), "tablet" (768x1024), or "mobile" (390x844). Run desktop first, then tablet, then mobile — the tablet pass is where late-breakpoint bugs hide (content crushed but not yet collapsed).');
     async function tryCapture(opts) {
         try {
             return { ok: true, shot: await captureScreenshot(opts) };
@@ -674,6 +754,17 @@ function createServer(auth, guard, apiKey) {
             return null; // transient fetch failure — verify without the reference rather than blocking the gate
         }
     }
+    /** Structured prerequisite prompt — returned when a browser tool can't run. */
+    function buildPrerequisite(reason) {
+        return {
+            action: 'suggest_install',
+            tool: 'playwright-core',
+            reason,
+            install_command: 'npm i -g playwright-core',
+            question: 'Install playwright-core globally for visual verification? This enables screenshot_ui, verify_visual, and audit_page to capture and audit your rendered pages.',
+            options: ['Yes, install it', 'No, I\'ll verify manually'],
+        };
+    }
     server.registerTool('verify_visual', {
         title: 'Verify Visual (screenshot vs reference)',
         description: 'The FINAL quality gate for any UI work — ALWAYS call this after validate_code + build succeed, before declaring done. ' +
@@ -681,17 +772,22 @@ function createServer(auth, guard, apiKey) {
             'plus a region-by-region comparison rubric you must answer item by item. This catches what code checks cannot: a banner ' +
             'with no image, a shrunken logo, an unintended dark background, an unloaded font, broken spacing. ' +
             'Pass the route URL and the slug of the reference component you built from; omit slug for a reference-free self-review. ' +
-            'Fix every FAIL it surfaces and call it again — iterate until all items pass (max 3 rounds).',
+            'Fix every FAIL it surfaces and call it again — iterate until all items pass (max 3 rounds). ' +
+            'INTERACTIVE STATES: after the static capture, re-run with clickSelector for each dropdown/popover/modal trigger ' +
+            'to verify overlay surface treatment (bg-ak-elevated + border + shadow-lg). ' +
+            'RESPONSIVE: also run with viewport:"mobile" to verify mobile menu and layout.',
         inputSchema: {
             url: z.string().max(MAX_URL_LENGTH).describe('The page to capture — your running app route, e.g. http://localhost:3000/dashboard'),
             slug: z.string().max(MAX_SLUG_LENGTH).optional()
                 .describe('Slug of the reference component you built from (adds its preview image to compare against). Omit if there is no single reference.'),
             selector: z.string().max(MAX_QUERY_LENGTH).optional()
                 .describe('Optional CSS selector to capture just the rebuilt region (e.g. "main", "#hero") when it sits inside a larger app shell.'),
+            clickSelector: z.string().max(MAX_QUERY_LENGTH).optional()
+                .describe('Click this element BEFORE capturing — use to open dropdowns, popovers, or modals for interactive state verification (e.g. "[data-testid=\'account-menu\']", "button:has-text(\'Menu\')").'),
             viewport: viewportSchema,
             fullPage: z.boolean().optional().default(true).describe('Capture the full scrollable page (default true) or just the viewport.'),
         },
-    }, async ({ url, slug, selector, viewport, fullPage }) => {
+    }, async ({ url, slug, selector, clickSelector, viewport, fullPage }) => {
         const urlErr = validatePageUrl(url);
         if (urlErr)
             return errorResult(urlErr);
@@ -701,7 +797,7 @@ function createServer(auth, guard, apiKey) {
                 return errorResult(slugErr);
         }
         try {
-            await guard.check();
+            await guard.requirePremium('verify_visual');
             let reference = null;
             let referenceNote = '';
             if (slug) {
@@ -713,7 +809,7 @@ function createServer(auth, guard, apiKey) {
                 else
                     referenceNote = `\n\n(Note: the reference preview for "${slug}" could not be fetched right now — run the rubric as a self-review against the recipe you installed.)`;
             }
-            const result = await tryCapture({ url, selector, viewport, fullPage });
+            const result = await tryCapture({ url, selector, clickSelector, viewport, fullPage });
             if (!result.ok) {
                 if (result.failure.kind === 'capture-error')
                     return errorResult(result.failure.message);
@@ -723,6 +819,7 @@ function createServer(auth, guard, apiKey) {
                     content.push({ type: 'image', data: reference.base64, mimeType: reference.mimeType });
                 }
                 content.push({ type: 'text', text: buildBrowserFallbackGuide(result.failure.reason, !!reference) });
+                content.push({ type: 'text', text: '\n\n---\nPREREQUISITE:\n' + JSON.stringify(buildPrerequisite(result.failure.reason), null, 2) });
                 return { content };
             }
             const { shot } = result;
@@ -752,25 +849,35 @@ function createServer(auth, guard, apiKey) {
         description: 'Screenshot a page of YOUR running app (dev server must be up) and get the image back with a visual self-review ' +
             'rubric — so you can SEE what you actually rendered instead of assuming. Use during polish/revamp work or any time ' +
             'you changed UI without a single reference component. When you built from a specific library component, prefer ' +
-            'verify_visual (it adds the reference preview to compare against).',
+            'verify_visual (it adds the reference preview to compare against). ' +
+            'INTERACTIVE STATES: pass clickSelector to click a trigger element BEFORE the screenshot — use this to open dropdowns, ' +
+            'popovers, and modals so you can verify their styling (bg-ak-elevated + border + shadow-lg). Run once without clickSelector ' +
+            'for the static state, then again WITH clickSelector for each interactive element.',
         inputSchema: {
             url: z.string().max(MAX_URL_LENGTH).describe('The page to capture, e.g. http://localhost:3000/settings'),
             selector: z.string().max(MAX_QUERY_LENGTH).optional()
                 .describe('Optional CSS selector to capture one region (e.g. "main", "#pricing").'),
+            clickSelector: z.string().max(MAX_QUERY_LENGTH).optional()
+                .describe('Click this element BEFORE capturing — use to open dropdowns, popovers, or modals for interactive state verification (e.g. "[data-testid=\'account-menu\']", "button:has-text(\'Menu\')").'),
             viewport: viewportSchema,
             fullPage: z.boolean().optional().default(true).describe('Capture the full scrollable page (default true) or just the viewport.'),
         },
-    }, async ({ url, selector, viewport, fullPage }) => {
+    }, async ({ url, selector, clickSelector, viewport, fullPage }) => {
         const urlErr = validatePageUrl(url);
         if (urlErr)
             return errorResult(urlErr);
         try {
-            await guard.check();
-            const result = await tryCapture({ url, selector, viewport, fullPage });
+            await guard.requirePremium('screenshot_ui');
+            const result = await tryCapture({ url, selector, clickSelector, viewport, fullPage });
             if (!result.ok) {
                 if (result.failure.kind === 'capture-error')
                     return errorResult(result.failure.message);
-                return textResult(buildBrowserFallbackGuide(result.failure.reason, false));
+                return {
+                    content: [
+                        { type: 'text', text: buildBrowserFallbackGuide(result.failure.reason, false) },
+                        { type: 'text', text: '\n\n---\nPREREQUISITE:\n' + JSON.stringify(buildPrerequisite(result.failure.reason), null, 2) },
+                    ],
+                };
             }
             const { shot } = result;
             return {
@@ -787,6 +894,83 @@ function createServer(auth, guard, apiKey) {
             return errorResult(`Screenshot failed: ${err instanceof Error ? redactApiKey(err.message, apiKey) : 'Unknown error'}`);
         }
     });
+    // ─── Numerical audit (shipyard-grade quality gate) ───────────────────
+    server.registerTool('audit_page', {
+        title: 'Audit Page (numerical quality gate)',
+        description: 'Run a shipyard-grade numerical audit on your rendered page (dev server must be running). ' +
+            'Tests 8 checks at multiple breakpoints: horizontal reflow, tap targets (WCAG 2.5.8), prose line measure, ' +
+            'document structure (h1, landmarks, heading levels), focus visibility (:focus-visible), ' +
+            'motion/prefers-reduced-motion, CLS risk (unsized media), and WCAG color contrast (with alpha compositing ' +
+            'through the DOM tree — not a naive check). Returns structured findings with error/warning/note counts. ' +
+            'This is the numerical companion to verify_visual/screenshot_ui — it measures, they show. ' +
+            'FREE TIER — always available, no Pro key needed. Run it on every route before declaring done.',
+        inputSchema: {
+            url: z.string().max(MAX_URL_LENGTH).describe('The page to audit, e.g. http://localhost:3000/dashboard'),
+            breakpoints: z.array(z.number().int().min(280).max(3840)).optional()
+                .describe('Viewport widths to test (default: [390, 768, 1440]). Reflow + tap targets run at each; page-level checks run at the widest.'),
+        },
+    }, async ({ url, breakpoints }) => {
+        const urlErr = validatePageUrl(url);
+        if (urlErr)
+            return errorResult(urlErr);
+        try {
+            await guard.check();
+            const result = await auditPage(url, breakpoints ?? undefined);
+            const lines = [
+                `# Numerical Audit — ${url}`,
+                `Breakpoints: ${(breakpoints ?? [390, 768, 1440]).join(', ')}px`,
+                '',
+            ];
+            for (const bp of result.breakpoints) {
+                const errs = bp.findings.filter(f => f.severity === 'error');
+                const warns = bp.findings.filter(f => f.severity === 'warning');
+                lines.push(`## ${bp.width}px`);
+                for (const f of bp.findings) {
+                    const icon = f.severity === 'error' ? '✗' : f.severity === 'warning' ? '!' : '·';
+                    lines.push(`  ${icon}  [${f.check}] ${f.detail}`);
+                    if (f.elements?.length) {
+                        lines.push(`     offenders: ${f.elements.join(', ')}`);
+                    }
+                }
+                if (!errs.length && !warns.length)
+                    lines.push('  ✓  All checks pass');
+                lines.push('');
+            }
+            if (result.pageLevel.length) {
+                lines.push('## Page-level checks');
+                for (const f of result.pageLevel) {
+                    const icon = f.severity === 'error' ? '✗' : f.severity === 'warning' ? '!' : '·';
+                    lines.push(`  ${icon}  [${f.check}] ${f.detail}`);
+                }
+                lines.push('');
+            }
+            lines.push(`---`);
+            lines.push(`**${result.summary.errors} errors · ${result.summary.warnings} warnings · ${result.summary.notes} notes**`);
+            if (result.summary.errors === 0 && result.summary.warnings === 0) {
+                lines.push('');
+                lines.push('Numbers pass. Now read the fold cold at 390px: what is this, who is it for,');
+                lines.push('what do I do next. No audit catches that one.');
+            }
+            else if (result.summary.errors > 0) {
+                lines.push('');
+                lines.push('Fix every ERROR before declaring done. Address WARNINGs where feasible.');
+            }
+            return textResult(lines.join('\n'));
+        }
+        catch (err) {
+            if (err instanceof AuthError)
+                return errorResult(err.message);
+            if (err instanceof BrowserUnavailableError) {
+                return {
+                    content: [
+                        { type: 'text', text: `Numerical audit requires a local browser but none was found: ${err.message}\n\nThe audit checks (reflow, contrast, tap targets, focus, motion, CLS, structure) could not run. This gate was SKIPPED, not passed.` },
+                        { type: 'text', text: '\n\n---\nPREREQUISITE:\n' + JSON.stringify(buildPrerequisite(err.message), null, 2) },
+                    ],
+                };
+            }
+            return errorResult(`Audit failed: ${err instanceof Error ? redactApiKey(err.message, apiKey) : 'Unknown error'}`);
+        }
+    });
     server.registerTool('install_component', {
         title: 'Install Component',
         description: 'Get the CLI command to install an AstralKit component into the user\'s project. ' +
@@ -814,7 +998,15 @@ function createServer(auth, guard, apiKey) {
         return jsonResult({
             slug,
             command,
-            description: `Install the ${slug} component into your project. Run this in your project root.`,
+            mustExecute: true,
+            note: 'This returns the command string. You MUST execute it in the project root. The component is NOT installed until the command runs successfully.',
+            instructions: [
+                `1. RUN this command in the project root: ${command}`,
+                '2. VERIFY the component files were created (check the output or list the installed path)',
+                '3. Import and use the installed component — do NOT hand-write a copy of the component code',
+                '4. Apply a palette (get_theming) if none is set — the bare black-and-white default theme reads unfinished',
+                '5. AFTER wiring: screenshot desktop + tablet + mobile, clickSelector every dropdown/modal open state, and run audit_page (free) — installed components can still break in YOUR app (missing deps, layout collisions, unthemed overlays)',
+            ],
         });
     });
     server.registerTool('validate_code', {
@@ -836,6 +1028,26 @@ function createServer(auth, guard, apiKey) {
         }
         // Each issue carries an actionable fix (a "diff" the agent can apply directly).
         const issues = [];
+        // CSS custom property references — the #1 tokenization mistake. Agents write
+        // var(--color-ak-*) into stylesheets instead of using ak-* utility classes.
+        const cssVarRefs = code.match(/var\(--(?:color|spacing|radius|text|tracking|leading|shadow|size|height|width)-ak-[a-z0-9_-]+\)/g);
+        if (cssVarRefs) {
+            issues.push({
+                rule: 'css-var-instead-of-class',
+                detail: `CSS custom property references found: ${[...new Set(cssVarRefs)].slice(0, 5).join(', ')}.`,
+                fix: 'NEVER use var(--color-ak-*) / var(--spacing-ak-*) in CSS. Use the Tailwind utility class on the element instead: var(--color-ak-surface) → className="bg-ak-surface", var(--spacing-ak-3) → className="p-ak-3". Delete any stylesheet rules that reference ak CSS variables and move the styling to className.',
+            });
+        }
+        // Bare colors: bg-white, bg-black, text-white, text-black (no shade suffix)
+        const bareColors = code.match(/\b(bg|text|border|ring)-(white|black)\b/g);
+        if (bareColors) {
+            const unique = [...new Set(bareColors)];
+            issues.push({
+                rule: 'bare-color',
+                detail: `Bare colors: ${unique.join(', ')}.`,
+                fix: `Replace with semantic tokens — ${tokenSuggestions(unique)}. (Full crosswalk via get_design_tokens.)`,
+            });
+        }
         const rawTailwindColors = code.match(/\b(bg|text|border|ring|fill|stroke|from|to|via|divide|outline)-(gray|slate|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3}\b/g);
         if (rawTailwindColors) {
             issues.push({
@@ -888,6 +1100,130 @@ function createServer(auth, guard, apiKey) {
                 });
             }
         }
+        // Shadows on panels/cards (not modals/overlays)
+        const shadowClasses = code.match(/\bshadow-(sm|md|lg|xl|2xl)\b/g);
+        if (shadowClasses) {
+            const hasModal = /modal|dialog|overlay|popover|dropdown|tooltip|Menu|Sheet/i.test(code);
+            if (!hasModal) {
+                issues.push({
+                    rule: 'shadow-on-panel',
+                    detail: `Shadow classes found: ${[...new Set(shadowClasses)].join(', ')}.`,
+                    fix: 'Panels and cards use border border-ak-border, NOT shadow. Shadows are only allowed on modals, popovers, dropdowns, and tooltips (floating/overlaid elements).',
+                });
+            }
+        }
+        // !important — never
+        if (/!important/.test(code)) {
+            issues.push({
+                rule: 'important-used',
+                detail: '!important found in code.',
+                fix: 'Never use !important — it creates cascading specificity issues. Fix the root cause: reorder classes, restructure the component, or check for conflicting stylesheets.',
+            });
+        }
+        // @apply directives
+        if (/@apply\s/.test(code)) {
+            issues.push({
+                rule: 'at-apply',
+                detail: '@apply directive found.',
+                fix: 'Extract the utilities from @apply, convert each to its ak-* equivalent, apply them to the JSX className, and delete the CSS rule. All styling belongs on the element, never in @apply.',
+            });
+        }
+        // Dot notation in ak-* spacing (ak-1.5 silently collapses to zero in v4)
+        const dotNotation = code.match(/\bak-\d+\.\d+\b/g);
+        if (dotNotation) {
+            issues.push({
+                rule: 'dot-notation-spacing',
+                detail: `Dot notation in ak-* tokens: ${[...new Set(dotNotation)].join(', ')}.`,
+                fix: 'Use underscore, not dot: ak-1_5 (not ak-1.5), ak-0_5 (not ak-0.5). Dot notation silently collapses to zero in Tailwind v4.',
+            });
+        }
+        // /opacity on ak-* tokens (renders transparent, not faded)
+        const opacityOnAk = code.match(/\b(?:bg|text|border|ring)-ak-[a-z0-9_-]+\/\d+\b/g);
+        if (opacityOnAk) {
+            const nonExempt = opacityOnAk.filter(m => !m.includes('inverse-on-surface'));
+            if (nonExempt.length > 0) {
+                issues.push({
+                    rule: 'opacity-on-ak-token',
+                    detail: `Opacity modifier on ak-* tokens: ${[...new Set(nonExempt)].slice(0, 5).join(', ')}.`,
+                    fix: 'Opacity on ak-* tokens renders transparent, not faded. Use the -subtle variant instead (e.g. bg-ak-warning-subtle not bg-ak-warning/30). The ONLY sanctioned opacity idiom is inverse-on-surface/NN.',
+                });
+            }
+        }
+        // The AI sizing bias — tiny type/icons are the single most common AI-coder
+        // failure. Static tells here; audit_page measures the rendered truth.
+        {
+            const tinyText = code.match(/\btext-ak-2xs\b|\btext-\[(?:[1-9]|1[01])(?:px|\.\d+px)\]/g);
+            if (tinyText) {
+                issues.push({
+                    rule: 'tiny-text',
+                    detail: `Sub-12px text: ${[...new Set(tinyText)].join(', ')}.`,
+                    fix: 'Text under 12px is below the accessible floor — legitimate ONLY for dataviz tick labels and legal fine print. Body = text-ak-base (16px), meta = text-ak-sm (14px), annotations = text-ak-xs (12px). You have a trained bias toward small sizes; when uncertain, size UP one step.',
+                });
+            }
+            const rawXs = code.match(/\btext-xs\b/g);
+            if (rawXs && rawXs.length > 2) {
+                issues.push({
+                    rule: 'small-text-density',
+                    detail: `text-xs used ${rawXs.length}× — the page skews small.`,
+                    fix: 'Heavy text-xs use is the AI sizing bias (training data skews to dense 12-14px UI). Rebuild hierarchy from the TOP down: set the display/title sizes first, body lands at text-ak-base (16px), and only tabular annotations stay at 12px.',
+                });
+            }
+            const tinyIcons = code.match(/\bsize=\{(?:1[0-4])\}/g);
+            if (tinyIcons) {
+                issues.push({
+                    rule: 'tiny-icon',
+                    detail: `Icons at 14px or below: ${[...new Set(tinyIcons)].join(', ')}.`,
+                    fix: 'Meaningful icons (nav items, list leading icons, section markers) belong at 20-24px. 16px only for inline chevrons and meta glyphs. size={12} or size={14} on a standalone icon reads as clutter next to text.',
+                });
+            }
+        }
+        // CSS module imports
+        if (/import\s+\w+\s+from\s+['"][^'"]+\.module\.css['"]/g.test(code)) {
+            issues.push({
+                rule: 'css-module-import',
+                detail: 'CSS module import found.',
+                fix: 'Treat CSS modules like any stylesheet: READ the .module.css file, EXTRACT each CSS property, FIND the equivalent ak-* utility class, APPLY to className, DELETE the .module.css file, and remove the import + all styles.* references.',
+            });
+        }
+        // Overlay/dropdown surface treatment — the exact gap that caused the topbar dropdown bug.
+        // Detect overlay-like patterns (absolute/fixed + z-index + state-driven visibility) and
+        // check they have complete surface treatment (bg + border + shadow).
+        {
+            const hasOverlayPositioning = /\b(absolute|fixed)\b[^`"'\n]{0,80}\bz-\d|\bz-\d[^`"'\n]{0,80}\b(absolute|fixed)\b/.test(code);
+            const hasDropdownState = /(isOpen|showMenu|showDropdown|menuOpen|dropdownOpen|setShow|setOpen|isVisible|showPanel|panelOpen)/i.test(code);
+            const hasRadixOverlay = /(Popover\.Content|DropdownMenu\.Content|Dialog\.Content|HoverCard\.Content|Tooltip\.Content|Select\.Content)/i.test(code);
+            if ((hasOverlayPositioning && hasDropdownState) || hasRadixOverlay) {
+                const hasElevatedBg = /bg-ak-elevated/.test(code);
+                const hasShadow = /shadow-(sm|md|lg|xl|2xl)\b/.test(code);
+                const missing = [];
+                if (!hasElevatedBg)
+                    missing.push('bg-ak-elevated');
+                if (!hasShadow)
+                    missing.push('shadow-lg');
+                if (missing.length > 0) {
+                    issues.push({
+                        rule: 'overlay-surface',
+                        detail: `Overlay/dropdown elements detected but missing surface treatment: ${missing.join(', ')}.`,
+                        fix: 'Floating overlays (dropdowns, popovers, tooltips, menus) MUST have all three: bg-ak-elevated (background), border border-ak-border (border), and shadow-lg (shadow). Overlays are the ONE place shadows are required — they float above the page and need visual separation. This is invisible in code review but immediately obvious to users.',
+                    });
+                }
+            }
+        }
+        // Responsive navigation — desktop-only navs are the #1 responsiveness bug.
+        {
+            const hasNavElement = /<nav[\s>]/i.test(code) || /\bnav\b/i.test(code);
+            const hasMultipleLinks = ([...code.matchAll(/<(?:a|Link)\s/g)].length >= 3) ||
+                ([...code.matchAll(/href=/g)].length >= 3);
+            const hasResponsiveHiding = /(hidden\s+(sm|md|lg|xl):flex|(sm|md|lg|xl):hidden)/.test(code);
+            const hasMobileMenu = /(hamburger|mobile.*menu|Sheet|Drawer|sidebar.*mobile|List\s|menu.*mobile)/i.test(code);
+            if (hasNavElement && hasMultipleLinks && !hasResponsiveHiding && !hasMobileMenu) {
+                issues.push({
+                    rule: 'no-responsive-nav',
+                    detail: 'Navigation with links but no responsive/mobile menu pattern detected.',
+                    fix: 'Desktop nav links must be hidden on mobile (hidden md:flex) with a hamburger trigger (md:hidden) that opens a Radix Dialog side-sheet. Desktop-only navs are the most common responsiveness bug. Reference the source recipe\'s mobile handling — call get_component for the same slug and check its responsive pattern.',
+                });
+            }
+        }
         if (/bg-ak-neutral-900[^"\n]*text-white|text-white[^"\n]*bg-ak-neutral-900/.test(code)) {
             issues.push({
                 rule: 'fake-inverse-panel',
@@ -977,8 +1313,8 @@ function createServer(auth, guard, apiKey) {
             issueCount: issues.length,
             issues,
             summary: issues.length === 0
-                ? 'Code follows AstralKit conventions. NOTE: this checks conventions, NOT that the code compiles — always run a real build/typecheck (tsc / next build). Then finish with verify_visual (screenshot vs reference): convention checks cannot see a missing banner image, a shrunken logo, or an unloaded font — only the visual gate can.'
-                : `Found ${issues.length} issue${issues.length === 1 ? '' : 's'}. Apply each fix and re-run validate_code until clean. (validate_code checks conventions, not compilation — also run a real build/typecheck, then verify_visual as the final gate.)`,
+                ? 'Code follows AstralKit conventions. NOTE: this checks conventions, NOT that the code compiles — always run a real build/typecheck (tsc / next build). Then the visual gates: verify_visual or screenshot_ui at desktop + tablet + mobile (and clickSelector for open dropdown/modal states), AND audit_page on the route (FREE, no API key — runs even when the premium visual tools are gated). A themed screen is part of done: if you have not applied a palette (get_theming), the default black-and-white theme reads as an unfinished template.'
+                : `Found ${issues.length} issue${issues.length === 1 ? '' : 's'}. Apply each fix and re-run validate_code until clean. (validate_code checks conventions, not compilation — also run a real build/typecheck, then verify_visual/screenshot_ui + audit_page as the final gates.)`,
         });
     });
     server.registerTool('review_app', {
@@ -999,7 +1335,7 @@ function createServer(auth, guard, apiKey) {
         },
     }, async ({ code, files, screen_type }) => {
         try {
-            await guard.check();
+            await guard.requirePremium('review_app');
         }
         catch (err) {
             if (err instanceof AuthError)
@@ -1114,7 +1450,7 @@ function createServer(auth, guard, apiKey) {
             contents: [{ uri: 'astralkit://setup', text: SETUP, mimeType: 'text/markdown' }],
         };
     });
-    server.registerResource('AstralKit Polish Guide', 'astralkit://polish', { description: 'Revamp an existing UI to AstralKit quality — 6-phase procedure, design-smell rubric, allowed structural changes, self-check (quality polish, not just token translation)', mimeType: 'text/markdown' }, async () => {
+    server.registerResource('AstralKit Polish Guide', 'astralkit://polish', { description: 'Revamp an existing UI to AstralKit quality — 7-phase procedure, design-smell rubric, allowed structural changes, self-check (quality polish, not just token translation)', mimeType: 'text/markdown' }, async () => {
         await guard.check();
         return {
             contents: [{ uri: 'astralkit://polish', text: buildPolishGuide(), mimeType: 'text/markdown' }],
@@ -1182,6 +1518,40 @@ function createServer(auth, guard, apiKey) {
                 },
             }],
     }));
+    server.registerPrompt('preflight', {
+        title: 'Preflight Verification',
+        description: 'Run the full AstralKit quality gate (tsc + build + validate_code + visual + numerical audit) before declaring UI work done.',
+        argsSchema: {
+            routes: z.string().max(MAX_DESCRIPTION_LENGTH).describe('Comma-separated route paths to verify, e.g. "/dashboard, /settings"'),
+        },
+    }, async ({ routes }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Run the AstralKit preflight verification gate on these routes: ${routes}\n\n` +
+                        `## The 5 gates (run in order — do not skip any):\n\n` +
+                        `### 1. TypeScript\n` +
+                        `\`npx tsc --noEmit\` — must produce zero errors.\n\n` +
+                        `### 2. Build\n` +
+                        `\`npm run build\` (or \`next build\`) — must succeed. tsc alone misses runtime issues.\n\n` +
+                        `### 3. validate_code\n` +
+                        `Call validate_code on each changed file. Fix every issue, re-run until clean.\n\n` +
+                        `### 4. Visual verification\n` +
+                        `For each route:\n` +
+                        `a. screenshot_ui at desktop viewport — run the full rubric (completeness, imagery, brand, surfaces, typography, spacing, theme, integrity, interactive-states, responsive).\n` +
+                        `b. screenshot_ui with clickSelector for each dropdown/popover/modal trigger — verify overlay surface treatment (bg-ak-elevated + border + shadow-lg).\n` +
+                        `c. screenshot_ui at mobile viewport — verify responsive menu and layout.\n` +
+                        `d. Fix every FAIL, re-shot until clean (max 3 rounds per route).\n\n` +
+                        `### 5. Numerical audit\n` +
+                        `audit_page on each route URL. This runs 8 checks at multiple breakpoints: reflow, tap targets, line measure, document structure, focus visibility, motion/reduced-motion, CLS risk, and WCAG color contrast. Errors must reach ZERO. List surviving warnings with a judgment for each.\n\n` +
+                        `## Reporting\n` +
+                        `One line per gate: PASS or FAIL + detail. Do NOT declare the work done with any gate still failing.\n` +
+                        `If audit_page or screenshot_ui is unavailable (no local browser), note it explicitly — that gate was SKIPPED, not passed.\n\n` +
+                        `Numbers pass. Now read the fold cold at 390px: what is this, who is it for, what do I do next. No audit catches that one.`,
+                },
+            }],
+    }));
     return server;
 }
 export async function startServer() {
@@ -1190,9 +1560,11 @@ export async function startServer() {
     configure(apiKey, apiUrl);
     let auth;
     try {
-        auth = await validatePremiumAccess(apiKey);
+        auth = await validateAccess(apiKey);
     }
     catch (err) {
+        // A PRESENT-but-invalid key exits loudly — a misconfigured subscriber must
+        // hear about it, not be silently downgraded to the free tier.
         if (err instanceof AuthError) {
             console.error(`\n[astralkit-mcp] ${err.message}\n`);
             process.exit(1);
@@ -1201,8 +1573,18 @@ export async function startServer() {
         console.error(`\n[astralkit-mcp] Unexpected error during authentication:\n${redactApiKey(errMsg, apiKey)}\n`);
         process.exit(1);
     }
-    console.error(`[astralkit-mcp] Authenticated as ${auth.email} (${auth.tier})`);
-    const guard = new AuthGuard(apiKey);
+    if (auth.level === 'anonymous') {
+        console.error('[astralkit-mcp] Running in FREE mode (no API key). Grammar, discovery and free components are available.\n' +
+            '[astralkit-mcp] Premium tools + the full library need a Pro key: https://astralkit.com/settings');
+    }
+    else if (auth.level === 'free') {
+        console.error(`[astralkit-mcp] Authenticated as ${auth.email} (${auth.tier} — free tier). ` +
+            'Premium tools need a Pro plan: https://astralkit.com/pricing');
+    }
+    else {
+        console.error(`[astralkit-mcp] Authenticated as ${auth.email} (${auth.tier})`);
+    }
+    const guard = new AuthGuard(apiKey, auth);
     const server = createServer(auth, guard, apiKey);
     const transport = new StdioServerTransport();
     await server.connect(transport);