feat: autonomous backlog push — admin UX overhaul + storage parity + residential parity + Documenso Phase 1

Massive multi-area push driven by docs/admin-ux-backlog.md. Every byte
path now goes through getStorageBackend() so signed EOIs, contracts,
brochures, berth PDFs, files, avatars, branding logos, and DB backups
all work identically on S3 and filesystem backends.

USER SETTINGS (rebuild)
  - Country + Timezone selectors with cross-defaulting
  - Browser-detected timezone banner ("Looks like you're in Europe/Paris…")
  - Email change with verification flow (user_email_changes table,
    OLD-address cancel link + NEW-address confirm link)
    + EMAIL_CHANGE_INSTANT=true dev shortcut
  - Password reset triggered via better-auth requestPasswordReset
  - Profile photo upload + crop (square 256×256) via shared
    <ImageCropperDialog> + /api/v1/me/avatar

BRANDING
  - Shared <ImageCropperDialog> using react-easy-crop
  - Logo upload + crop in /admin/branding (writes via
    /api/v1/admin/settings/image -> storage backend)
  - Email header/footer HTML defaults injectable via "Insert default"
  - SettingsFormCard new field types: timezone (combobox), image-upload

STORAGE ADMIN OVERHAUL
  - S3 config form FIRST, swap action SECOND
  - Test connection before any switch
  - Two-button switch: "Switch + migrate" vs "Switch only" with
    warning modals
  - runMigration() honours skipMigration flag
  - /api/ready + system-monitoring health check use the active
    storage backend instead of always probing MinIO
  - Filesystem backend already had full feature parity — verified

BACKUP MANAGEMENT (real)
  - New backup_jobs table (id / status / trigger / size / storage_path)
  - runBackup() service spawns pg_dump --format=custom, streams to
    active storage backend via getStorageBackend().put()
  - /admin/backup page: trigger, history, download .dump for restore
  - Super-admin gated

AI ADMIN PANEL
  - /admin/ai consolidates master switch + monthly token cap +
    provider credentials
  - Per-feature settings (OCR, berth-PDF parser, recommender)
    linked from the same page

ONBOARDING WIZARD
  - /admin/onboarding now real with auto-checked steps
  - Reads each setting key + lists endpoint (roles/users/tags) to
    decide completion
  - Manual checkboxes for steps without an auto-detect signal
  - Progress bar + Mark done/Mark incomplete buttons
  - State persisted in system_settings.onboarding_manual_status

RESIDENTIAL PARITY (full)
  - New residential_client_notes + residential_interest_notes tables
    (mirror marina-side shape)
  - Polymorphic notes.service.ts extended (verifyParent, listForEntity,
    create, update, delete) for residential_clients/_interests
  - <NotesList> component accepts the new entity types
  - 4 new note endpoints (GET/POST/PATCH/DELETE for clients + interests)
  - 2 new activity endpoints (residential clients + interests)
  - residential-client-tabs.tsx + residential-interest-tabs.tsx use
    DetailLayout (Overview / Interests / Notes / Activity)
  - residential-client-detail-header.tsx mirrors marina-side strip
  - useBreadcrumbHint wired into both detail components
  - Configurable Assigned-to dropdown (residential_interests.view perm)

CONFIGURABLE RESIDENTIAL STAGES
  - residential-stages.service.ts with list / save / orphan-check
  - /api/v1/residential/stages GET/PUT
  - /admin/residential-stages admin UI with reassign-on-remove modal
  - Validators relaxed from z.enum to z.string

DOCUMENSO PHASE 1
  - Schema: document_signers.invited_at / opened_at /
    last_reminder_sent_at / signing_token (+ idx_ds_signing_token)
  - Schema: documents.completion_cc_emails (text[]) +
    auto_reminder_interval_days (int)
  - transformSigningUrl() now maps SignerRole -> URL segment via
    ROLE_TO_URL_SEGMENT (approver->cc, witness->witness) — fixes
    Risk #5 where approver invites landed on /sign/error
  - POST /api/v1/documents/[id]/send-invitation with auto-pick of
    next pending signer
  - Per-port settings: documenso_developer_label / _approver_label
    + documenso_developer_user_id / _approver_user_id (Phase 7
    Project Director RBAC binding fields)

ADMIN UX RAPID-FIRE
  - Sidebar collapse removed (always-expanded design)
  - Audit log: input sizes (h-9), date pickers w-44, action cell
    sub-label so single-row entries aren't blank
  - Sales email config: token list <details> + tooltips on
    threshold + body fields
  - Custom Settings card: long-form description
  - Reminder digest timezone uses TimezoneCombobox
  - Port form: currency dropdown (10 common currencies) + timezone
    combobox + brand color picker
  - Permissions count badge opens modal with granted/denied per
    resource
  - Role names display-normalized via prettifyRoleName
  - Tag form: native input type=color
  - Custom Fields page: amber heads-up about non-integration
  - Settings manager: select field type + fallthrough_policy as dropdown
  - Storage admin S3 fields ship as proper password + boolean

LIST PAGES
  - Residential client list: clickable email/phone (mailto/tel/wa.me)
  - Residential interests + Documents Hub search inputs sized h-9

CURRENCY API
  - scripts/test-currency-api.ts verifies live Frankfurter fetch
    -> DB upsert -> getRate -> convert. Inverse-rate drift <=0.001

TESTS
  - 1185/1185 vitest passing
  - tsc clean
  - eslint 0 errors (16 pre-existing warnings)

Note: WEBSITE_INTAKE_SECRET added to .env.example but committed
separately due to pre-commit hook policy on .env* files.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/residential/residential-client-detail-header.tsx

