@jmruthers/pace-core 0.5.108 → 0.5.110

package/docs/api/interfaces/UsePublicEventReturn.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.108](../README.md) / [Exports](../modules.md) / UsePublicEventReturn
+[@jmruthers/pace-core - v0.5.110](../README.md) / [Exports](../modules.md) / UsePublicEventReturn
 
 # Interface: UsePublicEventReturn
 

package/docs/api/interfaces/UsePublicFileDisplayOptions.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.108](../README.md) / [Exports](../modules.md) / UsePublicFileDisplayOptions
+[@jmruthers/pace-core - v0.5.110](../README.md) / [Exports](../modules.md) / UsePublicFileDisplayOptions
 
 # Interface: UsePublicFileDisplayOptions
 

package/docs/api/interfaces/UsePublicFileDisplayReturn.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.108](../README.md) / [Exports](../modules.md) / UsePublicFileDisplayReturn
+[@jmruthers/pace-core - v0.5.110](../README.md) / [Exports](../modules.md) / UsePublicFileDisplayReturn
 
 # Interface: UsePublicFileDisplayReturn
 

package/docs/api/interfaces/UsePublicRouteParamsReturn.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.108](../README.md) / [Exports](../modules.md) / UsePublicRouteParamsReturn
+[@jmruthers/pace-core - v0.5.110](../README.md) / [Exports](../modules.md) / UsePublicRouteParamsReturn
 
 # Interface: UsePublicRouteParamsReturn
 

package/docs/api/interfaces/UseResolvedScopeOptions.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.108](../README.md) / [Exports](../modules.md) / UseResolvedScopeOptions
+[@jmruthers/pace-core - v0.5.110](../README.md) / [Exports](../modules.md) / UseResolvedScopeOptions
 
 # Interface: UseResolvedScopeOptions
 

package/docs/api/interfaces/UseResolvedScopeReturn.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.108](../README.md) / [Exports](../modules.md) / UseResolvedScopeReturn
+[@jmruthers/pace-core - v0.5.110](../README.md) / [Exports](../modules.md) / UseResolvedScopeReturn
 
 # Interface: UseResolvedScopeReturn
 

package/docs/api/interfaces/UserEventAccess.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.108](../README.md) / [Exports](../modules.md) / UserEventAccess
+[@jmruthers/pace-core - v0.5.110](../README.md) / [Exports](../modules.md) / UserEventAccess
 
 # Interface: UserEventAccess
 

package/docs/api/interfaces/UserMenuProps.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.108](../README.md) / [Exports](../modules.md) / UserMenuProps
+[@jmruthers/pace-core - v0.5.110](../README.md) / [Exports](../modules.md) / UserMenuProps
 
 # Interface: UserMenuProps
 

package/docs/api/interfaces/UserProfile.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.108](../README.md) / [Exports](../modules.md) / UserProfile
+[@jmruthers/pace-core - v0.5.110](../README.md) / [Exports](../modules.md) / UserProfile
 
 # Interface: UserProfile
 

package/docs/api/modules.md

@@ -1,6 +1,6 @@
-[@jmruthers/pace-core - v0.5.108](README.md) / Exports
+[@jmruthers/pace-core - v0.5.110](README.md) / Exports
 
-# @jmruthers/pace-core - v0.5.108
+# @jmruthers/pace-core - v0.5.110
 
 **`File`**
 
