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/settings/user-settings.tsx

@@ -1,15 +1,21 @@
 'use client';
 
-import { useState, useEffect } from 'react';
-import { Save } from 'lucide-react';
+import { useState, useEffect, useMemo, useRef } from 'react';
+import { Save, KeyRound, Globe, Upload } from 'lucide-react';
 
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Switch } from '@/components/ui/switch';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { PageHeader } from '@/components/shared/page-header';
+import { CountryCombobox } from '@/components/shared/country-combobox';
+import { TimezoneCombobox } from '@/components/shared/timezone-combobox';
+import { ImageCropperDialog } from '@/components/shared/image-cropper-dialog';
 import { apiFetch } from '@/lib/api/client';
+import { primaryTimezoneFor } from '@/lib/i18n/timezones';
+import type { CountryCode } from '@/lib/i18n/countries';
 
 interface NotificationPrefs {
   reminder_due: boolean;
@@ -21,13 +27,41 @@ interface NotificationPrefs {
   [key: string]: boolean;
 }
 
+interface MeResponse {
+  user?: { name: string; email: string };
+  preferences?: { country?: string; timezone?: string };
+  profile?: { avatarFileId?: string | null };
+}
+
 export function UserSettings() {
   const [notifPrefs, setNotifPrefs] = useState<NotificationPrefs | null>(null);
   const [displayName, setDisplayName] = useState('');
   const [phone, setPhone] = useState('');
-  const [timezone, setTimezone] = useState('');
+  const [email, setEmail] = useState('');
+  const [originalEmail, setOriginalEmail] = useState('');
+  const [country, setCountry] = useState<string | null>(null);
+  const [timezone, setTimezone] = useState<string | null>(null);
   const [saving, setSaving] = useState<string | null>(null);
   const [message, setMessage] = useState<string | null>(null);
+  const [resetMsg, setResetMsg] = useState<string | null>(null);
+  const [emailMsg, setEmailMsg] = useState<string | null>(null);
+  const [avatarFileId, setAvatarFileId] = useState<string | null>(null);
+  const [avatarUrl, setAvatarUrl] = useState<string | null>(null);
+  const [pendingAvatarFile, setPendingAvatarFile] = useState<File | null>(null);
+  const [cropperOpen, setCropperOpen] = useState(false);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  // Browser-detected timezone — surfaces a banner when the rep is
+  // travelling and the saved value no longer matches their device's
+  // locale. Quietly absent in SSR; the picker still works without it.
+  const detectedTz = useMemo(() => {
+    if (typeof Intl === 'undefined') return null;
+    try {
+      return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    } catch {
+      return null;
+    }
+  }, []);
 
   useEffect(() => {
     void loadProfile();
@@ -35,10 +69,35 @@ export function UserSettings() {
   }, []);
 
   async function loadProfile() {
-    const res = await apiFetch<{ data: { user?: { name: string } } }>('/api/v1/me', {
-      method: 'GET',
-    });
+    const res = await apiFetch<{ data: MeResponse }>('/api/v1/me', { method: 'GET' });
     setDisplayName(res.data.user?.name ?? '');
+    setEmail(res.data.user?.email ?? '');
+    setOriginalEmail(res.data.user?.email ?? '');
+    setCountry(res.data.preferences?.country ?? null);
+    setTimezone(res.data.preferences?.timezone ?? null);
+    const fid = res.data.profile?.avatarFileId ?? null;
+    setAvatarFileId(fid);
+    setAvatarUrl(fid ? `/api/v1/files/${fid}/preview` : null);
+  }
+
+  function handleAvatarPicked(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0] ?? null;
+    if (!file) return;
+    setPendingAvatarFile(file);
+    setCropperOpen(true);
+    // Reset so picking the same file twice still triggers onChange.
+    if (fileInputRef.current) fileInputRef.current.value = '';
+  }
+
+  async function uploadAvatar(blob: Blob) {
+    const fd = new FormData();
+    fd.append('file', new File([blob], 'avatar.jpg', { type: 'image/jpeg' }));
+    const res = await fetch('/api/v1/me/avatar', { method: 'POST', body: fd });
+    if (!res.ok) throw new Error('Avatar upload failed');
+    const json = (await res.json()) as { data: { avatarFileId: string } };
+    setAvatarFileId(json.data.avatarFileId);
+    // Cache-bust the preview URL with a query so the new image renders.
+    setAvatarUrl(`/api/v1/files/${json.data.avatarFileId}/preview?t=${Date.now()}`);
   }
 
   async function loadNotificationPrefs() {
@@ -46,7 +105,6 @@ export function UserSettings() {
       const res = await apiFetch<{ data: NotificationPrefs }>('/api/v1/notifications/preferences');
       setNotifPrefs(res.data);
     } catch {
-      // Preferences may not exist yet
       setNotifPrefs({
         reminder_due: true,
         reminder_overdue: true,
@@ -58,6 +116,16 @@ export function UserSettings() {
     }
   }
 
+  function handleCountryChange(iso: string | null) {
+    setCountry(iso);
+    // Auto-default timezone when the rep picks a country and hasn't
+    // explicitly set a timezone yet. Same trick as the client overview.
+    if (iso && !timezone) {
+      const tz = primaryTimezoneFor(iso as CountryCode);
+      if (tz) setTimezone(tz);
+    }
+  }
+
   async function saveProfile() {
     setSaving('profile');
     setMessage(null);
@@ -67,7 +135,10 @@ export function UserSettings() {
         body: {
           displayName: displayName || undefined,
           phone: phone || null,
-          preferences: { timezone: timezone || undefined },
+          preferences: {
+            country: country ?? undefined,
+            timezone: timezone ?? undefined,
+          },
         },
       });
       setMessage('Profile saved');
@@ -78,6 +149,34 @@ export function UserSettings() {
     }
   }
 
+  async function saveEmail() {
+    if (email === originalEmail) return;
+    setSaving('email');
+    setEmailMsg(null);
+    try {
+      await apiFetch('/api/v1/me/email', { method: 'PATCH', body: { email } });
+      setOriginalEmail(email);
+      setEmailMsg('Email updated. Use the new address next time you sign in.');
+    } catch (err: unknown) {
+      setEmailMsg(err instanceof Error ? err.message : 'Failed to update email');
+    } finally {
+      setSaving(null);
+    }
+  }
+
+  async function requestPasswordReset() {
+    setSaving('password');
+    setResetMsg(null);
+    try {
+      await apiFetch('/api/v1/me/password-reset', { method: 'POST' });
+      setResetMsg('Password-reset email sent. Check your inbox.');
+    } catch (err: unknown) {
+      setResetMsg(err instanceof Error ? err.message : 'Failed to send reset email');
+    } finally {
+      setSaving(null);
+    }
+  }
+
   async function toggleNotifPref(key: string, value: boolean) {
     setSaving(key);
     try {
@@ -91,6 +190,10 @@ export function UserSettings() {
     }
   }
 
+  function adoptDetectedTz() {
+    if (detectedTz) setTimezone(detectedTz);
+  }
+
   const NOTIF_LABELS: Record<string, string> = {
     reminder_due: 'Reminder due',
     reminder_overdue: 'Reminder overdue',
@@ -100,6 +203,8 @@ export function UserSettings() {
     duplicate_alert: 'Duplicate client detected',
   };
 
+  const tzMismatch = detectedTz && timezone && detectedTz !== timezone;
+
   return (
     <div>
       <PageHeader title="Settings" description="Manage your profile and notification preferences" />
@@ -111,8 +216,42 @@ export function UserSettings() {
             <CardDescription>Update your display name and contact info</CardDescription>
           </CardHeader>
           <CardContent className="space-y-4">
+            {/* Avatar — click the photo to pick a file, which opens the
+                cropper. Cropped result uploads via /api/v1/me/avatar. */}
+            <div className="flex items-center gap-4">
+              <Avatar className="h-16 w-16">
+                {avatarUrl ? <AvatarImage src={avatarUrl} alt="Profile photo" /> : null}
+                <AvatarFallback>
+                  {(displayName || email || 'U').slice(0, 1).toUpperCase()}
+                </AvatarFallback>
+              </Avatar>
+              <div className="space-y-1">
+                <Label className="text-sm">Profile photo</Label>
+                <div>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    onClick={() => fileInputRef.current?.click()}
+                  >
+                    <Upload className="mr-1.5 h-3.5 w-3.5" />
+                    {avatarFileId ? 'Replace photo' : 'Upload photo'}
+                  </Button>
+                  <input
+                    ref={fileInputRef}
+                    type="file"
+                    accept="image/jpeg,image/png,image/webp"
+                    onChange={handleAvatarPicked}
+                    className="hidden"
+                  />
+                </div>
+                <p className="text-xs text-muted-foreground">
+                  PNG, JPG, or WebP up to 2 MB. You&apos;ll be able to crop after picking.
+                </p>
+              </div>
+            </div>
             <div className="space-y-2">
-              <Label htmlFor="settings-name">Display Name</Label>
+              <Label htmlFor="settings-name">Display name</Label>
               <Input
                 id="settings-name"
                 value={displayName}
@@ -131,24 +270,97 @@ export function UserSettings() {
               />
             </div>
             <div className="space-y-2">
-              <Label htmlFor="settings-tz">Timezone</Label>
-              <Input
-                id="settings-tz"
+              <Label>Country</Label>
+              <CountryCombobox value={country} onChange={handleCountryChange} />
+              <p className="text-xs text-muted-foreground">
+                Sets the default timezone when you pick a country and haven&apos;t chosen one
+                explicitly.
+              </p>
+            </div>
+            <div className="space-y-2">
+              <Label>Timezone</Label>
+              <TimezoneCombobox
                 value={timezone}
-                onChange={(e) => setTimezone(e.target.value)}
-                placeholder="America/Anguilla"
+                onChange={setTimezone}
+                countryHint={(country as CountryCode | null) ?? undefined}
               />
+              {tzMismatch && (
+                <div className="flex items-start gap-2 rounded-md border border-amber-300 bg-amber-50 px-3 py-2 text-xs text-amber-900">
+                  <Globe className="h-3.5 w-3.5 shrink-0 mt-0.5" />
+                  <div className="flex-1">
+                    Looks like you&apos;re in <strong>{detectedTz}</strong> right now (saved:{' '}
+                    {timezone}).
+                    <button
+                      type="button"
+                      onClick={adoptDetectedTz}
+                      className="ml-1 underline underline-offset-2 hover:no-underline"
+                    >
+                      Update?
+                    </button>
+                  </div>
+                </div>
+              )}
             </div>
             <div className="flex items-center gap-3">
               <Button onClick={saveProfile} disabled={saving === 'profile'}>
                 <Save className="mr-1.5 h-4 w-4" />
-                {saving === 'profile' ? 'Saving...' : 'Save Profile'}
+                {saving === 'profile' ? 'Saving…' : 'Save profile'}
               </Button>
               {message && <span className="text-sm text-muted-foreground">{message}</span>}
             </div>
           </CardContent>
         </Card>
 
+        <Card>
+          <CardHeader>
+            <CardTitle>Account</CardTitle>
+            <CardDescription>Sign-in email and password</CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <div className="space-y-2">
+              <Label htmlFor="settings-email">Email</Label>
+              <Input
+                id="settings-email"
+                type="email"
+                value={email}
+                onChange={(e) => setEmail(e.target.value)}
+              />
+              <div className="flex items-center gap-3">
+                <Button
+                  size="sm"
+                  variant="outline"
+                  onClick={saveEmail}
+                  disabled={saving === 'email' || email === originalEmail || !email}
+                >
+                  {saving === 'email' ? 'Updating…' : 'Update email'}
+                </Button>
+                {emailMsg && <span className="text-xs text-muted-foreground">{emailMsg}</span>}
+              </div>
+              <p className="text-xs text-muted-foreground">
+                Changing your email also changes the address you use to sign in.
+              </p>
+            </div>
+            <div className="space-y-2 pt-2 border-t">
+              <Label>Password</Label>
+              <div className="flex items-center gap-3">
+                <Button
+                  size="sm"
+                  variant="outline"
+                  onClick={requestPasswordReset}
+                  disabled={saving === 'password'}
+                >
+                  <KeyRound className="mr-1.5 h-3.5 w-3.5" />
+                  {saving === 'password' ? 'Sending…' : 'Send reset email'}
+                </Button>
+                {resetMsg && <span className="text-xs text-muted-foreground">{resetMsg}</span>}
+              </div>
+              <p className="text-xs text-muted-foreground">
+                We&apos;ll email you a link to set a new password.
+              </p>
+            </div>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle>Notifications</CardTitle>
@@ -169,6 +381,16 @@ export function UserSettings() {
           </CardContent>
         </Card>
       </div>
+
+      <ImageCropperDialog
+        open={cropperOpen}
+        onOpenChange={setCropperOpen}
+        file={pendingAvatarFile}
+        aspect={1}
+        outputWidth={256}
+        title="Crop profile photo"
+        onUpload={uploadAvatar}
+      />
     </div>
   );
 }