@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/rbac/quick-start.md

@@ -1,7 +1,5 @@
 # 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
@@ -9,16 +7,8 @@ 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
-- 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)
+- Server-side permission validation
+- Caching and performance optimization
 
 ## 🚀 Step-by-Step Implementation
 
@@ -33,40 +23,31 @@ cd user-manager
 
 ### 2. Install Dependencies
 
-**CRITICAL**: Use the exact versions specified to avoid compatibility issues.
-
 ```bash
-npm install @jmruthers/pace-core@^0.4.1 @supabase/supabase-js@^2.38.0
+npm install @jmruthers/pace-core @supabase/supabase-js
 npm install -D tailwindcss @types/react @types/react-dom
 ```
 
-### 3. Configure Tailwind CSS v4
+### 3. Configure Tailwind CSS
 
-Install Tailwind CSS v4:
 ```bash
-npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+npx tailwindcss init
 ```
 
-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}'
-      ]
-    })
+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}',
   ],
-})
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
 ```
 
 ### 4. Set Up Environment Variables
@@ -74,546 +55,389 @@ export default defineConfig({
 Create `.env.local`:
 
 ```bash
-# .env.local
-VITE_SUPABASE_URL=https://your-project.supabase.co
-VITE_SUPABASE_ANON_KEY=your-anon-key-here
-VITE_APP_NAME=user-manager
+REACT_APP_SUPABASE_URL=https://your-project.supabase.co
+REACT_APP_SUPABASE_ANON_KEY=your-anon-key-here
 ```
 
-**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`:
+### 5. Create Supabase Client
 
 ```typescript
 // src/lib/supabase.ts
 import { createClient } from '@supabase/supabase-js'
 
-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')
-}
+const supabaseUrl = process.env.REACT_APP_SUPABASE_URL!
+const supabaseAnonKey = process.env.REACT_APP_SUPABASE_ANON_KEY!
 
 export const supabase = createClient(supabaseUrl, supabaseAnonKey)
 ```
 
-### 8. App Setup (CRITICAL)
+### 6. Set Up App Structure
 
-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'
+```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';
 import { 
   UnifiedAuthProvider, 
-  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')
-}
+  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';
 
-// CRITICAL: Set the app name globally for RBAC
-setRBACAppName(APP_NAME)
+// ⚠️ REQUIRED: Setup RBAC first
+setupRBAC(supabase);
 
 function App() {
   return (
     <UnifiedAuthProvider 
-      supabaseClient={supabase}
+      supabaseClient={supabase} 
+      appName="user-manager"
     >
       <OrganisationProvider>
-        <EventProvider>
-          <Router>
-            <Routes>
-              <Route path="/login" element={<Login />} />
-              <Route path="/" element={<Dashboard />} />
-              <Route path="/users" element={<Users />} />
-            </Routes>
-          </Router>
-        </EventProvider>
+        <Router>
+          <Routes>
+            <Route path="/login" element={<LoginPage />} />
+            <Route path="/" element={<AppLayout />}>
+              <Route index element={<DashboardPage />} />
+              <Route path="users" element={<UsersPage />} />
+            </Route>
+          </Routes>
+        </Router>
       </OrganisationProvider>
     </UnifiedAuthProvider>
-  )
+  );
 }
 
-export default App
+export default App;
 ```
 
-### 9. Create Login Page
+### 7. Create Login Page
 
-Create `src/pages/Login.tsx`:
+```tsx
+// src/components/LoginPage.tsx
+import { LoginForm } from '@jmruthers/pace-core';
+import { useNavigate } from 'react-router-dom';
 
-```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)
-    }
-  }
+export function LoginPage() {
+  const navigate = useNavigate();
+
+  const handleLoginSuccess = () => {
+    navigate('/');
+  };
 
   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 your account
+            Sign in to User Manager
           </h2>
         </div>
-        <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>
+        <LoginForm onLoginSuccess={handleLoginSuccess} />
       </div>
     </div>
-  )
+  );
 }
 ```
 
-### 10. Create Dashboard Page
+### 8. Create App Layout
 
-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>
+```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'
   }
+];
 
+export function AppLayout() {
   return (
-    <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>
-  )
+    <PaceAppLayout 
+      appName="User Manager"
+      navItems={navItems}
+    >
+      <Outlet />
+    </PaceAppLayout>
+  );
 }
 ```
 
-### 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>
-  }
+### 9. Create Dashboard Page
 
+```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="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 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>
-      </main>
+      </PermissionEnforcer>
     </div>
