@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/rbac/quick-start.md

@@ -1,5 +1,7 @@
 # RBAC Quick Start
 
+> **⚠️ CRITICAL**: This guide is designed to be impossible to get wrong. Follow every step exactly as written, and your RBAC system will work perfectly.
+
 Build your first RBAC-enabled application in under 10 minutes.
 
 ## 🎯 What We'll Build
@@ -7,8 +9,16 @@ Build your first RBAC-enabled application in under 10 minutes.
 A simple user management app that demonstrates:
 - Permission-based UI rendering
 - Component-level access control
-- Server-side permission validation
-- Caching and performance optimization
+- Proper app ID resolution (fixes "Access Denied" errors)
+- Correct provider setup (fixes 400/406 database errors)
+- App context requirements (organisation vs event-based)
+
+## 🚨 Critical Rules (Follow These or It Won't Work)
+
+1. **Never make direct database queries** to `rbac_apps`, `rbac_global_roles`, or other RBAC tables
+2. **Always use `PagePermissionGuard`** for page-level permissions (not manual permission checks)
+3. **Always set up providers correctly** in the exact order shown
+4. **Use the exact app name** from your environment variable (must match database exactly)
 
 ## 🚀 Step-by-Step Implementation
 
@@ -23,31 +33,40 @@ cd user-manager
 
 ### 2. Install Dependencies
 
+**CRITICAL**: Use the exact versions specified to avoid compatibility issues.
+
 ```bash
-npm install @jmruthers/pace-core @supabase/supabase-js
+npm install @jmruthers/pace-core@^0.4.1 @supabase/supabase-js@^2.38.0
 npm install -D tailwindcss @types/react @types/react-dom
 ```
 
-### 3. Configure Tailwind CSS
+### 3. Configure Tailwind CSS v4
 
+Install Tailwind CSS v4:
 ```bash
-npx tailwindcss init
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
 ```
 
-Update `tailwind.config.js`:
-
-```js
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
+Update `vite.config.ts`:
+
+```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({
+      // CRITICAL: Include pace-core components for scanning
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
   ],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
-}
+})
 ```
 
 ### 4. Set Up Environment Variables
@@ -55,389 +74,546 @@ module.exports = {
 Create `.env.local`:
 
 ```bash
