@jmruthers/pace-core 0.5.109 → 0.5.110

package/docs/api/interfaces/RouteConfig.md

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

package/docs/api/interfaces/SecureDataContextType.md

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

package/docs/api/interfaces/SecureDataProviderProps.md

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

package/docs/api/interfaces/StorageConfig.md

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

package/docs/api/interfaces/StorageFileInfo.md

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

package/docs/api/interfaces/StorageFileMetadata.md

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

package/docs/api/interfaces/StorageListOptions.md

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

package/docs/api/interfaces/StorageListResult.md

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

package/docs/api/interfaces/StorageUploadOptions.md

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

package/docs/api/interfaces/StorageUploadResult.md

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

package/docs/api/interfaces/StorageUrlOptions.md

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

package/docs/api/interfaces/StyleImport.md

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

package/docs/api/interfaces/SwitchProps.md

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

package/docs/api/interfaces/ToastActionElement.md

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

package/docs/api/interfaces/ToastProps.md

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

package/docs/api/interfaces/UnifiedAuthContextType.md

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

package/docs/api/interfaces/UnifiedAuthProviderProps.md

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

package/docs/api/interfaces/UseInactivityTrackerOptions.md

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

package/docs/api/interfaces/UseInactivityTrackerReturn.md

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

package/docs/api/interfaces/UsePublicEventOptions.md

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

package/docs/api/interfaces/UsePublicEventReturn.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.5.109](../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.109](../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.109](../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.109](../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.109](../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.109](../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.109](../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.109](../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.109](../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.109](README.md) / Exports
+[@jmruthers/pace-core - v0.5.110](README.md) / Exports
 
-# @jmruthers/pace-core - v0.5.109
+# @jmruthers/pace-core - v0.5.110
 
 **`File`**
 
@@ -499,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)
 
 ___
 
@@ -5027,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)
 
 ___
 
@@ -5066,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)
 
 ___
 
@@ -5088,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)
 
 ___
 
@@ -5110,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)
 
 ___
 
@@ -5145,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)
 
 ___
 
@@ -5169,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)
 
 ___
 
@@ -5193,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)
 
 ___
 
@@ -5221,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)
 
 ___
 
@@ -5249,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)
 
 ___
 
@@ -5467,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)
 
 ___
 
@@ -5662,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)
 
 ___
 
@@ -5676,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)
 
 ___
 
@@ -5690,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)
 
 ___
 
@@ -5704,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)
 
 ___
 
@@ -5718,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
 
@@ -5733,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
 
@@ -5742,7 +5743,7 @@ RBACEngine instance
 
 #### Defined in
 
-[packages/core/src/rbac/engine.ts:594](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/engine.ts#L594)
+[packages/core/src/rbac/engine.ts:601](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/engine.ts#L601)
 
 ___
 

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/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