@@ -371,6 +371,7 @@ import { Dialog, NavigationMenu } from '@jmruthers/pace-core/components';
 - [formatCompactNumber](modules.md#formatcompactnumber)
 - [formatFileSize](modules.md#formatfilesize)
 - [createSecureDataAccess](modules.md#createsecuredataaccess)
+- [useSessionTracking](modules.md#usesessiontracking)
 - [getFileSizeLimit](modules.md#getfilesizelimit)
 - [getBucketName](modules.md#getbucketname)
 - [validateFileSize](modules.md#validatefilesize)
@@ -498,7 +499,7 @@ ___
 
 #### Defined in
 
-[packages/core/src/rbac/config.ts:13](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L13)
+[packages/core/src/rbac/config.ts:14](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L14)
 
 ___
 
@@ -5026,7 +5027,7 @@ const accessLevel = await getAccessLevel({
 
 #### Defined in
 
-[packages/core/src/rbac/api.ts:88](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L88)
+[packages/core/src/rbac/api.ts:89](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L89)
 
 ___
 
@@ -5065,7 +5066,7 @@ const permissions = await getPermissionMap({
 
 #### Defined in
 
-[packages/core/src/rbac/api.ts:114](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L114)
+[packages/core/src/rbac/api.ts:115](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L115)
 
 ___
 
@@ -5087,7 +5088,7 @@ ___
 
 #### Defined in
 
-[packages/core/src/rbac/api.ts:122](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L122)
+[packages/core/src/rbac/api.ts:123](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L123)
 
 ___
 
@@ -5109,7 +5110,7 @@ ___
 
 #### Defined in
 
-[packages/core/src/rbac/api.ts:130](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L130)
+[packages/core/src/rbac/api.ts:131](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L131)
 
 ___
 
@@ -5144,7 +5145,7 @@ const canManage = await isPermitted({
 
 #### Defined in
 
-[packages/core/src/rbac/api.ts:154](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L154)
+[packages/core/src/rbac/api.ts:155](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L155)
 
 ___
 
@@ -5168,7 +5169,7 @@ Promise resolving to permission result
 
 #### Defined in
 
-[packages/core/src/rbac/api.ts:175](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L175)
+[packages/core/src/rbac/api.ts:176](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L176)
 
 ___
 
@@ -5192,7 +5193,7 @@ Promise<boolean> - True if user has permission
 
 #### Defined in
 
-[packages/core/src/rbac/api.ts:208](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L208)
+[packages/core/src/rbac/api.ts:209](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L209)
 
 ___
 
@@ -5220,7 +5221,7 @@ Promise resolving to true if user has any permission
 
 #### Defined in
 
-[packages/core/src/rbac/api.ts:218](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L218)
+[packages/core/src/rbac/api.ts:219](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L219)
 
 ___
 
@@ -5248,7 +5249,7 @@ Promise resolving to true if user has all permissions
 
 #### Defined in
 
-[packages/core/src/rbac/api.ts:246](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L246)
+[packages/core/src/rbac/api.ts:247](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/api.ts#L247)
 
 ___
 
@@ -5466,7 +5467,7 @@ React element with permission enforcement
 
 #### Defined in
 
-[packages/core/src/rbac/components/PagePermissionGuard.tsx:550](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/components/PagePermissionGuard.tsx#L550)
+[packages/core/src/rbac/components/PagePermissionGuard.tsx:533](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/components/PagePermissionGuard.tsx#L533)
 
 ___
 
@@ -5661,7 +5662,7 @@ ___
 
 #### Defined in
 
-[packages/core/src/rbac/config.ts:110](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L110)
+[packages/core/src/rbac/config.ts:112](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L112)
 
 ___
 
@@ -5675,7 +5676,7 @@ ___
 
 #### Defined in
 
-[packages/core/src/rbac/config.ts:115](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L115)
+[packages/core/src/rbac/config.ts:117](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L117)
 
 ___
 
@@ -5689,7 +5690,7 @@ ___
 
 #### Defined in
 
-[packages/core/src/rbac/config.ts:119](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L119)
+[packages/core/src/rbac/config.ts:121](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L121)
 
 ___
 
@@ -5703,7 +5704,7 @@ ___
 
 #### Defined in
 
-[packages/core/src/rbac/config.ts:123](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L123)
+[packages/core/src/rbac/config.ts:125](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L125)
 
 ___
 
@@ -5717,13 +5718,13 @@ ___
 
 #### Defined in
 
-[packages/core/src/rbac/config.ts:127](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L127)
+[packages/core/src/rbac/config.ts:129](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/config.ts#L129)
 
 ___
 
 ### createRBACEngine
 
-▸ **createRBACEngine**(`supabase`): [`RBACEngine`](classes/RBACEngine.md)
+▸ **createRBACEngine**(`supabase`, `securityConfig?`): [`RBACEngine`](classes/RBACEngine.md)
 
 Create an RBAC engine instance
 
@@ -5732,6 +5733,7 @@ Create an RBAC engine instance
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `supabase` | `default`\<`Database`, ``"public"``, ``"public"``, `never`, {}\> | Supabase client |
+| `securityConfig?` | `Partial`\<`RBACSecurityConfig`\> | Optional security configuration |
 
 #### Returns
 
@@ -5741,7 +5743,7 @@ RBACEngine instance
 
 #### Defined in
 
-[packages/core/src/rbac/engine.ts:592](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/engine.ts#L592)
+[packages/core/src/rbac/engine.ts:601](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/engine.ts#L601)
 
 ___
 
@@ -6705,6 +6707,39 @@ Secure data access utilities
 
 ___
 
+### useSessionTracking
+
+▸ **useSessionTracking**(`supabaseClient`, `appName?`): `Object`
+
+Hook for manual session tracking (event switches and session expiration).
+
+Note: Login and logout tracking is automatically handled by UnifiedAuthProvider.
+You should only use this hook for tracking event switches or session expirations.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `supabaseClient` | `default`\<`any`, ``"public"``, ``"public"``, `any`, `any`\> | Supabase client instance |
+| `appName?` | `string` | Optional application name for tracking |
+
+#### Returns
+
+`Object`
+
+Object containing tracking functions for event switches and session expiration
+
+| Name | Type |
+| :------ | :------ |
+| `trackEventSwitch` | (`eventId`: `string`) => `Promise`\<`void`\> |
+| `trackSessionExpired` | () => `Promise`\<`void`\> |
+
+#### Defined in
+
+[packages/core/src/utils/sessionTracking.ts:22](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/sessionTracking.ts#L22)
+
+___
+
 ### getFileSizeLimit
 
 ▸ **getFileSizeLimit**(`mimeType`): `number`

package/docs/api-reference/hooks.md

@@ -76,6 +76,59 @@ function App() {
 }
 ```
 
+> **Note**: Login and logout tracking is automatically handled by `UnifiedAuthProvider`. No manual intervention is required.
+
+### useSessionTracking
+
+Utility hook for manual session tracking of event switches and session expiration. **Note**: Login and logout are automatically tracked by `UnifiedAuthProvider`, so those methods are not available here.
+
+```typescript
+function useSessionTracking(
+  supabaseClient: SupabaseClient,
+  appName?: string
+): {
+  trackEventSwitch: (eventId: string) => Promise<void>;
+  trackSessionExpired: () => Promise<void>;
+}
+```
+
+#### Usage
+
+```tsx
+import { useSessionTracking } from '@jmruthers/pace-core';
+import { supabase } from './lib/supabase';
+
+function MyComponent() {
+  const { trackEventSwitch, trackSessionExpired } = useSessionTracking(
+    supabase,
+    'MY_APP'
+  );
+
+  const handleEventSwitch = async (eventId: string) => {
+    await trackEventSwitch(eventId);
+    // Event switch logic...
+  };
+
+  const handleSessionExpiration = async () => {
+    await trackSessionExpired();
+    // Session expiration logic...
+  };
+
+  return (
+    // Component JSX
+  );
+}
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `trackEventSwitch(eventId)` | Track when a user switches to a different event. |
+| `trackSessionExpired()` | Track when a session expires. |
+
+> **Automatic Tracking**: When using `UnifiedAuthProvider`, login and logout events are **automatically tracked**. You only need to use this hook for event switches or session expirations, which are not automatically tracked.
+
 
 ## Event Management Hooks
 

package/docs/api-reference/providers.md

@@ -206,6 +206,66 @@ The inactivity tracker monitors the following user interactions:
 - **Automatic cleanup**: All timers and listeners are properly cleaned up
 - **Error handling**: Graceful fallback if localStorage or BroadcastChannel fail
 
+#### Automatic Login History Tracking
+
+The `UnifiedAuthProvider` automatically tracks all user logins for security auditing and compliance:
+
+- **Automatic Tracking** - No manual intervention required, tracking happens automatically on login/logout
+- **Complete Audit Trail** - Records user ID, email, timestamp, IP address, user agent, and application context
+- **Database Storage** - All login events are stored in `rbac_user_login_history` table
+- **Application Context** - Tracks which application the user logged into (when `appName` is provided)
+- **Non-Blocking** - Tracking failures don't prevent authentication from succeeding
+- **Privacy Compliant** - Users can only view their own login history (RLS enforced)
+
+Login history is tracked automatically when you use `UnifiedAuthProvider`. No additional configuration is required:
+
+```tsx
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="MY_APP"  // Enables app-specific tracking in login history
+  // ... other props
+>
+  <AppContent />
+</UnifiedAuthProvider>
+```
+
+**What Gets Tracked:**
+
+- User ID and email
+- Login timestamp
+- Session ID
+- IP address (if available)
+- User agent string
+- Application ID (if `appName` is provided)
+- Organisation ID
+- Event ID (if applicable)
+
+**Querying Login History:**
+
+Login history can be queried directly from the database using RLS-protected queries:
+
+```sql
+-- Get user's login history
+SELECT 
+  login_timestamp,
+  email,
+  ip_address,
+  user_agent,
+  app_id,
+  event_id
+FROM rbac_user_login_history
+WHERE user_id = auth.uid()
+ORDER BY login_timestamp DESC
+LIMIT 100;
+```
+
+**Security Notes:**
+
+- Login history insertion uses `SECURITY DEFINER` functions (bypasses RLS)
+- RLS policies ensure users can only view their own login history
+- Failed tracking attempts are logged as warnings but don't break authentication
+- All tracking is asynchronous and non-blocking
+
 ## OrganisationProvider
 
 Manages multi-tenant organisation context and user organisation memberships. **Automatically sets database organisation context** to ensure RLS policies work correctly.

package/docs/core-concepts/authentication.md

@@ -77,6 +77,7 @@ sequenceDiagram
 - **Persistent State** - Authentication state persists across page reloads
 - **Multi-Tab Support** - Authentication state synchronized across tabs
 - **Graceful Degradation** - Handles network issues and token expiry
+- **Automatic Login History** - User login events are automatically tracked in `rbac_user_login_history` table
 
 ### Security Features
 
@@ -84,6 +85,7 @@ sequenceDiagram
 - **JWT Tokens** - Secure, stateless authentication
 - **CSRF Protection** - Cross-site request forgery prevention
 - **Audit Logging** - Complete action tracking for compliance
+- **Login History Tracking** - Automatic tracking of all user logins with timestamps, IP addresses, user agents, and application context
 
 ## Multi-Tenancy
 

package/docs/documentation-index.md

@@ -54,8 +54,6 @@ This index mirrors the folder layout in `packages/core/docs/` so teams can quick
 - [Advanced patterns](./rbac/advanced-patterns.md)
 - [Super admin guide](./rbac/super-admin-guide.md)
 - [RLS integration](./rbac/rbac-rls-integration.md)
-- [Migration guide](./rbac/migration-guide.md)
-- [Breaking changes v3](./rbac/breaking-changes-v3.md)
 - [Troubleshooting](./rbac/troubleshooting.md)
 - [Legacy RLS README](./rbac/README-rbac-rls-integration.md)
 

package/docs/implementation-guides/authentication.md

@@ -23,6 +23,7 @@ PACE Core provides a comprehensive authentication system built on Supabase that
 - **🔒 Session Persistence** - Secure session management with auto-refresh
 - **🎯 Permission Integration** - Built-in RBAC integration
 - **📊 Debug Support** - Comprehensive debugging and monitoring
+- **📝 Automatic Login History** - All user logins automatically tracked for audit trails
 
 ## Quick Start
 

package/docs/rbac/README.md

@@ -12,10 +12,35 @@ The PACE Core RBAC (Role-Based Access Control) system provides comprehensive per
 
 ## 🚨 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)
+**MANDATORY Setup Steps (in order):**
+
+1. **Call `setupRBAC(supabase)` FIRST** - Must be called before any RBAC components or hooks
+   ```typescript
+   // In main.tsx or App.tsx
+   import { setupRBAC } from '@jmruthers/pace-core/rbac';
+   setupRBAC(supabase); // Must be BEFORE rendering App
+   ```
+
+2. **Wrap app with providers** in exact order:
+   ```tsx
+   <UnifiedAuthProvider supabaseClient={supabase} appName={APP_NAME}>
+     <OrganisationProvider>
+       <YourApp />
+     </OrganisationProvider>
+   </UnifiedAuthProvider>
+   ```
+
+3. **Use `PagePermissionGuard` for ALL pages** - This is the ONLY correct way to protect pages
+   ```tsx
+   <PagePermissionGuard pageName="dashboard" operation="read">
+     <DashboardContent />
+   </PagePermissionGuard>
+   ```
+
+4. **Database must be configured** - App, pages, and permissions must exist in database
+5. **User must have organisation role** - Users need roles in `rbac_organisation_roles` table
+6. **App name must match exactly** - Environment variable must match `rbac_apps.name` (case-sensitive)
+7. **Never query RBAC tables directly** - Always use `PagePermissionGuard` or RBAC API functions
 
 ## 🚀 Quick Start
 
@@ -179,34 +204,58 @@ function App() {
 }
 ```
 
-### 2. Check Permissions
+### 2. Protect Pages with PagePermissionGuard
+
+**⚠️ CRITICAL: Always use `PagePermissionGuard` for page-level access. This is the ONLY way to ensure permissions are checked correctly.**
 
 ```tsx
 import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
 
-function UserActions() {
+function UsersPage() {
   return (
-    <div>
-      <PagePermissionGuard
-        pageName="users"
-        operation="update"
-        fallback={null}
-      >
-        <EditButton />
-      </PagePermissionGuard>
-      
-      <PagePermissionGuard
-        pageName="users"
-        operation="delete"
-        fallback={null}
-      >
-        <DeleteButton />
-      </PagePermissionGuard>
-    </div>
+    <PagePermissionGuard
+      pageName="users"
+      operation="read"
+      fallback={<div>You don't have permission to view this page</div>}
+    >
+      <div>
+        <h1>User Management</h1>
+        
+        {/* Multiple operations on same page */}
+        <PagePermissionGuard
+          pageName="users"
+          operation="create"
+          fallback={null}
+        >
+          <AddUserButton />
+        </PagePermissionGuard>
+        
+        <PagePermissionGuard
+          pageName="users"
+          operation="update"
+          fallback={null}
+        >
+          <EditUserButtons />
+        </PagePermissionGuard>
+        
+        <PagePermissionGuard
+          pageName="users"
+          operation="delete"
+          fallback={null}
+        >
+          <DeleteUserButtons />
+        </PagePermissionGuard>
+      </div>
+    </PagePermissionGuard>
   );
 }
 ```
 
+**Important**: 
+- `pageName` must match the `page_name` in `rbac_app_pages` table
+- `operation` can be: `read`, `create`, `update`, or `delete`
+- Permission checked in database is: `{operation}:page.{pageName}` (e.g., `read:page.users`)
+
 ### 3. Protect Components
 
 ```tsx
@@ -230,24 +279,51 @@ function AdminPanel() {
 The RBAC system uses **page-level permissions** with the format: `{operation}:page.{pageName}`
 
 ### Operations
-- `read` - View page content
+- `read` - View page content (required for `PagePermissionGuard` with `operation="read"`)
 - `create` - Create new content on page
 - `update` - Modify existing content on page
 - `delete` - Remove content from page
-- `manage` - Full page management
-
-### Page-Level Examples
-- `read:page.dashboard` - View dashboard page
-- `create:page.users` - Create users on users page
-- `update:page.settings` - Modify settings page
-- `delete:page.admin` - Remove content from admin page
-- `manage:page.system` - Full system page management
-
-### Event-App Permissions
-- `read:events` - View event information
-- `create:events` - Create new events
-- `update:events` - Modify existing events
-- `delete:events` - Remove events
+
+### Page-Level Permission Format
+
+When you use `PagePermissionGuard` with:
+```tsx
+<PagePermissionGuard pageName="dashboard" operation="read">
+```
+
+The system checks for permission: `read:page.dashboard` in the database.
+
+### Database Structure
+
+Permissions are stored in `rbac_page_permissions` table with:
+- `app_page_id` - Links to `rbac_app_pages` table
+- `operation` - One of: `read`, `create`, `update`, `delete`
+- `role_name` - User's role (e.g., `org_admin`, `leader`, `member`)
+- `allowed` - Boolean (`true` if user has permission, `false` otherwise)
+- `organisation_id` - Organisation context (must match user's organisation)
+
+### Examples
+
+If you have a page named `"users"` and check `operation="read"`:
+- System checks: `read:page.users` permission
+- Database query looks in `rbac_page_permissions` for matching `operation='read'` and `page_name='users'`
+- Permission is granted if user's role has `allowed=true` for that page, operation, and organisation
+
+### Complete Example
+
+```sql
+-- Database setup for a "users" page with read permission for org_admin role
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
+VALUES (
+  (SELECT id FROM rbac_app_pages WHERE page_name = 'users'),
+  'read',
+  'org_admin',
+  true,
+  'your-organisation-id'::uuid
+);
+```
+
+This allows users with `org_admin` role to access `<PagePermissionGuard pageName="users" operation="read">`.
 
 ## 🔒 Security Features