-REACT_APP_SUPABASE_URL=https://your-project.supabase.co
-REACT_APP_SUPABASE_ANON_KEY=your-anon-key-here
+# .env.local
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key-here
+VITE_APP_NAME=user-manager
 ```
 
-### 5. Create Supabase Client
+**CRITICAL**: 
+- Use `VITE_` prefix for Vite projects
+- Use `NEXT_PUBLIC_` prefix for Next.js projects
+- The `VITE_APP_NAME` must match exactly what you have in the `rbac_apps` table
+
+### 5. Database Setup (CRITICAL)
+
+**CRITICAL**: Your app must be registered in the database before you can use RBAC.
+
+#### 5.1 Register Your App
+
+Run this SQL in your Supabase SQL editor:
+
+```sql
+-- Replace 'user-manager' with your actual app name (must match VITE_APP_NAME)
+INSERT INTO rbac_apps (name, display_name, requires_event, is_active) 
+VALUES ('user-manager', 'User Manager', false, true)
+ON CONFLICT (name) DO UPDATE SET
+  display_name = EXCLUDED.display_name,
+  requires_event = EXCLUDED.requires_event,
+  is_active = EXCLUDED.is_active;
+```
+
+#### 5.2 Create App Pages
+
+```sql
+-- Create pages for your app (replace 'user-manager' with your actual app name)
+INSERT INTO rbac_app_pages (app_id, page_name, page_description)
+SELECT 
+  a.id,
+  unnest(ARRAY['dashboard', 'users', 'settings', 'admin']),
+  unnest(ARRAY['Main Dashboard', 'User Management', 'App Settings', 'Admin Panel'])
+FROM rbac_apps a 
+WHERE a.name = 'user-manager';
+```
+
+#### 5.3 Set Up Page Permissions
+
+```sql
+-- Set up basic permissions for each page (replace 'user-manager' with your actual app name)
+WITH app_pages AS (
+  SELECT ap.id as page_id, ap.page_name, a.id as app_id
+  FROM rbac_app_pages ap
+  JOIN rbac_apps a ON ap.app_id = a.id
+  WHERE a.name = 'user-manager'
+)
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
+SELECT 
+  ap.page_id,
+  op.operation,
+  role.role_name,
+  CASE 
+    WHEN role.role_name = 'org_admin' THEN true
+    WHEN role.role_name = 'leader' AND ap.page_name != 'admin' THEN true
+    WHEN role.role_name = 'member' AND ap.page_name IN ('dashboard', 'users') THEN true
+    ELSE false
+  END,
+  '00000000-0000-0000-0000-000000000000'::uuid -- Replace with your organisation ID
+FROM app_pages ap
+CROSS JOIN (SELECT unnest(ARRAY['read', 'create', 'update', 'delete']) as operation) op
+CROSS JOIN (SELECT unnest(ARRAY['org_admin', 'leader', 'member']) as role_name) role;
+```
+
+#### 5.4 Assign User Roles
+
+```sql
+-- Grant a user the org_admin role (replace with actual user and organisation IDs)
+INSERT INTO rbac_organisation_roles (user_id, organisation_id, role, status, granted_at)
+VALUES (
+  'your-user-id'::uuid,
+  'your-organisation-id'::uuid,
+  'org_admin',
+  'active',
+  NOW()
+)
+ON CONFLICT (user_id, organisation_id) DO UPDATE SET
+  role = EXCLUDED.role,
+  status = EXCLUDED.status,
+  updated_at = NOW();
+```
+
+### 6. App Context Requirements
+
+The RBAC system supports two types of apps based on their context requirements:
+
+#### Organisation-Based App (Default)
+- **Context**: Requires `organisationId` in scope
+- **Use case**: User management, organisation settings, general dashboards
+- **Database**: `rbac_apps.requires_event = false`
+
+#### Event-Based App
+- **Context**: Requires `eventId` in scope, automatically resolves `organisationId` from event
+- **Use case**: Event registration, event management, event-specific reporting
+- **Database**: `rbac_apps.requires_event = true`
+
+### 7. Create Supabase Client
+
+Create `src/lib/supabase.ts`:
 
 ```typescript
 // src/lib/supabase.ts
 import { createClient } from '@supabase/supabase-js'
 
-const supabaseUrl = process.env.REACT_APP_SUPABASE_URL!
-const supabaseAnonKey = process.env.REACT_APP_SUPABASE_ANON_KEY!
+const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
+const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
+
+if (!supabaseUrl || !supabaseAnonKey) {
+  throw new Error('Missing Supabase environment variables')
+}
 
 export const supabase = createClient(supabaseUrl, supabaseAnonKey)
 ```
 
-### 6. Set Up App Structure
+### 8. App Setup (CRITICAL)
 
-```tsx
-// src/App.tsx - COMPLETE setup
-import React from 'react';
-import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
-import { setupRBAC } from '@jmruthers/pace-core/rbac';
+Create `src/App.tsx` with this EXACT structure:
+
+```typescript
+// src/App.tsx
+import React from 'react'
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
 import { 
   UnifiedAuthProvider, 
-  OrganisationProvider 
-} from '@jmruthers/pace-core';
-import { supabase } from './lib/supabase';
-import { AppLayout } from './components/AppLayout';
-import { LoginPage } from './components/LoginPage';
-import { DashboardPage } from './components/DashboardPage';
-import { UsersPage } from './components/UsersPage';
+  OrganisationProvider,
+  EventProvider 
+} from '@jmruthers/pace-core/providers'
+import { setRBACAppName } from '@jmruthers/pace-core/utils'
+import { supabase } from './lib/supabase'
+import { Dashboard } from './pages/Dashboard'
+import { Users } from './pages/Users'
+import { Login } from './pages/Login'
+
+// CRITICAL: Set the app name for RBAC resolution
+const APP_NAME = import.meta.env.VITE_APP_NAME
+
+if (!APP_NAME) {
+  throw new Error('VITE_APP_NAME environment variable is required')
+}
 
-// ⚠️ REQUIRED: Setup RBAC first
-setupRBAC(supabase);
+// CRITICAL: Set the app name globally for RBAC
+setRBACAppName(APP_NAME)
 
 function App() {
   return (
     <UnifiedAuthProvider 
-      supabaseClient={supabase} 
-      appName="user-manager"
+      supabaseClient={supabase}
     >
       <OrganisationProvider>
-        <Router>
-          <Routes>
-            <Route path="/login" element={<LoginPage />} />
-            <Route path="/" element={<AppLayout />}>
-              <Route index element={<DashboardPage />} />
-              <Route path="users" element={<UsersPage />} />
-            </Route>
-          </Routes>
-        </Router>
+        <EventProvider>
+          <Router>
+            <Routes>
+              <Route path="/login" element={<Login />} />
+              <Route path="/" element={<Dashboard />} />
+              <Route path="/users" element={<Users />} />
+            </Routes>
+          </Router>
+        </EventProvider>
       </OrganisationProvider>
     </UnifiedAuthProvider>
-  );
+  )
 }
 
-export default App;
+export default App
 ```
 
