@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/migration/MIGRATION_GUIDE.md

@@ -1,12 +1,25 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # PACE Core Migration Guide
 
-> **🔄 Complete Migration Reference** | [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
+> **🔄 Complete Migration Reference** | [← Back to Documentation](../README.md) | [Installation Guide](../getting-started/installation-guide.md)
 
-Comprehensive migration guide for upgrading PACE Core across all versions with detailed instructions, breaking changes, and troubleshooting.
+Comprehensive migration guide for upgrading PACE Core across all versions with detailed instructions, breaking changes, troubleshooting, and best practices.
 
 ## Overview
 
-This guide covers all PACE Core migrations from version 0.1.0 to the latest version. Use the version-specific sections to find the exact migration steps for your upgrade path.
+This guide covers all PACE Core migrations from version 0.1.0 to the latest version. It includes:
+
+- **Version Upgrades**: Upgrading between major/minor versions
+- **Breaking Changes**: Handling API changes and deprecations
+- **Database Migrations**: Schema updates and data transformations
+- **Configuration Updates**: Environment and build configuration changes
+- **Dependency Updates**: Third-party library compatibility
+- **Troubleshooting**: Common issues and solutions
 
 ## Quick Reference
 
@@ -19,6 +32,24 @@ This guide covers all PACE Core migrations from version 0.1.0 to the latest vers
 | v0.3.x | v0.5.x | ⚠️ Major | 30-45 min | RBAC system, providers |
 | v0.2.x | v0.5.x | ⚠️ Major | 45-60 min | Complete restructure |
 
+## Quick Migration Checklist
+
+### Before You Start
+- [ ] **Backup your project** - Always backup before major updates
+- [ ] **Check current version** - `npm list @jmruthers/pace-core`
+- [ ] **Review changelog** - Check for breaking changes
+- [ ] **Test in development** - Never migrate directly in production
+
+### Essential Tests
+- [ ] **Build succeeds** - `npm run build`
+- [ ] **App starts** - `npm run dev`
+- [ ] **Authentication works** - Login/logout
+- [ ] **Components render** - All UI components display
+- [ ] **Permissions work** - RBAC functions correctly
+- [ ] **Forms work** - Form validation and submission
+- [ ] **Data tables work** - CRUD operations
+- [ ] **Styling correct** - No visual regressions
+
 ## Current Version Migration (v0.5.x)
 
 ### Latest Changes in v0.5.x
@@ -70,26 +101,92 @@ function MyApp() {
 }
 ```
 
-## Version History
+## Breaking Changes
 
-### v0.5.54 (Latest)
+### v0.5.65+ - Mandatory Inactivity Timeouts
 
-**Changes:**
-- File reference system improvements
-- Enhanced error handling
-- Performance optimizations
+**Status**: ⚠️ **BREAKING CHANGE**  
+**Date**: January 2025  
+**Impact**: High - Affects all apps using `UnifiedAuthProvider`
 
-**Migration:** No action required - fully backward compatible.
+#### What Changed
 
-### v0.5.0 - v0.5.53
+The `UnifiedAuthProvider` now requires mandatory inactivity timeout configuration. These props were previously optional but are now required for security and TypeScript compliance.
 
-**New Features:**
-- File Upload & Storage System
-- Inactivity Tracking
-- Public Pages System
-- Organisation Security
+#### Before (Old Code)
 
-**Migration:** No breaking changes - all features are additive.
+```tsx
+// ❌ This will now cause TypeScript errors
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <App />
+</UnifiedAuthProvider>
+```
+
+#### After (New Code)
+
+```tsx
+// ✅ Required configuration
+<UnifiedAuthProvider 
+  supabaseClient={supabase} 
+  appName="my-app"
+  idleTimeoutMs={30 * 60 * 1000}  // Required: 30 minutes
+  warnBeforeMs={5 * 60 * 1000}    // Required: 5 minutes warning
+  onIdleLogout={() => window.location.href = '/login'}  // Required
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+#### Required Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `idleTimeoutMs` | `number` | ✅ Yes | Idle timeout in milliseconds |
+| `warnBeforeMs` | `number` | ✅ Yes | Warning before logout in milliseconds |
+| `onIdleLogout` | `() => void` | ✅ Yes | Callback when user is logged out |
+
+#### Migration Steps
+
+1. **Identify all UnifiedAuthProvider instances** in your codebase
+2. **Add the three required props** to each instance
+3. **Choose appropriate timeout values** for your application
+4. **Test the inactivity warning and logout flow**
+
+#### Why This Change
+
+This breaking change was made for security reasons:
+- Ensures all apps have automatic logout functionality
+- Prevents security vulnerabilities from idle sessions
+- Provides consistent user experience across all apps
+- Improves overall security posture
+
+### v2.0.0 - Service Architecture Changes
+
+**Status**: ⚠️ **BREAKING CHANGE**  
+**Date**: December 2024  
+**Impact**: Medium - Affects apps using service architecture
+
+#### What Changed
+
+The library now uses a service-based architecture with pure TypeScript service classes and React integration through providers and hooks.
+
+#### Key Changes
+
+- ✅ **New Service Layer**: Pure TypeScript classes for business logic
+- ✅ **Provider Layer**: React context integration for services
+- ✅ **Hook Layer**: Reactive hooks for component integration
+- ✅ **Backward Compatible**: `UnifiedAuthProvider` maintained for compatibility
+
+#### Migration
+
+The service architecture is now the default. Existing code continues to work without changes:
+
+```tsx
+// Works out of the box - uses service architecture internally
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+```
+
+## Version-Specific Migrations
 
 ### v0.4.17 - Source Path Fix
 
@@ -200,36 +297,38 @@ export default defineConfig({
 })
 ```
 
-3. **Test the configuration:**
+3. **Remove old Tailwind dependencies:**
+```bash
+npm uninstall tailwindcss postcss autoprefixer
+npm install @tailwindcss/vite tailwindcss@^4.0.0
+```
+
+4. **Test styling:**
 ```tsx
-// Test component
 import { Button } from '@jmruthers/pace-core';
 
 function TestComponent() {
   return (
-    <Button className="bg-main-600 text-main-50">
+    <Button variant="primary" className="bg-main-600 text-main-50">
       Test Button
     </Button>
   );
 }
 ```
 
-### v0.4.15 - Tailwind Scanning Fix
-
-**Issue Fixed:** Components appeared unstyled due to missing Tailwind class scanning.
+### v0.4.15 - Tailwind Content Scanning
 
-**Root Cause:** Tailwind v4 needs to scan source files, not compiled JavaScript.
+**Change:** Required explicit content scanning for pace-core components.
 
 **Migration Steps:**
 
-1. **Update pace-core:**
-```bash
-npm install @jmruthers/pace-core@^0.4.15
-```
-
-2. **Update Vite configuration:**
+1. **Update Vite configuration:**
 ```typescript
 // vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
 export default defineConfig({
   plugins: [
     react(),
@@ -243,442 +342,819 @@ export default defineConfig({
 })
 ```
 
-3. **Clear build cache:**
-```bash
-rm -rf dist .vite node_modules
-npm install
-```
-
-4. **Verify CSS generation:**
-```bash
-# Should generate 800+ CSS rules (not 292)
-npm run build
-```
-
-### v0.4.14 and Earlier
-
-**Legacy Configuration:**
-```typescript
-// Old configuration (v0.4.14 and below)
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
+2. **Verify CSS import:**
+```tsx
+// Ensure this import is first
+import '@jmruthers/pace-core/src/styles/core.css';
 ```
 
-## Major Version Migrations
-
-### v0.3.x to v0.5.x
+## API Changes Migration
 
-**Breaking Changes:**
-- Provider hierarchy changes
-- RBAC system updates
-- New authentication patterns
+### Component Props Migration
 
-**Migration Steps:**
+**Common prop changes:**
 
-1. **Update dependencies:**
-```bash
-npm install @jmruthers/pace-core@^0.5.0
+```tsx
+// Before (v0.x)
+<DataTable
+  data={data}
+  columns={columns}
+  enableSearch={true}
+  enablePagination={true}
+/>
+
+// After (v1.x)
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    search: true,
+    pagination: true,
+    sorting: true,
+    filtering: true
+  }}
+/>
 ```
 
-2. **Update provider hierarchy:**
-```tsx
-// Before (v0.3.x)
-<AuthProvider>
-  <OrganisationProvider>
-    <EventProvider>
-      <App />
-    </EventProvider>
-  </OrganisationProvider>
-</AuthProvider>
+### Hook Changes
 
-// After (v0.5.x)
-<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-  <OrganisationProvider>
-    <EventProvider>
-      <App />
-    </EventProvider>
-  </OrganisationProvider>
-</UnifiedAuthProvider>
-```
+**RBAC hooks moved to separate module:**
 
-3. **Update authentication hooks:**
 ```tsx
 // Before
-import { useAuth } from '@jmruthers/pace-core';
+import { useCan, usePermissions } from '@jmruthers/pace-core';
 
 // After
-import { useUnifiedAuth } from '@jmruthers/pace-core';
+import { useCan, usePermissions } from '@jmruthers/pace-core/rbac';
 ```
 
-4. **Update RBAC usage:**
+### Import Changes
+
+**Consolidated imports:**
+
 ```tsx
 // Before
-import { useRBAC } from '@jmruthers/pace-core';
+import { Button } from '@jmruthers/pace-core/components';
+import { useUnifiedAuth } from '@jmruthers/pace-core/hooks';
 
 // After
-import { useCan } from '@jmruthers/pace-core/rbac';
+import { Button, useUnifiedAuth } from '@jmruthers/pace-core';
 ```
 
-### v0.2.x to v0.5.x
+## Database Migration
 
-**Breaking Changes:**
-- Complete component restructure
-- New import paths
-- Updated prop interfaces
+### Schema Migration
 
-**Migration Steps:**
+```sql
+-- Migration script for database schema changes
+-- 001_migrate_users_table.sql
+
+-- Add new columns to users table
+ALTER TABLE users 
+ADD COLUMN IF NOT EXISTS organisation_id UUID REFERENCES organisations(id),
+ADD COLUMN IF NOT EXISTS role VARCHAR(50) DEFAULT 'user',
+ADD COLUMN IF NOT EXISTS permissions JSONB DEFAULT '[]';
+
+-- Create index for performance
+CREATE INDEX IF NOT EXISTS idx_users_organisation_id ON users(organisation_id);
+CREATE INDEX IF NOT EXISTS idx_users_role ON users(role);
+
+-- Update existing users with default values
+UPDATE users 
+SET 
+  organisation_id = (SELECT id FROM organisations LIMIT 1),
+  role = 'user',
+  permissions = '[]'
+WHERE organisation_id IS NULL;
+
+-- Add constraints
+ALTER TABLE users 
+ALTER COLUMN organisation_id SET NOT NULL,
+ALTER COLUMN role SET NOT NULL;
+```
 
-1. **Update all imports:**
-```tsx
-// Before (v0.2.x)
-import { Button, Card, useAuth } from '@jmruthers/pace-core/components';
+### Data Migration
 
-// After (v0.5.x)
-import { Button, Card, useUnifiedAuth } from '@jmruthers/pace-core';
+```typescript
+// Migration script for data transformation
+async function migrateUserData() {
+  const { supabase } = useSupabase();
+  
+  // Get all users
+  const { data: users, error } = await supabase
+    .from('users')
+    .select('*');
+  
+  if (error) {
+    console.error('Failed to fetch users:', error);
+    return;
+  }
+  
+  // Transform user data
+  const migratedUsers = users.map(user => ({
+    ...user,
+    // Convert old permission format to new format
+    permissions: user.permissions?.map((permission: string) => 
+      permission.replace('_', ':')
+    ) || [],
+    // Add default role if missing
+    role: user.role || 'user',
+    // Add organisation if missing
+    organisation_id: user.organisation_id || 'default-org-id',
+  }));
+  
+  // Update users in batches
+  const batchSize = 100;
+  for (let i = 0; i < migratedUsers.length; i += batchSize) {
+    const batch = migratedUsers.slice(i, i + batchSize);
+    
+    const { error: updateError } = await supabase
+      .from('users')
+      .upsert(batch);
+    
+    if (updateError) {
+      console.error(`Failed to update batch ${i / batchSize + 1}:`, updateError);
+    }
+  }
+  
+  console.log('User data migration completed');
+}
 ```
 
-2. **Update component props:**
-```tsx
-// Check component documentation for prop changes
-// Most components maintain backward compatibility
-```
+### RLS Policy Migration
 
-3. **Update authentication:**
-```tsx
-// Follow v0.3.x to v0.5.x migration steps
-```
+```sql
+-- Migration script for RLS policies
+-- 002_migrate_rls_policies.sql
+
+-- Drop old policies
+DROP POLICY IF EXISTS "Users can view their own data" ON users;
+DROP POLICY IF EXISTS "Users can update their own data" ON users;
+
+-- Create new policies with organisation isolation
+CREATE POLICY "Users can view their own organisation's data" ON users
+  FOR SELECT USING (
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
 
-## Breaking Changes Reference
+CREATE POLICY "Users can update their own data" ON users
+  FOR UPDATE USING (
+    id = auth.uid() AND
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
 
-### Authentication Changes
+CREATE POLICY "Users can insert their own data" ON users
+  FOR INSERT WITH CHECK (
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
 
-| Version | Change | Before | After |
-|---------|--------|--------|-------|
-| v0.4.0 | Provider consolidation | `AuthProvider` | `UnifiedAuthProvider` |
-| v0.4.0 | Hook consolidation | `useAuth` | `useUnifiedAuth` |
-| v0.3.0 | Provider hierarchy | Individual providers | Nested providers |
+-- Apply similar policies to other tables
+-- events table
+CREATE POLICY "Users can view their organisation's events" ON events
+  FOR SELECT USING (
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
 
-### RBAC Changes
+CREATE POLICY "Users can manage their organisation's events" ON events
+  FOR ALL USING (
+    organisation_id = auth.jwt() ->> 'organisation_id'
+  );
+```
 
-| Version | Change | Before | After |
-|---------|--------|--------|-------|
-| v0.5.0 | Hook location | `useRBAC` | `useCan` from `/rbac` |
-| v0.4.0 | Permission format | `"read users"` | `"read:users"` |
-| v0.3.0 | Scope format | `{ userId, orgId }` | `{ organisationId }` |
+## Configuration Migration
 
-### Component Changes
+### Environment Variables Migration
 
-| Version | Change | Before | After |
-|---------|--------|--------|-------|
-| v0.4.0 | Import paths | `/components` | Main export |
-| v0.3.0 | Prop interfaces | Legacy props | Updated interfaces |
-| v0.2.0 | Component names | Old names | New naming convention |
+```bash
+# Migration script for environment variables
+# old.env -> new.env
 
-## RBAC System Migration
+# Old environment variables
+VITE_AUTH_URL=https://old-auth.example.com
+VITE_API_KEY=old-api-key
+VITE_DEBUG_MODE=true
 
-### Legacy to New RBAC
+# New environment variables
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key
+VITE_APP_ENV=development
+VITE_DEBUG=false
 
-**Database Schema Changes:**
-```sql
--- New RBAC tables (v0.4.0+)
-CREATE TABLE rbac_apps (
-  id UUID PRIMARY KEY,
-  name TEXT NOT NULL,
-  requires_event BOOLEAN DEFAULT false
-);
-
-CREATE TABLE rbac_page_permissions (
-  id UUID PRIMARY KEY,
-  app_id UUID REFERENCES rbac_apps(id),
-  page_name TEXT NOT NULL,
-  operation TEXT NOT NULL,
-  required_permissions TEXT[] NOT NULL
-);
-
--- Migration from old system
-INSERT INTO rbac_apps (id, name, requires_event)
-VALUES ('your-app-id', 'Your App Name', false);
-```
-
-**Code Migration:**
-```tsx
-// Before (Legacy RBAC)
-import { useRBAC } from '@jmruthers/pace-core';
+# Migration script
+#!/bin/bash
+# migrate-env.sh
 
-function MyComponent() {
-  const { hasPermission } = useRBAC();
-  const canEdit = hasPermission('edit', 'users');
-}
+echo "Migrating environment variables..."
 
-// After (New RBAC)
-import { useCan } from '@jmruthers/pace-core/rbac';
+# Backup old environment file
+cp .env .env.backup
 
-function MyComponent() {
-  const { hasPermission } = useCan();
-  const canEdit = await hasPermission('update:users', { organisationId });
-}
-```
+# Create new environment file
+cat > .env << EOF
+# Supabase Configuration
+VITE_SUPABASE_URL=${VITE_SUPABASE_URL:-https://your-project.supabase.co}
+VITE_SUPABASE_ANON_KEY=${VITE_SUPABASE_ANON_KEY:-your-anon-key}
 
-### Permission Format Changes
+# Application Configuration
+VITE_APP_ENV=${VITE_APP_ENV:-development}
+VITE_DEBUG=${VITE_DEBUG:-false}
 
-**Old Format:**
-```tsx
-// v0.3.x and earlier
-hasPermission('read', 'users')
-hasPermission('edit', 'organisations')
-```
+# Feature Flags
+VITE_FEATURE_ANALYTICS=${VITE_FEATURE_ANALYTICS:-false}
+VITE_FEATURE_BETA=${VITE_FEATURE_BETA:-false}
 
-**New Format:**
-```tsx
-// v0.4.x and later
-hasPermission('read:users', { organisationId })
-hasPermission('update:organisations', { organisationId })
+# Monitoring
+VITE_SENTRY_DSN=${VITE_SENTRY_DSN:-}
+VITE_ANALYTICS_ID=${VITE_ANALYTICS_ID:-}
+EOF
+
+echo "Environment migration completed"
 ```
 
-## Organisation Context Changes
+### Build Configuration Migration
 
-### Provider Hierarchy Updates
+```typescript
+// Migration script for build configuration
+// vite.config.old.ts -> vite.config.ts
 
-**Timing Fix (v0.4.0):**
-```tsx
-// Before - Race condition possible
-<AuthProvider>
-  <OrganisationProvider>
-    <EventProvider>
-      <App />
-    </EventProvider>
-  </OrganisationProvider>
-</AuthProvider>
+// Old configuration
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    outDir: 'build',
+    sourcemap: true,
+  },
+  define: {
+    global: 'globalThis',
+  },
+});
 
-// After - Proper timing
-<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-  <OrganisationProvider>
-    <EventProvider>
-      <App />
-    </EventProvider>
-  </OrganisationProvider>
-</UnifiedAuthProvider>
+// New configuration
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    target: 'es2015',
+    outDir: 'dist',
+    sourcemap: false, // Disable in production
+    minify: 'terser',
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom'],
+          paceCore: ['@jmruthers/pace-core'],
+          supabase: ['@supabase/supabase-js'],
+        },
+      },
+    },
+    terserOptions: {
+      compress: {
+        drop_console: true,
+        drop_debugger: true,
+      },
+    },
+  },
+  define: {
+    __DEV__: JSON.stringify(process.env.NODE_ENV === 'development'),
+  },
+  optimizeDeps: {
+    include: ['@jmruthers/pace-core'],
+  },
+});
 ```
 
-### Context Resolution
+### Package.json Migration
 
-**Automatic Database Context:**
-```tsx
-// The OrganisationProvider now automatically sets database context
-// No manual setup required
-<OrganisationProvider>
-  <YourApp />
-</OrganisationProvider>
+```json
+// Migration script for package.json dependencies
+// package.json.old -> package.json
 
-// Database context is automatically set via:
-// SELECT set_organisation_context(organisation_id);
+{
+  "name": "my-app",
+  "version": "2.0.0",
+  "dependencies": {
+    // Old dependencies
+    "@jmruthers/pace-core": "^1.5.0",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    
+    // New dependencies
+    "@jmruthers/pace-core": "^2.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@supabase/supabase-js": "^2.38.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    // Old dev dependencies
+    "@types/react": "^17.0.0",
+    "@types/react-dom": "^17.0.0",
+    
+    // New dev dependencies
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "vite": "^4.4.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    // Old scripts
+    "start": "react-scripts start",
+    "build": "react-scripts build",
+    "test": "react-scripts test",
+    
+    // New scripts
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "type-check": "tsc --noEmit"
+  }
+}
 ```
 
-## Troubleshooting Common Migration Issues
-
-### Styling Issues After Upgrade
+## Migration Tools and Utilities
 
-**Problem:** Components appear unstyled after upgrade.
+### Migration Helper Functions
 
-**Solutions:**
-1. **Check Vite configuration:**
 ```typescript
-// Ensure pace-core source files are included
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
+// utils/migrationHelpers.ts
+export class MigrationHelpers {
+  // Check if migration is needed
+  static needsMigration(currentVersion: string, targetVersion: string): boolean {
+    const current = this.parseVersion(currentVersion);
+    const target = this.parseVersion(targetVersion);
+    
+    return current.major < target.major || 
+           (current.major === target.major && current.minor < target.minor);
+  }
+  
+  // Parse version string
+  static parseVersion(version: string) {
+    const [major, minor, patch] = version.split('.').map(Number);
+    return { major, minor, patch };
+  }
+  
+  // Migrate component props
+  static migrateComponentProps(oldProps: any, componentName: string) {
+    const migrations = {
+      Button: {
+        type: 'variant',
+        size: 'md',
+        loading: false,
+      },
+      DataTable: {
+        data: 'rows',
+        columns: 'columns',
+        pagination: 'enablePagination',
+      },
+      Form: {
+        onSubmit: 'onSubmit',
+        validation: 'schema',
+      },
+    };
+    
+    const migration = migrations[componentName];
+    if (!migration) return oldProps;
+    
+    const newProps = { ...oldProps };
+    
+    Object.entries(migration).forEach(([oldKey, newKey]) => {
+      if (oldProps[oldKey] !== undefined) {
+        newProps[newKey] = oldProps[oldKey];
+        delete newProps[oldKey];
+      }
+    });
+    
+    return newProps;
+  }
+  
+  // Migrate permission format
+  static migratePermissionFormat(permission: string): string {
+    return permission.replace('_', ':');
+  }
+  
+  // Migrate user data
+  static migrateUserData(user: any) {
+    return {
+      ...user,
+      permissions: user.permissions?.map(this.migratePermissionFormat) || [],
+      role: user.role || 'user',
+      organisation_id: user.organisation_id || 'default',
+    };
+  }
+  
+  // Generate migration report
+  static generateMigrationReport(changes: any[]) {
+    return {
+      timestamp: new Date().toISOString(),
+      changes,
+      summary: {
+        total: changes.length,
+        breaking: changes.filter(c => c.breaking).length,
+        nonBreaking: changes.filter(c => !c.breaking).length,
+      },
+    };
+  }
+}
 ```
 
-2. **Clear build cache:**
-```bash
-rm -rf dist .vite node_modules
-npm install
-npm run build
-```
+### Migration Validation
 
-3. **Verify CSS file size:**
-```bash
-# Should be 50-100+ KB
-ls -la dist/assets/*.css
+```typescript
+// utils/migrationValidation.ts
+export class MigrationValidation {
+  // Validate component usage
+  static validateComponentUsage(componentName: string, props: any) {
+    const validations = {
+      Button: {
+        required: ['children'],
+        optional: ['variant', 'size', 'loading', 'disabled', 'onClick'],
+        deprecated: ['type'],
+      },
+      DataTable: {
+        required: ['data', 'columns'],
+        optional: ['pagination', 'sorting', 'filtering'],
+        deprecated: ['rows'],
+      },
+    };
+    
+    const validation = validations[componentName];
+    if (!validation) return { valid: true, warnings: [] };
+    
+    const warnings = [];
+    
+    // Check for deprecated props
+    validation.deprecated.forEach(prop => {
+      if (props[prop] !== undefined) {
+        warnings.push(`Prop '${prop}' is deprecated in ${componentName}`);
+      }
+    });
+    
+    // Check for missing required props
+    validation.required.forEach(prop => {
+      if (props[prop] === undefined) {
+        warnings.push(`Required prop '${prop}' is missing in ${componentName}`);
+      }
+    });
+    
+    return {
+      valid: warnings.length === 0,
+      warnings,
+    };
+  }
+  
+  // Validate hook usage
+  static validateHookUsage(hookName: string, args: any[]) {
+    const validations = {
+      useUnifiedAuth: {
+        args: 0,
+        description: 'No arguments required',
+      },
+      useRBAC: {
+        args: 0,
+        description: 'No arguments required',
+      },
+      useEvents: {
+        args: 0,
+        description: 'No arguments required',
+      },
+    };
+    
+    const validation = validations[hookName];
+    if (!validation) return { valid: true, warnings: [] };
+    
+    const warnings = [];
+    
+    if (args.length !== validation.args) {
+      warnings.push(`${hookName} expects ${validation.args} arguments, got ${args.length}`);
+    }
+    
+    return {
+      valid: warnings.length === 0,
+      warnings,
+    };
+  }
+  
+  // Validate configuration
+  static validateConfiguration(config: any) {
+    const required = [
+      'VITE_SUPABASE_URL',
+      'VITE_SUPABASE_ANON_KEY',
+    ];
+    
+    const warnings = [];
+    
+    required.forEach(key => {
+      if (!config[key]) {
+        warnings.push(`Required environment variable '${key}' is missing`);
+      }
+    });
+    
+    return {
+      valid: warnings.length === 0,
+      warnings,
+    };
+  }
+}
 ```
 
-### Import Path Changes
+## Common Migration Issues
 
-**Problem:** Import errors after upgrade.
+### Styling Issues
 
-**Solutions:**
-1. **Update import paths:**
-```tsx
-// Old
-import { Button } from '@jmruthers/pace-core/components';
+**Problem**: Components appear unstyled after update
 
-// New
+**Solution**:
+```tsx
+// Ensure CSS import is first
+import '@jmruthers/pace-core/src/styles/core.css';
 import { Button } from '@jmruthers/pace-core';
 ```
 
-2. **Check for moved exports:**
-```tsx
-// RBAC hooks moved
-import { useCan } from '@jmruthers/pace-core/rbac';
+### Build Errors
+
+**Problem**: Build fails with Tailwind errors
+
+**Solution**:
+```bash
+# Clear all caches
+rm -rf node_modules package-lock.json
+npm install
+
+# Check Tailwind config
+npm run build -- --debug
+```
+
+### TypeScript Errors
+
+**Problem**: Type errors after update
+
+**Solution**:
+```bash
+# Update TypeScript types
+npm install @types/react@latest @types/react-dom@latest
 
-// Storage hooks
-import { useStorage } from '@jmruthers/pace-core';
+# Regenerate types
+npm run type-check
 ```
 
 ### Authentication Issues
 
-**Problem:** Authentication not working after upgrade.
+**Problem**: Login not working after update
 
-**Solutions:**
-1. **Update provider hierarchy:**
+**Solution**:
 ```tsx
-// Use UnifiedAuthProvider
+// Check provider hierarchy
 <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
   <OrganisationProvider>
     <EventProvider>
-      <App />
+      <YourApp />
     </EventProvider>
   </OrganisationProvider>
 </UnifiedAuthProvider>
 ```
 
-2. **Update hook usage:**
-```tsx
-// Use useUnifiedAuth
-const { user, signIn, signOut } = useUnifiedAuth();
-```
+## Migration Best Practices
 
-### RBAC Permission Issues
+### Migration Checklist
 
-**Problem:** Permissions not working after RBAC migration.
+- [ ] Review breaking changes documentation
+- [ ] Create migration plan
+- [ ] Set up staging environment
+- [ ] Backup current data
+- [ ] Test migration in staging
+- [ ] Update dependencies
+- [ ] Migrate configuration
+- [ ] Update code for new APIs
+- [ ] Test all functionality
+- [ ] Deploy to production
+- [ ] Monitor for issues
+- [ ] Clean up old code
 
-**Solutions:**
-1. **Update permission format:**
-```tsx
-// Old format
-hasPermission('read', 'users')
+### Migration Strategy
 
-// New format
-hasPermission('read:users', { organisationId })
+```typescript
+// Migration strategy implementation
+export class MigrationStrategy {
+  static async executeMigration(fromVersion: string, toVersion: string) {
+    console.log(`Starting migration from ${fromVersion} to ${toVersion}`);
+    
+    // 1. Pre-migration checks
+    const preChecks = await this.performPreChecks();
+    if (!preChecks.success) {
+      throw new Error(`Pre-migration checks failed: ${preChecks.errors.join(', ')}`);
+    }
+    
+    // 2. Backup current state
+    const backup = await this.createBackup();
+    console.log('Backup created:', backup.location);
+    
+    // 3. Update dependencies
+    await this.updateDependencies(toVersion);
+    
+    // 4. Migrate configuration
+    await this.migrateConfiguration();
+    
+    // 5. Migrate code
+    await this.migrateCode();
+    
+    // 6. Migrate data
+    await this.migrateData();
+    
+    // 7. Post-migration validation
+    const validation = await this.validateMigration();
+    if (!validation.success) {
+      console.error('Migration validation failed:', validation.errors);
+      await this.rollback(backup);
+      throw new Error('Migration failed validation');
+    }
+    
+    console.log('Migration completed successfully');
+    return { success: true, backup };
+  }
+  
+  static async performPreChecks() {
+    const checks = [
+      this.checkDependencies(),
+      this.checkConfiguration(),
+      this.checkDataIntegrity(),
+    ];
+    
+    const results = await Promise.all(checks);
+    const errors = results.flatMap(r => r.errors || []);
+    
+    return {
+      success: errors.length === 0,
+      errors,
+    };
+  }
+  
+  static async createBackup() {
+    // Implementation for creating backup
+    return {
+      location: '/backups/migration-backup-' + Date.now(),
+      timestamp: new Date().toISOString(),
+    };
+  }
+  
+  static async rollback(backup: any) {
+    console.log('Rolling back to backup:', backup.location);
+    // Implementation for rollback
+  }
+}
 ```
 
-2. **Check scope requirements:**
-```tsx
-// Always include organisation context
-const canEdit = await hasPermission('update:users', { 
-  organisationId: currentOrg.id 
-});
-```
+### Rollback Strategy
 
-3. **Verify database setup:**
-```sql
--- Ensure RBAC tables exist
-SELECT * FROM rbac_apps;
-SELECT * FROM rbac_page_permissions;
+```typescript
+// Rollback strategy implementation
+export class RollbackStrategy {
+  static async rollbackMigration(backup: any) {
+    console.log('Starting rollback process...');
+    
+    try {
+      // 1. Restore database
+      await this.restoreDatabase(backup.database);
+      
+      // 2. Restore configuration
+      await this.restoreConfiguration(backup.config);
+      
+      // 3. Restore code
+      await this.restoreCode(backup.code);
+      
+      // 4. Restore dependencies
+      await this.restoreDependencies(backup.dependencies);
+      
+      // 5. Validate rollback
+      const validation = await this.validateRollback();
+      
+      if (validation.success) {
+        console.log('Rollback completed successfully');
+        return { success: true };
+      } else {
+        throw new Error('Rollback validation failed');
+      }
+    } catch (error) {
+      console.error('Rollback failed:', error);
+      throw error;
+    }
+  }
+  
+  static async validateRollback() {
+    // Implementation for rollback validation
+    return { success: true };
+  }
+}
 ```
 
-### Build Errors
-
-**Problem:** Build fails after upgrade.
+## Emergency Rollback
 
-**Solutions:**
-1. **Update peer dependencies:**
 ```bash
-npm install @tanstack/react-table@^8.0.0
-npm install @radix-ui/react-checkbox@^1.0.0
-npm install @radix-ui/react-dialog@^1.0.0
+# Rollback to previous version
+npm install @jmruthers/pace-core@0.4.16
+
+# Or specific working version
+npm install @jmruthers/pace-core@0.4.15
+
+# Clear caches
+rm -rf node_modules package-lock.json
+npm install
 ```
 
-2. **Check TypeScript errors:**
+## Getting Help
+
+### If Migration Fails
+
+1. **Check the logs** - Look for specific error messages
+2. **Revert changes** - Go back to working version
+3. **Check documentation** - Look for migration guides
+4. **Search issues** - Check GitHub issues
+5. **Ask for help** - Create detailed issue report
+
+### Debug Information
+
+When asking for help, include:
+
 ```bash
-npm run type-check
-```
+# Version information
+npm list @jmruthers/pace-core
+node --version
+npm --version
 
-3. **Update tsconfig.json:**
-```json
-{
-  "compilerOptions": {
-    "skipLibCheck": true,
-    "moduleResolution": "node"
-  }
-}
+# Build output
+npm run build 2>&1 | tee build.log
+
+# Error details
+# Include full error messages and stack traces
 ```
 
-## Migration Checklist
+## Version History
+
+### v0.5.54 (Latest)
+
+**Changes:**
+- File reference system improvements
+- Enhanced error handling
+- Performance optimizations
+
+**Migration:** No action required - fully backward compatible.
+
+### v0.5.0 - v0.5.53
 
-### Pre-Migration
+**New Features:**
+- File Upload & Storage System
+- Inactivity Tracking
+- Public Pages System
+- Organisation Security
 
-- [ ] Backup current codebase
-- [ ] Document current version
-- [ ] Test current functionality
-- [ ] Check for custom configurations
+**Migration:** No breaking changes - all features are additive.
 
-### During Migration
+### v0.4.17
+- ⚠️ Source path fixes for Tailwind scanning
 
-- [ ] Update package.json
-- [ ] Update import statements
-- [ ] Update component usage
-- [ ] Update configuration files
-- [ ] Run type checking
-- [ ] Test build process
+### v0.4.16
+- ⚠️ CSS-first approach for Tailwind v4
 
-### Post-Migration
+### v0.4.15
+- ⚠️ Tailwind content scanning requirements
 
-- [ ] Test all functionality
-- [ ] Verify styling
-- [ ] Check authentication
-- [ ] Test RBAC permissions
-- [ ] Performance testing
-- [ ] Update documentation
+## Checking for Breaking Changes
 
-## Getting Help
+### Before Upgrading
 
-### Common Resources
+1. **Check this file** for breaking changes in your target version
+2. **Review migration guides** for each breaking change
+3. **Test in development environment** before production
+4. **Update TypeScript** to catch type errors early
 
-- **[Troubleshooting Guide](../troubleshooting/README.md)** - Detailed problem solving
-- **[API Reference](../api-reference/)** - Complete API documentation
-- **[Examples](../getting-started/examples/)** - Working code examples
-- **[GitHub Issues](https://github.com/jmruthers/pace-core/issues)** - Bug reports
+### Finding Your Current Version
 
-### Migration Support
+```bash
+npm list @jmruthers/pace-core
+```
 
-If you encounter issues during migration:
+Or check your `package.json`:
+```json
+{
+  "dependencies": {
+    "@jmruthers/pace-core": "^0.5.65"
+  }
+}
+```
 
-1. **Check this guide** for your specific version
-2. **Review troubleshooting section** for common issues
-3. **Test with minimal example** to isolate problems
-4. **Check GitHub issues** for similar problems
-5. **Create new issue** with detailed information
+## Staying Updated
 
-### Version-Specific Help
+To stay informed about breaking changes:
 
-- **v0.4.17+**: [Source Path Fix Guide](./v0.4.17-source-path-fix.md)
-- **v0.4.16**: [CSS-First Migration Guide](./v0.4.16-css-first-approach.md)
-- **v0.4.15**: [Tailwind Scanning Guide](./v0.4.15-tailwind-scanning.md)
-- **RBAC**: [RBAC Migration Guide](./rbac-migration.md)
+- 📢 **Check this file** before each upgrade
+- 📢 **Review release notes** on GitHub
+- 📢 **Subscribe to notifications** for major versions
+- 📢 **Follow migration guides** step-by-step
 
-## Next Steps
+---
 
-After successful migration:
+**Remember**: Always test breaking changes in a development environment before deploying to production.
 
-- **[Getting Started](../getting-started/quick-start.md)** - Learn new features
-- **[Implementation Guides](../implementation-guides/)** - Advanced patterns
-- **[Best Practices](../best-practices/)** - Production guidelines
-- **[API Reference](../api-reference/)** - Complete documentation
+**Last Updated**: January 2025  
+**Current Stable Version**: v0.5.65+  
+**Next Major Version**: v1.0.0 (TBD)