@jmruthers/pace-core 0.5.57 → 0.5.58

package/docs/troubleshooting/common-issues.md

@@ -1,1563 +1,163 @@
-# Common Issues
+# Common Issues & Solutions
 
-This guide provides solutions to the most common issues you may encounter when using `@jmruthers/pace-core`.
+## 🚨 **Critical Setup Issues**
 
-## Navigation Issues
+### Issue 1: "RPC call timeout after 10 seconds" / "Loading organisation context..." hangs
 
-### NavigationMenu Not Receiving Authentication Context
+**Symptoms:**
+- App hangs on "Loading organisation context..."
+- Console shows "RPC call timeout after 10 seconds"
+- No error messages, just infinite loading
 
-**Problem**: `NavigationMenu` shows `permissions: undefined`, `roles: undefined`, `accessLevel: undefined` in console logs.
+**Root Cause:** Wrong API key or missing RBAC setup
 
-**Root Cause**: The `NavigationMenu` component is not properly connected to the authentication context.
-
-**Solution**: Ensure `NavigationMenu` is used within the proper provider hierarchy and enable permission filtering:
-
-```tsx
-// ❌ WRONG - NavigationMenu without proper context
-<NavigationMenu 
-  items={navItems}
-  currentPath={location.pathname}
-  onNavigate={handleNavigate}
-/>
-
-// ✅ CORRECT - NavigationMenu with authentication context
-<UnifiedAuthProvider supabaseClient={supabase} appName="My App">
-  <OrganisationProvider>
-    <EventProvider>
-      <PaceAppLayout 
-        appName="My App" 
-        navItems={navItems}
-        showEventSelector={true}
-      >
-        <Routes>
-          {/* Your routes */}
-        </Routes>
-      </PaceAppLayout>
-    </EventProvider>
-  </OrganisationProvider>
-</UnifiedAuthProvider>
-```
-
-**Alternative Solution**: Use `NavigationMenu` directly with permission filtering:
-
-```tsx
-import { NavigationMenu } from '@jmruthers/pace-core';
-import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
-
-function AuthenticatedNavigation() {
-  const { hasPermission, hasRole } = useUnifiedAuth();
-
-  const navItems = [
-    { 
-      id: 'dashboard', 
-      label: 'Dashboard', 
-      href: '/dashboard',
-      permissions: ['dashboard:read']
-    },
-    { 
-      id: 'admin', 
-      label: 'Admin Panel', 
-      href: '/admin',
-      roles: ['admin']
-    }
-  ];
-
-  return (
-    <NavigationMenu 
-      items={navItems}
-      currentPath={location.pathname}
-      onNavigate={handleNavigate}
-      filterByPermissions={true}
-      auditLog={true}
-    />
-  );
-}
-```
-
-### NavigationMenu Items Not Filtering by Permissions
-
-**Problem**: All navigation items are shown regardless of user permissions.
-
-**Solution**: Enable permission filtering and add permission requirements to navigation items:
-
-```tsx
-// Add permissions to navigation items
-const navItems = [
-  { 
-    id: 'dashboard', 
-    label: 'Dashboard', 
-    href: '/dashboard',
-    permissions: ['dashboard:read'] // Required permission
-  },
-  { 
-    id: 'admin', 
-    label: 'Admin Panel', 
-    href: '/admin',
-    roles: ['admin', 'super_admin'] // Required roles
-  }
-];
-
-// Enable filtering
-<NavigationMenu 
-  items={navItems}
-  filterByPermissions={true}
-  auditLog={true}
-/>
-```
-
-### NavigationMenu Console Errors
-
-**Problem**: Console shows "useUnifiedAuth not available" warnings.
-
-**Solution**: Ensure `NavigationMenu` is used within `UnifiedAuthProvider`:
-
-```tsx
-// ❌ WRONG - Outside of auth provider
-<NavigationMenu items={navItems} />
-
-// ✅ CORRECT - Inside auth provider
-<UnifiedAuthProvider supabaseClient={supabase} appName="My App">
-  <NavigationMenu items={navItems} />
-</UnifiedAuthProvider>
-```
-
-## Authentication Issues
-
-### 1. "User not authenticated" Error
-
-**Problem**: Users are getting "not authenticated" errors even when they should be logged in.
-
-**Solution**:
-
-```typescript
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function App() {
-  const { user, loading, error } = useUnifiedAuth();
-
-  if (loading) {
-    return <div>Loading...</div>;
-  }
-
-  if (error) {
-    console.error('Auth error:', error);
-    return <div>Authentication error: {error.message}</div>;
-  }
-
-  if (!user) {
-    return <LoginForm />;
-  }
-
-  return <AuthenticatedApp />;
-}
-```
-
-**Common Causes**:
-- Session expired
-- Invalid token
-- Network connectivity issues
-- Supabase configuration problems
-
-**Debugging**:
-```typescript
-// Check session status
-const { session } = useUnifiedAuth();
-console.log('Session:', session);
-console.log('Session expires:', new Date(session?.expires_at * 1000));
-```
-
-### 2. Authentication Provider Not Wrapped
-
-**Problem**: Components can't access authentication context.
-
-**Solution**: Ensure your app is wrapped with the authentication provider:
-
-```typescript
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <UnifiedAuthProvider>
-      <YourApp />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-### 3. Session Refresh Issues
-
-**Problem**: Sessions are not refreshing automatically.
-
-**Solution**:
-
-```typescript
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function SessionManager() {
-  const { session, refreshSession } = useUnifiedAuth();
-
-  useEffect(() => {
-    if (session && session.expires_at) {
-      const timeUntilExpiry = session.expires_at * 1000 - Date.now();
-      const refreshTime = Math.max(timeUntilExpiry - 5 * 60 * 1000, 0);
-
-      const timer = setTimeout(() => {
-        refreshSession();
-      }, refreshTime);
-
-      return () => clearTimeout(timer);
-    }
-  }, [session, refreshSession]);
-
-  return null;
-}
-```
-
-## Permission Issues
-
-### 1. "Access denied" Errors
-
-**Problem**: Users are getting access denied even when they should have permissions.
-
-**Solution**:
-
-```typescript
-import { useRBAC } from '@jmruthers/pace-core';
-
-function DebugPermissions() {
-  const { user, roles, permissions, hasPermission } = useRBAC();
-
-  console.log('User:', user);
-  console.log('Roles:', roles);
-  console.log('Permissions:', permissions);
-
-  // Test specific permissions
-  console.log('Can read users:', hasPermission('read:users'));
-  console.log('Can create events:', hasPermission('create:events'));
-
-  return (
-    <div>
-      <h3>Permission Debug Info</h3>
-      <p>User: {user?.email}</p>
-      <p>Roles: {roles.map(r => r.name).join(', ')}</p>
-      <p>Permissions: {permissions.map(p => p.name).join(', ')}</p>
-    </div>
-  );
-}
-```
-
-### 2. Page Permission Not Working
-
-**Problem**: Page-level permissions are not being enforced.
-
-**Solution**:
-
-```typescript
-import { usePagePermission } from '@jmruthers/pace-core';
-
-function ProtectedPage() {
-  const { hasAccess, loading, error } = usePagePermission('admin');
-
-  if (loading) {
-    return <div>Checking permissions...</div>;
-  }
-
-  if (error) {
-    console.error('Permission error:', error);
-    return <div>Error checking permissions</div>;
-  }
-
-  if (!hasAccess) {
-    return <div>Access denied</div>;
-  }
+**Solution:**
+1. **Verify API Key Type** - Ensure you're using the **anon key**, not service role key
+   ```typescript
+   // Check your environment variables
+   console.log('API Key check:', {
+     hasAnonKey: !!process.env.REACT_APP_SUPABASE_ANON_KEY,
+     keyLength: process.env.REACT_APP_SUPABASE_ANON_KEY?.length,
+     startsWithEyJ: process.env.REACT_APP_SUPABASE_ANON_KEY?.startsWith('eyJ')
+   })
+   ```
 
-  return <AdminDashboard />;
-}
-```
+2. **Ensure RBAC Setup** - Call `setupRBAC` before using RBAC features
+   ```typescript
+   // src/main.tsx - MUST be called before rendering
+   import { setupRBAC } from '@jmruthers/pace-core/rbac'
+   setupRBAC(supabase)
+   ```
 
-### 3. Organisation Context Missing
+3. **Check Provider Configuration** - Verify correct provider hierarchy
+   ```tsx
+   <UnifiedAuthProvider 
+     supabaseClient={supabase} 
+     appName="your-app"
+     enableRBAC={true}
+     requireOrganisationContext={true}
+   >
+     <OrganisationProvider>
+       <EventProvider>
+         <YourApp />
+       </EventProvider>
+     </OrganisationProvider>
+   </UnifiedAuthProvider>
+   ```
 
-**Problem**: Organisation-based permissions are not working.
+### Issue 2: "No organisation context available"
 
-**Solution**:
+**Symptoms:**
+- Error: "No organisation context available"
+- Components can't access organisation data
 
-```typescript
-import { useOrganisation } from '@jmruthers/pace-core';
+**Root Cause:** Missing OrganisationProvider or wrong provider order
 
