Update README and documentation for email verification and role management

- Enhanced README to reflect the introduction of email verification and hybrid RBAC.
- Updated API documentation to clarify login requirements and JWT claims, including new roles and email verification processes.
- Added details on the X-Tenant-Id header and its significance for SystemAdmin operations.
- Revised deployment documentation to include email verification settings and their implications in production.
- Introduced new file for temporary cookies generated during development.

Author: APK-Arjun-Developer

README.md

@@ -1,13 +1,13 @@
 # Multi-Tenant Platform
 
-.NET **10** multi-tenant SaaS API with JWT authentication, permission-based RBAC, tenant isolation, and automated production deploys.
+.NET **10** multi-tenant SaaS API with JWT authentication, hybrid RBAC, complete tenant isolation, email verification, and automated production deploys.
 
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
-| [docs/PROJECT.md](docs/PROJECT.md) | Architecture, auth, data model, migrations & seeds |
-| [docs/API.md](docs/API.md) | v1 endpoints, envelope, login, profiles, addresses |
+| [docs/PROJECT.md](docs/PROJECT.md) | Architecture, auth model, tenant isolation, data model, migrations & seeds |
+| [docs/API.md](docs/API.md) | v1 endpoints, envelope, login, email verification, invitations, profiles, addresses |
 | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | GitHub Actions → MonsterASP.NET (FTP) production deploy |
 
 ## How it works (workflow)
@@ -26,8 +26,8 @@
 
 On every app start (local or production):
 
-1. **Migrations** — pending EF migrations from `__EFMigrationsHistory` are applied (`ApplyMigrationsOnStartup`).
-2. **Seeds** — pending versioned seeds from `SeedHistory` are applied (`ApplySeedsOnStartup`). Already-applied seeds are skipped.
+1. **Migrations** — pending EF migrations from `__EFMigrationsHistory` are applied.
+2. **Seeds** — pending versioned seeds from `SeedHistory` are applied. Already-applied seeds are skipped.
 
 Schema baseline: single migration **`InitialCreate`**. Seed versions are tracked like migrations.
 
@@ -45,6 +45,8 @@ dotnet user-secrets set "ConnectionStrings:DefaultConnection" "Server=localhost\
 
 Or rely on [appsettings.Development.json](src/Api/appsettings.Development.json) for local SQL/JWT (dev only).
 
+In Development, `Features:RequireEmailVerification` is `false` — newly created users can log in immediately without completing email verification. Set it to `true` (the production default) to test the OTP flow.
+
 ### 2. Run the API
 
 ```powershell
@@ -66,7 +68,7 @@ Open:
 - Health: `GET /api/v1/health`
 - API base: `/api/v1`
 
-**Default SuperAdmin** (after seeds): `admin@system.com` / value of `Seeding:AdminPassword` (e.g. `Admin123!` in Development).
+**Default SystemAdmin** (after seeds): `admin@system.com` / value of `Seeding:AdminPassword` (e.g. `Admin123!` in Development).
 
 ### 3. Add a migration (developers)
 
@@ -89,18 +91,24 @@ See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for production deploy.
 
 - Deploy: push to **`master`** or run **Deploy to MonsterASP (FTPS)** workflow.
 - Required GitHub secrets: `FTP_*`, `PRODUCTION_CONNECTION_STRING`, `JWT_KEY`, `ADMIN_PASSWORD`, recommended `SITE_URL`.
+- Email verification is **on** by default in production (`Features:RequireEmailVerification: true`). New users must verify their email via OTP before logging in.
 - Swagger: `https://<your-site>/swagger` — open (set `Swagger:EnabledInProduction` to `false` to hide it).
 - Fresh database: delete and recreate the database in the MonsterASP control panel (or drop all tables in SSMS), then redeploy.
 
 ## Highlights
 
-- **Permissions**: PascalCase (`Users.View`); checked per request, **not** in JWT
-- **JWT claims**: `user_id`, `tenant_id`, `role_id`, role names
+- **Hybrid RBAC**: Layer 1 = `SystemRole` on `ApplicationUser` (ceiling authority); Layer 2 = custom roles with permissions (TenantUser business capabilities only)
+- **Three system roles**: `SystemAdmin` (platform), `TenantAdmin` (manages one tenant), `TenantUser` (operational)
+- **X-Tenant-Id header**: SystemAdmin must supply `X-Tenant-Id` on all tenant-scoped requests; TenantAdmin/TenantUser are always pinned to their JWT `tenant_id`
+- **Email verification**: OTP-based (6-digit, 15 min); skipped in Development via `Features:RequireEmailVerification: false`
+- **Permissions**: PascalCase (`Users.View`); checked per request from DB (cached), never in JWT
+- **JWT claims**: `user_id`, `tenant_id`, `system_role`, `full_name`, `role_ids`
 - **Versioned seeds**: `SeedHistory` table; pending seeds only (like migrations)
 - **Profiles**: user & tenant profile images via `Files` FK; `profileUrl` in responses
 - **Addresses**: optional user/tenant address with `fullAddress` combined string
+- **Invitations**: TenantAdmin invites TenantUsers; SystemAdmin invites TenantAdmins
 - **Onboarding**: `POST /api/v1/tenants` with `user`, `tenant`, `roles[]` (permission GUIDs)
-- **No public registration** — SuperAdmin onboards tenants
+- **No public registration** — SystemAdmin onboards tenants
 
 ## Project structure
 

Tempcookies_admin.txt

@@ -0,0 +1,6 @@
+# Netscape HTTP Cookie File
+# https://curl.se/docs/http-cookies.html
+# This file was generated by libcurl! Edit at your own risk.
+
+#HttpOnly_localhost	FALSE	/	FALSE	1782583388	refresh_token	H9%2Brv5zORv6HZtv4SqyQ20A%2BCQ%2BEx3PUvVhvqzmnnnoUlkjD1WcPkwAg4SVPsqiTru2NJqO6DvpknOvYV%2BOOfg%3D%3D
+#HttpOnly_localhost	FALSE	/	FALSE	1781979488	access_token	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhOTA3OWIyYS1jZmJmLTQ1MzktYTRkOS1iYzliMTA3Zjg2ZTgiLCJlbWFpbCI6ImFkbWluQHN5c3RlbS5jb20iLCJqdGkiOiI1NmQ4ZmJmYS1hNjViLTQyYjQtOTFjOC04ZjBiMGRhNjM5OWUiLCJ1c2VyX2lkIjoiYTkwNzliMmEtY2ZiZi00NTM5LWE0ZDktYmM5YjEwN2Y4NmU4IiwidGVuYW50X2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiZnVsbF9uYW1lIjoiU3lzdGVtIEFkbWluaXN0cmF0b3IiLCJzeXN0ZW1fcm9sZSI6IjEiLCJleHAiOjE3ODE5Nzk0ODgsImlzcyI6Ik11bHRpVGVuYW50UGxhdGZvcm0iLCJhdWQiOiJNdWx0aVRlbmFudFBsYXRmb3JtVXNlcnMifQ.dDcS6E4cUn8VsgYDVQb0yfYUEQBRLnYqEOyYVPvYmrE