From e275a7ea2ca9f7795c82d30faee6950eec595d65 Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Mon, 20 Jul 2026 14:32:14 +0300
Subject: [PATCH 01/11] =?UTF-8?q?fix(web):=20render=20Payments=20+=20activ?=
 =?UTF-8?q?ity=20feeds=20=E2=80=94=20align=20PaginatedResponse=20to=20`ite?=
 =?UTF-8?q?ms`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The shared PaginatedResponse<T> typed its array field as `data`, but the
backend list services (payments.service, timeline.service) return `items`.
The client `unwrap` transform keys on a top-level `data` property only to
peel the optional ApiEnvelope, so it passed the `{items,total,page,limit}`
object through untouched — and 5 FE reads of `?.data ?? []` then resolved
to `undefined ?? []`, rendering the Payments list and every "Recent
activity" feed empty on production.

Fix: flip the contract array field to `items`, update the 5 paginated reads
(payments-page, finance/staff/tenant dashboards, timeline-feed), and add BE
regression specs asserting the list envelope is keyed by `items`. The two
notification reads keep `.data` — NotificationListResponse is a distinct
shape with a real `data` field. Web-only (packages/contracts + apps/web).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../modules/payments/payments.service.spec.ts | 45 +++++++++++++++++++
 .../modules/timeline/timeline.service.spec.ts | 36 +++++++++++++++
 .../dashboard/finance-dashboard.tsx           |  2 +-
 .../components/dashboard/payments-page.tsx    |  2 +-
 .../components/dashboard/staff-dashboard.tsx  |  2 +-
 .../components/dashboard/tenant-dashboard.tsx |  2 +-
 .../components/dashboard/timeline-feed.tsx    |  2 +-
 packages/contracts/src/index.ts               |  9 +++-
 8 files changed, 94 insertions(+), 6 deletions(-)
 create mode 100644 apps/api/src/modules/payments/payments.service.spec.ts
 create mode 100644 apps/api/src/modules/timeline/timeline.service.spec.ts

diff --git a/apps/api/src/modules/payments/payments.service.spec.ts b/apps/api/src/modules/payments/payments.service.spec.ts
new file mode 100644
index 00000000..407de712
--- /dev/null
+++ b/apps/api/src/modules/payments/payments.service.spec.ts
@@ -0,0 +1,45 @@
+import { PaymentsService } from './payments.service';
+
+/**
+ * Regression guard for the paginated-list contract drift bug: the backend list
+ * envelope MUST expose its rows under `items` (matching PaginatedResponse<T> in
+ * @repo/contracts and the FE reads), never `data`. A `data` array here silently
+ * renders empty lists on the client (the FE reads `.items`), and would also be
+ * mis-peeled by the client's `unwrap` ApiEnvelope transform.
+ */
+describe('PaymentsService', () => {
+  const orgId = 'org-1';
+
+  function makeService(rows: unknown[] = [], total = 0) {
+    const prisma: any = {
+      payment: {
+        findMany: jest.fn().mockResolvedValue(rows),
+        count: jest.fn().mockResolvedValue(total),
+      },
+    };
+    return { service: new PaymentsService(prisma), prisma };
+  }
+
+  it('returns the paginated envelope keyed by `items`, not `data`', async () => {
+    const rows = [{ id: 'pay-1' }, { id: 'pay-2' }];
+    const { service } = makeService(rows, 2);
+
+    const result = await service.findAll(orgId, 1, 20);
+
+    expect(result).toEqual({ items: rows, total: 2, page: 1, limit: 20 });
+    expect(result.items).toEqual(rows);
+    expect(result).not.toHaveProperty('data');
+  });
+
+  it('applies page/limit as skip/take and echoes them back', async () => {
+    const { service, prisma } = makeService([], 0);
+
+    const result = await service.findAll(orgId, 3, 10);
+
+    expect(prisma.payment.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { orgId }, skip: 20, take: 10 }),
+    );
+    expect(result.page).toBe(3);
+    expect(result.limit).toBe(10);
+  });
+});
diff --git a/apps/api/src/modules/timeline/timeline.service.spec.ts b/apps/api/src/modules/timeline/timeline.service.spec.ts
new file mode 100644
index 00000000..13460e0d
--- /dev/null
+++ b/apps/api/src/modules/timeline/timeline.service.spec.ts
@@ -0,0 +1,36 @@
+import { TimelineService } from './timeline.service';
+import { AuthenticatedUser } from '@/common/types/authenticated-user.type';
+
+/**
+ * Regression guard for the paginated-list contract drift bug: the timeline feed
+ * envelope MUST expose its rows under `items` (matching PaginatedResponse<T> in
+ * @repo/contracts and the FE reads), never `data`. A `data` array here silently
+ * renders every "Recent activity" feed empty on the client.
+ */
+describe('TimelineService', () => {
+  const orgId = 'org-1';
+
+  function makeService(rows: unknown[] = [], total = 0) {
+    const prisma: any = {
+      event: {
+        findMany: jest.fn().mockResolvedValue(rows),
+        count: jest.fn().mockResolvedValue(total),
+      },
+    };
+    return { service: new TimelineService(prisma), prisma };
+  }
+
+  const caller = (roles: string[]): AuthenticatedUser =>
+    ({ sub: 'user-1', roles } as unknown as AuthenticatedUser);
+
+  it('returns the paginated envelope keyed by `items`, not `data`', async () => {
+    const rows = [{ id: 'evt-1' }, { id: 'evt-2' }];
+    const { service } = makeService(rows, 2);
+
+    const result = await service.findForCaller(orgId, caller(['org_admin']), 1, 20);
+
+    expect(result).toEqual({ items: rows, total: 2, page: 1, limit: 20 });
+    expect(result.items).toEqual(rows);
+    expect(result).not.toHaveProperty('data');
+  });
+});
diff --git a/apps/web/src/components/dashboard/finance-dashboard.tsx b/apps/web/src/components/dashboard/finance-dashboard.tsx
index 81d50e52..49b8fd15 100644
--- a/apps/web/src/components/dashboard/finance-dashboard.tsx
+++ b/apps/web/src/components/dashboard/finance-dashboard.tsx
@@ -57,7 +57,7 @@ export function FinanceDashboard({ me, locale, dict }: FinanceDashboardProps) {
   const { data: timelineData, isLoading: timelineLoading } =
     useListTimelineQuery({ limit: 5 });
 
-  const timelineEvents = (timelineData?.data ?? []).slice(0, 5);
+  const timelineEvents = (timelineData?.items ?? []).slice(0, 5);
   const overdueTotal = overdueOutstanding(overdue);
   const overdueCount = overdue?.length ?? 0;
   const netMtd = summary ? Number(summary.mtdNet) : 0;
diff --git a/apps/web/src/components/dashboard/payments-page.tsx b/apps/web/src/components/dashboard/payments-page.tsx
index 0a1b651a..613a3c38 100644
--- a/apps/web/src/components/dashboard/payments-page.tsx
+++ b/apps/web/src/components/dashboard/payments-page.tsx
@@ -55,7 +55,7 @@ export function PaymentsPage({ locale, readonly = false }: PaymentsPageProps) {
   const dateLocale = locale === 'ar' ? ar : undefined;
   const { data: paymentsData, isLoading } = useListPaymentsQuery();
 
-  const payments = paymentsData?.data ?? [];
+  const payments = paymentsData?.items ?? [];
 
   const now = new Date();
   const currentMonth = now.getMonth();
diff --git a/apps/web/src/components/dashboard/staff-dashboard.tsx b/apps/web/src/components/dashboard/staff-dashboard.tsx
index 8fc98d35..e6bcb012 100644
--- a/apps/web/src/components/dashboard/staff-dashboard.tsx
+++ b/apps/web/src/components/dashboard/staff-dashboard.tsx
@@ -51,7 +51,7 @@ export function StaffDashboard({ me, locale, dict }: StaffDashboardProps) {
 
   const stats = maintenanceStats(requests);
   const attention = topActiveRequests(requests, 5);
-  const timelineEvents = timelineData?.data ?? [];
+  const timelineEvents = timelineData?.items ?? [];
   const userName = me?.user?.fullName ?? '';
 
   return (
diff --git a/apps/web/src/components/dashboard/tenant-dashboard.tsx b/apps/web/src/components/dashboard/tenant-dashboard.tsx
index 6866af52..c266eebe 100644
--- a/apps/web/src/components/dashboard/tenant-dashboard.tsx
+++ b/apps/web/src/components/dashboard/tenant-dashboard.tsx
@@ -161,7 +161,7 @@ export function TenantDashboard({ me, locale, dict }: TenantDashboardProps) {
     defaultValues: EMPTY_VALUES,
   });
 
-  const events = timelineData?.data ?? [];
+  const events = timelineData?.items ?? [];
   const requests = overview?.maintenanceRequests ?? [];
   const openCount = requests.filter((r) =>
     OPEN_STATUSES.includes(r.status),
diff --git a/apps/web/src/components/dashboard/timeline-feed.tsx b/apps/web/src/components/dashboard/timeline-feed.tsx
index 5cdb8839..b320f57f 100644
--- a/apps/web/src/components/dashboard/timeline-feed.tsx
+++ b/apps/web/src/components/dashboard/timeline-feed.tsx
@@ -41,7 +41,7 @@ export function TimelineFeed({ locale, limit = 10 }: TimelineFeedProps) {
     );
   }
 
-  const events = data?.data ?? [];
+  const events = data?.items ?? [];
 
   if (events.length === 0) {
     return (
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 1dae59fd..d927dab2 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -21,8 +21,15 @@ export type ApiEnvelope<TData> = {
   message?: string;
 };
 
+/**
+ * Paginated list envelope. The array field is `items` (NOT `data`) — this must
+ * match the backend list services (payments.service, timeline.service) exactly,
+ * or FE consumers reading the array get an empty list. Do not rename to `data`:
+ * the `unwrap` transform on the client keys on a top-level `data` property to
+ * peel the optional ApiEnvelope, so a `data` array here would be mis-unwrapped.
+ */
 export type PaginatedResponse<T> = {
-  data: T[];
+  items: T[];
   total: number;
   page: number;
   limit: number;

From a5a9bf073efe26c8462f00920509b52105547aed Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 01:16:35 +0300
Subject: [PATCH 02/11] =?UTF-8?q?fix(F1):=20quick-win=20correctness=20?=
 =?UTF-8?q?=E2=80=94=20logout=20origin,=20subscription-payments=20nav,=20s?=
 =?UTF-8?q?ign-out=20reachability,=20lease=20date=20guard,=20task=20renter?=
 =?UTF-8?q?=20autofill,=20expense=E2=86=92WO=20label?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sprint F1 of the Property Manager behavior-fix roadmap (workflow-anchored fixes
from docs/propertymanager_bugs.txt). All six are contained, verified changes:

- F1.1 [Q34/35] Logout returns to the PUBLIC origin. federated-logout now builds
  post_logout_redirect_uri from x-forwarded-host/host + x-forwarded-proto instead
  of request.url (which leaked the Next container host behind nginx). KC client
  prorentallb-web now also has post.logout.redirect.uris="+" (whitelists the
  redirect) — set additively out-of-band.
- F1.2 [Q11/24] Nav "Payments" → "Subscription Payments" (en/ar) and moved beside
  Subscription in the sidebar; the page is subscription-only.
- F1.3 [Q17] Sidebar Sign-out always reachable: dashboard layout is now a fixed
  app-shell (h-screen/overflow-hidden), <main> scrolls, <nav> scrolls independently.
- F1.4 [Q8] Server guard: lease endDate must be strictly after startDate on
  create() and update() (assertValidDateRange) — the DTO only validated dates in
  isolation. Regression spec added (api leases 24/24).
- F1.5 [Q12] New maintenance-request autofills the renter from the chosen
  apartment's active lease.
- F1.6 [Q16a] Expense→work-order cell shows the #<id> label, not the raw cuid
  (full WorkOrder.number is F2.1).

i18n parity held (en==ar 1023). Verified: web check-types clean, web vitest 30/30,
api leases jest 24/24, gitnexus detect_changes footprint matches intent.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/modules/leases/leases.service.spec.ts | 15 +++++++++
 apps/api/src/modules/leases/leases.service.ts | 31 +++++++++++++++++++
 apps/web/src/app/[lang]/dashboard/layout.tsx  |  8 +++--
 .../app/api/auth/federated-logout/route.ts    | 17 +++++++++-
 .../components/dashboard/expenses-page.tsx    |  4 ++-
 .../src/components/dashboard/tasks-page.tsx   | 22 ++++++++++++-
 .../components/layout/dashboard-sidebar.tsx   | 19 ++++++------
 apps/web/src/i18n/dictionaries/ar.json        |  2 +-
 apps/web/src/i18n/dictionaries/en.json        |  2 +-
 9 files changed, 104 insertions(+), 16 deletions(-)

diff --git a/apps/api/src/modules/leases/leases.service.spec.ts b/apps/api/src/modules/leases/leases.service.spec.ts
index 9bae2a03..a1667e7d 100644
--- a/apps/api/src/modules/leases/leases.service.spec.ts
+++ b/apps/api/src/modules/leases/leases.service.spec.ts
@@ -1,4 +1,5 @@
 import {
+  BadRequestException,
   ConflictException,
   ForbiddenException,
   NotFoundException,
@@ -146,6 +147,20 @@ describe('LeasesService', () => {
       });
     });
 
+    it('rejects creating a lease whose end date is not after its start date', async () => {
+      const { service, prisma } = makeService();
+
+      await expect(
+        service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+          ...dto,
+          startDate: '2026-06-01T00:00:00.000Z',
+          endDate: '2026-06-01T00:00:00.000Z',
+        }),
+      ).rejects.toBeInstanceOf(BadRequestException);
+
+      expect(prisma.lease.create).not.toHaveBeenCalled();
+    });
+
     it('does not sync the apartment when created with an explicit non-active status', async () => {
       const { service, prisma } = makeService();
       prisma.lease.create.mockResolvedValue(leaseRow({ status: 'draft' }));
diff --git a/apps/api/src/modules/leases/leases.service.ts b/apps/api/src/modules/leases/leases.service.ts
index 3df5a02b..eddb88c6 100644
--- a/apps/api/src/modules/leases/leases.service.ts
+++ b/apps/api/src/modules/leases/leases.service.ts
@@ -1,4 +1,5 @@
 import {
+  BadRequestException,
   ConflictException,
   Injectable,
   NotFoundException,
@@ -56,6 +57,28 @@ export class LeasesService {
     if (!renter) throw new NotFoundException('Renter not found.');
   }
 
+  /**
+   * Server-side invariant: a lease must end strictly after it starts. The FE
+   * enforces this too, but a direct API call previously bypassed it (the DTO
+   * only validated each date in isolation), so a lease with endDate <= startDate
+   * could be persisted.
+   */
+  private assertValidDateRange(
+    startDate: string | Date,
+    endDate: string | Date,
+  ): void {
+    const startMs = new Date(startDate).getTime();
+    const endMs = new Date(endDate).getTime();
+    if (Number.isNaN(startMs) || Number.isNaN(endMs)) {
+      throw new BadRequestException('Invalid lease start or end date.');
+    }
+    if (endMs <= startMs) {
+      throw new BadRequestException(
+        'Lease end date must be after the start date.',
+      );
+    }
+  }
+
   // ── CRUD ──────────────────────────────────────────────────────────────────
 
   async findAll(
@@ -186,6 +209,7 @@ export class LeasesService {
   ): Promise<{ data: LeaseResponse }> {
     await this.assertApartmentInScope(orgId, buildingId, floorId, apartmentId);
     await this.assertRenterInOrg(orgId, dto.renterId);
+    this.assertValidDateRange(dto.startDate, dto.endDate);
 
     const resolvedStatus = dto.status ?? 'active';
     const now = new Date();
@@ -261,6 +285,13 @@ export class LeasesService {
     });
     if (!existing) throw new NotFoundException('Lease not found.');
 
+    // Validate the resulting date range against whichever dates are being
+    // changed, falling back to the stored values for the untouched one.
+    this.assertValidDateRange(
+      dto.startDate ?? existing.startDate,
+      dto.endDate ?? existing.endDate,
+    );
+
     const isTerminating =
       dto.status === 'terminated' && existing.status !== 'terminated';
 
diff --git a/apps/web/src/app/[lang]/dashboard/layout.tsx b/apps/web/src/app/[lang]/dashboard/layout.tsx
index 91067d63..49095d66 100644
--- a/apps/web/src/app/[lang]/dashboard/layout.tsx
+++ b/apps/web/src/app/[lang]/dashboard/layout.tsx
@@ -49,7 +49,11 @@ export default async function DashboardLayout({
   const userName = session.user?.name ?? session.user?.email ?? '';
 
   return (
-    <div className="flex min-h-screen bg-background">
+    // h-screen + overflow-hidden turns this into a fixed app-shell: the sidebar
+    // stays viewport-height and the main column scrolls on its own, so a long
+    // page (e.g. the Activity feed) can never push the sidebar's Sign-out
+    // control below the fold. See dashboard-sidebar for the internal nav scroll.
+    <div className="flex h-screen overflow-hidden bg-background">
       <DashboardSidebar
         locale={locale}
         role={role}
@@ -63,7 +67,7 @@ export default async function DashboardLayout({
           role={role}
           dict={dict}
         />
-        <main className="flex-1 p-6 lg:p-8">{children}</main>
+        <main className="flex-1 overflow-y-auto p-6 lg:p-8">{children}</main>
       </div>
     </div>
   );
diff --git a/apps/web/src/app/api/auth/federated-logout/route.ts b/apps/web/src/app/api/auth/federated-logout/route.ts
index 8eee3afd..8f2afd3a 100644
--- a/apps/web/src/app/api/auth/federated-logout/route.ts
+++ b/apps/web/src/app/api/auth/federated-logout/route.ts
@@ -20,12 +20,27 @@ export async function GET(request: NextRequest) {
   const url = new URL(request.url);
   const locale = url.searchParams.get('locale') ?? 'en';
 
+  // Resolve the PUBLIC origin. Behind the nginx reverse proxy the Next.js
+  // standalone server derives `request.url` from its own internal bind address
+  // (e.g. `https://<container-id>:3000`), so `url.origin` leaks the container
+  // host into `post_logout_redirect_uri` — Keycloak then rejects it as an
+  // invalid redirect URI. Trust the forwarded headers instead (nginx sets
+  // `Host: $host` and `X-Forwarded-Proto: $scheme`; `trustHost: true` is on in
+  // auth.config.ts), falling back to the request URL only for local/dev.
+  const forwardedHost =
+    request.headers.get('x-forwarded-host') ?? request.headers.get('host');
+  const forwardedProto =
+    request.headers.get('x-forwarded-proto') ?? url.protocol.replace(/:$/, '');
+  const origin = forwardedHost
+    ? `${forwardedProto}://${forwardedHost}`
+    : url.origin;
+
   const endSession = `${serverEnv.KEYCLOAK_BASE}/realms/${serverEnv.KEYCLOAK_REALM}/protocol/openid-connect/logout`;
   const params = new URLSearchParams();
   if (session?.idToken) {
     params.set('id_token_hint', session.idToken);
   }
-  params.set('post_logout_redirect_uri', `${url.origin}/${locale}`);
+  params.set('post_logout_redirect_uri', `${origin}/${locale}`);
   params.set('client_id', serverEnv.OAUTH_CLIENT);
 
   return NextResponse.json({ url: `${endSession}?${params.toString()}` });
diff --git a/apps/web/src/components/dashboard/expenses-page.tsx b/apps/web/src/components/dashboard/expenses-page.tsx
index 7a5655a8..7a8c701c 100644
--- a/apps/web/src/components/dashboard/expenses-page.tsx
+++ b/apps/web/src/components/dashboard/expenses-page.tsx
@@ -798,7 +798,9 @@ export function ExpensesPage({
                       : '—'}
                   </TableCell>
                   <TableCell className="text-sm text-muted-foreground">
-                    {expense.workOrderId ?? '—'}
+                    {expense.workOrderId
+                      ? workOrderLabel(expense.workOrderId)
+                      : '—'}
                   </TableCell>
                   {canWrite && (
                     <TableCell>
diff --git a/apps/web/src/components/dashboard/tasks-page.tsx b/apps/web/src/components/dashboard/tasks-page.tsx
index 413a5614..9740a31b 100644
--- a/apps/web/src/components/dashboard/tasks-page.tsx
+++ b/apps/web/src/components/dashboard/tasks-page.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import { useRouter } from 'next/navigation';
 import { useForm, Controller } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
@@ -62,6 +62,7 @@ import { useListBuildingsQuery } from '@/store/api/endpoints/buildings.api';
 import { useListFloorsQuery } from '@/store/api/endpoints/floors.api';
 import { useListApartmentsQuery } from '@/store/api/endpoints/apartments.api';
 import { useListRentersQuery } from '@/store/api/endpoints/renters.api';
+import { useListAllLeasesQuery } from '@/store/api/endpoints/leases.api';
 import type {
   MaintenanceRequestPriority,
   MaintenanceRequestResponse,
@@ -225,6 +226,7 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
 
   const createBuildingId = watchCreate('buildingId');
   const createFloorId = watchCreate('floorId');
+  const createApartmentId = watchCreate('apartmentId');
 
   const { data: createFloors } = useListFloorsQuery(createBuildingId, {
     skip: !createBuildingId,
@@ -234,6 +236,24 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
     { skip: !createBuildingId || !createFloorId },
   );
 
+  // A maintenance request belongs to a property; the renter is derived from it.
+  // When the user picks an apartment that has an active lease, auto-fill the
+  // renter from that lease so they don't have to hand-pick (and can't mismatch)
+  // it. Apartments with no active lease fall back to manual selection.
+  const { data: allLeases } = useListAllLeasesQuery();
+  useEffect(() => {
+    if (!createApartmentId) return;
+    const activeLease = allLeases?.find(
+      (l) =>
+        l.apartmentId === createApartmentId && l.effectiveStatus === 'active',
+    );
+    if (activeLease) {
+      setCreateValue('renterId', activeLease.renterId, {
+        shouldValidate: true,
+      });
+    }
+  }, [createApartmentId, allLeases, setCreateValue]);
+
   const editSchema = useMemo(
     () => buildEditSchema(t.dialog.edit),
     [t.dialog.edit],
diff --git a/apps/web/src/components/layout/dashboard-sidebar.tsx b/apps/web/src/components/layout/dashboard-sidebar.tsx
index 54429490..809338e7 100644
--- a/apps/web/src/components/layout/dashboard-sidebar.tsx
+++ b/apps/web/src/components/layout/dashboard-sidebar.tsx
@@ -107,13 +107,6 @@ function buildNavItems(
       href: `/${locale}/dashboard/users`,
       areaKey: 'users',
     },
-    {
-      key: 'payments',
-      label: dict.nav.payments,
-      icon: DollarSign,
-      href: `/${locale}/dashboard/payments`,
-      areaKey: 'payments',
-    },
     {
       key: 'reports',
       label: dict.nav.reports,
@@ -149,6 +142,13 @@ function buildNavItems(
       href: `/${locale}/dashboard/billing`,
       areaKey: 'billing',
     },
+    {
+      key: 'payments',
+      label: dict.nav.payments,
+      icon: DollarSign,
+      href: `/${locale}/dashboard/payments`,
+      areaKey: 'payments',
+    },
     {
       key: 'timeline',
       label: dict.nav.timeline,
@@ -214,8 +214,9 @@ function SidebarContent({
 
       <Separator className="bg-white/10" />
 
-      {/* Navigation */}
-      <nav className="flex-1 space-y-0.5 px-3 py-4">
+      {/* Navigation — scrolls independently so the user/sign-out block below
+          stays pinned to the bottom of the viewport regardless of item count. */}
+      <nav className="flex-1 space-y-0.5 overflow-y-auto px-3 py-4">
         {visibleItems.map((item) => {
           const active = isActive(item.href);
           const Icon = item.icon;
diff --git a/apps/web/src/i18n/dictionaries/ar.json b/apps/web/src/i18n/dictionaries/ar.json
index f1e237df..b0809c56 100644
--- a/apps/web/src/i18n/dictionaries/ar.json
+++ b/apps/web/src/i18n/dictionaries/ar.json
@@ -10,7 +10,7 @@
     "billing": "الاشتراك",
     "users": "الفريق",
     "timeline": "النشاط",
-    "payments": "المدفوعات",
+    "payments": "مدفوعات الاشتراك",
     "buildings": "المباني",
     "myBuildings": "مبانيّ",
     "renters": "المستأجرون",
diff --git a/apps/web/src/i18n/dictionaries/en.json b/apps/web/src/i18n/dictionaries/en.json
index 591038e1..ea917806 100644
--- a/apps/web/src/i18n/dictionaries/en.json
+++ b/apps/web/src/i18n/dictionaries/en.json
@@ -10,7 +10,7 @@
     "billing": "Subscription",
     "users": "Team",
     "timeline": "Activity",
-    "payments": "Payments",
+    "payments": "Subscription Payments",
     "buildings": "Buildings",
     "myBuildings": "My Buildings",
     "renters": "Renters",

From 3580e3af9b370d4da230c5afcbfe155b716fe1d9 Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 01:57:05 +0300
Subject: [PATCH 03/11] =?UTF-8?q?feat(F2):=20maintenance=20&=20work-order?=
 =?UTF-8?q?=20workflow=20=E2=80=94=20WO=20numbers,=20my-work-orders,=20sup?=
 =?UTF-8?q?ervisor=20deep-links,=20task=20filters?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sprint F2 of the Property Manager behavior roadmap (workflow W5).

F2.1 [Q16] Human-readable WorkOrder.number (decision D4: org-scoped sequential
  WO-000123). Migration adds WorkOrder.number (nullable→backfill per org by
  createdAt→NOT NULL + @@unique([orgId,number])). create() assigns the next
  number under a per-org pg advisory lock (unique index is the backstop).
  Shared formatWorkOrderNumber() in @repo/contracts; WorkOrderResponse gains
  number + numberLabel. Shown on the maintenance-request detail Work Orders
  table and — via a new ExpenseResponse.workOrderNumberLabel (BE joins
  WorkOrder.number) — on the expenses "Work order" column (replaces the F1.6
  #<id> stopgap). Backfills existing rows.

F2.2 [Q27] Maintenance "assigned to me". New GET /work-orders/assigned-to-me
  (WorkOrdersOverviewController + findAssignedToCaller, enriched with request/
  apartment/building + active-first ordering). Maintenance dashboard shows a
  "My work orders" section (assigned WOs at the top, deep-linked to the
  request). Maintenance-request detail highlights rows assigned to the caller
  ("Assigned to you" badge; callerSub decoded from the access-token JWT).

F2.3 [Q23] Supervisor dashboard deep-links. KPI tiles now link to filtered
  lists (?status=open|in_progress|resolved, ?priority=urgent) and "Needs
  attention" rows deep-link to /tasks/:id (were all generic /tasks). Tasks page
  reads those query params and gained status/priority filter controls.

F2.4 [Q12] Reverse renter→apartment autofill in the new-request dialog
  (renter with one active lease backfills building/floor/apartment), with a
  ping-pong guard on both directions.

i18n parity held (en==ar 1033). Verified: api build EXIT 0 + jest 277 pass/4
skip; web check-types clean, next build EXIT 0, vitest 30/30, eslint clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../modules/expenses/expenses.service.spec.ts |  59 ++++--
 .../src/modules/expenses/expenses.service.ts  |  20 ++-
 .../work-orders/work-order-formatter.ts       |   5 +-
 .../work-orders-overview.controller.ts        |  31 ++++
 .../modules/work-orders/work-orders.module.ts |   3 +-
 .../work-orders/work-orders.service.spec.ts   | 160 +++++++++++++++++
 .../work-orders/work-orders.service.ts        |  90 ++++++++--
 .../app/[lang]/dashboard/tasks/[id]/page.tsx  |  25 +++
 .../api/work-orders/assigned-to-me/route.ts   |   5 +
 .../components/dashboard/expenses-page.tsx    |  19 +-
 .../maintenance-request-detail-page.tsx       | 170 +++++++++++-------
 .../components/dashboard/staff-dashboard.tsx  |  95 +++++++++-
 .../src/components/dashboard/tasks-page.tsx   | 138 +++++++++++++-
 apps/web/src/i18n/dictionaries/ar.json        |  20 ++-
 apps/web/src/i18n/dictionaries/en.json        |  20 ++-
 .../store/api/endpoints/work-orders.api.ts    |  19 ++
 packages/contracts/src/index.ts               |  32 ++++
 .../migration.sql                             |  26 +++
 packages/database/prisma/schema.prisma        |   5 +
 19 files changed, 819 insertions(+), 123 deletions(-)
 create mode 100644 apps/api/src/modules/work-orders/work-orders-overview.controller.ts
 create mode 100644 apps/web/src/app/api/work-orders/assigned-to-me/route.ts
 create mode 100644 packages/database/prisma/migrations/20260721010000_add_work_order_number/migration.sql

diff --git a/apps/api/src/modules/expenses/expenses.service.spec.ts b/apps/api/src/modules/expenses/expenses.service.spec.ts
index 9c76d98e..6575aa02 100644
--- a/apps/api/src/modules/expenses/expenses.service.spec.ts
+++ b/apps/api/src/modules/expenses/expenses.service.spec.ts
@@ -53,6 +53,7 @@ describe('ExpensesService', () => {
     buildingId,
     vendorId: null,
     workOrderId: null,
+    workOrder: null,
     category: 'repairs',
     amount: { toString: () => '150.00' },
     incurredAt: new Date('2026-01-05T00:00:00.000Z'),
@@ -62,6 +63,10 @@ describe('ExpensesService', () => {
     ...overrides,
   });
 
+  const WORK_ORDER_NUMBER_INCLUDE = {
+    workOrder: { select: { number: true } },
+  };
+
   describe('findAll', () => {
     it('returns all org expenses for an org-wide role (org_admin)', async () => {
       const { service, prisma, buildingAccess } = makeService({
@@ -77,6 +82,7 @@ describe('ExpensesService', () => {
       );
       expect(prisma.expense.findMany).toHaveBeenCalledWith({
         where: { orgId },
+        include: WORK_ORDER_NUMBER_INCLUDE,
         orderBy: { incurredAt: 'desc' },
       });
       expect(result.data).toEqual([
@@ -100,6 +106,7 @@ describe('ExpensesService', () => {
       );
       expect(prisma.expense.findMany).toHaveBeenCalledWith({
         where: { orgId },
+        include: WORK_ORDER_NUMBER_INCLUDE,
         orderBy: { incurredAt: 'desc' },
       });
     });
@@ -115,9 +122,34 @@ describe('ExpensesService', () => {
 
       expect(prisma.expense.findMany).toHaveBeenCalledWith({
         where: { orgId, buildingId: { in: [buildingId] } },
+        include: WORK_ORDER_NUMBER_INCLUDE,
         orderBy: { incurredAt: 'desc' },
       });
     });
+
+    it('populates workOrderNumberLabel for a row with a linked work order', async () => {
+      const { service, prisma } = makeService({
+        expense: {
+          findMany: jest
+            .fn()
+            .mockResolvedValue([
+              expenseRow({ workOrderId: 'wo-1', workOrder: { number: 123 } }),
+            ]),
+        },
+      });
+
+      const result = await service.findAll(orgId, callerId, Role.ORG_ADMIN);
+
+      expect(prisma.expense.findMany).toHaveBeenCalledWith(
+        expect.objectContaining({ include: WORK_ORDER_NUMBER_INCLUDE }),
+      );
+      expect(result.data).toEqual([
+        expect.objectContaining({
+          workOrderId: 'wo-1',
+          workOrderNumberLabel: 'WO-000123',
+        }),
+      ]);
+    });
   });
 
   describe('findOne', () => {
@@ -135,6 +167,7 @@ describe('ExpensesService', () => {
 
       expect(prisma.expense.findFirst).toHaveBeenCalledWith({
         where: { id: 'expense-1', orgId },
+        include: WORK_ORDER_NUMBER_INCLUDE,
       });
       expect(result.data).toEqual(expect.objectContaining({ id: 'expense-1' }));
     });
@@ -201,6 +234,7 @@ describe('ExpensesService', () => {
           incurredAt: new Date('2026-01-05T00:00:00.000Z'),
           notes: undefined,
         },
+        include: WORK_ORDER_NUMBER_INCLUDE,
       });
       expect(timeline.emit).toHaveBeenCalledWith(
         expect.objectContaining({
@@ -242,12 +276,14 @@ describe('ExpensesService', () => {
         where: { id: 'wo-1', orgId },
         select: { vendorId: true },
       });
-      expect(prisma.expense.create).toHaveBeenCalledWith({
-        data: expect.objectContaining({
-          vendorId: 'vendor-1',
-          workOrderId: 'wo-1',
+      expect(prisma.expense.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            vendorId: 'vendor-1',
+            workOrderId: 'wo-1',
+          }),
         }),
-      });
+      );
     });
 
     it('rejects when vendorId and workOrderId are both provided but do not match', async () => {
@@ -280,12 +316,14 @@ describe('ExpensesService', () => {
         vendorId: 'vendor-1',
       });
 
-      expect(prisma.expense.create).toHaveBeenCalledWith({
-        data: expect.objectContaining({
-          vendorId: 'vendor-1',
-          workOrderId: 'wo-1',
+      expect(prisma.expense.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            vendorId: 'vendor-1',
+            workOrderId: 'wo-1',
+          }),
         }),
-      });
+      );
     });
 
     it('rejects with ForbiddenException for a supervisor caller', async () => {
@@ -322,6 +360,7 @@ describe('ExpensesService', () => {
       expect(prisma.expense.update).toHaveBeenCalledWith({
         where: { id: 'expense-1' },
         data: { notes: 'Paid in full' },
+        include: WORK_ORDER_NUMBER_INCLUDE,
       });
       expect(timeline.emit).toHaveBeenCalledWith(
         expect.objectContaining({ action: 'expense.updated' }),
diff --git a/apps/api/src/modules/expenses/expenses.service.ts b/apps/api/src/modules/expenses/expenses.service.ts
index df8b2003..3718ae6f 100644
--- a/apps/api/src/modules/expenses/expenses.service.ts
+++ b/apps/api/src/modules/expenses/expenses.service.ts
@@ -12,7 +12,11 @@ import {
 } from '@/common/building-access/building-access.service';
 import { TimelineService } from '@/modules/timeline/timeline.service';
 import { Role } from '@/common/enums';
-import { ExpenseCategory, ExpenseResponse } from '@repo/contracts';
+import {
+  ExpenseCategory,
+  ExpenseResponse,
+  formatWorkOrderNumber,
+} from '@repo/contracts';
 import { CreateExpenseDto } from './dto/create-expense.dto';
 import { UpdateExpenseDto } from './dto/update-expense.dto';
 
@@ -28,8 +32,15 @@ type ExpenseRow = {
   notes: string | null;
   createdAt: Date;
   updatedAt: Date;
+  workOrder?: { number: number } | null;
 };
 
+/** Shared across findAll/findOne/create/update so the linked Work Order's
+ * display number is always available to formatExpense. */
+const WORK_ORDER_NUMBER_INCLUDE = {
+  workOrder: { select: { number: true } },
+} as const;
+
 @Injectable()
 export class ExpensesService {
   constructor(
@@ -82,6 +93,9 @@ export class ExpensesService {
       buildingId: expense.buildingId,
       vendorId: expense.vendorId,
       workOrderId: expense.workOrderId,
+      workOrderNumberLabel: expense.workOrder
+        ? formatWorkOrderNumber(expense.workOrder.number)
+        : null,
       category: expense.category as ExpenseCategory,
       amount: expense.amount.toString(),
       incurredAt: expense.incurredAt.toISOString(),
@@ -109,6 +123,7 @@ export class ExpensesService {
         orgId,
         ...(allowedBuildingIds && { buildingId: { in: allowedBuildingIds } }),
       },
+      include: WORK_ORDER_NUMBER_INCLUDE,
       orderBy: { incurredAt: 'desc' },
     });
 
@@ -123,6 +138,7 @@ export class ExpensesService {
   ): Promise<{ data: ExpenseResponse }> {
     const expense = await this.prisma.expense.findFirst({
       where: { id: expenseId, orgId },
+      include: WORK_ORDER_NUMBER_INCLUDE,
     });
     if (!expense) throw new NotFoundException('Expense not found.');
 
@@ -176,6 +192,7 @@ export class ExpensesService {
         incurredAt: new Date(dto.incurredAt),
         notes: dto.notes,
       },
+      include: WORK_ORDER_NUMBER_INCLUDE,
     });
 
     await this.timeline.emit({
@@ -226,6 +243,7 @@ export class ExpensesService {
         }),
         ...(dto.notes !== undefined && { notes: dto.notes }),
       },
+      include: WORK_ORDER_NUMBER_INCLUDE,
     });
 
     await this.timeline.emit({
diff --git a/apps/api/src/modules/work-orders/work-order-formatter.ts b/apps/api/src/modules/work-orders/work-order-formatter.ts
index 6c36cf12..8f8cb84d 100644
--- a/apps/api/src/modules/work-orders/work-order-formatter.ts
+++ b/apps/api/src/modules/work-orders/work-order-formatter.ts
@@ -1,9 +1,10 @@
 import { Prisma } from '@repo/db';
-import { WorkOrderResponse } from '@repo/contracts';
+import { WorkOrderResponse, formatWorkOrderNumber } from '@repo/contracts';
 
 export type WorkOrderRow = {
   id: string;
   orgId: string;
+  number: number;
   maintenanceRequestId: string;
   vendorId: string | null;
   assignedUserId: string | null;
@@ -20,6 +21,8 @@ export function formatWorkOrder(workOrder: WorkOrderRow): WorkOrderResponse {
   return {
     id: workOrder.id,
     orgId: workOrder.orgId,
+    number: workOrder.number,
+    numberLabel: formatWorkOrderNumber(workOrder.number),
     maintenanceRequestId: workOrder.maintenanceRequestId,
     vendorId: workOrder.vendorId,
     assignedUserId: workOrder.assignedUserId,
diff --git a/apps/api/src/modules/work-orders/work-orders-overview.controller.ts b/apps/api/src/modules/work-orders/work-orders-overview.controller.ts
new file mode 100644
index 00000000..3676959a
--- /dev/null
+++ b/apps/api/src/modules/work-orders/work-orders-overview.controller.ts
@@ -0,0 +1,31 @@
+import { Controller, Get } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { WorkOrdersService } from './work-orders.service';
+import { OrgScopeService } from '@/common/org-scope/org-scope.service';
+import { CurrentUser, Roles } from '@/common/decorators';
+import { AuthenticatedUser } from '@/common/types/authenticated-user.type';
+import { Role } from '@/common/enums';
+
+/**
+ * Org-wide "my work orders" list (Sprint F2.2) — feeds a maintenance user's
+ * assigned-to-me view across every maintenance request. Complements (does
+ * not replace) the nested
+ * maintenance-requests/:maintenanceRequestId/work-orders controller, which
+ * stays scoped to a single request.
+ */
+@ApiTags('work-orders')
+@ApiBearerAuth()
+@Controller('work-orders')
+export class WorkOrdersOverviewController {
+  constructor(
+    private readonly workOrdersService: WorkOrdersService,
+    private readonly orgScope: OrgScopeService,
+  ) {}
+
+  @Roles(Role.ORG_ADMIN, Role.SUPERVISOR, Role.MAINTENANCE)
+  @Get('assigned-to-me')
+  async getAssignedToMe(@CurrentUser() user: AuthenticatedUser) {
+    const { orgId } = await this.orgScope.resolveForCaller(user);
+    return this.workOrdersService.findAssignedToCaller(orgId, user.sub);
+  }
+}
diff --git a/apps/api/src/modules/work-orders/work-orders.module.ts b/apps/api/src/modules/work-orders/work-orders.module.ts
index 89bdbe27..a67ec2c9 100644
--- a/apps/api/src/modules/work-orders/work-orders.module.ts
+++ b/apps/api/src/modules/work-orders/work-orders.module.ts
@@ -1,10 +1,11 @@
 import { Module } from '@nestjs/common';
 import { WorkOrdersController } from './work-orders.controller';
+import { WorkOrdersOverviewController } from './work-orders-overview.controller';
 import { WorkOrdersService } from './work-orders.service';
 import { WorkOrderApartmentStatusService } from './work-order-apartment-status.service';
 
 @Module({
-  controllers: [WorkOrdersController],
+  controllers: [WorkOrdersController, WorkOrdersOverviewController],
   providers: [WorkOrdersService, WorkOrderApartmentStatusService],
   exports: [WorkOrdersService],
 })
diff --git a/apps/api/src/modules/work-orders/work-orders.service.spec.ts b/apps/api/src/modules/work-orders/work-orders.service.spec.ts
index 56fe6722..7e09d2fd 100644
--- a/apps/api/src/modules/work-orders/work-orders.service.spec.ts
+++ b/apps/api/src/modules/work-orders/work-orders.service.spec.ts
@@ -38,6 +38,7 @@ describe('WorkOrdersService', () => {
       workOrder: {
         findFirst: jest.fn().mockResolvedValue(null),
         findMany: jest.fn().mockResolvedValue([]),
+        aggregate: jest.fn().mockResolvedValue({ _max: { number: 0 } }),
         create: jest.fn(),
         update: jest.fn(),
         delete: jest.fn(),
@@ -47,7 +48,12 @@ describe('WorkOrdersService', () => {
         count: jest.fn().mockResolvedValue(0),
         ...overrides.expense,
       },
+      // create() assigns the org-scoped number inside a transaction + advisory
+      // lock. Run the callback against the same mock and stub the raw lock.
+      $executeRaw: jest.fn().mockResolvedValue(1),
+      $transaction: jest.fn(),
     };
+    prisma.$transaction.mockImplementation((cb: any) => cb(prisma));
     const buildingAccess = {
       assertBuildingAccess: jest.fn().mockResolvedValue(undefined),
       ...overrides.buildingAccess,
@@ -76,6 +82,7 @@ describe('WorkOrdersService', () => {
   const workOrderRow = (overrides: Partial<Record<string, unknown>> = {}) => ({
     id: 'wo-1',
     orgId,
+    number: 1,
     maintenanceRequestId,
     vendorId: 'vendor-1',
     assignedUserId: null,
@@ -241,6 +248,128 @@ describe('WorkOrdersService', () => {
     });
   });
 
+  describe('findAssignedToCaller', () => {
+    const assignedRow = (overrides: Partial<Record<string, unknown>> = {}) => ({
+      ...workOrderRow({ assignedUserId: callerId, vendorId: null }),
+      maintenanceRequest: {
+        title: 'Leaking faucet',
+        status: 'open',
+        buildingId,
+        apartmentId,
+        apartment: {
+          unitNumber: '101',
+          building: { name: 'Tower A' },
+        },
+      },
+      ...overrides,
+    });
+
+    it("queries only work orders assigned to the caller, ordered by createdAt desc", async () => {
+      const { service, prisma } = makeService({
+        workOrder: { findMany: jest.fn().mockResolvedValue([assignedRow()]) },
+      });
+
+      await service.findAssignedToCaller(orgId, callerId);
+
+      expect(prisma.workOrder.findMany).toHaveBeenCalledWith({
+        where: { orgId, assignedUserId: callerId },
+        include: {
+          maintenanceRequest: {
+            select: {
+              title: true,
+              status: true,
+              buildingId: true,
+              apartmentId: true,
+              apartment: {
+                select: {
+                  unitNumber: true,
+                  building: { select: { name: true } },
+                },
+              },
+            },
+          },
+        },
+        orderBy: { createdAt: 'desc' },
+      });
+    });
+
+    it('enriches each row with request/apartment/building context and the numberLabel', async () => {
+      const { service } = makeService({
+        workOrder: {
+          findMany: jest
+            .fn()
+            .mockResolvedValue([assignedRow({ number: 123 })]),
+        },
+      });
+
+      const result = await service.findAssignedToCaller(orgId, callerId);
+
+      expect(result.data).toEqual([
+        expect.objectContaining({
+          id: 'wo-1',
+          number: 123,
+          numberLabel: 'WO-000123',
+          requestTitle: 'Leaking faucet',
+          requestStatus: 'open',
+          buildingId,
+          buildingName: 'Tower A',
+          apartmentId,
+          apartmentUnit: '101',
+        }),
+      ]);
+    });
+
+    it("returns an empty list when the caller has no assigned work orders", async () => {
+      const { service, prisma } = makeService({
+        workOrder: { findMany: jest.fn().mockResolvedValue([]) },
+      });
+
+      const result = await service.findAssignedToCaller(orgId, 'other-caller');
+
+      expect(prisma.workOrder.findMany).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: { orgId, assignedUserId: 'other-caller' },
+        }),
+      );
+      expect(result.data).toEqual([]);
+    });
+
+    it('surfaces active (scheduled/in_progress) work orders before completed/canceled ones', async () => {
+      const completed = assignedRow({
+        id: 'wo-completed',
+        status: 'completed',
+        createdAt: new Date('2026-01-03T00:00:00.000Z'),
+      });
+      const scheduled = assignedRow({
+        id: 'wo-scheduled',
+        status: 'scheduled',
+        createdAt: new Date('2026-01-01T00:00:00.000Z'),
+      });
+      const inProgress = assignedRow({
+        id: 'wo-in-progress',
+        status: 'in_progress',
+        createdAt: new Date('2026-01-02T00:00:00.000Z'),
+      });
+      const { service } = makeService({
+        // Simulate the query's createdAt-desc ordering: completed (newest)
+        // first, then in_progress, then scheduled (oldest).
+        workOrder: {
+          findMany: jest
+            .fn()
+            .mockResolvedValue([completed, inProgress, scheduled]),
+        },
+      });
+
+      const result = await service.findAssignedToCaller(orgId, callerId);
+
+      expect(result.data.map((w) => w.id)).toEqual([
+        'wo-in-progress',
+        'wo-scheduled',
+        'wo-completed',
+      ]);
+    });
+  });
+
   describe('create', () => {
     it('creates a work order with a vendor assigned, opens the apartment, and emits work_order.created', async () => {
       const { service, prisma, timeline, workOrderApartmentStatus } =
@@ -262,6 +391,7 @@ describe('WorkOrdersService', () => {
       expect(prisma.workOrder.create).toHaveBeenCalledWith({
         data: {
           orgId,
+          number: 1,
           maintenanceRequestId,
           vendorId: 'vendor-1',
           assignedUserId: undefined,
@@ -270,6 +400,10 @@ describe('WorkOrdersService', () => {
           resolutionNotes: undefined,
         },
       });
+      expect(prisma.workOrder.aggregate).toHaveBeenCalledWith({
+        where: { orgId },
+        _max: { number: true },
+      });
       expect(workOrderApartmentStatus.onWorkOrderOpened).toHaveBeenCalledWith(
         apartmentId,
       );
@@ -295,6 +429,32 @@ describe('WorkOrdersService', () => {
       expect(result.data.assignedUserId).toBe('user-1');
     });
 
+    it('assigns the next org-scoped number (max + 1) and exposes a WO-000123 label', async () => {
+      const { service, prisma } = makeService({
+        workOrder: {
+          aggregate: jest.fn().mockResolvedValue({ _max: { number: 41 } }),
+          create: jest.fn().mockResolvedValue(
+            workOrderRow({ number: 42, vendorId: 'vendor-1' }),
+          ),
+        },
+      });
+
+      const result = await service.create(
+        orgId,
+        actorId,
+        Role.ORG_ADMIN,
+        maintenanceRequestId,
+        { vendorId: 'vendor-1' },
+      );
+
+      expect(prisma.$executeRaw).toHaveBeenCalled(); // advisory lock taken
+      expect(prisma.workOrder.create).toHaveBeenCalledWith(
+        expect.objectContaining({ data: expect.objectContaining({ number: 42 }) }),
+      );
+      expect(result.data.number).toBe(42);
+      expect(result.data.numberLabel).toBe('WO-000042');
+    });
+
     it('rejects with BadRequestException when both vendorId and assignedUserId are set', async () => {
       const { service } = makeService();
 
diff --git a/apps/api/src/modules/work-orders/work-orders.service.ts b/apps/api/src/modules/work-orders/work-orders.service.ts
index 1e8b1e17..130965da 100644
--- a/apps/api/src/modules/work-orders/work-orders.service.ts
+++ b/apps/api/src/modules/work-orders/work-orders.service.ts
@@ -10,7 +10,11 @@ import { BuildingAccessService } from '@/common/building-access/building-access.
 import { TimelineService } from '@/modules/timeline/timeline.service';
 import { WorkOrderApartmentStatusService } from './work-order-apartment-status.service';
 import { Role } from '@/common/enums';
-import { WorkOrderResponse } from '@repo/contracts';
+import {
+  AssignedWorkOrderListResponse,
+  MaintenanceRequestStatus,
+  WorkOrderResponse,
+} from '@repo/contracts';
 import { formatWorkOrder } from './work-order-formatter';
 import { CreateWorkOrderDto } from './dto/create-work-order.dto';
 import { UpdateWorkOrderDto } from './dto/update-work-order.dto';
@@ -81,6 +85,58 @@ export class WorkOrdersService {
     return { data: formatWorkOrder(workOrder) };
   }
 
+  /**
+   * All work orders assigned to the caller across every maintenance request
+   * in the org (Sprint F2.2 "My work orders" data source). Scoped by
+   * assignedUserId = callerId, so no separate building-access check is
+   * needed — a maintenance user can only ever see their own assignments.
+   */
+  async findAssignedToCaller(
+    orgId: string,
+    callerId: string,
+  ): Promise<AssignedWorkOrderListResponse> {
+    const workOrders = await this.prisma.workOrder.findMany({
+      where: { orgId, assignedUserId: callerId },
+      include: {
+        maintenanceRequest: {
+          select: {
+            title: true,
+            status: true,
+            buildingId: true,
+            apartmentId: true,
+            apartment: {
+              select: {
+                unitNumber: true,
+                building: { select: { name: true } },
+              },
+            },
+          },
+        },
+      },
+      orderBy: { createdAt: 'desc' },
+    });
+
+    // Active (scheduled/in_progress) work orders surface first; within each
+    // group the query's createdAt-desc order is preserved because
+    // Array#sort is a stable sort.
+    const activeRank = (status: string) => (OPEN_STATUSES.has(status) ? 0 : 1);
+    const sorted = [...workOrders].sort(
+      (a, b) => activeRank(a.status) - activeRank(b.status),
+    );
+
+    return {
+      data: sorted.map((w) => ({
+        ...formatWorkOrder(w),
+        requestTitle: w.maintenanceRequest.title,
+        requestStatus: w.maintenanceRequest.status as MaintenanceRequestStatus,
+        buildingId: w.maintenanceRequest.buildingId,
+        buildingName: w.maintenanceRequest.apartment.building.name,
+        apartmentId: w.maintenanceRequest.apartmentId,
+        apartmentUnit: w.maintenanceRequest.apartment.unitNumber,
+      })),
+    };
+  }
+
   // ── CRUD (write) ──────────────────────────────────────────────────────────
 
   async create(
@@ -110,16 +166,28 @@ export class WorkOrdersService {
       );
     }
 
-    const workOrder = await this.prisma.workOrder.create({
-      data: {
-        orgId,
-        maintenanceRequestId,
-        vendorId: dto.vendorId,
-        assignedUserId: dto.assignedUserId,
-        status: dto.status,
-        cost: dto.cost,
-        resolutionNotes: dto.resolutionNotes,
-      },
+    // Assign the next org-scoped sequential number under a per-org advisory lock
+    // so concurrent creates cannot collide on a number. The @@unique([orgId,
+    // number]) index is the backstop if two writers ever race the lock.
+    const workOrder = await this.prisma.$transaction(async (tx) => {
+      await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${`work_order_number:${orgId}`}))`;
+      const { _max } = await tx.workOrder.aggregate({
+        where: { orgId },
+        _max: { number: true },
+      });
+      const nextNumber = (_max.number ?? 0) + 1;
+      return tx.workOrder.create({
+        data: {
+          orgId,
+          number: nextNumber,
+          maintenanceRequestId,
+          vendorId: dto.vendorId,
+          assignedUserId: dto.assignedUserId,
+          status: dto.status,
+          cost: dto.cost,
+          resolutionNotes: dto.resolutionNotes,
+        },
+      });
     });
 
     await this.workOrderApartmentStatus.onWorkOrderOpened(request.apartmentId);
diff --git a/apps/web/src/app/[lang]/dashboard/tasks/[id]/page.tsx b/apps/web/src/app/[lang]/dashboard/tasks/[id]/page.tsx
index ed05d997..2d1967b5 100644
--- a/apps/web/src/app/[lang]/dashboard/tasks/[id]/page.tsx
+++ b/apps/web/src/app/[lang]/dashboard/tasks/[id]/page.tsx
@@ -6,6 +6,28 @@ import { isLocale } from '@/i18n/config';
 import { getDictionary } from '@/i18n/get-dictionary';
 import { MaintenanceRequestDetailPage } from '@/components/dashboard/maintenance-request-detail-page';
 
+/**
+ * The NextAuth session object does not expose the Keycloak `sub` (the JWT
+ * strategy's session callback only surfaces name/email/image by default, and
+ * this app's own session callback — auth/auth.ts — doesn't add it either).
+ * `session.accessToken` is the raw Keycloak-issued JWT though, and its `sub`
+ * claim is exactly the id `WorkOrder.assignedUserId` is compared against
+ * (per repo convention: users are referenced by their Keycloak `sub`). Decode
+ * it here rather than widening the shared session type for one call site.
+ */
+function decodeAccessTokenSub(token: string | undefined): string | undefined {
+  if (!token) return undefined;
+  try {
+    const payload = token.split('.')[1];
+    if (!payload) return undefined;
+    const decoded = Buffer.from(payload, 'base64url').toString('utf8');
+    const parsed = JSON.parse(decoded) as { sub?: string };
+    return parsed.sub;
+  } catch {
+    return undefined;
+  }
+}
+
 export default async function MaintenanceRequestDetailPageRoute({
   params,
 }: {
@@ -26,12 +48,15 @@ export default async function MaintenanceRequestDetailPageRoute({
   // only update status/resolutionNotes on a Work Order assigned to them
   // (enforced in WorkOrdersService) — neither is the plain 'tasks'
   // canWrite() value, which is 'full' for maintenance at the page level.
+  const callerSub = decodeAccessTokenSub(session.accessToken);
+
   return (
     <MaintenanceRequestDetailPage
       id={id}
       locale={locale}
       canWrite={role === 'org_admin'}
       isMaintenanceCaller={role === 'maintenance'}
+      callerSub={callerSub}
       dict={dict}
     />
   );
diff --git a/apps/web/src/app/api/work-orders/assigned-to-me/route.ts b/apps/web/src/app/api/work-orders/assigned-to-me/route.ts
new file mode 100644
index 00000000..c5f94a69
--- /dev/null
+++ b/apps/web/src/app/api/work-orders/assigned-to-me/route.ts
@@ -0,0 +1,5 @@
+import { forwardRoute } from '@/lib/api/forward';
+
+export const runtime = 'nodejs';
+
+export const GET = forwardRoute('/work-orders/assigned-to-me');
diff --git a/apps/web/src/components/dashboard/expenses-page.tsx b/apps/web/src/components/dashboard/expenses-page.tsx
index 7a8c701c..ae4596b9 100644
--- a/apps/web/src/components/dashboard/expenses-page.tsx
+++ b/apps/web/src/components/dashboard/expenses-page.tsx
@@ -141,12 +141,6 @@ const EMPTY_VALUES: ExpenseFormValues = {
   notes: '',
 };
 
-// ── Work order label (WorkOrderResponse has no title/description) ────────────
-
-function workOrderLabel(id: string) {
-  return `#${id.slice(-6)}`;
-}
-
 // ── Shared form fields (create + edit dialogs) ────────────────────────────────
 
 function ExpenseFormFields({
@@ -173,7 +167,9 @@ function ExpenseFormFields({
   canLinkWorkOrder: boolean;
   maintenanceRequestId: string;
   onMaintenanceRequestChange: (id: string) => void;
-  workOrders: { id: string; vendorId?: string | null }[] | undefined;
+  workOrders:
+    | { id: string; vendorId?: string | null; numberLabel: string }[]
+    | undefined;
   setValue: ReturnType<typeof useForm<ExpenseFormValues>>['setValue'];
   getValues: ReturnType<typeof useForm<ExpenseFormValues>>['getValues'];
   dict: Dictionary;
@@ -381,7 +377,8 @@ function ExpenseFormFields({
                     {(value: string | null) =>
                       !value || value === NONE
                         ? t.workOrderSection.workOrderNone
-                        : workOrderLabel(value)
+                        : (workOrders?.find((w) => w.id === value)
+                            ?.numberLabel ?? value)
                     }
                   </SelectValue>
                 </SelectTrigger>
@@ -391,7 +388,7 @@ function ExpenseFormFields({
                   </SelectItem>
                   {workOrders?.map((w) => (
                     <SelectItem key={w.id} value={w.id}>
-                      {workOrderLabel(w.id)}
+                      {w.numberLabel}
                     </SelectItem>
                   ))}
                 </SelectContent>
@@ -798,9 +795,7 @@ export function ExpensesPage({
                       : '—'}
                   </TableCell>
                   <TableCell className="text-sm text-muted-foreground">
-                    {expense.workOrderId
-                      ? workOrderLabel(expense.workOrderId)
-                      : '—'}
+                    {expense.workOrderNumberLabel ?? '—'}
                   </TableCell>
                   {canWrite && (
                     <TableCell>
diff --git a/apps/web/src/components/dashboard/maintenance-request-detail-page.tsx b/apps/web/src/components/dashboard/maintenance-request-detail-page.tsx
index 5810faf2..aac2267b 100644
--- a/apps/web/src/components/dashboard/maintenance-request-detail-page.tsx
+++ b/apps/web/src/components/dashboard/maintenance-request-detail-page.tsx
@@ -16,6 +16,8 @@ import {
   WrenchIcon,
 } from 'lucide-react';
 
+import { formatWorkOrderNumber } from '@repo/contracts';
+
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -206,6 +208,13 @@ interface MaintenanceRequestDetailPageProps {
    * backend's per-row 403 + toast is the real enforcement.
    */
   isMaintenanceCaller: boolean;
+  /**
+   * The caller's Keycloak `sub`, used to highlight work orders assigned to
+   * them. Decoded server-side from the session access token (the session
+   * object itself does not expose `sub`/`id` for the JWT strategy) — undefined
+   * falls back to no highlight rather than a wrong one.
+   */
+  callerSub?: string;
   dict: Dictionary;
 }
 
@@ -214,6 +223,7 @@ export function MaintenanceRequestDetailPage({
   locale,
   canWrite,
   isMaintenanceCaller,
+  callerSub,
   dict,
 }: MaintenanceRequestDetailPageProps) {
   const t = dict.maintenance;
@@ -535,6 +545,7 @@ export function MaintenanceRequestDetailPage({
         <Table>
           <TableHeader>
             <TableRow>
+              <TableHead>{t.detail.table.number}</TableHead>
               <TableHead>{t.detail.table.status}</TableHead>
               <TableHead>{t.detail.table.assignee}</TableHead>
               <TableHead>{t.detail.table.cost}</TableHead>
@@ -549,7 +560,7 @@ export function MaintenanceRequestDetailPage({
             {request.workOrders.length === 0 ? (
               <TableRow>
                 <TableCell
-                  colSpan={canWrite || isMaintenanceCaller ? 6 : 5}
+                  colSpan={canWrite || isMaintenanceCaller ? 7 : 6}
                   className="text-center py-10 text-muted-foreground"
                 >
                   <WrenchIcon className="size-8 mx-auto mb-2 opacity-30" />
@@ -557,77 +568,100 @@ export function MaintenanceRequestDetailPage({
                 </TableCell>
               </TableRow>
             ) : (
-              request.workOrders.map((workOrder) => (
-                <TableRow key={workOrder.id}>
-                  <TableCell>
-                    <WorkOrderStatusBadge
-                      status={workOrder.status}
-                      labels={t.workOrderStatus}
-                    />
-                  </TableCell>
-                  <TableCell className="text-sm text-muted-foreground">
-                    {assigneeLabel(workOrder)}
-                  </TableCell>
-                  <TableCell className="text-sm text-muted-foreground">
-                    {workOrder.cost ?? '—'}
-                  </TableCell>
-                  <TableCell className="text-sm text-muted-foreground">
-                    {workOrder.resolutionNotes ?? '—'}
-                  </TableCell>
-                  <TableCell className="text-sm text-muted-foreground">
-                    {workOrder.completedAt
-                      ? new Date(workOrder.completedAt).toLocaleDateString()
-                      : '—'}
-                  </TableCell>
-                  {(canWrite || isMaintenanceCaller) && (
+              request.workOrders.map((workOrder) => {
+                const assignedToCaller =
+                  Boolean(callerSub) &&
+                  Boolean(workOrder.assignedUserId) &&
+                  workOrder.assignedUserId === callerSub;
+                return (
+                  <TableRow
+                    key={workOrder.id}
+                    className={assignedToCaller ? 'bg-primary/5' : undefined}
+                  >
+                    <TableCell className="text-sm font-medium">
+                      {workOrder.numberLabel ??
+                        formatWorkOrderNumber(workOrder.number)}
+                    </TableCell>
                     <TableCell>
-                      <DropdownMenu>
-                        <DropdownMenuTrigger
-                          render={
-                            <Button
-                              variant="ghost"
-                              size="icon-sm"
-                              aria-label={t.detail.actionsLabel}
-                            >
-                              <MoreHorizontalIcon />
-                            </Button>
-                          }
-                        />
-                        <DropdownMenuContent align="end">
-                          {canWrite && (
-                            <DropdownMenuItem
-                              onClick={() => openEdit(workOrder)}
-                            >
-                              <PencilIcon className="size-3.5 mr-1.5" />
-                              {dict.common.edit}
-                            </DropdownMenuItem>
-                          )}
-                          {isMaintenanceCaller && !canWrite && (
-                            <DropdownMenuItem
-                              onClick={() => openStatusUpdate(workOrder)}
-                            >
-                              <PencilIcon className="size-3.5 mr-1.5" />
-                              {t.detail.updateStatusAction}
-                            </DropdownMenuItem>
-                          )}
-                          {canWrite && (
-                            <>
-                              <DropdownMenuSeparator />
+                      <WorkOrderStatusBadge
+                        status={workOrder.status}
+                        labels={t.workOrderStatus}
+                      />
+                    </TableCell>
+                    <TableCell className="text-sm text-muted-foreground">
+                      <span className="inline-flex items-center gap-1.5">
+                        {assigneeLabel(workOrder)}
+                        {assignedToCaller && (
+                          <Badge
+                            variant="outline"
+                            className="bg-primary/10 text-primary border-primary/20"
+                          >
+                            {t.detail.assignedToYou}
+                          </Badge>
+                        )}
+                      </span>
+                    </TableCell>
+                    <TableCell className="text-sm text-muted-foreground">
+                      {workOrder.cost ?? '—'}
+                    </TableCell>
+                    <TableCell className="text-sm text-muted-foreground">
+                      {workOrder.resolutionNotes ?? '—'}
+                    </TableCell>
+                    <TableCell className="text-sm text-muted-foreground">
+                      {workOrder.completedAt
+                        ? new Date(workOrder.completedAt).toLocaleDateString()
+                        : '—'}
+                    </TableCell>
+                    {(canWrite || isMaintenanceCaller) && (
+                      <TableCell>
+                        <DropdownMenu>
+                          <DropdownMenuTrigger
+                            render={
+                              <Button
+                                variant="ghost"
+                                size="icon-sm"
+                                aria-label={t.detail.actionsLabel}
+                              >
+                                <MoreHorizontalIcon />
+                              </Button>
+                            }
+                          />
+                          <DropdownMenuContent align="end">
+                            {canWrite && (
                               <DropdownMenuItem
-                                variant="destructive"
-                                onClick={() => setDeleteTarget(workOrder)}
+                                onClick={() => openEdit(workOrder)}
                               >
-                                <TrashIcon className="size-3.5 mr-1.5" />
-                                {dict.common.delete}
+                                <PencilIcon className="size-3.5 mr-1.5" />
+                                {dict.common.edit}
                               </DropdownMenuItem>
-                            </>
-                          )}
-                        </DropdownMenuContent>
-                      </DropdownMenu>
-                    </TableCell>
-                  )}
-                </TableRow>
-              ))
+                            )}
+                            {isMaintenanceCaller && !canWrite && (
+                              <DropdownMenuItem
+                                onClick={() => openStatusUpdate(workOrder)}
+                              >
+                                <PencilIcon className="size-3.5 mr-1.5" />
+                                {t.detail.updateStatusAction}
+                              </DropdownMenuItem>
+                            )}
+                            {canWrite && (
+                              <>
+                                <DropdownMenuSeparator />
+                                <DropdownMenuItem
+                                  variant="destructive"
+                                  onClick={() => setDeleteTarget(workOrder)}
+                                >
+                                  <TrashIcon className="size-3.5 mr-1.5" />
+                                  {dict.common.delete}
+                                </DropdownMenuItem>
+                              </>
+                            )}
+                          </DropdownMenuContent>
+                        </DropdownMenu>
+                      </TableCell>
+                    )}
+                  </TableRow>
+                );
+              })
             )}
           </TableBody>
         </Table>
diff --git a/apps/web/src/components/dashboard/staff-dashboard.tsx b/apps/web/src/components/dashboard/staff-dashboard.tsx
index e6bcb012..137b1bd6 100644
--- a/apps/web/src/components/dashboard/staff-dashboard.tsx
+++ b/apps/web/src/components/dashboard/staff-dashboard.tsx
@@ -12,9 +12,14 @@ import {
 } from 'lucide-react';
 import { useListMaintenanceRequestsQuery } from '@/store/api/endpoints/maintenance-requests.api';
 import { useListTimelineQuery } from '@/store/api/endpoints/timeline.api';
+import { useGetAssignedWorkOrdersQuery } from '@/store/api/endpoints/work-orders.api';
 import { maintenanceStats, topActiveRequests } from '@/lib/dashboard-kpis';
 import { KpiTile } from '@/components/dashboard/kpi-tile';
-import type { MaintenanceRequestPriority, MeResponse } from '@/types/api';
+import type {
+  MaintenanceRequestPriority,
+  MeResponse,
+  WorkOrderStatus,
+} from '@/types/api';
 import type { Dictionary } from '@/i18n/get-dictionary';
 import { Badge } from '@/components/ui/badge';
 import { Skeleton } from '@/components/ui/skeleton';
@@ -38,16 +43,32 @@ const PRIORITY_CLASS: Record<MaintenanceRequestPriority, string> = {
   low: 'bg-gray-500/15 text-gray-600 border-gray-200',
 };
 
-export function StaffDashboard({ me, locale, dict }: StaffDashboardProps) {
+const WORK_ORDER_STATUS_CLASS: Record<WorkOrderStatus, string> = {
+  scheduled: 'bg-amber-50 text-amber-700 border-amber-200',
+  in_progress: 'bg-blue-50 text-blue-700 border-blue-200',
+  completed: 'bg-emerald-50 text-emerald-700 border-emerald-200',
+  canceled: 'bg-muted text-muted-foreground border-transparent',
+};
+
+export function StaffDashboard({
+  me,
+  locale,
+  role,
+  dict,
+}: StaffDashboardProps) {
   const t = dict.dashboard;
   const k = t.kpi;
+  const m = dict.maintenance;
   const dateLocale = locale === 'ar' ? ar : undefined;
   const base = `/${locale}/dashboard`;
+  const isMaintenance = role === 'maintenance';
 
   const { data: requests, isLoading: requestsLoading } =
     useListMaintenanceRequestsQuery();
   const { data: timelineData, isLoading: timelineLoading } =
     useListTimelineQuery({ limit: 5 });
+  const { data: assignedWorkOrders, isLoading: assignedLoading } =
+    useGetAssignedWorkOrdersQuery(undefined, { skip: !isMaintenance });
 
   const stats = maintenanceStats(requests);
   const attention = topActiveRequests(requests, 5);
@@ -65,22 +86,80 @@ export function StaffDashboard({ me, locale, dict }: StaffDashboardProps) {
         <p className="mt-1 text-sm text-muted-foreground">{k.staffOverview}</p>
       </div>
 
+      {/* My work orders — maintenance-role only. Surfaced above the KPI row
+          so a maintenance user sees their own assigned work first. */}
+      {isMaintenance && (
+        <section className="flex flex-col gap-3">
+          <div>
+            <h2 className="text-lg font-semibold tracking-tight">
+              {k.myWorkOrders.title}
+            </h2>
+            <p className="mt-0.5 text-sm text-muted-foreground">
+              {k.myWorkOrders.subtitle}
+            </p>
+          </div>
+          <div className="overflow-hidden rounded-xl border bg-card">
+            {assignedLoading ? (
+              <div className="flex flex-col gap-3 p-4">
+                {[0, 1, 2].map((i) => (
+                  <Skeleton key={i} className="h-10 w-full" />
+                ))}
+              </div>
+            ) : !assignedWorkOrders || assignedWorkOrders.length === 0 ? (
+              <p className="p-6 text-center text-sm text-muted-foreground">
+                {k.myWorkOrders.empty}
+              </p>
+            ) : (
+              <ul className="divide-y">
+                {assignedWorkOrders.map((row) => (
+                  <li key={row.id}>
+                    <Link
+                      href={`${base}/tasks/${row.maintenanceRequestId}`}
+                      className="flex items-center gap-3 px-4 py-3 transition-colors hover:bg-accent/40"
+                    >
+                      <div className="min-w-0 flex-1">
+                        <p className="truncate text-sm font-medium">
+                          {row.numberLabel} · {row.requestTitle}
+                        </p>
+                        <p className="truncate text-xs text-muted-foreground">
+                          {row.buildingName}
+                          {row.apartmentUnit
+                            ? ` · ${k.unit} ${row.apartmentUnit}`
+                            : ''}
+                        </p>
+                      </div>
+                      <Badge
+                        variant="outline"
+                        className={WORK_ORDER_STATUS_CLASS[row.status]}
+                      >
+                        {m.workOrderStatus[row.status]}
+                      </Badge>
+                      <ChevronRightIcon className="size-4 shrink-0 text-muted-foreground/60 rtl:rotate-180" />
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </div>
+        </section>
+      )}
+
       {/* KPI row — live from the maintenance-request list (building-scoped
           server-side; the one org-wide list both supervisor and maintenance
-          can read). All tiles deep-link into the tasks module. */}
+          can read). All tiles deep-link into the filtered tasks module. */}
       <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
         <KpiTile
           label={k.openRequests}
           value={String(stats.open)}
           icon={<WrenchIcon className="size-4" />}
-          href={`${base}/tasks`}
+          href={`${base}/tasks?status=open`}
           loading={requestsLoading}
         />
         <KpiTile
           label={k.inProgress}
           value={String(stats.inProgress)}
           icon={<LoaderIcon className="size-4" />}
-          href={`${base}/tasks`}
+          href={`${base}/tasks?status=in_progress`}
           loading={requestsLoading}
         />
         <KpiTile
@@ -88,7 +167,7 @@ export function StaffDashboard({ me, locale, dict }: StaffDashboardProps) {
           value={String(stats.activeUrgent)}
           tone={stats.activeUrgent > 0 ? 'negative' : 'neutral'}
           icon={<AlertTriangleIcon className="size-4" />}
-          href={`${base}/tasks`}
+          href={`${base}/tasks?priority=urgent`}
           loading={requestsLoading}
         />
         <KpiTile
@@ -96,7 +175,7 @@ export function StaffDashboard({ me, locale, dict }: StaffDashboardProps) {
           value={String(stats.resolved)}
           tone={stats.resolved > 0 ? 'positive' : 'neutral'}
           icon={<CheckCircle2Icon className="size-4" />}
-          href={`${base}/tasks`}
+          href={`${base}/tasks?status=resolved`}
           loading={requestsLoading}
         />
       </div>
@@ -122,7 +201,7 @@ export function StaffDashboard({ me, locale, dict }: StaffDashboardProps) {
               {attention.map((req) => (
                 <li key={req.id}>
                   <Link
-                    href={`${base}/tasks`}
+                    href={`${base}/tasks/${req.id}`}
                     className="flex items-center gap-3 px-4 py-3 transition-colors hover:bg-accent/40"
                   >
                     <div className="min-w-0 flex-1">
diff --git a/apps/web/src/components/dashboard/tasks-page.tsx b/apps/web/src/components/dashboard/tasks-page.tsx
index 9740a31b..4da1b833 100644
--- a/apps/web/src/components/dashboard/tasks-page.tsx
+++ b/apps/web/src/components/dashboard/tasks-page.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect, useMemo, useState } from 'react';
-import { useRouter } from 'next/navigation';
+import { useRouter, useSearchParams } from 'next/navigation';
 import { useForm, Controller } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
@@ -175,6 +175,8 @@ type EditFormValues = z.infer<ReturnType<typeof buildEditSchema>>;
 
 // ── Main component ────────────────────────────────────────────────────────────
 
+const ALL = '__all__';
+
 interface TasksPageProps {
   /** When false (non-admin), hide all write actions. */
   canWrite: boolean;
@@ -185,6 +187,7 @@ interface TasksPageProps {
 export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
   const t = dict.tasks;
   const router = useRouter();
+  const searchParams = useSearchParams();
   const {
     data: requests,
     isLoading,
@@ -193,6 +196,18 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
   const { data: buildings } = useListBuildingsQuery();
   const { data: renters } = useListRentersQuery();
 
+  // Dashboard KPI tiles deep-link here with `?status=` / `?priority=` to land
+  // pre-filtered (e.g. a supervisor's "urgent" tile). Unknown/absent values
+  // fall back to "all".
+  const [statusFilter, setStatusFilter] = useState<string>(() => {
+    const param = searchParams.get('status');
+    return param && (STATUSES as string[]).includes(param) ? param : ALL;
+  });
+  const [priorityFilter, setPriorityFilter] = useState<string>(() => {
+    const param = searchParams.get('priority');
+    return param && (PRIORITIES as string[]).includes(param) ? param : ALL;
+  });
+
   const [createMaintenanceRequest, { isLoading: creating }] =
     useCreateMaintenanceRequestMutation();
   const [updateMaintenanceRequest, { isLoading: updating }] =
@@ -218,6 +233,7 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
     reset: resetCreate,
     watch: watchCreate,
     setValue: setCreateValue,
+    getValues: getCreateValues,
     formState: { errors: createErrors },
   } = useForm<CreateFormValues>({
     resolver: zodResolver(createSchema),
@@ -227,6 +243,7 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
   const createBuildingId = watchCreate('buildingId');
   const createFloorId = watchCreate('floorId');
   const createApartmentId = watchCreate('apartmentId');
+  const createRenterId = watchCreate('renterId');
 
   const { data: createFloors } = useListFloorsQuery(createBuildingId, {
     skip: !createBuildingId,
@@ -247,12 +264,41 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
       (l) =>
         l.apartmentId === createApartmentId && l.effectiveStatus === 'active',
     );
-    if (activeLease) {
+    // Guard against ping-ponging with the renter→apartment effect below: only
+    // write when the value actually needs to change.
+    if (
+      activeLease &&
+      getCreateValues('renterId') !== activeLease.renterId
+    ) {
       setCreateValue('renterId', activeLease.renterId, {
         shouldValidate: true,
       });
     }
-  }, [createApartmentId, allLeases, setCreateValue]);
+  }, [createApartmentId, allLeases, setCreateValue, getCreateValues]);
+
+  // Reverse of the above: picking a renter with exactly one active lease
+  // fills building → floor → apartment from that lease (building must be set
+  // first since floor/apartment options are dependent queries). A renter with
+  // zero or multiple active leases leaves the fields for manual selection.
+  useEffect(() => {
+    if (!createRenterId) return;
+    const matches = allLeases?.filter(
+      (l) => l.renterId === createRenterId && l.effectiveStatus === 'active',
+    );
+    if (!matches || matches.length !== 1) return;
+    const [lease] = matches;
+    if (getCreateValues('buildingId') !== lease.buildingId) {
+      setCreateValue('buildingId', lease.buildingId, { shouldValidate: true });
+    }
+    if (getCreateValues('floorId') !== lease.floorId) {
+      setCreateValue('floorId', lease.floorId, { shouldValidate: true });
+    }
+    if (getCreateValues('apartmentId') !== lease.apartmentId) {
+      setCreateValue('apartmentId', lease.apartmentId, {
+        shouldValidate: true,
+      });
+    }
+  }, [createRenterId, allLeases, setCreateValue, getCreateValues]);
 
   const editSchema = useMemo(
     () => buildEditSchema(t.dialog.edit),
@@ -334,6 +380,20 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
     router.push(`/${locale}/dashboard/tasks/${requestId}`);
   }
 
+  const hasAnyRequests = (requests?.length ?? 0) > 0;
+
+  const filteredRequests = useMemo(() => {
+    return (requests ?? []).filter((request) => {
+      if (statusFilter !== ALL && request.status !== statusFilter) {
+        return false;
+      }
+      if (priorityFilter !== ALL && request.priority !== priorityFilter) {
+        return false;
+      }
+      return true;
+    });
+  }, [requests, statusFilter, priorityFilter]);
+
   return (
     <div className="flex flex-col gap-6">
       {/* Header */}
@@ -365,6 +425,65 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
         </div>
       </div>
 
+      {/* Filters */}
+      {hasAnyRequests && (
+        <div className="flex flex-wrap items-end gap-3 rounded-xl border bg-card p-4">
+          <div className="flex flex-col gap-1.5">
+            <Label htmlFor="tasks-filter-status">{t.filters.statusLabel}</Label>
+            <Select
+              value={statusFilter}
+              onValueChange={(val) => setStatusFilter(val ?? ALL)}
+            >
+              <SelectTrigger id="tasks-filter-status" className="w-40">
+                <SelectValue>
+                  {(value: string | null) =>
+                    !value || value === ALL
+                      ? t.filters.allStatuses
+                      : (t.status[value as MaintenanceRequestStatus] ?? value)
+                  }
+                </SelectValue>
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value={ALL}>{t.filters.allStatuses}</SelectItem>
+                {STATUSES.map((status) => (
+                  <SelectItem key={status} value={status}>
+                    {t.status[status]}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+          <div className="flex flex-col gap-1.5">
+            <Label htmlFor="tasks-filter-priority">
+              {t.filters.priorityLabel}
+            </Label>
+            <Select
+              value={priorityFilter}
+              onValueChange={(val) => setPriorityFilter(val ?? ALL)}
+            >
+              <SelectTrigger id="tasks-filter-priority" className="w-40">
+                <SelectValue>
+                  {(value: string | null) =>
+                    !value || value === ALL
+                      ? t.filters.allPriorities
+                      : (t.priority[value as MaintenanceRequestPriority] ??
+                        value)
+                  }
+                </SelectValue>
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value={ALL}>{t.filters.allPriorities}</SelectItem>
+                {PRIORITIES.map((priority) => (
+                  <SelectItem key={priority} value={priority}>
+                    {t.priority[priority]}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+        </div>
+      )}
+
       {/* Requests table */}
       <div className="rounded-xl border bg-card overflow-hidden">
         <Table>
@@ -411,7 +530,7 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
                   {t.list.loadError}
                 </TableCell>
               </TableRow>
-            ) : requests?.length === 0 ? (
+            ) : !hasAnyRequests ? (
               <TableRow>
                 <TableCell
                   colSpan={canWrite ? 6 : 5}
@@ -421,8 +540,17 @@ export function TasksPage({ canWrite, locale, dict }: TasksPageProps) {
                   {canWrite ? t.empty.write : t.empty.default}
                 </TableCell>
               </TableRow>
+            ) : filteredRequests.length === 0 ? (
+              <TableRow>
+                <TableCell
+                  colSpan={canWrite ? 6 : 5}
+                  className="text-center py-10 text-muted-foreground"
+                >
+                  {t.list.noMatch}
+                </TableCell>
+              </TableRow>
             ) : (
-              requests?.map((request) => (
+              filteredRequests.map((request) => (
                 <TableRow
                   key={request.id}
                   className="cursor-pointer hover:bg-muted/40"
diff --git a/apps/web/src/i18n/dictionaries/ar.json b/apps/web/src/i18n/dictionaries/ar.json
index b0809c56..6f6fb59c 100644
--- a/apps/web/src/i18n/dictionaries/ar.json
+++ b/apps/web/src/i18n/dictionaries/ar.json
@@ -173,6 +173,11 @@
         "medium": "متوسطة",
         "high": "عالية",
         "urgent": "عاجلة"
+      },
+      "myWorkOrders": {
+        "title": "أوامر العمل الخاصة بي",
+        "subtitle": "أوامر العمل المسندة إليك.",
+        "empty": "لا توجد أوامر عمل مسندة إليك بعد."
       }
     },
     "tenant": {
@@ -1138,10 +1143,12 @@
         "assignee": "المورّد / المكلَّف",
         "cost": "التكلفة",
         "resolutionNotes": "ملاحظات الحل",
-        "completed": "تاريخ الإنجاز"
+        "completed": "تاريخ الإنجاز",
+        "number": "أمر العمل"
       },
       "empty": "لا توجد أوامر عمل بعد.",
-      "updateStatusAction": "تحديث الحالة"
+      "updateStatusAction": "تحديث الحالة",
+      "assignedToYou": "مسندة إليك"
     },
     "workOrder": {
       "fields": {
@@ -1213,7 +1220,8 @@
       "actions": {
         "view": "عرض"
       },
-      "loadError": "تعذّر تحميل طلبات الصيانة. يرجى المحاولة مجدداً."
+      "loadError": "تعذّر تحميل طلبات الصيانة. يرجى المحاولة مجدداً.",
+      "noMatch": "لا توجد طلبات صيانة مطابقة للمرشحات الحالية."
     },
     "empty": {
       "default": "لا توجد طلبات صيانة بعد.",
@@ -1277,6 +1285,12 @@
         "success": "تم حذف طلب الصيانة.",
         "error": "تعذّر حذف طلب الصيانة."
       }
+    },
+    "filters": {
+      "statusLabel": "الحالة",
+      "allStatuses": "كل الحالات",
+      "priorityLabel": "الأولوية",
+      "allPriorities": "كل الأولويات"
     }
   },
   "expenses": {
diff --git a/apps/web/src/i18n/dictionaries/en.json b/apps/web/src/i18n/dictionaries/en.json
index ea917806..39927af9 100644
--- a/apps/web/src/i18n/dictionaries/en.json
+++ b/apps/web/src/i18n/dictionaries/en.json
@@ -173,6 +173,11 @@
         "medium": "Medium",
         "high": "High",
         "urgent": "Urgent"
+      },
+      "myWorkOrders": {
+        "title": "My work orders",
+        "subtitle": "Work orders assigned to you.",
+        "empty": "No work orders assigned to you yet."
       }
     },
     "tenant": {
@@ -1138,10 +1143,12 @@
         "assignee": "Vendor / Assignee",
         "cost": "Cost",
         "resolutionNotes": "Resolution notes",
-        "completed": "Completed"
+        "completed": "Completed",
+        "number": "Work order"
       },
       "empty": "No work orders yet.",
-      "updateStatusAction": "Update status"
+      "updateStatusAction": "Update status",
+      "assignedToYou": "Assigned to you"
     },
     "workOrder": {
       "fields": {
@@ -1213,7 +1220,8 @@
       "actions": {
         "view": "View"
       },
-      "loadError": "Failed to load maintenance requests. Please try again."
+      "loadError": "Failed to load maintenance requests. Please try again.",
+      "noMatch": "No maintenance requests match the current filters."
     },
     "empty": {
       "default": "No maintenance requests yet.",
@@ -1277,6 +1285,12 @@
         "success": "Maintenance request deleted.",
         "error": "Failed to delete maintenance request."
       }
+    },
+    "filters": {
+      "statusLabel": "Status",
+      "allStatuses": "All statuses",
+      "priorityLabel": "Priority",
+      "allPriorities": "All priorities"
     }
   },
   "expenses": {
diff --git a/apps/web/src/store/api/endpoints/work-orders.api.ts b/apps/web/src/store/api/endpoints/work-orders.api.ts
index c35f78de..c305974b 100644
--- a/apps/web/src/store/api/endpoints/work-orders.api.ts
+++ b/apps/web/src/store/api/endpoints/work-orders.api.ts
@@ -1,6 +1,7 @@
 import { baseApi } from '@/store/api/base-api';
 import type {
   ApiEnvelope,
+  AssignedWorkOrderRow,
   CreateWorkOrderBody,
   PatchWorkOrderBody,
   WorkOrderResponse,
@@ -95,6 +96,23 @@ export const workOrdersApi = baseApi.injectEndpoints({
       ],
     }),
 
+    // Work orders assigned to the calling (maintenance-role) user, enriched
+    // with request/building/apartment context — powers the "My work orders"
+    // dashboard section without drilling into each maintenance request.
+    getAssignedWorkOrders: build.query<AssignedWorkOrderRow[], void>({
+      query: () => ({ url: '/work-orders/assigned-to-me', method: 'GET' }),
+      transformResponse: (
+        response: AssignedWorkOrderRow[] | ApiEnvelope<AssignedWorkOrderRow[]>,
+      ) => unwrap(response),
+      providesTags: (result) =>
+        result
+          ? [
+              ...result.map(({ id }) => ({ type: 'WorkOrder' as const, id })),
+              { type: 'WorkOrder', id: 'ASSIGNED_TO_ME' },
+            ]
+          : [{ type: 'WorkOrder', id: 'ASSIGNED_TO_ME' }],
+    }),
+
     deleteWorkOrder: build.mutation<
       { id: string },
       MaintenanceRequestScope & { workOrderId: string }
@@ -126,4 +144,5 @@ export const {
   useCreateWorkOrderMutation,
   useUpdateWorkOrderMutation,
   useDeleteWorkOrderMutation,
+  useGetAssignedWorkOrdersQuery,
 } = workOrdersApi;
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index d927dab2..dc1b057c 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -583,6 +583,10 @@ export type WorkOrderStatus = z.infer<typeof workOrderStatusSchema>;
 export type WorkOrderResponse = {
   id: string;
   orgId: string;
+  /** Org-scoped sequential number (raw integer). */
+  number: number;
+  /** Pre-formatted display label, e.g. `WO-000123`. */
+  numberLabel: string;
   maintenanceRequestId: string;
   vendorId?: string | null;
   assignedUserId?: string | null;
@@ -594,11 +598,37 @@ export type WorkOrderResponse = {
   updatedAt: string;
 };
 
+/**
+ * Canonical work-order number formatter used on both the API and the web app so
+ * `WO-000123` renders identically everywhere a work order is referenced.
+ */
+export function formatWorkOrderNumber(n: number): string {
+  return `WO-${String(n).padStart(6, '0')}`;
+}
+
 /** GET /maintenance-requests/:id response — MaintenanceRequestResponse plus its full Work Order history. */
 export type MaintenanceRequestDetailResponse = MaintenanceRequestResponse & {
   workOrders: WorkOrderResponse[];
 };
 
+/**
+ * A work order assigned to the calling user, enriched with the parent request /
+ * apartment / building context so it can be surfaced as a standalone "My work
+ * orders" list (GET /work-orders/assigned-to-me) without drilling into a request.
+ */
+export type AssignedWorkOrderRow = WorkOrderResponse & {
+  requestTitle: string;
+  requestStatus: MaintenanceRequestStatus;
+  buildingId: string;
+  buildingName: string;
+  apartmentId: string;
+  apartmentUnit: string;
+};
+
+export type AssignedWorkOrderListResponse = {
+  data: AssignedWorkOrderRow[];
+};
+
 /**
  * maintenanceRequestId is implicit from the nested route (not part of the
  * body), matching the CreateLeaseBody precedent for apartmentId/floorId/
@@ -640,6 +670,8 @@ export type ExpenseResponse = {
   buildingId?: string | null;
   vendorId?: string | null;
   workOrderId?: string | null;
+  /** Pre-formatted `WO-000123` for the linked work order, if any (display). */
+  workOrderNumberLabel?: string | null;
   category: ExpenseCategory;
   amount: string; // Decimal(12,2) serialized as string
   incurredAt: string;
diff --git a/packages/database/prisma/migrations/20260721010000_add_work_order_number/migration.sql b/packages/database/prisma/migrations/20260721010000_add_work_order_number/migration.sql
new file mode 100644
index 00000000..afb1480d
--- /dev/null
+++ b/packages/database/prisma/migrations/20260721010000_add_work_order_number/migration.sql
@@ -0,0 +1,26 @@
+-- Add an org-scoped, human-readable sequential number to WorkOrder (rendered as
+-- `WO-000123` in the UI). New column added nullable, backfilled per org by
+-- creation order, then made NOT NULL with a per-org unique index.
+
+-- 1) Add the column (nullable for the backfill window).
+ALTER TABLE "WorkOrder" ADD COLUMN "number" INTEGER;
+
+-- 2) Backfill: number existing rows 1..N within each org, ordered by createdAt
+--    (id as a stable tie-breaker) so numbers are deterministic.
+WITH numbered AS (
+  SELECT
+    "id",
+    ROW_NUMBER() OVER (PARTITION BY "orgId" ORDER BY "createdAt" ASC, "id" ASC) AS rn
+  FROM "WorkOrder"
+)
+UPDATE "WorkOrder" AS w
+SET "number" = numbered.rn
+FROM numbered
+WHERE w."id" = numbered."id";
+
+-- 3) Enforce NOT NULL now that every row has a value.
+ALTER TABLE "WorkOrder" ALTER COLUMN "number" SET NOT NULL;
+
+-- 4) Guarantee uniqueness of (orgId, number). The application assigns the next
+--    number under a per-org advisory lock; this index is the backstop.
+CREATE UNIQUE INDEX "WorkOrder_orgId_number_key" ON "WorkOrder"("orgId", "number");
diff --git a/packages/database/prisma/schema.prisma b/packages/database/prisma/schema.prisma
index d4004661..29d0c600 100644
--- a/packages/database/prisma/schema.prisma
+++ b/packages/database/prisma/schema.prisma
@@ -322,6 +322,10 @@ model MaintenanceRequest {
 model WorkOrder {
   id                   String             @id @default(cuid())
   orgId                String
+  /// Org-scoped sequential number, rendered as `WO-000123` everywhere a work
+  /// order is referenced. Assigned on create under a per-org advisory lock and
+  /// guaranteed unique per org by @@unique([orgId, number]).
+  number               Int
   maintenanceRequestId String
   vendorId             String?
   assignedUserId       String?
@@ -335,6 +339,7 @@ model WorkOrder {
   vendor               Vendor?            @relation(fields: [vendorId], references: [id], onDelete: Restrict)
   expenses             Expense[]
 
+  @@unique([orgId, number])
   @@index([maintenanceRequestId])
   @@index([vendorId])
   @@index([orgId])

From d68db2c8689fcb0fbbaaf2e801846e1fe8fb7a58 Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 02:21:03 +0300
Subject: [PATCH 04/11] fix(F2.3): middleware sources sub-area gating from the
 authoritative permission matrix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root cause of the partner's Q23 ("clicking Tasks as supervisor bounces to the
dashboard"): proxy.ts (edge middleware) kept an INLINE hand-maintained copy of
the permission map that had drifted from auth/permissions.ts — its `tasks` entry
listed only org_admin + maintenance, omitting supervisor's `readonly`. So the
sidebar (which reads the real matrix) showed the Tasks link, but the edge
redirected supervisor off /dashboard/tasks -> /dashboard. Same class of bug
would recur on any future drift.

Fix: import PERMISSION_MATRIX + getAccess from auth/permissions.ts and gate
directly from it (renters->buildings alias + "unknown sub-area -> allow through"
fallback matching the previous semantics). permissions.ts is a plain object +
pure functions (type-only Role import) so it stays edge-runtime-safe. Divergence
between nav visibility and edge gating is now structurally impossible.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/web/src/proxy.ts | 61 ++++++++++++++++---------------------------
 1 file changed, 22 insertions(+), 39 deletions(-)

diff --git a/apps/web/src/proxy.ts b/apps/web/src/proxy.ts
index 462c8cd2..35639739 100644
--- a/apps/web/src/proxy.ts
+++ b/apps/web/src/proxy.ts
@@ -2,6 +2,11 @@ import { NextResponse, type NextRequest } from 'next/server';
 
 import { auth } from '@/auth/auth';
 import { dashboardPathForRole, normalizeRole, ROLES } from '@/auth/roles';
+import {
+  PERMISSION_MATRIX,
+  getAccess,
+  type DashboardArea,
+} from '@/auth/permissions';
 import { defaultLocale, isLocale } from '@/i18n/config';
 import type { Role } from '@/auth/roles';
 
@@ -37,48 +42,26 @@ const SESSION_COOKIE_NAMES = [
  */
 
 // ---------------------------------------------------------------------------
-// Inline permissions map (mirrors auth/permissions.ts — kept minimal so the
-// middleware stays edge-runtime-safe with no complex imports).
-// Roles listed here are the ONLY roles that MAY access each sub-area.
-// Omitting a sub-area means all authenticated users are allowed through
-// (the per-page guard handles finer gating).
+// Sub-area gating sources DIRECTLY from the authoritative permission matrix
+// (auth/permissions.ts) — no inline copy. A hand-maintained duplicate here
+// previously drifted (it omitted supervisor's readonly `tasks` access), so the
+// edge bounced supervisors off /dashboard/tasks even though the sidebar showed
+// the link. Importing the real matrix makes divergence structurally impossible.
+// permissions.ts is a plain object + pure functions (type-only Role import) →
+// edge-runtime safe.
+//
+// `renters` has no dedicated area — it reuses the `buildings` permission.
+// A sub-path not present in the matrix at all is let through (the per-page
+// guard remains the authoritative gate).
 // ---------------------------------------------------------------------------
 
-type AccessLevel = 'full' | 'readonly' | 'none';
-
-const AREA_PERMISSIONS: Record<string, Partial<Record<Role, AccessLevel>>> = {
-  users: {
-    org_admin: 'full',
-    supervisor: 'readonly',
-    // finance, maintenance, tenant → "none" (not listed ⇒ default none)
-  },
-  payments: {
-    org_admin: 'full',
-    finance: 'full',
-    supervisor: 'readonly',
-    // maintenance, tenant → none
-  },
-  reports: {
-    org_admin: 'full',
-    finance: 'full',
-    // supervisor, maintenance, tenant → none
-  },
-  billing: {
-    org_admin: 'full',
-    // supervisor, finance, maintenance, tenant → none
-  },
-  tasks: {
-    org_admin: 'full',
-    maintenance: 'full',
-    // supervisor, finance, tenant → none
-  },
-};
+const SUBAREA_ALIASES: Record<string, DashboardArea> = { renters: 'buildings' };
+const KNOWN_AREAS = new Set<string>(Object.keys(PERMISSION_MATRIX.org_admin));
 
-function roleCanAccessArea(role: Role, area: string): boolean {
-  const areaMap = AREA_PERMISSIONS[area];
-  if (!areaMap) return true; // unknown area → let it through, page guard decides
-  const level = areaMap[role] ?? 'none';
-  return level !== 'none';
+function roleCanAccessArea(role: Role, subArea: string): boolean {
+  const area = SUBAREA_ALIASES[subArea] ?? subArea;
+  if (!KNOWN_AREAS.has(area)) return true; // unknown sub-area → page guard decides
+  return getAccess(role, area as DashboardArea) !== 'none';
 }
 
 // ---------------------------------------------------------------------------

From 0f1d5f758edcf05cd3c49fbded7ebfc26864db93 Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 02:59:41 +0300
Subject: [PATCH 05/11] =?UTF-8?q?feat(F3):=20billing/invoicing/finance=20?=
 =?UTF-8?q?=E2=80=94=20recurring=20rent=20invoices,=20WO=E2=86=92tenant=20?=
 =?UTF-8?q?charge,=20reports/expense=20clarity?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sprint F3 of the Property Manager behavior roadmap (workflows W4/W7).

F3.1 [Q10] Recurring rent invoices (decision D1: monthly, anchored to the lease
  start day-of-month, generated within 7 days before the due date, idempotent
  per (lease, billing period), no proration). New recurring-invoices module:
  generateForLease (UTC-normalized, short-month clamp, 7-day lead window,
  active+start-date guard, idempotent via new Invoice.billingPeriod +
  @@unique([leaseId,billingPeriod]) with a P2002 race backstop) -> runForOrg/
  runAll; a BullMQ repeatable daily job (06:00) as the scheduler; and
  POST /recurring-invoices/run (org_admin) on-demand, surfaced as a
  "Generate rent invoices" button on the Invoices page.

F3.2 [Q13] Bill a tenant from a work order (decision D2: opt-in, default OFF).
  WorkOrder gains chargeToTenant + tenantChargeAmount + tenantChargedAt. On
  completion (create-as-completed or update-into-completed) with the flag + an
  amount + not-yet-charged, adds one invoice line item to the apartment's active
  lease (category other, due +30d) and stamps tenantChargedAt (idempotent; no
  active lease -> warn, no charge, no throw). FE: charge toggle + amount + badge.

F3.3 [Q14/39/40] Reports clarity — income = collected rent (cash basis), net =
  income - expenses (helper text/tooltips; no math change).

F3.4 [Q15] Expense != invoice clarification copy.

Two migrations (Invoice.billingPeriod; WorkOrder tenant-charge fields). i18n
parity en==ar 1046. Verified: api build EXIT 0 + jest 293 pass/4 skip (incl. 12
recurring + 5 WO-charge); web check-types clean, vitest 30/30, next build EXIT 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/api/src/app.module.ts                    |   2 +
 .../recurring-invoices-scheduler.service.ts   |  42 +++
 .../recurring-invoices.constants.ts           |  15 +
 .../recurring-invoices.controller.ts          |  30 ++
 .../recurring-invoices.module.ts              |  19 ++
 .../recurring-invoices.processor.ts           |  25 ++
 .../recurring-invoices.service.spec.ts        | 272 ++++++++++++++++++
 .../recurring-invoices.service.ts             | 238 +++++++++++++++
 .../work-orders/dto/create-work-order.dto.ts  |  23 +-
 .../work-orders/dto/update-work-order.dto.ts  |  14 +
 .../work-orders/work-order-formatter.ts       |   6 +
 .../work-orders/work-orders.service.spec.ts   | 270 ++++++++++++++++-
 .../work-orders/work-orders.service.ts        | 141 ++++++++-
 .../app/api/recurring-invoices/run/route.ts   |   7 +
 .../components/dashboard/expenses-page.tsx    |   6 +-
 .../components/dashboard/invoices-page.tsx    |  28 ++
 .../maintenance-request-detail-page.tsx       | 120 +++++++-
 .../src/components/dashboard/reports-page.tsx |   7 +
 apps/web/src/components/ui/checkbox.tsx       |  28 ++
 apps/web/src/i18n/dictionaries/ar.json        |  25 +-
 apps/web/src/i18n/dictionaries/en.json        |  25 +-
 .../src/store/api/endpoints/invoices.api.ts   |  14 +
 packages/contracts/src/index.ts               |  20 ++
 .../migration.sql                             |   8 +
 .../migration.sql                             |   9 +
 packages/database/prisma/schema.prisma        |  13 +
 26 files changed, 1381 insertions(+), 26 deletions(-)
 create mode 100644 apps/api/src/modules/recurring-invoices/recurring-invoices-scheduler.service.ts
 create mode 100644 apps/api/src/modules/recurring-invoices/recurring-invoices.constants.ts
 create mode 100644 apps/api/src/modules/recurring-invoices/recurring-invoices.controller.ts
 create mode 100644 apps/api/src/modules/recurring-invoices/recurring-invoices.module.ts
 create mode 100644 apps/api/src/modules/recurring-invoices/recurring-invoices.processor.ts
 create mode 100644 apps/api/src/modules/recurring-invoices/recurring-invoices.service.spec.ts
 create mode 100644 apps/api/src/modules/recurring-invoices/recurring-invoices.service.ts
 create mode 100644 apps/web/src/app/api/recurring-invoices/run/route.ts
 create mode 100644 apps/web/src/components/ui/checkbox.tsx
 create mode 100644 packages/database/prisma/migrations/20260721020000_add_invoice_billing_period/migration.sql
 create mode 100644 packages/database/prisma/migrations/20260721030000_add_work_order_tenant_charge/migration.sql

diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts
index f9d9411e..a90d2181 100644
--- a/apps/api/src/app.module.ts
+++ b/apps/api/src/app.module.ts
@@ -44,6 +44,7 @@ import { NotificationsModule } from '@/modules/notifications/notifications.modul
 import { SupportTicketsModule } from '@/modules/support-tickets/support-tickets.module';
 import { ReportsModule } from '@/modules/reports/reports.module';
 import { TenantModule } from '@/modules/tenant/tenant.module';
+import { RecurringInvoicesModule } from '@/modules/recurring-invoices/recurring-invoices.module';
 
 @Module({
   imports: [
@@ -110,6 +111,7 @@ import { TenantModule } from '@/modules/tenant/tenant.module';
     SupportTicketsModule,
     ReportsModule,
     TenantModule,
+    RecurringInvoicesModule,
   ],
   providers: [
     { provide: APP_GUARD, useClass: ThrottlerGuard },
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices-scheduler.service.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices-scheduler.service.ts
new file mode 100644
index 00000000..c61e9d0c
--- /dev/null
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices-scheduler.service.ts
@@ -0,0 +1,42 @@
+import { InjectQueue } from '@nestjs/bullmq';
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { Queue } from 'bullmq';
+import {
+  RECURRING_INVOICES_CRON,
+  RECURRING_INVOICES_DAILY_JOB_ID,
+  RECURRING_INVOICES_QUEUE,
+  RECURRING_INVOICES_RUN_JOB,
+} from './recurring-invoices.constants';
+
+/**
+ * Registers the daily repeatable job on module init (there is no
+ * `@nestjs/schedule` in this app — BullMQ's repeatable jobs are the
+ * scheduling primitive here, same as the rest of the queue infra). A fixed
+ * jobId means BullMQ upserts the same repeatable job definition on every app
+ * restart instead of accumulating duplicate schedules.
+ */
+@Injectable()
+export class RecurringInvoicesSchedulerService implements OnModuleInit {
+  private readonly logger = new Logger(RecurringInvoicesSchedulerService.name);
+
+  constructor(
+    @InjectQueue(RECURRING_INVOICES_QUEUE) private readonly queue: Queue,
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    try {
+      await this.queue.add(
+        RECURRING_INVOICES_RUN_JOB,
+        {},
+        {
+          repeat: { pattern: RECURRING_INVOICES_CRON },
+          jobId: RECURRING_INVOICES_DAILY_JOB_ID,
+        },
+      );
+    } catch (error) {
+      this.logger.error(
+        `Failed to schedule the daily recurring-invoices job: ${String(error)}`,
+      );
+    }
+  }
+}
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices.constants.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices.constants.ts
new file mode 100644
index 00000000..7d0e9228
--- /dev/null
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices.constants.ts
@@ -0,0 +1,15 @@
+/** Name of the BullMQ queue that drives the daily recurring-invoice run. */
+export const RECURRING_INVOICES_QUEUE = 'recurring-invoices';
+
+/** Job name used for the daily generation run. */
+export const RECURRING_INVOICES_RUN_JOB = 'run-daily';
+
+/**
+ * Fixed jobId for the repeatable job. BullMQ upserts a repeatable job by its
+ * (name, jobId, repeat options) — reusing this id on every app restart avoids
+ * accumulating duplicate schedules.
+ */
+export const RECURRING_INVOICES_DAILY_JOB_ID = 'recurring-invoices-daily';
+
+/** Daily at 06:00 UTC — well ahead of the 7-day generation lead window. */
+export const RECURRING_INVOICES_CRON = '0 6 * * *';
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices.controller.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices.controller.ts
new file mode 100644
index 00000000..9f5f8087
--- /dev/null
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices.controller.ts
@@ -0,0 +1,30 @@
+import { Controller, Post } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { RecurringInvoicesService } from './recurring-invoices.service';
+import { OrgScopeService } from '@/common/org-scope/org-scope.service';
+import { CurrentUser, Roles } from '@/common/decorators';
+import { AuthenticatedUser } from '@/common/types/authenticated-user.type';
+import { Role } from '@/common/enums';
+
+/**
+ * Manual "generate now" trigger for recurring rent invoices (F3.1). Runs the
+ * same idempotent core the daily scheduler runs, scoped to the caller's org —
+ * both a real feature (an org admin doesn't have to wait for the 06:00 UTC
+ * job) and the primary way to live-verify generation.
+ */
+@ApiTags('recurring-invoices')
+@ApiBearerAuth()
+@Controller('recurring-invoices')
+@Roles(Role.ORG_ADMIN)
+export class RecurringInvoicesController {
+  constructor(
+    private readonly recurringInvoices: RecurringInvoicesService,
+    private readonly orgScope: OrgScopeService,
+  ) {}
+
+  @Post('run')
+  async run(@CurrentUser() user: AuthenticatedUser) {
+    const { orgId } = await this.orgScope.resolveForCaller(user);
+    return this.recurringInvoices.runForOrg(orgId);
+  }
+}
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices.module.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices.module.ts
new file mode 100644
index 00000000..317bb2b4
--- /dev/null
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices.module.ts
@@ -0,0 +1,19 @@
+import { Module } from '@nestjs/common';
+import { BullModule } from '@nestjs/bullmq';
+import { RecurringInvoicesController } from './recurring-invoices.controller';
+import { RecurringInvoicesService } from './recurring-invoices.service';
+import { RecurringInvoicesProcessor } from './recurring-invoices.processor';
+import { RecurringInvoicesSchedulerService } from './recurring-invoices-scheduler.service';
+import { RECURRING_INVOICES_QUEUE } from './recurring-invoices.constants';
+
+@Module({
+  imports: [BullModule.registerQueue({ name: RECURRING_INVOICES_QUEUE })],
+  controllers: [RecurringInvoicesController],
+  providers: [
+    RecurringInvoicesService,
+    RecurringInvoicesProcessor,
+    RecurringInvoicesSchedulerService,
+  ],
+  exports: [RecurringInvoicesService],
+})
+export class RecurringInvoicesModule {}
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices.processor.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices.processor.ts
new file mode 100644
index 00000000..0f134e63
--- /dev/null
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices.processor.ts
@@ -0,0 +1,25 @@
+import { Processor, WorkerHost } from '@nestjs/bullmq';
+import { Logger } from '@nestjs/common';
+import { Job } from 'bullmq';
+import { RECURRING_INVOICES_QUEUE } from './recurring-invoices.constants';
+import { RecurringInvoicesService } from './recurring-invoices.service';
+
+/**
+ * Consumes the daily repeatable job and runs generation across every org.
+ * The manual `POST /recurring-invoices/run` endpoint calls
+ * {@link RecurringInvoicesService.runForOrg} directly (single-org, synchronous
+ * response) — this processor is only reached by the scheduled job.
+ */
+@Processor(RECURRING_INVOICES_QUEUE)
+export class RecurringInvoicesProcessor extends WorkerHost {
+  private readonly logger = new Logger(RecurringInvoicesProcessor.name);
+
+  constructor(private readonly recurringInvoices: RecurringInvoicesService) {
+    super();
+  }
+
+  async process(job: Job): Promise<void> {
+    this.logger.debug(`Starting recurring-invoice run (job ${job.id})`);
+    await this.recurringInvoices.runAll();
+  }
+}
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices.service.spec.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices.service.spec.ts
new file mode 100644
index 00000000..8336e4df
--- /dev/null
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices.service.spec.ts
@@ -0,0 +1,272 @@
+import { Prisma } from '@repo/db';
+import { RecurringInvoicesService } from './recurring-invoices.service';
+import { LeaseStatusService } from '@/common/lease-status/lease-status.service';
+
+describe('RecurringInvoicesService', () => {
+  const orgId = 'org-1';
+  const buildingId = 'building-1';
+  const leaseId = 'lease-1';
+
+  function makeService(
+    overrides: {
+      invoice?: Partial<Record<string, jest.Mock>>;
+      lease?: Partial<Record<string, jest.Mock>>;
+    } = {},
+  ) {
+    const prisma: any = {
+      invoice: {
+        findUnique: jest.fn().mockResolvedValue(null),
+        create: jest
+          .fn()
+          .mockImplementation((args: any) =>
+            Promise.resolve({ id: 'invoice-new', ...args.data }),
+          ),
+        ...overrides.invoice,
+      },
+      lease: {
+        findMany: jest.fn().mockResolvedValue([]),
+        ...overrides.lease,
+      },
+    };
+    const timeline = { emit: jest.fn().mockResolvedValue(undefined) };
+    const leaseStatus = new LeaseStatusService();
+    const service = new RecurringInvoicesService(
+      prisma,
+      timeline as any,
+      leaseStatus,
+    );
+    return { service, prisma, timeline, leaseStatus };
+  }
+
+  const lease = (overrides: Partial<Record<string, unknown>> = {}) => ({
+    id: leaseId,
+    orgId,
+    buildingId,
+    startDate: new Date('2026-01-15T00:00:00.000Z'),
+    endDate: new Date('2027-01-15T00:00:00.000Z'),
+    status: 'active',
+    rentAmount: new Prisma.Decimal('1000.00'),
+    ...overrides,
+  });
+
+  describe('generateForLease', () => {
+    it('creates an invoice when the next due date is within the 7-day lead window', async () => {
+      const { service, prisma, timeline } = makeService();
+      const asOf = new Date('2026-06-15T00:00:00.000Z'); // anchor day 15 — due today
+
+      const result = await service.generateForLease(lease(), asOf);
+
+      expect(result).toBe('created');
+      expect(prisma.invoice.create).toHaveBeenCalledWith({
+        data: {
+          orgId,
+          buildingId,
+          leaseId,
+          dueDate: new Date('2026-06-15T00:00:00.000Z'),
+          billingPeriod: '2026-06',
+          lineItems: {
+            create: [
+              {
+                category: 'rent',
+                description: 'Monthly rent',
+                amount: expect.any(Prisma.Decimal),
+              },
+            ],
+          },
+        },
+      });
+      expect(timeline.emit).toHaveBeenCalledWith(
+        expect.objectContaining({
+          orgId,
+          action: 'invoice.auto_generated',
+          targetType: 'Invoice',
+          metadata: { leaseId, billingPeriod: '2026-06' },
+        }),
+      );
+    });
+
+    it('clamps a 31st anchor into a short month (Feb) and still generates within the window', async () => {
+      const { service, prisma } = makeService();
+      const shortMonthLease = lease({
+        startDate: new Date('2026-01-31T00:00:00.000Z'),
+      });
+      const asOf = new Date('2026-02-24T00:00:00.000Z'); // 4 days before Feb 28 (clamped)
+
+      const result = await service.generateForLease(shortMonthLease, asOf);
+
+      expect(result).toBe('created');
+      expect(prisma.invoice.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            dueDate: new Date('2026-02-28T00:00:00.000Z'),
+            billingPeriod: '2026-02',
+          }),
+        }),
+      );
+    });
+
+    it('returns not-due when the next occurrence is more than 7 days away', async () => {
+      const { service, prisma } = makeService();
+      const asOf = new Date('2026-06-01T00:00:00.000Z'); // anchor 15th — 14 days away
+
+      const result = await service.generateForLease(lease(), asOf);
+
+      expect(result).toBe('not-due');
+      expect(prisma.invoice.create).not.toHaveBeenCalled();
+    });
+
+    it('returns skipped-existing when an invoice already exists for the billing period', async () => {
+      const { service, prisma } = makeService({
+        invoice: {
+          findUnique: jest.fn().mockResolvedValue({ id: 'existing-invoice' }),
+        },
+      });
+      const asOf = new Date('2026-06-15T00:00:00.000Z');
+
+      const result = await service.generateForLease(lease(), asOf);
+
+      expect(result).toBe('skipped-existing');
+      expect(prisma.invoice.create).not.toHaveBeenCalled();
+    });
+
+    it('is idempotent: calling generateForLease twice for the same period creates exactly one invoice', async () => {
+      // Fake the DB unique constraint on (leaseId, billingPeriod) with a tiny
+      // in-memory store, so the second call's findUnique sees what the first
+      // call's create wrote.
+      const store = new Map<string, unknown>();
+      const { service, prisma } = makeService({
+        invoice: {
+          findUnique: jest.fn().mockImplementation(({ where }: any) => {
+            const key = `${where.leaseId_billingPeriod.leaseId}:${where.leaseId_billingPeriod.billingPeriod}`;
+            return Promise.resolve(store.get(key) ?? null);
+          }),
+          create: jest.fn().mockImplementation(({ data }: any) => {
+            const key = `${data.leaseId}:${data.billingPeriod}`;
+            const row = { id: `invoice-${store.size + 1}`, ...data };
+            store.set(key, row);
+            return Promise.resolve(row);
+          }),
+        },
+      });
+      const asOf = new Date('2026-06-15T00:00:00.000Z');
+      const theLease = lease();
+
+      const first = await service.generateForLease(theLease, asOf);
+      const second = await service.generateForLease(theLease, asOf);
+
+      expect(first).toBe('created');
+      expect(second).toBe('skipped-existing');
+      expect(prisma.invoice.create).toHaveBeenCalledTimes(1);
+    });
+
+    it('treats a P2002 unique-constraint race on create as skipped-existing', async () => {
+      const { service, prisma } = makeService({
+        invoice: {
+          create: jest.fn().mockRejectedValue(
+            new Prisma.PrismaClientKnownRequestError('duplicate', {
+              code: 'P2002',
+              clientVersion: 'test',
+            }),
+          ),
+        },
+      });
+      const asOf = new Date('2026-06-15T00:00:00.000Z');
+
+      const result = await service.generateForLease(lease(), asOf);
+
+      expect(result).toBe('skipped-existing');
+    });
+
+    it('returns inactive when the lease has already ended by the candidate due date', async () => {
+      const { service, prisma } = makeService();
+      const endedLease = lease({
+        startDate: new Date('2025-01-15T00:00:00.000Z'),
+        endDate: new Date('2026-05-31T00:00:00.000Z'), // ended before the June candidate
+      });
+      const asOf = new Date('2026-06-10T00:00:00.000Z');
+
+      const result = await service.generateForLease(endedLease, asOf);
+
+      expect(result).toBe('inactive');
+      expect(prisma.invoice.create).not.toHaveBeenCalled();
+    });
+
+    it('returns inactive for a non-active (draft/terminated) lease status', async () => {
+      const { service } = makeService();
+      const draftLease = lease({ status: 'draft' });
+      const asOf = new Date('2026-06-15T00:00:00.000Z');
+
+      const result = await service.generateForLease(draftLease, asOf);
+
+      expect(result).toBe('inactive');
+    });
+
+    it('returns inactive when the computed candidate falls before the lease actually starts', async () => {
+      const { service, prisma } = makeService();
+      // Lease doesn't start until August 10th; asOf is in early June, well
+      // before the lease starts, yet the periodic anchor's June occurrence
+      // still falls within the 7-day lead window relative to asOf.
+      const futureLease = lease({
+        startDate: new Date('2026-08-10T00:00:00.000Z'),
+        endDate: new Date('2027-08-10T00:00:00.000Z'),
+      });
+      const asOf = new Date('2026-06-05T00:00:00.000Z');
+
+      const result = await service.generateForLease(futureLease, asOf);
+
+      expect(result).toBe('inactive');
+      expect(prisma.invoice.create).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('runForOrg', () => {
+    it("aggregates created/skipped/considered across the org's active leases", async () => {
+      const dueLease = lease({ id: 'lease-due' });
+      const notDueLease = lease({
+        id: 'lease-not-due',
+        startDate: new Date('2026-01-01T00:00:00.000Z'),
+      });
+      const { service, prisma } = makeService({
+        lease: {
+          findMany: jest.fn().mockResolvedValue([dueLease, notDueLease]),
+        },
+      });
+      const asOf = new Date('2026-06-15T00:00:00.000Z');
+
+      const result = await service.runForOrg(orgId, asOf);
+
+      expect(prisma.lease.findMany).toHaveBeenCalledWith(
+        expect.objectContaining({ where: { orgId, status: 'active' } }),
+      );
+      expect(result.leasesConsidered).toBe(2);
+      expect(result.generated).toBe(1);
+      expect(result.skippedExisting).toBe(0);
+    });
+  });
+
+  describe('runAll', () => {
+    it('sums runForOrg results across every org with an active lease', async () => {
+      const { service, prisma } = makeService({
+        lease: {
+          findMany: jest
+            .fn()
+            .mockResolvedValueOnce([{ orgId: 'org-a' }, { orgId: 'org-b' }]) // distinct orgId query
+            .mockResolvedValueOnce([lease({ orgId: 'org-a' })]) // org-a leases
+            .mockResolvedValueOnce([lease({ orgId: 'org-b', id: 'lease-2' })]), // org-b leases
+        },
+      });
+      const asOf = new Date('2026-06-15T00:00:00.000Z');
+
+      const result = await service.runAll(asOf);
+
+      expect(prisma.lease.findMany).toHaveBeenNthCalledWith(1, {
+        where: { status: 'active' },
+        select: { orgId: true },
+        distinct: ['orgId'],
+      });
+      expect(result.leasesConsidered).toBe(2);
+      expect(result.generated).toBe(2);
+      expect(result.skippedExisting).toBe(0);
+    });
+  });
+});
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices.service.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices.service.ts
new file mode 100644
index 00000000..e07c9d55
--- /dev/null
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices.service.ts
@@ -0,0 +1,238 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Prisma } from '@repo/db';
+import { PrismaService } from '@/infrastructure/prisma/prisma.service';
+import { TimelineService } from '@/modules/timeline/timeline.service';
+import { LeaseStatusService } from '@/common/lease-status/lease-status.service';
+import { LeaseStatus, RecurringInvoiceRunResponse } from '@repo/contracts';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/** Generate 7 days before the computed due date (decision D1). */
+const LEAD_WINDOW_DAYS = 7;
+
+export type GenerateResult =
+  'created' | 'skipped-existing' | 'not-due' | 'inactive';
+
+/**
+ * The minimal lease shape {@link RecurringInvoicesService.generateForLease}
+ * needs. Deliberately DB-shape-agnostic (plain fields, no Prisma payload
+ * types) so unit tests can hand-build fixtures without a real Lease row.
+ */
+export type RecurringLeaseInput = {
+  id: string;
+  orgId: string;
+  buildingId: string;
+  startDate: Date;
+  endDate: Date;
+  /** Raw DB status ('draft' | 'active' | 'terminated' — 'expired' is derived, never stored). */
+  status: string;
+  rentAmount: Prisma.Decimal | number;
+};
+
+/**
+ * F3.1 recurring rent invoices (decision D1): monthly, anchored to the
+ * lease's start-date day-of-month, generated 7 days before the computed due
+ * date, idempotent per (lease, billing period) via the Invoice
+ * `@@unique([leaseId, billingPeriod])` constraint. No proration — the line
+ * item is always the flat `lease.rentAmount`.
+ */
+@Injectable()
+export class RecurringInvoicesService {
+  private readonly logger = new Logger(RecurringInvoicesService.name);
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly timeline: TimelineService,
+    private readonly leaseStatus: LeaseStatusService,
+  ) {}
+
+  /** UTC midnight for `date` — every comparison below is done at day granularity. */
+  private startOfUtcDay(date: Date): Date {
+    return new Date(
+      Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
+    );
+  }
+
+  /**
+   * `anchorDay` clamped into (year, month) — e.g. anchor 31 in a 28-day
+   * February becomes Feb 28. `month` may be any integer (including < 0 or
+   * > 11); `Date.UTC` normalizes the overflow/underflow into the correct
+   * year, which is what lets `nextDueDate` roll into next month for free.
+   */
+  private clampedDateForMonth(
+    year: number,
+    month: number,
+    anchorDay: number,
+  ): Date {
+    const lastDayOfMonth = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(year, month, Math.min(anchorDay, lastDayOfMonth)));
+  }
+
+  /**
+   * The next occurrence of `anchorDay` on/after `today` (both already
+   * UTC-midnight-normalized): this month's occurrence (clamped for short
+   * months), or next month's if this month's has already passed.
+   */
+  private nextDueDate(anchorDay: number, today: Date): Date {
+    const thisMonth = this.clampedDateForMonth(
+      today.getUTCFullYear(),
+      today.getUTCMonth(),
+      anchorDay,
+    );
+    if (thisMonth < today) {
+      return this.clampedDateForMonth(
+        today.getUTCFullYear(),
+        today.getUTCMonth() + 1,
+        anchorDay,
+      );
+    }
+    return thisMonth;
+  }
+
+  private billingPeriodKey(date: Date): string {
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    return `${date.getUTCFullYear()}-${month}`;
+  }
+
+  /**
+   * Pure, idempotent core: given a lease and an "as of" date, decide whether
+   * a rent invoice is due and — if so — create it. Safe to call repeatedly
+   * for the same (lease, asOf): a second call in the same billing period is
+   * a no-op ('skipped-existing'), backstopped by the DB unique constraint
+   * even under a concurrent-writer race.
+   */
+  async generateForLease(
+    lease: RecurringLeaseInput,
+    asOf: Date,
+  ): Promise<GenerateResult> {
+    const today = this.startOfUtcDay(asOf);
+    const anchorDay = lease.startDate.getUTCDate();
+    const candidate = this.nextDueDate(anchorDay, today);
+
+    const leadDays = Math.round(
+      (candidate.getTime() - today.getTime()) / MS_PER_DAY,
+    );
+    if (leadDays > LEAD_WINDOW_DAYS) {
+      return 'not-due';
+    }
+
+    const isActive = this.leaseStatus.isEffectivelyActive(
+      { status: lease.status as LeaseStatus, endDate: lease.endDate },
+      candidate,
+    );
+    if (candidate < this.startOfUtcDay(lease.startDate) || !isActive) {
+      return 'inactive';
+    }
+
+    const billingPeriod = this.billingPeriodKey(candidate);
+
+    const existing = await this.prisma.invoice.findUnique({
+      where: { leaseId_billingPeriod: { leaseId: lease.id, billingPeriod } },
+    });
+    if (existing) {
+      return 'skipped-existing';
+    }
+
+    try {
+      const invoice = await this.prisma.invoice.create({
+        data: {
+          orgId: lease.orgId,
+          buildingId: lease.buildingId,
+          leaseId: lease.id,
+          dueDate: candidate,
+          billingPeriod,
+          lineItems: {
+            create: [
+              {
+                category: 'rent',
+                description: 'Monthly rent',
+                amount: lease.rentAmount,
+              },
+            ],
+          },
+        },
+      });
+
+      await this.timeline.emit({
+        orgId: lease.orgId,
+        action: 'invoice.auto_generated',
+        targetType: 'Invoice',
+        targetId: invoice.id,
+        metadata: { leaseId: lease.id, billingPeriod },
+      });
+
+      return 'created';
+    } catch (err) {
+      if (
+        err instanceof Prisma.PrismaClientKnownRequestError &&
+        err.code === 'P2002'
+      ) {
+        // Idempotency backstop: another writer created the same
+        // (leaseId, billingPeriod) invoice in the race window between our
+        // existence check and this create.
+        return 'skipped-existing';
+      }
+      throw err;
+    }
+  }
+
+  /** Run generation for every active lease in one org. */
+  async runForOrg(
+    orgId: string,
+    asOf: Date = new Date(),
+  ): Promise<RecurringInvoiceRunResponse> {
+    const leases = await this.prisma.lease.findMany({
+      where: { orgId, status: 'active' },
+      select: {
+        id: true,
+        orgId: true,
+        buildingId: true,
+        startDate: true,
+        endDate: true,
+        status: true,
+        rentAmount: true,
+      },
+    });
+
+    let generated = 0;
+    let skippedExisting = 0;
+    for (const lease of leases) {
+      const result = await this.generateForLease(lease, asOf);
+      if (result === 'created') generated++;
+      else if (result === 'skipped-existing') skippedExisting++;
+    }
+
+    return { generated, leasesConsidered: leases.length, skippedExisting };
+  }
+
+  /**
+   * Run generation across every org — the daily scheduler's entry point.
+   * Iterates orgs (derived from the set of orgs with an active lease) and
+   * aggregates each org's {@link runForOrg} result.
+   */
+  async runAll(asOf: Date = new Date()): Promise<RecurringInvoiceRunResponse> {
+    const orgs = await this.prisma.lease.findMany({
+      where: { status: 'active' },
+      select: { orgId: true },
+      distinct: ['orgId'],
+    });
+
+    const totals: RecurringInvoiceRunResponse = {
+      generated: 0,
+      leasesConsidered: 0,
+      skippedExisting: 0,
+    };
+    for (const { orgId } of orgs) {
+      const result = await this.runForOrg(orgId, asOf);
+      totals.generated += result.generated;
+      totals.leasesConsidered += result.leasesConsidered;
+      totals.skippedExisting += result.skippedExisting;
+    }
+
+    this.logger.log(
+      `Recurring invoice run: generated=${totals.generated} considered=${totals.leasesConsidered} skipped=${totals.skippedExisting}`,
+    );
+
+    return totals;
+  }
+}
diff --git a/apps/api/src/modules/work-orders/dto/create-work-order.dto.ts b/apps/api/src/modules/work-orders/dto/create-work-order.dto.ts
index 778203b3..35f735db 100644
--- a/apps/api/src/modules/work-orders/dto/create-work-order.dto.ts
+++ b/apps/api/src/modules/work-orders/dto/create-work-order.dto.ts
@@ -1,4 +1,11 @@
-import { IsEnum, IsNumber, IsOptional, IsString, Min } from 'class-validator';
+import {
+  IsBoolean,
+  IsEnum,
+  IsNumber,
+  IsOptional,
+  IsString,
+  Min,
+} from 'class-validator';
 import { ApiPropertyOptional } from '@nestjs/swagger';
 import { WorkOrderStatus } from '@repo/db';
 
@@ -31,4 +38,18 @@ export class CreateWorkOrderDto {
   @IsOptional()
   @IsString()
   resolutionNotes?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Opt-in: bill this work order to the tenant on completion. Defaults to false.',
+  })
+  @IsOptional()
+  @IsBoolean()
+  chargeToTenant?: boolean;
+
+  @ApiPropertyOptional({ nullable: true })
+  @IsOptional()
+  @IsNumber({ maxDecimalPlaces: 2 })
+  @Min(0)
+  tenantChargeAmount?: number | null;
 }
diff --git a/apps/api/src/modules/work-orders/dto/update-work-order.dto.ts b/apps/api/src/modules/work-orders/dto/update-work-order.dto.ts
index b169dd18..5312b024 100644
--- a/apps/api/src/modules/work-orders/dto/update-work-order.dto.ts
+++ b/apps/api/src/modules/work-orders/dto/update-work-order.dto.ts
@@ -1,4 +1,5 @@
 import {
+  IsBoolean,
   IsDateString,
   IsEnum,
   IsNumber,
@@ -40,4 +41,17 @@ export class UpdateWorkOrderDto {
   @IsOptional()
   @IsDateString()
   completedAt?: string | null;
+
+  @ApiPropertyOptional({
+    description: 'Opt-in: bill this work order to the tenant on completion.',
+  })
+  @IsOptional()
+  @IsBoolean()
+  chargeToTenant?: boolean;
+
+  @ApiPropertyOptional({ nullable: true })
+  @IsOptional()
+  @IsNumber({ maxDecimalPlaces: 2 })
+  @Min(0)
+  tenantChargeAmount?: number | null;
 }
diff --git a/apps/api/src/modules/work-orders/work-order-formatter.ts b/apps/api/src/modules/work-orders/work-order-formatter.ts
index 8f8cb84d..32bb1b76 100644
--- a/apps/api/src/modules/work-orders/work-order-formatter.ts
+++ b/apps/api/src/modules/work-orders/work-order-formatter.ts
@@ -12,6 +12,9 @@ export type WorkOrderRow = {
   cost: Prisma.Decimal | null;
   resolutionNotes: string | null;
   completedAt: Date | null;
+  chargeToTenant: boolean;
+  tenantChargeAmount: Prisma.Decimal | null;
+  tenantChargedAt: Date | null;
   createdAt: Date;
   updatedAt: Date;
 };
@@ -30,6 +33,9 @@ export function formatWorkOrder(workOrder: WorkOrderRow): WorkOrderResponse {
     cost: workOrder.cost?.toString() ?? null,
     resolutionNotes: workOrder.resolutionNotes,
     completedAt: workOrder.completedAt?.toISOString() ?? null,
+    chargeToTenant: workOrder.chargeToTenant,
+    tenantChargeAmount: workOrder.tenantChargeAmount?.toString() ?? null,
+    tenantChargedAt: workOrder.tenantChargedAt?.toISOString() ?? null,
     createdAt: workOrder.createdAt.toISOString(),
     updatedAt: workOrder.updatedAt.toISOString(),
   };
diff --git a/apps/api/src/modules/work-orders/work-orders.service.spec.ts b/apps/api/src/modules/work-orders/work-orders.service.spec.ts
index 7e09d2fd..2e4aafdc 100644
--- a/apps/api/src/modules/work-orders/work-orders.service.spec.ts
+++ b/apps/api/src/modules/work-orders/work-orders.service.spec.ts
@@ -21,7 +21,10 @@ describe('WorkOrdersService', () => {
       maintenanceRequest?: Partial<Record<string, jest.Mock>>;
       workOrder?: Partial<Record<string, jest.Mock>>;
       expense?: Partial<Record<string, jest.Mock>>;
+      lease?: Partial<Record<string, jest.Mock>>;
+      invoice?: Partial<Record<string, jest.Mock>>;
       buildingAccess?: Partial<Record<string, jest.Mock>>;
+      leaseStatus?: Partial<Record<string, jest.Mock>>;
       workOrderApartmentStatus?: Partial<Record<string, jest.Mock>>;
     } = {},
   ) {
@@ -32,6 +35,7 @@ describe('WorkOrdersService', () => {
           orgId,
           buildingId,
           apartmentId,
+          title: 'Leaking faucet',
         }),
         ...overrides.maintenanceRequest,
       },
@@ -48,8 +52,19 @@ describe('WorkOrdersService', () => {
         count: jest.fn().mockResolvedValue(0),
         ...overrides.expense,
       },
+      // F3.2 tenant-charge path: find the apartment's active lease and create
+      // a new invoice on it.
+      lease: {
+        findFirst: jest.fn().mockResolvedValue(null),
+        ...overrides.lease,
+      },
+      invoice: {
+        create: jest.fn().mockResolvedValue({ id: 'invoice-1' }),
+        ...overrides.invoice,
+      },
       // create() assigns the org-scoped number inside a transaction + advisory
-      // lock. Run the callback against the same mock and stub the raw lock.
+      // lock; the tenant-charge path also runs inside a $transaction. Run the
+      // callback against the same mock and stub the raw lock.
       $executeRaw: jest.fn().mockResolvedValue(1),
       $transaction: jest.fn(),
     };
@@ -59,6 +74,10 @@ describe('WorkOrdersService', () => {
       ...overrides.buildingAccess,
     };
     const timeline = { emit: jest.fn().mockResolvedValue(undefined) };
+    const leaseStatus = {
+      isEffectivelyActive: jest.fn().mockReturnValue(true),
+      ...overrides.leaseStatus,
+    };
     const workOrderApartmentStatus = {
       onWorkOrderOpened: jest.fn().mockResolvedValue(undefined),
       onWorkOrderClosed: jest.fn().mockResolvedValue(undefined),
@@ -68,6 +87,7 @@ describe('WorkOrdersService', () => {
       prisma,
       buildingAccess as any,
       timeline as any,
+      leaseStatus as any,
       workOrderApartmentStatus as any,
     );
     return {
@@ -75,6 +95,7 @@ describe('WorkOrdersService', () => {
       prisma,
       buildingAccess,
       timeline,
+      leaseStatus,
       workOrderApartmentStatus,
     };
   }
@@ -90,6 +111,9 @@ describe('WorkOrdersService', () => {
     cost: new Prisma.Decimal('150.00'),
     resolutionNotes: null,
     completedAt: null,
+    chargeToTenant: false,
+    tenantChargeAmount: null,
+    tenantChargedAt: null,
     createdAt: new Date('2026-01-01T00:00:00.000Z'),
     updatedAt: new Date('2026-01-01T00:00:00.000Z'),
     ...overrides,
@@ -264,7 +288,7 @@ describe('WorkOrdersService', () => {
       ...overrides,
     });
 
-    it("queries only work orders assigned to the caller, ordered by createdAt desc", async () => {
+    it('queries only work orders assigned to the caller, ordered by createdAt desc', async () => {
       const { service, prisma } = makeService({
         workOrder: { findMany: jest.fn().mockResolvedValue([assignedRow()]) },
       });
@@ -296,9 +320,7 @@ describe('WorkOrdersService', () => {
     it('enriches each row with request/apartment/building context and the numberLabel', async () => {
       const { service } = makeService({
         workOrder: {
-          findMany: jest
-            .fn()
-            .mockResolvedValue([assignedRow({ number: 123 })]),
+          findMany: jest.fn().mockResolvedValue([assignedRow({ number: 123 })]),
         },
       });
 
@@ -319,7 +341,7 @@ describe('WorkOrdersService', () => {
       ]);
     });
 
-    it("returns an empty list when the caller has no assigned work orders", async () => {
+    it('returns an empty list when the caller has no assigned work orders', async () => {
       const { service, prisma } = makeService({
         workOrder: { findMany: jest.fn().mockResolvedValue([]) },
       });
@@ -433,9 +455,11 @@ describe('WorkOrdersService', () => {
       const { service, prisma } = makeService({
         workOrder: {
           aggregate: jest.fn().mockResolvedValue({ _max: { number: 41 } }),
-          create: jest.fn().mockResolvedValue(
-            workOrderRow({ number: 42, vendorId: 'vendor-1' }),
-          ),
+          create: jest
+            .fn()
+            .mockResolvedValue(
+              workOrderRow({ number: 42, vendorId: 'vendor-1' }),
+            ),
         },
       });
 
@@ -449,7 +473,9 @@ describe('WorkOrdersService', () => {
 
       expect(prisma.$executeRaw).toHaveBeenCalled(); // advisory lock taken
       expect(prisma.workOrder.create).toHaveBeenCalledWith(
-        expect.objectContaining({ data: expect.objectContaining({ number: 42 }) }),
+        expect.objectContaining({
+          data: expect.objectContaining({ number: 42 }),
+        }),
       );
       expect(result.data.number).toBe(42);
       expect(result.data.numberLabel).toBe('WO-000042');
@@ -503,6 +529,121 @@ describe('WorkOrdersService', () => {
     });
   });
 
+  describe('create — tenant charge on completion (F3.2)', () => {
+    const activeLeaseRow = {
+      id: 'lease-1',
+      buildingId,
+      status: 'active',
+      endDate: new Date('2030-01-01T00:00:00.000Z'),
+    };
+
+    it("charges the apartment's active lease when created directly as completed with chargeToTenant", async () => {
+      const { service, prisma, timeline } = makeService({
+        lease: { findFirst: jest.fn().mockResolvedValue(activeLeaseRow) },
+      });
+      prisma.workOrder.create.mockResolvedValue(
+        workOrderRow({
+          status: 'completed',
+          chargeToTenant: true,
+          tenantChargeAmount: new Prisma.Decimal('75.00'),
+        }),
+      );
+
+      await service.create(
+        orgId,
+        actorId,
+        Role.ORG_ADMIN,
+        maintenanceRequestId,
+        {
+          vendorId: 'vendor-1',
+          status: 'completed',
+          chargeToTenant: true,
+          tenantChargeAmount: 75,
+        },
+      );
+
+      expect(prisma.lease.findFirst).toHaveBeenCalledWith({
+        where: { orgId, apartmentId, status: 'active' },
+        orderBy: { startDate: 'desc' },
+      });
+      expect(prisma.invoice.create).toHaveBeenCalledWith({
+        data: expect.objectContaining({
+          orgId,
+          buildingId,
+          leaseId: 'lease-1',
+          lineItems: {
+            create: [
+              expect.objectContaining({
+                category: 'other',
+                description: 'Work order WO-000001: Leaking faucet',
+              }),
+            ],
+          },
+        }),
+      });
+      expect(prisma.workOrder.update).toHaveBeenCalledWith({
+        where: { id: 'wo-1' },
+        data: { tenantChargedAt: expect.any(Date) },
+      });
+      expect(timeline.emit).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: 'work_order.tenant_charged',
+          targetId: 'wo-1',
+        }),
+      );
+    });
+
+    it('does not charge and does not throw when the apartment has no active lease', async () => {
+      const { service, prisma } = makeService({
+        lease: { findFirst: jest.fn().mockResolvedValue(null) },
+      });
+      prisma.workOrder.create.mockResolvedValue(
+        workOrderRow({
+          status: 'completed',
+          chargeToTenant: true,
+          tenantChargeAmount: new Prisma.Decimal('75.00'),
+        }),
+      );
+
+      await expect(
+        service.create(orgId, actorId, Role.ORG_ADMIN, maintenanceRequestId, {
+          vendorId: 'vendor-1',
+          status: 'completed',
+          chargeToTenant: true,
+          tenantChargeAmount: 75,
+        }),
+      ).resolves.toBeDefined();
+
+      expect(prisma.invoice.create).not.toHaveBeenCalled();
+      expect(prisma.workOrder.update).not.toHaveBeenCalled();
+    });
+
+    it('does not charge when chargeToTenant is false even though tenantChargeAmount is set', async () => {
+      const { service, prisma } = makeService();
+      prisma.workOrder.create.mockResolvedValue(
+        workOrderRow({
+          status: 'completed',
+          chargeToTenant: false,
+          tenantChargeAmount: new Prisma.Decimal('75.00'),
+        }),
+      );
+
+      await service.create(
+        orgId,
+        actorId,
+        Role.ORG_ADMIN,
+        maintenanceRequestId,
+        {
+          vendorId: 'vendor-1',
+          status: 'completed',
+        },
+      );
+
+      expect(prisma.lease.findFirst).not.toHaveBeenCalled();
+      expect(prisma.invoice.create).not.toHaveBeenCalled();
+    });
+  });
+
   describe('update', () => {
     const existingRow = () => ({
       ...workOrderRow(),
@@ -703,6 +844,115 @@ describe('WorkOrdersService', () => {
     });
   });
 
+  describe('update — tenant charge transition (F3.2)', () => {
+    const existingInProgressWithCharge = () => ({
+      ...workOrderRow({
+        status: 'in_progress',
+        chargeToTenant: true,
+        tenantChargeAmount: new Prisma.Decimal('120.00'),
+      }),
+      maintenanceRequest: { apartmentId, title: 'Leaking faucet' },
+    });
+
+    const activeLeaseRow = {
+      id: 'lease-1',
+      buildingId,
+      status: 'active',
+      endDate: new Date('2030-01-01T00:00:00.000Z'),
+    };
+
+    it('charges the active lease when a chargeToTenant work order transitions to completed', async () => {
+      const { service, prisma, timeline } = makeService({
+        workOrder: {
+          findFirst: jest
+            .fn()
+            .mockResolvedValue(existingInProgressWithCharge()),
+          update: jest.fn().mockResolvedValue(
+            workOrderRow({
+              status: 'completed',
+              chargeToTenant: true,
+              tenantChargeAmount: new Prisma.Decimal('120.00'),
+            }),
+          ),
+        },
+        lease: { findFirst: jest.fn().mockResolvedValue(activeLeaseRow) },
+      });
+
+      await service.update(
+        orgId,
+        actorId,
+        callerId,
+        Role.ORG_ADMIN,
+        maintenanceRequestId,
+        'wo-1',
+        { status: 'completed' },
+      );
+
+      expect(prisma.lease.findFirst).toHaveBeenCalledWith({
+        where: { orgId, apartmentId, status: 'active' },
+        orderBy: { startDate: 'desc' },
+      });
+      expect(prisma.invoice.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            leaseId: 'lease-1',
+            buildingId,
+            lineItems: {
+              create: [
+                expect.objectContaining({
+                  category: 'other',
+                  description: 'Work order WO-000001: Leaking faucet',
+                }),
+              ],
+            },
+          }),
+        }),
+      );
+      // First call is the main status update; the second is the tenantChargedAt
+      // stamp inside chargeTenantIfDue's transaction.
+      expect(prisma.workOrder.update).toHaveBeenNthCalledWith(2, {
+        where: { id: 'wo-1' },
+        data: { tenantChargedAt: expect.any(Date) },
+      });
+      expect(timeline.emit).toHaveBeenCalledWith(
+        expect.objectContaining({ action: 'work_order.tenant_charged' }),
+      );
+    });
+
+    it('does not double-charge when re-completing an already-charged work order', async () => {
+      const { service, prisma } = makeService({
+        workOrder: {
+          findFirst: jest
+            .fn()
+            .mockResolvedValue(existingInProgressWithCharge()),
+          update: jest.fn().mockResolvedValue(
+            workOrderRow({
+              status: 'completed',
+              chargeToTenant: true,
+              tenantChargeAmount: new Prisma.Decimal('120.00'),
+              tenantChargedAt: new Date('2026-01-05T00:00:00.000Z'),
+            }),
+          ),
+        },
+      });
+
+      await service.update(
+        orgId,
+        actorId,
+        callerId,
+        Role.ORG_ADMIN,
+        maintenanceRequestId,
+        'wo-1',
+        { status: 'completed' },
+      );
+
+      expect(prisma.lease.findFirst).not.toHaveBeenCalled();
+      expect(prisma.invoice.create).not.toHaveBeenCalled();
+      // Only the main status update — no second (tenantChargedAt-stamp) call.
+      expect(prisma.workOrder.update).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('remove', () => {
     it('deletes the work order, reverts the apartment via onWorkOrderClosed, and emits work_order.deleted', async () => {
       const { service, prisma, timeline, workOrderApartmentStatus } =
diff --git a/apps/api/src/modules/work-orders/work-orders.service.ts b/apps/api/src/modules/work-orders/work-orders.service.ts
index 130965da..fa7d01b2 100644
--- a/apps/api/src/modules/work-orders/work-orders.service.ts
+++ b/apps/api/src/modules/work-orders/work-orders.service.ts
@@ -3,17 +3,21 @@ import {
   ConflictException,
   ForbiddenException,
   Injectable,
+  Logger,
   NotFoundException,
 } from '@nestjs/common';
+import { Prisma } from '@repo/db';
 import { PrismaService } from '@/infrastructure/prisma/prisma.service';
 import { BuildingAccessService } from '@/common/building-access/building-access.service';
 import { TimelineService } from '@/modules/timeline/timeline.service';
+import { LeaseStatusService } from '@/common/lease-status/lease-status.service';
 import { WorkOrderApartmentStatusService } from './work-order-apartment-status.service';
 import { Role } from '@/common/enums';
 import {
   AssignedWorkOrderListResponse,
   MaintenanceRequestStatus,
   WorkOrderResponse,
+  formatWorkOrderNumber,
 } from '@repo/contracts';
 import { formatWorkOrder } from './work-order-formatter';
 import { CreateWorkOrderDto } from './dto/create-work-order.dto';
@@ -21,16 +25,117 @@ import { UpdateWorkOrderDto } from './dto/update-work-order.dto';
 
 const OPEN_STATUSES = new Set(['scheduled', 'in_progress']);
 const MAINTENANCE_ALLOWED_FIELDS = new Set(['status', 'resolutionNotes']);
+/** How long a tenant has to pay a work-order charge (F3.2, decision D2). */
+const TENANT_CHARGE_DUE_DAYS = 30;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/** Just what {@link WorkOrdersService.chargeTenantIfDue} needs from a freshly created/updated row. */
+type ChargeableWorkOrder = {
+  id: string;
+  number: number;
+  chargeToTenant: boolean;
+  tenantChargeAmount: Prisma.Decimal | null;
+  tenantChargedAt: Date | null;
+};
 
 @Injectable()
 export class WorkOrdersService {
+  private readonly logger = new Logger(WorkOrdersService.name);
+
   constructor(
     private readonly prisma: PrismaService,
     private readonly buildingAccess: BuildingAccessService,
     private readonly timeline: TimelineService,
+    private readonly leaseStatus: LeaseStatusService,
     private readonly workOrderApartmentStatus: WorkOrderApartmentStatusService,
   ) {}
 
+  /**
+   * F3.2 (decision D2, opt-in/default OFF): when a work order is or becomes
+   * `completed` and is flagged `chargeToTenant` with a `tenantChargeAmount`,
+   * bill the apartment's currently active lease via a new one-line-item
+   * invoice, due in 30 days. Guarded by `tenantChargedAt` so re-completing an
+   * already-charged work order is a no-op. Never throws — a missing active
+   * lease is logged and skipped rather than blocking the status transition.
+   */
+  private async chargeTenantIfDue(
+    orgId: string,
+    actorId: string,
+    apartmentId: string,
+    requestTitle: string,
+    workOrder: ChargeableWorkOrder,
+  ): Promise<void> {
+    if (
+      !workOrder.chargeToTenant ||
+      workOrder.tenantChargeAmount === null ||
+      workOrder.tenantChargedAt !== null
+    ) {
+      return;
+    }
+
+    const now = new Date();
+    const activeLease = await this.prisma.lease.findFirst({
+      where: { orgId, apartmentId, status: 'active' },
+      orderBy: { startDate: 'desc' },
+    });
+
+    if (
+      !activeLease ||
+      !this.leaseStatus.isEffectivelyActive(
+        { status: activeLease.status, endDate: activeLease.endDate },
+        now,
+      )
+    ) {
+      this.logger.warn(
+        `Work order ${workOrder.id} is chargeToTenant but apartment ${apartmentId} has no active lease — skipping tenant charge.`,
+      );
+      return;
+    }
+
+    const dueDate = new Date(
+      now.getTime() + TENANT_CHARGE_DUE_DAYS * MS_PER_DAY,
+    );
+    const numberLabel = formatWorkOrderNumber(workOrder.number);
+
+    const invoice = await this.prisma.$transaction(async (tx) => {
+      const created = await tx.invoice.create({
+        data: {
+          orgId,
+          buildingId: activeLease.buildingId,
+          leaseId: activeLease.id,
+          dueDate,
+          lineItems: {
+            create: [
+              {
+                category: 'other',
+                description: `Work order ${numberLabel}: ${requestTitle}`,
+                amount: workOrder.tenantChargeAmount,
+              },
+            ],
+          },
+        },
+      });
+      await tx.workOrder.update({
+        where: { id: workOrder.id },
+        data: { tenantChargedAt: now },
+      });
+      return created;
+    });
+
+    await this.timeline.emit({
+      orgId,
+      actorId,
+      action: 'work_order.tenant_charged',
+      targetType: 'WorkOrder',
+      targetId: workOrder.id,
+      metadata: {
+        invoiceId: invoice.id,
+        leaseId: activeLease.id,
+        amount: workOrder.tenantChargeAmount.toString(),
+      },
+    });
+  }
+
   async findAllForRequest(
     orgId: string,
     callerId: string,
@@ -154,7 +259,7 @@ export class WorkOrdersService {
 
     const request = await this.prisma.maintenanceRequest.findFirst({
       where: { id: maintenanceRequestId, orgId },
-      select: { apartmentId: true },
+      select: { apartmentId: true, title: true },
     });
     if (!request) {
       throw new NotFoundException('Maintenance request not found.');
@@ -186,6 +291,8 @@ export class WorkOrdersService {
           status: dto.status,
           cost: dto.cost,
           resolutionNotes: dto.resolutionNotes,
+          chargeToTenant: dto.chargeToTenant,
+          tenantChargeAmount: dto.tenantChargeAmount,
         },
       });
     });
@@ -205,6 +312,16 @@ export class WorkOrdersService {
       },
     });
 
+    if (workOrder.status === 'completed') {
+      await this.chargeTenantIfDue(
+        orgId,
+        actorId,
+        request.apartmentId,
+        request.title,
+        workOrder,
+      );
+    }
+
     return { data: formatWorkOrder(workOrder) };
   }
 
@@ -219,7 +336,9 @@ export class WorkOrdersService {
   ): Promise<{ data: WorkOrderResponse }> {
     const existing = await this.prisma.workOrder.findFirst({
       where: { id: workOrderId, orgId, maintenanceRequestId },
-      include: { maintenanceRequest: { select: { apartmentId: true } } },
+      include: {
+        maintenanceRequest: { select: { apartmentId: true, title: true } },
+      },
     });
     if (!existing) {
       throw new NotFoundException('Work order not found.');
@@ -287,6 +406,8 @@ export class WorkOrdersService {
     }
 
     const reassigning = vendorProvided || assigneeProvided;
+    const completingNow =
+      dto.status === 'completed' && existing.status !== 'completed';
 
     const workOrder = await this.prisma.workOrder.update({
       where: { id: workOrderId },
@@ -298,6 +419,12 @@ export class WorkOrdersService {
           resolutionNotes: dto.resolutionNotes,
         }),
         ...(completedAt !== undefined && { completedAt }),
+        ...(dto.chargeToTenant !== undefined && {
+          chargeToTenant: dto.chargeToTenant,
+        }),
+        ...(dto.tenantChargeAmount !== undefined && {
+          tenantChargeAmount: dto.tenantChargeAmount,
+        }),
       },
     });
 
@@ -320,6 +447,16 @@ export class WorkOrdersService {
       metadata: { changes: Object.keys(dto) },
     });
 
+    if (completingNow) {
+      await this.chargeTenantIfDue(
+        orgId,
+        actorId,
+        existing.maintenanceRequest.apartmentId,
+        existing.maintenanceRequest.title,
+        workOrder,
+      );
+    }
+
     return { data: formatWorkOrder(workOrder) };
   }
 
diff --git a/apps/web/src/app/api/recurring-invoices/run/route.ts b/apps/web/src/app/api/recurring-invoices/run/route.ts
new file mode 100644
index 00000000..cacd7df3
--- /dev/null
+++ b/apps/web/src/app/api/recurring-invoices/run/route.ts
@@ -0,0 +1,7 @@
+import { forwardRoute } from '@/lib/api/forward';
+
+export const runtime = 'nodejs';
+
+// F3.1 — org_admin "generate rent invoices now" trigger. Also runs daily via the
+// backend BullMQ scheduler; this is the on-demand path (and the verify hook).
+export const POST = forwardRoute('/recurring-invoices/run');
diff --git a/apps/web/src/components/dashboard/expenses-page.tsx b/apps/web/src/components/dashboard/expenses-page.tsx
index ae4596b9..23bc9663 100644
--- a/apps/web/src/components/dashboard/expenses-page.tsx
+++ b/apps/web/src/components/dashboard/expenses-page.tsx
@@ -168,8 +168,7 @@ function ExpenseFormFields({
   maintenanceRequestId: string;
   onMaintenanceRequestChange: (id: string) => void;
   workOrders:
-    | { id: string; vendorId?: string | null; numberLabel: string }[]
-    | undefined;
+    { id: string; vendorId?: string | null; numberLabel: string }[] | undefined;
   setValue: ReturnType<typeof useForm<ExpenseFormValues>>['setValue'];
   getValues: ReturnType<typeof useForm<ExpenseFormValues>>['getValues'];
   dict: Dictionary;
@@ -598,6 +597,9 @@ export function ExpensesPage({
         <div>
           <h1 className="text-2xl font-semibold tracking-tight">{t.title}</h1>
           <p className="text-sm text-muted-foreground mt-0.5">{t.subtitle}</p>
+          <p className="text-xs text-muted-foreground mt-1 max-w-2xl">
+            {t.notBilledToTenantsNote}
+          </p>
         </div>
         <div className="flex items-center gap-2">
           {!canWrite && (
diff --git a/apps/web/src/components/dashboard/invoices-page.tsx b/apps/web/src/components/dashboard/invoices-page.tsx
index 7cbe932a..de538fa9 100644
--- a/apps/web/src/components/dashboard/invoices-page.tsx
+++ b/apps/web/src/components/dashboard/invoices-page.tsx
@@ -14,6 +14,7 @@ import {
   PencilIcon,
   TrashIcon,
   XIcon,
+  RefreshCwIcon,
 } from 'lucide-react';
 
 import { Badge } from '@/components/ui/badge';
@@ -56,6 +57,7 @@ import {
 import {
   useListInvoicesQuery,
   useCreateInvoiceMutation,
+  useRunRecurringInvoicesMutation,
   useUpdateInvoiceMutation,
   useDeleteInvoiceMutation,
 } from '@/store/api/endpoints/invoices.api';
@@ -481,6 +483,21 @@ export function InvoicesPage({ canWrite, locale, dict }: InvoicesPageProps) {
   const { data: buildings } = useListBuildingsQuery();
 
   const [createInvoice, { isLoading: creating }] = useCreateInvoiceMutation();
+  const [runRecurring, { isLoading: generating }] =
+    useRunRecurringInvoicesMutation();
+
+  async function handleGenerateRecurring() {
+    try {
+      const res = await runRecurring().unwrap();
+      toast.success(
+        t.list.generateRecurring.result
+          .replace('{generated}', String(res.generated))
+          .replace('{skipped}', String(res.skippedExisting)),
+      );
+    } catch {
+      toast.error(t.list.generateRecurring.error);
+    }
+  }
   const [updateInvoice, { isLoading: updating }] = useUpdateInvoiceMutation();
   const [deleteInvoice, { isLoading: deleting }] = useDeleteInvoiceMutation();
 
@@ -638,6 +655,17 @@ export function InvoicesPage({ canWrite, locale, dict }: InvoicesPageProps) {
               {t.list.readOnly}
             </Badge>
           )}
+          {canWrite && (
+            <Button
+              variant="outline"
+              onClick={handleGenerateRecurring}
+              disabled={generating}
+              title={t.list.generateRecurring.hint}
+            >
+              <RefreshCwIcon />
+              {t.list.generateRecurring.button}
+            </Button>
+          )}
           {canWrite && (
             <Button
               onClick={() => {
diff --git a/apps/web/src/components/dashboard/maintenance-request-detail-page.tsx b/apps/web/src/components/dashboard/maintenance-request-detail-page.tsx
index aac2267b..0da98e2d 100644
--- a/apps/web/src/components/dashboard/maintenance-request-detail-page.tsx
+++ b/apps/web/src/components/dashboard/maintenance-request-detail-page.tsx
@@ -21,6 +21,7 @@ import { formatWorkOrderNumber } from '@repo/contracts';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { Checkbox } from '@/components/ui/checkbox';
 import { Badge } from '@/components/ui/badge';
 import { Skeleton } from '@/components/ui/skeleton';
 import { Textarea } from '@/components/ui/textarea';
@@ -158,6 +159,11 @@ const createWorkOrderSchema = z.object({
   status: z.enum(['scheduled', 'in_progress', 'completed', 'canceled']),
   cost: z.string().optional(),
   resolutionNotes: z.string().optional(),
+  // F3.2: opt-in tenant billing. Default false; amount required in
+  // onCreateSubmit below (mirrors the vendor/staff manual checks) rather
+  // than a zod .refine, since this schema has no dictionary-driven messages.
+  chargeToTenant: z.boolean(),
+  tenantChargeAmount: z.string().optional(),
 });
 
 type CreateWorkOrderFormValues = z.infer<typeof createWorkOrderSchema>;
@@ -169,6 +175,8 @@ const CREATE_WORK_ORDER_EMPTY: CreateWorkOrderFormValues = {
   status: 'scheduled',
   cost: '',
   resolutionNotes: '',
+  chargeToTenant: false,
+  tenantChargeAmount: '',
 };
 
 // ── Edit Work Order form (org_admin only, full) ─────────────────────────────
@@ -180,6 +188,8 @@ const editWorkOrderSchema = z.object({
   status: z.enum(['scheduled', 'in_progress', 'completed', 'canceled']),
   cost: z.string().optional(),
   resolutionNotes: z.string().optional(),
+  chargeToTenant: z.boolean(),
+  tenantChargeAmount: z.string().optional(),
 });
 
 type EditWorkOrderFormValues = z.infer<typeof editWorkOrderSchema>;
@@ -268,6 +278,7 @@ export function MaintenanceRequestDetailPage({
     defaultValues: CREATE_WORK_ORDER_EMPTY,
   });
   const createMode = watchCreate('assignmentMode');
+  const createChargeToTenant = watchCreate('chargeToTenant');
 
   const {
     control: editControl,
@@ -279,6 +290,7 @@ export function MaintenanceRequestDetailPage({
     resolver: zodResolver(editWorkOrderSchema),
   });
   const editMode = watchEdit('assignmentMode');
+  const editChargeToTenant = watchEdit('chargeToTenant');
 
   const {
     control: statusControl,
@@ -344,6 +356,10 @@ export function MaintenanceRequestDetailPage({
       toast.error(t.workOrder.create.staffRequired);
       return;
     }
+    if (values.chargeToTenant && !values.tenantChargeAmount) {
+      toast.error(t.workOrder.fields.tenantChargeAmountRequired);
+      return;
+    }
     try {
       await createWorkOrder({
         maintenanceRequestId: id,
@@ -357,6 +373,11 @@ export function MaintenanceRequestDetailPage({
           status: values.status,
           cost: values.cost ? Number(values.cost) : undefined,
           resolutionNotes: values.resolutionNotes || undefined,
+          chargeToTenant: values.chargeToTenant,
+          tenantChargeAmount:
+            values.chargeToTenant && values.tenantChargeAmount
+              ? Number(values.tenantChargeAmount)
+              : undefined,
         },
       }).unwrap();
       toast.success(t.workOrder.create.success);
@@ -376,11 +397,17 @@ export function MaintenanceRequestDetailPage({
       status: workOrder.status,
       cost: workOrder.cost ?? '',
       resolutionNotes: workOrder.resolutionNotes ?? '',
+      chargeToTenant: workOrder.chargeToTenant,
+      tenantChargeAmount: workOrder.tenantChargeAmount ?? '',
     });
   }
 
   async function onEditSubmit(values: EditWorkOrderFormValues) {
     if (!editTarget) return;
+    if (values.chargeToTenant && !values.tenantChargeAmount) {
+      toast.error(t.workOrder.fields.tenantChargeAmountRequired);
+      return;
+    }
     try {
       await updateWorkOrder({
         maintenanceRequestId: id,
@@ -397,6 +424,11 @@ export function MaintenanceRequestDetailPage({
           status: values.status,
           cost: values.cost ? Number(values.cost) : null,
           resolutionNotes: values.resolutionNotes || null,
+          chargeToTenant: values.chargeToTenant,
+          tenantChargeAmount:
+            values.chargeToTenant && values.tenantChargeAmount
+              ? Number(values.tenantChargeAmount)
+              : null,
         },
       }).unwrap();
       toast.success(t.workOrder.edit.success);
@@ -602,7 +634,23 @@ export function MaintenanceRequestDetailPage({
                       </span>
                     </TableCell>
                     <TableCell className="text-sm text-muted-foreground">
-                      {workOrder.cost ?? '—'}
+                      <span className="inline-flex items-center gap-1.5">
+                        {workOrder.cost ?? '—'}
+                        {workOrder.chargeToTenant && (
+                          <Badge
+                            variant="outline"
+                            className={
+                              workOrder.tenantChargedAt
+                                ? 'bg-emerald-50 text-emerald-700 border-emerald-200'
+                                : 'bg-amber-50 text-amber-700 border-amber-200'
+                            }
+                          >
+                            {workOrder.tenantChargedAt
+                              ? t.detail.tenantChargeBilled
+                              : t.detail.tenantChargePending}
+                          </Badge>
+                        )}
+                      </span>
                     </TableCell>
                     <TableCell className="text-sm text-muted-foreground">
                       {workOrder.resolutionNotes ?? '—'}
@@ -824,6 +872,41 @@ export function MaintenanceRequestDetailPage({
                 {...regCreate('cost')}
               />
             </div>
+            <div className="flex flex-col gap-2">
+              <div className="flex items-center gap-2">
+                <Controller
+                  control={createControl}
+                  name="chargeToTenant"
+                  render={({ field }) => (
+                    <Checkbox
+                      id="wo-charge-to-tenant"
+                      checked={field.value}
+                      onCheckedChange={(checked) =>
+                        field.onChange(checked === true)
+                      }
+                    />
+                  )}
+                />
+                <Label htmlFor="wo-charge-to-tenant" className="font-normal">
+                  {t.workOrder.fields.chargeToTenant}
+                </Label>
+              </div>
+              {createChargeToTenant && (
+                <div className="flex flex-col gap-1.5">
+                  <Label htmlFor="wo-tenant-charge-amount">
+                    {t.workOrder.fields.tenantChargeAmount}
+                  </Label>
+                  <Input
+                    id="wo-tenant-charge-amount"
+                    type="number"
+                    step="0.01"
+                    min="0"
+                    placeholder="0.00"
+                    {...regCreate('tenantChargeAmount')}
+                  />
+                </div>
+              )}
+            </div>
             <div className="flex flex-col gap-1.5">
               <Label htmlFor="wo-notes">
                 {t.workOrder.fields.resolutionNotes}{' '}
@@ -1007,6 +1090,41 @@ export function MaintenanceRequestDetailPage({
                 {...regEdit('cost')}
               />
             </div>
+            <div className="flex flex-col gap-2">
+              <div className="flex items-center gap-2">
+                <Controller
+                  control={editControl}
+                  name="chargeToTenant"
+                  render={({ field }) => (
+                    <Checkbox
+                      id="woe-charge-to-tenant"
+                      checked={field.value}
+                      onCheckedChange={(checked) =>
+                        field.onChange(checked === true)
+                      }
+                    />
+                  )}
+                />
+                <Label htmlFor="woe-charge-to-tenant" className="font-normal">
+                  {t.workOrder.fields.chargeToTenant}
+                </Label>
+              </div>
+              {editChargeToTenant && (
+                <div className="flex flex-col gap-1.5">
+                  <Label htmlFor="woe-tenant-charge-amount">
+                    {t.workOrder.fields.tenantChargeAmount}
+                  </Label>
+                  <Input
+                    id="woe-tenant-charge-amount"
+                    type="number"
+                    step="0.01"
+                    min="0"
+                    placeholder="0.00"
+                    {...regEdit('tenantChargeAmount')}
+                  />
+                </div>
+              )}
+            </div>
             <div className="flex flex-col gap-1.5">
               <Label htmlFor="woe-notes">
                 {t.workOrder.fields.resolutionNotes}{' '}
diff --git a/apps/web/src/components/dashboard/reports-page.tsx b/apps/web/src/components/dashboard/reports-page.tsx
index 51767239..ff710d1d 100644
--- a/apps/web/src/components/dashboard/reports-page.tsx
+++ b/apps/web/src/components/dashboard/reports-page.tsx
@@ -245,6 +245,9 @@ export function ReportsPage({ locale, dict }: ReportsPageProps) {
       <div>
         <h1 className="text-2xl font-semibold tracking-tight">{t.title}</h1>
         <p className="mt-0.5 text-sm text-muted-foreground">{t.subtitle}</p>
+        <p className="mt-1 max-w-2xl text-xs text-muted-foreground">
+          {t.methodologyNote}
+        </p>
       </div>
 
       {/* Date-range filter */}
@@ -315,6 +318,7 @@ export function ReportsPage({ locale, dict }: ReportsPageProps) {
                   label={t.kpis.mtdIncome}
                   value={money.format(Number(summary.mtdIncome))}
                   icon={<WalletIcon className="size-4" />}
+                  hint={t.kpis.incomeHint}
                 />
                 <StatTile
                   label={t.kpis.mtdNet}
@@ -327,6 +331,7 @@ export function ReportsPage({ locale, dict }: ReportsPageProps) {
                       <TrendingDownIcon className="size-4" />
                     )
                   }
+                  hint={t.kpis.netHint}
                 />
               </>
             )}
@@ -339,6 +344,7 @@ export function ReportsPage({ locale, dict }: ReportsPageProps) {
                 label={t.kpis.rangeIncome}
                 value={money.format(Number(summary.range.income))}
                 icon={<WalletIcon className="size-4" />}
+                hint={t.kpis.incomeHint}
               />
               <StatTile
                 label={t.kpis.rangeExpenses}
@@ -356,6 +362,7 @@ export function ReportsPage({ locale, dict }: ReportsPageProps) {
                     <TrendingDownIcon className="size-4" />
                   )
                 }
+                hint={t.kpis.netHint}
               />
             </div>
           )}
diff --git a/apps/web/src/components/ui/checkbox.tsx b/apps/web/src/components/ui/checkbox.tsx
new file mode 100644
index 00000000..367908e8
--- /dev/null
+++ b/apps/web/src/components/ui/checkbox.tsx
@@ -0,0 +1,28 @@
+'use client';
+
+import { Checkbox as CheckboxPrimitive } from '@base-ui/react/checkbox';
+
+import { cn } from '@/lib/utils';
+import { CheckIcon } from 'lucide-react';
+
+function Checkbox({ className, ...props }: CheckboxPrimitive.Root.Props) {
+  return (
+    <CheckboxPrimitive.Root
+      data-slot="checkbox"
+      className={cn(
+        'peer relative flex size-4 shrink-0 items-center justify-center rounded-[4px] border border-input transition-colors outline-none group-has-disabled/field:opacity-50 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground dark:data-checked:bg-primary',
+        className,
+      )}
+      {...props}
+    >
+      <CheckboxPrimitive.Indicator
+        data-slot="checkbox-indicator"
+        className="grid place-content-center text-current transition-none [&>svg]:size-3.5"
+      >
+        <CheckIcon />
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  );
+}
+
+export { Checkbox };
diff --git a/apps/web/src/i18n/dictionaries/ar.json b/apps/web/src/i18n/dictionaries/ar.json
index 6f6fb59c..58139c91 100644
--- a/apps/web/src/i18n/dictionaries/ar.json
+++ b/apps/web/src/i18n/dictionaries/ar.json
@@ -287,7 +287,9 @@
       "ytdNet": "الصافي (هذا العام)",
       "rangeIncome": "الدخل (النطاق)",
       "rangeExpenses": "المصاريف (النطاق)",
-      "rangeNet": "الصافي (النطاق)"
+      "rangeNet": "الصافي (النطاق)",
+      "incomeHint": "الإيجار المحصَّل، وليس المفوتر",
+      "netHint": "الدخل ناقص المصاريف"
     },
     "chart": {
       "title": "الدخل مقابل المصاريف",
@@ -319,7 +321,8 @@
       "balance": "الرصيد",
       "daysOverdue": "أيام التأخير",
       "empty": "لا توجد فواتير متأخرة — الجميع مسدِّد."
-    }
+    },
+    "methodologyNote": "يعكس الدخل دفعات الإيجار المسجّلة فعلياً (على أساس نقدي)، وليس المبالغ المفوترة — من الطبيعي وجود فارق بين المفوتر والمحصَّل طالما بقيت الفواتير غير مسددة."
   },
   "leases": {
     "title": "العقود",
@@ -1045,6 +1048,12 @@
           "success": "تم حذف الفاتورة.",
           "error": "تعذّر حذف الفاتورة. يرجى المحاولة مجدداً."
         }
+      },
+      "generateRecurring": {
+        "button": "إنشاء فواتير الإيجار",
+        "hint": "إنشاء فواتير إيجار هذا الشهر لعقود الإيجار النشطة (يعمل تلقائيًا كل يوم أيضًا).",
+        "result": "تم إنشاء {generated} فاتورة إيجار؛ {skipped} موجودة مسبقًا.",
+        "error": "تعذّر إنشاء فواتير الإيجار."
       }
     },
     "detail": {
@@ -1148,7 +1157,9 @@
       },
       "empty": "لا توجد أوامر عمل بعد.",
       "updateStatusAction": "تحديث الحالة",
-      "assignedToYou": "مسندة إليك"
+      "assignedToYou": "مسندة إليك",
+      "tenantChargeBilled": "تم التحصيل من المستأجر",
+      "tenantChargePending": "سيتم التحصيل من المستأجر"
     },
     "workOrder": {
       "fields": {
@@ -1158,7 +1169,10 @@
         "status": "الحالة",
         "cost": "التكلفة",
         "optional": "(اختياري)",
-        "resolutionNotes": "ملاحظات الحل"
+        "resolutionNotes": "ملاحظات الحل",
+        "chargeToTenant": "تحصيل من المستأجر",
+        "tenantChargeAmount": "المبلغ المطلوب تحصيله",
+        "tenantChargeAmountRequired": "أدخل المبلغ المطلوب تحصيله من المستأجر."
       },
       "create": {
         "title": "أمر عمل جديد",
@@ -1368,6 +1382,7 @@
       "deleting": "جارٍ الحذف…",
       "success": "تم حذف المصروف.",
       "error": "تعذّر حذف المصروف. قد يكون مرتبطاً بعناصر أخرى."
-    }
+    },
+    "notBilledToTenantsNote": "المصاريف هي تكاليف منظمتك الخاصة (إصلاحات، دفعات للموردين، مرافق) — وليست فواتير تُرسل إلى المستأجرين. تُحصَّل مبالغ المستأجرين عبر الفواتير."
   }
 }
diff --git a/apps/web/src/i18n/dictionaries/en.json b/apps/web/src/i18n/dictionaries/en.json
index 39927af9..abba9df7 100644
--- a/apps/web/src/i18n/dictionaries/en.json
+++ b/apps/web/src/i18n/dictionaries/en.json
@@ -287,7 +287,9 @@
       "ytdNet": "Net (YTD)",
       "rangeIncome": "Income (range)",
       "rangeExpenses": "Expenses (range)",
-      "rangeNet": "Net (range)"
+      "rangeNet": "Net (range)",
+      "incomeHint": "Rent collected, not invoiced",
+      "netHint": "Income minus expenses"
     },
     "chart": {
       "title": "Income vs expenses",
@@ -319,7 +321,8 @@
       "balance": "Balance",
       "daysOverdue": "Days overdue",
       "empty": "No overdue invoices — everyone's paid up."
-    }
+    },
+    "methodologyNote": "Income reflects rent payments actually recorded (cash basis), not invoiced amounts — a gap between invoiced and collected is expected while invoices remain unpaid."
   },
   "leases": {
     "title": "Leases",
@@ -1045,6 +1048,12 @@
           "success": "Invoice deleted.",
           "error": "Failed to delete invoice. Please try again."
         }
+      },
+      "generateRecurring": {
+        "button": "Generate rent invoices",
+        "hint": "Create this month's rent invoices for active leases (also runs automatically each day).",
+        "result": "Generated {generated} rent invoice(s); {skipped} already existed.",
+        "error": "Couldn't generate rent invoices."
       }
     },
     "detail": {
@@ -1148,7 +1157,9 @@
       },
       "empty": "No work orders yet.",
       "updateStatusAction": "Update status",
-      "assignedToYou": "Assigned to you"
+      "assignedToYou": "Assigned to you",
+      "tenantChargeBilled": "Billed to tenant",
+      "tenantChargePending": "Will bill tenant"
     },
     "workOrder": {
       "fields": {
@@ -1158,7 +1169,10 @@
         "status": "Status",
         "cost": "Cost",
         "optional": "(optional)",
-        "resolutionNotes": "Resolution notes"
+        "resolutionNotes": "Resolution notes",
+        "chargeToTenant": "Charge to tenant",
+        "tenantChargeAmount": "Amount to charge",
+        "tenantChargeAmountRequired": "Enter an amount to charge the tenant."
       },
       "create": {
         "title": "New work order",
@@ -1368,6 +1382,7 @@
       "deleting": "Deleting…",
       "success": "Expense deleted.",
       "error": "Failed to delete expense. It may be referenced elsewhere."
-    }
+    },
+    "notBilledToTenantsNote": "Expenses are your organization's own costs (repairs, vendor payments, utilities) — they are not bills sent to tenants. Tenant charges are billed through invoices."
   }
 }
diff --git a/apps/web/src/store/api/endpoints/invoices.api.ts b/apps/web/src/store/api/endpoints/invoices.api.ts
index 77400cae..4dca85bd 100644
--- a/apps/web/src/store/api/endpoints/invoices.api.ts
+++ b/apps/web/src/store/api/endpoints/invoices.api.ts
@@ -4,6 +4,7 @@ import type {
   CreateInvoiceBody,
   InvoiceResponse,
   PatchInvoiceBody,
+  RecurringInvoiceRunResponse,
 } from '@/types/api';
 
 function unwrap<TData>(response: TData | ApiEnvelope<TData>): TData {
@@ -80,6 +81,18 @@ export const invoicesApi = baseApi.injectEndpoints({
         'Timeline',
       ],
     }),
+
+    // F3.1 — org_admin on-demand "generate rent invoices now". The same
+    // generation also runs daily via the backend scheduler.
+    runRecurringInvoices: build.mutation<RecurringInvoiceRunResponse, void>({
+      query: () => ({ url: '/recurring-invoices/run', method: 'POST' }),
+      transformResponse: (
+        response:
+          | RecurringInvoiceRunResponse
+          | ApiEnvelope<RecurringInvoiceRunResponse>,
+      ) => unwrap(response),
+      invalidatesTags: [{ type: 'Invoice', id: 'LIST' }, 'Timeline'],
+    }),
   }),
 });
 
@@ -89,4 +102,5 @@ export const {
   useCreateInvoiceMutation,
   useUpdateInvoiceMutation,
   useDeleteInvoiceMutation,
+  useRunRecurringInvoicesMutation,
 } = invoicesApi;
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index dc1b057c..26451ea9 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -594,6 +594,12 @@ export type WorkOrderResponse = {
   cost?: string | null; // Decimal(12,2) serialized as string
   resolutionNotes?: string | null;
   completedAt?: string | null;
+  /** Opt-in: bill this work order to the tenant on completion (F3.2, default false). */
+  chargeToTenant: boolean;
+  /** Amount to charge the tenant (Decimal(12,2) as string), when chargeToTenant. */
+  tenantChargeAmount?: string | null;
+  /** When the tenant charge was applied to an invoice (idempotency guard); null = not yet. */
+  tenantChargedAt?: string | null;
   createdAt: string;
   updatedAt: string;
 };
@@ -641,6 +647,8 @@ export type CreateWorkOrderBody = {
   status?: WorkOrderStatus;
   cost?: number;
   resolutionNotes?: string;
+  chargeToTenant?: boolean;
+  tenantChargeAmount?: number | null;
 };
 
 export type PatchWorkOrderBody = {
@@ -650,6 +658,18 @@ export type PatchWorkOrderBody = {
   cost?: number | null;
   resolutionNotes?: string | null;
   completedAt?: string | null;
+  chargeToTenant?: boolean;
+  tenantChargeAmount?: number | null;
+};
+
+/**
+ * Result of a recurring-invoice generation run (F3.1). The scheduled daily job
+ * and the manual "generate now" trigger both return this shape.
+ */
+export type RecurringInvoiceRunResponse = {
+  generated: number; // invoices created this run
+  leasesConsidered: number; // active leases inspected
+  skippedExisting: number; // periods that already had an invoice (idempotent no-op)
 };
 
 // ── Expenses ─────────────────────────────────────────────────────────────────
diff --git a/packages/database/prisma/migrations/20260721020000_add_invoice_billing_period/migration.sql b/packages/database/prisma/migrations/20260721020000_add_invoice_billing_period/migration.sql
new file mode 100644
index 00000000..bdfbc081
--- /dev/null
+++ b/packages/database/prisma/migrations/20260721020000_add_invoice_billing_period/migration.sql
@@ -0,0 +1,8 @@
+-- Recurring rent invoices (Sprint F3.1). Adds a nullable billing-period key
+-- (`YYYY-MM`) plus a unique index on (leaseId, billingPeriod) so the scheduled
+-- generator is idempotent per (lease, month). Postgres treats NULLs as distinct,
+-- so existing/manual invoices (billingPeriod IS NULL) never collide.
+
+ALTER TABLE "Invoice" ADD COLUMN "billingPeriod" TEXT;
+
+CREATE UNIQUE INDEX "Invoice_leaseId_billingPeriod_key" ON "Invoice"("leaseId", "billingPeriod");
diff --git a/packages/database/prisma/migrations/20260721030000_add_work_order_tenant_charge/migration.sql b/packages/database/prisma/migrations/20260721030000_add_work_order_tenant_charge/migration.sql
new file mode 100644
index 00000000..3ba91667
--- /dev/null
+++ b/packages/database/prisma/migrations/20260721030000_add_work_order_tenant_charge/migration.sql
@@ -0,0 +1,9 @@
+-- Opt-in "charge the tenant" for a work order (Sprint F3.2, decision D2 —
+-- default OFF). When chargeToTenant is set with a tenantChargeAmount, completing
+-- the work order adds one invoice line item on the apartment's active lease.
+-- tenantChargedAt records when the charge was applied so re-completing a work
+-- order can never double-bill the tenant.
+
+ALTER TABLE "WorkOrder" ADD COLUMN "chargeToTenant" BOOLEAN NOT NULL DEFAULT false;
+ALTER TABLE "WorkOrder" ADD COLUMN "tenantChargeAmount" DECIMAL(12,2);
+ALTER TABLE "WorkOrder" ADD COLUMN "tenantChargedAt" TIMESTAMP(3);
diff --git a/packages/database/prisma/schema.prisma b/packages/database/prisma/schema.prisma
index 29d0c600..86030f95 100644
--- a/packages/database/prisma/schema.prisma
+++ b/packages/database/prisma/schema.prisma
@@ -333,6 +333,13 @@ model WorkOrder {
   cost                 Decimal?           @db.Decimal(12, 2)
   resolutionNotes      String?
   completedAt          DateTime?
+  /// Opt-in tenant charge (Sprint F2.2/F3.2, decision D2 — default OFF). When
+  /// chargeToTenant is set with a tenantChargeAmount, completing the work order
+  /// adds one line item to a new invoice on the apartment's active lease.
+  /// tenantChargedAt stamps when that happened so re-completion can't double-bill.
+  chargeToTenant       Boolean            @default(false)
+  tenantChargeAmount   Decimal?           @db.Decimal(12, 2)
+  tenantChargedAt      DateTime?
   createdAt            DateTime           @default(now())
   updatedAt            DateTime           @updatedAt
   maintenanceRequest   MaintenanceRequest @relation(fields: [maintenanceRequestId], references: [id], onDelete: Cascade)
@@ -372,6 +379,11 @@ model Invoice {
   buildingId String
   leaseId    String
   dueDate    DateTime
+  /// Billing period key (`YYYY-MM`) for auto-generated recurring rent invoices.
+  /// NULL for manually-created invoices. The @@unique([leaseId, billingPeriod])
+  /// makes recurring generation idempotent per (lease, month) — NULLs are
+  /// distinct in Postgres, so manual invoices never collide.
+  billingPeriod String?
   notes      String?
   createdAt  DateTime          @default(now())
   updatedAt  DateTime          @updatedAt
@@ -379,6 +391,7 @@ model Invoice {
   lineItems  InvoiceLineItem[]
   payments   InvoicePayment[]
 
+  @@unique([leaseId, billingPeriod])
   @@index([orgId])
   @@index([buildingId])
   @@index([leaseId])

From 3948d15cd37e644f466667e166708ab135b79e7e Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 03:31:54 +0300
Subject: [PATCH 06/11] =?UTF-8?q?feat(F4):=20leasing=20correctness=20?=
 =?UTF-8?q?=E2=80=94=20true=20date-overlap,=20apartment=20expiry=20sweep,?=
 =?UTF-8?q?=20start-date=20policy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sprint F4 of the Property Manager behavior roadmap (workflow W3). No migration.

F4.1 [Q9] True date-overlap lease check. Replaced the old "block if ANY lease is
  effectively-active now" invariant (which made future/back-to-back leases
  impossible) with a real end-exclusive range-overlap check
  (newStart < existingEnd && existingStart < newEnd) against non-terminated
  leases on the apartment — in create() (active/draft) and update() (when dates/
  status change; self-excluded). Allows disjoint future/past + back-to-back;
  rejects real overlaps.

F4.2 [Q9] Apartment status auto-expiry. New apartment-status-sweep module: reverts
  `occupied` apartments with no effectively-active lease back to `vacant`
  (occupied-only filter leaves maintenance/unavailable alone). Daily BullMQ
  repeatable job (07:00) + POST /apartments/status-sweep (org_admin) on-demand
  trigger (BFF proxy added).

F4.3 [Q8, decision D3] Start-date policy. create() rejects a NEW active lease with
  a past start (400) unless CreateLeaseBody.recordExisting is set; FE adds a
  "Record an existing lease" checkbox that unlocks back-dating (and sets the flag)
  + a start-date `min=today` on both lease-create forms.

i18n parity en==ar 1052. Verified: api build EXIT 0 + jest 312 pass/4 skip (incl.
overlap/policy/sweep specs); web check-types clean, vitest 30/30, next build EXIT 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/api/src/app.module.ts                    |   2 +
 ...partment-status-sweep-scheduler.service.ts |  44 +++
 .../apartment-status-sweep.constants.ts       |  16 +
 .../apartment-status-sweep.controller.ts      |  33 ++
 .../apartment-status-sweep.module.ts          |  19 ++
 .../apartment-status-sweep.processor.ts       |  27 ++
 .../apartment-status-sweep.service.spec.ts    | 145 +++++++++
 .../apartment-status-sweep.service.ts         |  80 +++++
 .../modules/leases/dto/create-lease.dto.ts    |  11 +
 .../src/modules/leases/leases.service.spec.ts | 301 ++++++++++++++++--
 apps/api/src/modules/leases/leases.service.ts | 112 +++++--
 .../app/api/apartments/status-sweep/route.ts  |   7 +
 .../dashboard/apartment-detail-page.tsx       |  50 +++
 .../src/components/dashboard/leases-page.tsx  |  49 +++
 apps/web/src/i18n/dictionaries/ar.json        |  14 +-
 apps/web/src/i18n/dictionaries/en.json        |  14 +-
 packages/contracts/src/index.ts               |  16 +
 17 files changed, 893 insertions(+), 47 deletions(-)
 create mode 100644 apps/api/src/modules/apartment-status-sweep/apartment-status-sweep-scheduler.service.ts
 create mode 100644 apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.constants.ts
 create mode 100644 apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.controller.ts
 create mode 100644 apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.module.ts
 create mode 100644 apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.processor.ts
 create mode 100644 apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.service.spec.ts
 create mode 100644 apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.service.ts
 create mode 100644 apps/web/src/app/api/apartments/status-sweep/route.ts

diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts
index a90d2181..4b796bbb 100644
--- a/apps/api/src/app.module.ts
+++ b/apps/api/src/app.module.ts
@@ -45,6 +45,7 @@ import { SupportTicketsModule } from '@/modules/support-tickets/support-tickets.
 import { ReportsModule } from '@/modules/reports/reports.module';
 import { TenantModule } from '@/modules/tenant/tenant.module';
 import { RecurringInvoicesModule } from '@/modules/recurring-invoices/recurring-invoices.module';
+import { ApartmentStatusSweepModule } from '@/modules/apartment-status-sweep/apartment-status-sweep.module';
 
 @Module({
   imports: [
@@ -112,6 +113,7 @@ import { RecurringInvoicesModule } from '@/modules/recurring-invoices/recurring-
     ReportsModule,
     TenantModule,
     RecurringInvoicesModule,
+    ApartmentStatusSweepModule,
   ],
   providers: [
     { provide: APP_GUARD, useClass: ThrottlerGuard },
diff --git a/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep-scheduler.service.ts b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep-scheduler.service.ts
new file mode 100644
index 00000000..03488e71
--- /dev/null
+++ b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep-scheduler.service.ts
@@ -0,0 +1,44 @@
+import { InjectQueue } from '@nestjs/bullmq';
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { Queue } from 'bullmq';
+import {
+  APARTMENT_STATUS_SWEEP_CRON,
+  APARTMENT_STATUS_SWEEP_DAILY_JOB_ID,
+  APARTMENT_STATUS_SWEEP_QUEUE,
+  APARTMENT_STATUS_SWEEP_RUN_JOB,
+} from './apartment-status-sweep.constants';
+
+/**
+ * Registers the daily repeatable job on module init (there is no
+ * `@nestjs/schedule` in this app — BullMQ's repeatable jobs are the
+ * scheduling primitive here, same as the rest of the queue infra). A fixed
+ * jobId means BullMQ upserts the same repeatable job definition on every app
+ * restart instead of accumulating duplicate schedules.
+ */
+@Injectable()
+export class ApartmentStatusSweepSchedulerService implements OnModuleInit {
+  private readonly logger = new Logger(
+    ApartmentStatusSweepSchedulerService.name,
+  );
+
+  constructor(
+    @InjectQueue(APARTMENT_STATUS_SWEEP_QUEUE) private readonly queue: Queue,
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    try {
+      await this.queue.add(
+        APARTMENT_STATUS_SWEEP_RUN_JOB,
+        {},
+        {
+          repeat: { pattern: APARTMENT_STATUS_SWEEP_CRON },
+          jobId: APARTMENT_STATUS_SWEEP_DAILY_JOB_ID,
+        },
+      );
+    } catch (error) {
+      this.logger.error(
+        `Failed to schedule the daily apartment-status sweep job: ${String(error)}`,
+      );
+    }
+  }
+}
diff --git a/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.constants.ts b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.constants.ts
new file mode 100644
index 00000000..c75e3b0f
--- /dev/null
+++ b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.constants.ts
@@ -0,0 +1,16 @@
+/** Name of the BullMQ queue that drives the daily apartment-status sweep. */
+export const APARTMENT_STATUS_SWEEP_QUEUE = 'apartment-status-sweep';
+
+/** Job name used for the daily sweep run. */
+export const APARTMENT_STATUS_SWEEP_RUN_JOB = 'run-daily';
+
+/**
+ * Fixed jobId for the repeatable job. BullMQ upserts a repeatable job by its
+ * (name, jobId, repeat options) — reusing this id on every app restart avoids
+ * accumulating duplicate schedules.
+ */
+export const APARTMENT_STATUS_SWEEP_DAILY_JOB_ID =
+  'apartment-status-sweep-daily';
+
+/** Daily at 07:00 UTC — an hour after the recurring-invoices run. */
+export const APARTMENT_STATUS_SWEEP_CRON = '0 7 * * *';
diff --git a/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.controller.ts b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.controller.ts
new file mode 100644
index 00000000..b1792843
--- /dev/null
+++ b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.controller.ts
@@ -0,0 +1,33 @@
+import { Controller, Post } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { ApartmentStatusSweepService } from './apartment-status-sweep.service';
+import { OrgScopeService } from '@/common/org-scope/org-scope.service';
+import { CurrentUser, Roles } from '@/common/decorators';
+import { AuthenticatedUser } from '@/common/types/authenticated-user.type';
+import { Role } from '@/common/enums';
+
+/**
+ * Manual "sweep now" trigger for the apartment-status expiry sweep (F4.2).
+ * Runs the same idempotent core the daily scheduler runs, scoped to the
+ * caller's org. Mounted at `/apartments` (not a dedicated top-level path)
+ * since a status sweep reads most naturally as an apartments action; it
+ * does not collide with the nested
+ * buildings/:buildingId/floors/:floorId/apartments controller since Nest
+ * matches on the full path.
+ */
+@ApiTags('apartments')
+@ApiBearerAuth()
+@Controller('apartments')
+@Roles(Role.ORG_ADMIN)
+export class ApartmentStatusSweepController {
+  constructor(
+    private readonly apartmentStatusSweep: ApartmentStatusSweepService,
+    private readonly orgScope: OrgScopeService,
+  ) {}
+
+  @Post('status-sweep')
+  async runSweep(@CurrentUser() user: AuthenticatedUser) {
+    const { orgId } = await this.orgScope.resolveForCaller(user);
+    return this.apartmentStatusSweep.sweepForOrg(orgId);
+  }
+}
diff --git a/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.module.ts b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.module.ts
new file mode 100644
index 00000000..c2ae9c3d
--- /dev/null
+++ b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.module.ts
@@ -0,0 +1,19 @@
+import { Module } from '@nestjs/common';
+import { BullModule } from '@nestjs/bullmq';
+import { ApartmentStatusSweepController } from './apartment-status-sweep.controller';
+import { ApartmentStatusSweepService } from './apartment-status-sweep.service';
+import { ApartmentStatusSweepProcessor } from './apartment-status-sweep.processor';
+import { ApartmentStatusSweepSchedulerService } from './apartment-status-sweep-scheduler.service';
+import { APARTMENT_STATUS_SWEEP_QUEUE } from './apartment-status-sweep.constants';
+
+@Module({
+  imports: [BullModule.registerQueue({ name: APARTMENT_STATUS_SWEEP_QUEUE })],
+  controllers: [ApartmentStatusSweepController],
+  providers: [
+    ApartmentStatusSweepService,
+    ApartmentStatusSweepProcessor,
+    ApartmentStatusSweepSchedulerService,
+  ],
+  exports: [ApartmentStatusSweepService],
+})
+export class ApartmentStatusSweepModule {}
diff --git a/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.processor.ts b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.processor.ts
new file mode 100644
index 00000000..27bcdb4f
--- /dev/null
+++ b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.processor.ts
@@ -0,0 +1,27 @@
+import { Processor, WorkerHost } from '@nestjs/bullmq';
+import { Logger } from '@nestjs/common';
+import { Job } from 'bullmq';
+import { APARTMENT_STATUS_SWEEP_QUEUE } from './apartment-status-sweep.constants';
+import { ApartmentStatusSweepService } from './apartment-status-sweep.service';
+
+/**
+ * Consumes the daily repeatable job and sweeps every org. The manual
+ * `POST /apartments/status-sweep` endpoint calls
+ * {@link ApartmentStatusSweepService.sweepForOrg} directly (single-org,
+ * synchronous response) — this processor is only reached by the scheduled job.
+ */
+@Processor(APARTMENT_STATUS_SWEEP_QUEUE)
+export class ApartmentStatusSweepProcessor extends WorkerHost {
+  private readonly logger = new Logger(ApartmentStatusSweepProcessor.name);
+
+  constructor(
+    private readonly apartmentStatusSweep: ApartmentStatusSweepService,
+  ) {
+    super();
+  }
+
+  async process(job: Job): Promise<void> {
+    this.logger.debug(`Starting apartment-status sweep (job ${job.id})`);
+    await this.apartmentStatusSweep.sweepAll();
+  }
+}
diff --git a/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.service.spec.ts b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.service.spec.ts
new file mode 100644
index 00000000..c771101f
--- /dev/null
+++ b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.service.spec.ts
@@ -0,0 +1,145 @@
+import { ApartmentStatusSweepService } from './apartment-status-sweep.service';
+import { LeaseStatusService } from '@/common/lease-status/lease-status.service';
+
+describe('ApartmentStatusSweepService', () => {
+  const orgId = 'org-1';
+  const FAR_FUTURE = new Date('2099-01-01T00:00:00.000Z');
+  const FAR_PAST = new Date('2000-01-01T00:00:00.000Z');
+
+  function makeService(
+    overrides: {
+      apartment?: Partial<Record<string, jest.Mock>>;
+    } = {},
+  ) {
+    const prisma: any = {
+      apartment: {
+        findMany: jest.fn().mockResolvedValue([]),
+        update: jest.fn().mockResolvedValue({}),
+        ...overrides.apartment,
+      },
+    };
+    const leaseStatus = new LeaseStatusService();
+    const service = new ApartmentStatusSweepService(prisma, leaseStatus);
+    return { service, prisma };
+  }
+
+  describe('sweepForOrg', () => {
+    it('queries only occupied apartments, scoped to the org', async () => {
+      const { service, prisma } = makeService();
+
+      await service.sweepForOrg(orgId);
+
+      expect(prisma.apartment.findMany).toHaveBeenCalledWith({
+        where: { orgId, status: 'occupied' },
+        select: {
+          id: true,
+          leases: { select: { status: true, endDate: true } },
+        },
+      });
+    });
+
+    it('reverts an occupied apartment with no effectively-active lease to vacant', async () => {
+      const { service, prisma } = makeService({
+        apartment: {
+          findMany: jest.fn().mockResolvedValue([
+            {
+              id: 'apt-1',
+              leases: [{ status: 'terminated', endDate: FAR_PAST }],
+            },
+          ]),
+        },
+      });
+
+      const result = await service.sweepForOrg(orgId);
+
+      expect(prisma.apartment.update).toHaveBeenCalledWith({
+        where: { id: 'apt-1' },
+        data: { status: 'vacant' },
+      });
+      expect(result).toEqual({ reverted: 1, considered: 1 });
+    });
+
+    it('reverts an occupied apartment with no leases at all', async () => {
+      const { service, prisma } = makeService({
+        apartment: {
+          findMany: jest
+            .fn()
+            .mockResolvedValue([{ id: 'apt-1', leases: [] }]),
+        },
+      });
+
+      const result = await service.sweepForOrg(orgId);
+
+      expect(prisma.apartment.update).toHaveBeenCalledWith({
+        where: { id: 'apt-1' },
+        data: { status: 'vacant' },
+      });
+      expect(result).toEqual({ reverted: 1, considered: 1 });
+    });
+
+    it('leaves an occupied apartment alone when it still has an effectively-active lease', async () => {
+      const { service, prisma } = makeService({
+        apartment: {
+          findMany: jest.fn().mockResolvedValue([
+            {
+              id: 'apt-1',
+              leases: [{ status: 'active', endDate: FAR_FUTURE }],
+            },
+          ]),
+        },
+      });
+
+      const result = await service.sweepForOrg(orgId);
+
+      expect(prisma.apartment.update).not.toHaveBeenCalled();
+      expect(result).toEqual({ reverted: 0, considered: 1 });
+    });
+
+    it('reports considered/reverted counts across a mix of apartments', async () => {
+      const { service, prisma } = makeService({
+        apartment: {
+          findMany: jest.fn().mockResolvedValue([
+            { id: 'apt-1', leases: [] },
+            {
+              id: 'apt-2',
+              leases: [{ status: 'active', endDate: FAR_FUTURE }],
+            },
+            {
+              id: 'apt-3',
+              leases: [{ status: 'active', endDate: FAR_PAST }], // expired
+            },
+          ]),
+        },
+      });
+
+      const result = await service.sweepForOrg(orgId);
+
+      expect(prisma.apartment.update).toHaveBeenCalledTimes(2);
+      expect(prisma.apartment.update).toHaveBeenCalledWith({
+        where: { id: 'apt-1' },
+        data: { status: 'vacant' },
+      });
+      expect(prisma.apartment.update).toHaveBeenCalledWith({
+        where: { id: 'apt-3' },
+        data: { status: 'vacant' },
+      });
+      expect(result).toEqual({ reverted: 2, considered: 3 });
+    });
+  });
+
+  describe('sweepAll', () => {
+    it('sweeps across every org (no orgId filter)', async () => {
+      const { service, prisma } = makeService();
+
+      await service.sweepAll();
+
+      expect(prisma.apartment.findMany).toHaveBeenCalledWith({
+        where: { status: 'occupied' },
+        select: {
+          id: true,
+          leases: { select: { status: true, endDate: true } },
+        },
+      });
+    });
+  });
+});
diff --git a/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.service.ts b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.service.ts
new file mode 100644
index 00000000..f583a18c
--- /dev/null
+++ b/apps/api/src/modules/apartment-status-sweep/apartment-status-sweep.service.ts
@@ -0,0 +1,80 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { PrismaService } from '@/infrastructure/prisma/prisma.service';
+import { LeaseStatusService } from '@/common/lease-status/lease-status.service';
+import { ApartmentStatusSweepResponse } from '@repo/contracts';
+
+/**
+ * F4.2: leases only sync the apartment status at create/update/renew time —
+ * nothing continuously re-checks it, so an apartment left `occupied` by a
+ * lease that has since expired (or was terminated without a replacement)
+ * stays stuck `occupied` forever. This sweep finds `occupied` apartments with
+ * no effectively-active lease and reverts them to `vacant`.
+ *
+ * Only `occupied` apartments are ever touched: `maintenance` and
+ * `unavailable` apartments are excluded by the query itself (status ===
+ * 'occupied'), so an apartment with an open work order — which
+ * WorkOrderApartmentStatusService keeps at `maintenance` — is never
+ * considered here, let alone reverted.
+ */
+@Injectable()
+export class ApartmentStatusSweepService {
+  private readonly logger = new Logger(ApartmentStatusSweepService.name);
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly leaseStatus: LeaseStatusService,
+  ) {}
+
+  /**
+   * Pure, idempotent core: revert every `occupied` apartment (optionally
+   * scoped to `orgId`) that has no effectively-active lease as of `asOf`.
+   */
+  private async sweep(
+    orgId: string | undefined,
+    asOf: Date,
+  ): Promise<ApartmentStatusSweepResponse> {
+    const apartments = await this.prisma.apartment.findMany({
+      where: { ...(orgId && { orgId }), status: 'occupied' },
+      select: {
+        id: true,
+        leases: { select: { status: true, endDate: true } },
+      },
+    });
+
+    let reverted = 0;
+    for (const apartment of apartments) {
+      const hasActiveLease = apartment.leases.some((lease) =>
+        this.leaseStatus.isEffectivelyActive(
+          { status: lease.status, endDate: lease.endDate },
+          asOf,
+        ),
+      );
+      if (!hasActiveLease) {
+        await this.prisma.apartment.update({
+          where: { id: apartment.id },
+          data: { status: 'vacant' },
+        });
+        reverted++;
+      }
+    }
+
+    return { reverted, considered: apartments.length };
+  }
+
+  /** Sweep a single org — the manual `POST /apartments/status-sweep` trigger. */
+  async sweepForOrg(
+    orgId: string,
+    asOf: Date = new Date(),
+  ): Promise<ApartmentStatusSweepResponse> {
+    return this.sweep(orgId, asOf);
+  }
+
+  /** Sweep every org — the daily scheduler's entry point. */
+  async sweepAll(asOf: Date = new Date()): Promise<ApartmentStatusSweepResponse> {
+    const result = await this.sweep(undefined, asOf);
+    this.logger.log(
+      `Apartment status sweep: reverted=${result.reverted} considered=${result.considered}`,
+    );
+    return result;
+  }
+}
diff --git a/apps/api/src/modules/leases/dto/create-lease.dto.ts b/apps/api/src/modules/leases/dto/create-lease.dto.ts
index cfe9ee24..e3775f2b 100644
--- a/apps/api/src/modules/leases/dto/create-lease.dto.ts
+++ b/apps/api/src/modules/leases/dto/create-lease.dto.ts
@@ -1,4 +1,5 @@
 import {
+  IsBoolean,
   IsDateString,
   IsEnum,
   IsNotEmpty,
@@ -51,4 +52,14 @@ export class CreateLeaseDto {
   @IsOptional()
   @IsString()
   notes?: string;
+
+  @ApiPropertyOptional({
+    description:
+      "F4.3 (decision D3): a NEW active lease may not silently start in the past. " +
+      'Set this to explicitly record an already-existing lease with a back-dated ' +
+      'start; without it, a past start on an active lease is rejected (400).',
+  })
+  @IsOptional()
+  @IsBoolean()
+  recordExisting?: boolean;
 }
diff --git a/apps/api/src/modules/leases/leases.service.spec.ts b/apps/api/src/modules/leases/leases.service.spec.ts
index a1667e7d..6152086a 100644
--- a/apps/api/src/modules/leases/leases.service.spec.ts
+++ b/apps/api/src/modules/leases/leases.service.spec.ts
@@ -109,9 +109,13 @@ describe('LeasesService', () => {
     ...overrides,
   });
 
+  // Comfortably in the future (well past "today" for the foreseeable life of
+  // this suite) so the F4.3 past-start guard never trips on the happy path.
+  const FAR_ENOUGH_FUTURE_START = '2050-01-01T00:00:00.000Z';
+
   const dto = {
     renterId,
-    startDate: '2026-01-01T00:00:00.000Z',
+    startDate: FAR_ENOUGH_FUTURE_START,
     endDate: FAR_FUTURE,
     rentAmount: 1500,
     depositAmount: 1500,
@@ -173,7 +177,7 @@ describe('LeasesService', () => {
       expect(prisma.apartment.update).not.toHaveBeenCalled();
     });
 
-    it('rejects creating a second active lease on an apartment that already has one', async () => {
+    it('rejects creating a second active lease whose dates fully overlap an existing one', async () => {
       const { service, prisma } = makeService({
         lease: {
           findMany: jest.fn().mockResolvedValue([leaseRow()]),
@@ -186,22 +190,6 @@ describe('LeasesService', () => {
       expect(prisma.lease.create).not.toHaveBeenCalled();
     });
 
-    it('allows creating a draft lease alongside an existing active lease', async () => {
-      const { service, prisma } = makeService({
-        lease: {
-          findMany: jest.fn().mockResolvedValue([leaseRow()]),
-        },
-      });
-      prisma.lease.create.mockResolvedValue(leaseRow({ status: 'draft' }));
-
-      await service.create(orgId, actorId, buildingId, floorId, apartmentId, {
-        ...dto,
-        status: 'draft',
-      });
-
-      expect(prisma.lease.create).toHaveBeenCalled();
-    });
-
     it('allows a new active lease when the existing one has already expired', async () => {
       const { service, prisma } = makeService({
         lease: {
@@ -224,6 +212,198 @@ describe('LeasesService', () => {
       expect(prisma.lease.create).toHaveBeenCalled();
     });
 
+    describe('date-overlap check (F4.1)', () => {
+      // A bounded existing lease (not FAR_FUTURE-ended) so there's real room
+      // to construct disjoint/adjacent/partial ranges around it.
+      const boundedExisting = () =>
+        leaseRow({
+          id: 'lease-existing',
+          startDate: new Date('2030-01-01T00:00:00.000Z'),
+          endDate: new Date('2031-01-01T00:00:00.000Z'),
+        });
+
+      it('rejects a partial overlap at the head (new lease starts before, ends inside)', async () => {
+        const { service, prisma } = makeService({
+          lease: { findMany: jest.fn().mockResolvedValue([boundedExisting()]) },
+        });
+
+        await expect(
+          service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+            ...dto,
+            startDate: '2029-06-01T00:00:00.000Z',
+            endDate: '2030-06-01T00:00:00.000Z',
+          }),
+        ).rejects.toBeInstanceOf(ConflictException);
+        expect(prisma.lease.create).not.toHaveBeenCalled();
+      });
+
+      it('rejects a partial overlap at the tail (new lease starts inside, ends after)', async () => {
+        const { service, prisma } = makeService({
+          lease: { findMany: jest.fn().mockResolvedValue([boundedExisting()]) },
+        });
+
+        await expect(
+          service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+            ...dto,
+            startDate: '2030-06-01T00:00:00.000Z',
+            endDate: '2031-06-01T00:00:00.000Z',
+          }),
+        ).rejects.toBeInstanceOf(ConflictException);
+        expect(prisma.lease.create).not.toHaveBeenCalled();
+      });
+
+      it('allows a back-to-back lease starting exactly when the existing one ends', async () => {
+        const { service, prisma } = makeService({
+          lease: { findMany: jest.fn().mockResolvedValue([boundedExisting()]) },
+        });
+        prisma.lease.create.mockResolvedValue(leaseRow());
+
+        await service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+          ...dto,
+          startDate: '2031-01-01T00:00:00.000Z', // === existing.endDate
+          endDate: '2032-01-01T00:00:00.000Z',
+        });
+
+        expect(prisma.lease.create).toHaveBeenCalled();
+      });
+
+      it('allows a disjoint future lease (starts well after the existing one ends)', async () => {
+        const { service, prisma } = makeService({
+          lease: { findMany: jest.fn().mockResolvedValue([boundedExisting()]) },
+        });
+        prisma.lease.create.mockResolvedValue(leaseRow());
+
+        await service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+          ...dto,
+          startDate: '2035-01-01T00:00:00.000Z',
+          endDate: '2036-01-01T00:00:00.000Z',
+        });
+
+        expect(prisma.lease.create).toHaveBeenCalled();
+      });
+
+      it('allows a disjoint past lease (ends before the existing one starts)', async () => {
+        const { service, prisma } = makeService({
+          lease: { findMany: jest.fn().mockResolvedValue([boundedExisting()]) },
+        });
+        prisma.lease.create.mockResolvedValue(leaseRow({ status: 'draft' }));
+
+        // Use a draft here (start-date policy F4.3 only guards 'active').
+        await service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+          ...dto,
+          status: 'draft',
+          startDate: '2020-01-01T00:00:00.000Z',
+          endDate: '2021-01-01T00:00:00.000Z',
+        });
+
+        expect(prisma.lease.create).toHaveBeenCalled();
+      });
+
+      it('ignores a terminated existing lease even if its dates fully overlap', async () => {
+        const { service, prisma } = makeService({
+          lease: {
+            findMany: jest
+              .fn()
+              .mockResolvedValue([
+                { ...boundedExisting(), status: 'terminated' },
+              ]),
+          },
+        });
+        prisma.lease.create.mockResolvedValue(leaseRow());
+
+        await service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+          ...dto,
+          startDate: '2030-01-01T00:00:00.000Z',
+          endDate: '2031-01-01T00:00:00.000Z',
+        });
+
+        expect(prisma.lease.create).toHaveBeenCalled();
+      });
+
+      it('applies the overlap check to draft leases too (not exempt)', async () => {
+        const { service, prisma } = makeService({
+          lease: { findMany: jest.fn().mockResolvedValue([boundedExisting()]) },
+        });
+
+        await expect(
+          service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+            ...dto,
+            status: 'draft',
+            startDate: '2030-06-01T00:00:00.000Z',
+            endDate: '2030-09-01T00:00:00.000Z',
+          }),
+        ).rejects.toBeInstanceOf(ConflictException);
+        expect(prisma.lease.create).not.toHaveBeenCalled();
+      });
+    });
+
+    describe('start-date policy (F4.3)', () => {
+      it('rejects a new active lease starting in the past without recordExisting', async () => {
+        const { service, prisma } = makeService();
+
+        await expect(
+          service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+            ...dto,
+            startDate: '2020-01-01T00:00:00.000Z',
+          }),
+        ).rejects.toBeInstanceOf(BadRequestException);
+        expect(prisma.lease.create).not.toHaveBeenCalled();
+      });
+
+      it('allows a past-start active lease when recordExisting is true', async () => {
+        const { service, prisma } = makeService();
+        prisma.lease.create.mockResolvedValue(
+          leaseRow({ startDate: new Date('2020-01-01T00:00:00.000Z') }),
+        );
+
+        await service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+          ...dto,
+          startDate: '2020-01-01T00:00:00.000Z',
+          recordExisting: true,
+        });
+
+        expect(prisma.lease.create).toHaveBeenCalled();
+      });
+
+      it('allows an active lease starting today', async () => {
+        const { service, prisma } = makeService();
+        const today = new Date();
+        const todayUtcMidnight = new Date(
+          Date.UTC(
+            today.getUTCFullYear(),
+            today.getUTCMonth(),
+            today.getUTCDate(),
+          ),
+        ).toISOString();
+        prisma.lease.create.mockResolvedValue(leaseRow());
+
+        await service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+          ...dto,
+          startDate: todayUtcMidnight,
+        });
+
+        expect(prisma.lease.create).toHaveBeenCalled();
+      });
+
+      it('allows a past-start draft lease without recordExisting (guard only applies to active)', async () => {
+        const { service, prisma } = makeService();
+        prisma.lease.create.mockResolvedValue(
+          leaseRow({
+            status: 'draft',
+            startDate: new Date('2020-01-01T00:00:00.000Z'),
+          }),
+        );
+
+        await service.create(orgId, actorId, buildingId, floorId, apartmentId, {
+          ...dto,
+          status: 'draft',
+          startDate: '2020-01-01T00:00:00.000Z',
+        });
+
+        expect(prisma.lease.create).toHaveBeenCalled();
+      });
+    });
+
     it('throws NotFoundException when the apartment does not belong to the floor/building/org', async () => {
       const { service } = makeService({
         apartment: { findFirst: jest.fn().mockResolvedValue(null) },
@@ -328,6 +508,91 @@ describe('LeasesService', () => {
         ),
       ).rejects.toBeInstanceOf(NotFoundException);
     });
+
+    describe('date-overlap check (F4.1)', () => {
+      it('excludes the lease being updated from the overlap check (self-exclusion)', async () => {
+        const { service, prisma } = makeService({
+          lease: {
+            findFirst: jest.fn().mockResolvedValue(leaseRow()),
+            findMany: jest.fn().mockResolvedValue([]),
+          },
+        });
+        prisma.lease.update.mockResolvedValue(
+          leaseRow({ endDate: new Date('2099-06-01T00:00:00.000Z') }),
+        );
+
+        await service.update(
+          orgId,
+          actorId,
+          buildingId,
+          floorId,
+          apartmentId,
+          'lease-1',
+          { endDate: '2099-06-01T00:00:00.000Z' },
+        );
+
+        expect(prisma.lease.findMany).toHaveBeenCalledWith({
+          where: { apartmentId, id: { not: 'lease-1' } },
+          select: { status: true, startDate: true, endDate: true },
+        });
+        expect(prisma.lease.update).toHaveBeenCalled();
+      });
+
+      it('rejects updating a lease when the new dates overlap another non-terminated lease on the same apartment', async () => {
+        const { service, prisma } = makeService({
+          lease: {
+            findFirst: jest.fn().mockResolvedValue(leaseRow()),
+            findMany: jest.fn().mockResolvedValue([
+              leaseRow({
+                id: 'lease-2',
+                startDate: new Date('2027-06-01T00:00:00.000Z'),
+                endDate: new Date('2028-06-01T00:00:00.000Z'),
+              }),
+            ]),
+          },
+        });
+
+        await expect(
+          service.update(
+            orgId,
+            actorId,
+            buildingId,
+            floorId,
+            apartmentId,
+            'lease-1',
+            {
+              startDate: '2027-01-01T00:00:00.000Z',
+              endDate: '2027-12-01T00:00:00.000Z',
+            },
+          ),
+        ).rejects.toBeInstanceOf(ConflictException);
+        expect(prisma.lease.update).not.toHaveBeenCalled();
+      });
+
+      it('does not re-run the overlap check when neither dates nor status change', async () => {
+        const { service, prisma } = makeService({
+          lease: {
+            findFirst: jest.fn().mockResolvedValue(leaseRow()),
+          },
+        });
+        prisma.lease.update.mockResolvedValue(
+          leaseRow({ rentAmount: new Prisma.Decimal('1600.00') }),
+        );
+
+        await service.update(
+          orgId,
+          actorId,
+          buildingId,
+          floorId,
+          apartmentId,
+          'lease-1',
+          { rentAmount: 1600 },
+        );
+
+        expect(prisma.lease.findMany).not.toHaveBeenCalled();
+        expect(prisma.lease.update).toHaveBeenCalled();
+      });
+    });
   });
 
   describe('remove', () => {
diff --git a/apps/api/src/modules/leases/leases.service.ts b/apps/api/src/modules/leases/leases.service.ts
index eddb88c6..d2fffe79 100644
--- a/apps/api/src/modules/leases/leases.service.ts
+++ b/apps/api/src/modules/leases/leases.service.ts
@@ -79,6 +79,52 @@ export class LeasesService {
     }
   }
 
+  /** UTC midnight for `date` — the F4.3 start-date policy compares at day granularity. */
+  private startOfUtcDay(date: Date): Date {
+    return new Date(
+      Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
+    );
+  }
+
+  /**
+   * F4.1: true date-range overlap check, replacing the old "any effectively-
+   * active lease on the apartment" rule (which ignored the new lease's own
+   * dates and made back-to-back/future leases impossible). Rejects only if
+   * `[startDate, endDate)` overlaps an existing NON-terminated lease's own
+   * `[startDate, endDate)` on the same apartment — end-exclusive, so
+   * back-to-back leases (newStart === existingEnd) are allowed. Terminated
+   * leases are filtered out in application code (matching the sibling
+   * WorkOrderApartmentStatusService convention of querying broadly and
+   * filtering status in JS) so a stale mock/row can't silently bypass this in
+   * tests. `excludeLeaseId` lets update() exclude its own row.
+   */
+  private async assertNoOverlappingLease(
+    apartmentId: string,
+    startDate: Date,
+    endDate: Date,
+    excludeLeaseId?: string,
+  ): Promise<void> {
+    const existingLeases = await this.prisma.lease.findMany({
+      where: {
+        apartmentId,
+        ...(excludeLeaseId && { id: { not: excludeLeaseId } }),
+      },
+      select: { status: true, startDate: true, endDate: true },
+    });
+
+    const overlaps = existingLeases.some(
+      (l) =>
+        l.status !== 'terminated' &&
+        startDate < l.endDate &&
+        l.startDate < endDate,
+    );
+    if (overlaps) {
+      throw new ConflictException(
+        'This apartment already has a lease that overlaps these dates.',
+      );
+    }
+  }
+
   // ── CRUD ──────────────────────────────────────────────────────────────────
 
   async findAll(
@@ -209,26 +255,32 @@ export class LeasesService {
   ): Promise<{ data: LeaseResponse }> {
     await this.assertApartmentInScope(orgId, buildingId, floorId, apartmentId);
     await this.assertRenterInOrg(orgId, dto.renterId);
-    this.assertValidDateRange(dto.startDate, dto.endDate);
+
+    const startDate = new Date(dto.startDate);
+    const endDate = new Date(dto.endDate);
+    this.assertValidDateRange(startDate, endDate);
 
     const resolvedStatus = dto.status ?? 'active';
     const now = new Date();
 
-    if (resolvedStatus === 'active') {
-      const existingLeases = await this.prisma.lease.findMany({
-        where: { apartmentId },
-      });
-      const hasActiveLease = existingLeases.some((l) =>
-        this.leaseStatus.isEffectivelyActive(
-          { status: l.status, endDate: l.endDate },
-          now,
-        ),
+    // F4.3 (decision D3): a new ACTIVE lease can't silently start in the
+    // past — that almost always means the caller meant to back-date an
+    // already-existing lease, which must be explicit via recordExisting.
+    if (
+      resolvedStatus === 'active' &&
+      this.startOfUtcDay(startDate) < this.startOfUtcDay(now) &&
+      !dto.recordExisting
+    ) {
+      throw new BadRequestException(
+        "A new active lease can't start in the past; use 'record an existing lease' to back-date.",
       );
-      if (hasActiveLease) {
-        throw new ConflictException(
-          'This apartment already has an active lease.',
-        );
-      }
+    }
+
+    // F4.1: reject only on a genuine date-range overlap with another
+    // non-terminated lease on this apartment — not simply "an active lease
+    // exists" (that made future/back-to-back leases impossible).
+    if (resolvedStatus !== 'terminated') {
+      await this.assertNoOverlappingLease(apartmentId, startDate, endDate);
     }
 
     const lease = await this.prisma.$transaction(async (tx) => {
@@ -239,8 +291,8 @@ export class LeasesService {
           floorId,
           apartmentId,
           renterId: dto.renterId,
-          startDate: new Date(dto.startDate),
-          endDate: new Date(dto.endDate),
+          startDate,
+          endDate,
           rentAmount: dto.rentAmount,
           depositAmount: dto.depositAmount,
           status: resolvedStatus,
@@ -287,10 +339,28 @@ export class LeasesService {
 
     // Validate the resulting date range against whichever dates are being
     // changed, falling back to the stored values for the untouched one.
-    this.assertValidDateRange(
-      dto.startDate ?? existing.startDate,
-      dto.endDate ?? existing.endDate,
-    );
+    const resolvedStartDate =
+      dto.startDate !== undefined ? new Date(dto.startDate) : existing.startDate;
+    const resolvedEndDate =
+      dto.endDate !== undefined ? new Date(dto.endDate) : existing.endDate;
+    this.assertValidDateRange(resolvedStartDate, resolvedEndDate);
+
+    // F4.1: re-run the overlap check when the update touches the dates
+    // and/or (re)activates the lease — excluding the lease's own row so it
+    // doesn't conflict with itself.
+    const resolvedStatus = dto.status ?? existing.status;
+    const datesOrStatusChanging =
+      dto.startDate !== undefined ||
+      dto.endDate !== undefined ||
+      dto.status !== undefined;
+    if (datesOrStatusChanging && resolvedStatus !== 'terminated') {
+      await this.assertNoOverlappingLease(
+        apartmentId,
+        resolvedStartDate,
+        resolvedEndDate,
+        leaseId,
+      );
+    }
 
     const isTerminating =
       dto.status === 'terminated' && existing.status !== 'terminated';
diff --git a/apps/web/src/app/api/apartments/status-sweep/route.ts b/apps/web/src/app/api/apartments/status-sweep/route.ts
new file mode 100644
index 00000000..f1fd0f83
--- /dev/null
+++ b/apps/web/src/app/api/apartments/status-sweep/route.ts
@@ -0,0 +1,7 @@
+import { forwardRoute } from '@/lib/api/forward';
+
+export const runtime = 'nodejs';
+
+// F4.2 — org_admin on-demand apartment-status expiry sweep. Also runs daily via
+// the backend scheduler; this is the on-demand path (and the verify hook).
+export const POST = forwardRoute('/apartments/status-sweep');
diff --git a/apps/web/src/components/dashboard/apartment-detail-page.tsx b/apps/web/src/components/dashboard/apartment-detail-page.tsx
index 535eb83c..ab9ac281 100644
--- a/apps/web/src/components/dashboard/apartment-detail-page.tsx
+++ b/apps/web/src/components/dashboard/apartment-detail-page.tsx
@@ -20,6 +20,7 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Badge } from '@/components/ui/badge';
+import { Checkbox } from '@/components/ui/checkbox';
 import { Skeleton } from '@/components/ui/skeleton';
 import { Textarea } from '@/components/ui/textarea';
 import {
@@ -141,6 +142,18 @@ function LeaseStatusBadge({
 
 type DialogDict = Dictionary['apartments']['dialog'];
 
+/**
+ * Today as a local `YYYY-MM-DD` string — matches the value shape of a native
+ * `<input type="date">` so it can be used directly as `min` and compared
+ * lexically against form date strings.
+ */
+function todayDateInputValue(): string {
+  const d = new Date();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return `${d.getFullYear()}-${mm}-${dd}`;
+}
+
 function buildLeaseSchema(t: DialogDict) {
   const numericField = (label: string) =>
     z
@@ -161,10 +174,17 @@ function buildLeaseSchema(t: DialogDict) {
       depositAmount: numericField(t.fields.depositAmount),
       renewalTerms: z.string().optional(),
       notes: z.string().optional(),
+      // F4.3 (decision D3): a new active lease may not silently start in the
+      // past unless the creator explicitly flags it as an existing lease.
+      recordExisting: z.boolean(),
     })
     .refine((v) => v.endDate >= v.startDate, {
       message: t.errors.endAfterStart,
       path: ['endDate'],
+    })
+    .refine((v) => v.recordExisting || v.startDate >= todayDateInputValue(), {
+      message: t.errors.pastStartDate,
+      path: ['startDate'],
     });
 }
 type LeaseFormValues = z.infer<ReturnType<typeof buildLeaseSchema>>;
@@ -177,6 +197,7 @@ const DEFAULT_VALUES: LeaseFormValues = {
   depositAmount: '',
   renewalTerms: '',
   notes: '',
+  recordExisting: false,
 };
 
 function buildRenewSchema(t: DialogDict) {
@@ -255,12 +276,16 @@ export function ApartmentDetailPage({
     handleSubmit,
     reset,
     control,
+    watch,
     formState: { errors },
   } = useForm<LeaseFormValues>({
     resolver: zodResolver(leaseSchema),
     defaultValues: DEFAULT_VALUES,
   });
 
+  const recordExisting = watch('recordExisting');
+  const todayStr = todayDateInputValue();
+
   const {
     register: regRenew,
     handleSubmit: handleRenewSubmit,
@@ -284,6 +309,7 @@ export function ApartmentDetailPage({
           depositAmount: Number(values.depositAmount),
           renewalTerms: values.renewalTerms || undefined,
           notes: values.notes || undefined,
+          ...(values.recordExisting ? { recordExisting: true } : {}),
         },
       }).unwrap();
       toast.success(t.dialog.create.success);
@@ -583,6 +609,29 @@ export function ApartmentDetailPage({
                 </p>
               )}
             </div>
+            <div className="flex flex-col gap-1.5">
+              <div className="flex items-center gap-2">
+                <Controller
+                  control={control}
+                  name="recordExisting"
+                  render={({ field }) => (
+                    <Checkbox
+                      id="l-record-existing"
+                      checked={field.value}
+                      onCheckedChange={(checked) =>
+                        field.onChange(checked === true)
+                      }
+                    />
+                  )}
+                />
+                <Label htmlFor="l-record-existing" className="font-normal">
+                  {t.dialog.fields.recordExisting}
+                </Label>
+              </div>
+              <p className="text-xs text-muted-foreground">
+                {t.dialog.fields.recordExistingHelp}
+              </p>
+            </div>
             <div className="grid grid-cols-2 gap-4">
               <div className="flex flex-col gap-1.5">
                 <Label htmlFor="l-start">
@@ -592,6 +641,7 @@ export function ApartmentDetailPage({
                 <Input
                   id="l-start"
                   type="date"
+                  min={recordExisting ? undefined : todayStr}
                   aria-invalid={!!errors.startDate}
                   {...register('startDate')}
                 />
diff --git a/apps/web/src/components/dashboard/leases-page.tsx b/apps/web/src/components/dashboard/leases-page.tsx
index 3f4ee8e0..58d93125 100644
--- a/apps/web/src/components/dashboard/leases-page.tsx
+++ b/apps/web/src/components/dashboard/leases-page.tsx
@@ -12,6 +12,7 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Badge } from '@/components/ui/badge';
+import { Checkbox } from '@/components/ui/checkbox';
 import { Skeleton } from '@/components/ui/skeleton';
 import { Textarea } from '@/components/ui/textarea';
 import {
@@ -90,6 +91,18 @@ function LeaseStatusBadge({
 const NONE = '__none__';
 const ALL = '__all__';
 
+/**
+ * Today as a local `YYYY-MM-DD` string — matches the value shape of a native
+ * `<input type="date">` so it can be used directly as `min` and compared
+ * lexically against form date strings.
+ */
+function todayDateInputValue(): string {
+  const d = new Date();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return `${d.getFullYear()}-${mm}-${dd}`;
+}
+
 function buildLeaseSchema(t: Dictionary['leases']['dialog']) {
   const numericField = () =>
     z
@@ -111,10 +124,17 @@ function buildLeaseSchema(t: Dictionary['leases']['dialog']) {
       depositAmount: numericField(),
       renewalTerms: z.string().optional(),
       notes: z.string().optional(),
+      // F4.3 (decision D3): a new active lease may not silently start in the
+      // past unless the creator explicitly flags it as an existing lease.
+      recordExisting: z.boolean(),
     })
     .refine((v) => v.endDate >= v.startDate, {
       message: t.errors.endAfterStart,
       path: ['endDate'],
+    })
+    .refine((v) => v.recordExisting || v.startDate >= todayDateInputValue(), {
+      message: t.errors.pastStartDate,
+      path: ['startDate'],
     });
 }
 
@@ -131,6 +151,7 @@ const DEFAULT_VALUES: NewLeaseFormValues = {
   depositAmount: '',
   renewalTerms: '',
   notes: '',
+  recordExisting: false,
 };
 
 // ── New lease dialog ─────────────────────────────────────────────────────────
@@ -169,6 +190,8 @@ function NewLeaseDialog({
 
   const buildingId = watch('buildingId');
   const floorId = watch('floorId');
+  const recordExisting = watch('recordExisting');
+  const todayStr = todayDateInputValue();
 
   const { data: floors } = useListFloorsQuery(buildingId, {
     skip: !buildingId,
@@ -197,6 +220,7 @@ function NewLeaseDialog({
           depositAmount: Number(values.depositAmount),
           renewalTerms: values.renewalTerms || undefined,
           notes: values.notes || undefined,
+          ...(values.recordExisting ? { recordExisting: true } : {}),
         },
       }).unwrap();
       toast.success(t.success);
@@ -388,6 +412,30 @@ function NewLeaseDialog({
             )}
           </div>
 
+          <div className="flex flex-col gap-1.5">
+            <div className="flex items-center gap-2">
+              <Controller
+                control={control}
+                name="recordExisting"
+                render={({ field }) => (
+                  <Checkbox
+                    id="nl-record-existing"
+                    checked={field.value}
+                    onCheckedChange={(checked) =>
+                      field.onChange(checked === true)
+                    }
+                  />
+                )}
+              />
+              <Label htmlFor="nl-record-existing" className="font-normal">
+                {t.recordExisting}
+              </Label>
+            </div>
+            <p className="text-xs text-muted-foreground">
+              {t.recordExistingHelp}
+            </p>
+          </div>
+
           <div className="grid grid-cols-2 gap-4">
             <div className="flex flex-col gap-1.5">
               <Label htmlFor="nl-start">
@@ -396,6 +444,7 @@ function NewLeaseDialog({
               <Input
                 id="nl-start"
                 type="date"
+                min={recordExisting ? undefined : todayStr}
                 aria-invalid={!!errors.startDate}
                 {...register('startDate')}
               />
diff --git a/apps/web/src/i18n/dictionaries/ar.json b/apps/web/src/i18n/dictionaries/ar.json
index 58139c91..a9879dd8 100644
--- a/apps/web/src/i18n/dictionaries/ar.json
+++ b/apps/web/src/i18n/dictionaries/ar.json
@@ -384,8 +384,11 @@
         "startDate": "تاريخ البدء مطلوب",
         "endDate": "تاريخ الانتهاء مطلوب",
         "endAfterStart": "يجب أن يكون تاريخ الانتهاء في أو بعد تاريخ البدء",
-        "invalidAmount": "أدخل قيمة صالحة غير سالبة"
-      }
+        "invalidAmount": "أدخل قيمة صالحة غير سالبة",
+        "pastStartDate": "لا يمكن أن يكون تاريخ البدء في الماضي لعقد إيجار نشط جديد. فعّل \"تسجيل عقد إيجار قائم\" لتسجيله بتاريخ سابق."
+      },
+      "recordExisting": "تسجيل عقد إيجار قائم",
+      "recordExistingHelp": "يسمح بتاريخ بدء في الماضي لعقد إيجار بدأ فعليًا قبل اليوم."
     }
   },
   "support": {
@@ -688,7 +691,9 @@
         "depositAmount": "قيمة التأمين",
         "renewalTerms": "شروط التجديد",
         "notes": "ملاحظات",
-        "optional": "(اختياري)"
+        "optional": "(اختياري)",
+        "recordExisting": "تسجيل عقد إيجار قائم",
+        "recordExistingHelp": "يسمح بتاريخ بدء في الماضي لعقد إيجار بدأ فعليًا قبل اليوم."
       },
       "errors": {
         "renter": "المستأجر مطلوب",
@@ -696,7 +701,8 @@
         "endDate": "تاريخ الانتهاء مطلوب",
         "endAfterStart": "يجب أن يكون تاريخ الانتهاء في أو بعد تاريخ البدء",
         "mustBeNumber": "{label} يجب أن يكون رقماً",
-        "cannotBeNegative": "{label} لا يمكن أن يكون سالباً"
+        "cannotBeNegative": "{label} لا يمكن أن يكون سالباً",
+        "pastStartDate": "لا يمكن أن يكون تاريخ البدء في الماضي لعقد إيجار نشط جديد. فعّل \"تسجيل عقد إيجار قائم\" لتسجيله بتاريخ سابق."
       },
       "create": {
         "title": "عقد جديد",
diff --git a/apps/web/src/i18n/dictionaries/en.json b/apps/web/src/i18n/dictionaries/en.json
index abba9df7..284d428c 100644
--- a/apps/web/src/i18n/dictionaries/en.json
+++ b/apps/web/src/i18n/dictionaries/en.json
@@ -384,8 +384,11 @@
         "startDate": "Start date is required",
         "endDate": "End date is required",
         "endAfterStart": "End date must be on or after the start date",
-        "invalidAmount": "Enter a valid, non-negative amount"
-      }
+        "invalidAmount": "Enter a valid, non-negative amount",
+        "pastStartDate": "Start date can't be in the past for a new active lease. Check \"Record an existing lease\" to back-date it."
+      },
+      "recordExisting": "Record an existing lease",
+      "recordExistingHelp": "Allow a start date in the past for a lease that already began before today."
     }
   },
   "support": {
@@ -688,7 +691,9 @@
         "depositAmount": "Deposit amount",
         "renewalTerms": "Renewal terms",
         "notes": "Notes",
-        "optional": "(optional)"
+        "optional": "(optional)",
+        "recordExisting": "Record an existing lease",
+        "recordExistingHelp": "Allow a start date in the past for a lease that already began before today."
       },
       "errors": {
         "renter": "Renter is required",
@@ -696,7 +701,8 @@
         "endDate": "End date is required",
         "endAfterStart": "End date must be on or after the start date",
         "mustBeNumber": "{label} must be a number",
-        "cannotBeNegative": "{label} cannot be negative"
+        "cannotBeNegative": "{label} cannot be negative",
+        "pastStartDate": "Start date can't be in the past for a new active lease. Check \"Record an existing lease\" to back-date it."
       },
       "create": {
         "title": "New lease",
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 26451ea9..ceef822e 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -432,6 +432,12 @@ export type CreateLeaseBody = {
   status?: LeaseStatus;
   renewalTerms?: string;
   notes?: string;
+  /**
+   * F4.3 (decision D3): a NEW active lease may not silently start in the past.
+   * Set this to explicitly record an already-existing lease with a back-dated
+   * start; without it, a past start on an active lease is rejected (400).
+   */
+  recordExisting?: boolean;
 };
 
 export type PatchLeaseBody = {
@@ -672,6 +678,16 @@ export type RecurringInvoiceRunResponse = {
   skippedExisting: number; // periods that already had an invoice (idempotent no-op)
 };
 
+/**
+ * Result of an apartment-status expiry sweep (F4.2): reverts `occupied`
+ * apartments that no longer have an effectively-active lease (and no open work
+ * order) back to `vacant`. Runs daily via the scheduler and on-demand.
+ */
+export type ApartmentStatusSweepResponse = {
+  reverted: number; // apartments flipped occupied -> vacant
+  considered: number; // occupied apartments inspected
+};
+
 // ── Expenses ─────────────────────────────────────────────────────────────────
 
 export const expenseCategorySchema = z.enum([

From 920fe1b13f7552ec588db117e6ecd758460679a2 Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 04:05:46 +0300
Subject: [PATCH 07/11] =?UTF-8?q?feat(F5):=20notifications=20&=20activity/?=
 =?UTF-8?q?audit=20=E2=80=94=204=20new=20triggers=20+=20activity=20feed=20?=
 =?UTF-8?q?shows=20the=20actor?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sprint F5 of the Property Manager behavior roadmap (workflow W8). No migration.

F5.1 [Q20] Expand notification triggers (were: only support-ticket open/status).
  Added best-effort in-app notifications (alongside the existing timeline.emit,
  each skips silently when the recipient sub is null) for:
  - work_order.assigned → the assignee (WorkOrdersService.create + genuine
    reassignment in update; never notifies the actor about themself)
  - invoice.issued → the tenant (InvoicesService.create + the F3.1 recurring
    auto-generator) via Lease→Renter.renterUserId
  - invoice.payment_recorded → the tenant (InvoicePaymentsService.create)
  - lease.created → the tenant (LeasesService.create)
  Each module now imports NotificationsModule. Role-fanout triggers
  (payment-failed→finance, lease-expiring→admin, maintenance-created→supervisors)
  are left as documented // TODO F5.1 follow-up (need a shared org-members-by-role
  helper + a new expiry sweep).

F5.2 [Q18] Activity feed shows WHO. TimelineService.findForCaller now enriches
  each event with actorName by resolving distinct actorId subs via
  KeycloakAdminService.getUser (name→email→null), deduped per page + cached
  per-sub with a 5-min TTL; KC failure → null, never throws. Contract
  TimelineEvent.actorName added; the timeline feed renders "by {actor}" with a
  "System" fallback for actor-less/system events; dict wired into both feed
  call sites (+ localized the Activity page heading).

i18n parity en==ar 1054. Verified: api build EXIT 0 + full jest 332 pass/4 skip;
web check-types clean, vitest 30/30, next build EXIT 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../invoice-payments.module.ts                |   2 +
 .../invoice-payments.service.spec.ts          |  64 ++++++++-
 .../invoice-payments.service.ts               |  20 ++-
 .../src/modules/invoices/invoices.module.ts   |   2 +
 .../modules/invoices/invoices.service.spec.ts |  57 +++++++-
 .../src/modules/invoices/invoices.service.ts  |  21 ++-
 apps/api/src/modules/leases/leases.module.ts  |   2 +
 .../src/modules/leases/leases.service.spec.ts |  68 ++++++++-
 apps/api/src/modules/leases/leases.service.ts |  22 ++-
 .../recurring-invoices.module.ts              |   6 +-
 .../recurring-invoices.service.spec.ts        |  76 +++++++++-
 .../recurring-invoices.service.ts             |  34 ++++-
 .../modules/timeline/timeline.service.spec.ts | 128 ++++++++++++++++-
 .../src/modules/timeline/timeline.service.ts  |  99 ++++++++++++-
 .../modules/work-orders/work-orders.module.ts |   2 +
 .../work-orders/work-orders.service.spec.ts   | 136 ++++++++++++++++++
 .../work-orders/work-orders.service.ts        |  48 +++++++
 .../app/[lang]/dashboard/timeline/page.tsx    |   7 +-
 .../dashboard/org-admin-dashboard.tsx         |   2 +-
 .../components/dashboard/timeline-feed.tsx    |  36 +++--
 apps/web/src/i18n/dictionaries/ar.json        |   4 +
 apps/web/src/i18n/dictionaries/en.json        |   4 +
 packages/contracts/src/index.ts               |   3 +
 23 files changed, 810 insertions(+), 33 deletions(-)

diff --git a/apps/api/src/modules/invoice-payments/invoice-payments.module.ts b/apps/api/src/modules/invoice-payments/invoice-payments.module.ts
index 19644921..2d1a89ec 100644
--- a/apps/api/src/modules/invoice-payments/invoice-payments.module.ts
+++ b/apps/api/src/modules/invoice-payments/invoice-payments.module.ts
@@ -1,8 +1,10 @@
 import { Module } from '@nestjs/common';
 import { InvoicePaymentsController } from './invoice-payments.controller';
 import { InvoicePaymentsService } from './invoice-payments.service';
+import { NotificationsModule } from '@/modules/notifications/notifications.module';
 
 @Module({
+  imports: [NotificationsModule],
   controllers: [InvoicePaymentsController],
   providers: [InvoicePaymentsService],
   exports: [InvoicePaymentsService],
diff --git a/apps/api/src/modules/invoice-payments/invoice-payments.service.spec.ts b/apps/api/src/modules/invoice-payments/invoice-payments.service.spec.ts
index 71956c24..761ed460 100644
--- a/apps/api/src/modules/invoice-payments/invoice-payments.service.spec.ts
+++ b/apps/api/src/modules/invoice-payments/invoice-payments.service.spec.ts
@@ -16,6 +16,7 @@ describe('InvoicePaymentsService', () => {
       invoicePayment?: Partial<Record<string, jest.Mock>>;
       invoice?: Partial<Record<string, jest.Mock>>;
       buildingAccess?: Partial<Record<string, jest.Mock>>;
+      notifications?: Partial<Record<string, jest.Mock>>;
     } = {},
   ) {
     const prisma: any = {
@@ -37,12 +38,17 @@ describe('InvoicePaymentsService', () => {
       ...overrides.buildingAccess,
     };
     const timeline = { emit: jest.fn().mockResolvedValue(undefined) };
+    const notifications = {
+      enqueue: jest.fn().mockResolvedValue(undefined),
+      ...overrides.notifications,
+    };
     const service = new InvoicePaymentsService(
       prisma,
       buildingAccess as any,
       timeline as any,
+      notifications as any,
     );
-    return { service, prisma, buildingAccess, timeline };
+    return { service, prisma, buildingAccess, timeline, notifications };
   }
 
   const decimal = (value: string) => ({
@@ -168,7 +174,10 @@ describe('InvoicePaymentsService', () => {
         invoice: {
           findFirst: jest
             .fn()
-            .mockResolvedValueOnce({ id: 'invoice-1' })
+            .mockResolvedValueOnce({
+              id: 'invoice-1',
+              lease: { renter: { renterUserId: null } },
+            })
             .mockResolvedValueOnce(invoiceForSummary()),
         },
         invoicePayment: {
@@ -225,6 +234,57 @@ describe('InvoicePaymentsService', () => {
         service.create(orgId, callerId, Role.SUPERVISOR, dto),
       ).rejects.toBeInstanceOf(ForbiddenException);
     });
+
+    describe('tenant notification (F5.1)', () => {
+      it('notifies the tenant when the invoice lease renter has a linked portal user', async () => {
+        const { service, notifications } = makeService({
+          invoice: {
+            findFirst: jest
+              .fn()
+              .mockResolvedValueOnce({
+                id: 'invoice-1',
+                lease: { renter: { renterUserId: 'tenant-user-1' } },
+              })
+              .mockResolvedValueOnce(invoiceForSummary()),
+          },
+          invoicePayment: {
+            create: jest.fn().mockResolvedValue(paymentRow()),
+          },
+        });
+
+        await service.create(orgId, callerId, Role.ORG_ADMIN, dto);
+
+        expect(notifications.enqueue).toHaveBeenCalledTimes(1);
+        expect(notifications.enqueue).toHaveBeenCalledWith(
+          expect.objectContaining({
+            orgId,
+            userId: 'tenant-user-1',
+            type: 'invoice.payment_recorded',
+          }),
+        );
+      });
+
+      it('does not notify when the renter has no linked portal user', async () => {
+        const { service, notifications } = makeService({
+          invoice: {
+            findFirst: jest
+              .fn()
+              .mockResolvedValueOnce({
+                id: 'invoice-1',
+                lease: { renter: { renterUserId: null } },
+              })
+              .mockResolvedValueOnce(invoiceForSummary()),
+          },
+          invoicePayment: {
+            create: jest.fn().mockResolvedValue(paymentRow()),
+          },
+        });
+
+        await service.create(orgId, callerId, Role.ORG_ADMIN, dto);
+
+        expect(notifications.enqueue).not.toHaveBeenCalled();
+      });
+    });
   });
 
   describe('remove', () => {
diff --git a/apps/api/src/modules/invoice-payments/invoice-payments.service.ts b/apps/api/src/modules/invoice-payments/invoice-payments.service.ts
index 679d89fe..0d965698 100644
--- a/apps/api/src/modules/invoice-payments/invoice-payments.service.ts
+++ b/apps/api/src/modules/invoice-payments/invoice-payments.service.ts
@@ -8,6 +8,7 @@ import { Prisma } from '@repo/db';
 import { PrismaService } from '@/infrastructure/prisma/prisma.service';
 import { BuildingAccessService } from '@/common/building-access/building-access.service';
 import { TimelineService } from '@/modules/timeline/timeline.service';
+import { NotificationsService } from '@/modules/notifications/notifications.service';
 import { Role } from '@/common/enums';
 import {
   InvoicePaymentMethod,
@@ -35,6 +36,7 @@ export class InvoicePaymentsService {
     private readonly prisma: PrismaService,
     private readonly buildingAccess: BuildingAccessService,
     private readonly timeline: TimelineService,
+    private readonly notifications: NotificationsService,
   ) {}
 
   private assertWriteAccess(callerRole: Role): void {
@@ -159,7 +161,10 @@ export class InvoicePaymentsService {
 
     const invoice = await this.prisma.invoice.findFirst({
       where: { id: dto.invoiceId, orgId },
-      select: { id: true },
+      select: {
+        id: true,
+        lease: { select: { renter: { select: { renterUserId: true } } } },
+      },
     });
     if (!invoice) throw new NotFoundException('Invoice not found.');
 
@@ -183,6 +188,19 @@ export class InvoicePaymentsService {
       metadata: { invoiceId: invoice.id, amount: payment.amount.toString() },
     });
 
+    // F5.1: notify the tenant a payment was recorded — skip silently if the
+    // renter has no linked portal user.
+    if (invoice.lease.renter.renterUserId) {
+      await this.notifications.enqueue({
+        orgId,
+        userId: invoice.lease.renter.renterUserId,
+        type: 'invoice.payment_recorded',
+        title: 'Payment recorded',
+        body: `A payment of ${payment.amount.toString()} was recorded on your invoice.`,
+        data: { invoiceId: invoice.id, paymentId: payment.id },
+      });
+    }
+
     const summary = await this.summarizeInvoice(orgId, invoice.id);
 
     return { data: { payment: this.formatPayment(payment), invoice: summary } };
diff --git a/apps/api/src/modules/invoices/invoices.module.ts b/apps/api/src/modules/invoices/invoices.module.ts
index 058d12f8..25ec475d 100644
--- a/apps/api/src/modules/invoices/invoices.module.ts
+++ b/apps/api/src/modules/invoices/invoices.module.ts
@@ -1,8 +1,10 @@
 import { Module } from '@nestjs/common';
 import { InvoicesController } from './invoices.controller';
 import { InvoicesService } from './invoices.service';
+import { NotificationsModule } from '@/modules/notifications/notifications.module';
 
 @Module({
+  imports: [NotificationsModule],
   controllers: [InvoicesController],
   providers: [InvoicesService],
   exports: [InvoicesService],
diff --git a/apps/api/src/modules/invoices/invoices.service.spec.ts b/apps/api/src/modules/invoices/invoices.service.spec.ts
index b02a2d2c..ecd5ed7c 100644
--- a/apps/api/src/modules/invoices/invoices.service.spec.ts
+++ b/apps/api/src/modules/invoices/invoices.service.spec.ts
@@ -19,6 +19,7 @@ describe('InvoicesService', () => {
       invoiceLineItem?: Partial<Record<string, jest.Mock>>;
       invoicePayment?: Partial<Record<string, jest.Mock>>;
       buildingAccess?: Partial<Record<string, jest.Mock>>;
+      notifications?: Partial<Record<string, jest.Mock>>;
     } = {},
   ) {
     const prisma: any = {
@@ -52,12 +53,17 @@ describe('InvoicesService', () => {
       ...overrides.buildingAccess,
     };
     const timeline = { emit: jest.fn().mockResolvedValue(undefined) };
+    const notifications = {
+      enqueue: jest.fn().mockResolvedValue(undefined),
+      ...overrides.notifications,
+    };
     const service = new InvoicesService(
       prisma,
       buildingAccess as any,
       timeline as any,
+      notifications as any,
     );
-    return { service, prisma, buildingAccess, timeline };
+    return { service, prisma, buildingAccess, timeline, notifications };
   }
 
   const decimal = (value: string) => ({
@@ -210,7 +216,11 @@ describe('InvoicesService', () => {
     it('creates an invoice with the denormalized buildingId from the lease', async () => {
       const { service, prisma, timeline } = makeService({
         lease: {
-          findFirst: jest.fn().mockResolvedValue({ id: 'lease-1', buildingId }),
+          findFirst: jest.fn().mockResolvedValue({
+            id: 'lease-1',
+            buildingId,
+            renter: { renterUserId: null },
+          }),
         },
         invoice: { create: jest.fn().mockResolvedValue(invoiceRow()) },
       });
@@ -275,6 +285,49 @@ describe('InvoicesService', () => {
         service.create(orgId, callerId, Role.SUPERVISOR, dto),
       ).rejects.toBeInstanceOf(ForbiddenException);
     });
+
+    describe('tenant notification (F5.1)', () => {
+      it('notifies the tenant when the lease renter has a linked portal user', async () => {
+        const { service, notifications } = makeService({
+          lease: {
+            findFirst: jest.fn().mockResolvedValue({
+              id: 'lease-1',
+              buildingId,
+              renter: { renterUserId: 'tenant-user-1' },
+            }),
+          },
+          invoice: { create: jest.fn().mockResolvedValue(invoiceRow()) },
+        });
+
+        await service.create(orgId, callerId, Role.ORG_ADMIN, dto);
+
+        expect(notifications.enqueue).toHaveBeenCalledTimes(1);
+        expect(notifications.enqueue).toHaveBeenCalledWith(
+          expect.objectContaining({
+            orgId,
+            userId: 'tenant-user-1',
+            type: 'invoice.issued',
+          }),
+        );
+      });
+
+      it('does not notify when the renter has no linked portal user', async () => {
+        const { service, notifications } = makeService({
+          lease: {
+            findFirst: jest.fn().mockResolvedValue({
+              id: 'lease-1',
+              buildingId,
+              renter: { renterUserId: null },
+            }),
+          },
+          invoice: { create: jest.fn().mockResolvedValue(invoiceRow()) },
+        });
+
+        await service.create(orgId, callerId, Role.ORG_ADMIN, dto);
+
+        expect(notifications.enqueue).not.toHaveBeenCalled();
+      });
+    });
   });
 
   describe('update', () => {
diff --git a/apps/api/src/modules/invoices/invoices.service.ts b/apps/api/src/modules/invoices/invoices.service.ts
index 1f514fad..4cc2d3f7 100644
--- a/apps/api/src/modules/invoices/invoices.service.ts
+++ b/apps/api/src/modules/invoices/invoices.service.ts
@@ -9,6 +9,7 @@ import { Prisma } from '@repo/db';
 import { PrismaService } from '@/infrastructure/prisma/prisma.service';
 import { BuildingAccessService } from '@/common/building-access/building-access.service';
 import { TimelineService } from '@/modules/timeline/timeline.service';
+import { NotificationsService } from '@/modules/notifications/notifications.service';
 import { Role } from '@/common/enums';
 import { InvoiceLineItemCategory, InvoiceResponse } from '@repo/contracts';
 import { computeInvoiceSummary } from '@/common/invoice-summary/compute-invoice-summary';
@@ -58,6 +59,7 @@ export class InvoicesService {
     private readonly prisma: PrismaService,
     private readonly buildingAccess: BuildingAccessService,
     private readonly timeline: TimelineService,
+    private readonly notifications: NotificationsService,
   ) {}
 
   private assertWriteAccess(callerRole: Role): void {
@@ -180,7 +182,11 @@ export class InvoicesService {
 
     const lease = await this.prisma.lease.findFirst({
       where: { id: dto.leaseId, orgId },
-      select: { id: true, buildingId: true },
+      select: {
+        id: true,
+        buildingId: true,
+        renter: { select: { renterUserId: true } },
+      },
     });
     if (!lease) throw new NotFoundException('Lease not found.');
 
@@ -214,6 +220,19 @@ export class InvoicesService {
       },
     });
 
+    // F5.1: notify the tenant an invoice was issued — skip silently if the
+    // renter has no linked portal user (renterUserId is nullable).
+    if (lease.renter.renterUserId) {
+      await this.notifications.enqueue({
+        orgId,
+        userId: lease.renter.renterUserId,
+        type: 'invoice.issued',
+        title: 'New invoice issued',
+        body: `An invoice due ${invoice.dueDate.toISOString().slice(0, 10)} has been issued to your lease.`,
+        data: { invoiceId: invoice.id, leaseId: invoice.leaseId },
+      });
+    }
+
     return { data: this.formatInvoice(invoice) };
   }
 
diff --git a/apps/api/src/modules/leases/leases.module.ts b/apps/api/src/modules/leases/leases.module.ts
index 588310b0..e8b3b7f9 100644
--- a/apps/api/src/modules/leases/leases.module.ts
+++ b/apps/api/src/modules/leases/leases.module.ts
@@ -2,8 +2,10 @@ import { Module } from '@nestjs/common';
 import { LeasesController } from './leases.controller';
 import { LeasesOverviewController } from './leases-overview.controller';
 import { LeasesService } from './leases.service';
+import { NotificationsModule } from '@/modules/notifications/notifications.module';
 
 @Module({
+  imports: [NotificationsModule],
   controllers: [LeasesController, LeasesOverviewController],
   providers: [LeasesService],
   exports: [LeasesService],
diff --git a/apps/api/src/modules/leases/leases.service.spec.ts b/apps/api/src/modules/leases/leases.service.spec.ts
index 6152086a..45d5cd60 100644
--- a/apps/api/src/modules/leases/leases.service.spec.ts
+++ b/apps/api/src/modules/leases/leases.service.spec.ts
@@ -29,6 +29,7 @@ describe('LeasesService', () => {
       building?: Partial<Record<string, jest.Mock>>;
       floor?: Partial<Record<string, jest.Mock>>;
       buildingAccess?: Partial<Record<string, jest.Mock>>;
+      notifications?: Partial<Record<string, jest.Mock>>;
     } = {},
   ) {
     const prisma: any = {
@@ -75,6 +76,10 @@ describe('LeasesService', () => {
     );
 
     const timeline = { emit: jest.fn().mockResolvedValue(undefined) };
+    const notifications = {
+      enqueue: jest.fn().mockResolvedValue(undefined),
+      ...overrides.notifications,
+    };
     const buildingAccess = {
       assertBuildingAccess: jest.fn().mockResolvedValue(undefined),
       getAllowedBuildingIds: jest.fn(),
@@ -84,10 +89,18 @@ describe('LeasesService', () => {
     const service = new LeasesService(
       prisma,
       timeline as any,
+      notifications as any,
       buildingAccess as any,
       leaseStatus,
     );
-    return { service, prisma, timeline, buildingAccess, leaseStatus };
+    return {
+      service,
+      prisma,
+      timeline,
+      notifications,
+      buildingAccess,
+      leaseStatus,
+    };
   }
 
   const leaseRow = (overrides: Partial<Record<string, unknown>> = {}) => ({
@@ -423,6 +436,59 @@ describe('LeasesService', () => {
         service.create(orgId, actorId, buildingId, floorId, apartmentId, dto),
       ).rejects.toBeInstanceOf(NotFoundException);
     });
+
+    describe('tenant notification (F5.1)', () => {
+      it('notifies the tenant when the renter has a linked portal user', async () => {
+        const { service, prisma, notifications } = makeService({
+          renter: {
+            findFirst: jest
+              .fn()
+              .mockResolvedValue({ id: renterId, renterUserId: 'tenant-user-1' }),
+          },
+        });
+        prisma.lease.create.mockResolvedValue(leaseRow());
+
+        await service.create(
+          orgId,
+          actorId,
+          buildingId,
+          floorId,
+          apartmentId,
+          dto,
+        );
+
+        expect(notifications.enqueue).toHaveBeenCalledTimes(1);
+        expect(notifications.enqueue).toHaveBeenCalledWith(
+          expect.objectContaining({
+            orgId,
+            userId: 'tenant-user-1',
+            type: 'lease.created',
+          }),
+        );
+      });
+
+      it('does not notify when the renter has no linked portal user', async () => {
+        const { service, prisma, notifications } = makeService({
+          renter: {
+            findFirst: jest
+              .fn()
+              .mockResolvedValue({ id: renterId, renterUserId: null }),
+          },
+        });
+        prisma.lease.create.mockResolvedValue(leaseRow());
+
+        await service.create(
+          orgId,
+          actorId,
+          buildingId,
+          floorId,
+          apartmentId,
+          dto,
+        );
+
+        expect(notifications.enqueue).not.toHaveBeenCalled();
+      });
+    });
   });
 
   describe('update', () => {
diff --git a/apps/api/src/modules/leases/leases.service.ts b/apps/api/src/modules/leases/leases.service.ts
index d2fffe79..8539f3f4 100644
--- a/apps/api/src/modules/leases/leases.service.ts
+++ b/apps/api/src/modules/leases/leases.service.ts
@@ -6,6 +6,7 @@ import {
 } from '@nestjs/common';
 import { PrismaService } from '@/infrastructure/prisma/prisma.service';
 import { TimelineService } from '@/modules/timeline/timeline.service';
+import { NotificationsService } from '@/modules/notifications/notifications.service';
 import { BuildingAccessService } from '@/common/building-access/building-access.service';
 import { LeaseStatusService } from '@/common/lease-status/lease-status.service';
 import { Role } from '@/common/enums';
@@ -22,6 +23,7 @@ export class LeasesService {
   constructor(
     private readonly prisma: PrismaService,
     private readonly timeline: TimelineService,
+    private readonly notifications: NotificationsService,
     private readonly buildingAccess: BuildingAccessService,
     private readonly leaseStatus: LeaseStatusService,
   ) {}
@@ -49,12 +51,13 @@ export class LeasesService {
   private async assertRenterInOrg(
     orgId: string,
     renterId: string,
-  ): Promise<void> {
+  ): Promise<{ id: string; renterUserId: string | null }> {
     const renter = await this.prisma.renter.findFirst({
       where: { id: renterId, orgId },
-      select: { id: true },
+      select: { id: true, renterUserId: true },
     });
     if (!renter) throw new NotFoundException('Renter not found.');
+    return renter;
   }
 
   /**
@@ -254,7 +257,7 @@ export class LeasesService {
     dto: CreateLeaseDto,
   ): Promise<{ data: LeaseResponse }> {
     await this.assertApartmentInScope(orgId, buildingId, floorId, apartmentId);
-    await this.assertRenterInOrg(orgId, dto.renterId);
+    const renter = await this.assertRenterInOrg(orgId, dto.renterId);
 
     const startDate = new Date(dto.startDate);
     const endDate = new Date(dto.endDate);
@@ -320,6 +323,19 @@ export class LeasesService {
       metadata: { apartmentId, renterId: dto.renterId },
     });
 
+    // F5.1: notify the tenant — skip silently if the renter has no linked
+    // portal user.
+    if (renter.renterUserId) {
+      await this.notifications.enqueue({
+        orgId,
+        userId: renter.renterUserId,
+        type: 'lease.created',
+        title: 'New lease created',
+        body: 'A new lease has been created for you.',
+        data: { leaseId: lease.id, apartmentId },
+      });
+    }
+
     return { data: this.formatLease(lease) };
   }
 
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices.module.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices.module.ts
index 317bb2b4..bb7c9d57 100644
--- a/apps/api/src/modules/recurring-invoices/recurring-invoices.module.ts
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices.module.ts
@@ -5,9 +5,13 @@ import { RecurringInvoicesService } from './recurring-invoices.service';
 import { RecurringInvoicesProcessor } from './recurring-invoices.processor';
 import { RecurringInvoicesSchedulerService } from './recurring-invoices-scheduler.service';
 import { RECURRING_INVOICES_QUEUE } from './recurring-invoices.constants';
+import { NotificationsModule } from '@/modules/notifications/notifications.module';
 
 @Module({
-  imports: [BullModule.registerQueue({ name: RECURRING_INVOICES_QUEUE })],
+  imports: [
+    BullModule.registerQueue({ name: RECURRING_INVOICES_QUEUE }),
+    NotificationsModule,
+  ],
   controllers: [RecurringInvoicesController],
   providers: [
     RecurringInvoicesService,
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices.service.spec.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices.service.spec.ts
index 8336e4df..b360754b 100644
--- a/apps/api/src/modules/recurring-invoices/recurring-invoices.service.spec.ts
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices.service.spec.ts
@@ -11,6 +11,7 @@ describe('RecurringInvoicesService', () => {
     overrides: {
       invoice?: Partial<Record<string, jest.Mock>>;
       lease?: Partial<Record<string, jest.Mock>>;
+      notifications?: Partial<Record<string, jest.Mock>>;
     } = {},
   ) {
     const prisma: any = {
@@ -29,13 +30,18 @@ describe('RecurringInvoicesService', () => {
       },
     };
     const timeline = { emit: jest.fn().mockResolvedValue(undefined) };
+    const notifications = {
+      enqueue: jest.fn().mockResolvedValue(undefined),
+      ...overrides.notifications,
+    };
     const leaseStatus = new LeaseStatusService();
     const service = new RecurringInvoicesService(
       prisma,
       timeline as any,
+      notifications as any,
       leaseStatus,
     );
-    return { service, prisma, timeline, leaseStatus };
+    return { service, prisma, timeline, notifications, leaseStatus };
   }
 
   const lease = (overrides: Partial<Record<string, unknown>> = {}) => ({
@@ -46,9 +52,19 @@ describe('RecurringInvoicesService', () => {
     endDate: new Date('2027-01-15T00:00:00.000Z'),
     status: 'active',
     rentAmount: new Prisma.Decimal('1000.00'),
+    renterUserId: null,
     ...overrides,
   });
 
+  // runForOrg/runAll query the DB with `renter: { select: { renterUserId } }`
+  // nested (RecurringLeaseInput itself stays flat for generateForLease's
+  // hand-built fixtures — see its doc comment). This wraps a flat `lease()`
+  // fixture into the raw Prisma-shaped row runForOrg's mapping expects.
+  const rawLeaseRow = (l: ReturnType<typeof lease>) => {
+    const { renterUserId, ...rest } = l;
+    return { ...rest, renter: { renterUserId: renterUserId ?? null } };
+  };
+
   describe('generateForLease', () => {
     it('creates an invoice when the next due date is within the 7-day lead window', async () => {
       const { service, prisma, timeline } = makeService();
@@ -217,6 +233,51 @@ describe('RecurringInvoicesService', () => {
       expect(result).toBe('inactive');
       expect(prisma.invoice.create).not.toHaveBeenCalled();
     });
+
+    describe('tenant notification (F5.1)', () => {
+      it('notifies the tenant when the lease has a linked portal user', async () => {
+        const { service, notifications } = makeService();
+        const asOf = new Date('2026-06-15T00:00:00.000Z');
+
+        const result = await service.generateForLease(
+          lease({ renterUserId: 'tenant-user-1' }),
+          asOf,
+        );
+
+        expect(result).toBe('created');
+        expect(notifications.enqueue).toHaveBeenCalledTimes(1);
+        expect(notifications.enqueue).toHaveBeenCalledWith(
+          expect.objectContaining({
+            orgId,
+            userId: 'tenant-user-1',
+            type: 'invoice.issued',
+          }),
+        );
+      });
+
+      it('does not notify when the lease has no linked portal user', async () => {
+        const { service, notifications } = makeService();
+        const asOf = new Date('2026-06-15T00:00:00.000Z');
+
+        const result = await service.generateForLease(lease(), asOf);
+
+        expect(result).toBe('created');
+        expect(notifications.enqueue).not.toHaveBeenCalled();
+      });
+
+      it('does not notify when no invoice is generated (not-due)', async () => {
+        const { service, notifications } = makeService();
+        const asOf = new Date('2026-06-01T00:00:00.000Z'); // 14 days away
+
+        const result = await service.generateForLease(
+          lease({ renterUserId: 'tenant-user-1' }),
+          asOf,
+        );
+
+        expect(result).toBe('not-due');
+        expect(notifications.enqueue).not.toHaveBeenCalled();
+      });
+    });
   });
 
   describe('runForOrg', () => {
@@ -228,7 +289,12 @@ describe('RecurringInvoicesService', () => {
       });
       const { service, prisma } = makeService({
         lease: {
-          findMany: jest.fn().mockResolvedValue([dueLease, notDueLease]),
+          findMany: jest
+            .fn()
+            .mockResolvedValue([
+              rawLeaseRow(dueLease),
+              rawLeaseRow(notDueLease),
+            ]),
         },
       });
       const asOf = new Date('2026-06-15T00:00:00.000Z');
@@ -251,8 +317,10 @@ describe('RecurringInvoicesService', () => {
           findMany: jest
             .fn()
             .mockResolvedValueOnce([{ orgId: 'org-a' }, { orgId: 'org-b' }]) // distinct orgId query
-            .mockResolvedValueOnce([lease({ orgId: 'org-a' })]) // org-a leases
-            .mockResolvedValueOnce([lease({ orgId: 'org-b', id: 'lease-2' })]), // org-b leases
+            .mockResolvedValueOnce([rawLeaseRow(lease({ orgId: 'org-a' }))]) // org-a leases
+            .mockResolvedValueOnce([
+              rawLeaseRow(lease({ orgId: 'org-b', id: 'lease-2' })),
+            ]), // org-b leases
         },
       });
       const asOf = new Date('2026-06-15T00:00:00.000Z');
diff --git a/apps/api/src/modules/recurring-invoices/recurring-invoices.service.ts b/apps/api/src/modules/recurring-invoices/recurring-invoices.service.ts
index e07c9d55..a8324242 100644
--- a/apps/api/src/modules/recurring-invoices/recurring-invoices.service.ts
+++ b/apps/api/src/modules/recurring-invoices/recurring-invoices.service.ts
@@ -2,6 +2,7 @@ import { Injectable, Logger } from '@nestjs/common';
 import { Prisma } from '@repo/db';
 import { PrismaService } from '@/infrastructure/prisma/prisma.service';
 import { TimelineService } from '@/modules/timeline/timeline.service';
+import { NotificationsService } from '@/modules/notifications/notifications.service';
 import { LeaseStatusService } from '@/common/lease-status/lease-status.service';
 import { LeaseStatus, RecurringInvoiceRunResponse } from '@repo/contracts';
 
@@ -27,6 +28,8 @@ export type RecurringLeaseInput = {
   /** Raw DB status ('draft' | 'active' | 'terminated' — 'expired' is derived, never stored). */
   status: string;
   rentAmount: Prisma.Decimal | number;
+  /** Keycloak sub of the tenant to notify when an invoice is auto-generated (F5.1); null if the renter has no linked portal user. */
+  renterUserId: string | null;
 };
 
 /**
@@ -43,6 +46,7 @@ export class RecurringInvoicesService {
   constructor(
     private readonly prisma: PrismaService,
     private readonly timeline: TimelineService,
+    private readonly notifications: NotificationsService,
     private readonly leaseStatus: LeaseStatusService,
   ) {}
 
@@ -161,6 +165,19 @@ export class RecurringInvoicesService {
         metadata: { leaseId: lease.id, billingPeriod },
       });
 
+      // F5.1: notify the tenant — system-generated, no actor. Skip silently
+      // when the renter has no linked portal user.
+      if (lease.renterUserId) {
+        await this.notifications.enqueue({
+          orgId: lease.orgId,
+          userId: lease.renterUserId,
+          type: 'invoice.issued',
+          title: 'New invoice issued',
+          body: `Your rent invoice for ${billingPeriod} has been issued, due ${candidate.toISOString().slice(0, 10)}.`,
+          data: { invoiceId: invoice.id, leaseId: lease.id, billingPeriod },
+        });
+      }
+
       return 'created';
     } catch (err) {
       if (
@@ -181,7 +198,7 @@ export class RecurringInvoicesService {
     orgId: string,
     asOf: Date = new Date(),
   ): Promise<RecurringInvoiceRunResponse> {
-    const leases = await this.prisma.lease.findMany({
+    const rawLeases = await this.prisma.lease.findMany({
       where: { orgId, status: 'active' },
       select: {
         id: true,
@@ -191,9 +208,24 @@ export class RecurringInvoicesService {
         endDate: true,
         status: true,
         rentAmount: true,
+        renter: { select: { renterUserId: true } },
       },
     });
 
+    // Flatten Renter.renterUserId onto the lease — RecurringLeaseInput stays
+    // DB-shape-agnostic (see its doc comment) so generateForLease's unit
+    // tests can keep hand-building plain fixtures.
+    const leases: RecurringLeaseInput[] = rawLeases.map((l) => ({
+      id: l.id,
+      orgId: l.orgId,
+      buildingId: l.buildingId,
+      startDate: l.startDate,
+      endDate: l.endDate,
+      status: l.status,
+      rentAmount: l.rentAmount,
+      renterUserId: l.renter?.renterUserId ?? null,
+    }));
+
     let generated = 0;
     let skippedExisting = 0;
     for (const lease of leases) {
diff --git a/apps/api/src/modules/timeline/timeline.service.spec.ts b/apps/api/src/modules/timeline/timeline.service.spec.ts
index 13460e0d..05e9b0ad 100644
--- a/apps/api/src/modules/timeline/timeline.service.spec.ts
+++ b/apps/api/src/modules/timeline/timeline.service.spec.ts
@@ -10,14 +10,26 @@ import { AuthenticatedUser } from '@/common/types/authenticated-user.type';
 describe('TimelineService', () => {
   const orgId = 'org-1';
 
-  function makeService(rows: unknown[] = [], total = 0) {
+  function makeService(
+    rows: unknown[] = [],
+    total = 0,
+    overrides: { keycloakAdmin?: Partial<Record<string, jest.Mock>> } = {},
+  ) {
     const prisma: any = {
       event: {
         findMany: jest.fn().mockResolvedValue(rows),
         count: jest.fn().mockResolvedValue(total),
       },
     };
-    return { service: new TimelineService(prisma), prisma };
+    const keycloakAdmin = {
+      getUser: jest.fn().mockResolvedValue(null),
+      ...overrides.keycloakAdmin,
+    };
+    return {
+      service: new TimelineService(prisma, keycloakAdmin as any),
+      prisma,
+      keycloakAdmin,
+    };
   }
 
   const caller = (roles: string[]): AuthenticatedUser =>
@@ -29,8 +41,116 @@ describe('TimelineService', () => {
 
     const result = await service.findForCaller(orgId, caller(['org_admin']), 1, 20);
 
-    expect(result).toEqual({ items: rows, total: 2, page: 1, limit: 20 });
-    expect(result.items).toEqual(rows);
+    expect(result).toEqual({
+      items: [
+        { id: 'evt-1', actorName: null },
+        { id: 'evt-2', actorName: null },
+      ],
+      total: 2,
+      page: 1,
+      limit: 20,
+    });
     expect(result).not.toHaveProperty('data');
   });
+
+  describe('actorName enrichment (F5.2)', () => {
+    it('resolves the actor name once for two events by the same actor (dedupe/cache)', async () => {
+      const rows = [
+        { id: 'evt-1', actorId: 'user-a' },
+        { id: 'evt-2', actorId: 'user-a' },
+      ];
+      const { service, keycloakAdmin } = makeService(rows, 2, {
+        keycloakAdmin: {
+          getUser: jest
+            .fn()
+            .mockResolvedValue({ firstName: 'Jane', lastName: 'Doe' }),
+        },
+      });
+
+      const result = await service.findForCaller(
+        orgId,
+        caller(['org_admin']),
+        1,
+        20,
+      );
+
+      expect(result.items).toEqual([
+        { id: 'evt-1', actorId: 'user-a', actorName: 'Jane Doe' },
+        { id: 'evt-2', actorId: 'user-a', actorName: 'Jane Doe' },
+      ]);
+      expect(keycloakAdmin.getUser).toHaveBeenCalledTimes(1);
+      expect(keycloakAdmin.getUser).toHaveBeenCalledWith('user-a');
+    });
+
+    it('caches a resolved actor name across separate findForCaller calls', async () => {
+      const rows = [{ id: 'evt-1', actorId: 'user-a' }];
+      const { service, keycloakAdmin } = makeService(rows, 1, {
+        keycloakAdmin: {
+          getUser: jest.fn().mockResolvedValue({ firstName: 'Jane' }),
+        },
+      });
+
+      await service.findForCaller(orgId, caller(['org_admin']), 1, 20);
+      await service.findForCaller(orgId, caller(['org_admin']), 1, 20);
+
+      expect(keycloakAdmin.getUser).toHaveBeenCalledTimes(1);
+    });
+
+    it('yields a null actorName for a system-generated event (null actorId)', async () => {
+      const rows = [{ id: 'evt-1', actorId: null }];
+      const { service, keycloakAdmin } = makeService(rows, 1);
+
+      const result = await service.findForCaller(
+        orgId,
+        caller(['org_admin']),
+        1,
+        20,
+      );
+
+      expect(result.items).toEqual([
+        { id: 'evt-1', actorId: null, actorName: null },
+      ]);
+      expect(keycloakAdmin.getUser).not.toHaveBeenCalled();
+    });
+
+    it('yields a null actorName (never throws) when the Keycloak lookup fails', async () => {
+      const rows = [{ id: 'evt-1', actorId: 'user-a' }];
+      const { service } = makeService(rows, 1, {
+        keycloakAdmin: {
+          getUser: jest.fn().mockRejectedValue(new Error('KC unreachable')),
+        },
+      });
+
+      const result = await service.findForCaller(
+        orgId,
+        caller(['org_admin']),
+        1,
+        20,
+      );
+
+      expect(result.items).toEqual([
+        { id: 'evt-1', actorId: 'user-a', actorName: null },
+      ]);
+    });
+
+    it('falls back to email when no first/last name is available', async () => {
+      const rows = [{ id: 'evt-1', actorId: 'user-a' }];
+      const { service } = makeService(rows, 1, {
+        keycloakAdmin: {
+          getUser: jest.fn().mockResolvedValue({ email: 'jane@example.com' }),
+        },
+      });
+
+      const result = await service.findForCaller(
+        orgId,
+        caller(['org_admin']),
+        1,
+        20,
+      );
+
+      expect(result.items[0]).toEqual(
+        expect.objectContaining({ actorName: 'jane@example.com' }),
+      );
+    });
+  });
 });
diff --git a/apps/api/src/modules/timeline/timeline.service.ts b/apps/api/src/modules/timeline/timeline.service.ts
index e0b3d330..596a80f7 100644
--- a/apps/api/src/modules/timeline/timeline.service.ts
+++ b/apps/api/src/modules/timeline/timeline.service.ts
@@ -3,6 +3,7 @@ import { PrismaService } from '@/infrastructure/prisma/prisma.service';
 import { Prisma } from '@repo/db';
 import { Role } from '@/common/enums';
 import { AuthenticatedUser } from '@/common/types/authenticated-user.type';
+import { KeycloakAdminService } from '@/infrastructure/keycloak/keycloak-admin.service';
 
 export interface EmitEventOptions {
   orgId: string;
@@ -13,11 +14,30 @@ export interface EmitEventOptions {
   metadata?: Record<string, unknown>;
 }
 
+/** F5.2: how long a resolved actor display name is cached before re-fetching. */
+const ACTOR_NAME_CACHE_TTL_MS = 5 * 60 * 1000;
+
+interface ActorNameCacheEntry {
+  name: string | null;
+  expiresAt: number;
+}
+
 @Injectable()
 export class TimelineService {
   private readonly logger = new Logger(TimelineService.name);
 
-  constructor(private readonly prisma: PrismaService) {}
+  /**
+   * F5.2: process-local cache of actorId (Keycloak sub) -> resolved display
+   * name, so the activity feed doesn't hit Keycloak once per event per
+   * request. Small TTL rather than forever, so a user's name change (rare)
+   * eventually shows up without a restart.
+   */
+  private readonly actorNameCache = new Map<string, ActorNameCacheEntry>();
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly keycloakAdmin: KeycloakAdminService,
+  ) {}
 
   async emit(options: EmitEventOptions): Promise<void> {
     try {
@@ -80,6 +100,81 @@ export class TimelineService {
       this.prisma.event.count({ where }),
     ]);
 
-    return { items, total, page, limit };
+    return {
+      items: await this.enrichWithActorNames(items),
+      total,
+      page,
+      limit,
+    };
+  }
+
+  /**
+   * F5.2: resolve each event's `actorId` (a Keycloak sub) to a display name
+   * for the activity feed's "who" column. Deduped per page (one KC lookup per
+   * distinct actor, not per event) and cached across requests; a null/missing
+   * actorId (system-generated event) or an unresolvable actor both yield a
+   * null `actorName` rather than throwing — the feed must always return.
+   */
+  private async enrichWithActorNames<
+    T extends { actorId?: string | null },
+  >(events: T[]): Promise<(T & { actorName: string | null })[]> {
+    const distinctActorIds = [
+      ...new Set(
+        events
+          .map((e) => e.actorId)
+          .filter((id): id is string => Boolean(id)),
+      ),
+    ];
+
+    const nameByActorId = new Map<string, string | null>();
+    await Promise.all(
+      distinctActorIds.map(async (actorId) => {
+        nameByActorId.set(actorId, await this.resolveActorName(actorId));
+      }),
+    );
+
+    return events.map((e) => ({
+      ...e,
+      actorName: e.actorId ? (nameByActorId.get(e.actorId) ?? null) : null,
+    }));
+  }
+
+  /** Resolve (and cache) a single actor's display name by Keycloak sub. */
+  private async resolveActorName(sub: string): Promise<string | null> {
+    const cached = this.actorNameCache.get(sub);
+    const now = Date.now();
+    if (cached && cached.expiresAt > now) {
+      return cached.name;
+    }
+
+    let name: string | null = null;
+    try {
+      const user = await this.keycloakAdmin.getUser(sub);
+      name = this.extractDisplayName(user);
+    } catch (error) {
+      // Never let a KC hiccup fail the whole feed — the event still renders,
+      // just without a resolved actor name.
+      this.logger.warn(`Failed to resolve actor name for ${sub}: ${String(error)}`);
+      name = null;
+    }
+
+    this.actorNameCache.set(sub, {
+      name,
+      expiresAt: now + ACTOR_NAME_CACHE_TTL_MS,
+    });
+    return name;
+  }
+
+  /** firstName + lastName, falling back to email, then null. */
+  private extractDisplayName(
+    user: Record<string, unknown> | null,
+  ): string | null {
+    if (!user) return null;
+    const firstName = typeof user.firstName === 'string' ? user.firstName : '';
+    const lastName = typeof user.lastName === 'string' ? user.lastName : '';
+    const fullName = [firstName, lastName].filter(Boolean).join(' ').trim();
+    if (fullName) return fullName;
+    const email = user.email;
+    return typeof email === 'string' && email.length > 0 ? email : null;
   }
 }
diff --git a/apps/api/src/modules/work-orders/work-orders.module.ts b/apps/api/src/modules/work-orders/work-orders.module.ts
index a67ec2c9..7042403d 100644
--- a/apps/api/src/modules/work-orders/work-orders.module.ts
+++ b/apps/api/src/modules/work-orders/work-orders.module.ts
@@ -3,8 +3,10 @@ import { WorkOrdersController } from './work-orders.controller';
 import { WorkOrdersOverviewController } from './work-orders-overview.controller';
 import { WorkOrdersService } from './work-orders.service';
 import { WorkOrderApartmentStatusService } from './work-order-apartment-status.service';
+import { NotificationsModule } from '@/modules/notifications/notifications.module';
 
 @Module({
+  imports: [NotificationsModule],
   controllers: [WorkOrdersController, WorkOrdersOverviewController],
   providers: [WorkOrdersService, WorkOrderApartmentStatusService],
   exports: [WorkOrdersService],
diff --git a/apps/api/src/modules/work-orders/work-orders.service.spec.ts b/apps/api/src/modules/work-orders/work-orders.service.spec.ts
index 2e4aafdc..246efa31 100644
--- a/apps/api/src/modules/work-orders/work-orders.service.spec.ts
+++ b/apps/api/src/modules/work-orders/work-orders.service.spec.ts
@@ -26,6 +26,7 @@ describe('WorkOrdersService', () => {
       buildingAccess?: Partial<Record<string, jest.Mock>>;
       leaseStatus?: Partial<Record<string, jest.Mock>>;
       workOrderApartmentStatus?: Partial<Record<string, jest.Mock>>;
+      notifications?: Partial<Record<string, jest.Mock>>;
     } = {},
   ) {
     const prisma: any = {
@@ -74,6 +75,10 @@ describe('WorkOrdersService', () => {
       ...overrides.buildingAccess,
     };
     const timeline = { emit: jest.fn().mockResolvedValue(undefined) };
+    const notifications = {
+      enqueue: jest.fn().mockResolvedValue(undefined),
+      ...overrides.notifications,
+    };
     const leaseStatus = {
       isEffectivelyActive: jest.fn().mockReturnValue(true),
       ...overrides.leaseStatus,
@@ -87,6 +92,7 @@ describe('WorkOrdersService', () => {
       prisma,
       buildingAccess as any,
       timeline as any,
+      notifications as any,
       leaseStatus as any,
       workOrderApartmentStatus as any,
     );
@@ -95,6 +101,7 @@ describe('WorkOrdersService', () => {
       prisma,
       buildingAccess,
       timeline,
+      notifications,
       leaseStatus,
       workOrderApartmentStatus,
     };
@@ -644,6 +651,58 @@ describe('WorkOrdersService', () => {
     });
   });
 
+  describe('create — assignment notification (F5.1)', () => {
+    it('notifies the assignee when a work order is created with assignedUserId set', async () => {
+      const { service, prisma, notifications } = makeService();
+      prisma.workOrder.create.mockResolvedValue(
+        workOrderRow({ vendorId: null, assignedUserId: 'user-1', number: 7 }),
+      );
+
+      await service.create(
+        orgId,
+        actorId,
+        Role.ORG_ADMIN,
+        maintenanceRequestId,
+        { assignedUserId: 'user-1' },
+      );
+
+      expect(notifications.enqueue).toHaveBeenCalledTimes(1);
+      expect(notifications.enqueue).toHaveBeenCalledWith(
+        expect.objectContaining({
+          orgId,
+          userId: 'user-1',
+          type: 'work_order.assigned',
+        }),
+      );
+    });
+
+    it('does not notify when the work order is created with a vendor instead of an assignee', async () => {
+      const { service, prisma, notifications } = makeService();
+      prisma.workOrder.create.mockResolvedValue(
+        workOrderRow({ vendorId: 'vendor-1', assignedUserId: null }),
+      );
+
+      await service.create(orgId, actorId, Role.ORG_ADMIN, maintenanceRequestId, {
+        vendorId: 'vendor-1',
+      });
+
+      expect(notifications.enqueue).not.toHaveBeenCalled();
+    });
+
+    it('does not notify when the actor assigns the work order to themself', async () => {
+      const { service, prisma, notifications } = makeService();
+      prisma.workOrder.create.mockResolvedValue(
+        workOrderRow({ vendorId: null, assignedUserId: actorId }),
+      );
+
+      await service.create(orgId, actorId, Role.ORG_ADMIN, maintenanceRequestId, {
+        assignedUserId: actorId,
+      });
+
+      expect(notifications.enqueue).not.toHaveBeenCalled();
+    });
+  });
+
   describe('update', () => {
     const existingRow = () => ({
       ...workOrderRow(),
@@ -844,6 +903,83 @@ describe('WorkOrdersService', () => {
     });
   });
 
+  describe('update — reassignment notification (F5.1)', () => {
+    const existingRow = () => ({
+      ...workOrderRow({ assignedUserId: 'user-old' }),
+      maintenanceRequest: { apartmentId, title: 'Leaking faucet' },
+    });
+
+    it('notifies the newly-assigned user on reassignment', async () => {
+      const { service, prisma, notifications } = makeService({
+        workOrder: { findFirst: jest.fn().mockResolvedValue(existingRow()) },
+      });
+      prisma.workOrder.update.mockResolvedValue(
+        workOrderRow({ vendorId: null, assignedUserId: 'user-new' }),
+      );
+
+      await service.update(
+        orgId,
+        actorId,
+        callerId,
+        Role.ORG_ADMIN,
+        maintenanceRequestId,
+        'wo-1',
+        { assignedUserId: 'user-new' },
+      );
+
+      expect(notifications.enqueue).toHaveBeenCalledTimes(1);
+      expect(notifications.enqueue).toHaveBeenCalledWith(
+        expect.objectContaining({
+          orgId,
+          userId: 'user-new',
+          type: 'work_order.assigned',
+        }),
+      );
+    });
+
+    it('does not notify when the assignee is unchanged', async () => {
+      const { service, prisma, notifications } = makeService({
+        workOrder: { findFirst: jest.fn().mockResolvedValue(existingRow()) },
+      });
+      prisma.workOrder.update.mockResolvedValue(
+        workOrderRow({ assignedUserId: 'user-old', status: 'in_progress' }),
+      );
+
+      await service.update(
+        orgId,
+        actorId,
+        callerId,
+        Role.ORG_ADMIN,
+        maintenanceRequestId,
+        'wo-1',
+        { status: 'in_progress' },
+      );
+
+      expect(notifications.enqueue).not.toHaveBeenCalled();
+    });
+
+    it('does not notify when the actor reassigns the work order to themself', async () => {
+      const { service, prisma, notifications } = makeService({
+        workOrder: { findFirst: jest.fn().mockResolvedValue(existingRow()) },
+      });
+      prisma.workOrder.update.mockResolvedValue(
+        workOrderRow({ vendorId: null, assignedUserId: actorId }),
+      );
+
+      await service.update(
+        orgId,
+        actorId,
+        callerId,
+        Role.ORG_ADMIN,
+        maintenanceRequestId,
+        'wo-1',
+        { assignedUserId: actorId },
+      );
+
+      expect(notifications.enqueue).not.toHaveBeenCalled();
+    });
+  });
+
   describe('update — tenant charge transition (F3.2)', () => {
     const existingInProgressWithCharge = () => ({
       ...workOrderRow({
diff --git a/apps/api/src/modules/work-orders/work-orders.service.ts b/apps/api/src/modules/work-orders/work-orders.service.ts
index fa7d01b2..c1b4642a 100644
--- a/apps/api/src/modules/work-orders/work-orders.service.ts
+++ b/apps/api/src/modules/work-orders/work-orders.service.ts
@@ -10,6 +10,7 @@ import { Prisma } from '@repo/db';
 import { PrismaService } from '@/infrastructure/prisma/prisma.service';
 import { BuildingAccessService } from '@/common/building-access/building-access.service';
 import { TimelineService } from '@/modules/timeline/timeline.service';
+import { NotificationsService } from '@/modules/notifications/notifications.service';
 import { LeaseStatusService } from '@/common/lease-status/lease-status.service';
 import { WorkOrderApartmentStatusService } from './work-order-apartment-status.service';
 import { Role } from '@/common/enums';
@@ -46,6 +47,7 @@ export class WorkOrdersService {
     private readonly prisma: PrismaService,
     private readonly buildingAccess: BuildingAccessService,
     private readonly timeline: TimelineService,
+    private readonly notifications: NotificationsService,
     private readonly leaseStatus: LeaseStatusService,
     private readonly workOrderApartmentStatus: WorkOrderApartmentStatusService,
   ) {}
@@ -312,6 +314,26 @@ export class WorkOrdersService {
       },
     });
 
+    // F5.1: notify the assignee — skip silently if there is none (vendor-
+    // assigned work orders have no in-app user to notify) or if the actor
+    // assigned it to themself.
+    if (workOrder.assignedUserId && workOrder.assignedUserId !== actorId) {
+      await this.notifications.enqueue({
+        orgId,
+        userId: workOrder.assignedUserId,
+        type: 'work_order.assigned',
+        title: 'You were assigned a work order',
+        body: `You've been assigned to work order ${formatWorkOrderNumber(workOrder.number)}: ${request.title}`,
+        data: {
+          workOrderId: workOrder.id,
+          maintenanceRequestId,
+          numberLabel: formatWorkOrderNumber(workOrder.number),
+        },
+      });
+    }
+    // TODO F5.1 follow-up: role-fanout notifications (e.g. maintenance-created
+    // -> supervisors) need a shared org-members-by-role helper — out of scope here.
+
     if (workOrder.status === 'completed') {
       await this.chargeTenantIfDue(
         orgId,
@@ -409,6 +431,17 @@ export class WorkOrdersService {
     const completingNow =
       dto.status === 'completed' && existing.status !== 'completed';
 
+    // F5.1: only notify when this update is a genuine reassignment TO a new
+    // user (not just re-affirming the existing assignee), and never notify
+    // the actor about assigning it to themself.
+    const newAssignee =
+      assigneeProvided &&
+      assignedUserId &&
+      assignedUserId !== existing.assignedUserId &&
+      assignedUserId !== actorId
+        ? assignedUserId
+        : null;
+
     const workOrder = await this.prisma.workOrder.update({
       where: { id: workOrderId },
       data: {
@@ -447,6 +480,21 @@ export class WorkOrdersService {
       metadata: { changes: Object.keys(dto) },
     });
 
+    if (newAssignee) {
+      await this.notifications.enqueue({
+        orgId,
+        userId: newAssignee,
+        type: 'work_order.assigned',
+        title: 'You were assigned a work order',
+        body: `You've been assigned to work order ${formatWorkOrderNumber(workOrder.number)}: ${existing.maintenanceRequest.title}`,
+        data: {
+          workOrderId: workOrder.id,
+          maintenanceRequestId,
+          numberLabel: formatWorkOrderNumber(workOrder.number),
+        },
+      });
+    }
+
     if (completingNow) {
       await this.chargeTenantIfDue(
         orgId,
diff --git a/apps/web/src/app/[lang]/dashboard/timeline/page.tsx b/apps/web/src/app/[lang]/dashboard/timeline/page.tsx
index 7a5b8730..ab89c0a0 100644
--- a/apps/web/src/app/[lang]/dashboard/timeline/page.tsx
+++ b/apps/web/src/app/[lang]/dashboard/timeline/page.tsx
@@ -4,6 +4,7 @@ import { requireSession } from '@/auth/guards';
 import { normalizeRole } from '@/auth/roles';
 import { canAccess } from '@/auth/permissions';
 import { isLocale } from '@/i18n/config';
+import { getDictionary } from '@/i18n/get-dictionary';
 import { TimelineFeed } from '@/components/dashboard/timeline-feed';
 
 export default async function TimelinePageRoute({
@@ -22,10 +23,12 @@ export default async function TimelinePageRoute({
     redirect(`/${locale}/dashboard`);
   }
 
+  const dict = await getDictionary(locale);
+
   return (
     <div>
-      <h1 className="text-2xl font-semibold mb-6">Activity</h1>
-      <TimelineFeed locale={locale} limit={20} />
+      <h1 className="text-2xl font-semibold mb-6">{dict.nav.timeline}</h1>
+      <TimelineFeed locale={locale} limit={20} dict={dict} />
     </div>
   );
 }
diff --git a/apps/web/src/components/dashboard/org-admin-dashboard.tsx b/apps/web/src/components/dashboard/org-admin-dashboard.tsx
index 3b59e85c..b756ffb0 100644
--- a/apps/web/src/components/dashboard/org-admin-dashboard.tsx
+++ b/apps/web/src/components/dashboard/org-admin-dashboard.tsx
@@ -230,7 +230,7 @@ export function OrgAdminDashboard({ me, locale, dict }: OrgAdminDashboardProps)
           <h2 className="text-sm font-semibold">{t.recentActivity}</h2>
         </div>
         <div className="rounded-xl border bg-card px-4 py-3">
-          <TimelineFeed locale={locale} limit={8} />
+          <TimelineFeed locale={locale} limit={8} dict={dict} />
         </div>
       </div>
     </div>
diff --git a/apps/web/src/components/dashboard/timeline-feed.tsx b/apps/web/src/components/dashboard/timeline-feed.tsx
index b320f57f..7a25bf73 100644
--- a/apps/web/src/components/dashboard/timeline-feed.tsx
+++ b/apps/web/src/components/dashboard/timeline-feed.tsx
@@ -6,6 +6,7 @@ import { ar } from 'date-fns/locale';
 import { Skeleton } from '@/components/ui/skeleton';
 import { Badge } from '@/components/ui/badge';
 import { useListTimelineQuery } from '@/store/api/endpoints/timeline.api';
+import type { Dictionary } from '@/i18n/get-dictionary';
 
 function humanizeAction(action: string): string {
   return action
@@ -17,9 +18,15 @@ function humanizeAction(action: string): string {
 interface TimelineFeedProps {
   locale: string;
   limit?: number;
+  /**
+   * Optional: callers that already hold the page dict should pass it so the
+   * "by {actor}" / "System" strings are localized. Falls back to English
+   * literals when omitted so existing callers keep compiling untouched.
+   */
+  dict?: Dictionary;
 }
 
-export function TimelineFeed({ locale, limit = 10 }: TimelineFeedProps) {
+export function TimelineFeed({ locale, limit = 10, dict }: TimelineFeedProps) {
   const { data, isLoading } = useListTimelineQuery({ limit });
 
   if (isLoading) {
@@ -59,6 +66,13 @@ export function TimelineFeed({ locale, limit = 10 }: TimelineFeedProps) {
         const metaEmail = typeof meta?.email === 'string' ? meta.email : null;
         const metaRole = typeof meta?.role === 'string' ? meta.role : null;
 
+        // Who did this: resolved KC display name, else the legacy metadata
+        // email some events still carry, else a neutral "System" label for
+        // system-generated events (e.g. auto-generated invoices).
+        const actorName = event.actorName ?? metaEmail;
+        const actorLabel = actorName ?? dict?.timeline?.system ?? 'System';
+        const byLabel = dict?.timeline?.by ?? 'by';
+
         return (
           <div key={event.id} className="flex gap-3">
             {/* Timeline spine */}
@@ -82,14 +96,20 @@ export function TimelineFeed({ locale, limit = 10 }: TimelineFeedProps) {
                 )}
               </div>
 
-              {(metaEmail || metaRole) && (
+              <p className="text-xs text-muted-foreground">
+                {byLabel}{' '}
+                <span
+                  className={actorName ? 'font-medium text-foreground' : undefined}
+                >
+                  {actorLabel}
+                </span>
+              </p>
+
+              {metaRole && (
                 <div className="flex flex-wrap gap-2 text-xs text-muted-foreground">
-                  {metaEmail && <span>{metaEmail}</span>}
-                  {metaRole && (
-                    <span className="capitalize">
-                      {String(metaRole).toLowerCase()}
-                    </span>
-                  )}
+                  <span className="capitalize">
+                    {String(metaRole).toLowerCase()}
+                  </span>
                 </div>
               )}
 
diff --git a/apps/web/src/i18n/dictionaries/ar.json b/apps/web/src/i18n/dictionaries/ar.json
index a9879dd8..081c979c 100644
--- a/apps/web/src/i18n/dictionaries/ar.json
+++ b/apps/web/src/i18n/dictionaries/ar.json
@@ -1390,5 +1390,9 @@
       "error": "تعذّر حذف المصروف. قد يكون مرتبطاً بعناصر أخرى."
     },
     "notBilledToTenantsNote": "المصاريف هي تكاليف منظمتك الخاصة (إصلاحات، دفعات للموردين، مرافق) — وليست فواتير تُرسل إلى المستأجرين. تُحصَّل مبالغ المستأجرين عبر الفواتير."
+  },
+  "timeline": {
+    "system": "النظام",
+    "by": "بواسطة"
   }
 }
diff --git a/apps/web/src/i18n/dictionaries/en.json b/apps/web/src/i18n/dictionaries/en.json
index 284d428c..228447ea 100644
--- a/apps/web/src/i18n/dictionaries/en.json
+++ b/apps/web/src/i18n/dictionaries/en.json
@@ -1390,5 +1390,9 @@
       "error": "Failed to delete expense. It may be referenced elsewhere."
     },
     "notBilledToTenantsNote": "Expenses are your organization's own costs (repairs, vendor payments, utilities) — they are not bills sent to tenants. Tenant charges are billed through invoices."
+  },
+  "timeline": {
+    "system": "System",
+    "by": "by"
   }
 }
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index ceef822e..44293913 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -184,6 +184,9 @@ export type TimelineEvent = {
   id: string;
   orgId: string;
   actorId?: string | null;
+  /** F5.2: the actor's resolved display name (Keycloak), or null for
+   * system-generated events / unresolvable actors. Rendered as the "who". */
+  actorName?: string | null;
   action: string;
   targetType?: string | null;
   targetId?: string | null;

From bd1fee8e45fc49d56076da42b18c9712dc57325e Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 04:35:21 +0300
Subject: [PATCH 08/11] =?UTF-8?q?feat(F6):=20tenant=20experience=20&=20pro?=
 =?UTF-8?q?file=20=E2=80=94=20profile=20page=20+=20renter=20"available=20u?=
 =?UTF-8?q?nits"=20showcase?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sprint F6 (final) of the Property Manager behavior roadmap (workflows W10/W11).
No migration.

F6.1 [Q33] Profile page. New /{lang}/dashboard/profile (requireSession, any role)
  showing the signed-in identity (name, email, localized role, org name + status,
  reusing the existing role/status label maps) + a "Manage account" link to the
  Keycloak account console (password/2FA). A "Profile" item was added to the
  topbar user dropdown. Fixes the partner's "profile couldn't load" (there was no
  /profile route).

F6.2 [Q5] Renter apartment showcase (foundational slice; the full inquiry/
  application flow remains a documented v2 follow-up). New GET /available-units
  (org-scoped vacant apartments, all member roles incl. tenant, no
  building-access filter) → AvailableUnit[]. New "Available units" page + sidebar
  nav (permission area availableUnits: tenant full, others readonly). Per-unit
  "Express interest" reuses the existing support-ticket create flow (no new data
  model) to open a lead ticket referencing the unit.

i18n parity en==ar 1081. Verified: api build EXIT 0 + full jest 335 pass/4 skip
(incl. 3 available-units); web check-types clean, vitest 30/30, next build EXIT 0
(both new routes registered).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/api/src/app.module.ts                    |   2 +
 .../available-units.controller.ts             |  38 ++++
 .../available-units/available-units.module.ts |   9 +
 .../available-units.service.spec.ts           |  83 +++++++++
 .../available-units.service.ts                |  57 ++++++
 .../[lang]/dashboard/available-units/page.tsx |  28 +++
 .../src/app/[lang]/dashboard/profile/page.tsx | 111 +++++++++++
 apps/web/src/app/api/available-units/route.ts |   5 +
 apps/web/src/auth/permissions.ts              |  14 +-
 .../dashboard/available-units-page.tsx        | 172 ++++++++++++++++++
 .../components/layout/dashboard-sidebar.tsx   |   8 +
 .../components/layout/dashboard-topbar.tsx    |   9 +-
 apps/web/src/i18n/dictionaries/ar.json        |  35 +++-
 apps/web/src/i18n/dictionaries/en.json        |  35 +++-
 .../api/endpoints/available-units.api.ts      |  37 ++++
 apps/web/src/store/api/endpoints/index.ts     |   1 +
 apps/web/src/store/api/tag-types.ts           |   1 +
 packages/contracts/src/index.ts               |  21 +++
 18 files changed, 662 insertions(+), 4 deletions(-)
 create mode 100644 apps/api/src/modules/available-units/available-units.controller.ts
 create mode 100644 apps/api/src/modules/available-units/available-units.module.ts
 create mode 100644 apps/api/src/modules/available-units/available-units.service.spec.ts
 create mode 100644 apps/api/src/modules/available-units/available-units.service.ts
 create mode 100644 apps/web/src/app/[lang]/dashboard/available-units/page.tsx
 create mode 100644 apps/web/src/app/[lang]/dashboard/profile/page.tsx
 create mode 100644 apps/web/src/app/api/available-units/route.ts
 create mode 100644 apps/web/src/components/dashboard/available-units-page.tsx
 create mode 100644 apps/web/src/store/api/endpoints/available-units.api.ts

diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts
index 4b796bbb..d00c8c7b 100644
--- a/apps/api/src/app.module.ts
+++ b/apps/api/src/app.module.ts
@@ -46,6 +46,7 @@ import { ReportsModule } from '@/modules/reports/reports.module';
 import { TenantModule } from '@/modules/tenant/tenant.module';
 import { RecurringInvoicesModule } from '@/modules/recurring-invoices/recurring-invoices.module';
 import { ApartmentStatusSweepModule } from '@/modules/apartment-status-sweep/apartment-status-sweep.module';
+import { AvailableUnitsModule } from '@/modules/available-units/available-units.module';
 
 @Module({
   imports: [
@@ -114,6 +115,7 @@ import { ApartmentStatusSweepModule } from '@/modules/apartment-status-sweep/apa
     TenantModule,
     RecurringInvoicesModule,
     ApartmentStatusSweepModule,
+    AvailableUnitsModule,
   ],
   providers: [
     { provide: APP_GUARD, useClass: ThrottlerGuard },
diff --git a/apps/api/src/modules/available-units/available-units.controller.ts b/apps/api/src/modules/available-units/available-units.controller.ts
new file mode 100644
index 00000000..021964fa
--- /dev/null
+++ b/apps/api/src/modules/available-units/available-units.controller.ts
@@ -0,0 +1,38 @@
+import { Controller, Get } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { AvailableUnitsService } from './available-units.service';
+import { OrgScopeService } from '@/common/org-scope/org-scope.service';
+import { CurrentUser, Roles } from '@/common/decorators';
+import { AuthenticatedUser } from '@/common/types/authenticated-user.type';
+import { Role } from '@/common/enums';
+
+/**
+ * F6.2 — org-wide, read-only "Available units" showcase for prospective
+ * renters. A separate top-level controller (mirrors LeasesOverviewController
+ * / WorkOrdersOverviewController), not nested under buildings, since it lists
+ * vacant apartments across the whole org rather than a single building.
+ * Every member role — including TENANT — can view it; prospective tenants
+ * express interest via a support ticket rather than an action here.
+ */
+@ApiTags('available-units')
+@ApiBearerAuth()
+@Controller('available-units')
+export class AvailableUnitsController {
+  constructor(
+    private readonly availableUnitsService: AvailableUnitsService,
+    private readonly orgScope: OrgScopeService,
+  ) {}
+
+  @Roles(
+    Role.ORG_ADMIN,
+    Role.SUPERVISOR,
+    Role.FINANCE,
+    Role.MAINTENANCE,
+    Role.TENANT,
+  )
+  @Get()
+  async getAvailableUnits(@CurrentUser() user: AuthenticatedUser) {
+    const { orgId } = await this.orgScope.resolveForCaller(user);
+    return this.availableUnitsService.findAvailable(orgId);
+  }
+}
diff --git a/apps/api/src/modules/available-units/available-units.module.ts b/apps/api/src/modules/available-units/available-units.module.ts
new file mode 100644
index 00000000..65ba87cc
--- /dev/null
+++ b/apps/api/src/modules/available-units/available-units.module.ts
@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { AvailableUnitsController } from './available-units.controller';
+import { AvailableUnitsService } from './available-units.service';
+
+@Module({
+  controllers: [AvailableUnitsController],
+  providers: [AvailableUnitsService],
+})
+export class AvailableUnitsModule {}
diff --git a/apps/api/src/modules/available-units/available-units.service.spec.ts b/apps/api/src/modules/available-units/available-units.service.spec.ts
new file mode 100644
index 00000000..ab1db722
--- /dev/null
+++ b/apps/api/src/modules/available-units/available-units.service.spec.ts
@@ -0,0 +1,83 @@
+import { AvailableUnitsService } from './available-units.service';
+
+describe('AvailableUnitsService', () => {
+  const orgId = 'org-1';
+
+  function makeService(
+    overrides: {
+      apartment?: Partial<Record<string, jest.Mock>>;
+    } = {},
+  ) {
+    const prisma: any = {
+      apartment: {
+        findMany: jest.fn().mockResolvedValue([]),
+        ...overrides.apartment,
+      },
+    };
+    const service = new AvailableUnitsService(prisma);
+    return { service, prisma };
+  }
+
+  describe('findAvailable', () => {
+    it('scopes the query to the org and vacant apartments only, ordered by building then unit number', async () => {
+      const { service, prisma } = makeService();
+
+      await service.findAvailable(orgId);
+
+      expect(prisma.apartment.findMany).toHaveBeenCalledWith({
+        where: { orgId, status: 'vacant' },
+        include: {
+          building: { select: { name: true } },
+          floor: { select: { name: true } },
+        },
+        orderBy: [{ building: { name: 'asc' } }, { unitNumber: 'asc' }],
+      });
+    });
+
+    it('maps each vacant apartment to an AvailableUnit enriched with building/floor names', async () => {
+      const { service } = makeService({
+        apartment: {
+          findMany: jest.fn().mockResolvedValue([
+            {
+              id: 'apt-1',
+              buildingId: 'building-1',
+              floorId: 'floor-1',
+              unitNumber: '101',
+              bedrooms: 2,
+              bathrooms: { toString: () => '1.5' },
+              sqft: 850,
+              building: { name: 'Sunrise Tower' },
+              floor: { name: 'Ground Floor' },
+            },
+          ]),
+        },
+      });
+
+      const result = await service.findAvailable(orgId);
+
+      expect(result).toEqual({
+        data: [
+          {
+            id: 'apt-1',
+            buildingId: 'building-1',
+            buildingName: 'Sunrise Tower',
+            floorId: 'floor-1',
+            floorName: 'Ground Floor',
+            unitNumber: '101',
+            bedrooms: 2,
+            bathrooms: '1.5',
+            sqft: 850,
+          },
+        ],
+      });
+    });
+
+    it('returns an empty list when the org has no vacant apartments', async () => {
+      const { service } = makeService();
+
+      const result = await service.findAvailable(orgId);
+
+      expect(result).toEqual({ data: [] });
+    });
+  });
+});
diff --git a/apps/api/src/modules/available-units/available-units.service.ts b/apps/api/src/modules/available-units/available-units.service.ts
new file mode 100644
index 00000000..2578d713
--- /dev/null
+++ b/apps/api/src/modules/available-units/available-units.service.ts
@@ -0,0 +1,57 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@repo/db';
+import { PrismaService } from '@/infrastructure/prisma/prisma.service';
+import { AvailableUnit, AvailableUnitListResponse } from '@repo/contracts';
+
+@Injectable()
+export class AvailableUnitsService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  // ── Format helpers ────────────────────────────────────────────────────────
+
+  private formatAvailableUnit(apartment: {
+    id: string;
+    buildingId: string;
+    floorId: string;
+    unitNumber: string;
+    bedrooms: number;
+    bathrooms: Prisma.Decimal;
+    sqft: number | null;
+    building: { name: string };
+    floor: { name: string };
+  }): AvailableUnit {
+    return {
+      id: apartment.id,
+      buildingId: apartment.buildingId,
+      buildingName: apartment.building.name,
+      floorId: apartment.floorId,
+      floorName: apartment.floor.name,
+      unitNumber: apartment.unitNumber,
+      bedrooms: apartment.bedrooms,
+      bathrooms: apartment.bathrooms.toString(),
+      sqft: apartment.sqft,
+    };
+  }
+
+  // ── Reads ─────────────────────────────────────────────────────────────────
+
+  /**
+   * F6.2 — every vacant apartment in the org, enriched with building/floor
+   * names for the renter-facing "Available units" showcase. Deliberately NOT
+   * building-access scoped like the nested apartments/leases reads: a tenant
+   * isn't building-assigned, and this showcase is meant to surface every
+   * vacant unit org-wide, not just the caller's assigned buildings.
+   */
+  async findAvailable(orgId: string): Promise<AvailableUnitListResponse> {
+    const apartments = await this.prisma.apartment.findMany({
+      where: { orgId, status: 'vacant' },
+      include: {
+        building: { select: { name: true } },
+        floor: { select: { name: true } },
+      },
+      orderBy: [{ building: { name: 'asc' } }, { unitNumber: 'asc' }],
+    });
+
+    return { data: apartments.map((a) => this.formatAvailableUnit(a)) };
+  }
+}
diff --git a/apps/web/src/app/[lang]/dashboard/available-units/page.tsx b/apps/web/src/app/[lang]/dashboard/available-units/page.tsx
new file mode 100644
index 00000000..949d5d14
--- /dev/null
+++ b/apps/web/src/app/[lang]/dashboard/available-units/page.tsx
@@ -0,0 +1,28 @@
+import { requireSession } from '@/auth/guards';
+import { normalizeRole } from '@/auth/roles';
+import { canAccess } from '@/auth/permissions';
+import { redirect } from 'next/navigation';
+import { isLocale } from '@/i18n/config';
+import { getDictionary } from '@/i18n/get-dictionary';
+import { AvailableUnitsPage } from '@/components/dashboard/available-units-page';
+
+export default async function AvailableUnitsPageRoute({
+  params,
+}: {
+  params: Promise<{ lang: string }>;
+}) {
+  const { lang } = await params;
+  const locale = isLocale(lang) ? lang : 'en';
+  const session = await requireSession({ locale });
+  const role = normalizeRole(session.role ?? session.user?.role);
+
+  if (!canAccess(role, 'availableUnits')) {
+    // Match the sibling dashboard pages (buildings/invoices/leases/…), which
+    // bounce an unauthorized role back to their own dashboard home.
+    redirect(`/${locale}/dashboard`);
+  }
+
+  const dict = await getDictionary(locale);
+
+  return <AvailableUnitsPage locale={locale} dict={dict} />;
+}
diff --git a/apps/web/src/app/[lang]/dashboard/profile/page.tsx b/apps/web/src/app/[lang]/dashboard/profile/page.tsx
new file mode 100644
index 00000000..d1d5224d
--- /dev/null
+++ b/apps/web/src/app/[lang]/dashboard/profile/page.tsx
@@ -0,0 +1,111 @@
+import { UserIcon, ExternalLinkIcon } from 'lucide-react';
+
+import { requireSession } from '@/auth/guards';
+import { normalizeRole } from '@/auth/roles';
+import { isLocale } from '@/i18n/config';
+import { getDictionary } from '@/i18n/get-dictionary';
+import { serverEnv } from '@/lib/env';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import type { MeResponse } from '@/types/api';
+
+async function fetchMe(accessToken: string): Promise<MeResponse | null> {
+  try {
+    const res = await fetch(`${serverEnv.API_URL}/me`, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+      cache: 'no-store',
+    });
+    if (!res.ok) return null;
+    const json = (await res.json()) as MeResponse | { data: MeResponse };
+    return 'data' in json ? json.data : json;
+  } catch {
+    return null;
+  }
+}
+
+export default async function ProfilePage({
+  params,
+}: {
+  params: Promise<{ lang: string }>;
+}) {
+  const { lang } = await params;
+  const locale = isLocale(lang) ? lang : 'en';
+  const dict = await getDictionary(locale);
+  const t = dict.profile;
+
+  // Any authenticated role may view their own profile — no role gate here.
+  // proxy.ts intentionally excludes /dashboard/profile from its permission
+  // matrix, so this requireSession() call is the sole guard for this page.
+  const session = await requireSession({ locale });
+
+  let me: MeResponse | null = null;
+  if (session.accessToken) {
+    me = await fetchMe(session.accessToken);
+  }
+
+  const name = me?.user?.fullName ?? session.user?.name ?? '—';
+  const email = me?.user?.email ?? session.user?.email ?? '—';
+  const role = normalizeRole(me?.role ?? session.role ?? session.user?.role);
+  const roleLabel = role ? dict.auth.roles[role] : '—';
+  const orgName = me?.org?.name ?? '—';
+  const orgStatus = me?.org?.status;
+  const orgStatusLabel = orgStatus ? dict.billing.status[orgStatus] : null;
+
+  const accountUrl = `${serverEnv.KEYCLOAK_BASE}/realms/${serverEnv.KEYCLOAK_REALM}/account`;
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h1 className="flex items-center gap-2 text-2xl font-semibold tracking-tight">
+          <UserIcon className="size-6 text-muted-foreground" />
+          {t.title}
+        </h1>
+        <p className="mt-0.5 text-sm text-muted-foreground">{t.subtitle}</p>
+      </div>
+
+      <div className="grid grid-cols-1 gap-6 rounded-xl border bg-card p-6 sm:grid-cols-2">
+        <div className="flex flex-col gap-1">
+          <p className="text-xs text-muted-foreground">{t.name}</p>
+          <p className="text-sm">{name}</p>
+        </div>
+        <div className="flex flex-col gap-1">
+          <p className="text-xs text-muted-foreground">{t.email}</p>
+          <p className="text-sm">{email}</p>
+        </div>
+        <div className="flex flex-col gap-1">
+          <p className="text-xs text-muted-foreground">{t.role}</p>
+          <p className="text-sm">{roleLabel}</p>
+        </div>
+        <div className="flex flex-col gap-1">
+          <p className="text-xs text-muted-foreground">{t.organization}</p>
+          <div className="flex items-center gap-2">
+            <p className="text-sm">{orgName}</p>
+            {orgStatusLabel && (
+              <Badge variant="outline" className="text-xs">
+                {orgStatusLabel}
+              </Badge>
+            )}
+          </div>
+        </div>
+      </div>
+
+      <div className="flex flex-col gap-3 rounded-xl border bg-card p-6 sm:flex-row sm:items-center sm:justify-between">
+        <div className="max-w-md">
+          <h2 className="text-sm font-medium text-foreground">
+            {t.manageAccount}
+          </h2>
+          <p className="mt-0.5 text-xs text-muted-foreground">
+            {t.manageAccountHint}
+          </p>
+        </div>
+        <Button
+          variant="outline"
+          render={<a href={accountUrl} target="_blank" rel="noreferrer" />}
+        >
+          {t.manageAccount}
+          <ExternalLinkIcon />
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/api/available-units/route.ts b/apps/web/src/app/api/available-units/route.ts
new file mode 100644
index 00000000..08924c44
--- /dev/null
+++ b/apps/web/src/app/api/available-units/route.ts
@@ -0,0 +1,5 @@
+import { forwardRoute } from '@/lib/api/forward';
+
+export const runtime = 'nodejs';
+
+export const GET = forwardRoute('/available-units');
diff --git a/apps/web/src/auth/permissions.ts b/apps/web/src/auth/permissions.ts
index 41f7cc9c..9f7dee42 100644
--- a/apps/web/src/auth/permissions.ts
+++ b/apps/web/src/auth/permissions.ts
@@ -29,6 +29,10 @@
  *   "notifications" → /dashboard/notifications (a personal inbox, like the
  *                   header bell — every role gets 'full', there is no
  *                   restricted view of someone else's notifications)
+ *   "availableUnits" → /dashboard/available-units (F6.2 — renter-facing vacant
+ *                   units showcase; tenant gets 'full' since expressing
+ *                   interest — via a support ticket — is the whole point of
+ *                   the page for them; staff roles get 'readonly' visibility)
  */
 
 import type { Role } from '@/auth/roles';
@@ -47,7 +51,8 @@ export type DashboardArea =
   | 'invoices'
   | 'support'
   | 'leases'
-  | 'notifications';
+  | 'notifications'
+  | 'availableUnits';
 
 /**
  * Per-role access level for an area.
@@ -75,6 +80,7 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'full',
     leases: 'full',
     notifications: 'full',
+    availableUnits: 'readonly',
   },
   supervisor: {
     dashboard: 'readonly',
@@ -91,6 +97,7 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'full',
     leases: 'readonly',
     notifications: 'full',
+    availableUnits: 'readonly',
   },
   finance: {
     dashboard: 'readonly',
@@ -107,6 +114,7 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'readonly',
     leases: 'readonly',
     notifications: 'full',
+    availableUnits: 'readonly',
   },
   maintenance: {
     dashboard: 'readonly',
@@ -123,6 +131,7 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'readonly',
     leases: 'readonly',
     notifications: 'full',
+    availableUnits: 'readonly',
   },
   tenant: {
     dashboard: 'readonly',
@@ -142,6 +151,9 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'readonly',
     leases: 'none',
     notifications: 'full',
+    // full = this page IS the tenant's flow (browse vacant units → express
+    // interest via a support ticket); there's no write action to restrict.
+    availableUnits: 'full',
   },
 };
 
diff --git a/apps/web/src/components/dashboard/available-units-page.tsx b/apps/web/src/components/dashboard/available-units-page.tsx
new file mode 100644
index 00000000..adf2d8ad
--- /dev/null
+++ b/apps/web/src/components/dashboard/available-units-page.tsx
@@ -0,0 +1,172 @@
+'use client';
+
+import { toast } from 'sonner';
+import { BedDoubleIcon, HomeIcon, KeyRoundIcon, MapPinIcon } from 'lucide-react';
+
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+} from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Skeleton } from '@/components/ui/skeleton';
+
+import { useGetAvailableUnitsQuery } from '@/store/api/endpoints/available-units.api';
+import { useCreateSupportTicketMutation } from '@/store/api/endpoints/support-tickets.api';
+import type { AvailableUnit } from '@/types/api';
+import type { Dictionary } from '@/i18n/get-dictionary';
+
+// ── Express-interest button ──────────────────────────────────────────────────
+// Reuses the existing support-ticket create flow — no new data model. Each
+// card owns its own mutation instance so the "submitting" state (and
+// disabled button) is scoped to that one unit, not the whole page.
+
+function fillTemplate(
+  template: string,
+  values: Record<string, string>,
+): string {
+  return Object.entries(values).reduce(
+    (acc, [key, value]) => acc.replaceAll(`{${key}}`, value),
+    template,
+  );
+}
+
+function UnitCard({
+  unit,
+  t,
+}: {
+  unit: AvailableUnit;
+  t: Dictionary['availableUnits'];
+}) {
+  const [createSupportTicket, { isLoading: submitting }] =
+    useCreateSupportTicketMutation();
+
+  async function handleExpressInterest() {
+    const templateValues = {
+      building: unit.buildingName,
+      unit: unit.unitNumber,
+      floor: unit.floorName,
+      bedrooms: String(unit.bedrooms),
+      bathrooms: unit.bathrooms,
+    };
+    try {
+      await createSupportTicket({
+        subject: fillTemplate(t.interestSubjectTemplate, templateValues),
+        description: fillTemplate(t.interestDescriptionTemplate, templateValues),
+        category: 'general',
+      }).unwrap();
+      toast.success(t.interestSubmitted);
+    } catch {
+      toast.error(t.interestError);
+    }
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-1.5">
+          <KeyRoundIcon className="size-4 text-teal-600" />
+          {t.table.unit} {unit.unitNumber}
+        </CardTitle>
+        <CardDescription className="flex items-center gap-1.5">
+          <MapPinIcon className="size-3.5 shrink-0" />
+          {unit.buildingName} · {unit.floorName}
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <div className="grid grid-cols-3 gap-3 text-center">
+          <div className="flex flex-col items-center gap-1 rounded-lg bg-muted/50 py-2">
+            <BedDoubleIcon className="size-4 text-muted-foreground" />
+            <span className="text-sm font-medium">{unit.bedrooms}</span>
+            <span className="text-[11px] text-muted-foreground">
+              {t.table.bedrooms}
+            </span>
+          </div>
+          <div className="flex flex-col items-center gap-1 rounded-lg bg-muted/50 py-2">
+            <HomeIcon className="size-4 text-muted-foreground" />
+            <span className="text-sm font-medium">{unit.bathrooms}</span>
+            <span className="text-[11px] text-muted-foreground">
+              {t.table.bathrooms}
+            </span>
+          </div>
+          <div className="flex flex-col items-center gap-1 rounded-lg bg-muted/50 py-2">
+            <span className="text-sm font-medium">{unit.sqft ?? '—'}</span>
+            <span className="text-[11px] text-muted-foreground">
+              {t.table.sqft}
+            </span>
+          </div>
+        </div>
+      </CardContent>
+      <CardFooter>
+        <Button
+          className="w-full"
+          onClick={handleExpressInterest}
+          disabled={submitting}
+        >
+          {submitting ? t.submitting : t.expressInterest}
+        </Button>
+      </CardFooter>
+    </Card>
+  );
+}
+
+// ── Main component ────────────────────────────────────────────────────────────
+
+interface AvailableUnitsPageProps {
+  locale: string;
+  dict: Dictionary;
+}
+
+export function AvailableUnitsPage({ dict }: AvailableUnitsPageProps) {
+  const t = dict.availableUnits;
+  const { data: units, isLoading, isError } = useGetAvailableUnitsQuery();
+
+  const hasUnits = (units?.length ?? 0) > 0;
+
+  return (
+    <div className="flex flex-col gap-6">
+      {/* Header */}
+      <div>
+        <h1 className="text-2xl font-semibold tracking-tight">{t.title}</h1>
+        <p className="text-sm text-muted-foreground mt-0.5">{t.subtitle}</p>
+      </div>
+
+      {isLoading ? (
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {[...Array(6)].map((_, i) => (
+            <Card key={i}>
+              <CardHeader>
+                <Skeleton className="h-5 w-32" />
+                <Skeleton className="h-4 w-40" />
+              </CardHeader>
+              <CardContent>
+                <Skeleton className="h-16 w-full" />
+              </CardContent>
+              <CardFooter>
+                <Skeleton className="h-9 w-full" />
+              </CardFooter>
+            </Card>
+          ))}
+        </div>
+      ) : isError ? (
+        <div className="rounded-xl border bg-card p-10 text-center text-sm text-muted-foreground">
+          {t.loadError}
+        </div>
+      ) : !hasUnits ? (
+        <div className="rounded-xl border bg-card p-10 text-center text-muted-foreground">
+          <HomeIcon className="size-8 mx-auto mb-2 opacity-30" />
+          {t.empty}
+        </div>
+      ) : (
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {units?.map((unit) => (
+            <UnitCard key={unit.id} unit={unit} t={t} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/layout/dashboard-sidebar.tsx b/apps/web/src/components/layout/dashboard-sidebar.tsx
index 809338e7..3464e823 100644
--- a/apps/web/src/components/layout/dashboard-sidebar.tsx
+++ b/apps/web/src/components/layout/dashboard-sidebar.tsx
@@ -23,6 +23,7 @@ import {
   LifeBuoy,
   ScrollText,
   Bell,
+  KeyRound,
 } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
@@ -93,6 +94,13 @@ function buildNavItems(
       href: `/${locale}/dashboard/leases`,
       areaKey: 'leases',
     },
+    {
+      key: 'availableUnits',
+      label: dict.nav.availableUnits,
+      icon: KeyRound,
+      href: `/${locale}/dashboard/available-units`,
+      areaKey: 'availableUnits',
+    },
     {
       key: 'vendors',
       label: dict.nav.vendors,
diff --git a/apps/web/src/components/layout/dashboard-topbar.tsx b/apps/web/src/components/layout/dashboard-topbar.tsx
index 47a553d8..570d5ec6 100644
--- a/apps/web/src/components/layout/dashboard-topbar.tsx
+++ b/apps/web/src/components/layout/dashboard-topbar.tsx
@@ -1,7 +1,8 @@
 'use client';
 
+import Link from 'next/link';
 import { usePathname } from 'next/navigation';
-import { Sun, Moon } from 'lucide-react';
+import { Sun, Moon, UserIcon } from 'lucide-react';
 import { useTheme } from 'next-themes';
 import { federatedLogout } from '@/auth/federated-logout';
 
@@ -55,6 +56,7 @@ const PAGE_TITLE_MAP: Record<string, string> = {
   timeline: 'timeline',
   support: 'support',
   notifications: 'notifications',
+  profile: 'profile',
 };
 
 function usePageTitle(dict: Dictionary): string {
@@ -134,6 +136,11 @@ function UserDropdown({
           </p>
         </DropdownMenuLabel>
         <DropdownMenuSeparator />
+        <DropdownMenuItem render={<Link href={`/${locale}/dashboard/profile`} />}>
+          <UserIcon />
+          {dict.nav.profile}
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
         <DropdownMenuItem
           variant="destructive"
           onClick={() => federatedLogout(locale)}
diff --git a/apps/web/src/i18n/dictionaries/ar.json b/apps/web/src/i18n/dictionaries/ar.json
index 081c979c..c458a8b0 100644
--- a/apps/web/src/i18n/dictionaries/ar.json
+++ b/apps/web/src/i18n/dictionaries/ar.json
@@ -25,7 +25,9 @@
     "language": "اللغة",
     "role": "الدور",
     "menu": "فتح القائمة",
-    "close": "إغلاق"
+    "close": "إغلاق",
+    "profile": "الملف الشخصي",
+    "availableUnits": "الوحدات المتاحة"
   },
   "auth": {
     "signIn": "تسجيل الدخول",
@@ -1394,5 +1396,36 @@
   "timeline": {
     "system": "النظام",
     "by": "بواسطة"
+  },
+  "profile": {
+    "title": "الملف الشخصي",
+    "subtitle": "بيانات حسابك ومنظمتك.",
+    "name": "الاسم الكامل",
+    "email": "البريد الإلكتروني",
+    "role": "الدور",
+    "organization": "المنظمة",
+    "status": "الحالة",
+    "manageAccount": "إدارة الحساب",
+    "manageAccountHint": "حدّث كلمة المرور، وفعّل التحقق بخطوتين، وأدر إعدادات أمان حسابك."
+  },
+  "availableUnits": {
+    "title": "الوحدات المتاحة",
+    "subtitle": "تصفّح الوحدات الشاغرة وأخبرنا باهتمامك — سيتواصل فريقنا معك.",
+    "empty": "لا توجد وحدات متاحة حالياً. تحقق مرة أخرى قريباً.",
+    "loadError": "تعذّر تحميل الوحدات المتاحة. يرجى المحاولة مرة أخرى.",
+    "table": {
+      "building": "المبنى",
+      "unit": "الوحدة",
+      "floor": "الطابق",
+      "bedrooms": "غرف النوم",
+      "bathrooms": "الحمامات",
+      "sqft": "المساحة (قدم مربع)"
+    },
+    "expressInterest": "إبداء الاهتمام",
+    "submitting": "جارٍ الإرسال…",
+    "interestSubmitted": "تم إرسال طلب الاهتمام — سيتواصل فريقنا معك قريباً.",
+    "interestError": "تعذّر إرسال طلب الاهتمام. يرجى المحاولة مرة أخرى.",
+    "interestSubjectTemplate": "اهتمام بـ {building} · الوحدة {unit}",
+    "interestDescriptionTemplate": "أنا مهتم بالوحدة {unit} ({bedrooms} غرفة / {bathrooms} حمام) في {building}، {floor}. يرجى التواصل لمزيد من التفاصيل."
   }
 }
diff --git a/apps/web/src/i18n/dictionaries/en.json b/apps/web/src/i18n/dictionaries/en.json
index 228447ea..7f58b2bc 100644
--- a/apps/web/src/i18n/dictionaries/en.json
+++ b/apps/web/src/i18n/dictionaries/en.json
@@ -25,7 +25,9 @@
     "language": "Language",
     "role": "Role",
     "menu": "Open menu",
-    "close": "Close"
+    "close": "Close",
+    "profile": "Profile",
+    "availableUnits": "Available Units"
   },
   "auth": {
     "signIn": "Sign in",
@@ -1394,5 +1396,36 @@
   "timeline": {
     "system": "System",
     "by": "by"
+  },
+  "profile": {
+    "title": "Profile",
+    "subtitle": "Your account details and organization.",
+    "name": "Full name",
+    "email": "Email",
+    "role": "Role",
+    "organization": "Organization",
+    "status": "Status",
+    "manageAccount": "Manage account",
+    "manageAccountHint": "Update your password, enable two-factor authentication, and manage your account security."
+  },
+  "availableUnits": {
+    "title": "Available Units",
+    "subtitle": "Browse vacant units and let us know if you're interested — our team will follow up.",
+    "empty": "No units are available right now. Check back soon.",
+    "loadError": "Failed to load available units. Please try again.",
+    "table": {
+      "building": "Building",
+      "unit": "Unit",
+      "floor": "Floor",
+      "bedrooms": "Bedrooms",
+      "bathrooms": "Bathrooms",
+      "sqft": "Sqft"
+    },
+    "expressInterest": "Express interest",
+    "submitting": "Submitting…",
+    "interestSubmitted": "Interest submitted — our team will reach out soon.",
+    "interestError": "Couldn't submit your interest. Please try again.",
+    "interestSubjectTemplate": "Interest in {building} · Unit {unit}",
+    "interestDescriptionTemplate": "I'm interested in Unit {unit} ({bedrooms} bd / {bathrooms} ba) at {building}, {floor}. Please reach out with more details."
   }
 }
diff --git a/apps/web/src/store/api/endpoints/available-units.api.ts b/apps/web/src/store/api/endpoints/available-units.api.ts
new file mode 100644
index 00000000..23f6677e
--- /dev/null
+++ b/apps/web/src/store/api/endpoints/available-units.api.ts
@@ -0,0 +1,37 @@
+import { baseApi } from '@/store/api/base-api';
+import type { ApiEnvelope, AvailableUnit } from '@/types/api';
+
+function unwrap<TData>(response: TData | ApiEnvelope<TData>): TData {
+  return response && typeof response === 'object' && 'data' in response
+    ? (response as ApiEnvelope<TData>).data
+    : (response as TData);
+}
+
+export const availableUnitsApi = baseApi.injectEndpoints({
+  endpoints: (build) => ({
+    /**
+     * F6.2 — vacant apartments surfaced in the renter-facing "Available units"
+     * showcase (GET /available-units), enriched with building/floor names.
+     * Read-only; there is no create/update/delete for this list — prospective
+     * tenants "express interest" via a regular support ticket instead.
+     */
+    getAvailableUnits: build.query<AvailableUnit[], void>({
+      query: () => ({ url: '/available-units', method: 'GET' }),
+      transformResponse: (
+        response: AvailableUnit[] | ApiEnvelope<AvailableUnit[]>,
+      ) => unwrap(response),
+      providesTags: (result) =>
+        result
+          ? [
+              ...result.map(({ id }) => ({
+                type: 'AvailableUnit' as const,
+                id,
+              })),
+              { type: 'AvailableUnit', id: 'LIST' },
+            ]
+          : [{ type: 'AvailableUnit', id: 'LIST' }],
+    }),
+  }),
+});
+
+export const { useGetAvailableUnitsQuery } = availableUnitsApi;
diff --git a/apps/web/src/store/api/endpoints/index.ts b/apps/web/src/store/api/endpoints/index.ts
index 9df52f1b..527d31e8 100644
--- a/apps/web/src/store/api/endpoints/index.ts
+++ b/apps/web/src/store/api/endpoints/index.ts
@@ -19,3 +19,4 @@ import './support-tickets.api';
 import './notifications.api';
 import './reports.api';
 import './tenant.api';
+import './available-units.api';
diff --git a/apps/web/src/store/api/tag-types.ts b/apps/web/src/store/api/tag-types.ts
index 8be805bd..163fb82c 100644
--- a/apps/web/src/store/api/tag-types.ts
+++ b/apps/web/src/store/api/tag-types.ts
@@ -20,6 +20,7 @@ export const TAG_TYPES = [
   'Notification',
   'Report',
   'TenantOverview',
+  'AvailableUnit',
 ] as const;
 
 export type TagType = (typeof TAG_TYPES)[number];
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 44293913..56beee98 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -621,6 +621,27 @@ export function formatWorkOrderNumber(n: number): string {
   return `WO-${String(n).padStart(6, '0')}`;
 }
 
+/**
+ * F6.2 — a vacant apartment surfaced in the renter-facing "Available units"
+ * showcase (GET /available-units), enriched with building/floor names for
+ * display. Read-only; prospective tenants express interest via a support ticket.
+ */
+export type AvailableUnit = {
+  id: string;
+  buildingId: string;
+  buildingName: string;
+  floorId: string;
+  floorName: string;
+  unitNumber: string;
+  bedrooms: number;
+  bathrooms: string; // Decimal serialized as string
+  sqft?: number | null;
+};
+
+export type AvailableUnitListResponse = {
+  data: AvailableUnit[];
+};
+
 /** GET /maintenance-requests/:id response — MaintenanceRequestResponse plus its full Work Order history. */
 export type MaintenanceRequestDetailResponse = MaintenanceRequestResponse & {
   workOrders: WorkOrderResponse[];

From 7a55464891f56964e10fba72ddb401b4e4ca779c Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 04:49:51 +0300
Subject: [PATCH 09/11] fix(F6.1): profile dropdown item uses onClick
 navigation, not render={<Link>}
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The topbar user-dropdown "Profile" item using base-ui `render={<Link/>}` threw
Base UI error #31 when the menu opened (crashed the page into the error
boundary). Switched it to a plain DropdownMenuItem with
`onClick={() => router.push(...)}` — the same reliable pattern the sibling
"Sign out" item uses — which navigates without the base-ui render-composition
edge case. Removed the now-unused next/link import.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/web/src/components/layout/dashboard-topbar.tsx | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/components/layout/dashboard-topbar.tsx b/apps/web/src/components/layout/dashboard-topbar.tsx
index 570d5ec6..bc27e7f5 100644
--- a/apps/web/src/components/layout/dashboard-topbar.tsx
+++ b/apps/web/src/components/layout/dashboard-topbar.tsx
@@ -1,7 +1,6 @@
 'use client';
 
-import Link from 'next/link';
-import { usePathname } from 'next/navigation';
+import { usePathname, useRouter } from 'next/navigation';
 import { Sun, Moon, UserIcon } from 'lucide-react';
 import { useTheme } from 'next-themes';
 import { federatedLogout } from '@/auth/federated-logout';
@@ -116,6 +115,7 @@ function UserDropdown({
   dict: Dictionary;
 }) {
   const userInitial = userName ? userName.charAt(0).toUpperCase() : 'U';
+  const router = useRouter();
 
   return (
     <DropdownMenu>
@@ -136,7 +136,9 @@ function UserDropdown({
           </p>
         </DropdownMenuLabel>
         <DropdownMenuSeparator />
-        <DropdownMenuItem render={<Link href={`/${locale}/dashboard/profile`} />}>
+        <DropdownMenuItem
+          onClick={() => router.push(`/${locale}/dashboard/profile`)}
+        >
           <UserIcon />
           {dict.nav.profile}
         </DropdownMenuItem>

From a606a2cfce40487cb96380bf478f46606dbfc96a Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 05:01:55 +0300
Subject: [PATCH 10/11] =?UTF-8?q?fix(F6.1):=20topbar=20user-menu=20crash?=
 =?UTF-8?q?=20=E2=80=94=20DropdownMenuLabel=20used=20outside=20a=20Group?=
 =?UTF-8?q?=20(real=20Q33=20root=20cause)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The topbar avatar → user menu crashed the page into the error boundary the
moment it opened (Base UI error #31) — this is the partner's actual Q33
("clicking profile next to theme changes → this page couldn't load"; the
control next to the theme toggle IS this menu). Root cause: DropdownMenuLabel
maps to base-ui `Menu.GroupLabel`, which must live inside a `Menu.Group`; it was
rendered bare inside DropdownMenuContent, so base-ui threw on open. (The buildings
`⋯` menu, which has no label, opened fine — confirming the isolation.)

Fix: render the user-name header as a plain styled <div> instead of
DropdownMenuLabel (it's a display header, not a semantic group label); dropped
the now-unused import. The menu now opens and the Profile item works.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/web/src/components/layout/dashboard-topbar.tsx | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/components/layout/dashboard-topbar.tsx b/apps/web/src/components/layout/dashboard-topbar.tsx
index bc27e7f5..7293b892 100644
--- a/apps/web/src/components/layout/dashboard-topbar.tsx
+++ b/apps/web/src/components/layout/dashboard-topbar.tsx
@@ -14,7 +14,6 @@ import {
   DropdownMenuContent,
   DropdownMenuItem,
   DropdownMenuSeparator,
-  DropdownMenuLabel,
 } from '@/components/ui/dropdown-menu';
 import { LocaleSwitcher } from '@/components/layout/locale-switcher';
 import { MobileSidebarTrigger } from '@/components/layout/dashboard-sidebar';
@@ -130,11 +129,15 @@ function UserDropdown({
         </Avatar>
       </DropdownMenuTrigger>
       <DropdownMenuContent align="end" side="bottom">
-        <DropdownMenuLabel className="font-normal">
+        {/* Plain header, NOT DropdownMenuLabel: base-ui's Menu.GroupLabel must
+            live inside a Menu.Group — rendering it bare here threw Base UI
+            error #31 and crashed the whole menu on open (the real cause of the
+            partner's "profile couldn't load" Q33). */}
+        <div className="px-2 py-1.5">
           <p className="text-sm font-medium text-foreground">
             {userName || '—'}
           </p>
-        </DropdownMenuLabel>
+        </div>
         <DropdownMenuSeparator />
         <DropdownMenuItem
           onClick={() => router.push(`/${locale}/dashboard/profile`)}

From 3472741a599ffedb3725cfeaa7722b1967ade747 Mon Sep 17 00:00:00 2001
From: Mouhannad <mouhannad.alkhodor@axissoftsolutions.com>
Date: Tue, 21 Jul 2026 19:36:49 +0300
Subject: [PATCH 11/11] feat(tenant-portal): dedicated /portal + admin de-scope
 + IA audit fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tenant Portal (TP1-TP4) + IA1 audit fixes (docs/TENANT-PORTAL-ROADMAP.md).
- TP1: admin mints tenant login from create-renter form (email=username,
  permanent pwd; reuses createUserWithPassword, links renterUserId, no staff seat)
- TP2: new /[lang]/portal route group (own chrome) + routing isolation
  (roles.ts tenant->/portal, proxy.ts tenant<->dashboard both ways, dashboard RSC guard)
- TP3: portal content — lease history + apartments, available-units display-only,
  apartment-scoped Support/Requests, profile
- TP4: removed available-units from admin (area/nav/route) + retired express-interest;
  removed dead TenantDashboard admin branch
- IA1: finance timeline domain fix, billing->ORG_ADMIN, supervisor.payments->none,
  billing page->matrix, dead support-maintenance category removed
Zero migrations. i18n parity 1181. api jest 338/4skip, web vitest 30/30.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/modules/billing/billing.controller.ts |   2 +-
 .../modules/payments/payments.controller.ts   |   3 +-
 .../modules/renters/dto/create-renter.dto.ts  |  31 +-
 .../modules/renters/renters.service.spec.ts   |  77 ++-
 .../src/modules/renters/renters.service.ts    |  82 ++-
 .../src/modules/tenant/tenant.service.spec.ts |  39 ++
 apps/api/src/modules/tenant/tenant.service.ts |   7 +
 .../src/modules/timeline/timeline.service.ts  |  18 +-
 .../[lang]/dashboard/available-units/page.tsx |  28 -
 .../src/app/[lang]/dashboard/billing/page.tsx |   3 +-
 apps/web/src/app/[lang]/dashboard/layout.tsx  |   7 +
 apps/web/src/app/[lang]/dashboard/page.tsx    |   7 +-
 .../[lang]/portal/available-units/page.tsx    |  15 +
 apps/web/src/app/[lang]/portal/layout.tsx     |  41 ++
 apps/web/src/app/[lang]/portal/page.tsx       |  40 ++
 .../src/app/[lang]/portal/profile/page.tsx    | 158 +++++
 .../src/app/[lang]/portal/support/page.tsx    |  15 +
 apps/web/src/auth/permissions.ts              |  19 +-
 apps/web/src/auth/roles.ts                    |   3 +-
 .../dashboard/available-units-page.tsx        | 172 -----
 .../src/components/dashboard/renters-page.tsx | 390 ++++++++++-
 .../src/components/dashboard/support-page.tsx |   6 +-
 .../components/dashboard/tenant-dashboard.tsx | 649 ------------------
 .../components/layout/dashboard-sidebar.tsx   |   8 -
 .../portal/portal-available-units.tsx         | 148 ++++
 .../components/portal/portal-coming-soon.tsx  |  41 ++
 .../components/portal/portal-dict.fallback.ts | 228 ++++++
 apps/web/src/components/portal/portal-dict.ts | 129 ++++
 .../web/src/components/portal/portal-home.tsx | 246 +++++++
 .../src/components/portal/portal-shell.tsx    | 233 +++++++
 .../src/components/portal/portal-support.tsx  | 305 ++++++++
 apps/web/src/i18n/dictionaries/ar.json        | 128 +++-
 apps/web/src/i18n/dictionaries/en.json        | 128 +++-
 apps/web/src/proxy.ts                         |  16 +-
 .../tests/unit/tenant/tenant-overview.test.ts |   1 +
 packages/contracts/src/index.ts               |  17 +
 36 files changed, 2520 insertions(+), 920 deletions(-)
 delete mode 100644 apps/web/src/app/[lang]/dashboard/available-units/page.tsx
 create mode 100644 apps/web/src/app/[lang]/portal/available-units/page.tsx
 create mode 100644 apps/web/src/app/[lang]/portal/layout.tsx
 create mode 100644 apps/web/src/app/[lang]/portal/page.tsx
 create mode 100644 apps/web/src/app/[lang]/portal/profile/page.tsx
 create mode 100644 apps/web/src/app/[lang]/portal/support/page.tsx
 delete mode 100644 apps/web/src/components/dashboard/available-units-page.tsx
 delete mode 100644 apps/web/src/components/dashboard/tenant-dashboard.tsx
 create mode 100644 apps/web/src/components/portal/portal-available-units.tsx
 create mode 100644 apps/web/src/components/portal/portal-coming-soon.tsx
 create mode 100644 apps/web/src/components/portal/portal-dict.fallback.ts
 create mode 100644 apps/web/src/components/portal/portal-dict.ts
 create mode 100644 apps/web/src/components/portal/portal-home.tsx
 create mode 100644 apps/web/src/components/portal/portal-shell.tsx
 create mode 100644 apps/web/src/components/portal/portal-support.tsx

diff --git a/apps/api/src/modules/billing/billing.controller.ts b/apps/api/src/modules/billing/billing.controller.ts
index 611e58e0..1c9da691 100644
--- a/apps/api/src/modules/billing/billing.controller.ts
+++ b/apps/api/src/modules/billing/billing.controller.ts
@@ -17,7 +17,7 @@ export class BillingController {
     private readonly orgScope: OrgScopeService,
   ) {}
 
-  @Roles(Role.ORG_ADMIN, Role.FINANCE)
+  @Roles(Role.ORG_ADMIN)
   @Get('subscription')
   async getSubscription(@CurrentUser() user: AuthenticatedUser) {
     const { orgId } = await this.orgScope.resolveForCaller(user);
diff --git a/apps/api/src/modules/payments/payments.controller.ts b/apps/api/src/modules/payments/payments.controller.ts
index 99061fe6..d1731a2b 100644
--- a/apps/api/src/modules/payments/payments.controller.ts
+++ b/apps/api/src/modules/payments/payments.controller.ts
@@ -8,9 +8,8 @@ import { Role } from '@/common/enums';
 
 @ApiTags('payments')
 @ApiBearerAuth()
-// Supervisor is read-only — no mutating payment endpoints are exposed to supervisor.
 // TODO: scope by buildingId once Payment is building-linked.
-@Roles(Role.ORG_ADMIN, Role.FINANCE, Role.SUPERVISOR)
+@Roles(Role.ORG_ADMIN, Role.FINANCE)
 @Controller('payments')
 export class PaymentsController {
   constructor(
diff --git a/apps/api/src/modules/renters/dto/create-renter.dto.ts b/apps/api/src/modules/renters/dto/create-renter.dto.ts
index 5796350b..da87a6aa 100644
--- a/apps/api/src/modules/renters/dto/create-renter.dto.ts
+++ b/apps/api/src/modules/renters/dto/create-renter.dto.ts
@@ -1,6 +1,25 @@
-import { IsEmail, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import {
+  IsEmail,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  MinLength,
+  ValidateNested,
+} from 'class-validator';
+import { Type } from 'class-transformer';
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
+export class PortalLoginDto {
+  @ApiProperty()
+  @IsEmail()
+  email: string;
+
+  @ApiProperty()
+  @IsString()
+  @MinLength(8)
+  password: string;
+}
+
 export class CreateRenterDto {
   @ApiProperty()
   @IsString()
@@ -40,4 +59,14 @@ export class CreateRenterDto {
   @IsOptional()
   @IsString()
   renterUserId?: string | null;
+
+  @ApiPropertyOptional({
+    description:
+      'When present, the API mints a Keycloak tenant login for this renter and links it (sets renterUserId to the new sub). Admin-provisioned only — no self-registration. If both portalLogin and renterUserId are provided, portalLogin wins.',
+    type: PortalLoginDto,
+  })
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => PortalLoginDto)
+  portalLogin?: PortalLoginDto;
 }
diff --git a/apps/api/src/modules/renters/renters.service.spec.ts b/apps/api/src/modules/renters/renters.service.spec.ts
index e80ada10..092985b1 100644
--- a/apps/api/src/modules/renters/renters.service.spec.ts
+++ b/apps/api/src/modules/renters/renters.service.spec.ts
@@ -19,6 +19,7 @@ describe('RentersService', () => {
       renter?: Partial<Record<string, jest.Mock>>;
       lease?: Partial<Record<string, jest.Mock>>;
       buildingAccess?: Partial<Record<string, jest.Mock>>;
+      keycloakAdmin?: Partial<Record<string, jest.Mock>>;
     } = {},
   ) {
     const prisma = {
@@ -42,14 +43,21 @@ describe('RentersService', () => {
       getAllowedBuildingIds: jest.fn().mockResolvedValue(null),
       ...overrides.buildingAccess,
     };
+    const keycloakAdmin = {
+      createUserWithPassword: jest.fn().mockResolvedValue('kc-sub-1'),
+      setSingleClientRole: jest.fn().mockResolvedValue(undefined),
+      deleteUser: jest.fn().mockResolvedValue(undefined),
+      ...overrides.keycloakAdmin,
+    };
     const leaseStatus = new LeaseStatusService();
     const service = new RentersService(
       prisma as any,
       timeline as any,
       buildingAccess as any,
       leaseStatus,
+      keycloakAdmin as any,
     );
-    return { service, prisma, timeline, buildingAccess };
+    return { service, prisma, timeline, buildingAccess, keycloakAdmin };
   }
 
   const renterRow = (overrides: Partial<Record<string, unknown>> = {}) => ({
@@ -221,7 +229,7 @@ describe('RentersService', () => {
     const dto = { fullName: 'Jane Doe' };
 
     it('creates a renter scoped to the org and emits renter.created', async () => {
-      const { service, prisma, timeline } = makeService();
+      const { service, prisma, timeline, keycloakAdmin } = makeService();
       prisma.renter.create.mockResolvedValue(renterRow());
 
       await service.create(orgId, actorId, dto);
@@ -245,6 +253,71 @@ describe('RentersService', () => {
           targetType: 'Renter',
         }),
       );
+      // No portalLogin was passed → zero Keycloak calls, behavior unchanged.
+      expect(keycloakAdmin.createUserWithPassword).not.toHaveBeenCalled();
+      expect(keycloakAdmin.setSingleClientRole).not.toHaveBeenCalled();
+      expect(keycloakAdmin.deleteUser).not.toHaveBeenCalled();
+    });
+
+    it('mints a Keycloak tenant login when portalLogin is provided, links renterUserId to the new sub, and tags the timeline event', async () => {
+      const { service, prisma, timeline, keycloakAdmin } = makeService();
+      prisma.renter.create.mockResolvedValue(
+        renterRow({ renterUserId: 'kc-sub-1' }),
+      );
+
+      const portalDto = {
+        fullName: 'Jane Doe',
+        portalLogin: { email: 'jane@tenant.test', password: 'password123' },
+      };
+
+      await service.create(orgId, actorId, portalDto);
+
+      expect(keycloakAdmin.createUserWithPassword).toHaveBeenCalledWith({
+        username: 'jane@tenant.test',
+        password: 'password123',
+        email: 'jane@tenant.test',
+        firstName: 'Jane',
+        lastName: 'Doe',
+        attributes: { org_id: [orgId] },
+      });
+      expect(keycloakAdmin.setSingleClientRole).toHaveBeenCalledWith(
+        'kc-sub-1',
+        Role.TENANT,
+      );
+      expect(prisma.renter.create).toHaveBeenCalledWith({
+        data: expect.objectContaining({ renterUserId: 'kc-sub-1' }),
+      });
+      expect(timeline.emit).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: 'renter.created',
+          metadata: expect.objectContaining({ portalLogin: true }),
+        }),
+      );
+    });
+
+    it('maps a Keycloak 409 (email already taken) to ConflictException and persists no renter', async () => {
+      const conflict = {
+        isAxiosError: true,
+        response: { status: 409 },
+        message: 'Request failed with status code 409',
+      };
+
+      const { service, prisma, keycloakAdmin } = makeService({
+        keycloakAdmin: {
+          createUserWithPassword: jest.fn().mockRejectedValue(conflict),
+        },
+      });
+
+      const portalDto = {
+        fullName: 'Jane Doe',
+        portalLogin: { email: 'jane@tenant.test', password: 'password123' },
+      };
+
+      await expect(
+        service.create(orgId, actorId, portalDto),
+      ).rejects.toBeInstanceOf(ConflictException);
+      expect(prisma.renter.create).not.toHaveBeenCalled();
+      expect(keycloakAdmin.setSingleClientRole).not.toHaveBeenCalled();
     });
   });
 
diff --git a/apps/api/src/modules/renters/renters.service.ts b/apps/api/src/modules/renters/renters.service.ts
index 6153d222..5aae08a4 100644
--- a/apps/api/src/modules/renters/renters.service.ts
+++ b/apps/api/src/modules/renters/renters.service.ts
@@ -2,12 +2,15 @@ import {
   ConflictException,
   ForbiddenException,
   Injectable,
+  Logger,
   NotFoundException,
 } from '@nestjs/common';
+import { isAxiosError } from 'axios';
 import { PrismaService } from '@/infrastructure/prisma/prisma.service';
 import { TimelineService } from '@/modules/timeline/timeline.service';
 import { BuildingAccessService } from '@/common/building-access/building-access.service';
 import { LeaseStatusService } from '@/common/lease-status/lease-status.service';
+import { KeycloakAdminService } from '@/infrastructure/keycloak/keycloak-admin.service';
 import { formatLease, LeaseRow } from '@/modules/leases/lease-formatter';
 import { Role } from '@/common/enums';
 import {
@@ -34,11 +37,14 @@ type RenterRow = {
 
 @Injectable()
 export class RentersService {
+  private readonly logger = new Logger(RentersService.name);
+
   constructor(
     private readonly prisma: PrismaService,
     private readonly timeline: TimelineService,
     private readonly buildingAccess: BuildingAccessService,
     private readonly leaseStatus: LeaseStatusService,
+    private readonly keycloakAdmin: KeycloakAdminService,
   ) {}
 
   // ── Format helpers ────────────────────────────────────────────────────────
@@ -148,18 +154,65 @@ export class RentersService {
     actorId: string,
     dto: CreateRenterDto,
   ): Promise<{ data: RenterResponse }> {
-    const renter = await this.prisma.renter.create({
-      data: {
-        orgId,
-        fullName: dto.fullName,
-        email: dto.email,
-        phone: dto.phone,
-        emergencyContactName: dto.emergencyContactName,
-        emergencyContactPhone: dto.emergencyContactPhone,
-        notes: dto.notes,
-        renterUserId: dto.renterUserId,
-      },
-    });
+    // portalLogin wins over a passed-through renterUserId (see CreateRenterBody).
+    let renterUserId = dto.renterUserId;
+    let portalLoginMinted = false;
+
+    if (dto.portalLogin) {
+      const [firstName = '', ...rest] = dto.fullName.trim().split(' ');
+      const lastName = rest.join(' ');
+
+      try {
+        renterUserId = await this.keycloakAdmin.createUserWithPassword({
+          username: dto.portalLogin.email,
+          password: dto.portalLogin.password,
+          email: dto.portalLogin.email,
+          firstName,
+          lastName,
+          attributes: { org_id: [orgId] },
+        });
+      } catch (error) {
+        if (isAxiosError(error) && error.response?.status === 409) {
+          throw new ConflictException(
+            'A portal login with this email already exists.',
+          );
+        }
+        throw error;
+      }
+
+      // Tenant is NOT a CAPPED_ROLE and does not get building assignments —
+      // unlike staff (see UsersService.create).
+      await this.keycloakAdmin.setSingleClientRole(renterUserId, Role.TENANT);
+      portalLoginMinted = true;
+    }
+
+    let renter: RenterRow;
+    try {
+      renter = await this.prisma.renter.create({
+        data: {
+          orgId,
+          fullName: dto.fullName,
+          email: dto.email,
+          phone: dto.phone,
+          emergencyContactName: dto.emergencyContactName,
+          emergencyContactPhone: dto.emergencyContactPhone,
+          notes: dto.notes,
+          renterUserId,
+        },
+      });
+    } catch (error) {
+      // Best-effort rollback: don't strand a Keycloak login with no renter row.
+      if (portalLoginMinted && renterUserId) {
+        try {
+          await this.keycloakAdmin.deleteUser(renterUserId);
+        } catch (cleanupError) {
+          this.logger.warn(
+            `Failed to roll back Keycloak user ${renterUserId} after renter creation failure: ${String(cleanupError)}`,
+          );
+        }
+      }
+      throw error;
+    }
 
     await this.timeline.emit({
       orgId,
@@ -167,7 +220,10 @@ export class RentersService {
       action: 'renter.created',
       targetType: 'Renter',
       targetId: renter.id,
-      metadata: { fullName: renter.fullName },
+      metadata: {
+        fullName: renter.fullName,
+        ...(portalLoginMinted && { portalLogin: true }),
+      },
     });
 
     return { data: this.formatRenter(renter, null) };
diff --git a/apps/api/src/modules/tenant/tenant.service.spec.ts b/apps/api/src/modules/tenant/tenant.service.spec.ts
index ecd14283..83dc8d4f 100644
--- a/apps/api/src/modules/tenant/tenant.service.spec.ts
+++ b/apps/api/src/modules/tenant/tenant.service.spec.ts
@@ -72,6 +72,7 @@ describe('TenantService', () => {
       expect(data.linked).toBe(false);
       expect(data.renter).toBeNull();
       expect(data.lease).toBeNull();
+      expect(data.leaseHistory).toEqual([]);
       expect(data.invoices).toEqual([]);
       expect(data.maintenanceRequests).toEqual([]);
       expect(data.balance).toEqual({
@@ -157,6 +158,44 @@ describe('TenantService', () => {
       ]);
     });
 
+    it('returns the full lease history newest-first, distinct from the single current lease', async () => {
+      const olderLease = leaseRow({
+        id: 'lease-0',
+        startDate: new Date('2024-01-01T00:00:00.000Z'),
+        endDate: new Date('2025-01-01T00:00:00.000Z'),
+        status: 'ended',
+        apartment: { unitNumber: '2A', building: { name: 'Old Building' } },
+      });
+      const currentLease = leaseRow(); // startDate 2026-01-01, newer
+      const { service } = makeService({
+        renter: { findFirst: jest.fn().mockResolvedValue(renter) },
+        // Prisma orders by startDate desc, so the mock returns newest first.
+        lease: {
+          findMany: jest
+            .fn()
+            .mockResolvedValue([currentLease, olderLease]),
+        },
+      });
+
+      const { data } = await service.getOverview(orgId, sub, now);
+
+      expect(data.leaseHistory).toHaveLength(2);
+      expect(data.leaseHistory.map((l) => l.id)).toEqual([
+        'lease-1',
+        'lease-0',
+      ]);
+      expect(data.leaseHistory[1]).toEqual(
+        expect.objectContaining({
+          id: 'lease-0',
+          unitNumber: '2A',
+          buildingName: 'Old Building',
+          status: 'ended',
+        }),
+      );
+      // `lease` remains the single current one, unaffected by the history list.
+      expect(data.lease?.id).toBe('lease-1');
+    });
+
     it('derives effectiveStatus expired for an active lease whose endDate has passed', async () => {
       const { service } = makeService({
         renter: { findFirst: jest.fn().mockResolvedValue(renter) },
diff --git a/apps/api/src/modules/tenant/tenant.service.ts b/apps/api/src/modules/tenant/tenant.service.ts
index 98e27e35..5e933f55 100644
--- a/apps/api/src/modules/tenant/tenant.service.ts
+++ b/apps/api/src/modules/tenant/tenant.service.ts
@@ -74,6 +74,7 @@ export class TenantService {
       linked: false,
       renter: null,
       lease: null,
+      leaseHistory: [],
       balance: { invoiced: '0.00', paid: '0.00', outstanding: '0.00' },
       invoices: [],
       maintenanceRequests: [],
@@ -226,6 +227,12 @@ export class TenantService {
           phone: renter.phone,
         },
         lease: current ? this.formatLease(current, now) : null,
+        // Full lease history for the portal (TP3) — same per-lease formatter as
+        // `lease`, applied to every lease the tenant has ever held, newest first
+        // (leases were already fetched ordered by startDate desc).
+        leaseHistory: (leases as LeaseRow[]).map((l) =>
+          this.formatLease(l, now),
+        ),
         balance: {
           invoiced: this.money(totalInvoiced),
           paid: this.money(totalPaid),
diff --git a/apps/api/src/modules/timeline/timeline.service.ts b/apps/api/src/modules/timeline/timeline.service.ts
index 596a80f7..27e0ffc9 100644
--- a/apps/api/src/modules/timeline/timeline.service.ts
+++ b/apps/api/src/modules/timeline/timeline.service.ts
@@ -73,17 +73,21 @@ export class TimelineService {
       // Tenant: only own events
       where = { orgId, actorId: caller.sub };
     } else if (role === Role.FINANCE) {
-      // Finance: billing/payment/subscription events only
+      // Finance: invoice/invoice-payment/expense events only (finance's actual
+      // domain — NOT the platform's own Stripe subscription billing, which
+      // finance cannot even reach; see billing.controller.ts @Roles).
       where = {
         orgId,
         action: {
           in: [
-            'subscription.created',
-            'subscription.updated',
-            'subscription.canceled',
-            'payment.paid',
-            'payment.failed',
-            'checkout.completed',
+            'invoice.created',
+            'invoice.updated',
+            'invoice.deleted',
+            'invoice_payment.created',
+            'invoice_payment.deleted',
+            'expense.created',
+            'expense.updated',
+            'expense.deleted',
           ],
         },
       };
diff --git a/apps/web/src/app/[lang]/dashboard/available-units/page.tsx b/apps/web/src/app/[lang]/dashboard/available-units/page.tsx
deleted file mode 100644
index 949d5d14..00000000
--- a/apps/web/src/app/[lang]/dashboard/available-units/page.tsx
+++ /dev/null
@@ -1,28 +0,0 @@
-import { requireSession } from '@/auth/guards';
-import { normalizeRole } from '@/auth/roles';
-import { canAccess } from '@/auth/permissions';
-import { redirect } from 'next/navigation';
-import { isLocale } from '@/i18n/config';
-import { getDictionary } from '@/i18n/get-dictionary';
-import { AvailableUnitsPage } from '@/components/dashboard/available-units-page';
-
-export default async function AvailableUnitsPageRoute({
-  params,
-}: {
-  params: Promise<{ lang: string }>;
-}) {
-  const { lang } = await params;
-  const locale = isLocale(lang) ? lang : 'en';
-  const session = await requireSession({ locale });
-  const role = normalizeRole(session.role ?? session.user?.role);
-
-  if (!canAccess(role, 'availableUnits')) {
-    // Match the sibling dashboard pages (buildings/invoices/leases/…), which
-    // bounce an unauthorized role back to their own dashboard home.
-    redirect(`/${locale}/dashboard`);
-  }
-
-  const dict = await getDictionary(locale);
-
-  return <AvailableUnitsPage locale={locale} dict={dict} />;
-}
diff --git a/apps/web/src/app/[lang]/dashboard/billing/page.tsx b/apps/web/src/app/[lang]/dashboard/billing/page.tsx
index bc2d1d83..41a8db17 100644
--- a/apps/web/src/app/[lang]/dashboard/billing/page.tsx
+++ b/apps/web/src/app/[lang]/dashboard/billing/page.tsx
@@ -1,5 +1,6 @@
 import { requireSession } from '@/auth/guards';
 import { normalizeRole } from '@/auth/roles';
+import { canAccess } from '@/auth/permissions';
 import { redirect } from 'next/navigation';
 import { isLocale } from '@/i18n/config';
 import { getDictionary } from '@/i18n/get-dictionary';
@@ -14,7 +15,7 @@ export default async function DashboardBillingPage({
   const locale = isLocale(lang) ? lang : 'en';
   const session = await requireSession({ locale });
   const role = normalizeRole(session.role ?? session.user?.role);
-  if (role !== 'org_admin') redirect(`/${locale}/dashboard`);
+  if (!canAccess(role, 'billing')) redirect(`/${locale}/dashboard`);
   const dict = await getDictionary(locale);
   return <BillingPageContent locale={locale} dict={dict} />;
 }
diff --git a/apps/web/src/app/[lang]/dashboard/layout.tsx b/apps/web/src/app/[lang]/dashboard/layout.tsx
index 49095d66..968cefbf 100644
--- a/apps/web/src/app/[lang]/dashboard/layout.tsx
+++ b/apps/web/src/app/[lang]/dashboard/layout.tsx
@@ -1,4 +1,6 @@
+import { redirect } from 'next/navigation';
 import { requireSession, requireActiveOrg } from '@/auth/guards';
+import { normalizeRole } from '@/auth/roles';
 import { getDictionary } from '@/i18n/get-dictionary';
 import { isLocale } from '@/i18n/config';
 import { serverEnv } from '@/lib/env';
@@ -32,6 +34,11 @@ export default async function DashboardLayout({
   const locale = isLocale(lang) ? lang : 'en';
   const session = await requireSession({ locale });
 
+  // Tenants belong to the resident portal, never the admin dashboard shell.
+  // Authoritative in-RSC counterpart to the edge redirect in proxy.ts.
+  const sessionRole = normalizeRole(session.role ?? session.user?.role);
+  if (sessionRole === 'tenant') redirect(`/${locale}/portal`);
+
   // Authoritative paywall for the WHOLE dashboard subtree (incl. every
   // sub-page). "Has paid?" is org.status === ACTIVE in the DB — token-
   // independent, so it correctly bounces a lapsed (PAST_DUE/CANCELED) or
diff --git a/apps/web/src/app/[lang]/dashboard/page.tsx b/apps/web/src/app/[lang]/dashboard/page.tsx
index a328262f..1eb6f9bd 100644
--- a/apps/web/src/app/[lang]/dashboard/page.tsx
+++ b/apps/web/src/app/[lang]/dashboard/page.tsx
@@ -1,3 +1,4 @@
+import { redirect } from 'next/navigation';
 import { requireSession, requireActiveOrg } from '@/auth/guards';
 import { normalizeRole } from '@/auth/roles';
 import { isLocale } from '@/i18n/config';
@@ -7,7 +8,6 @@ import { SessionRefresher } from '@/components/auth/session-refresher';
 import { OrgAdminDashboard } from '@/components/dashboard/org-admin-dashboard';
 import { FinanceDashboard } from '@/components/dashboard/finance-dashboard';
 import { StaffDashboard } from '@/components/dashboard/staff-dashboard';
-import { TenantDashboard } from '@/components/dashboard/tenant-dashboard';
 import { DefaultDashboard } from '@/components/dashboard/default-dashboard';
 import type { MeResponse } from '@/types/api';
 
@@ -75,8 +75,11 @@ export default async function DashboardPage({
     if (role === 'supervisor' || role === 'maintenance') {
       return <StaffDashboard me={me} locale={locale} role={role} dict={dict} />;
     }
+    // Tenants belong to the resident portal, never the admin dashboard — the
+    // dashboard layout + proxy already redirect them. This is the last-resort
+    // guard so a tenant can never render an admin dashboard body.
     if (role === 'tenant') {
-      return <TenantDashboard me={me} locale={locale} dict={dict} />;
+      redirect(`/${locale}/portal`);
     }
     return (
       <DefaultDashboard me={me} locale={locale} role={role ?? 'unknown'} />
diff --git a/apps/web/src/app/[lang]/portal/available-units/page.tsx b/apps/web/src/app/[lang]/portal/available-units/page.tsx
new file mode 100644
index 00000000..d25a6dbe
--- /dev/null
+++ b/apps/web/src/app/[lang]/portal/available-units/page.tsx
@@ -0,0 +1,15 @@
+import { isLocale } from '@/i18n/config';
+import { getDictionary } from '@/i18n/get-dictionary';
+import { PortalAvailableUnits } from '@/components/portal/portal-available-units';
+
+export default async function PortalAvailableUnitsPage({
+  params,
+}: {
+  params: Promise<{ lang: string }>;
+}) {
+  const { lang } = await params;
+  const locale = isLocale(lang) ? lang : 'en';
+  const dict = await getDictionary(locale);
+
+  return <PortalAvailableUnits locale={locale} dict={dict} />;
+}
diff --git a/apps/web/src/app/[lang]/portal/layout.tsx b/apps/web/src/app/[lang]/portal/layout.tsx
new file mode 100644
index 00000000..d72c20e9
--- /dev/null
+++ b/apps/web/src/app/[lang]/portal/layout.tsx
@@ -0,0 +1,41 @@
+import { redirect } from 'next/navigation';
+import type { ReactNode } from 'react';
+
+import { requireSession } from '@/auth/guards';
+import { dashboardPathForRole, normalizeRole } from '@/auth/roles';
+import { isLocale } from '@/i18n/config';
+import { getDictionary } from '@/i18n/get-dictionary';
+import { PortalShell } from '@/components/portal/portal-shell';
+
+/**
+ * Tenant portal shell (TP2). A visually distinct, light/warm, mobile-first
+ * resident experience — NOT the admin dashboard chrome. Only the `tenant`
+ * role belongs here; every other role is bounced back to their dashboard.
+ * Routing-isolation (roles/permissions/middleware) is owned by the
+ * orchestrator, so this guard is intentionally self-contained here.
+ */
+export default async function PortalLayout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: Promise<{ lang: string }>;
+}) {
+  const { lang } = await params;
+  const locale = isLocale(lang) ? lang : 'en';
+  const session = await requireSession({ locale });
+
+  const role = normalizeRole(session.role ?? session.user?.role);
+  if (role !== 'tenant') {
+    redirect(dashboardPathForRole(role ?? 'org_admin', locale));
+  }
+
+  const dict = await getDictionary(locale);
+  const userName = session.user?.name ?? session.user?.email ?? '';
+
+  return (
+    <PortalShell locale={locale} dict={dict} userName={userName}>
+      {children}
+    </PortalShell>
+  );
+}
diff --git a/apps/web/src/app/[lang]/portal/page.tsx b/apps/web/src/app/[lang]/portal/page.tsx
new file mode 100644
index 00000000..72d6b09e
--- /dev/null
+++ b/apps/web/src/app/[lang]/portal/page.tsx
@@ -0,0 +1,40 @@
+import { requireSession } from '@/auth/guards';
+import { isLocale } from '@/i18n/config';
+import { getDictionary } from '@/i18n/get-dictionary';
+import { serverEnv } from '@/lib/env';
+import { PortalHome } from '@/components/portal/portal-home';
+import type { MeResponse } from '@/types/api';
+
+async function fetchMe(accessToken: string): Promise<MeResponse | null> {
+  try {
+    const res = await fetch(`${serverEnv.API_URL}/me`, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+      cache: 'no-store',
+    });
+    if (!res.ok) return null;
+    const json = (await res.json()) as MeResponse | { data: MeResponse };
+    return 'data' in json ? json.data : json;
+  } catch {
+    return null;
+  }
+}
+
+export default async function PortalHomePage({
+  params,
+}: {
+  params: Promise<{ lang: string }>;
+}) {
+  const { lang } = await params;
+  const locale = isLocale(lang) ? lang : 'en';
+  const dict = await getDictionary(locale);
+
+  const session = await requireSession({ locale });
+  const userName = session.user?.name ?? session.user?.email ?? '';
+
+  let me: MeResponse | null = null;
+  if (session.accessToken) {
+    me = await fetchMe(session.accessToken);
+  }
+
+  return <PortalHome me={me} userName={userName} locale={locale} dict={dict} />;
+}
diff --git a/apps/web/src/app/[lang]/portal/profile/page.tsx b/apps/web/src/app/[lang]/portal/profile/page.tsx
new file mode 100644
index 00000000..ac358360
--- /dev/null
+++ b/apps/web/src/app/[lang]/portal/profile/page.tsx
@@ -0,0 +1,158 @@
+import { UserIcon, ExternalLinkIcon, KeyRoundIcon } from 'lucide-react';
+
+import { requireSession } from '@/auth/guards';
+import { normalizeRole } from '@/auth/roles';
+import { isLocale } from '@/i18n/config';
+import { getDictionary } from '@/i18n/get-dictionary';
+import { serverEnv } from '@/lib/env';
+import { getPortalDict } from '@/components/portal/portal-dict';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent } from '@/components/ui/card';
+import type { MeResponse } from '@/types/api';
+
+async function fetchMe(accessToken: string): Promise<MeResponse | null> {
+  try {
+    const res = await fetch(`${serverEnv.API_URL}/me`, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+      cache: 'no-store',
+    });
+    if (!res.ok) return null;
+    const json = (await res.json()) as MeResponse | { data: MeResponse };
+    return 'data' in json ? json.data : json;
+  } catch {
+    return null;
+  }
+}
+
+export default async function PortalProfilePage({
+  params,
+}: {
+  params: Promise<{ lang: string }>;
+}) {
+  const { lang } = await params;
+  const locale = isLocale(lang) ? lang : 'en';
+  const dict = await getDictionary(locale);
+  // Shared profile labels (same as the admin profile page); the extra
+  // change-password link copy lives in the portal namespace.
+  const t = dict.profile;
+  const tp = getPortalDict(dict, locale).profile;
+
+  const session = await requireSession({ locale });
+
+  let me: MeResponse | null = null;
+  if (session.accessToken) {
+    me = await fetchMe(session.accessToken);
+  }
+
+  const name = me?.user?.fullName ?? session.user?.name ?? '—';
+  const email = me?.user?.email ?? session.user?.email ?? '—';
+  const role = normalizeRole(me?.role ?? session.role ?? session.user?.role);
+  const roleLabel = role ? dict.auth.roles[role] : '—';
+  const orgName = me?.org?.name ?? '—';
+
+  const accountUrl = `${serverEnv.KEYCLOAK_BASE}/realms/${serverEnv.KEYCLOAK_REALM}/account`;
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex items-center gap-3">
+        <span className="flex size-11 items-center justify-center rounded-2xl bg-gradient-to-br from-amber-400 to-orange-500 text-white">
+          <UserIcon className="size-5" />
+        </span>
+        <div>
+          <h1 className="text-2xl font-semibold tracking-tight text-foreground">
+            {t.title}
+          </h1>
+          <p className="mt-0.5 text-sm text-muted-foreground">{t.subtitle}</p>
+        </div>
+      </div>
+
+      <Card className="ring-foreground/10">
+        <CardContent className="grid grid-cols-1 gap-6 sm:grid-cols-2">
+          <Field label={t.name}>{name}</Field>
+          <Field label={t.email}>{email}</Field>
+          <Field label={t.role}>
+            <Badge
+              variant="outline"
+              className="border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-900/40 dark:bg-amber-400/10 dark:text-amber-300"
+            >
+              {roleLabel}
+            </Badge>
+          </Field>
+          <Field label={t.organization}>{orgName}</Field>
+        </CardContent>
+      </Card>
+
+      {/* Account management (Keycloak console) */}
+      <Card className="ring-foreground/10">
+        <CardContent className="flex flex-col gap-4">
+          <ActionRow
+            icon={<UserIcon className="size-5" />}
+            title={t.manageAccount}
+            hint={t.manageAccountHint}
+            href={accountUrl}
+            cta={t.manageAccount}
+          />
+          <div className="border-t border-border/60" />
+          <ActionRow
+            icon={<KeyRoundIcon className="size-5" />}
+            title={tp.changePassword}
+            hint={tp.changePasswordHint}
+            href={accountUrl}
+            cta={tp.changePassword}
+          />
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+function Field({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex flex-col gap-1">
+      <p className="text-xs text-muted-foreground">{label}</p>
+      <div className="text-sm font-medium text-foreground">{children}</div>
+    </div>
+  );
+}
+
+function ActionRow({
+  icon,
+  title,
+  hint,
+  href,
+  cta,
+}: {
+  icon: React.ReactNode;
+  title: string;
+  hint: string;
+  href: string;
+  cta: string;
+}) {
+  return (
+    <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+      <div className="flex items-start gap-3">
+        <span className="flex size-9 shrink-0 items-center justify-center rounded-xl bg-amber-100 text-amber-600 dark:bg-amber-400/15 dark:text-amber-300">
+          {icon}
+        </span>
+        <div className="max-w-md">
+          <h2 className="text-sm font-medium text-foreground">{title}</h2>
+          <p className="mt-0.5 text-xs text-muted-foreground">{hint}</p>
+        </div>
+      </div>
+      <Button
+        variant="outline"
+        render={<a href={href} target="_blank" rel="noreferrer" />}
+      >
+        {cta}
+        <ExternalLinkIcon />
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/[lang]/portal/support/page.tsx b/apps/web/src/app/[lang]/portal/support/page.tsx
new file mode 100644
index 00000000..381c9b9d
--- /dev/null
+++ b/apps/web/src/app/[lang]/portal/support/page.tsx
@@ -0,0 +1,15 @@
+import { isLocale } from '@/i18n/config';
+import { getDictionary } from '@/i18n/get-dictionary';
+import { PortalSupport } from '@/components/portal/portal-support';
+
+export default async function PortalSupportPage({
+  params,
+}: {
+  params: Promise<{ lang: string }>;
+}) {
+  const { lang } = await params;
+  const locale = isLocale(lang) ? lang : 'en';
+  const dict = await getDictionary(locale);
+
+  return <PortalSupport locale={locale} dict={dict} />;
+}
diff --git a/apps/web/src/auth/permissions.ts b/apps/web/src/auth/permissions.ts
index 9f7dee42..aedbc03c 100644
--- a/apps/web/src/auth/permissions.ts
+++ b/apps/web/src/auth/permissions.ts
@@ -29,10 +29,9 @@
  *   "notifications" → /dashboard/notifications (a personal inbox, like the
  *                   header bell — every role gets 'full', there is no
  *                   restricted view of someone else's notifications)
- *   "availableUnits" → /dashboard/available-units (F6.2 — renter-facing vacant
- *                   units showcase; tenant gets 'full' since expressing
- *                   interest — via a support ticket — is the whole point of
- *                   the page for them; staff roles get 'readonly' visibility)
+ *
+ * Note: available-units is NOT an admin area — the vacant-units showcase lives
+ * only in the tenant portal (/[lang]/portal/available-units), display-only.
  */
 
 import type { Role } from '@/auth/roles';
@@ -51,8 +50,7 @@ export type DashboardArea =
   | 'invoices'
   | 'support'
   | 'leases'
-  | 'notifications'
-  | 'availableUnits';
+  | 'notifications';
 
 /**
  * Per-role access level for an area.
@@ -80,13 +78,12 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'full',
     leases: 'full',
     notifications: 'full',
-    availableUnits: 'readonly',
   },
   supervisor: {
     dashboard: 'readonly',
     buildings: 'readonly',
     users: 'readonly',
-    payments: 'readonly',
+    payments: 'none',
     reports: 'none',
     billing: 'none',
     timeline: 'readonly',
@@ -97,7 +94,6 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'full',
     leases: 'readonly',
     notifications: 'full',
-    availableUnits: 'readonly',
   },
   finance: {
     dashboard: 'readonly',
@@ -114,7 +110,6 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'readonly',
     leases: 'readonly',
     notifications: 'full',
-    availableUnits: 'readonly',
   },
   maintenance: {
     dashboard: 'readonly',
@@ -131,7 +126,6 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'readonly',
     leases: 'readonly',
     notifications: 'full',
-    availableUnits: 'readonly',
   },
   tenant: {
     dashboard: 'readonly',
@@ -151,9 +145,6 @@ export const PERMISSION_MATRIX: PermissionMatrix = {
     support: 'readonly',
     leases: 'none',
     notifications: 'full',
-    // full = this page IS the tenant's flow (browse vacant units → express
-    // interest via a support ticket); there's no write action to restrict.
-    availableUnits: 'full',
   },
 };
 
diff --git a/apps/web/src/auth/roles.ts b/apps/web/src/auth/roles.ts
index d2730ce1..e6c8b210 100644
--- a/apps/web/src/auth/roles.ts
+++ b/apps/web/src/auth/roles.ts
@@ -35,7 +35,8 @@ export const ROLE_DASHBOARD: Record<Role, string> = {
   supervisor: '/dashboard',
   finance: '/dashboard',
   maintenance: '/dashboard',
-  tenant: '/dashboard',
+  // Tenants get the dedicated resident portal, not the admin dashboard shell.
+  tenant: '/portal',
 };
 
 /**
diff --git a/apps/web/src/components/dashboard/available-units-page.tsx b/apps/web/src/components/dashboard/available-units-page.tsx
deleted file mode 100644
index adf2d8ad..00000000
--- a/apps/web/src/components/dashboard/available-units-page.tsx
+++ /dev/null
@@ -1,172 +0,0 @@
-'use client';
-
-import { toast } from 'sonner';
-import { BedDoubleIcon, HomeIcon, KeyRoundIcon, MapPinIcon } from 'lucide-react';
-
-import {
-  Card,
-  CardHeader,
-  CardTitle,
-  CardDescription,
-  CardContent,
-  CardFooter,
-} from '@/components/ui/card';
-import { Button } from '@/components/ui/button';
-import { Skeleton } from '@/components/ui/skeleton';
-
-import { useGetAvailableUnitsQuery } from '@/store/api/endpoints/available-units.api';
-import { useCreateSupportTicketMutation } from '@/store/api/endpoints/support-tickets.api';
-import type { AvailableUnit } from '@/types/api';
-import type { Dictionary } from '@/i18n/get-dictionary';
-
-// ── Express-interest button ──────────────────────────────────────────────────
-// Reuses the existing support-ticket create flow — no new data model. Each
-// card owns its own mutation instance so the "submitting" state (and
-// disabled button) is scoped to that one unit, not the whole page.
-
-function fillTemplate(
-  template: string,
-  values: Record<string, string>,
-): string {
-  return Object.entries(values).reduce(
-    (acc, [key, value]) => acc.replaceAll(`{${key}}`, value),
-    template,
-  );
-}
-
-function UnitCard({
-  unit,
-  t,
-}: {
-  unit: AvailableUnit;
-  t: Dictionary['availableUnits'];
-}) {
-  const [createSupportTicket, { isLoading: submitting }] =
-    useCreateSupportTicketMutation();
-
-  async function handleExpressInterest() {
-    const templateValues = {
-      building: unit.buildingName,
-      unit: unit.unitNumber,
-      floor: unit.floorName,
-      bedrooms: String(unit.bedrooms),
-      bathrooms: unit.bathrooms,
-    };
-    try {
-      await createSupportTicket({
-        subject: fillTemplate(t.interestSubjectTemplate, templateValues),
-        description: fillTemplate(t.interestDescriptionTemplate, templateValues),
-        category: 'general',
-      }).unwrap();
-      toast.success(t.interestSubmitted);
-    } catch {
-      toast.error(t.interestError);
-    }
-  }
-
-  return (
-    <Card>
-      <CardHeader>
-        <CardTitle className="flex items-center gap-1.5">
-          <KeyRoundIcon className="size-4 text-teal-600" />
-          {t.table.unit} {unit.unitNumber}
-        </CardTitle>
-        <CardDescription className="flex items-center gap-1.5">
-          <MapPinIcon className="size-3.5 shrink-0" />
-          {unit.buildingName} · {unit.floorName}
-        </CardDescription>
-      </CardHeader>
-      <CardContent>
-        <div className="grid grid-cols-3 gap-3 text-center">
-          <div className="flex flex-col items-center gap-1 rounded-lg bg-muted/50 py-2">
-            <BedDoubleIcon className="size-4 text-muted-foreground" />
-            <span className="text-sm font-medium">{unit.bedrooms}</span>
-            <span className="text-[11px] text-muted-foreground">
-              {t.table.bedrooms}
-            </span>
-          </div>
-          <div className="flex flex-col items-center gap-1 rounded-lg bg-muted/50 py-2">
-            <HomeIcon className="size-4 text-muted-foreground" />
-            <span className="text-sm font-medium">{unit.bathrooms}</span>
-            <span className="text-[11px] text-muted-foreground">
-              {t.table.bathrooms}
-            </span>
-          </div>
-          <div className="flex flex-col items-center gap-1 rounded-lg bg-muted/50 py-2">
-            <span className="text-sm font-medium">{unit.sqft ?? '—'}</span>
-            <span className="text-[11px] text-muted-foreground">
-              {t.table.sqft}
-            </span>
-          </div>
-        </div>
-      </CardContent>
-      <CardFooter>
-        <Button
-          className="w-full"
-          onClick={handleExpressInterest}
-          disabled={submitting}
-        >
-          {submitting ? t.submitting : t.expressInterest}
-        </Button>
-      </CardFooter>
-    </Card>
-  );
-}
-
-// ── Main component ────────────────────────────────────────────────────────────
-
-interface AvailableUnitsPageProps {
-  locale: string;
-  dict: Dictionary;
-}
-
-export function AvailableUnitsPage({ dict }: AvailableUnitsPageProps) {
-  const t = dict.availableUnits;
-  const { data: units, isLoading, isError } = useGetAvailableUnitsQuery();
-
-  const hasUnits = (units?.length ?? 0) > 0;
-
-  return (
-    <div className="flex flex-col gap-6">
-      {/* Header */}
-      <div>
-        <h1 className="text-2xl font-semibold tracking-tight">{t.title}</h1>
-        <p className="text-sm text-muted-foreground mt-0.5">{t.subtitle}</p>
-      </div>
-
-      {isLoading ? (
-        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
-          {[...Array(6)].map((_, i) => (
-            <Card key={i}>
-              <CardHeader>
-                <Skeleton className="h-5 w-32" />
-                <Skeleton className="h-4 w-40" />
-              </CardHeader>
-              <CardContent>
-                <Skeleton className="h-16 w-full" />
-              </CardContent>
-              <CardFooter>
-                <Skeleton className="h-9 w-full" />
-              </CardFooter>
-            </Card>
-          ))}
-        </div>
-      ) : isError ? (
-        <div className="rounded-xl border bg-card p-10 text-center text-sm text-muted-foreground">
-          {t.loadError}
-        </div>
-      ) : !hasUnits ? (
-        <div className="rounded-xl border bg-card p-10 text-center text-muted-foreground">
-          <HomeIcon className="size-8 mx-auto mb-2 opacity-30" />
-          {t.empty}
-        </div>
-      ) : (
-        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
-          {units?.map((unit) => (
-            <UnitCard key={unit.id} unit={unit} t={t} />
-          ))}
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/apps/web/src/components/dashboard/renters-page.tsx b/apps/web/src/components/dashboard/renters-page.tsx
index 82ad9fe9..e9c92ba6 100644
--- a/apps/web/src/components/dashboard/renters-page.tsx
+++ b/apps/web/src/components/dashboard/renters-page.tsx
@@ -2,7 +2,7 @@
 
 import { useMemo, useState } from 'react';
 import { useRouter } from 'next/navigation';
-import { useForm } from 'react-hook-form';
+import { useForm, Controller } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 import { toast } from 'sonner';
@@ -11,14 +11,19 @@ import {
   MoreHorizontalIcon,
   ContactIcon,
   EyeIcon,
+  EyeOffIcon,
   PencilIcon,
   TrashIcon,
+  CopyIcon,
+  CheckIcon,
+  RefreshCwIcon,
 } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Badge } from '@/components/ui/badge';
+import { Checkbox } from '@/components/ui/checkbox';
 import { Skeleton } from '@/components/ui/skeleton';
 import { Textarea } from '@/components/ui/textarea';
 import {
@@ -34,6 +39,7 @@ import {
   DialogContent,
   DialogHeader,
   DialogTitle,
+  DialogDescription,
   DialogFooter,
   DialogClose,
 } from '@/components/ui/dialog';
@@ -51,7 +57,11 @@ import {
   useUpdateRenterMutation,
   useDeleteRenterMutation,
 } from '@/store/api/endpoints/renters.api';
-import type { RenterEffectiveStatus, RenterResponse } from '@/types/api';
+import type {
+  RenterEffectiveStatus,
+  RenterResponse,
+  ApiErrorEnvelope,
+} from '@/types/api';
 import type { Dictionary } from '@/i18n/get-dictionary';
 
 // ── Status badge ─────────────────────────────────────────────────────────────
@@ -109,6 +119,86 @@ const EMPTY_VALUES: RenterFormValues = {
   notes: '',
 };
 
+// ── Create-only: optional tenant portal login section (Sprint TP1) ───────────
+// An admin creating a renter may also mint a Keycloak tenant login in the same
+// step. `portalEmail`/`portalPassword` are only required when the toggle is on
+// — enforced via `superRefine` so the base `RenterFormValues` shape (shared
+// with the edit form, which has no portal-login section) stays untouched.
+function buildCreateRenterSchema(t: Dictionary['renters']['dialog']) {
+  return buildRenterSchema(t)
+    .extend({
+      createPortalLogin: z.boolean(),
+      portalEmail: z.string().optional(),
+      portalPassword: z.string().optional(),
+    })
+    .superRefine((values, ctx) => {
+      if (!values.createPortalLogin) return;
+
+      const email = values.portalEmail?.trim() ?? '';
+      if (!email) {
+        ctx.addIssue({
+          code: 'custom',
+          message: t.portalLogin.emailRequired,
+          path: ['portalEmail'],
+        });
+      } else if (!z.string().email().safeParse(email).success) {
+        ctx.addIssue({
+          code: 'custom',
+          message: t.portalLogin.invalidEmail,
+          path: ['portalEmail'],
+        });
+      }
+
+      const password = values.portalPassword ?? '';
+      if (!password) {
+        ctx.addIssue({
+          code: 'custom',
+          message: t.portalLogin.passwordRequired,
+          path: ['portalPassword'],
+        });
+      } else if (password.length < 8) {
+        ctx.addIssue({
+          code: 'custom',
+          message: t.portalLogin.passwordMinLength,
+          path: ['portalPassword'],
+        });
+      }
+    });
+}
+
+type CreateRenterFormValues = z.infer<
+  ReturnType<typeof buildCreateRenterSchema>
+>;
+
+const CREATE_EMPTY_VALUES: CreateRenterFormValues = {
+  ...EMPTY_VALUES,
+  createPortalLogin: false,
+  portalEmail: '',
+  portalPassword: '',
+};
+
+const PASSWORD_CHARS =
+  'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnpqrstuvwxyz23456789!@#$%';
+
+/**
+ * A strong, random password for the "Generate" button. Avoids visually
+ * ambiguous characters (0/O, 1/l/I) since an admin may need to read it aloud
+ * or retype it for the tenant.
+ */
+function generateStrongPassword(length = 14): string {
+  const bytes = new Uint32Array(length);
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < length; i++) {
+      bytes[i] = Math.floor(Math.random() * PASSWORD_CHARS.length);
+    }
+  }
+  return Array.from(bytes, (n) => PASSWORD_CHARS[n % PASSWORD_CHARS.length]).join(
+    '',
+  );
+}
+
 // ── Main component ────────────────────────────────────────────────────────────
 
 interface RentersPageProps {
@@ -129,17 +219,32 @@ export function RentersPage({ canWrite, locale, dict }: RentersPageProps) {
   const [createOpen, setCreateOpen] = useState(false);
   const [editTarget, setEditTarget] = useState<RenterResponse | null>(null);
   const [deleteTarget, setDeleteTarget] = useState<RenterResponse | null>(null);
+  const [showPortalPassword, setShowPortalPassword] = useState(false);
+  // Set once, right after a successful create-with-login — shown exactly once
+  // for handoff to the tenant, then discarded (never persisted or refetched).
+  const [portalCredentials, setPortalCredentials] = useState<{
+    email: string;
+    password: string;
+  } | null>(null);
 
   const renterSchema = useMemo(() => buildRenterSchema(t.dialog), [t.dialog]);
+  const createRenterSchema = useMemo(
+    () => buildCreateRenterSchema(t.dialog),
+    [t.dialog],
+  );
 
   const {
     register: regCreate,
     handleSubmit: handleCreate,
     reset: resetCreate,
+    control: controlCreate,
+    watch: watchCreate,
+    getValues: getCreateValues,
+    setValue: setCreateValue,
     formState: { errors: createErrors },
-  } = useForm<RenterFormValues>({
-    resolver: zodResolver(renterSchema),
-    defaultValues: EMPTY_VALUES,
+  } = useForm<CreateRenterFormValues>({
+    resolver: zodResolver(createRenterSchema),
+    defaultValues: CREATE_EMPTY_VALUES,
   });
 
   const {
@@ -152,11 +257,28 @@ export function RentersPage({ canWrite, locale, dict }: RentersPageProps) {
     defaultValues: EMPTY_VALUES,
   });
 
+  const createPortalLogin = watchCreate('createPortalLogin');
+
   function goToRenter(renterId: string) {
     router.push(`/${locale}/dashboard/renters/${renterId}`);
   }
 
-  async function onCreateSubmit(values: RenterFormValues) {
+  function closeCreateDialog() {
+    setCreateOpen(false);
+    setShowPortalPassword(false);
+    resetCreate(CREATE_EMPTY_VALUES);
+  }
+
+  async function onCreateSubmit(values: CreateRenterFormValues) {
+    // Only forward portalLogin when the toggle is on AND both fields passed
+    // validation — guards against a stale/partial value if the toggle was
+    // flipped off after typing.
+    const portalEmail = values.createPortalLogin
+      ? (values.portalEmail?.trim() ?? '')
+      : '';
+    const portalPassword = values.createPortalLogin
+      ? (values.portalPassword ?? '')
+      : '';
     try {
       await createRenter({
         fullName: values.fullName,
@@ -165,12 +287,29 @@ export function RentersPage({ canWrite, locale, dict }: RentersPageProps) {
         emergencyContactName: values.emergencyContactName || undefined,
         emergencyContactPhone: values.emergencyContactPhone || undefined,
         notes: values.notes || undefined,
+        ...(portalEmail && portalPassword
+          ? { portalLogin: { email: portalEmail, password: portalPassword } }
+          : {}),
       }).unwrap();
       toast.success(t.dialog.createdToast);
       setCreateOpen(false);
-      resetCreate(EMPTY_VALUES);
-    } catch {
-      toast.error(t.dialog.createErrorToast);
+      setShowPortalPassword(false);
+      if (portalEmail && portalPassword) {
+        // Hand off the credentials once — the dialog close resets the form,
+        // so this is the only place they're readable after this point.
+        setPortalCredentials({ email: portalEmail, password: portalPassword });
+      }
+      resetCreate(CREATE_EMPTY_VALUES);
+    } catch (err) {
+      const apiErr = err as Partial<ApiErrorEnvelope>;
+      if (portalEmail && apiErr?.status === 409) {
+        // Keycloak username (email) already taken — dialog stays open (we
+        // never call setCreateOpen(false) on this path) so the admin can fix
+        // the email and resubmit.
+        toast.error(t.dialog.portalLogin.emailConflictError);
+      } else {
+        toast.error(t.dialog.createErrorToast);
+      }
     }
   }
 
@@ -378,7 +517,13 @@ export function RentersPage({ canWrite, locale, dict }: RentersPageProps) {
       </div>
 
       {/* ── Create Renter Dialog ───────────────────────────────────────────── */}
-      <Dialog open={createOpen} onOpenChange={setCreateOpen}>
+      <Dialog
+        open={createOpen}
+        onOpenChange={(open) => {
+          if (open) setCreateOpen(true);
+          else closeCreateDialog();
+        }}
+      >
         <DialogContent className="sm:max-w-md">
           <DialogHeader>
             <DialogTitle>{t.dialog.addTitle}</DialogTitle>
@@ -389,17 +534,141 @@ export function RentersPage({ canWrite, locale, dict }: RentersPageProps) {
           >
             <RenterFormFields
               idPrefix="r"
-              register={regCreate}
+              // `regCreate` is `UseFormRegister<CreateRenterFormValues>`, a
+              // strict superset of `RenterFormValues` (same base fields, plus
+              // the portal-login ones). `RenterFormFields` only ever
+              // registers the shared base fields, so this is safe — but TS
+              // can't verify cross-form-shape register() assignability on
+              // its own.
+              register={
+                regCreate as unknown as ReturnType<
+                  typeof useForm<RenterFormValues>
+                >['register']
+              }
               errors={createErrors}
               t={t.dialog}
             />
+
+            {/* ── Optional tenant portal login (Sprint TP1) ─────────────── */}
+            <div className="flex flex-col gap-3 rounded-lg border p-3">
+              <div className="flex items-start gap-2">
+                <Controller
+                  control={controlCreate}
+                  name="createPortalLogin"
+                  render={({ field }) => (
+                    <Checkbox
+                      id="r-create-portal-login"
+                      checked={field.value}
+                      onCheckedChange={(checked) => {
+                        const next = checked === true;
+                        field.onChange(next);
+                        // Prefill the login email from the renter's own
+                        // email, if any — only when the admin hasn't already
+                        // typed one in.
+                        if (next && !getCreateValues('portalEmail')) {
+                          const baseEmail = getCreateValues('email');
+                          if (baseEmail) {
+                            setCreateValue('portalEmail', baseEmail);
+                          }
+                        }
+                      }}
+                      className="mt-0.5"
+                    />
+                  )}
+                />
+                <div className="flex flex-col gap-0.5">
+                  <Label
+                    htmlFor="r-create-portal-login"
+                    className="font-normal"
+                  >
+                    {t.dialog.portalLogin.toggleLabel}
+                  </Label>
+                  <p className="text-xs text-muted-foreground">
+                    {t.dialog.portalLogin.toggleHelp}
+                  </p>
+                </div>
+              </div>
+
+              {createPortalLogin && (
+                <div className="flex flex-col gap-3 ps-6">
+                  <div className="flex flex-col gap-1.5">
+                    <Label htmlFor="r-portal-email">
+                      {t.dialog.portalLogin.emailLabel}{' '}
+                      <span className="text-destructive">*</span>
+                    </Label>
+                    <Input
+                      id="r-portal-email"
+                      type="email"
+                      placeholder={t.dialog.portalLogin.placeholderEmail}
+                      aria-invalid={!!createErrors.portalEmail}
+                      {...regCreate('portalEmail')}
+                    />
+                    {createErrors.portalEmail && (
+                      <p className="text-xs text-destructive">
+                        {createErrors.portalEmail.message}
+                      </p>
+                    )}
+                  </div>
+                  <div className="flex flex-col gap-1.5">
+                    <Label htmlFor="r-portal-password">
+                      {t.dialog.portalLogin.passwordLabel}{' '}
+                      <span className="text-destructive">*</span>
+                    </Label>
+                    <div className="flex items-center gap-1.5">
+                      <div className="relative flex-1">
+                        <Input
+                          id="r-portal-password"
+                          type={showPortalPassword ? 'text' : 'password'}
+                          placeholder={t.dialog.portalLogin.placeholderPassword}
+                          aria-invalid={!!createErrors.portalPassword}
+                          className="pe-9"
+                          {...regCreate('portalPassword')}
+                        />
+                        <Button
+                          type="button"
+                          variant="ghost"
+                          size="icon-sm"
+                          className="absolute inset-y-0 end-0 my-auto"
+                          aria-label={
+                            showPortalPassword
+                              ? t.dialog.portalLogin.hidePassword
+                              : t.dialog.portalLogin.showPassword
+                          }
+                          onClick={() => setShowPortalPassword((prev) => !prev)}
+                        >
+                          {showPortalPassword ? <EyeOffIcon /> : <EyeIcon />}
+                        </Button>
+                      </div>
+                      <Button
+                        type="button"
+                        variant="outline"
+                        size="sm"
+                        onClick={() => {
+                          const generated = generateStrongPassword();
+                          setCreateValue('portalPassword', generated, {
+                            shouldValidate: true,
+                          });
+                          setShowPortalPassword(true);
+                        }}
+                      >
+                        <RefreshCwIcon className="size-3.5" />
+                        {t.dialog.portalLogin.generate}
+                      </Button>
+                    </div>
+                    {createErrors.portalPassword && (
+                      <p className="text-xs text-destructive">
+                        {createErrors.portalPassword.message}
+                      </p>
+                    )}
+                  </div>
+                </div>
+              )}
+            </div>
+
             <DialogFooter>
               <DialogClose
                 render={<Button variant="outline" type="button" />}
-                onClick={() => {
-                  setCreateOpen(false);
-                  resetCreate(EMPTY_VALUES);
-                }}
+                onClick={closeCreateDialog}
               >
                 {dict.common.cancel}
               </DialogClose>
@@ -491,6 +760,97 @@ export function RentersPage({ canWrite, locale, dict }: RentersPageProps) {
           </DialogFooter>
         </DialogContent>
       </Dialog>
+
+      {/* ── Portal Login Credentials (shown once for handoff) ─────────────── */}
+      <Dialog
+        open={!!portalCredentials}
+        onOpenChange={(open) => {
+          if (!open) setPortalCredentials(null);
+        }}
+      >
+        <DialogContent className="sm:max-w-sm">
+          <DialogHeader>
+            <DialogTitle>{t.dialog.portalLogin.successTitle}</DialogTitle>
+            <DialogDescription>
+              {t.dialog.portalLogin.successDescription}
+            </DialogDescription>
+          </DialogHeader>
+          {portalCredentials && (
+            <div className="flex flex-col gap-3">
+              <CredentialRow
+                label={t.dialog.portalLogin.emailFieldLabel}
+                value={portalCredentials.email}
+                copyLabel={t.dialog.portalLogin.copyEmailLabel}
+                copiedText={t.dialog.portalLogin.copied}
+              />
+              <CredentialRow
+                label={t.dialog.portalLogin.passwordFieldLabel}
+                value={portalCredentials.password}
+                copyLabel={t.dialog.portalLogin.copyPasswordLabel}
+                copiedText={t.dialog.portalLogin.copied}
+              />
+            </div>
+          )}
+          <DialogFooter>
+            <DialogClose
+              render={<Button type="button" />}
+              onClick={() => setPortalCredentials(null)}
+            >
+              {t.dialog.portalLogin.done}
+            </DialogClose>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}
+
+// ── Portal login credentials row (copy-to-clipboard) ──────────────────────────
+
+function CredentialRow({
+  label,
+  value,
+  copyLabel,
+  copiedText,
+}: {
+  label: string;
+  value: string;
+  copyLabel: string;
+  copiedText: string;
+}) {
+  const [copied, setCopied] = useState(false);
+
+  async function handleCopy() {
+    try {
+      await navigator.clipboard.writeText(value);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Clipboard API unavailable/denied — the value is still visible to
+      // select and copy manually.
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-1">
+      <Label className="text-xs text-muted-foreground">{label}</Label>
+      <div className="flex items-center gap-1.5">
+        <code className="flex-1 truncate rounded-md border bg-muted px-2 py-1.5 font-mono text-sm">
+          {value}
+        </code>
+        <Button
+          type="button"
+          variant="outline"
+          size="icon-sm"
+          aria-label={copyLabel}
+          onClick={handleCopy}
+        >
+          {copied ? <CheckIcon className="text-green-600" /> : <CopyIcon />}
+        </Button>
+      </div>
+      {copied && (
+        <p className="text-xs text-muted-foreground">{copiedText}</p>
+      )}
     </div>
   );
 }
diff --git a/apps/web/src/components/dashboard/support-page.tsx b/apps/web/src/components/dashboard/support-page.tsx
index e41c305a..c7f4cb32 100644
--- a/apps/web/src/components/dashboard/support-page.tsx
+++ b/apps/web/src/components/dashboard/support-page.tsx
@@ -43,10 +43,14 @@ import type { Dictionary } from '@/i18n/get-dictionary';
 
 // ── Static option lists (labels resolved from the dictionary at render) ───────
 
+// Maintenance is intentionally excluded from the CREATE form: a tenant's
+// category:'maintenance' ticket can never be actioned by the maintenance role
+// (resolve/close excludes them) — the real channel for that is a
+// MaintenanceRequest, not a support ticket. Existing tickets already tagged
+// 'maintenance' still render fine (CATEGORY_STYLES/t.categories keep the key).
 const CATEGORIES: SupportTicketCategory[] = [
   'general',
   'billing',
-  'maintenance',
   'technical',
   'other',
 ];
diff --git a/apps/web/src/components/dashboard/tenant-dashboard.tsx b/apps/web/src/components/dashboard/tenant-dashboard.tsx
deleted file mode 100644
index c266eebe..00000000
--- a/apps/web/src/components/dashboard/tenant-dashboard.tsx
+++ /dev/null
@@ -1,649 +0,0 @@
-'use client';
-
-import { useMemo, useState } from 'react';
-import { useForm, Controller } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
-import { toast } from 'sonner';
-import { formatDistanceToNow } from 'date-fns';
-import { ar } from 'date-fns/locale';
-import {
-  HomeIcon,
-  WalletIcon,
-  ReceiptTextIcon,
-  WrenchIcon,
-  PlusIcon,
-  ClockIcon,
-} from 'lucide-react';
-
-import { useListTimelineQuery } from '@/store/api/endpoints/timeline.api';
-import {
-  useGetTenantOverviewQuery,
-  useCreateTenantMaintenanceRequestMutation,
-} from '@/store/api/endpoints/tenant.api';
-import type {
-  MeResponse,
-  MaintenanceRequestPriority,
-  MaintenanceRequestStatus,
-  InvoiceStatus,
-  LeaseStatus,
-} from '@/types/api';
-import type { Dictionary } from '@/i18n/get-dictionary';
-import { KpiTile, useMoney } from '@/components/dashboard/kpi-tile';
-import { canOpenRequest, balanceTone } from '@/lib/tenant-overview';
-import { Badge } from '@/components/ui/badge';
-import { Button } from '@/components/ui/button';
-import { Skeleton } from '@/components/ui/skeleton';
-import { Label } from '@/components/ui/label';
-import { Input } from '@/components/ui/input';
-import { Textarea } from '@/components/ui/textarea';
-import {
-  Card,
-  CardContent,
-  CardHeader,
-  CardTitle,
-  CardDescription,
-} from '@/components/ui/card';
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from '@/components/ui/select';
-import {
-  Dialog,
-  DialogContent,
-  DialogHeader,
-  DialogTitle,
-  DialogFooter,
-  DialogClose,
-} from '@/components/ui/dialog';
-
-// ── Badge styling (mirrors support-page's status palette) ─────────────────────
-
-const INVOICE_STATUS_STYLES: Record<InvoiceStatus, string> = {
-  open: 'bg-amber-50 text-amber-700 border-amber-200',
-  partially_paid: 'bg-blue-50 text-blue-700 border-blue-200',
-  paid: 'bg-emerald-50 text-emerald-700 border-emerald-200',
-  overdue: 'bg-red-50 text-red-700 border-red-200',
-};
-
-const REQUEST_STATUS_STYLES: Record<MaintenanceRequestStatus, string> = {
-  open: 'bg-amber-50 text-amber-700 border-amber-200',
-  in_progress: 'bg-blue-50 text-blue-700 border-blue-200',
-  resolved: 'bg-emerald-50 text-emerald-700 border-emerald-200',
-  closed: 'bg-muted text-muted-foreground border-transparent',
-};
-
-const PRIORITY_STYLES: Record<MaintenanceRequestPriority, string> = {
-  low: 'bg-muted text-muted-foreground border-transparent',
-  medium: 'bg-blue-50 text-blue-700 border-blue-200',
-  high: 'bg-orange-50 text-orange-700 border-orange-200',
-  urgent: 'bg-red-50 text-red-700 border-red-200',
-};
-
-const PRIORITIES: MaintenanceRequestPriority[] = [
-  'low',
-  'medium',
-  'high',
-  'urgent',
-];
-
-const OPEN_STATUSES: MaintenanceRequestStatus[] = ['open', 'in_progress'];
-
-// ── Form ──────────────────────────────────────────────────────────────────────
-
-type RequestFormValues = {
-  title: string;
-  description: string;
-  priority: MaintenanceRequestPriority;
-};
-
-const EMPTY_VALUES: RequestFormValues = {
-  title: '',
-  description: '',
-  priority: 'medium',
-};
-
-interface TenantDashboardProps {
-  me: MeResponse | null;
-  locale: string;
-  dict: Dictionary;
-}
-
-export function TenantDashboard({ me, locale, dict }: TenantDashboardProps) {
-  const isAr = locale === 'ar';
-  const t = dict.dashboard.tenant;
-  const money = useMoney(locale);
-
-  const {
-    data: overview,
-    isLoading,
-    isError,
-  } = useGetTenantOverviewQuery();
-  const [createRequest, { isLoading: creating }] =
-    useCreateTenantMaintenanceRequestMutation();
-  const { data: timelineData, isLoading: timelineLoading } =
-    useListTimelineQuery({ limit: 5 });
-
-  const [createOpen, setCreateOpen] = useState(false);
-
-  const dateFmt = useMemo(
-    () =>
-      new Intl.DateTimeFormat(locale, {
-        year: 'numeric',
-        month: 'short',
-        day: 'numeric',
-      }),
-    [locale],
-  );
-  const fmtDate = (iso: string) => dateFmt.format(new Date(iso));
-
-  const schema = useMemo(
-    () =>
-      z.object({
-        title: z.string().trim().min(1, t.form.titleRequired),
-        description: z.string(),
-        priority: z.enum(['low', 'medium', 'high', 'urgent']),
-      }),
-    [t],
-  );
-
-  const {
-    register,
-    control,
-    handleSubmit,
-    reset,
-    formState: { errors },
-  } = useForm<RequestFormValues>({
-    resolver: zodResolver(schema),
-    defaultValues: EMPTY_VALUES,
-  });
-
-  const events = timelineData?.items ?? [];
-  const requests = overview?.maintenanceRequests ?? [];
-  const openCount = requests.filter((r) =>
-    OPEN_STATUSES.includes(r.status),
-  ).length;
-  const canOpen = canOpenRequest(overview);
-
-  async function onSubmit(values: RequestFormValues) {
-    try {
-      await createRequest({
-        title: values.title.trim(),
-        description: values.description.trim() || undefined,
-        priority: values.priority,
-      }).unwrap();
-      toast.success(t.requests.created);
-      setCreateOpen(false);
-      reset(EMPTY_VALUES);
-    } catch {
-      toast.error(t.requests.createError);
-    }
-  }
-
-  // ── Header ──────────────────────────────────────────────────────────────────
-  const header = (
-    <Card>
-      <CardHeader>
-        <CardTitle className="text-2xl font-semibold tracking-tight">
-          {`${t.welcome}${me?.user?.fullName ? `, ${me.user.fullName}` : ''}`}
-        </CardTitle>
-        <CardDescription>
-          {me?.org?.name ? `${t.subtitle} · ${me.org.name}` : t.subtitle}
-        </CardDescription>
-      </CardHeader>
-    </Card>
-  );
-
-  if (isLoading) {
-    return (
-      <div className="flex flex-col gap-6">
-        {header}
-        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-          <Skeleton className="h-28 rounded-xl" />
-          <Skeleton className="h-28 rounded-xl" />
-          <Skeleton className="h-28 rounded-xl" />
-        </div>
-        <Skeleton className="h-48 rounded-xl" />
-      </div>
-    );
-  }
-
-  if (isError) {
-    return (
-      <div className="flex flex-col gap-6">
-        {header}
-        <div className="rounded-xl border bg-card p-10 text-center text-sm text-muted-foreground">
-          {t.loadError}
-        </div>
-      </div>
-    );
-  }
-
-  // Not linked yet — warm empty state, no numbers.
-  if (!overview?.linked) {
-    return (
-      <div className="flex flex-col gap-6">
-        {header}
-        <Card className="border border-dashed border-muted-foreground/20 bg-muted/10">
-          <CardContent className="flex flex-col items-center justify-center gap-4 py-12 text-center">
-            <HomeIcon className="h-10 w-10 text-primary/50" />
-            <div className="flex flex-col gap-1">
-              <p className="font-medium text-foreground">{t.notLinkedTitle}</p>
-              <p className="max-w-sm text-sm text-muted-foreground">
-                {t.notLinkedDesc}
-              </p>
-            </div>
-          </CardContent>
-        </Card>
-        <ActivityCard
-          title={t.yourActivity}
-          empty={dict.dashboard.noActivity}
-          loading={timelineLoading}
-          events={events}
-          isAr={isAr}
-        />
-      </div>
-    );
-  }
-
-  const lease = overview.lease;
-  const balance = overview.balance;
-  const invoices = overview.invoices;
-
-  return (
-    <div className="flex flex-col gap-6">
-      {header}
-
-      {/* KPI row */}
-      <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-        <KpiTile
-          label={t.balance.outstanding}
-          value={money.format(parseFloat(balance.outstanding))}
-          tone={balanceTone(balance.outstanding)}
-          icon={<WalletIcon className="size-4" />}
-          hint={
-            balanceTone(balance.outstanding) === 'negative'
-              ? t.balance.due
-              : t.balance.settled
-          }
-        />
-        <KpiTile
-          label={t.balance.paid}
-          value={money.format(parseFloat(balance.paid))}
-          icon={<ReceiptTextIcon className="size-4" />}
-        />
-        <KpiTile
-          label={t.requests.openTitle}
-          value={openCount}
-          icon={<WrenchIcon className="size-4" />}
-          hint={t.requests.ofTotal.replace('{count}', String(requests.length))}
-        />
-      </div>
-
-      {/* My lease */}
-      <Card>
-        <CardHeader>
-          <CardTitle className="text-base font-semibold">
-            {t.lease.title}
-          </CardTitle>
-        </CardHeader>
-        <CardContent>
-          {lease ? (
-            <div className="grid gap-x-8 gap-y-4 sm:grid-cols-2 lg:grid-cols-3">
-              <Field label={t.lease.unit}>
-                {lease.unitNumber}
-                <span className="text-muted-foreground">
-                  {' · '}
-                  {lease.buildingName}
-                </span>
-              </Field>
-              <Field label={t.lease.status}>
-                <LeaseStatusBadge status={lease.effectiveStatus} dict={dict} />
-              </Field>
-              <Field label={t.lease.term}>
-                {fmtDate(lease.startDate)}
-                {` ${t.lease.to} `}
-                {fmtDate(lease.endDate)}
-              </Field>
-              <Field label={t.lease.rent}>
-                <span className="tabular-nums">
-                  {money.format(parseFloat(lease.rentAmount))}
-                </span>
-              </Field>
-              <Field label={t.lease.deposit}>
-                <span className="tabular-nums">
-                  {money.format(parseFloat(lease.depositAmount))}
-                </span>
-              </Field>
-            </div>
-          ) : (
-            <p className="text-sm text-muted-foreground">{t.lease.none}</p>
-          )}
-        </CardContent>
-      </Card>
-
-      {/* My invoices */}
-      <Card>
-        <CardHeader>
-          <CardTitle className="text-base font-semibold">
-            {t.invoices.title}
-          </CardTitle>
-        </CardHeader>
-        <CardContent>
-          {invoices.length === 0 ? (
-            <p className="text-sm text-muted-foreground">
-              <ReceiptTextIcon className="size-8 mx-auto mb-2 opacity-30" />
-              {t.invoices.empty}
-            </p>
-          ) : (
-            <div className="overflow-x-auto">
-              <table className="w-full text-sm">
-                <thead>
-                  <tr className="border-b text-start text-xs text-muted-foreground">
-                    <th className="py-2 pe-4 text-start font-medium">
-                      {t.invoices.dueDate}
-                    </th>
-                    <th className="py-2 pe-4 text-end font-medium">
-                      {t.invoices.invoiced}
-                    </th>
-                    <th className="py-2 pe-4 text-end font-medium">
-                      {t.invoices.paid}
-                    </th>
-                    <th className="py-2 pe-4 text-end font-medium">
-                      {t.invoices.balance}
-                    </th>
-                    <th className="py-2 text-start font-medium">
-                      {t.invoices.status}
-                    </th>
-                  </tr>
-                </thead>
-                <tbody>
-                  {invoices.map((inv) => (
-                    <tr key={inv.id} className="border-b last:border-0">
-                      <td className="py-2 pe-4">{fmtDate(inv.dueDate)}</td>
-                      <td className="py-2 pe-4 text-end tabular-nums">
-                        {money.format(parseFloat(inv.invoiced))}
-                      </td>
-                      <td className="py-2 pe-4 text-end tabular-nums">
-                        {money.format(parseFloat(inv.paid))}
-                      </td>
-                      <td className="py-2 pe-4 text-end tabular-nums">
-                        {money.format(parseFloat(inv.balance))}
-                      </td>
-                      <td className="py-2">
-                        <Badge
-                          variant="outline"
-                          className={INVOICE_STATUS_STYLES[inv.status]}
-                        >
-                          {t.invoiceStatus[inv.status]}
-                        </Badge>
-                      </td>
-                    </tr>
-                  ))}
-                </tbody>
-              </table>
-            </div>
-          )}
-        </CardContent>
-      </Card>
-
-      {/* My maintenance requests */}
-      <Card>
-        <CardHeader className="flex flex-row items-center justify-between gap-2">
-          <CardTitle className="text-base font-semibold">
-            {t.requests.title}
-          </CardTitle>
-          <Button
-            size="sm"
-            disabled={!canOpen}
-            onClick={() => {
-              reset(EMPTY_VALUES);
-              setCreateOpen(true);
-            }}
-          >
-            <PlusIcon className="size-3.5" />
-            {t.requests.new}
-          </Button>
-        </CardHeader>
-        <CardContent>
-          {!canOpen && (
-            <p className="mb-3 text-xs text-muted-foreground">
-              {t.requests.noLease}
-            </p>
-          )}
-          {requests.length === 0 ? (
-            <p className="text-sm text-muted-foreground">
-              <WrenchIcon className="size-8 mx-auto mb-2 opacity-30" />
-              {canOpen ? t.requests.emptyActive : t.requests.empty}
-            </p>
-          ) : (
-            <ul className="flex flex-col gap-3">
-              {requests.map((r) => (
-                <li
-                  key={r.id}
-                  className="flex flex-col gap-2 rounded-lg border p-3"
-                >
-                  <div className="flex flex-wrap items-center gap-2">
-                    <Badge
-                      variant="outline"
-                      className={REQUEST_STATUS_STYLES[r.status]}
-                    >
-                      {t.requestStatus[r.status]}
-                    </Badge>
-                    <Badge
-                      variant="outline"
-                      className={PRIORITY_STYLES[r.priority]}
-                    >
-                      {t.priority[r.priority]}
-                    </Badge>
-                    <span className="ms-auto text-xs text-muted-foreground">
-                      {t.requests.unit} {r.unitNumber} · {fmtDate(r.createdAt)}
-                    </span>
-                  </div>
-                  <p className="text-sm font-medium text-foreground">
-                    {r.title}
-                  </p>
-                  {r.description && (
-                    <p className="line-clamp-2 text-sm text-muted-foreground">
-                      {r.description}
-                    </p>
-                  )}
-                </li>
-              ))}
-            </ul>
-          )}
-        </CardContent>
-      </Card>
-
-      {/* Your activity */}
-      <ActivityCard
-        title={t.yourActivity}
-        empty={dict.dashboard.noActivity}
-        loading={timelineLoading}
-        events={events}
-        isAr={isAr}
-      />
-
-      {/* Create request dialog */}
-      <Dialog open={createOpen} onOpenChange={setCreateOpen}>
-        <DialogContent className="sm:max-w-md">
-          <DialogHeader>
-            <DialogTitle>{t.form.title}</DialogTitle>
-          </DialogHeader>
-          <form
-            onSubmit={handleSubmit(onSubmit)}
-            className="flex flex-col gap-4"
-          >
-            <div className="flex flex-col gap-1.5">
-              <Label htmlFor="tmr-title">
-                {t.form.titleLabel}{' '}
-                <span className="text-destructive">*</span>
-              </Label>
-              <Input
-                id="tmr-title"
-                placeholder={t.form.titlePlaceholder}
-                aria-invalid={!!errors.title}
-                {...register('title')}
-              />
-              {errors.title && (
-                <p className="text-xs text-destructive">
-                  {errors.title.message}
-                </p>
-              )}
-            </div>
-
-            <div className="flex flex-col gap-1.5">
-              <Label htmlFor="tmr-priority">{t.form.priorityLabel}</Label>
-              <Controller
-                control={control}
-                name="priority"
-                render={({ field }) => (
-                  <Select value={field.value} onValueChange={field.onChange}>
-                    <SelectTrigger id="tmr-priority" className="w-full">
-                      <SelectValue>
-                        {(value) =>
-                          t.priority[value as MaintenanceRequestPriority] ??
-                          value
-                        }
-                      </SelectValue>
-                    </SelectTrigger>
-                    <SelectContent>
-                      {PRIORITIES.map((p) => (
-                        <SelectItem key={p} value={p}>
-                          {t.priority[p]}
-                        </SelectItem>
-                      ))}
-                    </SelectContent>
-                  </Select>
-                )}
-              />
-            </div>
-
-            <div className="flex flex-col gap-1.5">
-              <Label htmlFor="tmr-desc">{t.form.descriptionLabel}</Label>
-              <Textarea
-                id="tmr-desc"
-                rows={4}
-                placeholder={t.form.descriptionPlaceholder}
-                {...register('description')}
-              />
-            </div>
-
-            <DialogFooter>
-              <DialogClose
-                render={<Button variant="outline" type="button" />}
-                onClick={() => {
-                  setCreateOpen(false);
-                  reset(EMPTY_VALUES);
-                }}
-              >
-                {t.form.cancel}
-              </DialogClose>
-              <Button type="submit" disabled={creating}>
-                {creating ? t.form.submitting : t.form.submit}
-              </Button>
-            </DialogFooter>
-          </form>
-        </DialogContent>
-      </Dialog>
-    </div>
-  );
-}
-
-// ── Small presentational helpers ──────────────────────────────────────────────
-
-function Field({
-  label,
-  children,
-}: {
-  label: string;
-  children: React.ReactNode;
-}) {
-  return (
-    <div className="flex flex-col gap-0.5">
-      <span className="text-xs text-muted-foreground">{label}</span>
-      <span className="text-sm font-medium text-foreground">{children}</span>
-    </div>
-  );
-}
-
-function LeaseStatusBadge({
-  status,
-  dict,
-}: {
-  status: LeaseStatus;
-  dict: Dictionary;
-}) {
-  const styles: Record<LeaseStatus, string> = {
-    draft: 'bg-muted text-muted-foreground border-transparent',
-    active: 'bg-emerald-50 text-emerald-700 border-emerald-200',
-    expired: 'bg-amber-50 text-amber-700 border-amber-200',
-    terminated: 'bg-muted text-muted-foreground border-transparent',
-  };
-  return (
-    <Badge variant="outline" className={styles[status]}>
-      {dict.dashboard.tenant.leaseStatus[status]}
-    </Badge>
-  );
-}
-
-function ActivityCard({
-  title,
-  empty,
-  loading,
-  events,
-  isAr,
-}: {
-  title: string;
-  empty: string;
-  loading: boolean;
-  events: { id: string; action: string; createdAt: string }[];
-  isAr: boolean;
-}) {
-  return (
-    <Card>
-      <CardHeader>
-        <CardTitle className="text-base font-semibold">{title}</CardTitle>
-      </CardHeader>
-      <CardContent>
-        {loading ? (
-          <div className="flex flex-col gap-3">
-            {[0, 1, 2].map((i) => (
-              <div key={i} className="flex flex-col gap-1.5">
-                <Skeleton className="h-4 w-3/4" />
-                <Skeleton className="h-3 w-1/4" />
-              </div>
-            ))}
-          </div>
-        ) : events.length === 0 ? (
-          <p className="text-sm text-muted-foreground">
-            <ClockIcon className="size-8 mx-auto mb-2 opacity-30" />
-            {empty}
-          </p>
-        ) : (
-          <ul className="flex flex-col gap-3">
-            {events.map((event) => (
-              <li key={event.id} className="flex flex-col gap-0.5">
-                <p className="text-sm font-medium text-foreground">
-                  {(() => {
-                    const h = event.action.replace(/\./g, ' ');
-                    return h.charAt(0).toUpperCase() + h.slice(1);
-                  })()}
-                </p>
-                <p className="text-xs text-muted-foreground">
-                  {formatDistanceToNow(new Date(event.createdAt), {
-                    addSuffix: true,
-                    locale: isAr ? ar : undefined,
-                  })}
-                </p>
-              </li>
-            ))}
-          </ul>
-        )}
-      </CardContent>
-    </Card>
-  );
-}
diff --git a/apps/web/src/components/layout/dashboard-sidebar.tsx b/apps/web/src/components/layout/dashboard-sidebar.tsx
index 3464e823..809338e7 100644
--- a/apps/web/src/components/layout/dashboard-sidebar.tsx
+++ b/apps/web/src/components/layout/dashboard-sidebar.tsx
@@ -23,7 +23,6 @@ import {
   LifeBuoy,
   ScrollText,
   Bell,
-  KeyRound,
 } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
@@ -94,13 +93,6 @@ function buildNavItems(
       href: `/${locale}/dashboard/leases`,
       areaKey: 'leases',
     },
-    {
-      key: 'availableUnits',
-      label: dict.nav.availableUnits,
-      icon: KeyRound,
-      href: `/${locale}/dashboard/available-units`,
-      areaKey: 'availableUnits',
-    },
     {
       key: 'vendors',
       label: dict.nav.vendors,
diff --git a/apps/web/src/components/portal/portal-available-units.tsx b/apps/web/src/components/portal/portal-available-units.tsx
new file mode 100644
index 00000000..b9e6c90b
--- /dev/null
+++ b/apps/web/src/components/portal/portal-available-units.tsx
@@ -0,0 +1,148 @@
+'use client';
+
+import {
+  KeyRoundIcon,
+  BuildingIcon,
+  BedDoubleIcon,
+  BathIcon,
+  RulerIcon,
+  Building2Icon,
+} from 'lucide-react';
+
+import { useGetAvailableUnitsQuery } from '@/store/api/endpoints/available-units.api';
+import type { AvailableUnit } from '@/types/api';
+import type { Dictionary } from '@/i18n/get-dictionary';
+import { getPortalDict, type PortalDict } from '@/components/portal/portal-dict';
+import { Skeleton } from '@/components/ui/skeleton';
+import { Card, CardContent } from '@/components/ui/card';
+
+type Props = {
+  locale: string;
+  dict: Dictionary;
+};
+
+export function PortalAvailableUnits({ locale, dict }: Props) {
+  const t = getPortalDict(dict, locale);
+  const { data: units, isLoading, isError } = useGetAvailableUnitsQuery();
+
+  return (
+    <div className="flex flex-col gap-6">
+      <header className="flex flex-col gap-1">
+        <h1 className="flex items-center gap-2 text-xl font-semibold tracking-tight text-foreground">
+          <KeyRoundIcon className="size-5 text-amber-600 dark:text-amber-400" />
+          {t.availableUnits.title}
+        </h1>
+        <p className="text-sm text-muted-foreground">
+          {t.availableUnits.subtitle}
+        </p>
+      </header>
+
+      {isLoading ? (
+        <div className="grid gap-4 sm:grid-cols-2">
+          <Skeleton className="h-44 rounded-xl" />
+          <Skeleton className="h-44 rounded-xl" />
+          <Skeleton className="h-44 rounded-xl" />
+          <Skeleton className="h-44 rounded-xl" />
+        </div>
+      ) : isError ? (
+        <Card className="ring-amber-200/50 dark:ring-amber-900/30">
+          <CardContent className="py-10 text-center text-sm text-muted-foreground">
+            {t.availableUnits.loadError}
+          </CardContent>
+        </Card>
+      ) : !units || units.length === 0 ? (
+        <Card className="border-dashed ring-amber-200/60 dark:ring-amber-900/30">
+          <CardContent className="flex flex-col items-center justify-center gap-3 py-12 text-center">
+            <span className="flex size-14 items-center justify-center rounded-2xl bg-amber-100 text-amber-600 dark:bg-amber-400/15 dark:text-amber-300">
+              <Building2Icon className="size-7" />
+            </span>
+            <p className="max-w-sm text-sm text-muted-foreground">
+              {t.availableUnits.empty}
+            </p>
+          </CardContent>
+        </Card>
+      ) : (
+        <ul className="grid gap-4 sm:grid-cols-2">
+          {units.map((unit) => (
+            <li key={unit.id}>
+              <UnitCard unit={unit} t={t} />
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+// Pure display — no "express interest", no actions of any kind (per TP3 scope).
+function UnitCard({ unit, t }: { unit: AvailableUnit; t: PortalDict }) {
+  return (
+    <Card className="h-full ring-foreground/10">
+      <CardContent className="flex h-full flex-col gap-4">
+        <div className="flex items-start gap-3">
+          <span className="flex size-10 shrink-0 items-center justify-center rounded-xl bg-gradient-to-br from-amber-400 to-orange-500 text-white">
+            <KeyRoundIcon className="size-5" />
+          </span>
+          <div className="flex min-w-0 flex-col">
+            <span className="truncate text-sm font-semibold text-foreground">
+              {t.support.unit} {unit.unitNumber}
+            </span>
+            <span className="flex items-center gap-1 truncate text-xs text-muted-foreground">
+              <BuildingIcon className="size-3.5" />
+              {unit.buildingName}
+            </span>
+          </div>
+        </div>
+
+        <dl className="grid grid-cols-2 gap-x-4 gap-y-3 border-t border-border/60 pt-4">
+          <Spec
+            icon={<Building2Icon className="size-4" />}
+            label={t.availableUnits.floor}
+            value={unit.floorName}
+          />
+          <Spec
+            icon={<BedDoubleIcon className="size-4" />}
+            label={t.availableUnits.bedrooms}
+            value={String(unit.bedrooms)}
+          />
+          <Spec
+            icon={<BathIcon className="size-4" />}
+            label={t.availableUnits.bathrooms}
+            value={unit.bathrooms}
+          />
+          {unit.sqft != null && (
+            <Spec
+              icon={<RulerIcon className="size-4" />}
+              label={t.availableUnits.area}
+              value={`${unit.sqft} ${t.availableUnits.sqftUnit}`}
+            />
+          )}
+        </dl>
+      </CardContent>
+    </Card>
+  );
+}
+
+function Spec({
+  icon,
+  label,
+  value,
+}: {
+  icon: React.ReactNode;
+  label: string;
+  value: string;
+}) {
+  return (
+    <div className="flex items-center gap-2.5">
+      <span className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-amber-100 text-amber-600 dark:bg-amber-400/15 dark:text-amber-300">
+        {icon}
+      </span>
+      <div className="flex min-w-0 flex-col">
+        <dt className="text-[11px] text-muted-foreground">{label}</dt>
+        <dd className="truncate text-sm font-medium text-foreground">
+          {value}
+        </dd>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/portal/portal-coming-soon.tsx b/apps/web/src/components/portal/portal-coming-soon.tsx
new file mode 100644
index 00000000..c3ef1a76
--- /dev/null
+++ b/apps/web/src/components/portal/portal-coming-soon.tsx
@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react';
+
+import { Badge } from '@/components/ui/badge';
+import { Card, CardContent } from '@/components/ui/card';
+
+/**
+ * Placeholder surface for portal sections whose content lands in TP3
+ * (available units, support, profile). Server-safe, fully localized by the
+ * caller. Keeps the warm portal tone rather than a bare "404-ish" page.
+ */
+export function PortalComingSoon({
+  icon,
+  badge,
+  title,
+  description,
+}: {
+  icon: ReactNode;
+  badge: string;
+  title: string;
+  description: string;
+}) {
+  return (
+    <Card className="ring-amber-200/50 dark:ring-amber-900/30">
+      <CardContent className="flex flex-col items-center justify-center gap-4 py-14 text-center">
+        <span className="flex size-16 items-center justify-center rounded-2xl bg-amber-100 text-amber-600 dark:bg-amber-400/15 dark:text-amber-300">
+          {icon}
+        </span>
+        <Badge
+          variant="outline"
+          className="border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-900/40 dark:bg-amber-400/10 dark:text-amber-300"
+        >
+          {badge}
+        </Badge>
+        <div className="flex flex-col gap-1">
+          <h1 className="text-lg font-semibold text-foreground">{title}</h1>
+          <p className="max-w-sm text-sm text-muted-foreground">{description}</p>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
diff --git a/apps/web/src/components/portal/portal-dict.fallback.ts b/apps/web/src/components/portal/portal-dict.fallback.ts
new file mode 100644
index 00000000..922579d6
--- /dev/null
+++ b/apps/web/src/components/portal/portal-dict.fallback.ts
@@ -0,0 +1,228 @@
+import type { PortalDict } from '@/components/portal/portal-dict';
+
+/**
+ * Local, dormant fallback for the `portal` i18n namespace (TP2).
+ *
+ * The canonical copy is authored in the TP2 scratchpad and merged into
+ * `en.json` / `ar.json` by the orchestrator. This slice must NOT touch those
+ * catalogs, so — until the merge lands — reading `dict.portal` would be
+ * `undefined` and crash the whole portal. This mirror keeps the shell alive
+ * and is ignored the moment `dict.portal` exists (see `getPortalDict`). Kept
+ * in-scope under `components/portal/**`; safe to delete once the keys ship.
+ */
+export const PORTAL_FALLBACK: Record<'en' | 'ar', PortalDict> = {
+  en: {
+    brandSubtitle: 'Resident portal',
+    nav: {
+      home: 'Home',
+      availableUnits: 'Available units',
+      support: 'Support',
+      profile: 'Profile',
+    },
+    userMenu: {
+      signedInAs: 'Signed in as',
+      profile: 'Profile',
+      signOut: 'Sign out',
+      openMenu: 'Open account menu',
+    },
+    home: {
+      welcome: 'Welcome home',
+      subtitle: 'Your home, at a glance',
+      leaseTitle: 'Your current lease',
+      unit: 'Unit',
+      building: 'Building',
+      status: 'Status',
+      term: 'Lease term',
+      rent: 'Monthly rent',
+      to: 'to',
+      noLease:
+        "You don't have an active lease yet. Your property manager will link one to your account.",
+      notLinkedTitle: "Your account isn't linked yet",
+      notLinkedDesc:
+        "We couldn't find a lease connected to your account. Your property manager will link your unit shortly — check back soon.",
+      loadError:
+        "We couldn't load your home details. Please refresh and try again.",
+      viewSupport: 'Need something? Contact support',
+      historyTitle: 'Your apartments',
+      current: 'Current',
+      deposit: 'Deposit',
+      emptyHistory:
+        'No lease history yet. Once your property manager links a lease, it will appear here.',
+    },
+    leaseStatus: {
+      draft: 'Draft',
+      active: 'Active',
+      expired: 'Expired',
+      terminated: 'Terminated',
+    },
+    availableUnits: {
+      title: 'Available units',
+      subtitle: 'Vacant homes in your community.',
+      empty: 'There are no available units right now. Please check back later.',
+      loadError:
+        "We couldn't load available units. Please refresh and try again.",
+      floor: 'Floor',
+      bedrooms: 'Bedrooms',
+      bathrooms: 'Bathrooms',
+      area: 'Area',
+      sqftUnit: 'sqft',
+    },
+    support: {
+      title: 'Support / Requests',
+      subtitle: 'Raise a maintenance request for your apartment and track it.',
+      new: 'New request',
+      noLease:
+        'You need an active lease before you can open a maintenance request.',
+      empty: 'You have no requests yet.',
+      emptyActive: 'You have no requests yet. Open one whenever you need help.',
+      created: 'Request submitted.',
+      createError: 'Something went wrong. Please try again.',
+      unit: 'Unit',
+      status: {
+        open: 'Open',
+        in_progress: 'In progress',
+        resolved: 'Resolved',
+        closed: 'Closed',
+      },
+      priority: {
+        low: 'Low',
+        medium: 'Medium',
+        high: 'High',
+        urgent: 'Urgent',
+      },
+      form: {
+        title: 'New maintenance request',
+        titleLabel: 'Title',
+        titlePlaceholder: 'e.g. Leaking kitchen tap',
+        titleRequired: 'Please add a short title.',
+        priorityLabel: 'Priority',
+        descriptionLabel: 'Description',
+        descriptionPlaceholder: 'Describe the issue in a little more detail…',
+        cancel: 'Cancel',
+        submit: 'Submit request',
+        submitting: 'Submitting…',
+      },
+    },
+    profile: {
+      changePassword: 'Change password',
+      changePasswordHint:
+        'Update the password you use to sign in to the portal.',
+    },
+    comingSoon: {
+      badge: 'Coming soon',
+      availableUnitsTitle: 'Available units',
+      availableUnitsDesc:
+        "Browse open units in your community. This is on its way — you'll be able to explore available homes here soon.",
+      supportTitle: 'Support & requests',
+      supportDesc:
+        'Raise maintenance requests and track their progress. This space is being prepared for you.',
+      profileTitle: 'Your profile',
+      profileDesc:
+        'View and manage your contact details and account. Coming soon.',
+    },
+  },
+  ar: {
+    brandSubtitle: 'بوابة الساكن',
+    nav: {
+      home: 'الرئيسية',
+      availableUnits: 'الوحدات المتاحة',
+      support: 'الدعم',
+      profile: 'الملف الشخصي',
+    },
+    userMenu: {
+      signedInAs: 'مسجّل الدخول باسم',
+      profile: 'الملف الشخصي',
+      signOut: 'تسجيل الخروج',
+      openMenu: 'فتح قائمة الحساب',
+    },
+    home: {
+      welcome: 'أهلاً بعودتك',
+      subtitle: 'منزلك في لمحة',
+      leaseTitle: 'عقد إيجارك الحالي',
+      unit: 'الوحدة',
+      building: 'المبنى',
+      status: 'الحالة',
+      term: 'مدة العقد',
+      rent: 'الإيجار الشهري',
+      to: 'إلى',
+      noLease:
+        'لا يوجد لديك عقد إيجار نشط بعد. سيقوم مدير العقار بربط عقدك بحسابك قريباً.',
+      notLinkedTitle: 'لم يتم ربط حسابك بعد',
+      notLinkedDesc:
+        'لم نتمكّن من العثور على عقد إيجار مرتبط بحسابك. سيقوم مدير العقار بربط وحدتك قريباً — يرجى المراجعة لاحقاً.',
+      loadError: 'تعذّر تحميل تفاصيل منزلك. يرجى تحديث الصفحة والمحاولة مرة أخرى.',
+      viewSupport: 'تحتاج شيئاً؟ تواصل مع الدعم',
+      historyTitle: 'وحداتك السكنية',
+      current: 'الحالي',
+      deposit: 'التأمين',
+      emptyHistory:
+        'لا يوجد سجل عقود بعد. سيظهر هنا فور قيام مدير العقار بربط عقدك.',
+    },
+    leaseStatus: {
+      draft: 'مسودة',
+      active: 'نشط',
+      expired: 'منتهٍ',
+      terminated: 'مُنهى',
+    },
+    availableUnits: {
+      title: 'الوحدات المتاحة',
+      subtitle: 'الوحدات الشاغرة في مجتمعك.',
+      empty: 'لا توجد وحدات متاحة حالياً. يرجى المراجعة لاحقاً.',
+      loadError: 'تعذّر تحميل الوحدات المتاحة. يرجى تحديث الصفحة والمحاولة مرة أخرى.',
+      floor: 'الطابق',
+      bedrooms: 'غرف النوم',
+      bathrooms: 'الحمّامات',
+      area: 'المساحة',
+      sqftUnit: 'قدم²',
+    },
+    support: {
+      title: 'الدعم / الطلبات',
+      subtitle: 'قدّم طلب صيانة لوحدتك وتابع حالته.',
+      new: 'طلب جديد',
+      noLease: 'تحتاج إلى عقد إيجار نشط قبل أن تتمكّن من فتح طلب صيانة.',
+      empty: 'لا توجد لديك طلبات بعد.',
+      emptyActive: 'لا توجد لديك طلبات بعد. افتح طلباً عندما تحتاج إلى المساعدة.',
+      created: 'تم إرسال الطلب.',
+      createError: 'حدث خطأ ما. يرجى المحاولة مرة أخرى.',
+      unit: 'الوحدة',
+      status: {
+        open: 'مفتوح',
+        in_progress: 'قيد التنفيذ',
+        resolved: 'تم الحل',
+        closed: 'مغلق',
+      },
+      priority: {
+        low: 'منخفضة',
+        medium: 'متوسطة',
+        high: 'عالية',
+        urgent: 'عاجلة',
+      },
+      form: {
+        title: 'طلب صيانة جديد',
+        titleLabel: 'العنوان',
+        titlePlaceholder: 'مثال: تسريب في صنبور المطبخ',
+        titleRequired: 'يرجى إضافة عنوان مختصر.',
+        priorityLabel: 'الأولوية',
+        descriptionLabel: 'الوصف',
+        descriptionPlaceholder: 'صف المشكلة بمزيد من التفصيل…',
+        cancel: 'إلغاء',
+        submit: 'إرسال الطلب',
+        submitting: 'جارٍ الإرسال…',
+      },
+    },
+    profile: {
+      changePassword: 'تغيير كلمة المرور',
+      changePasswordHint: 'حدّث كلمة المرور التي تستخدمها لتسجيل الدخول إلى البوابة.',
+    },
+    comingSoon: {
+      badge: 'قريباً',
+      availableUnitsTitle: 'الوحدات المتاحة',
+      availableUnitsDesc:
+        'تصفّح الوحدات المتاحة في مجتمعك. هذه الميزة في طريقها إليك — ستتمكّن قريباً من استكشاف المنازل المتاحة هنا.',
+      supportTitle: 'الدعم والطلبات',
+      supportDesc: 'قدّم طلبات الصيانة وتابع تقدّمها. نُجهّز هذه المساحة من أجلك.',
+      profileTitle: 'ملفك الشخصي',
+      profileDesc: 'اعرض وأدر بيانات التواصل وحسابك. قريباً.',
+    },
+  },
+};
diff --git a/apps/web/src/components/portal/portal-dict.ts b/apps/web/src/components/portal/portal-dict.ts
new file mode 100644
index 00000000..803dd4a6
--- /dev/null
+++ b/apps/web/src/components/portal/portal-dict.ts
@@ -0,0 +1,129 @@
+import type { Dictionary } from '@/i18n/get-dictionary';
+import { PORTAL_FALLBACK } from '@/components/portal/portal-dict.fallback';
+
+/**
+ * Shape of the `portal` i18n namespace (TP2).
+ *
+ * The keys are authored in the TP2 scratchpad and merged into
+ * `en.json` / `ar.json` by the orchestrator (this slice must not touch the
+ * catalogs). Until they land, `Dictionary` — inferred from `ar.json` — does
+ * not know about `portal`, so we describe the shape here and read it through
+ * `getPortalDict`. This keeps `check-types` green now and resolves at runtime
+ * once the keys are merged, without every component re-casting `dict`.
+ */
+export type PortalDict = {
+  brandSubtitle: string;
+  nav: {
+    home: string;
+    availableUnits: string;
+    support: string;
+    profile: string;
+  };
+  userMenu: {
+    signedInAs: string;
+    profile: string;
+    signOut: string;
+    openMenu: string;
+  };
+  home: {
+    welcome: string;
+    subtitle: string;
+    leaseTitle: string;
+    unit: string;
+    building: string;
+    status: string;
+    term: string;
+    rent: string;
+    to: string;
+    noLease: string;
+    notLinkedTitle: string;
+    notLinkedDesc: string;
+    loadError: string;
+    viewSupport: string;
+    // TP3 — lease history
+    historyTitle: string;
+    current: string;
+    deposit: string;
+    emptyHistory: string;
+  };
+  leaseStatus: {
+    draft: string;
+    active: string;
+    expired: string;
+    terminated: string;
+  };
+  // TP3 — available-units (display-only)
+  availableUnits: {
+    title: string;
+    subtitle: string;
+    empty: string;
+    loadError: string;
+    floor: string;
+    bedrooms: string;
+    bathrooms: string;
+    area: string;
+    sqftUnit: string;
+  };
+  // TP3 — support / requests (apartment-scoped maintenance)
+  support: {
+    title: string;
+    subtitle: string;
+    new: string;
+    noLease: string;
+    empty: string;
+    emptyActive: string;
+    created: string;
+    createError: string;
+    unit: string;
+    status: {
+      open: string;
+      in_progress: string;
+      resolved: string;
+      closed: string;
+    };
+    priority: {
+      low: string;
+      medium: string;
+      high: string;
+      urgent: string;
+    };
+    form: {
+      title: string;
+      titleLabel: string;
+      titlePlaceholder: string;
+      titleRequired: string;
+      priorityLabel: string;
+      descriptionLabel: string;
+      descriptionPlaceholder: string;
+      cancel: string;
+      submit: string;
+      submitting: string;
+    };
+  };
+  // TP3 — profile (shared labels come from `dict.profile`; only the extra
+  // change-password link lives here).
+  profile: {
+    changePassword: string;
+    changePasswordHint: string;
+  };
+  comingSoon: {
+    badge: string;
+    availableUnitsTitle: string;
+    availableUnitsDesc: string;
+    supportTitle: string;
+    supportDesc: string;
+    profileTitle: string;
+    profileDesc: string;
+  };
+};
+
+/**
+ * Read the `portal` namespace off the shared dictionary. Falls back to the
+ * local mirror (per `locale`) while the orchestrator's catalog merge is still
+ * pending, so the portal never white-screens on a missing namespace.
+ */
+export function getPortalDict(dict: Dictionary, locale: string): PortalDict {
+  const merged = (dict as unknown as { portal?: PortalDict }).portal;
+  if (merged) return merged;
+  return PORTAL_FALLBACK[locale === 'ar' ? 'ar' : 'en'];
+}
diff --git a/apps/web/src/components/portal/portal-home.tsx b/apps/web/src/components/portal/portal-home.tsx
new file mode 100644
index 00000000..526eb8ba
--- /dev/null
+++ b/apps/web/src/components/portal/portal-home.tsx
@@ -0,0 +1,246 @@
+'use client';
+
+import { useMemo } from 'react';
+import Link from 'next/link';
+import { HomeIcon, LifeBuoyIcon } from 'lucide-react';
+
+import { useGetTenantOverviewQuery } from '@/store/api/endpoints/tenant.api';
+import type {
+  MeResponse,
+  LeaseStatus,
+  TenantLeaseView,
+  TenantOverviewResponse,
+} from '@/types/api';
+import type { Dictionary } from '@/i18n/get-dictionary';
+import { getPortalDict, type PortalDict } from '@/components/portal/portal-dict';
+import { useMoney } from '@/components/dashboard/kpi-tile';
+import { Badge } from '@/components/ui/badge';
+import { Skeleton } from '@/components/ui/skeleton';
+import { Card, CardContent } from '@/components/ui/card';
+
+type Props = {
+  me: MeResponse | null;
+  userName: string;
+  locale: string;
+  dict: Dictionary;
+};
+
+// Mirrors the tenant-dashboard lease-status palette.
+const LEASE_STATUS_STYLES: Record<LeaseStatus, string> = {
+  draft: 'bg-muted text-muted-foreground border-transparent',
+  active: 'bg-emerald-50 text-emerald-700 border-emerald-200',
+  expired: 'bg-amber-50 text-amber-700 border-amber-200',
+  terminated: 'bg-muted text-muted-foreground border-transparent',
+};
+
+export function PortalHome({ me, userName, locale, dict }: Props) {
+  const t = getPortalDict(dict, locale);
+  const money = useMoney(locale);
+  const { data: overview, isLoading, isError } = useGetTenantOverviewQuery();
+
+  const dateFmt = useMemo(
+    () =>
+      new Intl.DateTimeFormat(locale, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      }),
+    [locale],
+  );
+  const fmtDate = (iso: string) => dateFmt.format(new Date(iso));
+
+  const name = me?.user?.fullName ?? userName;
+  const orgName = me?.org?.name;
+
+  // Newest first; the active/current lease is surfaced first regardless.
+  const currentId = overview?.lease?.id ?? null;
+  const history = useMemo(() => {
+    const list = [...(overview?.leaseHistory ?? [])];
+    list.sort((a, b) => {
+      const aCurrent = a.id === currentId || a.effectiveStatus === 'active';
+      const bCurrent = b.id === currentId || b.effectiveStatus === 'active';
+      if (aCurrent !== bCurrent) return aCurrent ? -1 : 1;
+      return b.startDate.localeCompare(a.startDate);
+    });
+    return list;
+  }, [overview?.leaseHistory, currentId]);
+
+  const hero = (
+    <section className="overflow-hidden rounded-2xl bg-gradient-to-br from-amber-400 via-orange-400 to-orange-500 p-6 text-white shadow-sm sm:p-8">
+      <p className="text-sm font-medium text-white/80">
+        {orgName ?? t.brandSubtitle}
+      </p>
+      <h1 className="mt-1 text-2xl font-semibold tracking-tight sm:text-3xl">
+        {name ? `${t.home.welcome}, ${name}` : t.home.welcome}
+      </h1>
+      <p className="mt-1 text-sm text-white/85">{t.home.subtitle}</p>
+    </section>
+  );
+
+  return (
+    <div className="flex flex-col gap-6">
+      {hero}
+
+      <section className="flex flex-col gap-4">
+        <h2 className="px-1 text-base font-semibold text-foreground">
+          {t.home.historyTitle}
+        </h2>
+
+        {isLoading ? (
+          <div className="flex flex-col gap-4">
+            <Skeleton className="h-40 rounded-xl" />
+            <Skeleton className="h-40 rounded-xl" />
+          </div>
+        ) : isError ? (
+          <Card className="ring-amber-200/50 dark:ring-amber-900/30">
+            <CardContent className="py-10 text-center text-sm text-muted-foreground">
+              {t.home.loadError}
+            </CardContent>
+          </Card>
+        ) : !overview?.linked ? (
+          <Card className="border-dashed ring-amber-200/60 dark:ring-amber-900/30">
+            <CardContent className="flex flex-col items-center justify-center gap-4 py-12 text-center">
+              <span className="flex size-14 items-center justify-center rounded-2xl bg-amber-100 text-amber-600 dark:bg-amber-400/15 dark:text-amber-300">
+                <HomeIcon className="size-7" />
+              </span>
+              <div className="flex flex-col gap-1">
+                <p className="font-medium text-foreground">
+                  {t.home.notLinkedTitle}
+                </p>
+                <p className="max-w-sm text-sm text-muted-foreground">
+                  {t.home.notLinkedDesc}
+                </p>
+              </div>
+              <Link
+                href={`/${locale}/portal/support`}
+                className="inline-flex items-center gap-2 rounded-lg px-2 py-1 text-sm font-medium text-amber-700 outline-none hover:underline focus-visible:ring-2 focus-visible:ring-amber-500/60 dark:text-amber-400"
+              >
+                <LifeBuoyIcon className="size-4" />
+                {t.home.viewSupport}
+              </Link>
+            </CardContent>
+          </Card>
+        ) : history.length === 0 ? (
+          <Card className="border-dashed ring-amber-200/60 dark:ring-amber-900/30">
+            <CardContent className="py-10 text-center text-sm text-muted-foreground">
+              {t.home.emptyHistory}
+            </CardContent>
+          </Card>
+        ) : (
+          <ul className="flex flex-col gap-4">
+            {history.map((lease) => (
+              <li key={lease.id}>
+                <LeaseHistoryCard
+                  lease={lease}
+                  current={
+                    lease.id === currentId || lease.effectiveStatus === 'active'
+                  }
+                  t={t}
+                  money={money}
+                  fmtDate={fmtDate}
+                />
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+    </div>
+  );
+}
+
+function LeaseHistoryCard({
+  lease,
+  current,
+  t,
+  money,
+  fmtDate,
+}: {
+  lease: TenantLeaseView;
+  current: boolean;
+  t: PortalDict;
+  money: ReturnType<typeof useMoney>;
+  fmtDate: (iso: string) => string;
+}) {
+  return (
+    <Card
+      className={
+        current
+          ? 'bg-amber-50/40 ring-2 ring-amber-300/70 dark:bg-amber-400/5 dark:ring-amber-500/30'
+          : 'ring-foreground/10'
+      }
+    >
+      <CardContent className="flex flex-col gap-4">
+        {/* Header: unit + building · status */}
+        <div className="flex flex-wrap items-start justify-between gap-3">
+          <div className="flex min-w-0 items-center gap-3">
+            <span
+              className={[
+                'flex size-10 shrink-0 items-center justify-center rounded-xl',
+                current
+                  ? 'bg-gradient-to-br from-amber-400 to-orange-500 text-white'
+                  : 'bg-amber-100 text-amber-600 dark:bg-amber-400/15 dark:text-amber-300',
+              ].join(' ')}
+            >
+              <HomeIcon className="size-5" />
+            </span>
+            <div className="flex min-w-0 flex-col">
+              <span className="truncate text-sm font-semibold text-foreground">
+                {t.home.unit} {lease.unitNumber}
+              </span>
+              <span className="truncate text-xs text-muted-foreground">
+                {lease.buildingName}
+              </span>
+            </div>
+          </div>
+          <div className="flex items-center gap-2">
+            {current && (
+              <Badge className="border-transparent bg-amber-500 text-white">
+                {t.home.current}
+              </Badge>
+            )}
+            <Badge
+              variant="outline"
+              className={LEASE_STATUS_STYLES[lease.effectiveStatus]}
+            >
+              {t.leaseStatus[lease.effectiveStatus]}
+            </Badge>
+          </div>
+        </div>
+
+        {/* Details */}
+        <div className="grid gap-x-6 gap-y-3 border-t border-border/60 pt-4 sm:grid-cols-3">
+          <DetailField label={t.home.term}>
+            {fmtDate(lease.startDate)}
+            <span className="text-muted-foreground">{` ${t.home.to} `}</span>
+            {fmtDate(lease.endDate)}
+          </DetailField>
+          <DetailField label={t.home.rent}>
+            <span className="tabular-nums">
+              {money.format(parseFloat(lease.rentAmount))}
+            </span>
+          </DetailField>
+          <DetailField label={t.home.deposit}>
+            <span className="tabular-nums">
+              {money.format(parseFloat(lease.depositAmount))}
+            </span>
+          </DetailField>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function DetailField({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex flex-col gap-0.5">
+      <span className="text-xs text-muted-foreground">{label}</span>
+      <span className="text-sm font-medium text-foreground">{children}</span>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/portal/portal-shell.tsx b/apps/web/src/components/portal/portal-shell.tsx
new file mode 100644
index 00000000..9cea0624
--- /dev/null
+++ b/apps/web/src/components/portal/portal-shell.tsx
@@ -0,0 +1,233 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import Link from 'next/link';
+import { usePathname, useRouter } from 'next/navigation';
+import {
+  HomeIcon,
+  KeyRoundIcon,
+  LifeBuoyIcon,
+  UserIcon,
+  LogOutIcon,
+} from 'lucide-react';
+
+import { federatedLogout } from '@/auth/federated-logout';
+import { Avatar, AvatarFallback } from '@/components/ui/avatar';
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+} from '@/components/ui/dropdown-menu';
+import type { Dictionary } from '@/i18n/get-dictionary';
+import { getPortalDict } from '@/components/portal/portal-dict';
+
+type NavKey = 'home' | 'availableUnits' | 'support' | 'profile';
+
+type NavItem = {
+  key: NavKey;
+  label: string;
+  href: string;
+  icon: React.ElementType;
+};
+
+type Props = {
+  locale: string;
+  dict: Dictionary;
+  userName: string;
+  children: ReactNode;
+};
+
+function buildNavItems(locale: string, t: ReturnType<typeof getPortalDict>): NavItem[] {
+  const base = `/${locale}/portal`;
+  return [
+    { key: 'home', label: t.nav.home, href: base, icon: HomeIcon },
+    {
+      key: 'availableUnits',
+      label: t.nav.availableUnits,
+      href: `${base}/available-units`,
+      icon: KeyRoundIcon,
+    },
+    {
+      key: 'support',
+      label: t.nav.support,
+      href: `${base}/support`,
+      icon: LifeBuoyIcon,
+    },
+    {
+      key: 'profile',
+      label: t.nav.profile,
+      href: `${base}/profile`,
+      icon: UserIcon,
+    },
+  ];
+}
+
+export function PortalShell({ locale, dict, userName, children }: Props) {
+  const t = getPortalDict(dict, locale);
+  const pathname = usePathname();
+  const router = useRouter();
+  const items = buildNavItems(locale, t);
+  const homeHref = `/${locale}/portal`;
+
+  const userInitial = userName ? userName.charAt(0).toUpperCase() : 'U';
+
+  function isActive(href: string) {
+    if (href === homeHref) return pathname === href;
+    return pathname === href || pathname.startsWith(`${href}/`);
+  }
+
+  return (
+    // Warm, light, app-like chrome — deliberately NOT the admin navy sidebar.
+    // A soft amber wash sets the resident-facing tone across light + dark.
+    <div className="relative flex min-h-screen flex-col bg-gradient-to-b from-amber-50/70 via-background to-background dark:from-amber-950/20 dark:via-background">
+      {/* ── Top bar: brand · desktop nav · account ─────────────────────────── */}
+      <header
+        className="sticky top-0 z-30 border-b border-border/70 bg-background/70 backdrop-blur-md supports-[backdrop-filter]:bg-background/60"
+        style={{ paddingTop: 'env(safe-area-inset-top)' }}
+      >
+        <div className="mx-auto flex h-16 w-full max-w-3xl items-center gap-3 px-4">
+          {/* Brand */}
+          <Link
+            href={homeHref}
+            className="flex min-w-0 items-center gap-2.5 rounded-lg outline-none focus-visible:ring-2 focus-visible:ring-amber-500/60"
+          >
+            <span className="flex size-9 shrink-0 items-center justify-center rounded-xl bg-gradient-to-br from-amber-400 to-orange-500 shadow-sm">
+              <HomeIcon className="size-4 text-white" />
+            </span>
+            <span className="flex min-w-0 flex-col leading-tight">
+              <span className="truncate text-sm font-semibold text-foreground">
+                {dict.app.name}
+              </span>
+              <span className="truncate text-[11px] font-medium text-amber-700 dark:text-amber-400">
+                {t.brandSubtitle}
+              </span>
+            </span>
+          </Link>
+
+          {/* Desktop nav */}
+          <nav className="mx-auto hidden items-center gap-1 md:flex">
+            {items.map((item) => {
+              const active = isActive(item.href);
+              const Icon = item.icon;
+              return (
+                <Link
+                  key={item.key}
+                  href={item.href}
+                  aria-current={active ? 'page' : undefined}
+                  className={[
+                    'flex h-10 items-center gap-2 rounded-full px-3.5 text-sm font-medium transition-colors outline-none focus-visible:ring-2 focus-visible:ring-amber-500/60',
+                    active
+                      ? 'bg-amber-100/80 text-amber-900 dark:bg-amber-400/15 dark:text-amber-200'
+                      : 'text-muted-foreground hover:bg-foreground/5 hover:text-foreground',
+                  ].join(' ')}
+                >
+                  <Icon className="size-4" />
+                  {item.label}
+                </Link>
+              );
+            })}
+          </nav>
+
+          {/* Account menu */}
+          <div className="ms-auto md:ms-0">
+            <DropdownMenu>
+              <DropdownMenuTrigger
+                render={
+                  <Button
+                    variant="ghost"
+                    className="h-11 gap-2 rounded-full px-1.5 ps-1.5 pe-2.5"
+                  />
+                }
+                aria-label={t.userMenu.openMenu}
+              >
+                <Avatar size="sm">
+                  <AvatarFallback className="bg-gradient-to-br from-amber-400 to-orange-500 text-xs font-semibold text-white">
+                    {userInitial}
+                  </AvatarFallback>
+                </Avatar>
+                <span className="hidden max-w-[10rem] truncate text-sm font-medium text-foreground sm:inline">
+                  {userName || '—'}
+                </span>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" side="bottom" className="w-56">
+                {/* Plain header (not DropdownMenuLabel — base-ui GroupLabel must
+                    live inside a Group; see topbar note). */}
+                <div className="flex flex-col px-2 py-1.5">
+                  <span className="text-[11px] text-muted-foreground">
+                    {t.userMenu.signedInAs}
+                  </span>
+                  <span className="truncate text-sm font-medium text-foreground">
+                    {userName || '—'}
+                  </span>
+                </div>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem
+                  onClick={() => router.push(`/${locale}/portal/profile`)}
+                >
+                  <UserIcon />
+                  {t.userMenu.profile}
+                </DropdownMenuItem>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem
+                  variant="destructive"
+                  onClick={() => federatedLogout(locale)}
+                >
+                  <LogOutIcon />
+                  {t.userMenu.signOut}
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
+        </div>
+      </header>
+
+      {/* ── Content ────────────────────────────────────────────────────────── */}
+      {/* Extra bottom padding on mobile clears the fixed tab bar + safe area. */}
+      <main className="mx-auto w-full max-w-3xl flex-1 px-4 pt-6 pb-28 md:pb-12">
+        {children}
+      </main>
+
+      {/* ── Mobile bottom tab bar ──────────────────────────────────────────── */}
+      <nav
+        aria-label={t.brandSubtitle}
+        className="fixed inset-x-0 bottom-0 z-30 border-t border-border/70 bg-background/85 backdrop-blur-md md:hidden"
+        style={{ paddingBottom: 'env(safe-area-inset-bottom)' }}
+      >
+        <div className="mx-auto grid max-w-3xl grid-cols-4">
+          {items.map((item) => {
+            const active = isActive(item.href);
+            const Icon = item.icon;
+            return (
+              <Link
+                key={item.key}
+                href={item.href}
+                aria-current={active ? 'page' : undefined}
+                className={[
+                  'flex min-h-14 flex-col items-center justify-center gap-1 px-1 py-2 text-[11px] font-medium transition-colors outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-amber-500/60',
+                  active
+                    ? 'text-amber-700 dark:text-amber-400'
+                    : 'text-muted-foreground hover:text-foreground',
+                ].join(' ')}
+              >
+                <span
+                  className={[
+                    'flex h-7 w-12 items-center justify-center rounded-full transition-colors',
+                    active
+                      ? 'bg-amber-100 dark:bg-amber-400/15'
+                      : 'bg-transparent',
+                  ].join(' ')}
+                >
+                  <Icon className="size-5" />
+                </span>
+                <span className="truncate">{item.label}</span>
+              </Link>
+            );
+          })}
+        </div>
+      </nav>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/portal/portal-support.tsx b/apps/web/src/components/portal/portal-support.tsx
new file mode 100644
index 00000000..e0735085
--- /dev/null
+++ b/apps/web/src/components/portal/portal-support.tsx
@@ -0,0 +1,305 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+import { useForm, Controller } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { toast } from 'sonner';
+import { PlusIcon, WrenchIcon } from 'lucide-react';
+
+import {
+  useGetTenantOverviewQuery,
+  useCreateTenantMaintenanceRequestMutation,
+} from '@/store/api/endpoints/tenant.api';
+import type {
+  MaintenanceRequestPriority,
+  MaintenanceRequestStatus,
+} from '@/types/api';
+import type { Dictionary } from '@/i18n/get-dictionary';
+import { getPortalDict } from '@/components/portal/portal-dict';
+import { canOpenRequest } from '@/lib/tenant-overview';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Skeleton } from '@/components/ui/skeleton';
+import { Label } from '@/components/ui/label';
+import { Input } from '@/components/ui/input';
+import { Textarea } from '@/components/ui/textarea';
+import { Card, CardContent } from '@/components/ui/card';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogFooter,
+  DialogClose,
+} from '@/components/ui/dialog';
+
+// Mirrors the tenant-dashboard request palette.
+const REQUEST_STATUS_STYLES: Record<MaintenanceRequestStatus, string> = {
+  open: 'bg-amber-50 text-amber-700 border-amber-200',
+  in_progress: 'bg-blue-50 text-blue-700 border-blue-200',
+  resolved: 'bg-emerald-50 text-emerald-700 border-emerald-200',
+  closed: 'bg-muted text-muted-foreground border-transparent',
+};
+
+const PRIORITY_STYLES: Record<MaintenanceRequestPriority, string> = {
+  low: 'bg-muted text-muted-foreground border-transparent',
+  medium: 'bg-blue-50 text-blue-700 border-blue-200',
+  high: 'bg-orange-50 text-orange-700 border-orange-200',
+  urgent: 'bg-red-50 text-red-700 border-red-200',
+};
+
+const PRIORITIES: MaintenanceRequestPriority[] = [
+  'low',
+  'medium',
+  'high',
+  'urgent',
+];
+const OPEN_STATUSES: MaintenanceRequestStatus[] = ['open', 'in_progress'];
+
+type RequestFormValues = {
+  title: string;
+  description: string;
+  priority: MaintenanceRequestPriority;
+};
+
+const EMPTY_VALUES: RequestFormValues = {
+  title: '',
+  description: '',
+  priority: 'medium',
+};
+
+type Props = { locale: string; dict: Dictionary };
+
+export function PortalSupport({ locale, dict }: Props) {
+  const t = getPortalDict(dict, locale).support;
+  const { data: overview, isLoading, isError } = useGetTenantOverviewQuery();
+  const [createRequest, { isLoading: creating }] =
+    useCreateTenantMaintenanceRequestMutation();
+  const [createOpen, setCreateOpen] = useState(false);
+
+  const dateFmt = useMemo(
+    () =>
+      new Intl.DateTimeFormat(locale, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      }),
+    [locale],
+  );
+  const fmtDate = (iso: string) => dateFmt.format(new Date(iso));
+
+  const schema = useMemo(
+    () =>
+      z.object({
+        title: z.string().trim().min(1, t.form.titleRequired),
+        description: z.string(),
+        priority: z.enum(['low', 'medium', 'high', 'urgent']),
+      }),
+    [t],
+  );
+
+  const {
+    register,
+    control,
+    handleSubmit,
+    reset,
+    formState: { errors },
+  } = useForm<RequestFormValues>({
+    resolver: zodResolver(schema),
+    defaultValues: EMPTY_VALUES,
+  });
+
+  const requests = overview?.maintenanceRequests ?? [];
+  const canOpen = canOpenRequest(overview);
+
+  async function onSubmit(values: RequestFormValues) {
+    try {
+      await createRequest({
+        title: values.title.trim(),
+        description: values.description.trim() || undefined,
+        priority: values.priority,
+      }).unwrap();
+      toast.success(t.created);
+      setCreateOpen(false);
+      reset(EMPTY_VALUES);
+    } catch {
+      toast.error(t.createError);
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-6">
+      {/* Header */}
+      <section className="flex flex-wrap items-end justify-between gap-3">
+        <div>
+          <h1 className="text-2xl font-semibold tracking-tight text-foreground">
+            {t.title}
+          </h1>
+          <p className="mt-0.5 text-sm text-muted-foreground">{t.subtitle}</p>
+        </div>
+        <Button
+          disabled={!canOpen}
+          onClick={() => {
+            reset(EMPTY_VALUES);
+            setCreateOpen(true);
+          }}
+          className="bg-gradient-to-br from-amber-400 to-orange-500 text-white hover:from-amber-500 hover:to-orange-600"
+        >
+          <PlusIcon className="size-4" />
+          {t.new}
+        </Button>
+      </section>
+
+      {!canOpen && !isLoading && (
+        <p className="text-xs text-muted-foreground">{t.noLease}</p>
+      )}
+
+      {isLoading ? (
+        <div className="flex flex-col gap-3">
+          <Skeleton className="h-24 rounded-xl" />
+          <Skeleton className="h-24 rounded-xl" />
+        </div>
+      ) : isError ? (
+        <Card className="ring-amber-200/50 dark:ring-amber-900/30">
+          <CardContent className="py-10 text-center text-sm text-muted-foreground">
+            {dict.dashboard.tenant.loadError}
+          </CardContent>
+        </Card>
+      ) : requests.length === 0 ? (
+        <Card className="border-dashed ring-amber-200/60 dark:ring-amber-900/30">
+          <CardContent className="flex flex-col items-center justify-center gap-3 py-12 text-center">
+            <span className="flex size-14 items-center justify-center rounded-2xl bg-amber-100 text-amber-600 dark:bg-amber-400/15 dark:text-amber-300">
+              <WrenchIcon className="size-7" />
+            </span>
+            <p className="max-w-sm text-sm text-muted-foreground">
+              {canOpen ? t.emptyActive : t.empty}
+            </p>
+          </CardContent>
+        </Card>
+      ) : (
+        <ul className="flex flex-col gap-3">
+          {requests.map((r) => (
+            <li key={r.id}>
+              <Card className="ring-foreground/10">
+                <CardContent className="flex flex-col gap-2">
+                  <div className="flex flex-wrap items-center gap-2">
+                    <Badge
+                      variant="outline"
+                      className={REQUEST_STATUS_STYLES[r.status]}
+                    >
+                      {t.status[r.status]}
+                    </Badge>
+                    <Badge
+                      variant="outline"
+                      className={PRIORITY_STYLES[r.priority]}
+                    >
+                      {t.priority[r.priority]}
+                    </Badge>
+                    <span className="ms-auto text-xs text-muted-foreground">
+                      {t.unit} {r.unitNumber} · {fmtDate(r.createdAt)}
+                    </span>
+                  </div>
+                  <p className="text-sm font-medium text-foreground">
+                    {r.title}
+                  </p>
+                  {r.description && (
+                    <p className="line-clamp-2 text-sm text-muted-foreground">
+                      {r.description}
+                    </p>
+                  )}
+                </CardContent>
+              </Card>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {/* Create request dialog */}
+      <Dialog open={createOpen} onOpenChange={setCreateOpen}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>{t.form.title}</DialogTitle>
+          </DialogHeader>
+          <form onSubmit={handleSubmit(onSubmit)} className="flex flex-col gap-4">
+            <div className="flex flex-col gap-1.5">
+              <Label htmlFor="psr-title">
+                {t.form.titleLabel} <span className="text-destructive">*</span>
+              </Label>
+              <Input
+                id="psr-title"
+                placeholder={t.form.titlePlaceholder}
+                aria-invalid={!!errors.title}
+                {...register('title')}
+              />
+              {errors.title && (
+                <p className="text-xs text-destructive">
+                  {errors.title.message}
+                </p>
+              )}
+            </div>
+
+            <div className="flex flex-col gap-1.5">
+              <Label htmlFor="psr-priority">{t.form.priorityLabel}</Label>
+              <Controller
+                control={control}
+                name="priority"
+                render={({ field }) => (
+                  <Select value={field.value} onValueChange={field.onChange}>
+                    <SelectTrigger id="psr-priority" className="w-full">
+                      <SelectValue>
+                        {(value) =>
+                          t.priority[value as MaintenanceRequestPriority] ??
+                          value
+                        }
+                      </SelectValue>
+                    </SelectTrigger>
+                    <SelectContent>
+                      {PRIORITIES.map((p) => (
+                        <SelectItem key={p} value={p}>
+                          {t.priority[p]}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                )}
+              />
+            </div>
+
+            <div className="flex flex-col gap-1.5">
+              <Label htmlFor="psr-desc">{t.form.descriptionLabel}</Label>
+              <Textarea
+                id="psr-desc"
+                rows={4}
+                placeholder={t.form.descriptionPlaceholder}
+                {...register('description')}
+              />
+            </div>
+
+            <DialogFooter>
+              <DialogClose
+                render={<Button variant="outline" type="button" />}
+                onClick={() => {
+                  setCreateOpen(false);
+                  reset(EMPTY_VALUES);
+                }}
+              >
+                {t.form.cancel}
+              </DialogClose>
+              <Button type="submit" disabled={creating}>
+                {creating ? t.form.submitting : t.form.submit}
+              </Button>
+            </DialogFooter>
+          </form>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}
diff --git a/apps/web/src/i18n/dictionaries/ar.json b/apps/web/src/i18n/dictionaries/ar.json
index c458a8b0..1313cf81 100644
--- a/apps/web/src/i18n/dictionaries/ar.json
+++ b/apps/web/src/i18n/dictionaries/ar.json
@@ -784,7 +784,33 @@
       "updatedToast": "تم تحديث المستأجر.",
       "updateErrorToast": "تعذّر تحديث المستأجر.",
       "deletedToast": "تم حذف المستأجر.",
-      "deleteErrorToast": "تعذّر حذف المستأجر."
+      "deleteErrorToast": "تعذّر حذف المستأجر.",
+      "portalLogin": {
+        "toggleLabel": "إنشاء حساب دخول للبوابة لهذا المستأجر",
+        "toggleHelp": "يتيح لهذا المستأجر تسجيل الدخول إلى بوابة المستأجرين لعرض عقوده والوحدات المتاحة وتقديم طلبات الدعم.",
+        "emailLabel": "البريد الإلكتروني لتسجيل الدخول",
+        "placeholderEmail": "jane@example.com",
+        "emailRequired": "البريد الإلكتروني لتسجيل الدخول مطلوب",
+        "invalidEmail": "يرجى إدخال بريد إلكتروني صحيح",
+        "passwordLabel": "كلمة المرور",
+        "placeholderPassword": "8 أحرف على الأقل",
+        "passwordRequired": "كلمة المرور مطلوبة",
+        "passwordMinLength": "يجب أن تتكوّن كلمة المرور من 8 أحرف على الأقل",
+        "showPassword": "إظهار كلمة المرور",
+        "hidePassword": "إخفاء كلمة المرور",
+        "generate": "توليد",
+        "generatedToast": "تم توليد كلمة مرور قوية.",
+        "emailConflictError": "هذا البريد الإلكتروني مسجّل بالفعل. يرجى استخدام بريد إلكتروني مختلف لحساب البوابة.",
+        "successTitle": "تم إنشاء حساب البوابة",
+        "successDescription": "سلّم بيانات الدخول هذه للمستأجر الآن — لن تُعرض كلمة المرور مرة أخرى لأسباب أمنية.",
+        "emailFieldLabel": "البريد الإلكتروني",
+        "passwordFieldLabel": "كلمة المرور",
+        "copy": "نسخ",
+        "copied": "تم النسخ",
+        "copyEmailLabel": "نسخ البريد الإلكتروني",
+        "copyPasswordLabel": "نسخ كلمة المرور",
+        "done": "تم"
+      }
     },
     "detail": {
       "notFound": "المستأجر غير موجود.",
@@ -1427,5 +1453,105 @@
     "interestError": "تعذّر إرسال طلب الاهتمام. يرجى المحاولة مرة أخرى.",
     "interestSubjectTemplate": "اهتمام بـ {building} · الوحدة {unit}",
     "interestDescriptionTemplate": "أنا مهتم بالوحدة {unit} ({bedrooms} غرفة / {bathrooms} حمام) في {building}، {floor}. يرجى التواصل لمزيد من التفاصيل."
+  },
+  "portal": {
+    "brandSubtitle": "بوابة الساكن",
+    "nav": {
+      "home": "الرئيسية",
+      "availableUnits": "الوحدات المتاحة",
+      "support": "الدعم",
+      "profile": "الملف الشخصي"
+    },
+    "userMenu": {
+      "signedInAs": "مسجّل الدخول باسم",
+      "profile": "الملف الشخصي",
+      "signOut": "تسجيل الخروج",
+      "openMenu": "فتح قائمة الحساب"
+    },
+    "home": {
+      "welcome": "أهلاً بعودتك",
+      "subtitle": "منزلك في لمحة",
+      "leaseTitle": "عقد إيجارك الحالي",
+      "unit": "الوحدة",
+      "building": "المبنى",
+      "status": "الحالة",
+      "term": "مدة العقد",
+      "rent": "الإيجار الشهري",
+      "to": "إلى",
+      "noLease": "لا يوجد لديك عقد إيجار نشط بعد. سيقوم مدير العقار بربط عقدك بحسابك قريباً.",
+      "notLinkedTitle": "لم يتم ربط حسابك بعد",
+      "notLinkedDesc": "لم نتمكّن من العثور على عقد إيجار مرتبط بحسابك. سيقوم مدير العقار بربط وحدتك قريباً — يرجى المراجعة لاحقاً.",
+      "loadError": "تعذّر تحميل تفاصيل منزلك. يرجى تحديث الصفحة والمحاولة مرة أخرى.",
+      "viewSupport": "تحتاج شيئاً؟ تواصل مع الدعم",
+      "historyTitle": "وحداتك السكنية",
+      "current": "الحالي",
+      "deposit": "التأمين",
+      "emptyHistory": "لا يوجد سجل عقود بعد. سيظهر هنا فور قيام مدير العقار بربط عقدك."
+    },
+    "leaseStatus": {
+      "draft": "مسودة",
+      "active": "نشط",
+      "expired": "منتهٍ",
+      "terminated": "مُنهى"
+    },
+    "comingSoon": {
+      "badge": "قريباً",
+      "availableUnitsTitle": "الوحدات المتاحة",
+      "availableUnitsDesc": "تصفّح الوحدات المتاحة في مجتمعك. هذه الميزة في طريقها إليك — ستتمكّن قريباً من استكشاف المنازل المتاحة هنا.",
+      "supportTitle": "الدعم والطلبات",
+      "supportDesc": "قدّم طلبات الصيانة وتابع تقدّمها. نُجهّز هذه المساحة من أجلك.",
+      "profileTitle": "ملفك الشخصي",
+      "profileDesc": "اعرض وأدر بيانات التواصل وحسابك. قريباً."
+    },
+    "availableUnits": {
+      "title": "الوحدات المتاحة",
+      "subtitle": "الوحدات الشاغرة في مجتمعك.",
+      "empty": "لا توجد وحدات متاحة حالياً. يرجى المراجعة لاحقاً.",
+      "loadError": "تعذّر تحميل الوحدات المتاحة. يرجى تحديث الصفحة والمحاولة مرة أخرى.",
+      "floor": "الطابق",
+      "bedrooms": "غرف النوم",
+      "bathrooms": "الحمّامات",
+      "area": "المساحة",
+      "sqftUnit": "قدم²"
+    },
+    "support": {
+      "title": "الدعم / الطلبات",
+      "subtitle": "قدّم طلب صيانة لوحدتك وتابع حالته.",
+      "new": "طلب جديد",
+      "noLease": "تحتاج إلى عقد إيجار نشط قبل أن تتمكّن من فتح طلب صيانة.",
+      "empty": "لا توجد لديك طلبات بعد.",
+      "emptyActive": "لا توجد لديك طلبات بعد. افتح طلباً عندما تحتاج إلى المساعدة.",
+      "created": "تم إرسال الطلب.",
+      "createError": "حدث خطأ ما. يرجى المحاولة مرة أخرى.",
+      "unit": "الوحدة",
+      "status": {
+        "open": "مفتوح",
+        "in_progress": "قيد التنفيذ",
+        "resolved": "تم الحل",
+        "closed": "مغلق"
+      },
+      "priority": {
+        "low": "منخفضة",
+        "medium": "متوسطة",
+        "high": "عالية",
+        "urgent": "عاجلة"
+      },
+      "form": {
+        "title": "طلب صيانة جديد",
+        "titleLabel": "العنوان",
+        "titlePlaceholder": "مثال: تسريب في صنبور المطبخ",
+        "titleRequired": "يرجى إضافة عنوان مختصر.",
+        "priorityLabel": "الأولوية",
+        "descriptionLabel": "الوصف",
+        "descriptionPlaceholder": "صف المشكلة بمزيد من التفصيل…",
+        "cancel": "إلغاء",
+        "submit": "إرسال الطلب",
+        "submitting": "جارٍ الإرسال…"
+      }
+    },
+    "profile": {
+      "changePassword": "تغيير كلمة المرور",
+      "changePasswordHint": "حدّث كلمة المرور التي تستخدمها لتسجيل الدخول إلى البوابة."
+    }
   }
 }
diff --git a/apps/web/src/i18n/dictionaries/en.json b/apps/web/src/i18n/dictionaries/en.json
index 7f58b2bc..22208fde 100644
--- a/apps/web/src/i18n/dictionaries/en.json
+++ b/apps/web/src/i18n/dictionaries/en.json
@@ -784,7 +784,33 @@
       "updatedToast": "Renter updated.",
       "updateErrorToast": "Failed to update renter.",
       "deletedToast": "Renter deleted.",
-      "deleteErrorToast": "Failed to delete renter."
+      "deleteErrorToast": "Failed to delete renter.",
+      "portalLogin": {
+        "toggleLabel": "Create a portal login for this tenant",
+        "toggleHelp": "Lets this renter sign in to the tenant portal to view their leases and available units, and submit support requests.",
+        "emailLabel": "Login email",
+        "placeholderEmail": "jane@example.com",
+        "emailRequired": "Portal login email is required",
+        "invalidEmail": "Enter a valid email address",
+        "passwordLabel": "Password",
+        "placeholderPassword": "Min. 8 characters",
+        "passwordRequired": "Password is required",
+        "passwordMinLength": "Password must be at least 8 characters",
+        "showPassword": "Show password",
+        "hidePassword": "Hide password",
+        "generate": "Generate",
+        "generatedToast": "A strong password was generated.",
+        "emailConflictError": "That email is already registered. Please use a different email for the portal login.",
+        "successTitle": "Portal login created",
+        "successDescription": "Give these credentials to the tenant now — for security, the password won't be shown again.",
+        "emailFieldLabel": "Email",
+        "passwordFieldLabel": "Password",
+        "copy": "Copy",
+        "copied": "Copied",
+        "copyEmailLabel": "Copy email",
+        "copyPasswordLabel": "Copy password",
+        "done": "Done"
+      }
     },
     "detail": {
       "notFound": "Renter not found.",
@@ -1427,5 +1453,105 @@
     "interestError": "Couldn't submit your interest. Please try again.",
     "interestSubjectTemplate": "Interest in {building} · Unit {unit}",
     "interestDescriptionTemplate": "I'm interested in Unit {unit} ({bedrooms} bd / {bathrooms} ba) at {building}, {floor}. Please reach out with more details."
+  },
+  "portal": {
+    "brandSubtitle": "Resident portal",
+    "nav": {
+      "home": "Home",
+      "availableUnits": "Available units",
+      "support": "Support",
+      "profile": "Profile"
+    },
+    "userMenu": {
+      "signedInAs": "Signed in as",
+      "profile": "Profile",
+      "signOut": "Sign out",
+      "openMenu": "Open account menu"
+    },
+    "home": {
+      "welcome": "Welcome home",
+      "subtitle": "Your home, at a glance",
+      "leaseTitle": "Your current lease",
+      "unit": "Unit",
+      "building": "Building",
+      "status": "Status",
+      "term": "Lease term",
+      "rent": "Monthly rent",
+      "to": "to",
+      "noLease": "You don't have an active lease yet. Your property manager will link one to your account.",
+      "notLinkedTitle": "Your account isn't linked yet",
+      "notLinkedDesc": "We couldn't find a lease connected to your account. Your property manager will link your unit shortly — check back soon.",
+      "loadError": "We couldn't load your home details. Please refresh and try again.",
+      "viewSupport": "Need something? Contact support",
+      "historyTitle": "Your apartments",
+      "current": "Current",
+      "deposit": "Deposit",
+      "emptyHistory": "No lease history yet. Once your property manager links a lease, it will appear here."
+    },
+    "leaseStatus": {
+      "draft": "Draft",
+      "active": "Active",
+      "expired": "Expired",
+      "terminated": "Terminated"
+    },
+    "comingSoon": {
+      "badge": "Coming soon",
+      "availableUnitsTitle": "Available units",
+      "availableUnitsDesc": "Browse open units in your community. This is on its way — you'll be able to explore available homes here soon.",
+      "supportTitle": "Support & requests",
+      "supportDesc": "Raise maintenance requests and track their progress. This space is being prepared for you.",
+      "profileTitle": "Your profile",
+      "profileDesc": "View and manage your contact details and account. Coming soon."
+    },
+    "availableUnits": {
+      "title": "Available units",
+      "subtitle": "Vacant homes in your community.",
+      "empty": "There are no available units right now. Please check back later.",
+      "loadError": "We couldn't load available units. Please refresh and try again.",
+      "floor": "Floor",
+      "bedrooms": "Bedrooms",
+      "bathrooms": "Bathrooms",
+      "area": "Area",
+      "sqftUnit": "sqft"
+    },
+    "support": {
+      "title": "Support / Requests",
+      "subtitle": "Raise a maintenance request for your apartment and track it.",
+      "new": "New request",
+      "noLease": "You need an active lease before you can open a maintenance request.",
+      "empty": "You have no requests yet.",
+      "emptyActive": "You have no requests yet. Open one whenever you need help.",
+      "created": "Request submitted.",
+      "createError": "Something went wrong. Please try again.",
+      "unit": "Unit",
+      "status": {
+        "open": "Open",
+        "in_progress": "In progress",
+        "resolved": "Resolved",
+        "closed": "Closed"
+      },
+      "priority": {
+        "low": "Low",
+        "medium": "Medium",
+        "high": "High",
+        "urgent": "Urgent"
+      },
+      "form": {
+        "title": "New maintenance request",
+        "titleLabel": "Title",
+        "titlePlaceholder": "e.g. Leaking kitchen tap",
+        "titleRequired": "Please add a short title.",
+        "priorityLabel": "Priority",
+        "descriptionLabel": "Description",
+        "descriptionPlaceholder": "Describe the issue in a little more detail…",
+        "cancel": "Cancel",
+        "submit": "Submit request",
+        "submitting": "Submitting…"
+      }
+    },
+    "profile": {
+      "changePassword": "Change password",
+      "changePasswordHint": "Update the password you use to sign in to the portal."
+    }
   }
 }
diff --git a/apps/web/src/proxy.ts b/apps/web/src/proxy.ts
index 35639739..d10ae0e6 100644
--- a/apps/web/src/proxy.ts
+++ b/apps/web/src/proxy.ts
@@ -143,7 +143,8 @@ export default auth((request) => {
   const sessionExpired = session?.error === 'RefreshAccessTokenError';
 
   // Route classification.
-  const isProtected = area === 'dashboard' || area === 'billing';
+  const isProtected =
+    area === 'dashboard' || area === 'billing' || area === 'portal';
   const isAnonOnly = area === undefined || area === 'login'; // landing root + login
 
   // Direct role-named segments (e.g. /<locale>/org_admin) are not real routes →
@@ -165,6 +166,19 @@ export default auth((request) => {
       return sessionExpired ? clearSessionCookies(response, request) : response;
     }
 
+    // ── Portal ⇄ dashboard isolation ─────────────────────────────────────
+    // Tenants live in the resident portal, never the admin dashboard shell;
+    // every other role is the inverse. Keeps the two audiences fully separated
+    // at the edge (the layout guards remain the authoritative gate).
+    if (area === 'dashboard' && sessionRole === 'tenant') {
+      return NextResponse.redirect(new URL(`/${locale}/portal`, nextUrl));
+    }
+    if (area === 'portal' && sessionRole && sessionRole !== 'tenant') {
+      return NextResponse.redirect(
+        new URL(dashboardPathForRole(sessionRole, locale), nextUrl),
+      );
+    }
+
     // ── Paywall gate — DELIBERATELY NOT done here ────────────────────────
     // "Has the user paid?" is org.status === ACTIVE in the DB, which is
     // token-independent. The session-token role, by contrast, is a copy that
diff --git a/apps/web/src/tests/unit/tenant/tenant-overview.test.ts b/apps/web/src/tests/unit/tenant/tenant-overview.test.ts
index 2d05566f..e783ac27 100644
--- a/apps/web/src/tests/unit/tenant/tenant-overview.test.ts
+++ b/apps/web/src/tests/unit/tenant/tenant-overview.test.ts
@@ -27,6 +27,7 @@ function overview(
     balance: { invoiced: '0.00', paid: '0.00', outstanding: '0.00' },
     invoices: [],
     maintenanceRequests: [],
+    leaseHistory: [],
     ...overrides,
   };
 }
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 56beee98..cf2bc141 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -364,6 +364,17 @@ export type CreateRenterBody = {
   notes?: string;
   /** Keycloak `sub` of the tenant user to link (enables their portal). */
   renterUserId?: string | null;
+  /**
+   * When present, the API mints a Keycloak tenant login for this renter and
+   * links it (sets `renterUserId` to the new `sub`). Admin-provisioned only —
+   * no self-registration. `email` becomes the login username (must be unique in
+   * the realm); `password` is set permanent (no forced reset). The tenant does
+   * NOT consume a plan staff seat. See TENANT-PORTAL-ROADMAP.md TP1.
+   */
+  portalLogin?: {
+    email: string;
+    password: string;
+  };
 };
 
 export type PatchRenterBody = {
@@ -1121,6 +1132,12 @@ export type TenantOverviewResponse = {
     phone?: string | null;
   } | null;
   lease: TenantLeaseView | null;
+  /**
+   * All of the tenant's leases, newest start first — the portal's lease-history
+   * + "apartments I've leased" surface (TP3). `lease` remains the single
+   * currently-surfaced one; this is the full list.
+   */
+  leaseHistory: TenantLeaseView[];
   balance: TenantBalance;
   /** Latest invoices for the tenant's lease(s), newest dueDate first. */
   invoices: TenantInvoiceView[];