@vibecheckai/cli 3.1.2 → 3.1.4

package/bin/runners/runPolish.js

@@ -0,0 +1,2452 @@
+/**
+ * vibecheck polish - Production Polish Analyzer
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * Finds all the small detailed things you forgot - the polish that makes
+ * projects production-ready.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Categories:
+ * - Frontend: Error boundaries, 404 pages, loading states, empty states
+ * - Backend: Health endpoints, graceful shutdown, rate limiting, validation
+ * - Security: HTTPS, CORS, CSP, secrets management, auth headers
+ * - Performance: Caching, compression, lazy loading, bundle optimization
+ * - Accessibility: ARIA labels, focus management, color contrast, keyboard nav
+ * - SEO: Meta tags, sitemap, robots.txt, Open Graph, structured data
+ * - Configuration: Environment variables, feature flags, logging
+ * - Documentation: README, API docs, CHANGELOG, contributing guide
+ * - Infrastructure: Docker, CI/CD, monitoring, backups
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TERMINAL STYLING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  underline: '\x1b[4m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+};
+
+const icons = {
+  critical: '🔴',
+  high: '🟠',
+  medium: '🟡',
+  low: '🔵',
+  check: '✓',
+  cross: '✗',
+  arrow: '→',
+  star: '★',
+  sparkle: '✨',
+  wrench: '🔧',
+  rocket: '🚀',
+  shield: '🛡️',
+  lightning: '⚡',
+  eye: '👁️',
+  search: '🔍',
+  book: '📖',
+  gear: '⚙️',
+  server: '🖥️',
+  lock: '🔒',
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UTILITY FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function pathExists(filePath) {
+  try {
+    await fs.promises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findFile(dir, pattern, maxDepth = 5, currentDepth = 0) {
+  if (currentDepth >= maxDepth) return null;
+  
+  try {
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      // Skip node_modules, .git, dist, etc.
+      if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build') {
+        continue;
+      }
+      
+      const fullPath = path.join(dir, entry.name);
+      
+      if (entry.isDirectory()) {
+        const found = await findFile(fullPath, pattern, maxDepth, currentDepth + 1);
+        if (found) return found;
+      } else if (pattern.test(entry.name)) {
+        return fullPath;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function readFileSafe(filePath) {
+  try {
+    return await fs.promises.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function fileContains(filePath, pattern) {
+  const content = await readFileSafe(filePath);
+  if (!content) return false;
+  return pattern.test(content);
+}
+
+async function findAllFiles(dir, pattern, maxDepth = 5, currentDepth = 0) {
+  if (currentDepth >= maxDepth) return [];
+  const results = [];
+  
+  try {
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build') {
+        continue;
+      }
+      
+      const fullPath = path.join(dir, entry.name);
+      
+      if (entry.isDirectory()) {
+        const found = await findAllFiles(fullPath, pattern, maxDepth, currentDepth + 1);
+        results.push(...found);
+      } else if (pattern.test(entry.name)) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+  
+  return results;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// POLISH CHECKERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const checkers = {
+  // ─────────────────────────────────────────────────────────────────────────────
+  // FRONTEND CHECKER - Comprehensive UX/UI Polish Analysis
+  // ─────────────────────────────────────────────────────────────────────────────
+  async frontend(projectPath) {
+    const issues = [];
+    const srcPath = path.join(projectPath, 'src');
+    const appPath = path.join(projectPath, 'app'); // Next.js app router
+    const pagesPath = path.join(projectPath, 'pages'); // Next.js pages router
+    const componentsPath = path.join(srcPath, 'components');
+    
+    const hasSrc = await pathExists(srcPath);
+    const hasApp = await pathExists(appPath);
+    const hasPages = await pathExists(pagesPath);
+    
+    if (!hasSrc && !hasApp && !hasPages) return issues;
+    
+    const searchPath = hasSrc ? srcPath : (hasApp ? appPath : pagesPath);
+    const packageJson = await readFileSafe(path.join(projectPath, 'package.json'));
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ERROR HANDLING & BOUNDARIES
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasErrorBoundary = await findFile(searchPath, /ErrorBoundary|error\.(tsx?|jsx?)$/i);
+    if (!hasErrorBoundary) {
+      issues.push({
+        id: 'missing-error-boundary',
+        category: 'Frontend',
+        severity: 'critical',
+        title: 'Missing Error Boundary',
+        description: 'No error boundary component found. React errors will crash the entire app.',
+        suggestion: 'Add ErrorBoundary component to catch and handle React errors gracefully.',
+        autoFixable: true,
+        aiPrompt: `Create a reusable ErrorBoundary component for React/Next.js that:
+1. Catches JavaScript errors anywhere in the child component tree
+2. Logs errors to console and optionally to an error tracking service
+3. Displays a user-friendly fallback UI with:
+   - A friendly error message
+   - A "Try Again" button that resets the error state
+   - Option to report the error
+4. Supports custom fallback UI via props
+5. Uses TypeScript with proper typing
+6. Includes a useErrorBoundary hook for functional components
+7. Has smooth fade-in animation for the fallback UI
+
+Place it in src/components/ErrorBoundary.tsx`,
+      });
+    }
+    
+    const has404 = await findFile(searchPath, /not-found|NotFound|404/i);
+    if (!has404) {
+      issues.push({
+        id: 'missing-404',
+        category: 'Frontend',
+        severity: 'medium',
+        title: 'Missing 404 Page',
+        description: 'No custom 404/NotFound page found. Users will see default browser error.',
+        suggestion: 'Add a custom 404 page with navigation options.',
+        autoFixable: true,
+        aiPrompt: `Create a beautiful, user-friendly 404 Not Found page that:
+1. Has a visually appealing design with subtle animations
+2. Shows a clear "Page Not Found" message
+3. Includes helpful navigation options:
+   - Go back to previous page button
+   - Go to homepage button
+   - Search functionality (if applicable)
+   - Popular/suggested links
+4. Has a fun illustration or animation (CSS-based, no external images)
+5. Is fully responsive for mobile
+6. Maintains the site's design language
+7. Includes proper meta tags for SEO
+
+For Next.js App Router: Create app/not-found.tsx
+For Pages Router: Create pages/404.tsx`,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // LOADING STATES & SKELETONS
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasLoadingSpinner = await findFile(searchPath, /Spinner|LoadingSpinner/i);
+    if (!hasLoadingSpinner) {
+      issues.push({
+        id: 'missing-spinner',
+        category: 'Frontend',
+        severity: 'high',
+        title: 'Missing Loading Spinner',
+        description: 'No spinner component found. Users need visual feedback during loading.',
+        suggestion: 'Add a reusable Spinner component with multiple sizes and variants.',
+        autoFixable: true,
+        aiPrompt: `Create a modern, reusable Spinner/Loading component that:
+1. Has multiple size variants: sm, md, lg, xl
+2. Supports custom colors via props or CSS variables
+3. Has multiple styles: circular spinner, dots, pulse, bars
+4. Uses pure CSS animations (no external dependencies)
+5. Is accessible with proper ARIA attributes (role="status", aria-label)
+6. Supports dark/light mode automatically
+7. Can be used inline or as an overlay
+8. Has smooth entrance/exit animations
+9. TypeScript with proper prop types
+
+Create: src/components/ui/Spinner.tsx and src/components/ui/Spinner.css`,
+      });
+    }
+    
+    const hasSkeleton = await findFile(searchPath, /Skeleton|Shimmer|Placeholder/i);
+    if (!hasSkeleton) {
+      issues.push({
+        id: 'missing-skeleton',
+        category: 'Frontend',
+        severity: 'high',
+        title: 'Missing Skeleton Loaders',
+        description: 'No skeleton/shimmer components found. Skeleton loaders provide better perceived performance than spinners.',
+        suggestion: 'Add skeleton components for content placeholders.',
+        autoFixable: true,
+        aiPrompt: `Create a comprehensive Skeleton loading system with:
+
+1. Base Skeleton component with:
+   - Shimmer animation effect
+   - Multiple variants: text, circular, rectangular, rounded
+   - Customizable width, height, border-radius
+   - Animation that flows left-to-right with gradient
+
+2. Pre-built skeleton patterns:
+   - SkeletonText (paragraph lines with varying widths)
+   - SkeletonAvatar (circular profile picture placeholder)
+   - SkeletonCard (card layout placeholder)
+   - SkeletonTable (table rows placeholder)
+   - SkeletonList (list items placeholder)
+   - SkeletonImage (image placeholder with aspect ratio)
+
+3. Features:
+   - CSS-only animations (performant)
+   - Dark/light mode support
+   - Customizable animation speed
+   - Can disable animation for reduced motion preference
+   - TypeScript with proper types
+
+Create: src/components/ui/Skeleton.tsx with all variants`,
+      });
+    }
+    
+    const hasLoadingPage = await findFile(searchPath, /loading\.(tsx?|jsx?)$/i);
+    if (!hasLoadingPage && hasApp) {
+      issues.push({
+        id: 'missing-loading-page',
+        category: 'Frontend',
+        severity: 'medium',
+        title: 'Missing Next.js Loading State',
+        description: 'No loading.tsx found. Next.js App Router supports automatic loading states.',
+        suggestion: 'Add loading.tsx files for route segments.',
+        autoFixable: true,
+        aiPrompt: `Create a loading.tsx file for Next.js App Router that:
+1. Shows a full-page skeleton loader matching your layout
+2. Uses your Skeleton components for consistency
+3. Includes a subtle progress indicator
+4. Maintains layout structure to prevent layout shift
+5. Has smooth fade-out when content loads
+
+Create: app/loading.tsx (root level) and consider adding to major route segments`,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // EMPTY STATES & FEEDBACK
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasEmptyState = await findFile(searchPath, /EmptyState|Empty|NoData|NoResults/i);
+    if (!hasEmptyState) {
+      issues.push({
+        id: 'missing-empty-states',
+        category: 'Frontend',
+        severity: 'medium',
+        title: 'Missing Empty States',
+        description: 'No empty state components found. Users need helpful messages when data is empty.',
+        suggestion: 'Add EmptyState components for lists and data displays.',
+        autoFixable: true,
+        aiPrompt: `Create a versatile EmptyState component system with:
+
+1. Base EmptyState component with:
+   - Icon slot (customizable)
+   - Title and description
+   - Action button(s)
+   - Illustration option
+
+2. Pre-built variants:
+   - EmptySearch: "No results found" with search tips
+   - EmptyList: "No items yet" with add item CTA
+   - EmptyInbox: "All caught up!" positive empty state
+   - EmptyError: "Something went wrong" with retry
+   - EmptyPermission: "Access denied" with request access
+   - EmptyOffline: "You're offline" with retry when online
+
+3. Features:
+   - Subtle entrance animation
+   - Responsive design
+   - Supports custom illustrations
+   - Action buttons with loading states
+   - TypeScript with proper props
+
+Create: src/components/ui/EmptyState.tsx with all variants`,
+      });
+    }
+    
+    const hasToast = await findFile(searchPath, /Toast|Notification|Snackbar/i);
+    if (!hasToast) {
+      issues.push({
+        id: 'missing-toast',
+        category: 'Frontend',
+        severity: 'high',
+        title: 'Missing Toast/Notification System',
+        description: 'No toast or notification component found for user feedback.',
+        suggestion: 'Add a toast/notification system for user feedback on actions.',
+        autoFixable: true,
+        aiPrompt: `Create a complete Toast notification system with:
+
+1. Toast component with:
+   - Variants: success, error, warning, info, loading
+   - Auto-dismiss with configurable duration
+   - Manual dismiss button
+   - Progress bar showing time remaining
+   - Stack multiple toasts
+   - Position options: top-right, top-center, bottom-right, etc.
+
+2. Toast provider/context:
+   - useToast() hook for easy triggering
+   - toast.success(), toast.error(), etc. methods
+   - toast.promise() for async operations
+   - Global configuration
+
+3. Features:
+   - Smooth slide-in/out animations
+   - Swipe to dismiss on mobile
+   - Pause on hover
+   - Accessible with ARIA live regions
+   - Queue management
+   - TypeScript with proper types
+
+Create: src/components/ui/Toast.tsx and src/hooks/useToast.ts`,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // FORMS & INPUT FEEDBACK
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasFormValidation = await findFile(searchPath, /FormError|FieldError|ValidationMessage/i);
+    const hasReactHookForm = packageJson && /react-hook-form/i.test(packageJson);
+    if (!hasFormValidation && !hasReactHookForm) {
+      issues.push({
+        id: 'missing-form-validation-ui',
+        category: 'Frontend',
+        severity: 'high',
+        title: 'Missing Form Validation UI',
+        description: 'No form validation components found. Users need clear feedback on form errors.',
+        suggestion: 'Add form validation components with clear error states.',
+        autoFixable: true,
+        aiPrompt: `Create a comprehensive form validation UI system with:
+
+1. FormField wrapper component with:
+   - Label with required indicator
+   - Help text / description
+   - Error message display
+   - Success state indicator
+   - Character counter for text inputs
+
+2. Input components with built-in validation states:
+   - TextInput with error/success borders
+   - SelectInput with validation
+   - Checkbox/Radio with error states
+   - TextArea with validation
+
+3. Validation feedback:
+   - Inline error messages with icons
+   - Shake animation on error
+   - Real-time validation feedback
+   - Form-level error summary
+   - Success checkmark animation
+
+4. Features:
+   - Works with react-hook-form or standalone
+   - Accessible error announcements
+   - Touch-friendly error targets
+   - TypeScript with proper types
+
+Create: src/components/ui/FormField.tsx and related input components`,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // MICRO-INTERACTIONS & ANIMATIONS
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasAnimationLib = packageJson && /framer-motion|react-spring|@react-spring|gsap|animejs/i.test(packageJson);
+    const hasAnimations = await findFile(searchPath, /animate|motion|transition|useSpring/i);
+    if (!hasAnimationLib && !hasAnimations) {
+      issues.push({
+        id: 'missing-animations',
+        category: 'Frontend',
+        severity: 'medium',
+        title: 'Missing Animation System',
+        description: 'No animation library or utilities found. Animations make UX feel polished.',
+        suggestion: 'Add framer-motion or CSS animations for micro-interactions.',
+        autoFixable: true,
+        aiPrompt: `Create a lightweight animation system with:
+
+1. CSS animation utilities (no library needed):
+   - Fade in/out
+   - Slide in from directions
+   - Scale up/down
+   - Bounce, pulse, shake
+   - Stagger children animations
+
+2. Animation wrapper components:
+   - <FadeIn> - fade in on mount
+   - <SlideIn direction="up|down|left|right">
+   - <ScaleIn> - scale from 0 to 1
+   - <AnimatePresence> - animate on unmount
+   - <StaggerChildren> - stagger child animations
+
+3. CSS utilities:
+   - .animate-fade-in, .animate-slide-up, etc.
+   - Animation delay utilities
+   - Reduced motion media query support
+   - Duration and easing variables
+
+4. Hooks:
+   - useInView() - trigger animation when element is visible
+   - useAnimation() - programmatic control
+
+Create: src/styles/animations.css and src/components/ui/Animate.tsx
+
+Or install framer-motion: npm install framer-motion`,
+      });
+    }
+    
+    const hasHoverEffects = await findAllFiles(searchPath, /\.(css|scss|tsx?|jsx?)$/);
+    let foundHoverStates = false;
+    for (const file of hasHoverEffects.slice(0, 20)) {
+      const content = await readFileSafe(file);
+      if (content && /:hover|onMouseEnter|hover:/i.test(content)) {
+        foundHoverStates = true;
+        break;
+      }
+    }
+    if (!foundHoverStates) {
+      issues.push({
+        id: 'missing-hover-states',
+        category: 'Frontend',
+        severity: 'medium',
+        title: 'Missing Hover States',
+        description: 'No hover effects detected. Interactive elements need visual feedback on hover.',
+        suggestion: 'Add hover states to buttons, links, and interactive elements.',
+        autoFixable: true,
+        aiPrompt: `Add comprehensive hover states to your components:
+
+1. Button hover effects:
+   - Subtle background color shift
+   - Slight scale transform (1.02)
+   - Shadow elevation change
+   - Underline animation for text buttons
+
+2. Card hover effects:
+   - Lift effect with shadow
+   - Border color change
+   - Subtle background shift
+   - Scale transform
+
+3. Link hover effects:
+   - Underline animation (slide in)
+   - Color transition
+   - Arrow/icon movement
+
+4. Interactive elements:
+   - Focus-visible states (keyboard users)
+   - Active/pressed states
+   - Disabled state styling
+
+5. CSS utilities to add:
+\`\`\`css
+.hover-lift:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+}
+
+.hover-scale:hover {
+  transform: scale(1.02);
+}
+
+.hover-glow:hover {
+  box-shadow: 0 0 20px rgba(var(--primary-rgb), 0.3);
+}
+\`\`\`
+
+Add to: src/styles/interactions.css or your global styles`,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // HAPTIC FEEDBACK & MOBILE UX
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasHapticFeedback = await findFile(searchPath, /haptic|vibrate|navigator\.vibrate/i);
+    if (!hasHapticFeedback) {
+      issues.push({
+        id: 'missing-haptic-feedback',
+        category: 'Frontend',
+        severity: 'low',
+        title: 'Missing Haptic Feedback',
+        description: 'No haptic feedback found. Mobile users benefit from tactile feedback on interactions.',
+        suggestion: 'Add haptic feedback for key interactions on mobile.',
+        autoFixable: true,
+        aiPrompt: `Create a haptic feedback utility system:
+
+1. useHaptic() hook:
+\`\`\`typescript
+const useHaptic = () => {
+  const trigger = (type: 'light' | 'medium' | 'heavy' | 'success' | 'error') => {
+    if (!navigator.vibrate) return;
+    
+    const patterns = {
+      light: [10],
+      medium: [20],
+      heavy: [30],
+      success: [10, 50, 10],
+      error: [50, 30, 50, 30, 50],
+    };
+    
+    navigator.vibrate(patterns[type]);
+  };
+  
+  return { trigger };
+};
+\`\`\`
+
+2. Integration points:
+   - Button clicks (light)
+   - Form submission success (success)
+   - Form validation error (error)
+   - Toggle switches (light)
+   - Pull-to-refresh complete (medium)
+   - Delete/destructive actions (heavy)
+
+3. Best practices:
+   - Always check navigator.vibrate support
+   - Respect user preferences (reduced motion)
+   - Don't overuse - only key interactions
+   - Different patterns for different actions
+
+Create: src/hooks/useHaptic.ts`,
+      });
+    }
+    
+    const hasPullToRefresh = await findFile(searchPath, /PullToRefresh|pull-to-refresh|usePullRefresh/i);
+    if (!hasPullToRefresh && packageJson && /react-native|mobile|pwa/i.test(packageJson)) {
+      issues.push({
+        id: 'missing-pull-refresh',
+        category: 'Frontend',
+        severity: 'low',
+        title: 'Missing Pull-to-Refresh',
+        description: 'No pull-to-refresh found. Mobile/PWA apps benefit from this gesture.',
+        suggestion: 'Add pull-to-refresh for mobile list views.',
+        autoFixable: true,
+        aiPrompt: `Create a pull-to-refresh component for mobile:
+
+1. PullToRefresh wrapper component:
+   - Touch gesture detection
+   - Visual pull indicator
+   - Loading spinner during refresh
+   - Haptic feedback on trigger
+   - Smooth animations
+
+2. Features:
+   - Configurable pull threshold
+   - Custom pull indicator
+   - Callback on refresh
+   - Disable on desktop
+
+Create: src/components/ui/PullToRefresh.tsx`,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ACCESSIBILITY (ARIA & A11Y)
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasAriaLive = await findFile(searchPath, /aria-live|role="alert"|role="status"/i);
+    if (!hasAriaLive) {
+      issues.push({
+        id: 'missing-aria-live',
+        category: 'Frontend',
+        severity: 'high',
+        title: 'Missing ARIA Live Regions',
+        description: 'No ARIA live regions found. Screen readers won\'t announce dynamic content changes.',
+        suggestion: 'Add aria-live regions for toasts, alerts, and dynamic updates.',
+        autoFixable: true,
+        aiPrompt: `Add ARIA live regions for accessibility:
+
+1. Create an Announcer component for screen readers:
+\`\`\`tsx
+const Announcer = () => {
+  const [message, setMessage] = useState('');
+  
+  // Expose via context or global
+  useEffect(() => {
+    window.announce = (msg: string) => setMessage(msg);
+    return () => delete window.announce;
+  }, []);
+  
+  return (
+    <div 
+      role="status" 
+      aria-live="polite" 
+      aria-atomic="true"
+      className="sr-only"
+    >
+      {message}
+    </div>
+  );
+};
+\`\`\`
+
+2. Places to add aria-live:
+   - Toast notifications: aria-live="polite"
+   - Error alerts: aria-live="assertive"
+   - Loading states: aria-live="polite" aria-busy="true"
+   - Search results count
+   - Form validation errors
+
+3. Screen reader only utility:
+\`\`\`css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+\`\`\`
+
+Create: src/components/ui/Announcer.tsx`,
+      });
+    }
+    
+    const hasFocusTrap = await findFile(searchPath, /FocusTrap|focus-trap|useFocusTrap/i);
+    const hasModal = await findFile(searchPath, /Modal|Dialog|Drawer/i);
+    if (hasModal && !hasFocusTrap) {
+      issues.push({
+        id: 'missing-focus-trap',
+        category: 'Frontend',
+        severity: 'high',
+        title: 'Missing Focus Trap for Modals',
+        description: 'Modal/Dialog found but no focus trap. Keyboard users can tab outside the modal.',
+        suggestion: 'Add focus trap to modals and dialogs.',
+        autoFixable: true,
+        aiPrompt: `Add focus trapping to modals and dialogs:
+
+1. Create useFocusTrap hook:
+\`\`\`typescript
+const useFocusTrap = (isOpen: boolean) => {
+  const ref = useRef<HTMLElement>(null);
+  
+  useEffect(() => {
+    if (!isOpen || !ref.current) return;
+    
+    const focusableElements = ref.current.querySelectorAll(
+      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+    );
+    const firstElement = focusableElements[0] as HTMLElement;
+    const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;
+    
+    // Focus first element on open
+    firstElement?.focus();
+    
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+      
+      if (e.shiftKey && document.activeElement === firstElement) {
+        e.preventDefault();
+        lastElement?.focus();
+      } else if (!e.shiftKey && document.activeElement === lastElement) {
+        e.preventDefault();
+        firstElement?.focus();
+      }
+    };
+    
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen]);
+  
+  return ref;
+};
+\`\`\`
+
+2. Additional requirements:
+   - Return focus to trigger element on close
+   - Handle Escape key to close
+   - Prevent body scroll when open
+   - aria-modal="true" on modal
+
+Create: src/hooks/useFocusTrap.ts`,
+      });
+    }
+    
+    const hasSkipLink = await findFile(searchPath, /SkipLink|skip-to-content|skip-nav/i);
+    if (!hasSkipLink) {
+      issues.push({
+        id: 'missing-skip-link',
+        category: 'Frontend',
+        severity: 'medium',
+        title: 'Missing Skip Link',
+        description: 'No skip-to-content link found. Keyboard users can\'t skip navigation.',
+        suggestion: 'Add a skip-to-main-content link at the top of pages.',
+        autoFixable: true,
+        aiPrompt: `Add a skip link for keyboard navigation:
+
+\`\`\`tsx
+// components/SkipLink.tsx
+export const SkipLink = () => (
+  <a
+    href="#main-content"
+    className="skip-link"
+  >
+    Skip to main content
+  </a>
+);
+
+// styles
+.skip-link {
+  position: absolute;
+  top: -40px;
+  left: 0;
+  background: var(--primary);
+  color: white;
+  padding: 8px 16px;
+  z-index: 100;
+  transition: top 0.3s;
+}
+
+.skip-link:focus {
+  top: 0;
+}
+
+// Add id to main content
+<main id="main-content">
+\`\`\`
+
+Place at the very top of your layout, before the header.`,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CACHING & PERFORMANCE
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasSWR = packageJson && /swr|@tanstack\/react-query|react-query/i.test(packageJson);
+    if (!hasSWR) {
+      issues.push({
+        id: 'missing-data-caching',
+        category: 'Frontend',
+        severity: 'high',
+        title: 'Missing Data Caching Library',
+        description: 'No SWR or React Query found. Data fetching lacks caching, revalidation, and deduplication.',
+        suggestion: 'Add SWR or TanStack Query for data caching and synchronization.',
+        autoFixable: false,
+        aiPrompt: `Add a data fetching and caching solution:
+
+Option 1: SWR (lighter weight)
+\`\`\`bash
+npm install swr
+\`\`\`
+
+\`\`\`typescript
+// hooks/useApi.ts
+import useSWR from 'swr';
+
+const fetcher = (url: string) => fetch(url).then(r => r.json());
+
+export const useUser = (id: string) => {
+  const { data, error, isLoading, mutate } = useSWR(
+    \`/api/users/\${id}\`,
+    fetcher,
+    {
+      revalidateOnFocus: true,
+      revalidateOnReconnect: true,
+      dedupingInterval: 2000,
+    }
+  );
+  
+  return { user: data, error, isLoading, refresh: mutate };
+};
+\`\`\`
+
+Option 2: TanStack Query (more features)
+\`\`\`bash
+npm install @tanstack/react-query
+\`\`\`
+
+Benefits you'll get:
+- Automatic caching
+- Background revalidation
+- Request deduplication
+- Optimistic updates
+- Offline support
+- Retry logic`,
+      });
+    }
+    
+    const hasMemoization = await findFile(searchPath, /useMemo|useCallback|React\.memo/i);
+    if (!hasMemoization) {
+      issues.push({
+        id: 'missing-memoization',
+        category: 'Frontend',
+        severity: 'low',
+        title: 'No Memoization Detected',
+        description: 'No useMemo/useCallback/React.memo usage found. May have unnecessary re-renders.',
+        suggestion: 'Review components for memoization opportunities.',
+        autoFixable: false,
+        aiPrompt: `Review your components for memoization opportunities:
+
+1. useMemo - for expensive calculations:
+\`\`\`typescript
+const sortedItems = useMemo(() => 
+  items.sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+\`\`\`
+
+2. useCallback - for functions passed as props:
+\`\`\`typescript
+const handleClick = useCallback((id: string) => {
+  setSelected(id);
+}, []);
+\`\`\`
+
+3. React.memo - for components that receive same props:
+\`\`\`typescript
+const ExpensiveList = React.memo(({ items }) => {
+  return items.map(item => <Item key={item.id} {...item} />);
+});
+\`\`\`
+
+Where to apply:
+- List item components
+- Charts and visualizations
+- Components receiving objects/arrays as props
+- Expensive filter/sort operations
+- Event handlers passed to children`,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // LOGGING & DEBUGGING
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasLogger = await findFile(searchPath, /logger|logging|winston|pino|loglevel/i);
+    const hasConsoleRemoval = packageJson && /babel-plugin-transform-remove-console|terser/i.test(packageJson);
+    if (!hasLogger) {
+      issues.push({
+        id: 'missing-frontend-logger',
+        category: 'Frontend',
+        severity: 'medium',
+        title: 'Missing Logging System',
+        description: 'No structured logging found. console.log statements are not suitable for production.',
+        suggestion: 'Add a logging utility that can be disabled in production.',
+        autoFixable: true,
+        aiPrompt: `Create a frontend logging utility:
+
+\`\`\`typescript
+// lib/logger.ts
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const isDev = process.env.NODE_ENV === 'development';
+
+const logger = {
+  debug: (...args: any[]) => isDev && console.debug('[DEBUG]', ...args),
+  info: (...args: any[]) => isDev && console.info('[INFO]', ...args),
+  warn: (...args: any[]) => console.warn('[WARN]', ...args),
+  error: (...args: any[]) => {
+    console.error('[ERROR]', ...args);
+    // Send to error tracking service in production
+    if (!isDev && typeof window !== 'undefined') {
+      // Sentry.captureException(args[0]);
+    }
+  },
+  
+  // Performance logging
+  time: (label: string) => isDev && console.time(label),
+  timeEnd: (label: string) => isDev && console.timeEnd(label),
+  
+  // Group logs
+  group: (label: string) => isDev && console.group(label),
+  groupEnd: () => isDev && console.groupEnd(),
+};
+
+export default logger;
+\`\`\`
+
+Usage:
+\`\`\`typescript
+import logger from '@/lib/logger';
+
+logger.debug('User data:', userData);
+logger.error('Failed to fetch', error);
+
+logger.time('render');
+// ... expensive operation
+logger.timeEnd('render');
+\`\`\``,
+      });
+    }
+    
+    const hasErrorTracking = packageJson && /sentry|bugsnag|rollbar|logrocket|@sentry/i.test(packageJson);
+    if (!hasErrorTracking) {
+      issues.push({
+        id: 'missing-error-tracking',
+        category: 'Frontend',
+        severity: 'high',
+        title: 'Missing Error Tracking',
+        description: 'No error tracking service found. Production errors will go unnoticed.',
+        suggestion: 'Add Sentry, Bugsnag, or similar for production error monitoring.',
+        autoFixable: false,
+        aiPrompt: `Set up error tracking with Sentry:
+
+1. Install Sentry:
+\`\`\`bash
+npm install @sentry/nextjs
+npx @sentry/wizard@latest -i nextjs
+\`\`\`
+
+2. This will create:
+   - sentry.client.config.ts
+   - sentry.server.config.ts
+   - sentry.edge.config.ts
+
+3. Configure environment:
+\`\`\`env
+SENTRY_DSN=your-dsn-here
+SENTRY_AUTH_TOKEN=your-auth-token
+\`\`\`
+
+4. Custom error boundary integration:
+\`\`\`typescript
+import * as Sentry from '@sentry/nextjs';
+
+// In your error boundary
+componentDidCatch(error, errorInfo) {
+  Sentry.captureException(error, { extra: errorInfo });
+}
+\`\`\`
+
+5. User context:
+\`\`\`typescript
+Sentry.setUser({ id: user.id, email: user.email });
+\`\`\``,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // IMAGE & MEDIA OPTIMIZATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasLazyImages = await findFile(searchPath, /loading="lazy"|LazyImage|Image.*priority/i);
+    if (!hasLazyImages) {
+      issues.push({
+        id: 'missing-lazy-images',
+        category: 'Frontend',
+        severity: 'medium',
+        title: 'Missing Lazy Loading for Images',
+        description: 'No lazy loading for images detected. All images load immediately.',
+        suggestion: 'Add lazy loading to below-the-fold images.',
+        autoFixable: true,
+        aiPrompt: `Implement lazy loading for images:
+
+1. For Next.js - use next/image:
+\`\`\`tsx
+import Image from 'next/image';
+
+// Lazy load by default, add priority for above-fold
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  width={1200}
+  height={600}
+  priority // Only for above-the-fold images
+/>
+
+// Below the fold - lazy loads automatically
+<Image
+  src="/feature.jpg"
+  alt="Feature"
+  width={600}
+  height={400}
+  // No priority = lazy loaded
+/>
+\`\`\`
+
+2. For regular img tags:
+\`\`\`tsx
+<img
+  src="/image.jpg"
+  alt="Description"
+  loading="lazy"
+  decoding="async"
+/>
+\`\`\`
+
+3. Create a LazyImage component:
+\`\`\`tsx
+export const LazyImage = ({ src, alt, ...props }) => (
+  <img
+    src={src}
+    alt={alt}
+    loading="lazy"
+    decoding="async"
+    {...props}
+  />
+);
+\`\`\``,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // THEME & DARK MODE
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasDarkMode = await findFile(searchPath, /dark-mode|darkMode|theme-toggle|ThemeProvider|useTheme/i);
+    if (!hasDarkMode) {
+      issues.push({
+        id: 'missing-dark-mode',
+        category: 'Frontend',
+        severity: 'low',
+        title: 'Missing Dark Mode Support',
+        description: 'No dark mode implementation found. Many users prefer dark mode.',
+        suggestion: 'Add dark mode toggle with system preference detection.',
+        autoFixable: true,
+        aiPrompt: `Implement dark mode with system preference detection:
+
+1. Create ThemeProvider and useTheme hook:
+\`\`\`typescript
+// contexts/ThemeContext.tsx
+type Theme = 'light' | 'dark' | 'system';
+
+const ThemeContext = createContext<{
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+}>({ theme: 'system', setTheme: () => {} });
+
+export const ThemeProvider = ({ children }) => {
+  const [theme, setTheme] = useState<Theme>('system');
+  
+  useEffect(() => {
+    const saved = localStorage.getItem('theme') as Theme;
+    if (saved) setTheme(saved);
+  }, []);
+  
+  useEffect(() => {
+    const root = document.documentElement;
+    const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    const isDark = theme === 'dark' || (theme === 'system' && systemDark);
+    
+    root.classList.toggle('dark', isDark);
+    localStorage.setItem('theme', theme);
+  }, [theme]);
+  
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+};
+
+export const useTheme = () => useContext(ThemeContext);
+\`\`\`
+
+2. CSS variables approach:
+\`\`\`css
+:root {
+  --bg: #ffffff;
+  --text: #1a1a1a;
+  --primary: #0066cc;
+}
+
+.dark {
+  --bg: #1a1a1a;
+  --text: #ffffff;
+  --primary: #66b3ff;
+}
+\`\`\`
+
+3. Theme toggle component:
+\`\`\`tsx
+export const ThemeToggle = () => {
+  const { theme, setTheme } = useTheme();
+  
+  return (
+    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+      {theme === 'dark' ? '☀️' : '🌙'}
+    </button>
+  );
+};
+\`\`\``,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CONFIRMATION & DESTRUCTIVE ACTIONS
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasConfirmDialog = await findFile(searchPath, /ConfirmDialog|Confirm|AlertDialog|useConfirm/i);
+    if (!hasConfirmDialog) {
+      issues.push({
+        id: 'missing-confirm-dialog',
+        category: 'Frontend',
+        severity: 'high',
+        title: 'Missing Confirmation Dialog',
+        description: 'No confirmation dialog found. Destructive actions should require confirmation.',
+        suggestion: 'Add a confirmation dialog for delete, logout, and irreversible actions.',
+        autoFixable: true,
+        aiPrompt: `Create a confirmation dialog system:
+
+1. ConfirmDialog component:
+\`\`\`tsx
+interface ConfirmDialogProps {
+  isOpen: boolean;
+  onClose: () => void;
+  onConfirm: () => void;
+  title: string;
+  message: string;
+  confirmText?: string;
+  cancelText?: string;
+  variant?: 'danger' | 'warning' | 'info';
+  isLoading?: boolean;
+}
+
+export const ConfirmDialog = ({
+  isOpen, onClose, onConfirm, title, message,
+  confirmText = 'Confirm',
+  cancelText = 'Cancel',
+  variant = 'danger',
+  isLoading = false,
+}) => {
+  return (
+    <Dialog open={isOpen} onClose={onClose}>
+      <div className="confirm-dialog">
+        <h3>{title}</h3>
+        <p>{message}</p>
+        <div className="actions">
+          <Button variant="ghost" onClick={onClose} disabled={isLoading}>
+            {cancelText}
+          </Button>
+          <Button 
+            variant={variant} 
+            onClick={onConfirm}
+            isLoading={isLoading}
+          >
+            {confirmText}
+          </Button>
+        </div>
+      </div>
+    </Dialog>
+  );
+};
+\`\`\`
+
+2. useConfirm hook for easy usage:
+\`\`\`typescript
+const useConfirm = () => {
+  const [state, setState] = useState({ isOpen: false, config: null });
+  
+  const confirm = (config) => new Promise((resolve) => {
+    setState({
+      isOpen: true,
+      config: { ...config, resolve }
+    });
+  });
+  
+  const handleConfirm = () => {
+    state.config?.resolve(true);
+    setState({ isOpen: false, config: null });
+  };
+  
+  const handleCancel = () => {
+    state.config?.resolve(false);
+    setState({ isOpen: false, config: null });
+  };
+  
+  return { confirm, ConfirmDialog: /* render dialog */ };
+};
+
+// Usage:
+const { confirm } = useConfirm();
+const shouldDelete = await confirm({
+  title: 'Delete item?',
+  message: 'This action cannot be undone.',
+});
+if (shouldDelete) deleteItem();
+\`\`\``,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // OPTIMISTIC UPDATES
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasOptimisticUpdates = await findFile(searchPath, /optimistic|mutate.*onMutate|useMutation/i);
+    if (!hasOptimisticUpdates && hasSWR) {
+      issues.push({
+        id: 'missing-optimistic-updates',
+        category: 'Frontend',
+        severity: 'low',
+        title: 'No Optimistic Updates',
+        description: 'Data mutations may feel slow without optimistic updates.',
+        suggestion: 'Add optimistic updates for better perceived performance.',
+        autoFixable: false,
+        aiPrompt: `Implement optimistic updates for mutations:
+
+With SWR:
+\`\`\`typescript
+import useSWR, { useSWRConfig } from 'swr';
+
+const useUpdateTodo = () => {
+  const { mutate } = useSWRConfig();
+  
+  const updateTodo = async (id: string, data: Partial<Todo>) => {
+    // Optimistic update
+    mutate(
+      '/api/todos',
+      (todos: Todo[]) => todos.map(t => 
+        t.id === id ? { ...t, ...data } : t
+      ),
+      false // Don't revalidate yet
+    );
+    
+    try {
+      await fetch(\`/api/todos/\${id}\`, {
+        method: 'PATCH',
+        body: JSON.stringify(data),
+      });
+      // Revalidate after success
+      mutate('/api/todos');
+    } catch (error) {
+      // Revert on error
+      mutate('/api/todos');
+      throw error;
+    }
+  };
+  
+  return { updateTodo };
+};
+\`\`\`
+
+With TanStack Query:
+\`\`\`typescript
+const useUpdateTodo = () => {
+  const queryClient = useQueryClient();
+  
+  return useMutation({
+    mutationFn: updateTodoApi,
+    onMutate: async (newTodo) => {
+      await queryClient.cancelQueries({ queryKey: ['todos'] });
+      const previous = queryClient.getQueryData(['todos']);
+      
+      queryClient.setQueryData(['todos'], (old) =>
+        old.map(t => t.id === newTodo.id ? { ...t, ...newTodo } : t)
+      );
+      
+      return { previous };
+    },
+    onError: (err, newTodo, context) => {
+      queryClient.setQueryData(['todos'], context.previous);
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] });
+    },
+  });
+};
+\`\`\``,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // KEYBOARD SHORTCUTS
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasKeyboardShortcuts = await findFile(searchPath, /useHotkeys|Keyboard|shortcut|Cmd\+|Ctrl\+/i);
+    if (!hasKeyboardShortcuts) {
+      issues.push({
+        id: 'missing-keyboard-shortcuts',
+        category: 'Frontend',
+        severity: 'low',
+        title: 'Missing Keyboard Shortcuts',
+        description: 'No keyboard shortcuts detected. Power users benefit from keyboard navigation.',
+        suggestion: 'Add keyboard shortcuts for common actions.',
+        autoFixable: true,
+        aiPrompt: `Implement keyboard shortcuts for power users:
+
+1. Create useHotkey hook:
+\`\`\`typescript
+const useHotkey = (key: string, callback: () => void, deps: any[] = []) => {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      const isMac = navigator.platform.includes('Mac');
+      const modifier = isMac ? e.metaKey : e.ctrlKey;
+      
+      // Parse key combo like "mod+k" or "shift+enter"
+      const parts = key.toLowerCase().split('+');
+      const mainKey = parts[parts.length - 1];
+      const needsModifier = parts.includes('mod');
+      const needsShift = parts.includes('shift');
+      
+      if (needsModifier && !modifier) return;
+      if (needsShift && !e.shiftKey) return;
+      if (e.key.toLowerCase() !== mainKey) return;
+      
+      e.preventDefault();
+      callback();
+    };
+    
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, deps);
+};
+\`\`\`
+
+2. Common shortcuts to implement:
+   - Cmd/Ctrl + K: Search / Command palette
+   - Cmd/Ctrl + S: Save
+   - Cmd/Ctrl + Enter: Submit form
+   - Escape: Close modal/dialog
+   - ?: Show keyboard shortcuts help
+
+3. Display shortcut hints in UI:
+\`\`\`tsx
+<Button>
+  Save
+  <kbd className="ml-2 opacity-50">⌘S</kbd>
+</Button>
+\`\`\``,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SCROLL BEHAVIOR
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasScrollToTop = await findFile(searchPath, /ScrollToTop|scroll-to-top|BackToTop/i);
+    if (!hasScrollToTop) {
+      issues.push({
+        id: 'missing-scroll-to-top',
+        category: 'Frontend',
+        severity: 'low',
+        title: 'Missing Scroll-to-Top Button',
+        description: 'No scroll-to-top button found. Long pages need easy navigation back to top.',
+        suggestion: 'Add a scroll-to-top button for long pages.',
+        autoFixable: true,
+        aiPrompt: `Create a scroll-to-top button:
+
+\`\`\`tsx
+export const ScrollToTop = () => {
+  const [isVisible, setIsVisible] = useState(false);
+  
+  useEffect(() => {
+    const toggleVisibility = () => {
+      setIsVisible(window.scrollY > 500);
+    };
+    
+    window.addEventListener('scroll', toggleVisibility);
+    return () => window.removeEventListener('scroll', toggleVisibility);
+  }, []);
+  
+  const scrollToTop = () => {
+    window.scrollTo({
+      top: 0,
+      behavior: 'smooth'
+    });
+  };
+  
+  if (!isVisible) return null;
+  
+  return (
+    <button
+      onClick={scrollToTop}
+      className="scroll-to-top"
+      aria-label="Scroll to top"
+    >
+      ↑
+    </button>
+  );
+};
+\`\`\`
+
+CSS:
+\`\`\`css
+.scroll-to-top {
+  position: fixed;
+  bottom: 2rem;
+  right: 2rem;
+  width: 48px;
+  height: 48px;
+  border-radius: 50%;
+  background: var(--primary);
+  color: white;
+  border: none;
+  cursor: pointer;
+  opacity: 0.9;
+  transition: opacity 0.2s, transform 0.2s;
+  z-index: 50;
+}
+
+.scroll-to-top:hover {
+  opacity: 1;
+  transform: translateY(-2px);
+}
+\`\`\``,
+      });
+    }
+    
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PROGRESS INDICATORS
+    // ═══════════════════════════════════════════════════════════════════════════
+    
+    const hasProgressBar = await findFile(searchPath, /Progress|ProgressBar|NProgress|nprogress/i);
+    if (!hasProgressBar) {
+      issues.push({
+        id: 'missing-progress-bar',
+        category: 'Frontend',
+        severity: 'medium',
+        title: 'Missing Progress Indicators',
+        description: 'No progress bar found. Users need visual feedback for page transitions and uploads.',
+        suggestion: 'Add progress bar for navigation and long operations.',
+        autoFixable: true,
+        aiPrompt: `Add progress indicators:
+
+1. Page transition progress (NProgress style):
+\`\`\`bash
+npm install nprogress
+npm install @types/nprogress -D
+\`\`\`
+
+\`\`\`tsx
+// app/providers.tsx (Next.js App Router)
+'use client';
+import { useEffect } from 'react';
+import { usePathname, useSearchParams } from 'next/navigation';
+import NProgress from 'nprogress';
+import 'nprogress/nprogress.css';
+
+NProgress.configure({ showSpinner: false });
+
+export function NavigationProgress() {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  
+  useEffect(() => {
+    NProgress.done();
+  }, [pathname, searchParams]);
+  
+  return null;
+}
+\`\`\`
+
+2. Custom progress bar component:
+\`\`\`tsx
+export const ProgressBar = ({ value, max = 100 }) => (
+  <div className="progress-bar" role="progressbar" aria-valuenow={value}>
+    <div 
+      className="progress-bar-fill" 
+      style={{ width: \`\${(value / max) * 100}%\` }}
+    />
+  </div>
+);
+\`\`\`
+
+3. File upload progress:
+\`\`\`tsx
+export const UploadProgress = ({ progress, fileName }) => (
+  <div className="upload-progress">
+    <span>{fileName}</span>
+    <ProgressBar value={progress} />
+    <span>{progress}%</span>
+  </div>
+);
+\`\`\``,
+      });
+    }
+    
+    return issues;
+  },
+  
+  // ─────────────────────────────────────────────────────────────────────────────
+  // BACKEND CHECKER
+  // ─────────────────────────────────────────────────────────────────────────────
+  async backend(projectPath) {
+    const issues = [];
+    const apiPath = path.join(projectPath, 'src', 'server');
+    const apiAltPath = path.join(projectPath, 'api');
+    const pagesApiPath = path.join(projectPath, 'pages', 'api');
+    const appApiPath = path.join(projectPath, 'app', 'api');
+    
+    const hasApi = await pathExists(apiPath) || await pathExists(apiAltPath) ||
+                   await pathExists(pagesApiPath) || await pathExists(appApiPath);
+    
+    if (!hasApi) return issues;
+    
+    // Check for health endpoint
+    const hasHealth = await findFile(projectPath, /health|healthcheck|status/i);
+    if (!hasHealth) {
+      issues.push({
+        id: 'missing-health-endpoint',
+        category: 'Backend',
+        severity: 'high',
+        title: 'Missing Health Endpoint',
+        description: 'No health check endpoint found. Load balancers and monitoring can\'t verify service status.',
+        suggestion: 'Add a /health or /api/health endpoint that returns service status.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for validation library
+    const packageJson = await readFileSafe(path.join(projectPath, 'package.json'));
+    if (packageJson) {
+      const hasValidation = /zod|yup|joi|class-validator|ajv/i.test(packageJson);
+      if (!hasValidation) {
+        issues.push({
+          id: 'missing-validation',
+          category: 'Backend',
+          severity: 'high',
+          title: 'Missing Input Validation',
+          description: 'No validation library found. API inputs may not be properly validated.',
+          suggestion: 'Add zod, yup, joi, or similar for input validation.',
+          autoFixable: false,
+        });
+      }
+    }
+    
+    // Check for rate limiting
+    const hasRateLimiting = packageJson && /rate-limit|ratelimit|express-rate-limit|@upstash\/ratelimit/i.test(packageJson);
+    if (!hasRateLimiting) {
+      issues.push({
+        id: 'missing-rate-limiting',
+        category: 'Backend',
+        severity: 'high',
+        title: 'Missing Rate Limiting',
+        description: 'No rate limiting found. API is vulnerable to abuse and DDoS.',
+        suggestion: 'Add rate limiting middleware to protect your API.',
+        autoFixable: false,
+      });
+    }
+    
+    // Check for error handling middleware
+    const hasErrorMiddleware = await findFile(projectPath, /errorHandler|error-handler|errorMiddleware/i);
+    if (!hasErrorMiddleware) {
+      issues.push({
+        id: 'missing-error-handler',
+        category: 'Backend',
+        severity: 'medium',
+        title: 'Missing Global Error Handler',
+        description: 'No global error handler found. Unhandled errors may leak stack traces.',
+        suggestion: 'Add a global error handler middleware that catches and formats errors.',
+        autoFixable: true,
+      });
+    }
+    
+    return issues;
+  },
+  
+  // ─────────────────────────────────────────────────────────────────────────────
+  // SECURITY CHECKER
+  // ─────────────────────────────────────────────────────────────────────────────
+  async security(projectPath) {
+    const issues = [];
+    
+    // Check for .env.example
+    const hasEnvExample = await pathExists(path.join(projectPath, '.env.example')) ||
+                          await pathExists(path.join(projectPath, '.env.sample'));
+    if (!hasEnvExample) {
+      issues.push({
+        id: 'missing-env-example',
+        category: 'Security',
+        severity: 'medium',
+        title: 'Missing .env.example',
+        description: 'No .env.example file found. Team members won\'t know what env vars are needed.',
+        suggestion: 'Create .env.example with all required environment variables (without values).',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for .gitignore with .env
+    const gitignore = await readFileSafe(path.join(projectPath, '.gitignore'));
+    if (gitignore && !gitignore.includes('.env')) {
+      issues.push({
+        id: 'env-not-gitignored',
+        category: 'Security',
+        severity: 'critical',
+        title: '.env Not in .gitignore',
+        description: 'Environment files may be committed to git, exposing secrets.',
+        suggestion: 'Add .env* to .gitignore immediately.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for security headers
+    const packageJson = await readFileSafe(path.join(projectPath, 'package.json'));
+    const hasHelmet = packageJson && /helmet|next-secure-headers/i.test(packageJson);
+    if (!hasHelmet) {
+      issues.push({
+        id: 'missing-security-headers',
+        category: 'Security',
+        severity: 'high',
+        title: 'Missing Security Headers',
+        description: 'No security headers library found (helmet, etc.).',
+        suggestion: 'Add helmet or security headers middleware for CSP, HSTS, etc.',
+        autoFixable: false,
+      });
+    }
+    
+    // Check for CORS configuration
+    const hasCors = packageJson && /cors|@fastify\/cors/i.test(packageJson);
+    const nextConfig = await readFileSafe(path.join(projectPath, 'next.config.js')) ||
+                       await readFileSafe(path.join(projectPath, 'next.config.mjs'));
+    const hasNextCors = nextConfig && /headers|Access-Control/i.test(nextConfig);
+    
+    if (!hasCors && !hasNextCors) {
+      issues.push({
+        id: 'missing-cors',
+        category: 'Security',
+        severity: 'medium',
+        title: 'No CORS Configuration',
+        description: 'No CORS configuration found. May have issues with cross-origin requests.',
+        suggestion: 'Add CORS configuration to control which origins can access your API.',
+        autoFixable: false,
+      });
+    }
+    
+    return issues;
+  },
+  
+  // ─────────────────────────────────────────────────────────────────────────────
+  // PERFORMANCE CHECKER
+  // ─────────────────────────────────────────────────────────────────────────────
+  async performance(projectPath) {
+    const issues = [];
+    const packageJson = await readFileSafe(path.join(projectPath, 'package.json'));
+    
+    // Check for image optimization
+    const nextConfig = await readFileSafe(path.join(projectPath, 'next.config.js')) ||
+                       await readFileSafe(path.join(projectPath, 'next.config.mjs'));
+    const hasImageOptimization = (packageJson && /sharp|next\/image|@next\/image/i.test(packageJson)) ||
+                                  (nextConfig && /images:/i.test(nextConfig));
+    
+    if (!hasImageOptimization) {
+      issues.push({
+        id: 'missing-image-optimization',
+        category: 'Performance',
+        severity: 'medium',
+        title: 'Missing Image Optimization',
+        description: 'No image optimization setup found. Images may be served unoptimized.',
+        suggestion: 'Use Next.js Image component or sharp for image optimization.',
+        autoFixable: false,
+      });
+    }
+    
+    // Check for caching headers
+    const hasCaching = await findFile(projectPath, /cache|stale-while-revalidate/i);
+    if (!hasCaching) {
+      issues.push({
+        id: 'missing-caching',
+        category: 'Performance',
+        severity: 'medium',
+        title: 'No Caching Strategy',
+        description: 'No caching configuration found. API responses may not be cached.',
+        suggestion: 'Add Cache-Control headers or use SWR/React Query for client-side caching.',
+        autoFixable: false,
+      });
+    }
+    
+    // Check for bundle analyzer
+    const hasBundleAnalyzer = packageJson && /@next\/bundle-analyzer|webpack-bundle-analyzer/i.test(packageJson);
+    if (!hasBundleAnalyzer) {
+      issues.push({
+        id: 'missing-bundle-analyzer',
+        category: 'Performance',
+        severity: 'low',
+        title: 'No Bundle Analyzer',
+        description: 'No bundle analyzer installed. Can\'t visualize bundle size.',
+        suggestion: 'Add @next/bundle-analyzer to track and optimize bundle size.',
+        autoFixable: false,
+      });
+    }
+    
+    return issues;
+  },
+  
+  // ─────────────────────────────────────────────────────────────────────────────
+  // ACCESSIBILITY CHECKER
+  // ─────────────────────────────────────────────────────────────────────────────
+  async accessibility(projectPath) {
+    const issues = [];
+    const packageJson = await readFileSafe(path.join(projectPath, 'package.json'));
+    
+    // Check for accessibility testing
+    const hasA11yTesting = packageJson && /axe-core|@axe-core|jest-axe|cypress-axe|pa11y/i.test(packageJson);
+    if (!hasA11yTesting) {
+      issues.push({
+        id: 'missing-a11y-testing',
+        category: 'Accessibility',
+        severity: 'medium',
+        title: 'No Accessibility Testing',
+        description: 'No accessibility testing library found.',
+        suggestion: 'Add jest-axe, cypress-axe, or pa11y for automated a11y testing.',
+        autoFixable: false,
+      });
+    }
+    
+    // Check for skip link
+    const hasSkipLink = await findFile(projectPath, /skip-link|skiplink|SkipNav/i);
+    if (!hasSkipLink) {
+      issues.push({
+        id: 'missing-skip-link',
+        category: 'Accessibility',
+        severity: 'medium',
+        title: 'Missing Skip Link',
+        description: 'No skip-to-content link found. Keyboard users can\'t skip navigation.',
+        suggestion: 'Add a skip-to-main-content link at the top of your pages.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for focus-visible
+    const globalCss = await readFileSafe(path.join(projectPath, 'src', 'styles', 'globals.css')) ||
+                      await readFileSafe(path.join(projectPath, 'app', 'globals.css')) ||
+                      await readFileSafe(path.join(projectPath, 'styles', 'globals.css'));
+    
+    if (globalCss && /outline:\s*none|outline:\s*0/i.test(globalCss) && !/focus-visible/i.test(globalCss)) {
+      issues.push({
+        id: 'focus-removed',
+        category: 'Accessibility',
+        severity: 'high',
+        title: 'Focus Outline Removed',
+        description: 'Focus outlines are removed without alternative. Keyboard users can\'t see focus.',
+        suggestion: 'Use :focus-visible instead of removing outlines entirely.',
+        autoFixable: false,
+      });
+    }
+    
+    return issues;
+  },
+  
+  // ─────────────────────────────────────────────────────────────────────────────
+  // SEO CHECKER
+  // ─────────────────────────────────────────────────────────────────────────────
+  async seo(projectPath) {
+    const issues = [];
+    
+    // Check for robots.txt
+    const hasRobots = await pathExists(path.join(projectPath, 'public', 'robots.txt'));
+    if (!hasRobots) {
+      issues.push({
+        id: 'missing-robots',
+        category: 'SEO',
+        severity: 'medium',
+        title: 'Missing robots.txt',
+        description: 'No robots.txt file found. Search engines may not crawl correctly.',
+        suggestion: 'Add robots.txt to public folder to guide search engine crawlers.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for sitemap
+    const hasSitemap = await pathExists(path.join(projectPath, 'public', 'sitemap.xml')) ||
+                       await findFile(projectPath, /sitemap/i);
+    if (!hasSitemap) {
+      issues.push({
+        id: 'missing-sitemap',
+        category: 'SEO',
+        severity: 'medium',
+        title: 'Missing Sitemap',
+        description: 'No sitemap found. Search engines may miss some pages.',
+        suggestion: 'Generate sitemap.xml for better search engine indexing.',
+        autoFixable: false,
+      });
+    }
+    
+    // Check for meta description component or setup
+    const hasMetaTags = await findFile(projectPath, /MetaTags|Seo|Head|metadata/i);
+    if (!hasMetaTags) {
+      issues.push({
+        id: 'missing-meta-setup',
+        category: 'SEO',
+        severity: 'high',
+        title: 'Missing Meta Tag Setup',
+        description: 'No meta tag component found. Pages may lack proper SEO metadata.',
+        suggestion: 'Add a SEO/MetaTags component for consistent meta descriptions.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for Open Graph images
+    const hasOgImage = await pathExists(path.join(projectPath, 'public', 'og-image.png')) ||
+                       await pathExists(path.join(projectPath, 'public', 'og.png')) ||
+                       await findFile(path.join(projectPath, 'public'), /og[-_]?image/i);
+    if (!hasOgImage) {
+      issues.push({
+        id: 'missing-og-image',
+        category: 'SEO',
+        severity: 'low',
+        title: 'Missing Open Graph Image',
+        description: 'No OG image found. Social media shares will look plain.',
+        suggestion: 'Add og-image.png to public folder for social media previews.',
+        autoFixable: false,
+      });
+    }
+    
+    return issues;
+  },
+  
+  // ─────────────────────────────────────────────────────────────────────────────
+  // CONFIGURATION CHECKER
+  // ─────────────────────────────────────────────────────────────────────────────
+  async configuration(projectPath) {
+    const issues = [];
+    
+    // Check for TypeScript strict mode
+    const tsConfig = await readFileSafe(path.join(projectPath, 'tsconfig.json'));
+    if (tsConfig) {
+      const parsed = JSON.parse(tsConfig);
+      if (!parsed.compilerOptions?.strict) {
+        issues.push({
+          id: 'ts-not-strict',
+          category: 'Configuration',
+          severity: 'medium',
+          title: 'TypeScript Strict Mode Disabled',
+          description: 'TypeScript strict mode is not enabled. Type safety is reduced.',
+          suggestion: 'Enable "strict": true in tsconfig.json for better type safety.',
+          autoFixable: true,
+        });
+      }
+    }
+    
+    // Check for ESLint config
+    const hasEslint = await pathExists(path.join(projectPath, '.eslintrc.json')) ||
+                      await pathExists(path.join(projectPath, '.eslintrc.js')) ||
+                      await pathExists(path.join(projectPath, 'eslint.config.js'));
+    if (!hasEslint) {
+      issues.push({
+        id: 'missing-eslint',
+        category: 'Configuration',
+        severity: 'medium',
+        title: 'Missing ESLint Configuration',
+        description: 'No ESLint config found. Code quality may not be enforced.',
+        suggestion: 'Add ESLint configuration for code quality enforcement.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for Prettier
+    const hasPrettier = await pathExists(path.join(projectPath, '.prettierrc')) ||
+                        await pathExists(path.join(projectPath, '.prettierrc.json')) ||
+                        await pathExists(path.join(projectPath, 'prettier.config.js'));
+    if (!hasPrettier) {
+      issues.push({
+        id: 'missing-prettier',
+        category: 'Configuration',
+        severity: 'low',
+        title: 'Missing Prettier Configuration',
+        description: 'No Prettier config found. Code formatting may be inconsistent.',
+        suggestion: 'Add Prettier configuration for consistent code formatting.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for editor config
+    const hasEditorConfig = await pathExists(path.join(projectPath, '.editorconfig'));
+    if (!hasEditorConfig) {
+      issues.push({
+        id: 'missing-editorconfig',
+        category: 'Configuration',
+        severity: 'low',
+        title: 'Missing .editorconfig',
+        description: 'No .editorconfig found. Different editors may format differently.',
+        suggestion: 'Add .editorconfig for consistent editor settings across team.',
+        autoFixable: true,
+      });
+    }
+    
+    return issues;
+  },
+  
+  // ─────────────────────────────────────────────────────────────────────────────
+  // DOCUMENTATION CHECKER
+  // ─────────────────────────────────────────────────────────────────────────────
+  async documentation(projectPath) {
+    const issues = [];
+    
+    // Check for README
+    const hasReadme = await pathExists(path.join(projectPath, 'README.md'));
+    if (!hasReadme) {
+      issues.push({
+        id: 'missing-readme',
+        category: 'Documentation',
+        severity: 'high',
+        title: 'Missing README',
+        description: 'No README.md found. New developers won\'t know how to start.',
+        suggestion: 'Add README.md with project overview, setup, and usage instructions.',
+        autoFixable: true,
+      });
+    } else {
+      // Check README quality
+      const readme = await readFileSafe(path.join(projectPath, 'README.md'));
+      if (readme && readme.length < 500) {
+        issues.push({
+          id: 'insufficient-readme',
+          category: 'Documentation',
+          severity: 'medium',
+          title: 'Insufficient README',
+          description: 'README is very short. May be missing important sections.',
+          suggestion: 'Expand README with installation, usage, API docs, and contributing guide.',
+          autoFixable: false,
+        });
+      }
+    }
+    
+    // Check for CHANGELOG
+    const hasChangelog = await pathExists(path.join(projectPath, 'CHANGELOG.md'));
+    if (!hasChangelog) {
+      issues.push({
+        id: 'missing-changelog',
+        category: 'Documentation',
+        severity: 'low',
+        title: 'Missing CHANGELOG',
+        description: 'No CHANGELOG.md found. Version history is not documented.',
+        suggestion: 'Add CHANGELOG.md to track version history and changes.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for CONTRIBUTING guide
+    const hasContributing = await pathExists(path.join(projectPath, 'CONTRIBUTING.md'));
+    if (!hasContributing) {
+      issues.push({
+        id: 'missing-contributing',
+        category: 'Documentation',
+        severity: 'low',
+        title: 'Missing CONTRIBUTING Guide',
+        description: 'No CONTRIBUTING.md found. Contributors won\'t know the process.',
+        suggestion: 'Add CONTRIBUTING.md with contribution guidelines.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for LICENSE
+    const hasLicense = await pathExists(path.join(projectPath, 'LICENSE')) ||
+                       await pathExists(path.join(projectPath, 'LICENSE.md'));
+    if (!hasLicense) {
+      issues.push({
+        id: 'missing-license',
+        category: 'Documentation',
+        severity: 'medium',
+        title: 'Missing LICENSE',
+        description: 'No LICENSE file found. Legal usage of code is unclear.',
+        suggestion: 'Add a LICENSE file to clarify code usage rights.',
+        autoFixable: false,
+      });
+    }
+    
+    return issues;
+  },
+  
+  // ─────────────────────────────────────────────────────────────────────────────
+  // INFRASTRUCTURE CHECKER
+  // ─────────────────────────────────────────────────────────────────────────────
+  async infrastructure(projectPath) {
+    const issues = [];
+    
+    // Check for Dockerfile
+    const hasDocker = await pathExists(path.join(projectPath, 'Dockerfile')) ||
+                      await pathExists(path.join(projectPath, 'docker-compose.yml'));
+    if (!hasDocker) {
+      issues.push({
+        id: 'missing-docker',
+        category: 'Infrastructure',
+        severity: 'low',
+        title: 'Missing Docker Configuration',
+        description: 'No Docker setup found. Deployment may be inconsistent.',
+        suggestion: 'Add Dockerfile for consistent deployment environments.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for CI/CD
+    const hasGitHubActions = await pathExists(path.join(projectPath, '.github', 'workflows'));
+    const hasGitLab = await pathExists(path.join(projectPath, '.gitlab-ci.yml'));
+    const hasCircleCI = await pathExists(path.join(projectPath, '.circleci'));
+    
+    if (!hasGitHubActions && !hasGitLab && !hasCircleCI) {
+      issues.push({
+        id: 'missing-ci',
+        category: 'Infrastructure',
+        severity: 'high',
+        title: 'Missing CI/CD Configuration',
+        description: 'No CI/CD pipeline found. Code changes are not automatically tested.',
+        suggestion: 'Add GitHub Actions, GitLab CI, or CircleCI for automated testing.',
+        autoFixable: true,
+      });
+    }
+    
+    // Check for deployment config
+    const hasVercel = await pathExists(path.join(projectPath, 'vercel.json'));
+    const hasNetlify = await pathExists(path.join(projectPath, 'netlify.toml'));
+    const hasRailway = await pathExists(path.join(projectPath, 'railway.json'));
+    
+    if (!hasVercel && !hasNetlify && !hasRailway && !hasDocker) {
+      issues.push({
+        id: 'missing-deployment-config',
+        category: 'Infrastructure',
+        severity: 'medium',
+        title: 'No Deployment Configuration',
+        description: 'No deployment platform configuration found.',
+        suggestion: 'Add vercel.json, netlify.toml, or similar for deployment settings.',
+        autoFixable: false,
+      });
+    }
+    
+    // Check for environment validation
+    const packageJson = await readFileSafe(path.join(projectPath, 'package.json'));
+    const hasEnvValidation = packageJson && /@t3-oss\/env|envalid|dotenv-safe/i.test(packageJson);
+    if (!hasEnvValidation) {
+      issues.push({
+        id: 'missing-env-validation',
+        category: 'Infrastructure',
+        severity: 'medium',
+        title: 'No Environment Validation',
+        description: 'Environment variables are not validated at startup.',
+        suggestion: 'Add @t3-oss/env-nextjs or envalid to validate env vars at startup.',
+        autoFixable: false,
+      });
+    }
+    
+    return issues;
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// POLISH SERVICE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function analyzeProject(projectPath, options = {}) {
+  const allIssues = [];
+  const categories = Object.keys(checkers);
+  const selectedCategories = options.category 
+    ? [options.category.toLowerCase()] 
+    : categories;
+  
+  for (const category of selectedCategories) {
+    if (checkers[category]) {
+      try {
+        const issues = await checkers[category](projectPath);
+        allIssues.push(...issues);
+      } catch (error) {
+        console.error(`${c.red}Error in ${category} checker:${c.reset}`, error.message);
+      }
+    }
+  }
+  
+  // Calculate score
+  let score = 100;
+  for (const issue of allIssues) {
+    switch (issue.severity) {
+      case 'critical': score -= 10; break;
+      case 'high': score -= 5; break;
+      case 'medium': score -= 2; break;
+      case 'low': score -= 1; break;
+    }
+  }
+  score = Math.max(0, Math.min(100, score));
+  
+  // Generate recommendations
+  const recommendations = [];
+  const criticalCount = allIssues.filter(i => i.severity === 'critical').length;
+  const highCount = allIssues.filter(i => i.severity === 'high').length;
+  const autoFixable = allIssues.filter(i => i.autoFixable).length;
+  
+  if (criticalCount > 0) {
+    recommendations.push(`Fix ${criticalCount} critical issue(s) immediately - these affect security or functionality.`);
+  }
+  if (highCount > 0) {
+    recommendations.push(`Address ${highCount} high-priority issue(s) - these impact user experience or production readiness.`);
+  }
+  if (autoFixable > 0) {
+    recommendations.push(`${autoFixable} issue(s) can be auto-fixed. Run 'vibecheck polish --fix' to apply fixes.`);
+  }
+  if (recommendations.length === 0) {
+    recommendations.push('Your project looks polished! Great job! 🎉');
+  }
+  
+  return {
+    projectPath,
+    totalIssues: allIssues.length,
+    critical: criticalCount,
+    high: highCount,
+    medium: allIssues.filter(i => i.severity === 'medium').length,
+    low: allIssues.filter(i => i.severity === 'low').length,
+    issues: allIssues,
+    score,
+    recommendations,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CLI INTERFACE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function parseArgs(args) {
+  const opts = {
+    help: false,
+    fix: false,
+    json: false,
+    prompts: false,
+    verbose: false,
+    category: null,
+    path: process.cwd(),
+  };
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--fix' || arg === '-f') opts.fix = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--prompts' || arg === '--ai') opts.prompts = true;
+    else if (arg === '--verbose' || arg === '-v') opts.verbose = true;
+    else if (arg === '--category' || arg === '-c') opts.category = args[++i];
+    else if (arg === '--path' || arg === '-p') opts.path = args[++i];
+    else if (!arg.startsWith('-')) opts.path = arg;
+  }
+  
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+${c.bold}${icons.sparkle} vibecheck polish${c.reset} - Production Polish Analyzer
+
+${c.dim}Finds all the small detailed things you forgot - the polish that makes
+projects production-ready.${c.reset}
+
+${c.bold}USAGE${c.reset}
+  vibecheck polish [options] [path]
+
+${c.bold}OPTIONS${c.reset}
+  -h, --help              Show this help message
+  -f, --fix               Auto-fix issues where possible
+  --prompts, --ai         Show AI prompts for each issue (copy to AI assistant)
+  -v, --verbose           Show detailed output including AI prompts inline
+  -c, --category <name>   Check only specific category
+  -p, --path <path>       Project path (defaults to current directory)
+  --json                  Output as JSON (includes AI prompts)
+
+${c.bold}CATEGORIES${c.reset}
+  frontend       Error boundaries, skeletons, ARIA, haptics, animations, caching
+  backend        Health endpoints, validation, rate limiting, error handling
+  security       .env files, security headers, CORS, secrets management
+  performance    Image optimization, caching, bundle analysis
+  accessibility  A11y testing, skip links, focus management
+  seo            Meta tags, sitemap, robots.txt, Open Graph
+  configuration  TypeScript, ESLint, Prettier, EditorConfig
+  documentation  README, CHANGELOG, CONTRIBUTING, LICENSE
+  infrastructure Docker, CI/CD, deployment config, env validation
+
+${c.bold}EXAMPLES${c.reset}
+  vibecheck polish                     # Analyze current project
+  vibecheck polish --prompts           # Show AI prompts for all issues
+  vibecheck polish -c frontend --ai    # Frontend issues with AI prompts
+  vibecheck polish --fix               # Auto-fix issues
+  vibecheck polish --json              # Output JSON for CI
+
+${c.bold}AI PROMPTS${c.reset}
+  Each issue includes an AI-ready prompt you can copy to Cursor, Copilot, or Claude.
+  Use --prompts to see all prompts, or --json for machine-readable output.
+
+${c.bold}TIER${c.reset}
+  ${c.cyan}Free${c.reset} - Available on all tiers
+`);
+}
+
+function formatScore(score) {
+  if (score >= 90) return `${c.green}${c.bold}${score}/100${c.reset} ${c.green}(Excellent)${c.reset}`;
+  if (score >= 70) return `${c.yellow}${c.bold}${score}/100${c.reset} ${c.yellow}(Good)${c.reset}`;
+  if (score >= 50) return `${c.yellow}${c.bold}${score}/100${c.reset} ${c.yellow}(Needs Work)${c.reset}`;
+  return `${c.red}${c.bold}${score}/100${c.reset} ${c.red}(Critical Issues)${c.reset}`;
+}
+
+function formatSeverity(severity) {
+  const styles = {
+    critical: `${icons.critical} ${c.red}${c.bold}CRITICAL${c.reset}`,
+    high: `${icons.high} ${c.yellow}${c.bold}HIGH${c.reset}`,
+    medium: `${icons.medium} ${c.yellow}MEDIUM${c.reset}`,
+    low: `${icons.low} ${c.blue}LOW${c.reset}`,
+  };
+  return styles[severity] || severity;
+}
+
+function getCategoryIcon(category) {
+  const categoryIcons = {
+    Frontend: icons.sparkle,
+    Backend: icons.server,
+    Security: icons.lock,
+    Performance: icons.lightning,
+    Accessibility: icons.eye,
+    SEO: icons.search,
+    Configuration: icons.gear,
+    Documentation: icons.book,
+    Infrastructure: icons.rocket,
+  };
+  return categoryIcons[category] || icons.star;
+}
+
+async function runPolish(args) {
+  const opts = parseArgs(args);
+  
+  if (opts.help) {
+    printHelp();
+    return 0;
+  }
+  
+  const projectPath = path.resolve(opts.path);
+  
+  // Verify project exists
+  if (!await pathExists(projectPath)) {
+    console.error(`${c.red}${icons.cross} Project path does not exist: ${projectPath}${c.reset}`);
+    return 1;
+  }
+  
+  // JSON mode
+  if (opts.json) {
+    const report = await analyzeProject(projectPath, opts);
+    console.log(JSON.stringify(report, null, 2));
+    return report.critical > 0 ? 1 : 0;
+  }
+  
+  // Interactive mode
+  console.log(`
+${c.bold}╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║  ${icons.sparkle} ${c.cyan}VIBECHECK POLISH${c.reset}${c.bold} - Production Readiness Analyzer                        ║
+║                                                                              ║
+║  ${c.dim}Finds all the small detailed things you forgot - the polish that${c.reset}${c.bold}           ║
+║  ${c.dim}makes projects production-ready.${c.reset}${c.bold}                                            ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝${c.reset}
+`);
+  
+  console.log(`${c.dim}Project:${c.reset} ${projectPath}\n`);
+  
+  // Show spinner
+  const isTTY = process.stdout.isTTY;
+  if (isTTY) {
+    process.stdout.write(`${icons.search} Scanning project for polish issues...`);
+  } else {
+    console.log(`${icons.search} Scanning project for polish issues...`);
+  }
+  
+  const report = await analyzeProject(projectPath, opts);
+  
+  // Clear spinner line
+  if (isTTY && process.stdout.clearLine) {
+    process.stdout.clearLine(0);
+    process.stdout.cursorTo(0);
+  }
+  
+  // Summary
+  console.log(`${c.bold}${icons.star} POLISH REPORT SUMMARY${c.reset}\n`);
+  console.log(`   ${c.bold}Score:${c.reset}    ${formatScore(report.score)}`);
+  console.log(`   ${c.bold}Issues:${c.reset}   ${report.totalIssues} total`);
+  console.log(`            ${icons.critical} ${report.critical} critical  ${icons.high} ${report.high} high  ${icons.medium} ${report.medium} medium  ${icons.low} ${report.low} low\n`);
+  
+  if (report.issues.length === 0) {
+    console.log(`\n${c.green}${c.bold}${icons.check} Perfect!${c.reset} No polish issues found. Your project is production-ready! ${icons.rocket}\n`);
+    return 0;
+  }
+  
+  // Group by category
+  const byCategory = {};
+  for (const issue of report.issues) {
+    if (!byCategory[issue.category]) {
+      byCategory[issue.category] = [];
+    }
+    byCategory[issue.category].push(issue);
+  }
+  
+  // Show issues by category
+  console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}`);
+  console.log(`${c.bold}${icons.wrench} ISSUES BY CATEGORY${c.reset}`);
+  console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}\n`);
+  
+  const issuesWithPrompts = [];
+  
+  for (const [category, issues] of Object.entries(byCategory)) {
+    console.log(`${c.bold}${getCategoryIcon(category)} ${category}${c.reset} ${c.dim}(${issues.length} issues)${c.reset}`);
+    console.log(`${'─'.repeat(60)}`);
+    
+    for (const issue of issues) {
+      console.log(`\n   ${formatSeverity(issue.severity)}`);
+      console.log(`   ${c.bold}${issue.title}${c.reset}`);
+      console.log(`   ${c.dim}${issue.description}${c.reset}`);
+      if (issue.file) {
+        console.log(`   ${c.dim}File: ${path.relative(projectPath, issue.file)}${c.reset}`);
+      }
+      console.log(`   ${c.cyan}${icons.arrow} ${issue.suggestion}${c.reset}`);
+      if (issue.autoFixable) {
+        console.log(`   ${c.green}${icons.check} Auto-fixable${c.reset}`);
+      }
+      if (issue.aiPrompt) {
+        issuesWithPrompts.push(issue);
+        if (opts.verbose) {
+          console.log(`\n   ${c.magenta}${c.bold}🤖 AI PROMPT:${c.reset}`);
+          console.log(`   ${c.dim}${'─'.repeat(50)}${c.reset}`);
+          const promptLines = issue.aiPrompt.split('\n');
+          for (const line of promptLines) {
+            console.log(`   ${c.dim}${line}${c.reset}`);
+          }
+          console.log(`   ${c.dim}${'─'.repeat(50)}${c.reset}`);
+        } else {
+          console.log(`   ${c.magenta}🤖 Has AI prompt${c.reset} ${c.dim}(use --prompts to see)${c.reset}`);
+        }
+      }
+    }
+    console.log();
+  }
+  
+  // Recommendations
+  if (report.recommendations.length > 0) {
+    console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}`);
+    console.log(`${c.bold}💡 RECOMMENDATIONS${c.reset}`);
+    console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}\n`);
+    report.recommendations.forEach((rec, i) => {
+      console.log(`   ${i + 1}. ${rec}`);
+    });
+    console.log();
+  }
+  
+  // Auto-fix prompt
+  const autoFixable = report.issues.filter(i => i.autoFixable);
+  if (autoFixable.length > 0 && opts.fix) {
+    console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}`);
+    console.log(`${c.bold}${icons.wrench} AUTO-FIX${c.reset}`);
+    console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}\n`);
+    console.log(`   ${c.yellow}Auto-fix for ${autoFixable.length} issue(s) is coming soon!${c.reset}`);
+    console.log(`   ${c.dim}For now, please follow the suggestions above to fix issues manually.${c.reset}\n`);
+  } else if (autoFixable.length > 0) {
+    console.log(`${c.dim}Tip: Run 'vibecheck polish --fix' to auto-fix ${autoFixable.length} issue(s)${c.reset}\n`);
+  }
+  
+  // AI Prompts section (when --prompts flag is used)
+  if (opts.prompts && issuesWithPrompts.length > 0) {
+    console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}`);
+    console.log(`${c.bold}🤖 AI PROMPTS - Copy to your AI assistant${c.reset}`);
+    console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}\n`);
+    console.log(`${c.dim}Copy these prompts to Cursor, Copilot, Claude, or your preferred AI assistant.${c.reset}\n`);
+    
+    for (let i = 0; i < issuesWithPrompts.length; i++) {
+      const issue = issuesWithPrompts[i];
+      console.log(`${c.bold}╭───────────────────────────────────────────────────────────────────────────────╮${c.reset}`);
+      console.log(`${c.bold}│${c.reset} ${c.cyan}[${i + 1}/${issuesWithPrompts.length}]${c.reset} ${c.bold}${issue.title}${c.reset}`);
+      console.log(`${c.bold}│${c.reset} ${c.dim}Severity: ${issue.severity} | Category: ${issue.category}${c.reset}`);
+      console.log(`${c.bold}╰───────────────────────────────────────────────────────────────────────────────╯${c.reset}`);
+      console.log();
+      console.log(`${c.magenta}${issue.aiPrompt}${c.reset}`);
+      console.log();
+      console.log(`${c.dim}${'─'.repeat(79)}${c.reset}\n`);
+    }
+    
+    console.log(`${c.green}${c.bold}💡 Tip:${c.reset} Copy one prompt at a time and paste into your AI coding assistant.`);
+    console.log(`${c.dim}The prompts are designed to give AI complete context to generate the right code.${c.reset}\n`);
+  } else if (issuesWithPrompts.length > 0 && !opts.verbose) {
+    console.log(`${c.dim}${icons.star} ${issuesWithPrompts.length} issue(s) have AI prompts. Run with ${c.cyan}--prompts${c.reset}${c.dim} to see them.${c.reset}\n`);
+  }
+  
+  // Next steps
+  console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}`);
+  console.log(`${c.bold}${icons.rocket} NEXT STEPS${c.reset}`);
+  console.log(`${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}\n`);
+  console.log(`   1. Fix ${c.red}critical${c.reset} and ${c.yellow}high${c.reset} severity issues first`);
+  console.log(`   2. Use ${c.cyan}vibecheck polish --prompts${c.reset} to get AI-ready fixes`);
+  console.log(`   3. Copy prompts to your AI assistant (Cursor, Copilot, Claude)`);
+  console.log(`   4. Re-run ${c.cyan}vibecheck polish${c.reset} to verify fixes`);
+  console.log(`   5. Run ${c.cyan}vibecheck ship${c.reset} when score is 80+\n`);
+  
+  return report.critical > 0 ? 1 : 0;
+}
+
+module.exports = { runPolish };