-  )
+  );
 }
-```
-
-## 🧪 Test Your Setup
-
-1. **Start your development server**:
-   ```bash
-   npm run dev
-   ```
-
-2. **Navigate to your app** (usually `http://localhost:3000` or `http://localhost:5173`)
-
-3. **You should see the login page**
-
-4. **Log in with a user that has the `org_admin` role**
-
-5. **You should be redirected to the dashboard**
-
-6. **Click "View Users" - you should see the users page**
-
-7. **If you see "You don't have permission" messages, check the troubleshooting section below**
 
-## 🎉 Success Checklist
-
-Your RBAC setup is working correctly if:
-
-- [ ] 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
-
-## 🚨 Troubleshooting
-
-### Issue: "Access Denied" on all pages
+// 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>
+  );
+}
+```
 
-**Check these in order:**
+### 10. Create Users Page with Permission Guards
 
-1. **Verify your app is registered**:
-   ```sql
-   SELECT * FROM rbac_apps WHERE name = 'user-manager';
-   ```
+```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;
+}
 
-2. **Check your environment variable**:
-   ```typescript
-   console.log('App name:', import.meta.env.VITE_APP_NAME);
-   ```
+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();
 
-3. **Verify user has roles**:
-   ```sql
-   SELECT * FROM rbac_organisation_roles WHERE user_id = 'your-user-id';
-   ```
+  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>
+  );
+}
 
-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';
-   ```
+// Pattern 2: useCan for specific permission checks
+function DeleteActions({ userId, organisationId }) {
+  const { can, isLoading, error } = useCan(
+    userId || '',
+    { organisationId: organisationId || '' },
+    'delete:users'
+  );
 
-### Issue: 400/406 Database Errors
+  if (isLoading) return <div>Checking permissions...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!can) return null;
 
-**This means your app is making incorrect database queries. Check:**
+  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>
+  );
+}
+```
 
-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)
+## 🎉 You're Done!
 
-### Issue: "App not found or inactive"
+Your app now has:
+- ✅ User authentication with Supabase
+- ✅ Role-based access control
+- ✅ Permission-based UI rendering
+- ✅ Component-level access control
+- ✅ Modern UI components
 
-**Check:**
+## 🚀 Next Steps
 
-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**
+- **[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
 
-### Issue: Components not rendering
+## 🔧 Customization
 
-**Check:**
+### Add More Permissions
 
-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**
+```tsx
+// Check multiple permissions
+const { hasPermission } = useCan();
 
-## 🏢 App Context Requirements
+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 }),
+]);
 
-Your app is configured as an **organisation-based app** by default. This means:
+const [canRead, canCreate, canUpdate, canDelete] = permissions;
+```
 
-- ✅ Requires `organisationId` in permission scope
-- ✅ Works with organisation-level permissions
-- ✅ Automatically enforces organisation context
+### Add Access Level Checks
 
-### Switching to Event-Based App
+```tsx
+import { useAccessLevel, AccessLevelGuard } from '@jmruthers/pace-core';
 
-If you want to create an event-based app instead:
+function AdminPanel() {
+  const { accessLevel, isLoading } = useAccessLevel({
+    userId: 'current-user-id',
+    scope: { organisationId: 'current-org-id' }
+  });
 
-1. **Update Database**:
-```sql
-UPDATE rbac_apps 
-SET requires_event = true 
-WHERE name = 'user-manager';
+  return (
+    <AccessLevelGuard
+      userId="current-user-id"
+      scope={{ organisationId: "current-org-id" }}
+      requiredLevel="admin"
+    >
+      <div>Admin-only content</div>
+    </AccessLevelGuard>
+  );
+}
 ```
 
-2. **Update Frontend**:
+### Add Server-Side Validation
+
 ```tsx
-// Event-based app requires eventId instead of organisationId
-const scope = { eventId: selectedEventId, appId: 'user-manager' };
+// 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
+}
 ```
 
-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
+## 🆘 Need Help?
 
-This guide is designed to be foolproof - if you follow it exactly, your RBAC system will work correctly.
+- Check [Troubleshooting](./troubleshooting.md) for common issues
+- Review [Examples](./examples.md) for usage patterns
+- See [API Reference](./api-reference.md) for detailed documentation