@@ -0,0 +1,50 @@
+'use client';
+
+import { Home } from 'lucide-react';
+
+import { Badge } from '@/components/ui/badge';
+import { DetailHeaderStrip } from '@/components/shared/detail-header-strip';
+import { InlineEditableField } from '@/components/shared/inline-editable-field';
+
+interface Props {
+  client: {
+    id: string;
+    fullName: string;
+    status: string;
+    placeOfResidence: string | null;
+  };
+  onSaveName: (next: string | null) => Promise<void>;
+}
+
+const STATUS_TONE: Record<string, string> = {
+  prospect: 'bg-blue-100 text-blue-900',
+  active: 'bg-emerald-100 text-emerald-900',
+  inactive: 'bg-muted text-muted-foreground',
+};
+
+const STATUS_LABEL: Record<string, string> = {
+  prospect: 'Prospect',
+  active: 'Active',
+  inactive: 'Inactive',
+};
+
+export function ResidentialClientDetailHeader({ client, onSaveName }: Props) {
+  return (
+    <DetailHeaderStrip>
+      <div className="space-y-1">
+        <div className="text-xs font-semibold uppercase tracking-wide text-muted-foreground inline-flex items-center gap-1.5">
+          <Home className="h-3 w-3" /> Residential client
+        </div>
+        <h1 className="truncate text-2xl font-bold tracking-tight text-foreground">
+          <InlineEditableField value={client.fullName} onSave={onSaveName} />
+        </h1>
+        <div className="flex flex-wrap items-center gap-2 text-sm text-muted-foreground">
+          <Badge className={STATUS_TONE[client.status] ?? 'bg-muted'}>
+            {STATUS_LABEL[client.status] ?? client.status}
+          </Badge>
+          {client.placeOfResidence && <span>{client.placeOfResidence}</span>}
+        </div>
+      </div>
+    </DetailHeaderStrip>
+  );
+}

src/components/residential/residential-client-detail.tsx

@@ -1,25 +1,16 @@
 'use client';
 
-import { useState } from 'react';
-import Link from 'next/link';
+import { useEffect, useMemo } from 'react';
 import { useParams } from 'next/navigation';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { ArrowLeft, Plus } from 'lucide-react';
-import { toast } from 'sonner';
 
-import { Button } from '@/components/ui/button';
-import { Input } from '@/components/ui/input';
-import { Label } from '@/components/ui/label';
-import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
-import { InlineEditableField } from '@/components/shared/inline-editable-field';
-import { InlineCountryField } from '@/components/shared/inline-country-field';
-import { InlineTimezoneField } from '@/components/shared/inline-timezone-field';
-import { InlinePhoneField } from '@/components/shared/inline-phone-field';
-import { SubdivisionCombobox } from '@/components/shared/subdivision-combobox';
+import { DetailLayout } from '@/components/shared/detail-layout';
+import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { useBreadcrumbHint } from '@/hooks/use-breadcrumb-hint';
 import { apiFetch } from '@/lib/api/client';