-function OrganisationAwareComponent() {
-  const { currentOrganisation, loading, error } = useOrganisation();
+**Solution:**
+1. Ensure OrganisationProvider wraps your app content
+2. Check provider hierarchy is correct
+3. Verify `requireOrganisationContext={true}` is set
 
-  if (loading) {
-    return <div>Loading organisation...</div>;
-  }
+### Issue 3: "RBAC system not initialized"
 
-  if (error) {
-    console.error('Organisation error:', error);
-    return <div>Error loading organisation</div>;
-  }
+**Symptoms:**
+- Error: "RBAC system not initialized"
+- Permission checks fail
 
-  if (!currentOrganisation) {
-    return <div>Please select an organisation</div>;
-  }
+**Root Cause:** Missing `setupRBAC` call
 
-  return (
-    <div>
-      <h1>{currentOrganisation.name}</h1>
-      {/* Your component content */}
-    </div>
-  );
-}
-```
+**Solution:**
+1. Import `setupRBAC` from `@jmruthers/pace-core/rbac`
+2. Call `setupRBAC(supabase)` before using any RBAC features
+3. Ensure this happens before rendering your app
 
-### 4. Organisation Context Timing Issue (v0.3.44+ Fixed)
+### Issue 4: Components appear unstyled
 
-**Problem**: RLS policies failing on first load, super admin permissions returning false, or database queries not filtering by organisation.
+**Symptoms:**
+- Pace-core components have no styling
+- UI looks broken or unstyled
 
-**Root Cause**: Race condition where database organisation context wasn't set before other components tried to make queries.
+**Root Cause:** Missing CSS imports or Tailwind configuration
 
-**Solution**: This issue was fixed in v0.3.44+. The `OrganisationProvider` now:
+**Solution:**
+1. **Import CSS** - Add to your main entry point:
+   ```tsx
+   import '@jmruthers/pace-core/styles/core.css'
+   ```
 
-1. **Sets database context before rendering children**
-2. **Shows loading states during context setup**
-3. **Prevents race conditions with database queries**
+2. **Configure Tailwind v4** - Ensure proper content scanning:
+   ```js
+   // vite.config.js
+   import tailwindcss from '@tailwindcss/vite'
+   
+   export default defineConfig({
+     plugins: [
+       tailwindcss({
+         content: [
+           './src/**/*.{js,ts,jsx,tsx}',
+           './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+         ]
+       })
+     ]
+   })
+   ```
 
-If you're still experiencing this issue:
+## 🔍 **Debugging Checklist**
 
-```typescript
-// ✅ Ensure proper provider hierarchy
-<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-  <OrganisationProvider>  {/* This now handles context timing automatically */}
-    <EventProvider>
-      <YourAppContent />
-    </EventProvider>
-  </OrganisationProvider>
-</UnifiedAuthProvider>
-```
-
-**For v0.3.43 and earlier**: You may need to implement a local workaround:
+### 1. Verify Environment Variables
 
 ```typescript
-// Temporary workaround for older versions
-function OrganisationContextGuard({ children }: { children: React.ReactNode }) {
-  const { selectedOrganisation } = useOrganisation();
-  const { supabase } = useUnifiedAuth();
-  const [contextReady, setContextReady] = useState(false);
-
-  useEffect(() => {
-    if (selectedOrganisation && supabase) {
-      setOrganisationContext(supabase, selectedOrganisation.id)
-        .then(() => setContextReady(true))
-        .catch(console.error);
-    }
-  }, [selectedOrganisation, supabase]);
-
-  if (!contextReady) {
-    return <div>Setting up organisation context...</div>;
-  }
-
-  return <>{children}</>;
-}
-```
-
-**Detailed Setup**: If you're getting "unrecognized configuration parameter" errors, see the [Organisation Context Setup Guide](./organisation-context-setup.md) for complete database setup instructions.
-
-## Styling Issues
-
-### 1. App Looks Unstyled (Raw HTML)
-
-**Problem**: App appears with default browser styling only - no colors, fonts, or proper layout.
-
-**Symptoms**:
-- Default browser styling only
-- No colors, fonts, or layout
-- Components look like plain HTML
-- Header is squashed or too wide
-- Main container stretches full width
-- Missing colored background
-
-**Solution**:
-
-**CRITICAL**: Use the `PaceAppLayout` component - don't just import CSS files:
-
-```tsx
-// ❌ Wrong - just CSS imports
-import '@jmruthers/pace-core/styles/core.css';
-
-function App() {
-  return (
-    <div>
-      <h1>My App</h1>
-      {/* This won't be styled properly */}
-    </div>
-  );
-}
-
-// ✅ Correct - use PaceAppLayout
-import { PaceAppLayout } from '@jmruthers/pace-core';
-import './app.css'; // Your app's color palette (must come first)
-import '@jmruthers/pace-core/styles/core.css';
-
-function App() {
-  return (
-    <PaceAppLayout appName="My Application">
-      <div className="container mx-auto px-4 py-6">
-        <h1 className="text-3xl font-bold text-main-900">My App</h1>
-        <p className="text-main-700">This will be properly styled</p>
-      </div>
-    </PaceAppLayout>
-  );
-}
-```
-
-**Common Causes**:
-- Missing CSS imports
-- Wrong build tool configuration (using Tailwind v3 instead of v4)
-- Not using PaceAppLayout component
-- Missing app.css with color palette
-- CSS files not being processed
-
-**Build Tool Configuration**:
-
-**For Vite (Recommended):**
-```js
-// vite.config.js
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss() // Tailwind v4 - no config file needed!
-  ],
+console.log('Environment check:', {
+  url: process.env.REACT_APP_SUPABASE_URL,
+  hasKey: !!process.env.REACT_APP_SUPABASE_ANON_KEY,
+  keyLength: process.env.REACT_APP_SUPABASE_ANON_KEY?.length
 })
 ```
 
-**Dependencies:**
-```bash
-npm install -D @tailwindcss/vite tailwindcss@^4.0.0
-# Remove old Tailwind v3 if installed
-npm uninstall tailwindcss@^3.0.0
-```
-
-**Create app.css with Color Palette:**
-```css
-/* app.css - Your app's color palette */
-@theme static {
-  /* MAIN palette - your primary brand color */
-  --color-main-raw: oklch(0.7 0.057 252.02);
-  --color-main-50: oklch(0.98 0.001 252.02);
-  --color-main-100: oklch(0.96 0.005 252.02);
-  --color-main-200: oklch(0.927 0.012 252.02);
-  --color-main-300: oklch(0.881 0.021 252.02);
-  --color-main-400: oklch(0.822 0.032 252.02);
-  --color-main-500: oklch(0.75 0.047 252.02);
-  --color-main-600: oklch(0.7 0.057 252.02);
-  --color-main-700: oklch(0.567 0.044 252.02);
-  --color-main-800: oklch(0.456 0.034 252.02);
-  --color-main-900: oklch(0.332 0.024 252.02);
-  --color-main-950: oklch(0.195 0.014 252.02);
-
-  /* SEC palette - your secondary brand color */
-  --color-sec-raw: oklch(0.58 0.23 280.75);
-  --color-sec-50: oklch(0.98 0.003 280.75);
-  --color-sec-100: oklch(0.96 0.014 280.75);
-  --color-sec-200: oklch(0.927 0.033 280.75);
-  --color-sec-300: oklch(0.881 0.059 280.75);
-  --color-sec-400: oklch(0.822 0.093 280.75);
-  --color-sec-500: oklch(0.75 0.133 280.75);
-  --color-sec-600: oklch(0.665 0.182 280.75);
-  --color-sec-700: oklch(0.58 0.23 280.75);
-  --color-sec-800: oklch(0.456 0.158 280.75);
-  --color-sec-900: oklch(0.332 0.099 280.75);
-  --color-sec-950: oklch(0.195 0.047 280.75);
-
-  /* ACC palette - your accent brand color */
-  --color-acc-raw: oklch(0.64 0.21 37.76);
-  --color-acc-50: oklch(0.98 0.003 37.76);
-  --color-acc-100: oklch(0.96 0.015 37.76);
-  --color-acc-200: oklch(0.927 0.035 37.76);
-  --color-acc-300: oklch(0.881 0.063 37.76);
-  --color-acc-400: oklch(0.822 0.099 37.76);
-  --color-acc-500: oklch(0.75 0.143 37.76);
-  --color-acc-600: oklch(0.64 0.21 37.76);
-  --color-acc-700: oklch(0.567 0.177 37.76);
-  --color-acc-800: oklch(0.456 0.13 37.76);
-  --color-acc-900: oklch(0.332 0.085 37.76);
-  --color-acc-950: oklch(0.195 0.044 37.76);
-}
-```
-
-**Debugging Steps**:
-1. Check Browser DevTools for CSS import errors
-2. Verify pace-core CSS files are loading in Network tab
-3. Inspect elements to see if Tailwind classes are applied
-4. Ensure Tailwind v4 is installed and configured
-5. Test CSS imports with temporary rule: `body { background-color: red !important; }`
-
-**Quick Checklist**:
-- [ ] CSS files imported in main.tsx/App.tsx
-- [ ] app.css created with color palette
-- [ ] Using PaceAppLayout component
-- [ ] Tailwind v4 configured in build tool
-- [ ] No custom CSS overriding pace-core styles
-- [ ] All required dependencies installed
-- [ ] No build errors in console
-
-### 2. App Looks Different from Demo (v0.3.47+ Fixed)
-
-**Problem**: Your consuming app looks different from the PACE Core demo app
-
-**Symptoms**:
-- Different background colors (gray instead of blue)
-- Different text colors
-- Overall different visual appearance
-
-**Root Cause**: The demo app uses a custom CSS configuration, while consuming apps use our theme file. The theme file was using neutral gray colors instead of the blue-tinted scheme from the demo.
-
-**Solution**: This issue was fixed in v0.3.47+. The theme file now uses the same blue-tinted color scheme as the demo app:
-
-- **Background**: Very light blue (`--color-primary-50`)
-- **Foreground**: Very dark blue (`--color-primary-950`)
-- **Primary**: Blue (`--color-primary-600`)
-- **Borders**: Blue (`--color-primary-500`)
-- **Inputs**: Light purple (`--color-secondary-200`)
-
-**Quick Fix**:
-```bash
-npm install @jmruthers/pace-core@latest
-```
-
-### 2. Header Layout Issues (v0.3.48+ Fixed)
-
-**Problem**: Header elements are stacked vertically instead of being aligned horizontally across the page
-
-**Symptoms**:
-- Logo, navigation, and user menu are stacked vertically
-- Header doesn't use the full width properly
-- Layout looks broken compared to demo app
-
-**Root Cause**: Missing CSS variables that the header component depends on:
-- `--app-width` (for container width)
-- `--color-main-*` (for header background colors)
-- `--color-sec-*` and `--color-acc-*` (for other header elements)
-
-**Solution**: This issue was fixed in v0.3.48+. The theme file now includes all required CSS variables:
-
-- **Layout Variables**: `--app-width: 90rem`
-- **App Color Variables**: `--color-main-*`, `--color-sec-*`, `--color-acc-*`
-- **Complete Color Palette**: All color variants (50, 100, 200, etc.) plus `-raw` variants
-
-**Quick Fix**:
-```bash
-npm install @jmruthers/pace-core@latest
-```
-
-### 3. Missing CSS Variables (v0.3.49+ Fixed)
-
-**Problem**: Components not rendering correctly due to missing CSS variables
-
-**Symptoms**:
-- Components appear unstyled or broken
-- Console errors about undefined CSS variables
-- Inconsistent appearance across different components
-- DataTable examples not working properly
-
-**Root Cause**: The theme file was missing many CSS variables that components depend on:
-- Font variables (--font-sans, --font-serif, --font-mono)
-- Design tokens (--pace-* variables)
-- Event colors (--color-ev-* variables)
-- Radix UI variables (--radix-toast-*)
-
-**Solution**: This issue was fixed in v0.3.49+. The theme file now includes comprehensive variable coverage:
-
-- **Font Variables**: All typography variables for consistent fonts
-- **Design Tokens**: Complete PACE Core design token system
-- **Event Colors**: Full color palette for DataTable examples
-- **Component Variables**: All variables needed for component styling
-- **Radix UI Variables**: Third-party component library compatibility
-
-**Quick Fix**:
-```bash
-npm install @jmruthers/pace-core@latest
-```
-
-### 4. Login Page Styling Issues (v0.4.4+ Fixed)
-
-**Problem**: Login page looks different from the pace-core demo - unstyled button, wrong background, missing shadows.
-
-**Symptoms**:
-- Button appears as plain text instead of styled button
-- Background is white instead of gradient
-- Card has no shadow or wrong styling
-- Input fields are dark instead of white
-- Overall appearance doesn't match the demo
-
-**Root Cause**: Missing theme mappings in `styles/core.css` prevented CSS variables from being processed correctly by Tailwind v4.
-
-**Solution**: This issue was fixed in v0.4.4+. The theme file now includes complete mappings for all color palettes.
-
-**Quick Fix**:
-```bash
-npm install @jmruthers/pace-core@latest
-```
-
-**Required Setup** (must be exactly like this):
-
-1. **CSS Imports** (in your main.tsx):
-```tsx
-import './app.css'; // Your app's palette definitions (must come first)
-import '@jmruthers/pace-core/styles/core.css';
-```
-
-2. **App.css** (complete palette required):
-```css
-@theme static {
-  /* MAIN palette - your primary brand color */
-  --color-main-50: oklch(0.98 0.001 252.02);
-  --color-main-100: oklch(0.96 0.005 252.02);
-  /* ... all shades 50-950 + raw */
-  
-  /* SEC palette - your secondary brand color */
-  --color-sec-50: oklch(0.98 0.003 280.75);
-  /* ... all shades 50-950 + raw */
-  
-  /* ACC palette - your accent brand color */
-  --color-acc-50: oklch(0.98 0.003 37.76);
-  /* ... all shades 50-950 + raw */
-}
-
-@layer base {
-  .appGradient {
-    background: radial-gradient(var(--color-main-200), oklch(from var(--color-main-200) l c h / 0%) 30%), 
-                conic-gradient(var(--color-main-200), var(--color-sec-200), var(--color-acc-200), var(--color-main-200));
-    background-attachment: fixed;
-  }
-}
-```
-
-3. **HTML Structure** (in your index.html):
-```html
-<body class="appGradient">
-  <div id="root" class="grid grid-rows-[auto_1fr_auto] min-h-screen"></div>
-</body>
-```
-
-4. **Vite Configuration** (Tailwind v4 required):
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import tailwindcss from '@tailwindcss/vite';
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss() // Tailwind v4 - no config file needed!
-  ],
-});
-```
-
-**Debugging Steps**:
-1. Check browser dev tools for CSS import errors
-2. Verify `bg-main-600` class resolves to actual color value
-3. Ensure all CSS files are imported in correct order
-4. Confirm Tailwind v4 is installed (not v3)
-5. Test with minimal setup to isolate the issue
-
-### 5. Tailwind v4 Theme File Issues (v0.3.45+ Fixed)
-
-**Problem**: Build failures when using `@import '@jmruthers/pace-core/styles/core.css'`
-
-**Root Cause**: The theme file was missing semantic colors and had circular references in component classes.
-
-**Solution**: This issue was fixed in v0.3.45+. The theme file now includes:
-
-- **Complete semantic colors** (ring, border, background, foreground, etc.)
-- **Fixed component classes** (no circular @apply references)
-- **All required Tailwind v4 colors**
-
-**Quick Fix**:
-```bash
-npm install @jmruthers/pace-core@latest
-```
-
-**Usage**:
-```css
-/* index.css */
-@import '@jmruthers/pace-core/styles/core.css';
-```
-
-**Vite Configuration**:
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import tailwindcss from '@tailwindcss/vite';
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss() // ✅ Simple - theme is in CSS
-  ],
-});
-```
-
-### 2. Missing Semantic Colors
-
-**Problem**: Colors like `ring-ring`, `border`, `background` not working
-
-**Solution**: The theme file now includes all semantic colors:
-
-```css
-/* These are now included in the theme file */
---color-ring: var(--color-primary-600);
---color-border: var(--color-neutral-300);
---color-background: var(--color-neutral-50);
---color-foreground: var(--color-neutral-950);
-/* ... and more */
-```
-
-### 3. Component Classes Not Working
-
-**Problem**: `.pace-button`, `.pace-input` classes not applying styles
-
-**Solution**: Component classes are now self-contained:
-
-```css
-/* ✅ Fixed - no circular references */
-.pace-button-primary {
-  @apply inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none ring-offset-background bg-primary-600 text-main-50 hover:bg-primary-700 active:bg-primary-800;
-}
-```
-
-## Event Management Issues
-
-### 1. Events Not Loading
-
-**Problem**: Events are not being fetched or displayed.
-
-**Solution**:
+### 2. Test Supabase Connection
 
 ```typescript
