feat: Implement user tier-based feature gating system (refs #8)

Add subscription tier system to gate features behind Free/Pro/Enterprise tiers.

Backend:
- Create feature-tiers.ts with FEATURE_TIERS config and utilities
- Add /api/config/feature-tiers endpoint for frontend config fetch
- Create requireTier middleware for route-level tier enforcement
- Add subscriptionTier to request.userContext in auth plugin
- Gate scanForMaintenance in documents controller (Pro+ required)
- Add migration to reset scanForMaintenance for free users

Frontend:
- Create useTierAccess hook for tier checking
- Create UpgradeRequiredDialog component (responsive)
- Gate DocumentForm checkbox with lock icon for free users
- Add SubscriptionTier type to profile.types.ts

Documentation:
- Add TIER-GATING.md with usage guide

Tests: 30 passing (feature-tiers, tier-guard, controller)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

frontend/src/shared-minimal/components/UpgradeRequiredDialog.tsx

@@ -0,0 +1,178 @@
+/**
+ * @ai-summary Dialog prompting users to upgrade their subscription tier
+ * @ai-context Shown when users attempt to use a tier-gated feature
+ */
+
+import React from 'react';
+import {
+  Dialog,
+  DialogTitle,
+  DialogContent,
+  DialogActions,
+  Button,
+  Typography,
+  Box,
+  Chip,
+  useMediaQuery,
+  useTheme,
+  IconButton,
+} from '@mui/material';
+import LockOutlinedIcon from '@mui/icons-material/LockOutlined';
+import CloseIcon from '@mui/icons-material/Close';
+import { useTierAccess } from '../../core/hooks/useTierAccess';
+import type { SubscriptionTier } from '../../features/settings/types/profile.types';
+
+interface UpgradeRequiredDialogProps {
+  featureKey: string;
+  open: boolean;
+  onClose: () => void;
+}
+
+const tierDisplayNames: Record<SubscriptionTier, string> = {
+  free: 'Free',
+  pro: 'Pro',
+  enterprise: 'Enterprise',
+};
+
+const tierColors: Record<SubscriptionTier, 'default' | 'primary' | 'secondary'> = {
+  free: 'default',
+  pro: 'primary',
+  enterprise: 'secondary',
+};
+
+export const UpgradeRequiredDialog: React.FC<UpgradeRequiredDialogProps> = ({
+  featureKey,
+  open,
+  onClose,
+}) => {
+  const theme = useTheme();
+  const isSmall = useMediaQuery(theme.breakpoints.down('sm'));
+  const { tier, checkAccess } = useTierAccess();
+
+  const { config, requiredTier } = checkAccess(featureKey);
+
+  const handleUpgradeClick = () => {
+    // TODO: Navigate to upgrade page when Stripe integration is added
+    // For now, just close the dialog
+    onClose();
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onClose={onClose}
+      fullScreen={isSmall}
+      maxWidth="sm"
+      fullWidth
+      PaperProps={{
+        sx: {
+          maxHeight: isSmall ? '100%' : '90vh',
+          m: isSmall ? 0 : 2,
+        },
+      }}
+    >
+      {isSmall && (
+        <IconButton
+          aria-label="close"
+          onClick={onClose}
+          sx={{
+            position: 'absolute',
+            right: 8,
+            top: 8,
+            color: (theme) => theme.palette.grey[500],
+          }}
+        >
+          <CloseIcon />
+        </IconButton>
+      )}
+
+      <DialogTitle sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+        <LockOutlinedIcon color="action" />
+        Upgrade Required
+      </DialogTitle>
+
+      <DialogContent>
+        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 3 }}>
+          {/* Feature name */}
+          <Box>
+            <Typography variant="h6" gutterBottom>
+              {config?.name || 'Premium Feature'}
+            </Typography>
+            <Typography variant="body2" color="text.secondary">
+              {config?.upgradePrompt || 'This feature requires a higher subscription tier.'}
+            </Typography>
+          </Box>
+
+          {/* Tier comparison */}
+          <Box
+            sx={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              gap: 2,
+              py: 2,
+              px: 3,
+              bgcolor: 'action.hover',
+              borderRadius: 1,
+            }}
+          >
+            <Box sx={{ textAlign: 'center' }}>
+              <Typography variant="caption" color="text.secondary" display="block">
+                Your Plan
+              </Typography>
+              <Chip
+                label={tierDisplayNames[tier]}
+                color={tierColors[tier]}
+                size="small"
+                sx={{ mt: 0.5 }}
+              />
+            </Box>
+
+            <Typography variant="h5" color="text.secondary">
+              →
+            </Typography>
+
+            <Box sx={{ textAlign: 'center' }}>
+              <Typography variant="caption" color="text.secondary" display="block">
+                Required
+              </Typography>
+              <Chip
+                label={requiredTier ? tierDisplayNames[requiredTier] : 'Pro'}
+                color={requiredTier ? tierColors[requiredTier] : 'primary'}
+                size="small"
+                sx={{ mt: 0.5 }}
+              />
+            </Box>
+          </Box>
+
+          {/* Benefits preview */}
+          <Typography variant="body2" color="text.secondary">
+            Upgrade to unlock this feature and more premium capabilities.
+          </Typography>
+        </Box>
+      </DialogContent>
+
+      <DialogActions sx={{ px: 3, pb: 3, pt: 1, flexDirection: isSmall ? 'column' : 'row', gap: 1 }}>
+        <Button
+          onClick={onClose}
+          variant="outlined"
+          fullWidth={isSmall}
+          sx={{ order: isSmall ? 2 : 1 }}
+        >
+          Maybe Later
+        </Button>
+        <Button
+          onClick={handleUpgradeClick}
+          variant="contained"
+          color="primary"
+          fullWidth={isSmall}
+          sx={{ order: isSmall ? 1 : 2 }}
+        >
+          Upgrade (Coming Soon)
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+};
+
+export default UpgradeRequiredDialog;

frontend/src/shared-minimal/components/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @ai-summary Shared minimal components barrel export
+ */
+
+export { Button } from './Button';
+export { Card } from './Card';
+export { UpgradeRequiredDialog } from './UpgradeRequiredDialog';