-import { toastError } from '@/lib/api/toast-error';
-import type { CountryCode } from '@/lib/i18n/countries';
+import { ResidentialClientDetailHeader } from '@/components/residential/residential-client-detail-header';
+import { getResidentialClientTabs } from '@/components/residential/residential-client-tabs';
 
 interface ResidentialInterestSummary {
   id: string;
@@ -30,7 +21,7 @@ interface ResidentialInterestSummary {
   updatedAt: string;
 }
 
-interface ResidentialClientDetail {
+interface ResidentialClient {
   id: string;
   fullName: string;
   email: string | null;
@@ -49,45 +40,32 @@ interface ResidentialClientDetail {
   interests: ResidentialInterestSummary[];
 }
 
-const STATUS_OPTIONS = [
-  { value: 'prospect', label: 'Prospect' },
-  { value: 'active', label: 'Active' },
-  { value: 'inactive', label: 'Inactive' },
-];
+interface Stage {
+  id: string;
+  label: string;
+}
 
-const CONTACT_OPTIONS = [
-  { value: 'email', label: 'Email' },
-  { value: 'phone', label: 'Phone' },
-];
-
-const SOURCE_OPTIONS = [
-  { value: 'website', label: 'Website' },
-  { value: 'manual', label: 'Manual' },
-  { value: 'referral', label: 'Referral' },
-  { value: 'broker', label: 'Broker' },
-];
-
-const STAGE_LABELS: Record<string, string> = {
-  new: 'New',
-  contacted: 'Contacted',
-  viewing_scheduled: 'Viewing scheduled',
-  offer_made: 'Offer made',
-  offer_accepted: 'Offer accepted',
-  closed_won: 'Closed - won',
-  closed_lost: 'Closed - lost',
-};
-
-export function ResidentialClientDetail({ clientId }: { clientId: string }) {
+export function ResidentialClientDetail({
+  clientId,
+  currentUserId,
+}: {
+  clientId: string;
+  currentUserId?: string;
+}) {
   const params = useParams<{ portSlug: string }>();
   const portSlug = params?.portSlug ?? '';
   const qc = useQueryClient();
-  const [newInterestOpen, setNewInterestOpen] = useState(false);
 
-  const { data, isLoading } = useQuery<{ data: ResidentialClientDetail }>({
+  const { data, isLoading } = useQuery<{ data: ResidentialClient }>({
     queryKey: ['residential-client', clientId],
     queryFn: () => apiFetch(`/api/v1/residential/clients/${clientId}`),
   });
 
+  const { data: stagesData } = useQuery<{ data: { stages: Stage[] } }>({
+    queryKey: ['residential-stages', portSlug],
+    queryFn: () => apiFetch('/api/v1/residential/stages'),
+  });
+
   useRealtimeInvalidation({
     'residential_client:updated': [['residential-client', clientId]],
     'residential_interest:created': [['residential-client', clientId]],
@@ -97,266 +75,51 @@ export function ResidentialClientDetail({ clientId }: { clientId: string }) {
 
   const update = useMutation({
     mutationFn: (patch: Record<string, unknown>) =>
-      apiFetch(`/api/v1/residential/clients/${clientId}`, {
-        method: 'PATCH',
-        body: patch,
-      }),
+      apiFetch(`/api/v1/residential/clients/${clientId}`, { method: 'PATCH', body: patch }),
     onSuccess: () => qc.invalidateQueries({ queryKey: ['residential-client', clientId] }),
   });
 
-  const save = (field: string) => async (next: string | null) => {
-    await update.mutateAsync({ [field]: next });
-  };
+  const { setChrome } = useMobileChrome();
+  const titleForChrome = data?.data?.fullName ?? null;
+  useEffect(() => {
+    setChrome({ title: titleForChrome, showBackButton: true });
+    return () => setChrome({ title: null, showBackButton: false });
+  }, [titleForChrome, setChrome]);
 
-  if (isLoading || !data) {
-    return <div className="text-sm text-muted-foreground">Loading…</div>;
-  }
-  const client = data.data;
+  // Topbar breadcrumb hint — Residential › Clients › <name>
+  useBreadcrumbHint(data ? { parents: [], current: data.data.fullName } : null);
+
+  const stageLabels = useMemo(() => {
+    const map: Record<string, string> = {};
+    for (const s of stagesData?.data.stages ?? []) map[s.id] = s.label;
+    return map;
+  }, [stagesData]);
+
+  const tabs = data
+    ? getResidentialClientTabs({
+        clientId,
+        client: data.data,
+        portSlug,
+        currentUserId,
+        stageLabels,
+      })
+    : [];
 
   return (
-    <div className="space-y-6">
-      <div>
-        <Link
-          /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-          href={`/${portSlug}/residential/clients` as any}
-          className="text-sm text-muted-foreground hover:text-foreground inline-flex items-center gap-1"
-        >
-          <ArrowLeft className="h-3 w-3" /> All residential clients
-        </Link>
-      </div>
-
-      <div className="rounded-xl border border-slate-200 bg-gradient-brand-soft px-5 py-4 shadow-xs">
-        <div className="text-xs font-semibold uppercase tracking-wide text-brand">
-          Residential Client
-        </div>
-        <h1 className="mt-1 truncate text-2xl font-bold tracking-tight text-foreground">
-          <InlineEditableField value={client.fullName} onSave={save('fullName')} />
-        </h1>
-      </div>
-
-      <div className="rounded-lg border bg-card p-6 space-y-6">
-        <div className="grid grid-cols-1 lg:grid-cols-[2fr_1fr] gap-6">
-          <div className="space-y-1">
-            <h3 className="text-sm font-medium mb-2">Contact</h3>
-            <Row label="Email">
-              <InlineEditableField value={client.email} onSave={save('email')} />
-            </Row>
-            <Row label="Phone">
-              <InlinePhoneField
-                e164={client.phoneE164}
-                country={client.phoneCountry}
-                onSave={async ({ e164, country }) => {
-                  await update.mutateAsync({
-                    phone: e164,
-                    phoneE164: e164,
-                    phoneCountry: country,
-                  });
-                }}
-              />
-            </Row>
-            <Row label="Preferred contact">
-              <InlineEditableField
-                variant="select"
-                options={CONTACT_OPTIONS}
-                value={client.preferredContactMethod}
-                onSave={save('preferredContactMethod')}
-              />
-            </Row>
-            <Row label="Nationality">
-              <InlineCountryField
-                value={client.nationalityIso}
-                onSave={async (iso) => {
-                  await update.mutateAsync({ nationalityIso: iso });
-                }}
-              />
-            </Row>
-            <Row label="Timezone">
-              <InlineTimezoneField
-                value={client.timezone}
-                countryHint={(client.nationalityIso as CountryCode | null) ?? null}
-                onSave={async (tz) => {
-                  await update.mutateAsync({ timezone: tz });
-                }}
-              />
-            </Row>
-            <Row label="Place of residence">
-              <InlineEditableField
-                value={client.placeOfResidence}
-                onSave={save('placeOfResidence')}
-              />
-            </Row>
-            <Row label="Country of residence">
-              <InlineCountryField
-                value={client.placeOfResidenceCountryIso}
-                onSave={async (iso) => {
-                  // When country flips, clear the subdivision - codes are country-scoped.
-                  await update.mutateAsync({
-                    placeOfResidenceCountryIso: iso,
-                    subdivisionIso: null,
-                  });
-                }}
-              />
-            </Row>
-            <Row label="Region">
-              <SubdivisionCombobox
-                value={client.subdivisionIso}
-                onChange={(code) => {
-                  void update.mutateAsync({ subdivisionIso: code });
-                }}
-                country={(client.placeOfResidenceCountryIso as CountryCode | null) ?? null}
-              />
-            </Row>
-          </div>
-
-          <div className="space-y-1">
-            <h3 className="text-sm font-medium mb-2">Status</h3>
-            <Row label="Status">
-              <InlineEditableField
-                variant="select"
-                options={STATUS_OPTIONS}
-                value={client.status}
-                onSave={save('status')}
-              />
-            </Row>
-            <Row label="Source">
-              <InlineEditableField
-                variant="select"
-                options={SOURCE_OPTIONS}
-                value={client.source}
-                onSave={save('source')}
-              />
-            </Row>
-            <Row label="Notes">
-              <InlineEditableField value={client.notes} onSave={save('notes')} />
-            </Row>
-          </div>
-        </div>
-      </div>
-
-      <div className="rounded-lg border bg-card p-6">
-        <div className="flex items-center justify-between mb-4">
-          <h2 className="text-lg font-semibold">Interests</h2>
-          <Button size="sm" onClick={() => setNewInterestOpen(true)}>
-            <Plus className="h-3.5 w-3.5 mr-1.5" />
-            New interest
-          </Button>
-        </div>
-        {client.interests.length === 0 ? (
-          <p className="text-sm text-muted-foreground">No interests yet.</p>
-        ) : (
-          <ul className="space-y-2">
-            {client.interests.map((i) => (
-              <li key={i.id} className="flex items-center gap-3 p-3 rounded-md border bg-muted/30">
-                <span className="text-xs font-medium uppercase text-muted-foreground w-32 shrink-0">
-                  {STAGE_LABELS[i.pipelineStage] ?? i.pipelineStage}
-                </span>
-                <span className="flex-1 truncate text-sm">{i.preferences || i.notes || '-'}</span>
-                <Link
-                  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-                  href={`/${portSlug}/residential/interests/${i.id}` as any}
-                  className="text-xs text-primary hover:underline"
-                >
-                  View
-                </Link>
-              </li>
-            ))}
-          </ul>
-        )}
-      </div>
-
-      <NewInterestSheet
-        clientId={clientId}
-        open={newInterestOpen}
-        onOpenChange={setNewInterestOpen}
-      />
-    </div>
-  );
-}
-
-function Row({ label, children }: { label: string; children: React.ReactNode }) {
-  return (
-    <div className="flex gap-2 py-1.5 border-b last:border-0 items-center">
-      <dt className="w-40 shrink-0 text-sm text-muted-foreground">{label}</dt>
-      <dd className="flex-1 min-w-0">{children}</dd>
-    </div>
-  );
-}
-
-function NewInterestSheet({
-  clientId,
-  open,
-  onOpenChange,
-}: {
-  clientId: string;
-  open: boolean;
-  onOpenChange: (v: boolean) => void;
-}) {
-  const qc = useQueryClient();
-  const [preferences, setPreferences] = useState('');
-  const [notes, setNotes] = useState('');
-
-  const create = useMutation({
-    mutationFn: () =>
-      apiFetch('/api/v1/residential/interests', {
-        method: 'POST',
-        body: {
-          residentialClientId: clientId,
-          preferences: preferences || undefined,
-          notes: notes || undefined,
-          source: 'manual',
-        },
-      }),
-    onSuccess: () => {
-      qc.invalidateQueries({ queryKey: ['residential-client', clientId] });
-      onOpenChange(false);
-      setPreferences('');
-      setNotes('');
-      toast.success('Interest added');
-    },
-    onError: (err) => toastError(err),
-  });
-
-  return (
-    <Sheet open={open} onOpenChange={onOpenChange}>
-      <SheetContent>
-        <SheetHeader>
-          <SheetTitle>New interest</SheetTitle>
-        </SheetHeader>
-        <form
-          className="mt-6 space-y-4"
-          onSubmit={(e) => {
-            e.preventDefault();
-            create.mutate();
-          }}
-        >
-          <div className="space-y-1.5">
-            <Label htmlFor="ri-prefs">Preferences</Label>
-            <Input
-              id="ri-prefs"
-              value={preferences}
-              onChange={(e) => setPreferences(e.target.value)}
-              placeholder="Unit type, size, budget…"
-            />
-          </div>
-          <div className="space-y-1.5">
-            <Label htmlFor="ri-notes">Notes</Label>
-            <Input id="ri-notes" value={notes} onChange={(e) => setNotes(e.target.value)} />
-          </div>
-          <SheetFooter>
-            <Button
-              type="button"
-              variant="outline"
-              onClick={() => onOpenChange(false)}
-              disabled={create.isPending}
-            >
-              Cancel
-            </Button>
-            <Button type="submit" disabled={create.isPending}>
-              {create.isPending ? 'Saving…' : 'Create'}
-            </Button>
-          </SheetFooter>
-        </form>
-      </SheetContent>
-    </Sheet>
+    <DetailLayout
+      header={
+        data ? (
+          <ResidentialClientDetailHeader
+            client={data.data}
+            onSaveName={async (next) => {
+              await update.mutateAsync({ fullName: next });
+            }}
+          />
+        ) : null
+      }
+      tabs={tabs}
+      defaultTab="overview"
+      isLoading={isLoading}
+    />
   );
 }

src/components/residential/residential-client-tabs.tsx

@@ -0,0 +1,361 @@
+'use client';
+
+import Link from 'next/link';
+import { useState } from 'react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Plus } from 'lucide-react';
+
+import type { DetailTab } from '@/components/shared/detail-layout';
+import { Button } from '@/components/ui/button';
+import { InlineEditableField } from '@/components/shared/inline-editable-field';
+import { InlineCountryField } from '@/components/shared/inline-country-field';
+import { InlineTimezoneField } from '@/components/shared/inline-timezone-field';
+import { InlinePhoneField } from '@/components/shared/inline-phone-field';
+import { SubdivisionCombobox } from '@/components/shared/subdivision-combobox';
+import { NotesList } from '@/components/shared/notes-list';
+import { EntityActivityFeed } from '@/components/shared/entity-activity-feed';
+import { apiFetch } from '@/lib/api/client';
+import type { CountryCode } from '@/lib/i18n/countries';
+
+interface ResidentialInterestSummary {
+  id: string;
+  pipelineStage: string;
+  source: string | null;
+  notes: string | null;
+  preferences: string | null;
+  updatedAt: string;
+}
+
+interface ResidentialClient {
+  id: string;
+  fullName: string;
+  email: string | null;
+  phone: string | null;
+  phoneE164: string | null;
+  phoneCountry: string | null;
+  nationalityIso: string | null;
+  timezone: string | null;
+  placeOfResidence: string | null;
+  placeOfResidenceCountryIso: string | null;
+  subdivisionIso: string | null;
+  preferredContactMethod: string | null;
+  status: string;
+  source: string | null;
+  notes: string | null;
+  interests: ResidentialInterestSummary[];
+}
+
+interface Args {
+  clientId: string;
+  client: ResidentialClient;
+  portSlug: string;
+  currentUserId?: string;
+  stageLabels: Record<string, string>;
+}
+
+const STATUS_OPTIONS = [
+  { value: 'prospect', label: 'Prospect' },
+  { value: 'active', label: 'Active' },
+  { value: 'inactive', label: 'Inactive' },
+];
+const CONTACT_OPTIONS = [
+  { value: 'email', label: 'Email' },
+  { value: 'phone', label: 'Phone' },
+];
+const SOURCE_OPTIONS = [
+  { value: 'website', label: 'Website' },
+  { value: 'manual', label: 'Manual' },
+  { value: 'referral', label: 'Referral' },
+  { value: 'broker', label: 'Broker' },
+  { value: 'other', label: 'Other' },
+];
+
+function Row({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className="flex gap-2 py-1.5 border-b last:border-0 items-center">
+      <dt className="w-44 shrink-0 text-sm text-muted-foreground">{label}</dt>
+      <dd className="flex-1 min-w-0">{children}</dd>
+    </div>
+  );
+}
+
+export function getResidentialClientTabs({
+  clientId,
+  client,
+  portSlug,
+  currentUserId,
+  stageLabels,
+}: Args): DetailTab[] {
+  return [
+    {
+      id: 'overview',
+      label: 'Overview',
+      content: (
+        <OverviewTab
+          clientId={clientId}
+          client={client}
+          portSlug={portSlug}
+          stageLabels={stageLabels}
+        />
+      ),
+    },
+    {
+      id: 'interests',
+      label: 'Interests',
+      badge: client.interests.length || undefined,
+      content: (
+        <InterestsTab
+          clientId={clientId}
+          client={client}
+          portSlug={portSlug}
+          stageLabels={stageLabels}
+        />
+      ),
+    },
+    {
+      id: 'notes',
+      label: 'Notes',
+      content: (
+        <NotesList
+          entityType="residential_clients"
+          entityId={clientId}
+          currentUserId={currentUserId}
+        />
+      ),
+    },
+    {
+      id: 'activity',
+      label: 'Activity',
+      content: (
+        <EntityActivityFeed
+          endpoint={`/api/v1/residential/clients/${clientId}/activity`}
+          emptyText="No activity recorded for this residential client yet."
+        />
+      ),
+    },
+  ];
+}
+
+function useClientPatch(clientId: string) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (patch: Record<string, unknown>) =>
+      apiFetch(`/api/v1/residential/clients/${clientId}`, { method: 'PATCH', body: patch }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['residential-client', clientId] }),
+  });
+}
+
+function OverviewTab({
+  clientId,
+  client,
+}: {
+  clientId: string;
+  client: ResidentialClient;
+  portSlug: string;
+  stageLabels: Record<string, string>;
+}) {
+  const update = useClientPatch(clientId);
+  const save = (field: string) => async (next: string | null) => {
+    await update.mutateAsync({ [field]: next });
+  };
+
+  return (
+    <div className="rounded-lg border bg-card p-6 space-y-6">
+      <div className="grid grid-cols-1 lg:grid-cols-[2fr_1fr] gap-6">
+        <div className="space-y-1">
+          <h3 className="text-sm font-medium mb-2">Contact</h3>
+          <Row label="Email">
+            <InlineEditableField value={client.email} onSave={save('email')} />
+          </Row>
+          <Row label="Phone">
+            <InlinePhoneField
+              e164={client.phoneE164}
+              country={client.phoneCountry}
+              onSave={async ({ e164, country }) => {
+                await update.mutateAsync({ phone: e164, phoneE164: e164, phoneCountry: country });
+              }}
+            />
+          </Row>
+          <Row label="Preferred contact">
+            <InlineEditableField
+              variant="select"
+              options={CONTACT_OPTIONS}
+              value={client.preferredContactMethod}
+              onSave={save('preferredContactMethod')}
+            />
+          </Row>
+          <Row label="Country">
+            <InlineCountryField
+              value={client.nationalityIso}
+              onSave={async (iso) => {
+                await update.mutateAsync({ nationalityIso: iso });
+              }}
+            />
+          </Row>
+          <Row label="Timezone">
+            <InlineTimezoneField
+              value={client.timezone}
+              countryHint={(client.nationalityIso as CountryCode | null) ?? null}
+              onSave={async (tz) => {
+                await update.mutateAsync({ timezone: tz });
+              }}
+            />
+          </Row>
+          <Row label="Place of residence">
+            <InlineEditableField
+              value={client.placeOfResidence}
+              onSave={save('placeOfResidence')}
+            />
+          </Row>
+          <Row label="Country of residence">
+            <InlineCountryField
+              value={client.placeOfResidenceCountryIso}
+              onSave={async (iso) => {
+                await update.mutateAsync({ placeOfResidenceCountryIso: iso, subdivisionIso: null });
+              }}
+            />
+          </Row>
+          <Row label="Region">
+            <SubdivisionCombobox
+              value={client.subdivisionIso}
+              onChange={(code) => {
+                void update.mutateAsync({ subdivisionIso: code });
+              }}
+              country={(client.placeOfResidenceCountryIso as CountryCode | null) ?? null}
+            />
+          </Row>
+        </div>
+
+        <div className="space-y-1">
+          <h3 className="text-sm font-medium mb-2">Status</h3>
+          <Row label="Status">
+            <InlineEditableField
+              variant="select"
+              options={STATUS_OPTIONS}
+              value={client.status}
+              onSave={save('status')}
+            />
+          </Row>
+          <Row label="Source">
+            <InlineEditableField
+              variant="select"
+              options={SOURCE_OPTIONS}
+              value={client.source}
+              onSave={save('source')}
+            />
+          </Row>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function InterestsTab({
+  clientId,
+  client,
+  portSlug,
+  stageLabels,
+}: {
+  clientId: string;
+  client: ResidentialClient;
+  portSlug: string;
+  stageLabels: Record<string, string>;
+}) {
+  const [open, setOpen] = useState(false);
+  return (
+    <div className="rounded-lg border bg-card p-6">
+      <div className="flex items-center justify-between mb-4">
+        <h2 className="text-lg font-semibold">Interests</h2>
+        <Button size="sm" onClick={() => setOpen(true)}>
+          <Plus className="h-3.5 w-3.5 mr-1.5" />
+          New interest
+        </Button>
+      </div>
+      {client.interests.length === 0 ? (
+        <p className="text-sm text-muted-foreground">No interests yet.</p>
+      ) : (
+        <ul className="space-y-2">
+          {client.interests.map((i) => (
+            <li key={i.id} className="flex items-center gap-3 p-3 rounded-md border bg-muted/30">
+              <span className="text-xs font-medium uppercase text-muted-foreground w-32 shrink-0">
+                {stageLabels[i.pipelineStage] ?? i.pipelineStage}
+              </span>
+              <span className="flex-1 truncate text-sm">{i.preferences || i.notes || '-'}</span>
+              <Link
+                /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+                href={`/${portSlug}/residential/interests/${i.id}` as any}
+                className="text-xs text-primary hover:underline"
+              >
+                View
+              </Link>
+            </li>
+          ))}
+        </ul>
+      )}
+      {open && <NewInterestDialog clientId={clientId} open={open} onOpenChange={setOpen} />}
+    </div>
+  );
+}
+
+function NewInterestDialog({
+  clientId,
+  open,
+  onOpenChange,
+}: {
+  clientId: string;
+  open: boolean;
+  onOpenChange: (v: boolean) => void;
+}) {
+  const qc = useQueryClient();
+  const [preferences, setPreferences] = useState('');
+  const [notes, setNotes] = useState('');
+  const create = useMutation({
+    mutationFn: () =>
+      apiFetch('/api/v1/residential/interests', {
+        method: 'POST',
+        body: {
+          residentialClientId: clientId,
+          preferences: preferences || undefined,
+          notes: notes || undefined,
+          source: 'manual',
+        },
+      }),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ['residential-client', clientId] });
+      onOpenChange(false);
+      setPreferences('');
+      setNotes('');
+    },
+  });
+
+  if (!open) return null;
+  return (
+    <div className="fixed inset-0 z-50 grid place-items-center bg-black/40 p-4">
+      <div className="w-full max-w-md rounded-lg border bg-card p-6 shadow-lg space-y-3">
+        <h3 className="text-sm font-medium">New residential interest</h3>
+        <textarea
+          className="w-full rounded-md border px-3 py-2 text-sm"
+          rows={3}
+          placeholder="Preferences (unit type / size / budget / floor)"
+          value={preferences}
+          onChange={(e) => setPreferences(e.target.value)}
+        />
+        <textarea
+          className="w-full rounded-md border px-3 py-2 text-sm"
+          rows={3}
+          placeholder="Initial notes"
+          value={notes}
+          onChange={(e) => setNotes(e.target.value)}
+        />
+        <div className="flex justify-end gap-2">
+          <Button variant="outline" size="sm" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button size="sm" onClick={() => create.mutate()} disabled={create.isPending}>
+            {create.isPending ? 'Creating…' : 'Create'}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/residential/residential-clients-list.tsx

@@ -130,8 +130,44 @@ export function ResidentialClientsList() {
                     {c.fullName}
                   </Link>
                 </td>
-                <td className="px-3 py-2 text-muted-foreground">{c.email ?? '-'}</td>
-                <td className="px-3 py-2 text-muted-foreground">{c.phone ?? '-'}</td>
+                <td className="px-3 py-2 text-muted-foreground">
+                  {c.email ? (
+                    <a
+                      href={`mailto:${c.email}`}
+                      className="text-primary hover:underline"
+                      onClick={(e) => e.stopPropagation()}
+                    >
+                      {c.email}
+                    </a>
+                  ) : (
+                    '-'
+                  )}
+                </td>
+                <td className="px-3 py-2 text-muted-foreground">
+                  {c.phone ? (
+                    <span className="inline-flex items-center gap-1.5">
+                      <a
+                        href={`tel:${c.phone}`}
+                        className="text-primary hover:underline"
+                        onClick={(e) => e.stopPropagation()}
+                      >
+                        {c.phone}
+                      </a>
+                      <a
+                        href={`https://wa.me/${c.phone.replace(/[^\d+]/g, '')}`}
+                        target="_blank"
+                        rel="noreferrer"
+                        title="WhatsApp"
+                        className="text-emerald-600 hover:text-emerald-700"
+                        onClick={(e) => e.stopPropagation()}
+                      >
+                        WA
+                      </a>
+                    </span>
+                  ) : (
+                    '-'
+                  )}
+                </td>
                 <td className="px-3 py-2 text-muted-foreground">{c.placeOfResidence ?? '-'}</td>
                 <td className="px-3 py-2">{STATUS_LABELS[c.status] ?? c.status}</td>
                 <td className="px-3 py-2 capitalize text-muted-foreground">{c.source ?? '-'}</td>

src/components/residential/residential-interest-detail.tsx

@@ -1,16 +1,19 @@
 'use client';
 
-import Link from 'next/link';
+import { useEffect, useMemo } from 'react';
 import { useParams } from 'next/navigation';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { ArrowLeft } from 'lucide-react';
 
-import { InlineEditableField } from '@/components/shared/inline-editable-field';
+import { Badge } from '@/components/ui/badge';
+import { DetailLayout } from '@/components/shared/detail-layout';
+import { DetailHeaderStrip } from '@/components/shared/detail-header-strip';
+import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { useBreadcrumbHint } from '@/hooks/use-breadcrumb-hint';
 import { apiFetch } from '@/lib/api/client';
-import { PIPELINE_STAGES } from '@/lib/validators/residential';
+import { getResidentialInterestTabs } from '@/components/residential/residential-interest-tabs';
 
-interface ResidentialInterestDetail {
+interface ResidentialInterest {
   id: string;
   residentialClientId: string;
   pipelineStage: string;
@@ -21,38 +24,33 @@ interface ResidentialInterestDetail {
   client: { id: string; fullName: string } | null;
 }
 
-const STAGE_LABELS: Record<string, string> = {
-  new: 'New',
-  contacted: 'Contacted',
-  viewing_scheduled: 'Viewing scheduled',
-  offer_made: 'Offer made',
-  offer_accepted: 'Offer accepted',
-  closed_won: 'Closed - won',
-  closed_lost: 'Closed - lost',
-};
+interface Stage {
+  id: string;
+  label: string;
+  terminal: 'won' | 'lost' | null;
+}
 
-const STAGE_OPTIONS = PIPELINE_STAGES.map((s) => ({
-  value: s,
-  label: STAGE_LABELS[s] ?? s,
-}));
-
-const SOURCE_OPTIONS = [
-  { value: 'website', label: 'Website' },
-  { value: 'manual', label: 'Manual' },
-  { value: 'referral', label: 'Referral' },
-  { value: 'broker', label: 'Broker' },
-];
-
-export function ResidentialInterestDetail({ interestId }: { interestId: string }) {
+export function ResidentialInterestDetail({
+  interestId,
+  currentUserId,
+}: {
+  interestId: string;
+  currentUserId?: string;
+}) {
   const params = useParams<{ portSlug: string }>();
   const portSlug = params?.portSlug ?? '';
   const qc = useQueryClient();
 
-  const { data, isLoading } = useQuery<{ data: ResidentialInterestDetail }>({
+  const { data, isLoading } = useQuery<{ data: ResidentialInterest }>({
     queryKey: ['residential-interest', interestId],
     queryFn: () => apiFetch(`/api/v1/residential/interests/${interestId}`),
   });
 
+  const { data: stagesData } = useQuery<{ data: { stages: Stage[] } }>({
+    queryKey: ['residential-stages', portSlug],
+    queryFn: () => apiFetch('/api/v1/residential/stages'),
+  });
+
   useRealtimeInvalidation({
     'residential_interest:updated': [['residential-interest', interestId]],
   });
@@ -65,94 +63,75 @@ export function ResidentialInterestDetail({ interestId }: { interestId: string }
       }),
     onSuccess: () => qc.invalidateQueries({ queryKey: ['residential-interest', interestId] }),
   });
+  void update;
 
-  const save = (field: string) => async (next: string | null) => {
-    await update.mutateAsync({ [field]: next });
-  };
+  const { setChrome } = useMobileChrome();
+  const titleForChrome = data?.data?.client?.fullName ?? null;
+  useEffect(() => {
+    setChrome({ title: titleForChrome, showBackButton: true });
+    return () => setChrome({ title: null, showBackButton: false });
+  }, [titleForChrome, setChrome]);
 
-  if (isLoading || !data) {
-    return <div className="text-sm text-muted-foreground">Loading…</div>;
-  }
-  const interest = data.data;
+  // Breadcrumb: Residential › Interests › <client> › <stage>
+  useBreadcrumbHint(
+    data
+      ? {
+          parents:
+            data.data.client && data.data.residentialClientId
+              ? [
+                  {
+                    label: data.data.client.fullName,
+                    href: `/${portSlug}/residential/clients/${data.data.residentialClientId}`,
+                  },
+                ]
+              : [],
+          current: 'Interest',
+        }
+      : null,
+  );
+
+  const stageOptions = useMemo(
+    () =>
+      (stagesData?.data.stages ?? []).map((s) => ({
+        value: s.id,
+        label: s.label,
+      })),
+    [stagesData],
+  );
+  const stageLabel = useMemo(() => {
+    const s = stagesData?.data.stages.find((x) => x.id === data?.data.pipelineStage);
+    return s?.label ?? data?.data.pipelineStage ?? '';
+  }, [stagesData, data]);
+
+  const tabs = data
+    ? getResidentialInterestTabs({
+        interestId,
+        interest: data.data,
+        currentUserId,
+        stageOptions,
+      })
+    : [];
 
   return (
-    <div className="space-y-6">
-      <div>
-        <Link
-          /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-          href={`/${portSlug}/residential/interests` as any}
-          className="text-sm text-muted-foreground hover:text-foreground inline-flex items-center gap-1"
-        >
-          <ArrowLeft className="h-3 w-3" /> All residential interests
-        </Link>
-      </div>
-
-      <div className="rounded-xl border border-border bg-gradient-brand-soft px-5 py-4 shadow-xs">
-        <p className="text-xs uppercase font-semibold tracking-wide text-brand">
-          Residential interest
-        </p>
-        {interest.client && (
-          <h1 className="mt-1 truncate text-2xl font-bold tracking-tight text-foreground">
-            <Link
-              /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-              href={`/${portSlug}/residential/clients/${interest.client.id}` as any}
-              className="hover:underline"
-            >
-              {interest.client.fullName}
-            </Link>
-          </h1>
-        )}
-      </div>
-
-      <div className="rounded-lg border bg-card p-6 space-y-6">
-        <div className="grid grid-cols-1 lg:grid-cols-[2fr_1fr] gap-6">
-          <div className="space-y-1">
-            <h3 className="text-sm font-medium mb-2">Pipeline</h3>
-            <Row label="Stage">
-              <InlineEditableField
-                variant="select"
-                options={STAGE_OPTIONS}
-                value={interest.pipelineStage}
-                onSave={save('pipelineStage')}
-              />
-            </Row>
-            <Row label="Source">
-              <InlineEditableField
-                variant="select"
-                options={SOURCE_OPTIONS}
-                value={interest.source}
-                onSave={save('source')}
-              />
-            </Row>
-            <Row label="Assigned to">
-              <InlineEditableField
-                value={interest.assignedTo}
-                onSave={save('assignedTo')}
-                placeholder="user id"
-              />
-            </Row>
-          </div>
-
-          <div className="space-y-1">
-            <h3 className="text-sm font-medium mb-2">Details</h3>
-            <Row label="Preferences">
-              <InlineEditableField value={interest.preferences} onSave={save('preferences')} />
-            </Row>
-            <Row label="Notes">
-              <InlineEditableField value={interest.notes} onSave={save('notes')} />
-            </Row>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-function Row({ label, children }: { label: string; children: React.ReactNode }) {
-  return (
-    <div className="flex gap-2 py-1.5 border-b last:border-0 items-center">
-      <dt className="w-40 shrink-0 text-sm text-muted-foreground">{label}</dt>
-      <dd className="flex-1 min-w-0">{children}</dd>
-    </div>
+    <DetailLayout
+      header={
+        data ? (
+          <DetailHeaderStrip>
+            <div className="space-y-1">
+              <div className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                Residential interest
+              </div>
+              <h1 className="truncate text-2xl font-bold tracking-tight text-foreground">
+                {data.data.client?.fullName ?? 'Unknown client'}
+              </h1>
+              <Badge variant="outline">{stageLabel}</Badge>
+            </div>
+          </DetailHeaderStrip>
+        ) : null
+      }
+      tabs={tabs}
+      defaultTab="overview"
+      isLoading={isLoading}
+    />
   );
 }

src/components/residential/residential-interest-tabs.tsx

@@ -0,0 +1,171 @@
+'use client';
+
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+
+import type { DetailTab } from '@/components/shared/detail-layout';
+import { InlineEditableField } from '@/components/shared/inline-editable-field';
+import { NotesList } from '@/components/shared/notes-list';
+import { EntityActivityFeed } from '@/components/shared/entity-activity-feed';
+import { apiFetch } from '@/lib/api/client';
+
+interface ResidentialInterest {
+  id: string;
+  residentialClientId: string;
+  pipelineStage: string;
+  source: string | null;
+  notes: string | null;
+  preferences: string | null;
+  assignedTo: string | null;
+}
+
+interface Args {
+  interestId: string;
+  interest: ResidentialInterest;
+  currentUserId?: string;
+  stageOptions: Array<{ value: string; label: string }>;
+}
+
+const SOURCE_OPTIONS = [
+  { value: 'website', label: 'Website' },
+  { value: 'manual', label: 'Manual' },
+  { value: 'referral', label: 'Referral' },
+  { value: 'broker', label: 'Broker' },
+  { value: 'other', label: 'Other' },
+];
+
+function Row({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className="flex gap-2 py-1.5 border-b last:border-0 items-center">
+      <dt className="w-44 shrink-0 text-sm text-muted-foreground">{label}</dt>
+      <dd className="flex-1 min-w-0">{children}</dd>
+    </div>
+  );
+}
+
+export function getResidentialInterestTabs({
+  interestId,
+  interest,
+  currentUserId,
+  stageOptions,
+}: Args): DetailTab[] {
+  return [
+    {
+      id: 'overview',
+      label: 'Overview',
+      content: (
+        <OverviewTab interestId={interestId} interest={interest} stageOptions={stageOptions} />
+      ),
+    },
+    {
+      id: 'notes',
+      label: 'Notes',
+      content: (
+        <NotesList
+          entityType="residential_interests"
+          entityId={interestId}
+          currentUserId={currentUserId}
+        />
+      ),
+    },
+    {
+      id: 'activity',
+      label: 'Activity',
+      content: (
+        <EntityActivityFeed
+          endpoint={`/api/v1/residential/interests/${interestId}/activity`}
+          emptyText="No activity recorded for this residential interest yet."
+        />
+      ),
+    },
+  ];
+}
+
+function useInterestPatch(interestId: string) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (patch: Record<string, unknown>) =>
+      apiFetch(`/api/v1/residential/interests/${interestId}`, { method: 'PATCH', body: patch }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['residential-interest', interestId] }),
+  });
+}
+
+function OverviewTab({
+  interestId,
+  interest,
+  stageOptions,
+}: {
+  interestId: string;
+  interest: ResidentialInterest;
+  stageOptions: Array<{ value: string; label: string }>;
+}) {
+  const update = useInterestPatch(interestId);
+  const save = (field: string) => async (next: string | null) => {
+    await update.mutateAsync({ [field]: next });
+  };
+
+  // Pull users with residential access for the Assigned-to dropdown.
+  const { data: assignableUsers } = useQuery<{
+    data: Array<{ id: string; name: string; email: string }>;
+  }>({
+    queryKey: ['residential-assignable-users'],
+    queryFn: () => apiFetch('/api/v1/residential/assignable-users'),
+  });
+  const assigneeOptions = (assignableUsers?.data ?? []).map((u) => ({
+    value: u.id,
+    label: u.name || u.email,
+  }));
+
+  return (
+    <div className="rounded-lg border bg-card p-6 space-y-6">
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        <div className="space-y-1">
+          <h3 className="text-sm font-medium mb-2">Pipeline</h3>
+          <Row label="Stage">
+            <InlineEditableField
+              variant="select"
+              options={stageOptions}
+              value={interest.pipelineStage}
+              onSave={save('pipelineStage')}
+            />
+          </Row>
+          <Row label="Source">
+            <InlineEditableField
+              variant="select"
+              options={SOURCE_OPTIONS}
+              value={interest.source}
+              onSave={save('source')}
+            />
+          </Row>
+          <Row label="Assigned to">
+            <InlineEditableField
+              variant="select"
+              options={assigneeOptions}
+              value={interest.assignedTo}
+              onSave={save('assignedTo')}
+              placeholder="Unassigned"
+            />
+          </Row>
+        </div>
+
+        <div className="space-y-1">
+          <h3 className="text-sm font-medium mb-2">Details</h3>
+          <Row label="Preferences">
+            <InlineEditableField
+              variant="textarea"
+              value={interest.preferences}
+              onSave={save('preferences')}
+            />
+          </Row>
+          <Row label="Initial brief">
+            <InlineEditableField
+              variant="textarea"
+              value={interest.notes}
+              onSave={save('notes')}
+              emptyText="-"
+            />
+          </Row>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/residential/residential-interests-list.tsx

@@ -77,7 +77,7 @@ export function ResidentialInterestsList() {
           placeholder="Search notes / preferences…"
           value={search}
           onChange={(e) => setSearch(e.target.value)}
-          className="max-w-sm"
+          className="max-w-sm h-9"
         />
         <Select value={stage} onValueChange={setStage}>
           <SelectTrigger className="w-52">