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/features/documents/components/DocumentForm.tsx

@@ -1,14 +1,17 @@
 import React from 'react';
 import { Button } from '../../../shared-minimal/components/Button';
+import { UpgradeRequiredDialog } from '../../../shared-minimal/components/UpgradeRequiredDialog';
 import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
 import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
 import { DatePicker } from '@mui/x-date-pickers/DatePicker';
+import LockOutlinedIcon from '@mui/icons-material/LockOutlined';
 import dayjs from 'dayjs';
 import { useCreateDocument } from '../hooks/useDocuments';
 import { documentsApi } from '../api/documents.api';
 import type { DocumentType } from '../types/documents.types';
 import { useVehicles } from '../../vehicles/hooks/useVehicles';
 import type { Vehicle } from '../../vehicles/types/vehicles.types';
+import { useTierAccess } from '../../../core/hooks/useTierAccess';
 
 interface DocumentFormProps {
   onSuccess?: () => void;
@@ -42,9 +45,12 @@ export const DocumentForm: React.FC<DocumentFormProps> = ({ onSuccess, onCancel
   const [file, setFile] = React.useState<File | null>(null);
   const [uploadProgress, setUploadProgress] = React.useState<number>(0);
   const [error, setError] = React.useState<string | null>(null);
+  const [upgradeDialogOpen, setUpgradeDialogOpen] = React.useState<boolean>(false);
 
   const { data: vehicles } = useVehicles();
   const create = useCreateDocument();
+  const { hasAccess } = useTierAccess();
+  const canScanMaintenance = hasAccess('document.scanMaintenanceSchedule');
 
   const resetForm = () => {
     setTitle('');
@@ -349,18 +355,31 @@ export const DocumentForm: React.FC<DocumentFormProps> = ({ onSuccess, onCancel
 
         {documentType === 'manual' && (
           <div className="flex items-center md:col-span-2">
-            <label className="flex items-center cursor-pointer">
+            <label className={`flex items-center ${canScanMaintenance ? 'cursor-pointer' : 'cursor-not-allowed opacity-60'}`}>
               <input
                 type="checkbox"
-                checked={scanForMaintenance}
-                onChange={(e) => setScanForMaintenance(e.target.checked)}
-                className="w-5 h-5 rounded border-slate-300 text-primary-600 focus:ring-primary-500 dark:border-silverstone dark:focus:ring-abudhabi"
+                checked={canScanMaintenance ? scanForMaintenance : false}
+                onChange={(e) => canScanMaintenance && setScanForMaintenance(e.target.checked)}
+                disabled={!canScanMaintenance}
+                className="w-5 h-5 rounded border-slate-300 text-primary-600 focus:ring-primary-500 dark:border-silverstone dark:focus:ring-abudhabi disabled:opacity-50"
               />
               <span className="ml-2 text-sm font-medium text-slate-700 dark:text-avus">
                 Scan for Maintenance Schedule
               </span>
             </label>
-            <span className="ml-2 text-xs text-slate-500 dark:text-titanio">(Coming soon)</span>
+            {!canScanMaintenance && (
+              <button
+                type="button"
+                onClick={() => setUpgradeDialogOpen(true)}
+                className="ml-2 p-1 text-slate-500 hover:text-primary-600 dark:text-titanio dark:hover:text-abudhabi transition-colors"
+                title="Upgrade to Pro to unlock this feature"
+              >
+                <LockOutlinedIcon fontSize="small" />
+              </button>
+            )}
+            {canScanMaintenance && (
+              <span className="ml-2 text-xs text-slate-500 dark:text-titanio">(Coming soon)</span>
+            )}
           </div>
         )}
 
@@ -395,6 +414,12 @@ export const DocumentForm: React.FC<DocumentFormProps> = ({ onSuccess, onCancel
         <Button type="submit" className="min-h-[44px]">Create Document</Button>
         <Button type="button" variant="secondary" onClick={onCancel} className="min-h-[44px]">Cancel</Button>
       </div>
+
+      <UpgradeRequiredDialog
+        featureKey="document.scanMaintenanceSchedule"
+        open={upgradeDialogOpen}
+        onClose={() => setUpgradeDialogOpen(false)}
+      />
     </form>
     </LocalizationProvider>
   );

frontend/src/features/settings/types/profile.types.ts

@@ -2,12 +2,15 @@
  * @ai-summary User profile types for settings feature
  */
 
+export type SubscriptionTier = 'free' | 'pro' | 'enterprise';
+
 export interface UserProfile {
   id: string;
   auth0Sub: string;
   email: string;
   displayName?: string;
   notificationEmail?: string;
+  subscriptionTier: SubscriptionTier;
   createdAt: string;
   updatedAt: string;
 }