refactor(auth): include email in session data and update related documentation

Docs/api.md

@@ -395,9 +395,12 @@ Provide the current session identity for frontend consumers.
 Semantics (frontend-friendly):
 
 - 200 with `{ user: null }` when unauthenticated
-- 200 with `{ user: { userId, role, branchId } }` when authenticated
+- 200 with `{ user: { userId, role, branchId, email } }` when authenticated
 
-This avoids using 401 as control-flow for basic "am I logged in?" checks.
+Notes:
+
+- `email` is optional and may be `null`.
+- This avoids using 401 as control-flow for basic "am I logged in?" checks.
 
 ---
 

Docs/auth.md

@@ -181,11 +181,17 @@ Sessions are implemented as signed JWTs stored in HTTP-only cookies.
 	"userId": "<MongoDB ObjectId as string>",
 	"role": "branch | admin | dev",
 	"branchId": "NL01 | null",
+	"email": "name@company.tld | null",
 	"iat": 1700000000,
 	"exp": 1700003600
 }
 ```
 
+Notes:
+
+- `email` is optional and may be `null`.
+- The session email is used for displaying read-only account information in the UI (Profile).
+
 ### 5.2 JWT signing
 
 - Algorithm: `HS256`.
@@ -206,7 +212,7 @@ Attributes:
 
 Implementation lives in `lib/auth/session.js`:
 
-- `createSession({ userId, role, branchId })`
+- `createSession({ userId, role, branchId, email })`
 - `getSession()`
 - `destroySession()`
 
@@ -294,9 +300,21 @@ Response (unauthenticated):
 Response (authenticated):
 
 ```json
-{ "user": { "userId": "...", "role": "branch|admin|dev", "branchId": "NL01" } }
+{
+	"user": {
+		"userId": "...",
+		"role": "branch|admin|dev",
+		"branchId": "NL01",
+		"email": "nl01@example.com"
+	}
+}
 ```
 
+Notes:
+
+- `email` is optional and may be `null`.
+- The endpoint intentionally returns only minimal identity information needed by the UI.
+
 Security note:
 
 - The endpoint intentionally returns only the minimal session identity.
@@ -349,6 +367,7 @@ Response:
 Behavior:
 
 1. Validate JSON and required fields.
+
 2. Load the current user by `session.userId`.
    - If the user cannot be found: treat as invalid session and return `401 AUTH_UNAUTHENTICATED`.
 
@@ -359,6 +378,7 @@ Behavior:
    - If weak: return `400 VALIDATION_WEAK_PASSWORD` with structured `details`.
 
 5. Hash and persist the new password.
+
 6. Clear flags / sensitive reset state:
    - `mustChangePassword = false`
    - `passwordResetToken = null`

Docs/frontend-api-usage.md

@@ -290,9 +290,20 @@ Success:
 Success (authenticated):
 
 ```json
-{ "user": { "userId": "...", "role": "branch|admin|dev", "branchId": "NL01" } }
+{
+	"user": {
+		"userId": "...",
+		"role": "branch|admin|dev",
+		"branchId": "NL01",
+		"email": "nl01@example.com"
+	}
+}
 ```
 
+Notes:
+
+- `email` is optional and may be `null`.
+
 Success (unauthenticated):
 
 ```json
@@ -789,4 +800,4 @@ Rules:
 
 - Password reset / recovery:
   - The reset flow (request/reset via token/email) is intentionally planned as a separate follow-up ticket/phase.
-  - Rationale: higher security surface (token handling, non-leakage), external SMTP/IT dependencies, and separate rate limiting ticket (RHL-031) to avoid scope creep.
+  - Rationale: higher security surface (token handling and non-leakage), external SMTP/IT dependencies, and separate rate limiting ticket (RHL-031) to avoid scope creep.

Docs/frontend-ui.md

@@ -50,6 +50,7 @@ Timeline:
 
 - **Profile password change (RHL-009)**:
   - Route: `/profile` (protected)
+  - Profile shows read-only account/session metadata (role, branch, email).
   - Password change form calls `apiClient.changePassword({ currentPassword, newPassword })`.
   - Uses inline validation for actionable form errors.
   - Uses toast notifications (Sonner) for success/error feedback.
@@ -375,6 +376,11 @@ Behavior:
 3. If `{ user: null }`:
    - redirect to `/login?reason=expired&next=<current-url>`
 
+Notes:
+
+- `GET /api/auth/me` returns minimal identity data for the UI:
+  - `userId`, `role`, `branchId`, and (optionally) `email`.
+
 The `next` parameter:
 
 - includes the original `pathname` and query string
@@ -636,10 +642,13 @@ Rationale:
 
 - `components/profile/ProfilePage.jsx`
   - Renders:
-    - Account/session info card
-    - Email placeholder card
+    - Account/session info card (role, branch, read-only email)
     - Password change card
 
+  Note:
+  - The email address is displayed read-only.
+  - Email changes are not supported in the UI; email is managed centrally (IT / developers).
+
 - `components/profile/ChangePasswordCard.jsx`
   - Contains a password change form:
     - `currentPassword`
@@ -652,6 +661,7 @@ Rationale:
     - new password equals current password
 
   - Calls `apiClient.changePassword({ currentPassword, newPassword })`.
+
   - Uses Sonner toasts for success/error feedback.
 
 ### 11.3 Password policy UX
@@ -804,7 +814,7 @@ Verify flows in the browser:
 Profile checks (RHL-009):
 
 - Open `/profile`
-  - Confirm account info is visible
+  - Confirm account info is visible (including read-only email)
 
 - Change password:
   - wrong current password → inline error + toast
@@ -849,6 +859,7 @@ Deploy and verify on the server URL.
 Verify:
 
 - Explorer navigation and PDF open
+
 - Search UI:
   - scopes
   - limit selection