@cdmbase/wiki-browser 12.0.18-alpha.10 → 12.0.18-alpha.13

package/lib/templates/content/docs/LLM/preference-roles-and-permissions.md

@@ -0,0 +1,838 @@
+# How to Add Roles and Permissions Through Preferences
+
+> **AI Agent Note**: This document is structured for both human and LLM consumption. Look for `[AI-PARSEABLE]` sections for structured schemas and `[EXAMPLE-CODE]` for implementation patterns.
+
+This guide explains how to add new roles and their associated permissions using the preferences system, based on the tenantAdmin implementation.
+
+## Overview
+
+The role and permission system consists of three main components:
+1. **Role Definitions** - Define the roles in the system
+2. **Permission Definitions** - Define what permissions exist
+3. **Permission Overwrites** - Map which permissions each role has
+
+### [AI-PARSEABLE] System Components Schema
+
+```json
+{
+  "system": "role-permission-preferences",
+  "components": {
+    "roles": {
+      "file": "preferences/roles/accounts-roles.ts",
+      "type": "IConfigurationSchemaMap",
+      "purpose": "Define role configurations"
+    },
+    "permissions": {
+      "file": "preferences/permissions/accounts-permissions.ts",
+    [AI-PARSEABLE] Role Definition Schema
+
+```typescript
+interface RoleDefinition {
+  [key: string]: {
+    title: string;                    // Human-readable display name
+    value: ApplicationRoles;          // Enum value from ApplicationRoles
+    default: ApplicationRoles;        // Default value (usually same as value)
+    scope: ConfigurationScope;        // APPLICATION | WINDOW | RESOURCE
+    description: string;              // Purpose and access level description
+  }
+}
+```
+
+### [EXAMPLE-CODE]: "IConfigurationSchemaMap",
+      "purpose": "Define permission configurations"
+    },
+    "permissionOverwrites": {
+      "file": "preferences/roles/accounts-roles-permission-overwrite.ts",
+      "type": "Record<ApplicationRoles, ApplicationPermissions[]>",
+      "purpose": "Map roles to their permission sets"
+    },
+    "migration": {
+      "file": "migrations/dbMigrations/AddAccountsConfigurationsMigration.ts",
+      "type": "BaseConfigurationsMigration",
+      "purpose": "Register and persist configurations"
+    }
+  }
+}
+
+## Architecture
+
+```
+preferences/
+├── roles/
+│   ├── accounts-roles.ts                          # Role definitions
+│   └── accounts-roles-permission-overwrite.ts     # Permission mappings
+└── permissions/
+    └── accounts-permissions.ts                     # Permission definitions
+```
+
+## Step 1: Define Your Role
+
+Roles are defined in `accounts-roles.ts` using the `IConfigurationSchemaMap` interface.
+
+### Example: Adding a TenantAdmin Role
+
+```typescript
+import { IConfigurationSchemaMap } from '@adminide-stack/core';
+import { ApplicationRoles, ConfigurationScope } from 'common/server';
+import { capitalize } from 'lodash-es';
+
+const formatName = (str: string) =>
+    str
+        .split('_')
+        .map((word) => capitalize(word))
+        .join(' ');
+
+export const AccountRolesContribution: IConfigurationSchemaMap = {
+    // Application Level Role
+    'account.role.tenantadmin': {
+        title: 'Super Admin',                          // Display name
+        value: ApplicationRoles.TenantAdmin,           // Enum value
+        default: ApplicationRoles.TenantAdmin,         // Default value
+        scope: ConfigurationScope.APPLICATION,         // Scope level
+        description: 'Super Admin with full system access across all organizations',
+    },
+    
+    // Organization Level Role
+    'organization.role.owner': {
+        title: formatName(ApplicationRoles.Owner),
+        value: ApplicationRoles.Owner,
+        default: ApplicationRoles.Owner,
+        scope: ConfigurationScope.WINDOW,              // Organization scope
+        description: 'Owner of the Organization',
+    [AI-PARSEABLE] Configuration Key Naming Convention
+
+```json
+{
+  "namingPatterns": {
+    "applicationLevel": {
+      "pattern": "account.role.{rolename}",
+      "scope": "ConfigurationScope.APPLICATION",
+      "examples": [
+        "account.role.tenantadmin",
+        "account.role.user",
+        "account.role.guest"
+      ]
+    },
+    "organizationLevel": {
+      "pattern": "organization.role.{rolename}",
+      "scope": "ConfigurationScope.WINDOW",
+      "examples": [
+        "organization.role.owner",
+        "organization.role.admin",
+        "organization.role.manager"
+      ]
+    },
+    "teamLevel": {
+      "pattern": "organization.teams.role.{rolename}",
+      "scope": "ConfigurationScope.WINDOW",
+      "examples": [
+        "organization.teams.role.maintainer",
+
+### [AI-PARSEABLE] Permission Definition Schema
+
+```typescript
+interface PermissionDefinition {
+  [key: string]: {
+    title: string;                    // Human-readable display name
+    value: ApplicationPermissions;    // Enum value from ApplicationPermissions
+    default: ApplicationPermissions;  // Default value (usually same as value)
+    scope: ConfigurationScope;        // APPLICATION | WINDOW | RESOURCE
+    description: string;              // What action this permission allows
+  }
+}
+```
+
+### [EXAMPLE-CODE] Permission Definitions
+        "organization.teams.role.member"
+      ]
+    }
+  },
+  "rules": {
+    "keyFormat": "lowercase with dots as separators",
+    "rolenameFormat": "lowercase, no spaces or special chars",
+    "enumFormat": "SCREAMING_SNAKE_CASE"
+  }[AI-PARSEABLE] Permission Naming Convention
+
+```json
+{
+  "namingPatterns": {
+    "applicationLevel": {
+      "pattern": "account.permission.{permission_name}",
+      "examples": [
+        "account.permission.create_organization",
+
+### [AI-PARSEABLE] Permission Overwrite Schema
+
+```typescript
+interface PermissionOverwrite {
+  [role: ApplicationRoles]: ApplicationPermissions[];
+}
+
+// Example structure
+const overwrites: PermissionOverwrite = {
+  [ApplicationRoles.TenantAdmin]: [
+    /* all system permissions */
+  ],
+  [ApplicationRoles.Owner]: [
+    /* organization-level permissions */
+  ]
+};
+```
+
+### [EXAMPLE-CODE] Mapping Permissions to TenantAdmin
+        "account.permission.manage_users",
+        "account.permission.manage_system_settings"
+      ]
+    },
+    "organizationLevel": {
+      "pattern": "organization.permission.{permission_name}",
+      "examples": [
+        "organization.permission.manage_members",
+        "organization.permission.delete_resources"
+      ]
+    },
+    "resourceSpecific": {
+      "pattern": "{resource}.permission.{permission_name}",
+      "examples": [
+        "project.permission.create",
+        "team.permission.manage_members"
+      ]
+    }
+  }
+}
+
+### Configuration Key Naming Convention
+
+- **Application Level**: `account.role.{rolename}`
+  - Example: `account.role.tenantadmin`, `account.role.user`
+  
+- **Organization Level**: `organization.role.{rolename}`
+  - Example: `organization.role.owner`, `organization.role.admin`
+  
+- **Team Level**: `organization.teams.role.{rolename}`
+  - Example: `organization.teams.role.maintainer`
+
+## Step 2: Define Permissions
+
+Permissions are defined in `accounts-permissions.ts`.
+
+```typescript
+import { IConfigurationSchemaMap } from '@adminide-stack/core';
+import { ApplicationPermissions, ConfigurationScope } from 'common/server';
+
+export const AccountPermissionsContribution: IConfigurationSchemaMap = {
+    'account.permission.create_organization': {
+        title: 'Create Organization',.
+
+### [AI-PARSEABLE] Migration Registration Pattern
+
+```typescript
+interface ConfigurationMigration {
+  name: string;                          // Migration name (e.g., 'account')
+  id: string;                            // Unique ID with timestamp
+  roles: IConfigurationSchemaMap;        // Role definitions
+  permissions: IConfigurationSchemaMap;  // Permission definitions
+  permissionsOverride: PermissionOverwrite; // Role-permission mappings
+  policies?: object;                     // Optional policy configurations
+  settings?: object;                     // Optional settings
+}
+```
+
+### [EXAMPLE-CODE] Migration Registration
+        value: ApplicationPermissions.CREATE_ORGANIZATION,
+        default: ApplicationPermissions.CREATE_ORGANIZATION,
+        scope: ConfigurationScope.APPLICATION,
+        description: 'Permission to create new organizations',
+    },
+    
+    'account.permission.manage_users': {
+        title: 'Manage Users',
+        value: ApplicationPermissions.MANAGE_USERS,
+        default: ApplicationPermissions.MANAGE_USERS,
+   [AI-AGENT-WORKFLOW] Complete Example: Adding a New "Auditor" Role
+
+### [AI-PARSEABLE] Implementation Checklist
+
+```json
+{
+  "workflow": {
+    "step1": {
+      "action": "Update ApplicationRoles enum",
+      "file": "common/server (or equivalent)",
+      "required": true
+    },
+    "step2": {
+      "action": "Add role definition",
+      "file": "preferences/roles/accounts-roles.ts",
+      "required": true
+    },
+    "step3": {
+      "action": "Define new permissions if needed",
+      "file": "preferences/permissions/accounts-permissions.ts",
+      "required": false
+    },
+    "step4": {
+      "action": "Map permissions to role",
+      "file": "preferences/roles/accounts-roles-permission-overwrite.ts",
+      "required": true
+    },
+    "step5": {
+      "action": "Update migration ID",
+      "[STEP-2] file": "migrations/dbMigrations/AddAccountsConfigurationsMigration.ts",
+      "required": true,
+      "note": "Change timestamp in migration ID to trigger re-run"
+    }
+  }
+}
+```
+
+### 1. [STEP-1]
+};
+```
+
+### Permission Naming Convention
+
+- **Application Level**: `account.permission.{permission_name}`
+- **Organization Level**: `organization.permission.{permission_name}`
+- **Resource Specific**: `{resource}.permission.{permission_name}`
+[STEP-3] 
+## Step 3: Map Permissions to Roles
+
+Permission overwrites are defined in `accounts-roles-permission-overwrite.ts`.
+
+```typescript
+import { ApplicationRoles, ApplicationPermissions } from 'common/server';
+
+export const AccountRolesPermissionOverwrite = {
+    [ApplicationRoles.TenantAdmin]: [
+        // System Management
+        ApplicationPermissions.CREATE_ORGANIZATION,
+        ApplicationPermissions.DELETE_ORGANIZATION,
+        ApplicationPermissions.MANAGE_USERS,
+        ApplicationPermissions.MANAGE_SYSTEM_SETTINGS,
+        
+        // Billing & Subscriptions
+        ApplicationPermissions.MANAGE_SUBSCRIPTIONS,
+        ApplicationPermissions.VIEW_BILLING,
+        
+        // Full Organization Access
+        ApplicationPermissions.OWNER_PERMISSIONS,
+        ApplicationPermissions.ADMIN_PERMISSIONS,
+        
+        // ... all other permissions
+    ],
+    
+    [ApplicationRoles.Owner]: [
+        ApplicationPermissions.OWNER_PERMISSIONS,
+        ApplicationPermissions.MANAGE_ORGANIZATION,
+        ApplicationPermissions.INVITE_MEMBERS,
+        // ... organization-level permissions
+    ],
+};
+```
+
+## Step 4: Register in Migration
+
+Register your roles and permissions in the migration class:
+
+```typescript
+import [STEP-4] {
+    AccountPermissionsContribution,
+    AccountRolesContribution,
+    AccountRolesPermissionOverwrite,
+} from '../../preferences';
+
+@injectable()
+export class AddAccountsConfigurationsMigration extends BaseConfigurationsMigration {
+    name = 'account';
+
+    get roles() {
+        return AccountRolesContribution;
+    }
+
+    get permissions() {
+        return AccountPermissionsContribution;
+    }
+
+    [AI-PARSEABLE] Scope Definitions
+
+```json
+{
+  "scopes": {
+    "APPLICATION": {
+      "value": "ConfigurationScope.APPLICATION",
+      "level": "system-wide",
+      "appliesTo": "entire system across all organizations",
+      "useCases": [
+        "System administrator roles",
+        "Global permissions",
+        "Cross-organization access"
+      ],
+      "examples": [
+        "ApplicationRoles.TenantAdmin",
+        "ApplicationRoles.User",
+        "ApplicationRoles.Guest"
+      ]
+    },
+    "WINDOW": {
+      "value": "ConfigurationScope.WINDOW",
+      "level": "organization-specific",
+      "appliesTo": "single organization context",
+      "useCases": [
+        "Organization management roles",
+        "Team-level permissions",
+        "Organization-scoped access"
+      ],
+      "examples": [
+        "ApplicationRoles.Owner",
+        "ApplicationRoles.Admin",
+        "ApplicationRoles.Manager",
+        "ApplicationRoles.Member"
+      ]
+    },
+    "RESOURCE": {
+    [AI-PARSEABLE] Role Hierarchy Structure
+
+```json
+{
+  "roleHierarchy": {
+    "TenantAdmin": {
+      "level": "SYSTEM",
+      "scope": "APPLICATION",
+      "permissions": "ALL",
+      "children": ["Owner", "TeamMaintainer"]
+    },
+    "Owner": {
+      "level": "ORGANIZATION",
+      "scope": "WINDOW",
+      "permissions": "ORGANIZATION_ALL",
+      "children": ["Admin"]
+    },
+    "Admin": {
+      "level": "ORGANIZATION",
+      "scope": "WINDOW",
+      "permissions": "ORGANIZATION_MANAGEMENT",
+      "children": ["Manager"]
+    },
+    "Manager": {
+      "level": "ORGANIZATION",
+      "scope": "WINDOW",
+      "permissions": "ORGANIZATION_OPERATIONS",
+      "children": ["Contributor", "Member"]
+    },
+    "Contributor": {
+      "level": "ORGANIZATION",
+      "scope": "WINDOW",
+      "permissions": "READ_WRITE",
+      "children": []
+    },
+    "Member": {
+      "level": "ORGANIZATION",
+      "scope": "WINDOW",
+      "permissions": "READ_ONLY",
+      "children": []
+    },
+    "Guest": {
+      "level": "PUBLIC",
+      "scope": "APPLICATION",
+      "permissions": "PUBLIC_ONLY",
+      "children": []
+    },
+    "TeamMaintainer": {
+      "level": "TEAM",
+   [AI-AGENT-WORKFLOW] Migration Process
+
+### [AI-PARSEABLE] Migration Workflow
+
+```json
+{
+  "migrationWorkflow": {
+    "step1_updateEnums": {
+      "order": 1,
+      "action": "Add new values to ApplicationRoles or ApplicationPermissions enum",
+      "location": "common/server or equivalent",
+      "format": "SCREAMING_SNAKE_CASE",
+      "example": "ApplicationRoles.Auditor = 'AUDITOR'",
+      "critical": true
+    },
+    "step2_defineConfiguration": {
+      "order": 2,
+      "action": "Add role/permission definitions to preference files",
+      "locations": [
+        "preferences/roles/accounts-roles.ts",
+        "preferences/permissions/accounts-permissions.ts",
+        "preferences/roles/accounts-roles-permission-overwrite.ts"
+      ],
+      "critical": true
+    },
+    "step3_updateMigrationId": {
+      "order": 3,
+      "action": "Update migration ID with new timestamp",
+      "location": "migrations/dbMigrations/AddAccountsConfigurationsMigration.ts",
+      "property": "get id()",
+      "format": "${ClassName}_YYYYMMDD",
+   [AI-PARSEABLE] Troubleshooting Guide
+
+```json
+{
+  "troubleshooting": {
+    "roleNotAppearing": {
+      "symptoms": ["Role not visible in UI", "Role not available for assignment"],
+      "diagnosticChecks": [
+        {
+          "check": "Enum definition exists",
+          "location": "common/server ApplicationRoles enum",
+          "fix": "Add role to ApplicationRoles enum"
+        },
+        {
+          "check": "Configuration key naming correct",
+          "expected": "account.role.{rolename} or organization.role.{rolename}",
+          "fix": "Verify naming follows convention"
+        },
+        {
+          "check": "Migration has been run",
+   [AI-PARSEABLE] Quick Reference Card
+
+```json
+{
+  "quickReference": {
+    "files": {
+      "roleDefinitions": "preferences/roles/accounts-roles.ts",
+      "permissionDefinitions": "preferences/permissions/accounts-permissions.ts",
+      "permissionMappings": "preferences/roles/accounts-roles-permission-overwrite.ts",
+      "migration": "migrations/dbMigrations/AddAccountsConfigurationsMigration.ts",
+      "enums": "common/server (or equivalent package)"
+    },
+    "keyInterfaces": {
+      "IConfigurationSchemaMap": "@adminide-stack/core",
+      "ConfigurationScope": "common/server",
+      "ApplicationRoles": "common/server",
+      "ApplicationPermissions": "common/server",
+      "BaseConfigurationsMigration": "@adminide-stack/platform-server"
+    },
+    "namingConventions": {
+      "roleConfigKey": "account.role.{rolename} | organization.role.{rolename}",
+      "permissionConfigKey": "account.permission.{permname} | organization.permission.{permname}",
+      "enumFormat": "SCREAMING_SNAKE_CASE",
+      "migrationIdFormat": "${ClassName}_YYYYMMDD"
+    },
+    "scopes": {
+      "APPLICATION": "System-wide, across all organizations",
+      "WINDOW": "Organization or team level",
+      "RESOURCE": "Specific to individual entities"
+    },
+    "workflow": [
+      "1. Update ApplicationRoles/ApplicationPermissions enum",
+      "2. Add to accounts-roles.ts or accounts-permissions.ts",
+      "3. Map in accounts-roles-permission-overwrite.ts",
+      "4. Update migration ID timestamp",
+      "5. Run migration"
+    ]
+  }
+}
+```
+
+## References
+
+- [accounts-roles.ts](./accounts-roles.ts) - Role definitions
+- [accounts-roles-permission-overwrite.ts](./accounts-roles-permission-overwrite.ts) - Permission mappings
+- [AddAccountsConfigurationsMigration.ts](../../migrations/dbMigrations/AddAccountsConfigurationsMigration.ts) - Migration implementation
+- Configuration Registry: `@adminide-stack/core`
+- Common Types: `common/server`
+
+---
+
+## AI Agent Usage Notes
+
+This document includes:
+- **[AI-PARSEABLE]** sections with structured JSON schemas for machine parsing
+- **[EXAMPLE-CODE]** sections with complete implementation examples
+- **[AI-AGENT-WORKFLOW]** sections with step-by-step process definitions
+- **[STEP-N]** markers for sequential task execution
+- JSON schemas for all key data structures
+- Structured troubleshooting decision trees
+- Quick reference card for rapid lookups
+
+AI agents can extract structured information from JSON blocks and follow the workflow markers for automated implementation tasks.amp in migration ID"
+        }
+      ]
+    },
+    "permissionsNotWorking": {
+      "symptoms": ["Access denied", "Permissions not taking effect"],
+      "diagnosticChecks": [
+        {
+          "check": "Permission listed in permissionsOverride",
+          "location": "accounts-roles-permission-overwrite.ts",
+          "fix": "Add permission to role's permission array"
+        },
+        {
+          "check": "Role hierarchy correct",
+          "validation": "Check if higher roles include lower role permissions",
+          "fix": "Review and update permission inheritance"
+        },
+        {
+          "check": "ApplicationPermissions enum updated",
+          "location": "common/server ApplicationPermissions enum",
+          "fix": "Add permission to enum"
+        },
+        {
+          "check": "Redis cache cleared",
+          "command": "Clear Redis cache manually or restart",
+          "fix": "Clear cache via redisCacheManager"
+        }
+      ]
+    },
+    "migrationNotRunning": {
+      "symptoms": ["New configurations not in database", "Changes not reflected"],
+      "diagnosticChecks": [
+        {
+          "check": "Migration ID updated with new timestamp",
+          "location": "get id() method",
+          "fix": "Change date suffix: _20260128"
+        },
+        {
+          "check": "Database connection working",
+          "command": "Verify MongoDB connection",
+          "fix": "Check connection string and credentials"
+        },
+        {
+          "check": "Migration logs",
+          "location": "Application logs",
+          "fix": "Review error messages in migration logs"
+        },
+        {
+          "check": "Inheritance from BaseConfigurationsMigration",
+          "location": "Class declaration",
+          "fix": "Ensure extends BaseConfigurationsMigration"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Common Issues
+
+#### Role Not Appearing
+- Check enum definition in common/server
+- Verify configuration key naming
+- Ensure migration has been run
+- Check migration ID has been updated
+
+#### Permissions Not Working
+- Verify permission is listed in permissionsOverride
+- Check role hierarchy
+- Ensure ApplicationPermissions enum is updated
+- Clear Redis cache if needed
+
+#      "manual": "Can be done via redisCacheManager if needed"
+    }
+  },
+  "migrationIdFormat": {
+    "pattern": "${MigrationClassName}_${YYYYMMDD}",
+    "examples": [
+      "AddAccountsConfigurationsMigration_20260113",
+      "AddAccountsConfigurationsMigration_20260128"
+    ],
+    "requirement": "Must change to trigger re-run"
+  }
+}
+```
+
+### Implementation Steps
+    },
+    "TeamMember": {
+      "level": "TEAM",
+      "scope": "WINDOW",
+      "permissions": "TEAM_ACCESS",
+      "children": []
+    }
+  },
+  "hierarchyRules": {
+    "inheritance": "Higher roles include all permissions of lower roles",
+    "tenantAdminRule": "TenantAdmin has all system permissions",
+    "ownerRule": "Owner has all organization permissions within their org"
+  }
+}
+```
+
+### Visuale": "ConfigurationScope.RESOURCE",
+      "level": "resource-specific",
+      "appliesTo": "individual entities",
+      "useCases": [
+        "Project-specific roles",
+        "Document-level permissions",
+        "Fine-grained access control"
+      ],
+      "examples": [
+        "Project-specific roles",
+        "Document owners"
+      ]
+    }
+  }
+}ole
+    Owner = 'OWNER',
+    // ... other roles
+}
+```
+
+### 2. Add Role Definition
+
+```typescript
+// In accounts-roles.ts
+export const AccountRolesContribution: IConfigurationSchemaMap = {
+    // ... existing roles
+    
+    'account.role.auditor': {
+        title: 'Auditor',
+        value: ApplicationRoles.Auditor,
+        default: ApplicationRoles.Auditor,
+        scope: ConfigurationScope.APPLICATION,
+        description: 'Read-only access to audit logs and system reports',
+    },
+};
+```
+
+### 3. Define Auditor Permissions
+
+```typescript
+// In accounts-permissions.ts
+export const AccountPermissionsContribution: IConfigurationSchemaMap = {
+    // ... existing permissions
+    
+    'account.permission.view_audit_logs': {
+        title: 'View Audit Logs',
+        value: ApplicationPermissions.VIEW_AUDIT_LOGS,
+        default: ApplicationPermissions.VIEW_AUDIT_LOGS,
+        scope: ConfigurationScope.APPLICATION,
+        description: 'Permission to view system audit logs',
+    },
+};
+```
+
+### 4. Map Permissions to Auditor Role
+
+```typescript
+// In accounts-roles-permission-overwrite.ts
+export const AccountRolesPermissionOverwrite = {
+    // ... existing role mappings
+    
+    [ApplicationRoles.Auditor]: [
+        ApplicationPermissions.VIEW_AUDIT_LOGS,
+        ApplicationPermissions.VIEW_REPORTS,
+        ApplicationPermissions.VIEW_ORGANIZATIONS,
+        // Read-only permissions only
+    ],
+};
+```
+
+## Configuration Scopes
+
+### APPLICATION Scope
+- System-wide settings
+- Apply across all organizations
+- Examples: TenantAdmin, User, Guest
+
+### WINDOW Scope (Organization)
+- Organization-specific settings
+- Apply within a single organization context
+- Examples: Owner, Admin, Manager, Member
+
+### RESOURCE Scope
+- Specific to individual resources
+- Apply to particular entities
+- Examples: Project-specific roles
+
+## Best Practices
+
+### 1. Role Hierarchy
+```
+TenantAdmin (System Level)
+├── Owner (Organization Level)
+│   ├── Admin (Organization Level)
+│   │   ├── Manager (Organization Level)
+│   │   │   ├── Contributor (Organization Level)
+│   │   │   └── Member (Organization Level)
+│   └── Guest (Public Access)
+└── TeamMaintainer (Team Level)
+    └── TeamMember (Team Level)
+```
+
+### 2. Permission Inheritance
+- Higher roles should include all permissions of lower roles
+- TenantAdmin should have all system permissions
+- Owner should have all organization permissions
+
+### 3. Naming Conventions
+- Use SCREAMING_SNAKE_CASE for enum values
+- Use lowercase with underscores for configuration keys
+- Use descriptive names that indicate the action
+
+### 4. Documentation
+- Always include meaningful descriptions
+- Explain the scope and purpose of each role
+- Document permission sets clearly
+
+### 5. Testing
+```typescript
+// Test role registration
+describe('Role Configuration', () => {
+    it('should register TenantAdmin role', () => {
+        const role = AccountRolesContribution['account.role.tenantadmin'];
+        expect(role.value).toBe(ApplicationRoles.TenantAdmin);
+        expect(role.scope).toBe(ConfigurationScope.APPLICATION);
+    });
+});
+
+// Test permission mapping
+describe('Permission Overwrite', () => {
+    it('should grant full permissions to TenantAdmin', () => {
+        const permissions = AccountRolesPermissionOverwrite[ApplicationRoles.TenantAdmin];
+        expect(permissions).toContain(ApplicationPermissions.CREATE_ORGANIZATION);
+        expect(permissions).toContain(ApplicationPermissions.MANAGE_SYSTEM_SETTINGS);
+    });
+});
+```
+
+## Migration Process
+
+When adding new roles/permissions:
+
+1. **Update Enums** - Add to ApplicationRoles/ApplicationPermissions
+2. **Define Configuration** - Add to preference files
+3. **Update Migration ID** - Change migration ID to trigger re-run
+   ```typescript
+   get id() {
+       return `${AddAccountsConfigurationsMigration.name}_20260128`; // Update date
+   }
+   ```
+4. **Run Migration** - System will automatically register new configurations
+5. **Clear Cache** - Redis cache will be cleared automatically
+
+## Troubleshooting
+
+### Role Not Appearing
+- Check enum definition in common/server
+- Verify configuration key naming
+- Ensure migration has been run
+- Check migration ID has been updated
+
+### Permissions Not Working
+- Verify permission is listed in permissionsOverride
+- Check role hierarchy
+- Ensure ApplicationPermissions enum is updated
+- Clear Redis cache if needed
+
+### Migration Not Running
+- Update migration ID with new timestamp
+- Check database connection
+- Review migration logs
+- Verify BaseConfigurationsMigration inheritance
+
+## References
+
+- [accounts-roles.ts](./accounts-roles.ts) - Role definitions
+- [accounts-roles-permission-overwrite.ts](./accounts-roles-permission-overwrite.ts) - Permission mappings
+- [AddAccountsConfigurationsMigration.ts](../../migrations/dbMigrations/AddAccountsConfigurationsMigration.ts) - Migration implementation
+- Configuration Registry: `@adminide-stack/core`
+- Common Types: `common/server`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cdmbase/wiki-browser",
-    "version": "12.0.18-alpha.10",
+    "version": "12.0.18-alpha.13",
     "description": "Sample core for higher packages to depend on",
     "license": "ISC",
     "author": "CDMBase LLC",
@@ -21,13 +21,13 @@
         "watch": "yarn build:lib:watch"
     },
     "dependencies": {
-        "@admin-layout/tailwind-ui": "12.2.4-alpha.9",
+        "@admin-layout/tailwind-ui": "12.2.4-alpha.12",
         "@react-icons/all-files": "^4.1.0",
         "marked": "7.0.5",
         "openai": "^4.52.0"
     },
     "devDependencies": {
-        "common": "12.0.18-alpha.1"
+        "common": "12.0.18-alpha.13"
     },
     "peerDependencies": {
         "@common-stack/client-react": ">0.5.16",
@@ -64,7 +64,7 @@
             }
         ]
     },
-    "gitHead": "9d85ed54cf2d0a81f5027a9939b0b35a2d54b8a3",
+    "gitHead": "81310a170f55f20287cae9207b66af4d7e49376c",
     "typescript": {
         "definition": "lib/index.d.ts"
     }