-import { useEvents } from '@jmruthers/pace-core';
-
-function EventList() {
-  const { events, loading, error, refreshEvents } = useEvents();
-
-  if (loading) {
-    return <div>Loading events...</div>;
-  }
-
-  if (error) {
-    console.error('Events error:', error);
-    return (
-      <div>
-        <div>Error loading events: {error}</div>
-        <button onClick={refreshEvents}>Retry</button>
-      </div>
-    );
-  }
-
-  if (!events || events.length === 0) {
-    return <div>No events found</div>;
-  }
-
-  return (
-    <div>
-      {events.map(event => (
-        <div key={event.id}>
-          <h3>{event.name}</h3>
-          <p>{event.description}</p>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-### 2. Event Selection Not Working
-
-**Problem**: Users can't select events or the selection is not persisting.
-
-**Solution**:
-
-```typescript
-import { useEvents } from '@jmruthers/pace-core';
-
-function EventSelector() {
-  const { events, selectedEvent, setSelectedEvent, hasAccess } = useEvents();
-
-  const handleEventSelect = (event) => {
-    if (hasAccess(event.id)) {
-      setSelectedEvent(event);
-    } else {
-      console.warn('User does not have access to this event');
-    }
-  };
-
-  return (
-    <div>
-      <h2>Select Event</h2>
-      {events.map(event => (
-        <div key={event.id}>
-          <span>{event.name}</span>
-          {hasAccess(event.id) ? (
-            <button onClick={() => handleEventSelect(event)}>
-              {selectedEvent?.id === event.id ? 'Selected' : 'Select'}
-            </button>
-          ) : (
-            <span>No access</span>
-          )}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Form Issues
-
-### 1. Form Validation Not Working
-
-**Problem**: Form validation is not triggering or showing errors.
-
-**Solution**:
-
-```typescript
-import { useZodForm } from '@jmruthers/pace-core';
-import { z } from 'zod';
-
-const schema = z.object({
-  name: z.string().min(1, 'Name is required'),
-  email: z.string().email('Invalid email'),
-});
-
-function UserForm() {
-  const {
-    register,
-    handleSubmit,
-    formState: { errors, isSubmitting },
-    reset,
-  } = useZodForm(schema);
-
-  const onSubmit = async (data) => {
-    try {
-      await createUser(data);
-      reset();
-    } catch (error) {
-      console.error('Form submission error:', error);
-    }
-  };
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <div>
-        <input {...register('name')} placeholder="Name" />
-        {errors.name && <span className="error">{errors.name.message}</span>}
-      </div>
-      
-      <div>
-        <input type="email" {...register('email')} placeholder="Email" />
-        {errors.email && <span className="error">{errors.email.message}</span>}
-      </div>
-      
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? 'Submitting...' : 'Submit'}
-      </button>
-    </form>
-  );
-}
-```
-
-### 2. Form Data Not Saving
-
-**Problem**: Form data is not being saved to the database.
-
-**Solution**:
-
-```typescript
-import { useZodForm } from '@jmruthers/pace-core';
-import { useSupabase } from '@jmruthers/pace-core';
-
-function UserForm() {
-  const { supabase } = useSupabase();
-  const { currentOrganisation } = useOrganisation();
-
-  const onSubmit = async (data) => {
-    try {
-      const { error } = await supabase
-        .from('users')
-        .insert({
-          ...data,
-          organisation_id: currentOrganisation.id,
-        });
-
-      if (error) {
-        console.error('Database error:', error);
-        throw error;
-      }
-
-      console.log('User created successfully');
-    } catch (error) {
-      console.error('Form submission error:', error);
-    }
-  };
-
-  // ... rest of form component
-}
-```
-
-## Component Issues
-
-### 1. Components Not Rendering
-
-**Problem**: Components are not rendering or showing blank content.
-
-**Solution**:
-
-```typescript
-import { ErrorBoundary } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <ErrorBoundary fallback={<div>Something went wrong</div>}>
-      <YourComponents />
-    </ErrorBoundary>
-  );
-}
-```
-
-### 2. Styling Issues
-
-**Problem**: Components are not styled correctly or styles are missing.
-
-**Solution**:
-
-```typescript
-// Ensure Tailwind CSS is imported
-// Import the core CSS file
-import './app.css'; // Your app's color palette (must come first)
-import '@jmruthers/pace-core/styles/core.css';
-
-// Check if your app is properly set up
-function App() {
-  return (
-    <div>
-      <YourApp />
-    </div>
-  );
-}
-```
-
-### 3. Component Props Issues
-
-**Problem**: Components are not receiving the correct props or props are undefined.
-
-**Solution**:
-
-```typescript
-import { Button } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  // Always provide required props
-  return (
-    <Button 
-      variant="primary"
-      onClick={() => console.log('clicked')}
-    >
-      Click me
-    </Button>
-  );
-}
-```
-
-## Database Issues
-
-### 1. Database Connection Errors
-
-**Problem**: Cannot connect to Supabase database.
-
-**Solution**:
-
-```typescript
-import { createSupabaseClient } from '@jmruthers/pace-core';
-
-// Check environment variables
-const supabaseUrl = process.env.SUPABASE_URL;
-const supabaseKey = process.env.SUPABASE_ANON_KEY;
-
-if (!supabaseUrl || !supabaseKey) {
-  console.error('Missing Supabase environment variables');
-  throw new Error('Supabase configuration missing');
-}
-
-const supabase = createSupabaseClient(supabaseUrl, supabaseKey);
-
-// Test connection
-supabase.from('users').select('count').single()
-  .then(() => console.log('Database connected'))
-  .catch(error => console.error('Database connection failed:', error));
-```
-
-### 2. RLS Policy Issues
-
-**Problem**: Row Level Security policies are blocking legitimate access.
-
-**Solution**:
-
-```sql
--- Check if RLS is enabled
-SELECT schemaname, tablename, rowsecurity 
-FROM pg_tables 
-WHERE tablename = 'your_table_name';
-
--- Check policies
-SELECT * FROM pg_policies WHERE tablename = 'your_table_name';
-
--- Test policy
-SELECT * FROM your_table_name WHERE organisation_id = 'your_org_id';
-```
-
-### 3. Data Not Filtered by Organisation
-
-**Problem**: Data is not being filtered by the current organisation.
-
-**Solution**:
-
-```typescript
-import { useOrganisation } from '@jmruthers/pace-core';
-import { useSupabase } from '@jmruthers/pace-core';
-
-function DataComponent() {
-  const { supabase } = useSupabase();
-  const { currentOrganisation } = useOrganisation();
-
-  const fetchData = async () => {
-    if (!currentOrganisation) {
-      console.warn('No organisation selected');
-      return;
-    }
-
-    const { data, error } = await supabase
-      .from('your_table')
-      .select('*')
-      .eq('organisation_id', currentOrganisation.id);
-
-    if (error) {
-      console.error('Database error:', error);
-      return;
-    }
-
-    console.log('Filtered data:', data);
-  };
-
-  return (
-    <div>
-      <button onClick={fetchData}>Load Data</button>
-    </div>
-  );
-}
-```
-
-## Performance Issues
-
-### 1. Slow Loading Times
-
-**Problem**: Components are taking too long to load.
-
-**Solution**:
-
-```typescript
-import { useMemo } from 'react';
-import { useEvents } from '@jmruthers/pace-core';
-
-function OptimizedEventList() {
-  const { events, loading } = useEvents();
-
-  // Memoize expensive calculations
-  const sortedEvents = useMemo(() => {
-    return events?.sort((a, b) => 
-      new Date(a.start_date).getTime() - new Date(b.start_date).getTime()
-    ) || [];
-  }, [events]);
-
-  if (loading) {
-    return <div>Loading events...</div>;
-  }
-
-  return (
-    <div>
-      {sortedEvents.map(event => (
-        <EventCard key={event.id} event={event} />
-      ))}
-    </div>
-  );
-}
-```
-
-### 2. Memory Leaks
-
-**Problem**: Memory usage is increasing over time.
-
-**Solution**:
-
-```typescript
-import { useEffect, useCallback } from 'react';
-import { useEvents } from '@jmruthers/pace-core';
-
-function EventManager() {
-  const { events, refreshEvents } = useEvents();
-
-  // Clean up on unmount
-  useEffect(() => {
-    return () => {
-      // Cleanup function
-      console.log('Component unmounting');
-    };
-  }, []);
-
-  // Memoize callbacks
-  const handleRefresh = useCallback(() => {
-    refreshEvents();
-  }, [refreshEvents]);
-
-  return (
-    <div>
-      <button onClick={handleRefresh}>Refresh Events</button>
-      {/* Event list */}
-    </div>
-  );
-}
-```
-
-## Network Issues
-
-### 1. API Request Failures
-
-**Problem**: API requests are failing with network errors.
-
-**Solution**:
-
-```typescript
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function NetworkAwareComponent() {
-  const { error } = useUnifiedAuth();
-
-  useEffect(() => {
-    if (error) {
-      console.error('Network error:', error);
-      
-      // Check if it's a network issue
-      if (error.message.includes('network') || error.message.includes('fetch')) {
-        console.log('Network connectivity issue detected');
-        // Implement retry logic or show offline message
-      }
-    }
-  }, [error]);
-
-  return (
-    <div>
-      {error && (
-        <div className="error">
-          <p>Connection error: {error.message}</p>
-          <button onClick={() => window.location.reload()}>
-            Retry
-          </button>
-        </div>
-      )}
-    </div>
-  );
+const testConnection = async () => {
+  const { data, error } = await supabase
+    .from('organisations')
+    .select('id')
+    .limit(1)
+  
+  console.log('Connection test:', { data, error })
 }
 ```
 
-### 2. CORS Issues
-
-**Problem**: Getting CORS errors when making requests.
-
-**Solution**:
-
-```typescript
-// Check Supabase configuration
-const supabase = createSupabaseClient(
-  process.env.SUPABASE_URL!,
-  process.env.SUPABASE_ANON_KEY!,
-  {
-    auth: {
-      autoRefreshToken: true,
-      persistSession: true,
-      detectSessionInUrl: true,
-    },
-  }
-);
-```
-
-## Environment Issues
-
-### 1. Environment Variables Missing
-
-**Problem**: Application is failing due to missing environment variables.
-
-**Solution**:
-
-```typescript
-// Validate environment variables
-const requiredEnvVars = [
-  'SUPABASE_URL',
-  'SUPABASE_ANON_KEY',
-  'NODE_ENV',
-];
-
-requiredEnvVars.forEach(varName => {
-  if (!process.env[varName]) {
-    console.error(`Missing environment variable: ${varName}`);
-    throw new Error(`Missing required environment variable: ${varName}`);
-  }
-});
-
-console.log('Environment variables validated');
-```
-
-### 2. Development vs Production Issues
-
-**Problem**: Application works in development but not in production.
-
-**Solution**:
-
-```typescript
-// Environment-specific configuration
-const config = {
-  development: {
-    supabaseUrl: process.env.SUPABASE_URL,
-    supabaseKey: process.env.SUPABASE_ANON_KEY,
-    debug: true,
-  },
-  production: {
-    supabaseUrl: process.env.SUPABASE_URL,
-    supabaseKey: process.env.SUPABASE_ANON_KEY,
-    debug: false,
-  },
-};
-
-const currentConfig = config[process.env.NODE_ENV || 'development'];
-```
-
-## Debugging Tools
-
-### 1. Debug Component
+### 3. Check Provider Context
 
 ```typescript
-function DebugPanel() {
-  const { user, session } = useUnifiedAuth();
-  const { currentOrganisation } = useOrganisation();
-  const { events, selectedEvent } = useEvents();
+import { useUnifiedAuth } from '@jmruthers/pace-core'
 
-  return (
-    <div className="debug-panel">
-      <h3>Debug Information</h3>
-      <pre>
-        {JSON.stringify({
-          user: user?.email,
-          session: session?.expires_at,
-          organisation: currentOrganisation?.name,
-          events: events?.length,
-          selectedEvent: selectedEvent?.name,
-        }, null, 2)}
-      </pre>
-    </div>
-  );
+function DebugComponent() {
+  const auth = useUnifiedAuth()
+  console.log('Auth context:', auth)
+  return <div>Check console for auth context</div>
 }
 ```
 
-### 2. Error Boundary with Logging
+### 4. Verify RBAC Setup
 
 ```typescript
-import { ErrorBoundary } from '@jmruthers/pace-core';
+import { useRBAC } from '@jmruthers/pace-core'
 
-function LoggingErrorBoundary({ children }) {
-  return (
-    <ErrorBoundary
-      fallback={<div>Something went wrong</div>}
-      onError={(error, errorInfo) => {
-        console.error('Error caught by boundary:', error);
-        console.error('Error info:', errorInfo);
-        
-        // Send to error reporting service
-        // reportError(error, errorInfo);
-      }}
-    >
-      {children}
-    </ErrorBoundary>
-  );
+function DebugRBAC() {
+  const rbac = useRBAC()
+  console.log('RBAC context:', rbac)
+  return <div>Check console for RBAC context</div>
 }
 ```
 
-## 🌐 Public Pages Issues
-
-### Public Pages Not Working
-
-**Problem**: Public pages show authentication errors or don't load properly
-
-**Root Cause**: Public pages are being rendered inside the authentication context
-
-**Solution**: Public pages MUST be completely separate from your main app
-
-```tsx
-// ❌ WRONG - This will break
-<UnifiedAuthProvider>
-  <Routes>
-    <Route path="/events/:eventCode" element={<PublicPage />} />
-  </Routes>
-</UnifiedAuthProvider>
-
-// ✅ CORRECT - Separate applications
-<BrowserRouter>
-  <Routes>
-    <Route path="/events/*" element={<PublicPageApp />} />
-    <Route path="/*" element={
-      <UnifiedAuthProvider>
-        <AuthenticatedApp />
-      </UnifiedAuthProvider>
-    } />
-  </Routes>
-</BrowserRouter>
-```
-
-**Complete Setup:**
-```tsx
-// PublicPageApp.tsx
-import { PublicPageProvider } from '@jmruthers/pace-core';
-
-export function PublicPageApp() {
-  return (
-    <PublicPageProvider>
-      <Routes>
-        <Route path="/events/:eventCode" element={<PublicEventPage />} />
-      </Routes>
-    </PublicPageProvider>
-  );
-}
-```
-
-### Public Page Hooks Not Working
-
-**Problem**: `usePublicEvent` or `usePublicRouteParams` return null/undefined
-
-**Root Cause**: Not using the hooks inside `PublicPageProvider`
-
-**Solution**: Ensure all public page components are wrapped in `PublicPageProvider`
-
-```tsx
-// ❌ WRONG - Hooks won't work
-function PublicPage() {
-  const { eventCode } = usePublicRouteParams(); // Returns null
-  // ...
-}
-
-// ✅ CORRECT - Hooks work properly
-<PublicPageProvider>
-  <PublicPage /> {/* Hooks work here */}
-</PublicPageProvider>
-```
-
-### Public Page Loading Forever
-
-**Problem**: Public pages show loading spinner indefinitely
-
-**Root Cause**: Event data not found or API errors
-
-**Solution**: Add proper error handling and fallbacks
-
-```tsx
-function PublicEventPage() {
-  const { eventCode } = usePublicRouteParams({ fetchEventData: false });
-  const { event, isLoading, error, refetch } = usePublicEvent(eventCode || '');
-  
-  // Handle loading
-  if (isLoading) {
-    return <PublicLoadingSpinner message="Loading event..." />;
-  }
-  
-  // Handle error
-  if (error) {
-    return (
-      <div className="min-h-screen bg-white flex items-center justify-center">
-        <div className="text-center">
-          <h1 className="text-2xl font-bold text-gray-900 mb-4">
-            Event Not Found
-          </h1>
-          <p className="text-gray-600 mb-6">
-            The event code "{eventCode}" is invalid or not available for public viewing.
-          </p>
-          <button
-            onClick={refetch}
-            className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
-          >
-            Try Again
-          </button>
-        </div>
-      </div>
-    );
-  }
-  
-  // Handle missing event
-  if (!event) {
-    return <div>Event not found</div>;
-  }
-  
-  // Render the page
-  return (
-    <PublicPageLayout eventCode={eventCode || ''} event={event}>
-      {/* Your content */}
-    </PublicPageLayout>
-  );
-}
-```
-
-### Public Page Styling Issues
-
-**Problem**: Public pages appear unstyled or broken
-
-**Root Cause**: Missing CSS import or Tailwind configuration
-
-**Solution**: Ensure CSS is imported and Tailwind is configured
-
-```tsx
-// Make sure to import CSS
-import '@jmruthers/pace-core/styles/core.css';
-
-// And configure Tailwind properly
-// vite.config.ts
-import tailwindcss from '@tailwindcss/vite'
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-### Public Page Environment Variables
-
-**Problem**: Public pages can't access Supabase or environment variables
-
-**Root Cause**: Missing environment variables or incorrect configuration
-
-**Solution**: Set up environment variables and pass them to `PublicPageProvider`
-
-```tsx
-// .env.local
-VITE_SUPABASE_URL=your_supabase_url
-VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
-VITE_APP_NAME=Your App Name
-
-// PublicPageApp.tsx
-import { PublicPageProvider } from '@jmruthers/pace-core';
-
-export function PublicPageApp() {
-  return (
-    <PublicPageProvider
-      environment={{
-        supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
-        supabaseKey: import.meta.env.VITE_SUPABASE_ANON_KEY,
-      }}
-    >
-      <Routes>
-        <Route path="/events/:eventCode" element={<PublicEventPage />} />
-      </Routes>
-    </PublicPageProvider>
-  );
-}
-```
-
-### Public Page "process is not defined" Error
-
-**Problem**: `ReferenceError: process is not defined` when using `PublicPageProvider` in Vite-based applications
-
-**Root Cause**: The component is trying to access Node.js globals (`process`) that aren't available in browser environments
-
-**Solution**: This has been fixed in pace-core v0.4.61+. The `PublicPageProvider` now safely handles both browser and Node.js environments.
-
-**If you're still seeing this error:**
-
-1. **Update pace-core** to the latest version:
-   ```bash
-   npm update @jmruthers/pace-core
-   ```
-
-2. **Verify your Vite configuration** includes environment variable support:
-   ```ts
-   // vite.config.ts
-   export default defineConfig({
-     plugins: [react(), tailwindcss()],
-     envDir: '.', // Look for .env files in root
-     envPrefix: 'VITE_', // Only load VITE_ prefixed variables
-   })
-   ```
-
-3. **Set up environment variables** in your `.env` file:
-   ```bash
-   # .env.local
-   VITE_SUPABASE_URL=your_supabase_url
-   VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
-   ```
-
-4. **Use the correct environment variable names**:
-   - ✅ `VITE_SUPABASE_URL` (Vite)
-   - ✅ `NEXT_PUBLIC_SUPABASE_URL` (Next.js)
-   - ❌ `SUPABASE_URL` (not prefixed for Vite)
-
-**The fix ensures:**
-- ✅ Safe access to `import.meta.env` (Vite/browser)
-- ✅ Safe access to `process.env` (Node.js/server)
-- ✅ Proper fallback handling
-- ✅ No "process is not defined" errors
-
-### Public Page Database Access
-
-**Problem**: Public pages can't access event data from database
-
-**Root Cause**: Missing RLS policies or incorrect database setup
-
-**Solution**: Set up proper RLS policies for public access
-
-```sql
--- Enable RLS on events table
-ALTER TABLE events ENABLE ROW LEVEL SECURITY;
-
--- Create policy for public events
-CREATE POLICY "Public events are viewable by anyone" ON events
-  FOR SELECT USING (is_public = true);
-
--- Or allow specific event codes
-CREATE POLICY "Specific event codes are public" ON events
-  FOR SELECT USING (event_code IN ('EVENT123', 'EVENT456'));
-```
-
-## Getting Help
-
-If you're still experiencing issues:
-
-1. **Check the console** for error messages
-2. **Verify your configuration** (environment variables, Supabase setup)
-3. **Test with minimal setup** to isolate the issue
-4. **Check the documentation** for specific component usage
-5. **Search existing issues** in the GitHub repository
-6. **Create a new issue** with detailed information about your problem
+## 🆘 **Still Having Issues?**
 
-When reporting an issue, include:
+If you're still experiencing problems after following this guide:
 
-- **Environment**: Node.js version, package versions
-- **Steps to reproduce**: Clear steps to recreate the issue
-- **Expected behavior**: What you expected to happen
-- **Actual behavior**: What actually happened
-- **Error messages**: Full error messages from console
-- **Code example**: Minimal code that reproduces the issue
+1. **Check the browser console** for detailed error messages
+2. **Verify your Supabase project** has the pace-core schema
+3. **Ensure you're using the correct API key** (anon, not service role)
+4. **Test with a minimal setup** to isolate the issue
 
-For more specific troubleshooting, see the [Debugging Guide](./debugging.md). 
+The most common issue is using the **service role key** instead of the **anon key**. The service role key bypasses RLS policies and can cause unexpected behavior with RPC calls.