-### 7. Create Login Page
-
-```tsx
-// src/components/LoginPage.tsx
-import { LoginForm } from '@jmruthers/pace-core';
-import { useNavigate } from 'react-router-dom';
+### 9. Create Login Page
 
-export function LoginPage() {
-  const navigate = useNavigate();
+Create `src/pages/Login.tsx`:
 
-  const handleLoginSuccess = () => {
-    navigate('/');
-  };
+```typescript
+// src/pages/Login.tsx
+import React, { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { supabase } from '../lib/supabase'
+
+export function Login() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [loading, setLoading] = useState(false)
+  const navigate = useNavigate()
+
+  const handleLogin = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setLoading(true)
+
+    try {
+      const { data, error } = await supabase.auth.signInWithPassword({
+        email,
+        password
+      })
+
+      if (error) {
+        alert('Login failed: ' + error.message)
+        return
+      }
+
+      if (data.user) {
+        navigate('/')
+      }
+    } catch (error) {
+      alert('Login failed: ' + (error as Error).message)
+    } finally {
+      setLoading(false)
+    }
+  }
 
   return (
     <div className="min-h-screen flex items-center justify-center bg-gray-50">
       <div className="max-w-md w-full space-y-8">
         <div>
           <h2 className="mt-6 text-center text-3xl font-extrabold text-gray-900">
-            Sign in to User Manager
+            Sign in to your account
           </h2>
         </div>
-        <LoginForm onLoginSuccess={handleLoginSuccess} />
+        <form className="mt-8 space-y-6" onSubmit={handleLogin}>
+          <div>
+            <label htmlFor="email" className="sr-only">
+              Email address
+            </label>
+            <input
+              id="email"
+              name="email"
+              type="email"
+              required
+              className="appearance-none rounded-md relative block w-full px-3 py-2 border border-gray-300 placeholder-gray-500 text-gray-900 focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 focus:z-10 sm:text-sm"
+              placeholder="Email address"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+            />
+          </div>
+          <div>
+            <label htmlFor="password" className="sr-only">
+              Password
+            </label>
+            <input
+              id="password"
+              name="password"
+              type="password"
+              required
+              className="appearance-none rounded-md relative block w-full px-3 py-2 border border-gray-300 placeholder-gray-500 text-gray-900 focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 focus:z-10 sm:text-sm"
+              placeholder="Password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+            />
+          </div>
+          <div>
+            <button
+              type="submit"
+              disabled={loading}
+              className="group relative w-full flex justify-center py-2 px-4 border border-transparent text-sm font-medium rounded-md text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 disabled:opacity-50"
+            >
+              {loading ? 'Signing in...' : 'Sign in'}
+            </button>
+          </div>
+        </form>
       </div>
     </div>
-  );
+  )
 }
 ```
 
-### 8. Create App Layout
+### 10. Create Dashboard Page
 
-```tsx
-// src/components/AppLayout.tsx
-import { PaceAppLayout } from '@jmruthers/pace-core';
-import { Outlet } from 'react-router-dom';
-
-const navItems = [
-  {
-    title: 'Dashboard',
-    href: '/',
-    icon: 'HomeIcon'
-  },
-  {
-    title: 'Users',
-    href: '/users',
-    icon: 'UsersIcon'
+Create `src/pages/Dashboard.tsx`:
+
+```typescript
+// src/pages/Dashboard.tsx
+import React from 'react'
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers'
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac'
+import { Link } from 'react-router-dom'
+import { supabase } from '../lib/supabase'
+
+export function Dashboard() {
+  const { user, selectedOrganisationId } = useUnifiedAuth()
+
+  if (!user) {
+    return <div>Please log in</div>
   }
-];
 
-export function AppLayout() {
   return (
-    <PaceAppLayout 
-      appName="User Manager"
-      navItems={navItems}
-    >
-      <Outlet />
-    </PaceAppLayout>
-  );
+    <div className="min-h-screen bg-gray-50">
+      <nav className="bg-white shadow">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="flex justify-between h-16">
+            <div className="flex items-center">
+              <h1 className="text-xl font-semibold">Dashboard</h1>
+            </div>
+            <div className="flex items-center space-x-4">
+              <span className="text-sm text-gray-700">
+                {user.email} | Org: {selectedOrganisationId}
+              </span>
+              <button
+                onClick={() => supabase.auth.signOut()}
+                className="text-sm text-gray-500 hover:text-gray-700"
+              >
+                Sign out
+              </button>
+            </div>
+          </div>
+        </div>
+      </nav>
+
+      <main className="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
+        <div className="px-4 py-6 sm:px-0">
+          <div className="border-4 border-dashed border-gray-200 rounded-lg h-96 p-8">
+            <h2 className="text-2xl font-bold mb-4">Welcome to your Dashboard</h2>
+            
+            {/* CRITICAL: Use PagePermissionGuard for page-level permissions */}
+            <PagePermissionGuard
+              pageName="dashboard"
+              operation="read"
+              fallback={<div>You don't have permission to view the dashboard</div>}
+            >
+              <div className="space-y-4">
+                <p>You have access to the dashboard!</p>
+                
+                <div className="space-x-4">
+                  <Link 
+                    to="/users" 
+                    className="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600"
+                  >
+                    View Users
+                  </Link>
+                </div>
+              </div>
+            </PagePermissionGuard>
+          </div>
+        </div>
+      </main>
+    </div>
+  )
 }
 ```
 
-### 9. Create Dashboard Page
+### 11. Create Users Page
+
+Create `src/pages/Users.tsx`:
+
+```typescript
+// src/pages/Users.tsx
+import React from 'react'
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers'
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac'
+import { Link } from 'react-router-dom'
+import { supabase } from '../lib/supabase'
+
+export function Users() {
+  const { user, selectedOrganisationId } = useUnifiedAuth()
+
+  if (!user) {
+    return <div>Please log in</div>
+  }
 
-```tsx
-// src/components/DashboardPage.tsx
-import { Card, CardHeader, CardTitle, CardContent } from '@jmruthers/pace-core';
-import { PermissionEnforcer, useCan } from '@jmruthers/pace-core/rbac';
-import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
-
-export function DashboardPage() {
-  const { user, selectedOrganisationId } = useUnifiedAuth();
-  
-  // Pattern 1: PermissionEnforcer for automatic scope resolution
   return (
-    <div className="p-6">
-      <h1 className="text-2xl font-bold mb-6">Dashboard</h1>
-      
-      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
-        <Card>
-          <CardHeader>
-            <CardTitle>Total Users</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <p className="text-3xl font-bold">24</p>
-          </CardContent>
-        </Card>
-        
-        <Card>
-          <CardHeader>
-            <CardTitle>Active Sessions</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <p className="text-3xl font-bold">12</p>
-          </CardContent>
-        </Card>
-        
-        <Card>
-          <CardHeader>
-            <CardTitle>Permissions</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <PermissionStatus userId={user?.id} organisationId={selectedOrganisationId} />
-          </CardContent>
-        </Card>
-      </div>
-      
-      {/* Pattern 1: PermissionEnforcer - automatic scope resolution */}
-      <PermissionEnforcer
-        permissions={['manage:users']}
-        operation="user-management"
-        fallback={<div>You need user management permissions</div>}
-      >
-        <div className="mt-6">
-          <h2 className="text-lg font-semibold mb-4">User Management</h2>
-          <p>You have user management permissions!</p>
+    <div className="min-h-screen bg-gray-50">
+      <nav className="bg-white shadow">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="flex justify-between h-16">
+            <div className="flex items-center">
+              <Link to="/" className="text-blue-600 hover:text-blue-800 mr-4">
+                ← Back to Dashboard
+              </Link>
+              <h1 className="text-xl font-semibold">Users</h1>
+            </div>
+            <div className="flex items-center space-x-4">
+              <span className="text-sm text-gray-700">
+                {user.email} | Org: {selectedOrganisationId}
+              </span>
+              <button
+                onClick={() => supabase.auth.signOut()}
+                className="text-sm text-gray-500 hover:text-gray-700"
+              >
+                Sign out
+              </button>
+            </div>
+          </div>
+        </div>
+      </nav>
+
+      <main className="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
+        <div className="px-4 py-6 sm:px-0">
+          <div className="border-4 border-dashed border-gray-200 rounded-lg h-96 p-8">
+            <h2 className="text-2xl font-bold mb-4">User Management</h2>
+            
+            {/* CRITICAL: Use PagePermissionGuard for page-level permissions */}
+            <PagePermissionGuard
+              pageName="users"
+              operation="read"
+              fallback={<div>You don't have permission to view users</div>}
+            >
+              <div className="space-y-4">
+                <p>You have access to the users page!</p>
+                <p>This means your RBAC system is working correctly.</p>
+                
+                <div className="bg-green-100 border border-green-400 text-green-700 px-4 py-3 rounded">
+                  <strong>Success!</strong> Your RBAC setup is working correctly.
+                </div>
+              </div>
+            </PagePermissionGuard>
+          </div>
         </div>
-      </PermissionEnforcer>
+      </main>
     </div>
-  );
-}
-
-// Pattern 2: useCan for specific permission checks
-function PermissionStatus({ userId, organisationId }) {
-  const { can, isLoading, error } = useCan(
-    userId || '',
-    { organisationId: organisationId || '' },
-    'manage:users'
-  );
-
-  if (isLoading) return <p className="text-3xl font-bold">Loading...</p>;
-  if (error) return <p className="text-3xl font-bold text-red-500">Error</p>;
-  
-  return (
-    <p className="text-3xl font-bold">
-      {can ? 'Admin' : 'User'}
-    </p>
-  );
+  )
 }
 ```
 
-### 10. Create Users Page with Permission Guards
+## 🧪 Test Your Setup
 
-```tsx
-// src/components/UsersPage.tsx
-import { DataTable } from '@jmruthers/pace-core';
-import { PermissionEnforcer, useCan } from '@jmruthers/pace-core/rbac';
-import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
-import { useState } from 'react';
-
-interface User {
-  id: string;
-  name: string;
-  email: string;
-  role: string;
-  lastLogin: string;
-}
+1. **Start your development server**:
+   ```bash
+   npm run dev
+   ```
 
-const sampleUsers: User[] = [
-  { id: '1', name: 'John Doe', email: 'john@example.com', role: 'admin', lastLogin: '2024-01-15' },
-  { id: '2', name: 'Jane Smith', email: 'jane@example.com', role: 'user', lastLogin: '2024-01-14' },
-  { id: '3', name: 'Bob Johnson', email: 'bob@example.com', role: 'user', lastLogin: '2024-01-13' },
-];
-
-const columns = [
-  {
-    accessorKey: 'name',
-    header: 'Name',
-  },
-  {
-    accessorKey: 'email',
-    header: 'Email',
-  },
-  {
-    accessorKey: 'role',
-    header: 'Role',
-  },
-  {
-    accessorKey: 'lastLogin',
-    header: 'Last Login',
-  },
-];
-
-export function UsersPage() {
-  const [users] = useState<User[]>(sampleUsers);
-  const { user, selectedOrganisationId } = useUnifiedAuth();
+2. **Navigate to your app** (usually `http://localhost:3000` or `http://localhost:5173`)
 
-  return (
-    <div className="p-6">
-      <div className="flex justify-between items-center mb-6">
-        <h1 className="text-2xl font-bold">Users</h1>
-        
-        {/* Pattern 1: PermissionEnforcer - automatic scope resolution */}
-        <PermissionEnforcer
-          permissions={['create:users']}
-          operation="user-creation"
-          fallback={null} // Don't show anything if no permission
-        >
-          <button className="bg-blue-500 text-white px-4 py-2 rounded">
-            Add User
-          </button>
-        </PermissionEnforcer>
-      </div>
-      
-      <DataTable
-        data={users}
-        columns={columns}
-        features={{
-          search: true,
-          pagination: true,
-        }}
-      />
-      
-      {/* Pattern 2: useCan for specific permission checks */}
-      <DeleteActions userId={user?.id} organisationId={selectedOrganisationId} />
-    </div>
-  );
-}
+3. **You should see the login page**
 
-// Pattern 2: useCan for specific permission checks
-function DeleteActions({ userId, organisationId }) {
-  const { can, isLoading, error } = useCan(
-    userId || '',
-    { organisationId: organisationId || '' },
-    'delete:users'
-  );
+4. **Log in with a user that has the `org_admin` role**
 
-  if (isLoading) return <div>Checking permissions...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!can) return null;
+5. **You should be redirected to the dashboard**
 
-  return (
-    <div className="mt-4">
-      <h3 className="text-lg font-semibold mb-2">Admin Actions</h3>
-      <button className="bg-red-500 text-white px-4 py-2 rounded">
-        Delete Selected Users
-      </button>
-    </div>
-  );
-}
-```
+6. **Click "View Users" - you should see the users page**
 
-## 🎉 You're Done!
+7. **If you see "You don't have permission" messages, check the troubleshooting section below**
 
-Your app now has:
-- ✅ User authentication with Supabase
-- ✅ Role-based access control
-- ✅ Permission-based UI rendering
-- ✅ Component-level access control
-- ✅ Modern UI components
+## 🎉 Success Checklist
 
-## 🚀 Next Steps
+Your RBAC setup is working correctly if:
 
-- **[API Reference](./api-reference.md)** - Explore all available APIs
-- **[Examples](./examples.md)** - See more complex usage patterns
-- **[Advanced Patterns](./advanced-patterns.md)** - Learn optimization techniques
-- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
+- [ ] You can log in successfully
+- [ ] You see the dashboard without "Access Denied" messages
+- [ ] You can navigate to the users page
+- [ ] You see "Success! Your RBAC setup is working correctly" on the users page
+- [ ] No 400/406 errors in the browser console
+- [ ] No "App not found" errors in the console
 
-## 🔧 Customization
+## 🚨 Troubleshooting
 
-### Add More Permissions
+### Issue: "Access Denied" on all pages
 
-```tsx
-// Check multiple permissions
-const { hasPermission } = useCan();
+**Check these in order:**
 
-const permissions = await Promise.all([
-  hasPermission('read:users', { userId, scope }),
-  hasPermission('create:users', { userId, scope }),
-  hasPermission('update:users', { userId, scope }),
-  hasPermission('delete:users', { userId, scope }),
-]);
+1. **Verify your app is registered**:
+   ```sql
+   SELECT * FROM rbac_apps WHERE name = 'user-manager';
+   ```
 
-const [canRead, canCreate, canUpdate, canDelete] = permissions;
-```
+2. **Check your environment variable**:
+   ```typescript
+   console.log('App name:', import.meta.env.VITE_APP_NAME);
+   ```
 
-### Add Access Level Checks
+3. **Verify user has roles**:
+   ```sql
+   SELECT * FROM rbac_organisation_roles WHERE user_id = 'your-user-id';
+   ```
 
-```tsx
-import { useAccessLevel, AccessLevelGuard } from '@jmruthers/pace-core';
+4. **Check page permissions exist**:
+   ```sql
+   SELECT pp.*, ap.page_name, a.name as app_name
+   FROM rbac_page_permissions pp
+   JOIN rbac_app_pages ap ON pp.app_page_id = ap.id
+   JOIN rbac_apps a ON ap.app_id = a.id
+   WHERE a.name = 'user-manager';
+   ```
 
-function AdminPanel() {
-  const { accessLevel, isLoading } = useAccessLevel({
-    userId: 'current-user-id',
-    scope: { organisationId: 'current-org-id' }
-  });
+### Issue: 400/406 Database Errors
 
-  return (
-    <AccessLevelGuard
-      userId="current-user-id"
-      scope={{ organisationId: "current-org-id" }}
-      requiredLevel="admin"
-    >
-      <div>Admin-only content</div>
-    </AccessLevelGuard>
-  );
-}
-```
+**This means your app is making incorrect database queries. Check:**
+
+1. **You're using the providers correctly** (Step 8)
+2. **You're not making direct database queries to RBAC tables**
+3. **You're using the PagePermissionGuard component** (not manual permission checks)
+
+### Issue: "App not found or inactive"
+
+**Check:**
+
+1. **Your app name in the database matches your environment variable exactly**
+2. **Your app is marked as active** (`is_active = true`)
+3. **You're using the correct app name in the UnifiedAuthProvider**
+
+### Issue: Components not rendering
+
+**Check:**
+
+1. **You're using PagePermissionGuard (not manual permission checks)**
+2. **You're providing the correct pageName and operation**
+3. **The page exists in rbac_app_pages table**
+
+## 🏢 App Context Requirements
+
+Your app is configured as an **organisation-based app** by default. This means:
+
+- ✅ Requires `organisationId` in permission scope
+- ✅ Works with organisation-level permissions
+- ✅ Automatically enforces organisation context
 
-### Add Server-Side Validation
+### Switching to Event-Based App
 
+If you want to create an event-based app instead:
+
+1. **Update Database**:
+```sql
+UPDATE rbac_apps 
+SET requires_event = true 
+WHERE name = 'user-manager';
+```
+
+2. **Update Frontend**:
 ```tsx
-// API route example
-import { isPermitted } from '@jmruthers/pace-core';
-
-export async function POST(request: Request) {
-  const { userId, organisationId } = await request.json();
-  
-  const canCreate = await isPermitted({
-    userId,
-    scope: { organisationId },
-    permission: 'create:users'
-  });
-  
-  if (!canCreate) {
-    return Response.json({ error: 'Insufficient permissions' }, { status: 403 });
-  }
-  
-  // Proceed with user creation
-}
+// Event-based app requires eventId instead of organisationId
+const scope = { eventId: selectedEventId, appId: 'user-manager' };
 ```
 
-## 🆘 Need Help?
+3. **Automatic Organisation Resolution**:
+The system will automatically resolve the organisation ID from the event context.
+
+## 🚀 Next Steps
+
+- **[API Reference](./api-reference.md)** - Complete API documentation
+- **[Examples](./examples.md)** - More complex usage patterns
+- **[Troubleshooting](./troubleshooting.md)** - Advanced troubleshooting
+- **[Migration Guide](../migration/rbac-migration.md)** - If migrating from legacy RBAC
+
+## 🆘 Still Having Issues?
+
+If you're still having problems after following this guide exactly:
+
+1. **Check the browser console** for specific error messages
+2. **Verify your database setup** matches the SQL commands exactly
+3. **Make sure your environment variables** are set correctly
+4. **Check that your user has the correct roles** in the database
 
-- Check [Troubleshooting](./troubleshooting.md) for common issues
-- Review [Examples](./examples.md) for usage patterns
-- See [API Reference](./api-reference.md) for detailed documentation
+This guide is designed to be foolproof - if you follow it exactly, your RBAC system will work correctly.