@flusys/ng-iam 3.0.0-rc → 3.0.0

package/README.md

@@ -4,37 +4,15 @@
 
 `@flusys/ng-iam` provides Identity and Access Management (IAM) for FLUSYS applications. It includes permission state management, role-based access control (RBAC), action management with AND/OR prerequisite logic, and dynamic menu filtering based on user permissions.
 
-**Key Principle:** ng-iam is **100% independent** from ng-auth through the **Provider Interface Pattern**. No compile-time or runtime dependencies on ng-auth.
-
-## Package Information
+**Key Principle:** ng-iam is **100% independent** from ng-auth through the **Provider Interface Pattern**.
 
 | Item | Value |
 |------|-------|
 | Package | `@flusys/ng-iam` |
-| Version | 1.0.0 |
+| Version | 3.0.0 |
 | Dependencies | ng-core, ng-shared, ng-layout (IMenuItem only) |
-| NO dependency on | ng-auth (fully independent via Provider Pattern) |
 | CSS Framework | Tailwind CSS (not PrimeFlex) |
 | Build | `npm run build:ng-iam` |
-| Entry point | `public-api.ts` |
-
----
-
-## Table of Contents
-
-1. [Architecture](#architecture)
-2. [Provider Interfaces](#provider-interfaces)
-3. [Integration Options](#integration-options)
-4. [Permission Modes](#permission-modes)
-5. [Routes](#routes)
-6. [Services](#services)
-7. [Components](#components)
-8. [Page Components](#page-components)
-9. [Interfaces](#interfaces)
-10. [Utils & Constants](#utils--constants)
-11. [Backend Integration](#backend-integration)
-12. [Best Practices](#best-practices)
-13. [Common Issues](#common-issues)
 
 ---
 
@@ -42,131 +20,74 @@
 
 ```
 ng-shared (defines interfaces + tokens)
-    |
+    ↓
 Your Auth System (implements interfaces with adapters)
-    |
+    ↓
 ng-iam (consumes interfaces via DI)
 ```
 
-ng-iam resolves all auth-related data at runtime via DI tokens defined in ng-shared. If a required token is not provided, Angular throws a clear error at injection time.
+ng-iam resolves all auth-related data at runtime via DI tokens defined in ng-shared.
 
 ---
 
 ## Provider Interfaces
 
-ng-iam requires these provider interfaces:
-
 | Token | Source | Purpose | Required? |
 |-------|--------|---------|-----------|
-| `USER_PROVIDER` | `@flusys/ng-shared` | User list for role/action assignment | Yes |
-| `LAYOUT_AUTH_STATE` | `@flusys/ng-layout` | Current company/branch context | Yes (if company feature enabled) |
-| `COMPANY_API_PROVIDER` | `@flusys/ng-shared` | Company list for whitelisting | Optional (for CompanyActionSelector) |
-| `USER_PERMISSION_PROVIDER` | `@flusys/ng-shared` | User branch permissions | Optional (for branch-scoped permissions) |
-
-### How Components Use Providers
-
-User selection uses `lib-user-select` component from ng-shared (encapsulates USER_PROVIDER):
-
-```html
-<!-- UserActionSelectorComponent / UserRoleSelectorComponent -->
-<lib-user-select
-  [(value)]="selectedUserId"
-  [isEditMode]="true"
-  placeHolder="Select a user"
-/>
-```
-
-Company context is accessed via `LAYOUT_AUTH_STATE`:
-
-```typescript
-private readonly companyContext = inject(LAYOUT_AUTH_STATE);
-
-// Get current company
-const companyId = this.companyContext.currentCompanyInfo()?.id;
-```
-
-Branch permissions loaded from `USER_PERMISSION_PROVIDER`:
+| `USER_PROVIDER` | ng-shared | User list for role/action assignment | Yes |
+| `LAYOUT_AUTH_STATE` | ng-layout | Current company/branch context | Yes (if company enabled) |
+| `COMPANY_API_PROVIDER` | ng-shared | Company list for whitelisting | Optional |
+| `USER_PERMISSION_PROVIDER` | ng-shared | User branch permissions | Optional |
 
 ```typescript
-private readonly userPermissionProvider = inject(USER_PERMISSION_PROVIDER);
-
-const response = await this.userPermissionProvider
-  .getUserBranchPermissions(userId)
-  .toPromise();
+// Provider usage
+const companyId = inject(LAYOUT_AUTH_STATE).currentCompanyInfo()?.id;
+const response = await inject(USER_PERMISSION_PROVIDER).getUserBranchPermissions(userId).toPromise();
 ```
 
 ---
 
 ## Integration Options
 
-### Option 1: With FLUSYS ng-auth (Recommended)
-
-ng-auth provides pre-built adapters for all required interfaces.
+### With FLUSYS ng-auth (Recommended)
 
 ```typescript
-// app.config.ts
 import { provideAuthProviders } from '@flusys/ng-auth';
-
 export const appConfig: ApplicationConfig = {
-  providers: [
-    provideAuthProviders(), // Registers all adapters
-  ],
+  providers: [provideAuthProviders()],  // Registers all adapters
 };
 ```
 
-**Reference adapters in ng-auth:**
-
-| Adapter | Interface | Path |
-|---------|-----------|------|
-| `AuthUserProviderAdapter` | `IUserProvider` | `projects/ng-auth/adapters/` |
-| `AuthLayoutStateAdapter` | `ILayoutAuthState` | `projects/ng-auth/adapters/` |
-| `AuthCompanyApiProviderAdapter` | `ICompanyApiProvider` | `projects/ng-auth/adapters/` |
-| `AuthUserPermissionProviderAdapter` | `IUserPermissionProvider` | `projects/ng-auth/adapters/` |
-
-### Option 2: With Custom Auth System
-
-Implement the required interfaces with your own auth system. No ng-auth dependency needed.
+### With Custom Auth System
 
 ```typescript
-// Minimum configuration (basic IAM)
 providers: [
   { provide: USER_PROVIDER, useClass: YourUserProvider },
   { provide: LAYOUT_AUTH_STATE, useClass: YourCompanyContextProvider },
-]
-
-// Full configuration (company + branch permissions)
-providers: [
-  { provide: USER_PROVIDER, useClass: YourUserProvider },
-  { provide: LAYOUT_AUTH_STATE, useClass: YourCompanyContextProvider },
-  { provide: COMPANY_API_PROVIDER, useClass: YourCompanyApiProvider },
-  { provide: USER_PERMISSION_PROVIDER, useClass: YourUserPermissionProvider },
+  { provide: COMPANY_API_PROVIDER, useClass: YourCompanyApiProvider },       // Optional
+  { provide: USER_PERMISSION_PROVIDER, useClass: YourUserPermissionProvider }, // Optional
 ]
 ```
 
-**Feature matrix:**
-
 | Feature | Providers Needed |
 |---------|-----------------|
 | Basic role assignments | USER_PROVIDER only |
 | Company-scoped permissions | + LAYOUT_AUTH_STATE, COMPANY_API_PROVIDER |
 | Branch-scoped permissions | + LAYOUT_AUTH_STATE, USER_PERMISSION_PROVIDER |
-| Direct user permissions | + USER_PERMISSION_PROVIDER |
-
-All adapters must return `IListResponse<T>` or `ISingleResponse<T>` format from `@flusys/ng-shared`.
 
 ---
 
 ## Permission Modes
 
-FLUSYS IAM supports three permission modes configured via `APP_CONFIG.iam.permissionMode`:
+Configured via `APP_CONFIG.iam.permissionMode`:
 
 | Mode | Structure | Tabs Available | Use Case |
 |------|-----------|---------------|----------|
-| **DIRECT** | User -> Actions | User-Actions | Small apps, per-user permissions |
-| **RBAC** | User -> Role -> Actions | Role-Actions, User-Roles | Standard apps, role templates |
-| **FULL** | Both combined | Role-Actions, User-Roles, User-Actions | Maximum flexibility |
+| **DIRECT** | User -> Actions | User-Actions | Small apps |
+| **RBAC** | User -> Role -> Actions | Role-Actions, User-Roles | Standard apps |
+| **FULL** | Both combined | All tabs | Maximum flexibility |
 
-When company feature is enabled, a **Company-Actions** tab is added for whitelisting actions per company.
+When company feature is enabled, a **Company-Actions** tab is added for whitelisting.
 
 ---
 
@@ -175,26 +96,21 @@ When company feature is enabled, a **Company-Actions** tab is added for whitelis
 **Export:** `IAM_ROUTES` from `@flusys/ng-iam`
 
 ```
-/iam                          (IamContainerComponent - tabbed navigation)
-  /actions                    (ActionListPageComponent - hierarchical tree)
-  /actions/new                (ActionFormPageComponent - create)
-  /actions/:id                (ActionFormPageComponent - edit)
-  /roles                      (RoleListPageComponent - paginated table)
-  /roles/new                  (RoleFormPageComponent - create)
-  /roles/:id                  (RoleFormPageComponent - edit)
-  /permissions                (PermissionPageComponent - tabbed assignment UI)
-  (default redirect -> /actions)
+/iam                    → IamContainerComponent (tabbed navigation)
+  /actions              → ActionListPageComponent (hierarchical tree)
+  /actions/new          → ActionFormPageComponent (create)
+  /actions/:id          → ActionFormPageComponent (edit)
+  /roles                → RoleListPageComponent (paginated table)
+  /roles/new            → RoleFormPageComponent (create)
+  /roles/:id            → RoleFormPageComponent (edit)
+  /permissions          → PermissionPageComponent (tabbed assignment UI)
 ```
 
-**Usage in app routes:**
-
-```typescript
-import { IAM_ROUTES } from '@flusys/ng-iam';
-
-export const routes: Routes = [
-  { path: 'iam', children: IAM_ROUTES },
-];
-```
+| Route | Guard | Permission |
+|-------|-------|------------|
+| `/actions` | permissionGuard | `ACTION_PERMISSIONS.READ` |
+| `/roles` | permissionGuard | `ROLE_PERMISSIONS.READ` |
+| `/permissions` | anyPermissionGuard | Multiple READ permissions |
 
 ---
 
@@ -202,139 +118,84 @@ export const routes: Routes = [
 
 ### PermissionStateService
 
-Manages current user's permissions with signal-based state. Provided at root level.
+**File:** `services/permission-state.service.ts` | Provided at root level
 
-**Dependencies:** `MyPermissionsApiService`, `PermissionValidatorService` (from ng-shared)
+Manages current user's permissions with signal-based state.
 
-**Signals:**
-
-| Signal | Type | Description |
-|--------|------|-------------|
+| API | Type | Description |
+|-----|------|-------------|
 | `permissions` | `Signal<IMyPermissionsResponseDto \| null>` | Current user permissions (readonly) |
 | `isLoading` | `Signal<boolean>` | Loading state (readonly) |
+| `loadPermissions(dto?)` | `Observable<void>` | Load from `/iam/permissions/my-permissions` |
+| `isLoaded()` | `boolean` | Check if permissions loaded |
 
-**Methods:**
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `loadPermissions(dto?)` | `Observable<void>` | Load permissions from `/iam/permissions/my-permissions` |
-| `isLoaded()` | `boolean` | Check if permissions have been loaded |
-
-Permission checking is delegated to `PermissionValidatorService` from ng-shared (hasAction, hasAllActions, hasAnyAction, getActionCodes).
+Permission checking delegated to `PermissionValidatorService` from ng-shared.
 
 ```typescript
-const permissionState = inject(PermissionStateService);
-
-// Load permissions (typically in guard)
-await firstValueFrom(permissionState.loadPermissions());
-
-// Check permissions (via PermissionValidatorService)
-const validator = inject(PermissionValidatorService);
-validator.hasAction('user.create');
-validator.hasAllActions(['user.create', 'user.update']);
-validator.hasAnyAction(['user.view', 'user.list']);
+await firstValueFrom(permissionState.loadPermissions());  // Load in guard
+validator.hasAction('user.create');                       // Check permission
+validator.hasAllActions(['user.create', 'user.update']); // Check multiple
 ```
 
 ---
 
 ### ActionApiService
 
-Extends `ApiResourceService<IUpdateActionDto, IAction>` for action CRUD.
+**File:** `services/action-api.service.ts` | Extends `ApiResourceService<IUpdateActionDto, IAction>`
 
 **Resource:** `iam/actions`
 
-**Additional Methods:**
-
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `getTree(search?, isActive?, withDeleted?)` | `POST /iam/actions/tree` | Get hierarchical action tree |
-| `getActionsForPermission()` | `POST /iam/actions/tree-for-permission` | Get actions filtered by company whitelist |
+| `getTree(search?, isActive?, withDeleted?)` | `POST /iam/actions/tree` | Hierarchical action tree |
+| `getActionsForPermission()` | `POST /iam/actions/tree-for-permission` | Actions filtered by company whitelist |
 
-Inherits standard CRUD from `ApiResourceService`: `getAll`, `getById`, `insert`, `update`, `delete`.
+Inherits standard CRUD: `getAll`, `getById`, `insert`, `update`, `delete`.
 
 ---
 
 ### RoleApiService
 
-Extends `ApiResourceService<IUpdateRoleDto, IRole>` for role CRUD.
-
-**Resource:** `iam/roles`
+**File:** `services/role-api.service.ts` | Extends `ApiResourceService<IUpdateRoleDto, IRole>`
 
-Inherits standard CRUD from `ApiResourceService`. Only available in RBAC/FULL mode.
+**Resource:** `iam/roles` | Only available in RBAC/FULL mode.
 
 ---
 
 ### PermissionApiService
 
-Extends `BaseApiService` for all permission assignment operations.
+**File:** `services/permission-api.service.ts` | Extends `BaseApiService`
 
-**Base:** `super('iam')` - all paths resolved via `this.getUrl(...)` relative to `/iam/`
-
-**User -> Action (Direct Permissions):**
+All endpoints use POST (POST-only RPC convention).
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | `assignUserActions(data)` | `POST /iam/permissions/user-actions/assign` | Assign/remove actions for user |
-| `getUserActions(userId, query?)` | `GET /iam/permissions/user-actions/{userId}` | Get user's direct actions |
-
-**User -> Role:**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
+| `getUserActions(userId, query?)` | `POST /iam/permissions/get-user-actions` | Get user's direct actions |
 | `assignUserRoles(data)` | `POST /iam/permissions/user-roles/assign` | Assign/remove roles for user |
-| `getUserRoles(userId, query?)` | `GET /iam/permissions/user-roles/{userId}` | Get user's roles |
-
-**Role -> Action:**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
+| `getUserRoles(userId, query?)` | `POST /iam/permissions/get-user-roles` | Get user's roles |
 | `assignRoleActions(data)` | `POST /iam/permissions/role-actions/assign` | Assign/remove actions for role |
-| `getRoleActions(roleId, query?)` | `GET /iam/permissions/role-actions/{roleId}` | Get role's actions |
-
-**Company -> Action (Whitelisting):**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
+| `getRoleActions(roleId, query?)` | `POST /iam/permissions/get-role-actions` | Get role's actions |
 | `assignCompanyActions(data)` | `POST /iam/permissions/company-actions/assign` | Assign/remove company whitelist |
-| `getCompanyActions(companyId)` | `GET /iam/permissions/company-actions/{companyId}` | Get company's whitelisted actions |
-
-> **Note:** Read operations use GET (exception to the POST-only RPC convention). Write operations use POST.
-
----
-
-### MyPermissionsApiService
-
-Fetches current user's permissions.
-
-**Method:**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `getMyPermissions(dto?)` | `POST /iam/permissions/my-permissions` | Get current user's frontend actions and cached endpoint count |
+| `getCompanyActions(companyId)` | `POST /iam/permissions/get-company-actions` | Get company's whitelisted actions |
 
 ---
 
 ### ActionPermissionLogicService
 
-Manages smart prerequisite validation using AND/OR logic trees. Uses PrimeNG `ConfirmationService` and `MessageService` for dialogs.
+**File:** `services/action-permission-logic.service.ts`
 
-**Core Methods:**
+Manages smart prerequisite validation using AND/OR logic trees.
 
 | Method | Description |
 |--------|-------------|
-| `handleCheck(action, selection, allActions, onUpdate, onCancel)` | Handle action selection with recursive prerequisite validation |
+| `handleCheck(action, selection, allActions, onUpdate, onCancel)` | Handle selection with prerequisite validation |
 | `handleUncheck(action, selection, allActions, onUpdate)` | Handle deselection with dependency detection |
 | `hasUnmetPrerequisites(action, selection, allActions)` | Check if action has unmet prerequisites |
-| `getActionsWithUnmetPrerequisites(selection, allActions)` | Get all selected actions with unmet prerequisites |
-| `showValidationErrorDialog(invalid, selection, allActions, onUpdate)` | Pre-save validation error dialog with auto-fix |
+| `showValidationErrorDialog(invalid, selection, allActions, onUpdate)` | Pre-save validation with auto-fix |
 | `getPrerequisiteTooltip(action, selection, allActions)` | Get tooltip text with prerequisite info |
 
-**Features:**
-- Recursive deep-scan for cascading prerequisites
-- Smart AND/OR optimization (selects minimum required actions)
-- Visual formatting with status indicators
-- Alternative suggestions for OR logic branches
-- Pre-save validation with auto-fix capability
+Features: Recursive deep-scan, smart AND/OR optimization, alternative suggestions, pre-save validation.
 
 ---
 
@@ -342,257 +203,99 @@ Manages smart prerequisite validation using AND/OR logic trees. Uses PrimeNG `Co
 
 ### LogicBuilderComponent
 
-Visual AND/OR permission logic tree editor.
+**Selector:** `lib-logic-builder` | Visual AND/OR permission logic tree editor.
 
-| Property | Value |
-|----------|-------|
-| Selector | `lib-logic-builder` |
-| Standalone | Yes |
-| Change Detection | OnPush |
+| Input/Output | Type | Description |
+|--------------|------|-------------|
+| `logic` (input) | `ILogicNode \| null` | Current permission logic tree |
+| `actions` (input) | `Array<{id, name}>` | Available actions for dropdowns |
+| `logicChange` (output) | `ILogicNode \| null` | Emitted when logic changes |
 
-**Inputs:**
+---
 
-| Input | Type | Description |
-|-------|------|-------------|
-| `logic` | `ILogicNode \| null` | Current permission logic tree |
-| `actions` | `Array<{id, name}>` | Available actions for dropdowns |
+### Selector Components (Common Pattern)
 
-**Outputs:**
+All selector components share a common pattern with these signals:
 
-| Output | Type | Description |
-|--------|------|-------------|
-| `logicChange` | `ILogicNode \| null` | Emitted when logic changes |
+| Signal | Description |
+|--------|-------------|
+| `selectedXxxId` | Selected entity ID (user/role/company) |
+| `treeNodes` / `items` | Available items (TreeNode[] or flat array) |
+| `flatActions` | Flattened action list (for action selectors) |
+| `selectedIds` | Currently selected IDs (Set) |
+| `originalSelectedIds` | Original state for change tracking |
+| `isLoading` / `isSaving` | Loading/saving states |
+| `pendingAdd` / `pendingRemove` | Computed: items to add/remove |
+| `hasChanges` | Computed: whether there are pending changes |
 
-**Features:** Recursive tree builder, AND/OR operator toggling, action selector dropdowns, node add/remove.
+Common features: AbortController for request cancellation, responsive tables with `overflow-x-auto`, change tracking, select/deselect all.
 
 ---
 
 ### UserActionSelectorComponent
 
-Assigns actions directly to users (DIRECT/FULL mode).
-
-| Property | Value |
-|----------|-------|
-| Selector | `flusys-user-action-selector` |
-| Standalone | Yes |
-| Change Detection | OnPush |
-
-**Dependencies:** `APP_CONFIG`, `LAYOUT_AUTH_STATE`, `USER_PERMISSION_PROVIDER`, `ActionApiService`, `ActionPermissionLogicService`, `PermissionApiService`, `MessageService`
+**Selector:** `flusys-user-action-selector` | Assigns actions directly to users (DIRECT/FULL mode).
 
-**Features:**
-- User dropdown (`lib-user-select` component from ng-shared)
-- Branch selector (conditional, loaded from USER_PERMISSION_PROVIDER)
+- User dropdown (`lib-user-select` from ng-shared)
+- Branch selector (conditional, from USER_PERMISSION_PROVIDER)
 - Hierarchical TreeTable with checkboxes
-- Responsive table with `overflow-x-auto` container
-- Responsive columns (Code hidden on mobile, Description hidden until lg)
-- Action type tags (backend/frontend/both)
 - Prerequisite validation with tooltips
-- Change tracking with pending add/remove summary
-- Select/deselect all
-- Pre-save validation
 
 ---
 
 ### UserRoleSelectorComponent
 
-Assigns roles to users (RBAC/FULL mode).
+**Selector:** `flusys-user-role-selector` | Assigns roles to users (RBAC/FULL mode).
 
-| Property | Value |
-|----------|-------|
-| Selector | `flusys-user-role-selector` |
-| Standalone | Yes |
-| Change Detection | OnPush |
-
-**Dependencies:** `APP_CONFIG`, `LAYOUT_AUTH_STATE`, `USER_PERMISSION_PROVIDER`, `RoleApiService`, `PermissionApiService`, `MessageService`
-
-**Features:**
-- User dropdown (`lib-user-select` component from ng-shared)
-- Branch selector (conditional)
-- DataTable with pagination and `overflow-x-auto` container
-- Responsive columns (Code hidden on mobile, Description hidden until md)
-- Change tracking with pending add/remove summary
-- Select/deselect all
+- User dropdown with branch selector
+- DataTable with pagination
 - No prerequisite validation (roles are simple assignments)
 
 ---
 
 ### RoleActionSelectorComponent
 
-Assigns actions to roles (RBAC/FULL mode).
-
-| Property | Value |
-|----------|-------|
-| Selector | `flusys-role-action-selector` |
-| Standalone | Yes |
-| Change Detection | OnPush |
+**Selector:** `flusys-role-action-selector` | Assigns actions to roles (RBAC/FULL mode).
 
-**Dependencies:** `RoleApiService`, `ActionApiService`, `PermissionApiService`, `MessageService`, `ActionPermissionLogicService`
-
-**Features:**
 - Role dropdown with filter
-- Hierarchical TreeTable with checkboxes and `overflow-x-auto` container
-- Responsive columns (Code hidden until md, Requirements hidden until lg)
-- Prerequisite validation with smart dependency handling
-- Request cancellation with AbortController
-- Pre-save validation with auto-fix dialog
-- Change tracking with pending add/remove summary
+- Hierarchical TreeTable with checkboxes
+- Prerequisite validation with auto-fix dialog
 
 ---
 
 ### CompanyActionSelectorComponent
 
-Manages company action whitelisting (when company feature enabled).
+**Selector:** `flusys-company-action-selector` | Manages company action whitelisting.
 
-| Property | Value |
-|----------|-------|
-| Selector | `flusys-company-action-selector` |
-| Standalone | Yes |
-| Change Detection | OnPush |
-
-**Dependencies:** `COMPANY_API_PROVIDER`, `ActionApiService`, `PermissionApiService`, `MessageService`, `ConfirmationService`, `ActionPermissionLogicService`
-
-**Features:**
-- Company dropdown with filter (loaded from COMPANY_API_PROVIDER)
-- Full action tree (not filtered by company whitelist)
-- Hierarchical TreeTable with `overflow-x-auto` container
-- Responsive columns (Code hidden until md, Description hidden until lg)
-- Prerequisite validation with tooltips
+- Company dropdown (from COMPANY_API_PROVIDER)
+- Full action tree (not filtered)
 - Backend prerequisite error handling with auto-fix
-- Request cancellation with AbortController
-- Change tracking with pending whitelist/remove summary
 
 ---
 
 ## Page Components
 
-> Page components are **not exported** from the public API. They are internal and accessed via `IAM_ROUTES` (lazy-loaded by the router).
-
-### IamContainerComponent
-
-Tabbed navigation container for IAM pages.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-iam-container` |
-| Tabs | Actions (always), Roles (RBAC/FULL), Permissions (always) |
-| Change Detection | OnPush |
-
-**Features:**
-- Responsive page title (`text-xl sm:text-2xl`)
-- Horizontally scrollable tabs on mobile (hidden scrollbar)
-- Uses `RouterLink` and `RouterLinkActive` for navigation
-- Tab visibility based on permission mode
-
-**Responsive Patterns:**
-
-```html
-<!-- Page title -->
-<h1 class="text-xl sm:text-2xl font-bold m-0">Identity & Access Management</h1>
-
-<!-- Horizontally scrollable tabs (hidden scrollbar) -->
-<div class="scrollbar-hide flex gap-1 overflow-x-auto flex-nowrap">
-  <!-- tabs -->
-</div>
-```
-
-**Scrollbar hide CSS:**
-```css
-.scrollbar-hide {
-  -ms-overflow-style: none;
-  scrollbar-width: none;
-  &::-webkit-scrollbar { display: none; }
-}
-```
-
----
-
-### ActionListPageComponent
-
-Hierarchical action list with CRUD operations.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-action-list-page` |
-| Features | TreeTable display, create/edit/delete, read-only indicators, company context awareness |
-
-**Responsive features:**
-- TreeTable with `overflow-x-auto -mx-4 sm:mx-0` container
-- Responsive columns: Code (hidden until md), Active (hidden until sm), Read Only (hidden until lg)
-- Responsive header with stacked layout on mobile
-
-Reloads actions when company context changes via effect.
-
----
-
-### ActionFormPageComponent
-
-Action create/edit form with LogicBuilder integration.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-action-form-page` |
-| Features | Create/edit mode, parent action selector, ActionType enum, permissionLogic editor, display order, active flag |
+Page components are **internal** (not exported). Accessed via `IAM_ROUTES`.
 
-**Form fields:** name (required), description, code, actionType, permissionLogic, parentId, serial, isActive, metadata.
-
----
-
-### RoleListPageComponent
-
-Paginated role list with CRUD operations.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-role-list-page` |
-| Features | Paginated table (10/25/50), create/edit/delete, company context filtering, read-only indicators |
-
-**Responsive features:**
-- Table with `overflow-x-auto -mx-4 sm:mx-0` container
-- Responsive columns: Description (hidden until md), Read Only (hidden until sm)
-- Conditional paginator (only shown when data exists)
-
----
-
-### RoleFormPageComponent
-
-Role create/edit form.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-role-form-page` |
-| Features | Create/edit mode, company auto-assignment on create, active flag, display order |
-
-**Form fields:** name (required), description, serial, isActive. Company assigned automatically from context.
-
----
-
-### PermissionPageComponent
-
-Main permission management interface with tabbed layout.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-permission-page` |
-| Features | Dynamic tabs based on permission mode and company feature |
-
-**Tabs:**
-- Role-Actions (RBAC/FULL) - `RoleActionSelectorComponent`
-- User-Roles (RBAC/FULL) - `UserRoleSelectorComponent`
-- User-Actions (DIRECT/FULL) - `UserActionSelectorComponent`
-- Company-Actions (if company feature enabled) - `CompanyActionSelectorComponent`
+| Component | Selector | Features |
+|-----------|----------|----------|
+| `IamContainerComponent` | `lib-iam-container` | Tabbed navigation, responsive tabs |
+| `ActionListPageComponent` | `lib-action-list-page` | TreeTable, CRUD, read-only indicators |
+| `ActionFormPageComponent` | `lib-action-form-page` | Signal forms, LogicBuilder integration |
+| `RoleListPageComponent` | `lib-role-list-page` | Paginated table (10/25/50), CRUD |
+| `RoleFormPageComponent` | `lib-role-form-page` | Signal forms, company auto-assignment |
+| `PermissionPageComponent` | `lib-permission-page` | Dynamic tabs based on permission mode |
 
 ---
 
 ## Interfaces
 
-### ActionType (Enum)
+### Core Types
 
 ```typescript
-enum ActionType {
-  BACKEND = 'backend',     // API endpoint permissions (cached by PermissionGuard)
-  FRONTEND = 'frontend',   // UI feature permissions (returned in my-permissions)
-  BOTH = 'both',           // Both backend and frontend
-}
+enum ActionType { BACKEND = 'backend', FRONTEND = 'frontend', BOTH = 'both' }
+type PermissionAction = 'add' | 'remove';
+type PermissionMode = 'rbac' | 'direct' | 'full';
 ```
 
 ### IAction (extends IBaseEntity)
@@ -605,39 +308,12 @@ interface IAction extends IBaseEntity {
   code: string | null;
   actionType: ActionType;
   permissionLogic: ILogicNode | null;  // AND/OR prerequisite rules
-  parentId: string | null;             // For hierarchy
-  serial: number | null;               // Display order
+  parentId: string | null;
+  serial: number | null;
   isActive: boolean;
-  metadata: Record<string, any> | null;
-}
-```
-
-### IActionTreeDto (extends IAction)
-
-```typescript
-interface IActionTreeDto extends IAction {
-  children: IActionTreeDto[];
-}
-```
-
-### ICreateActionDto / IUpdateActionDto
-
-```typescript
-interface ICreateActionDto {
-  name: string;
-  description?: string;
-  code?: string;
-  actionType?: ActionType;
-  permissionLogic?: ILogicNode;
-  parentId?: string;
-  serial?: number;
-  isActive?: boolean;
-  metadata?: Record<string, any>;
-}
-
-interface IUpdateActionDto extends Partial<ICreateActionDto> {
-  id: string;
+  metadata: Record<string, unknown> | null;
 }
+interface IActionTreeDto extends IAction { children: IActionTreeDto[]; }
 ```
 
 ### IRole (extends IBaseEntity)
@@ -650,159 +326,37 @@ interface IRole extends IBaseEntity {
   companyId: string | null;
   isActive: boolean;
   serial: number | null;
-  metadata: Record<string, any> | null;
+  metadata: Record<string, unknown> | null;
 }
 ```
 
-### ICreateRoleDto / IUpdateRoleDto / IRoleQueryDto
+### Assignment DTOs
 
 ```typescript
-interface ICreateRoleDto {
-  name: string;
-  description?: string;
-  companyId?: string;
-  isActive?: boolean;
-  serial?: number;
-  metadata?: Record<string, any>;
-}
-
-interface IUpdateRoleDto extends Partial<ICreateRoleDto> {
-  id: string;
-}
-
-interface IRoleQueryDto {
-  companyId?: string;
-  isActive?: boolean;
-}
-```
-
-### Permission Interfaces
-
-```typescript
-type PermissionAction = 'add' | 'remove';
-type PermissionMode = 'rbac' | 'direct' | 'full';
-
-interface IPermissionItemDto {
-  id: string;
-  action: PermissionAction;
-}
+interface IPermissionItemDto { id: string; action: PermissionAction; }
 
-// Assignment DTOs
 interface IAssignUserActionsDto {
-  userId: string;
-  companyId?: string;
-  branchId?: string;      // null = company-wide
-  items: IPermissionItemDto[];
+  userId: string; companyId?: string; branchId?: string; items: IPermissionItemDto[];
 }
-
-interface IAssignCompanyActionsDto {
-  companyId: string;
-  items: IPermissionItemDto[];
-}
-
-interface IAssignRoleActionsDto {
-  roleId: string;
-  items: IPermissionItemDto[];
-}
-
+interface IAssignRoleActionsDto { roleId: string; items: IPermissionItemDto[]; }
+interface IAssignCompanyActionsDto { companyId: string; items: IPermissionItemDto[]; }
 interface IAssignUserRolesDto {
-  userId: string;
-  companyId?: string;
-  branchId?: string;
-  items: IPermissionItemDto[];
+  userId: string; companyId?: string; branchId?: string; items: IPermissionItemDto[];
 }
 ```
 
 ### Response DTOs
 
-```typescript
-interface IUserActionResponseDto {
-  id: string;
-  userId: string;
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-  branchId: string | null;
-  createdAt: Date;
-}
-
-interface IRoleActionResponseDto {
-  id: string;
-  roleId: string;
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-  createdAt: Date;
-}
-
-interface ICompanyActionResponseDto {
-  id: string;
-  companyId: string;
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-  createdAt: Date;
-}
-
-interface IUserRoleResponseDto {
-  id: string;
-  userId: string;
-  roleId: string;
-  roleCode: string;
-  roleName: string;
-  branchId: string | null;  // Always null - roles are NOT branch-scoped
-  createdAt: Date;
-}
-```
-
-### My Permissions Response
+All response DTOs include: `id`, entity reference IDs, `actionCode`/`roleCode`, `actionName`/`roleName`, `createdAt`.
 
 ```typescript
 interface IMyPermissionsResponseDto {
   frontendActions: Array<{ id: string; code: string; name: string; description: string }>;
   cachedEndpoints: number;  // Endpoint count for backend PermissionGuard
 }
-```
-
-### Menu & Logic Interfaces
-
-```typescript
-interface IMenuAction {
-  id: string;
-  code: string;
-  name: string;
-  route: string | null;
-  icon: string | null;
-  iconType: number | null;
-  serial: number | null;
-  parentId: string | null;
-  children?: IMenuAction[];
-}
-
-// ILogicNode is imported from @flusys/ng-shared
-```
-
-### Prerequisite Interfaces
-
-```typescript
-interface IPrerequisiteActionDto {
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-}
-
-interface IPrerequisiteValidationError {
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-  requiredActions: IPrerequisiteActionDto[];
-}
 
 interface IPermissionOperationResultDto {
-  success: boolean;
-  added: number;
-  removed: number;
-  message: string;
+  success: boolean; added: number; removed: number; message: string;
   prerequisiteErrors?: IPrerequisiteValidationError[];
 }
 ```
@@ -810,351 +364,195 @@ interface IPermissionOperationResultDto {
 ### Simple Models
 
 ```typescript
-interface IUser {
-  id: string;
-  name: string;
-  email: string;
-}
-
-interface IBranch {
-  id: string;
-  name: string;
-  companyId: string;
-}
-
-interface ICompany {
-  id: string;
-  name: string;
-  slug?: string;
-}
-```
-
-### Query DTOs
-
-```typescript
-interface IGetUserActionsDto {
-  branchId?: string;
-}
-
-interface IGetRoleActionsDto {}
-
-interface IGetUserRolesDto {
-  branchId?: string;  // Ignored by backend
-}
-
-interface IGetMyPermissionsDto {
-  parentCodes?: string[];
-}
+interface IUser { id: string; name: string; email: string; }
+interface IBranch { id: string; name: string; companyId: string; }
+interface ICompany { id: string; name: string; slug?: string; }
 ```
 
 ---
 
 ## Utils & Constants
 
-> Utils are **internal** (not exported from the public API). They are used by components and services within the package.
+Utils are **internal** (not exported from public API).
 
 ### permission-logic.util.ts
 
 | Function | Description |
 |----------|-------------|
-| `validateActionPrerequisites(action, selectedIds, allActions)` | Validate prerequisites respecting AND/OR. Returns `{valid, missingActions}` |
-| `extractRequiredActionIds(logic, allActions)` | Extract all action IDs from a logic tree |
-| `describePrerequisites(logic, allActions)` | Human-readable prerequisite description |
+| `validateActionPrerequisites(action, selectedIds, allActions)` | Validate prerequisites respecting AND/OR |
+| `extractRequiredActionIds(logic, allActions)` | Extract all action IDs from logic tree |
 
 ### tree-utils.ts
 
 | Function | Description |
 |----------|-------------|
 | `flattenTree<T>(tree)` | Flatten hierarchical tree into flat array |
-| `buildItemMap<T>(items)` | Build ID-to-item `Map` for O(1) lookup |
 | `buildTreeFromFlat<T>(flatList)` | Build tree from flat list using `parentId` |
-| `convertActionToTreeNode(actions)` | Convert `IActionTreeDto[]` to PrimeNG `TreeNode<IAction>[]` |
+| `convertActionToTreeNode(actions)` | Convert to PrimeNG `TreeNode<IAction>[]` |
 
 ### Constants
 
 ```typescript
-export const MAX_DROPDOWN_ITEMS = 100;  // Max items for dropdown lists (users, companies, roles, branches)
+export const MAX_DROPDOWN_ITEMS = 100;  // Max items for dropdown lists
 ```
 
-Exported directly as `MAX_DROPDOWN_ITEMS` from the package.
-
 ---
 
-## Backend Integration
-
-### Required Endpoints
-
-**Action CRUD:**
+## Responsive Table Patterns
 
-```
-POST /iam/actions/tree                    # Get hierarchical action tree
-POST /iam/actions/tree-for-permission     # Get actions filtered by company whitelist
-POST /iam/actions/get-all                 # List all actions (flat)
-POST /iam/actions/get/:id                 # Get action by ID
-POST /iam/actions/insert                  # Create action
-POST /iam/actions/update                  # Update action
-POST /iam/actions/delete                  # Delete action
-```
+All IAM tables use consistent Tailwind CSS patterns:
 
-**Role CRUD:**
+```html
+<!-- Container: horizontal scroll on mobile, full-width on desktop -->
+<div class="overflow-x-auto -mx-4 sm:mx-0">
+  <p-treeTable [tableStyle]="{ 'min-width': '50rem' }">...</p-treeTable>
+</div>
 
+<!-- Responsive columns -->
+<th>Name</th>                           <!-- Always visible -->
+<th class="hidden sm:table-cell">Code</th>     <!-- 640px+ -->
+<th class="hidden md:table-cell">Status</th>   <!-- 768px+ -->
+<th class="hidden lg:table-cell">Description</th> <!-- 1024px+ -->
 ```
-POST /iam/roles/get-all                   # List roles (with pagination + company filter)
-POST /iam/roles/get/:id                   # Get role by ID
-POST /iam/roles/insert                    # Create role
-POST /iam/roles/update                    # Update role
-POST /iam/roles/delete                    # Delete role
-```
-
-**Permission Assignments:**
 
-```
-POST /iam/permissions/my-permissions      # Current user's permissions
-POST /iam/permissions/user-actions/assign # Assign/remove user actions
-GET  /iam/permissions/user-actions/:id    # Get user's direct actions
-POST /iam/permissions/user-roles/assign   # Assign/remove user roles
-GET  /iam/permissions/user-roles/:id      # Get user's roles
-POST /iam/permissions/role-actions/assign # Assign/remove role actions
-GET  /iam/permissions/role-actions/:id    # Get role's actions
-POST /iam/permissions/company-actions/assign  # Assign/remove company whitelist
-GET  /iam/permissions/company-actions/:id     # Get company's whitelisted actions
-```
-
-### My Permissions Response Format
-
-```json
-{
-  "success": true,
-  "data": {
-    "frontendActions": [
-      {
-        "id": "uuid",
-        "code": "user.create",
-        "name": "Create User",
-        "description": "Allows creating new users"
-      }
-    ],
-    "cachedEndpoints": 42
-  }
-}
-```
+| Breakpoint | Class | Visibility |
+|------------|-------|------------|
+| Always | (none) | Always visible |
+| sm | `hidden sm:table-cell` | 640px+ |
+| md | `hidden md:table-cell` | 768px+ |
+| lg | `hidden lg:table-cell` | 1024px+ |
 
 ---
 
-## Responsive Table Patterns
+## Angular 21 Signal Forms Pattern
 
-All IAM tables and tree tables use consistent responsive patterns with Tailwind CSS.
+```typescript
+import { form, required } from '@angular/forms';
+
+readonly formModel = {
+  name: '',
+  description: '',
+  code: '',
+  actionType: ActionType.FRONTEND,
+  parentId: null as string | null,
+  serial: null as number | null,
+  isActive: true,
+  permissionLogic: null as ILogicNode | null,
+};
 
-### Table Container Pattern
+readonly actionForm = form(this.formModel, (f) => {
+  required(f.name, { message: 'Name is required' });
+});
 
-```html
-<!-- Wrapper enables horizontal scroll on mobile, full-width on desktop -->
-<div class="overflow-x-auto -mx-4 sm:mx-0">
-  <p-treeTable
-    [value]="treeNodes()"
-    dataKey="id"
-    styleClass="p-treetable-sm"
-    [tableStyle]="{ 'min-width': '50rem' }"
-  >
-    <!-- ... -->
-  </p-treeTable>
-</div>
+readonly canSubmit = computed(() => this.actionForm.valid() && !this.isSaving());
 ```
 
-**Key properties:**
-- `overflow-x-auto` - Enables horizontal scroll when content exceeds container
-- `-mx-4 sm:mx-0` - Edge-to-edge on mobile, normal margins on desktop
-- `[tableStyle]="{ 'min-width': '50rem' }"` - Minimum width ensures consistent layout
-
-### Responsive Column Visibility
-
-```html
-<ng-template #header>
-  <tr>
-    <th class="w-12"><!-- checkbox --></th>
-    <th>Name</th>                           <!-- Always visible -->
-    <th class="hidden sm:table-cell">Code</th>     <!-- Hidden on xs -->
-    <th>Type</th>                           <!-- Always visible -->
-    <th class="hidden md:table-cell">Status</th>   <!-- Hidden until md -->
-    <th class="hidden lg:table-cell">Description</th> <!-- Hidden until lg -->
-  </tr>
-</ng-template>
-```
+---
 
-**Breakpoint classes:**
-| Class | Visibility |
-|-------|------------|
-| (none) | Always visible |
-| `hidden sm:table-cell` | Visible at 640px+ |
-| `hidden md:table-cell` | Visible at 768px+ |
-| `hidden lg:table-cell` | Visible at 1024px+ |
+## Backend Integration
 
-### Header Layout Pattern
+### Required Endpoints
 
-```html
-<div class="flex flex-col md:flex-row justify-between items-start md:items-center gap-3 mb-4">
-  <div>
-    <h5 class="m-0 mb-1">Section Title</h5>
-    <p class="text-sm text-muted-color m-0">{{ count }} items available</p>
-  </div>
-  <div class="flex flex-wrap gap-2">
-    <!-- Action buttons -->
-  </div>
-</div>
 ```
+# Action CRUD
+POST /iam/actions/tree
+POST /iam/actions/tree-for-permission
+POST /iam/actions/get-all
+POST /iam/actions/get/:id
+POST /iam/actions/insert
+POST /iam/actions/update
+POST /iam/actions/delete
 
-### Dark Mode Styling
+# Role CRUD
+POST /iam/roles/get-all
+POST /iam/roles/get/:id
+POST /iam/roles/insert
+POST /iam/roles/update
+POST /iam/roles/delete
 
-```css
-/* Light mode */
-.validation-warning {
-  background-color: var(--p-yellow-50, #fefce8);
-  border-left: 4px solid var(--p-yellow-500, #eab308);
-  color: var(--p-yellow-700, #a16207);
-}
-
-/* Dark mode */
-:host-context(.p-dark) .validation-warning {
-  background-color: rgba(234, 179, 8, 0.1);
-  color: var(--p-yellow-400, #facc15);
-}
+# Permission Assignments
+POST /iam/permissions/my-permissions
+POST /iam/permissions/user-actions/assign
+POST /iam/permissions/get-user-actions
+POST /iam/permissions/user-roles/assign
+POST /iam/permissions/get-user-roles
+POST /iam/permissions/role-actions/assign
+POST /iam/permissions/get-role-actions
+POST /iam/permissions/company-actions/assign
+POST /iam/permissions/get-company-actions
 ```
 
-**Color classes (Tailwind):**
-| Purpose | Class |
-|---------|-------|
-| Muted text | `text-muted-color` |
-| Success | `text-green-500` |
-| Danger | `text-red-500` |
-| Warning | `text-orange-500` |
-| Primary | `text-primary` |
-
 ---
 
 ## Best Practices
 
 ### Permission Loading
 
-Load permissions in a guard to block navigation until ready:
-
 ```typescript
-// appInitGuard
+// In guard - block navigation until ready
 if (!permissionState.isLoaded()) {
-  try {
-    await firstValueFrom(permissionState.loadPermissions());
-  } catch (error) {
-    console.error('Failed to load permissions:', error);
-    // Continue with graceful degradation - don't block the app
-  }
+  await firstValueFrom(permissionState.loadPermissions());
 }
-return true;
 ```
 
-- Cache permissions in memory (PermissionStateService handles this)
-- Clear permissions on logout
-- Never store permissions in localStorage (security risk)
-- Never load permissions in component `ngOnInit` (causes race conditions)
+- Cache in memory (PermissionStateService handles this)
+- Clear on logout
+- Never store in localStorage (security risk)
+- Never load in component `ngOnInit` (race conditions)
 
 ### Permission Checks
 
 ```typescript
-// Single action
-validator.hasAction('user.create');
-
-// ALL required
-validator.hasAllActions(['user.create', 'user.update']);
-
-// ANY required
-validator.hasAnyAction(['user.view', 'user.list']);
+validator.hasAction('user.create');                       // Single
+validator.hasAllActions(['user.create', 'user.update']); // ALL required
+validator.hasAnyAction(['user.view', 'user.list']);      // ANY required
 ```
 
-Cache check results in computed signals rather than calling in templates or tight loops.
+Cache check results in computed signals, not in templates.
 
 ### Menu Filtering
 
 ```typescript
-// Set menu with requiredAction or logicNode
 this.layoutService.setMenu(menuItems);
-
-// Set permission checker (layout handles filtering automatically)
-this.layoutService.setPermissionChecker((actionCode) =>
-  validator.hasAction(actionCode)
-);
+this.layoutService.setPermissionChecker((code) => validator.hasAction(code));
 ```
 
-Do not filter menus manually - let layout handle it.
-
 ### Action Naming
 
 Format: `module.operation` or `module.entity.operation`
 
 ```typescript
-// Good
-'user.create'
-'user.update'
-'report.export'
-'admin.system.config'
-
-// Bad
-'create'           // Too generic
-'userCreate'       // Not dot notation
-'users'            // Entity name, not action
+// Good: 'user.create', 'report.export', 'admin.system.config'
+// Bad: 'create' (generic), 'userCreate' (not dot notation)
 ```
 
 ### LogicNode Pattern
 
-Complex permission rules using AND/OR operators:
-
 ```typescript
 // User needs 'user.create' AND ('user.update' OR 'user.delete')
 const logic: ILogicNode = {
   type: 'AND',
   children: [
     { type: 'ACTION', value: 'user.create' },
-    {
-      type: 'OR',
-      children: [
-        { type: 'ACTION', value: 'user.update' },
-        { type: 'ACTION', value: 'user.delete' },
-      ],
-    },
+    { type: 'OR', children: [
+      { type: 'ACTION', value: 'user.update' },
+      { type: 'ACTION', value: 'user.delete' },
+    ]},
   ],
 };
 ```
 
 ---
 
-## Common Issues
-
-| Problem | Cause | Solution |
-|---------|-------|----------|
-| `permissionState.isLoaded()` returns false | IAM not enabled or endpoint failing | Check `services.iam.enabled: true` in environment, verify `POST /iam/permissions/my-permissions` works |
-| Empty menu after login | Permissions not loaded or no matching actions | Check `permissionState.isLoaded()`, verify user has frontend actions, check `requiredAction` matches action codes |
-| Menu items not filtered | Permission checker not set | Call `layoutService.setPermissionChecker()` after loading permissions |
-| 401 on IAM endpoints with external auth | Auth token not forwarded | Ensure your auth interceptor adds `Authorization` header to IAM requests |
-| Provider not configured error | Missing DI registration | Add required providers to `app.config.ts` (USER_PROVIDER, LAYOUT_AUTH_STATE) |
-| Empty user/company dropdowns | API response format mismatch | Ensure adapters return `IListResponse<T>` format with `data` array |
-| TreeTable has excessive whitespace | Using `scrollHeight="flex"` without fixed-height parent | Remove `scrollHeight="flex"` and `[scrollable]="true"`, use `overflow-x-auto` container instead |
-| Table not horizontally scrollable on mobile | Missing responsive wrapper | Add `<div class="overflow-x-auto -mx-4 sm:mx-0">` around table |
-| Columns visible on mobile causing overflow | Missing responsive column classes | Add `hidden sm:table-cell` or `hidden md:table-cell` to non-essential columns |
-
----
-
 ## Configuration
 
-### Frontend Environment
-
 ```typescript
-// environment.ts
-services: {
-  iam: { baseUrl: 'http://localhost:2002/iam', enabled: true },
-}
+// Frontend: environment.ts
+services: { iam: { baseUrl: 'http://localhost:2002/iam', enabled: true } }
 ```
 
-### Backend Environment
-
 ```bash
-# .env
+# Backend: .env
 IAM_PERMISSION_MODE=FULL  # DIRECT, RBAC, or FULL
 ```
 
@@ -1170,60 +568,41 @@ IAM_PERMISSION_MODE=FULL  # DIRECT, RBAC, or FULL
 
 ### provideIamProviders()
 
-Registers provider adapters that enable other packages (ng-auth) to access IAM functionality without direct dependencies.
+Registers adapters for cross-package communication (e.g., ng-auth profile page).
 
 ```typescript
 import { provideIamProviders } from '@flusys/ng-iam';
-
-// app.config.ts
-export const appConfig: ApplicationConfig = {
-  providers: [
-    ...provideIamProviders(),  // Register IAM providers
-  ],
-};
+providers: [...provideIamProviders()]
 ```
 
-**Registers:**
-
-| Token | Adapter | Purpose |
-|-------|---------|---------|
-| `PROFILE_PERMISSION_PROVIDER` | `ProfilePermissionProviderAdapter` | User roles/actions for profile page |
-
-### ProfilePermissionProviderAdapter
-
-Implements `IProfilePermissionProvider` from ng-shared. Enables ng-auth's profile page to display user permissions.
+Registers `PROFILE_PERMISSION_PROVIDER` with `ProfilePermissionProviderAdapter`.
 
-```typescript
-interface IProfilePermissionProvider {
-  getUserRoles(userId: string, branchId?: string): Observable<ISingleResponse<IProfileRoleInfo[]>>;
-  getUserActions(userId: string, branchId?: string): Observable<ISingleResponse<IProfileActionInfo[]>>;
-}
-```
+---
 
-**Usage in ng-auth profile page:**
+## Common Issues
 
-```typescript
-// Optional injection - graceful degradation when IAM disabled
-private readonly permissionProvider = inject(PROFILE_PERMISSION_PROVIDER, { optional: true });
-
-// Load user permissions
-if (this.permissionProvider) {
-  this.permissionProvider.getUserRoles(userId, branchId).subscribe(response => {
-    this.roles.set(response.data ?? []);
-  });
-}
-```
+| Problem | Solution |
+|---------|----------|
+| `permissionState.isLoaded()` returns false | Check `services.iam.enabled: true`, verify `/iam/permissions/my-permissions` works |
+| Empty menu after login | Verify user has frontend actions, check `requiredAction` matches action codes |
+| Menu items not filtered | Call `layoutService.setPermissionChecker()` after loading permissions |
+| 401 on IAM endpoints | Ensure auth interceptor adds `Authorization` header |
+| Provider not configured error | Add required providers to `app.config.ts` |
+| Empty dropdowns | Ensure adapters return `IListResponse<T>` format |
+| Table not scrollable on mobile | Add `overflow-x-auto -mx-4 sm:mx-0` wrapper |
+| Columns overflow on mobile | Add `hidden sm:table-cell` to non-essential columns |
 
 ---
 
 ## See Also
 
-- **[CORE-GUIDE.md](./CORE-GUIDE.md)** - Configuration system (APP_CONFIG)
-- **[AUTH-GUIDE.md](./AUTH-GUIDE.md)** - Authentication and provider adapters
-- **[SHARED-GUIDE.md](./SHARED-GUIDE.md)** - Provider interface definitions
-- **[LAYOUT-GUIDE.md](./LAYOUT-GUIDE.md)** - Menu system and filtering
+- [CORE-GUIDE.md](./CORE-GUIDE.md) - Configuration system (APP_CONFIG)
+- [AUTH-GUIDE.md](./AUTH-GUIDE.md) - Authentication and provider adapters
+- [SHARED-GUIDE.md](./SHARED-GUIDE.md) - Provider interface definitions
+- [LAYOUT-GUIDE.md](./LAYOUT-GUIDE.md) - Menu system and filtering
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25
+**Version:** 3.0.0
 **Angular Version:** 21