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/documents/documents-hub.tsx

@@ -263,7 +263,7 @@ export function DocumentsHub({ portSlug, initialTab = 'all' }: DocumentsHubProps
           placeholder="Search by title…"
           value={search}
           onChange={(e) => setSearch(e.target.value)}
-          className="max-w-xs"
+          className="max-w-xs h-9"
         />
         <Select value={typeFilter} onValueChange={setTypeFilter}>
           <SelectTrigger className="w-44">

src/components/documents/eoi-generate-dialog.tsx

@@ -1,7 +1,9 @@
 'use client';
 
 import { useMemo, useState } from 'react';
+import Link from 'next/link';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { AlertTriangle, ExternalLink, FileSignature, Pencil } from 'lucide-react';
 
 import {
   Dialog,
@@ -20,37 +22,10 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { Label } from '@/components/ui/label';
+import { Skeleton } from '@/components/ui/skeleton';
 import { apiFetch } from '@/lib/api/client';
-
-/** Required for the EOI's top paragraph (Section 2) - without these the
- *  document is unsignable, so generation is blocked. Yacht and berth fields
- *  belong to Section 3 and may be left blank. */
-interface EoiPrerequisites {
-  hasName: boolean;
-  hasEmail: boolean;
-  hasAddress: boolean;
-  /** Optional - info-only checks. Generation proceeds without them. */
-  hasYacht: boolean;
-  hasBerth: boolean;
-}
-
-interface EoiGenerateDialogProps {
-  interestId: string;
-  open: boolean;
-  onOpenChange: (open: boolean) => void;
-  prerequisites: EoiPrerequisites;
-}
-
-const REQUIRED_LABELS: { key: keyof EoiPrerequisites; label: string }[] = [
-  { key: 'hasName', label: 'Client name' },
-  { key: 'hasAddress', label: 'Client address' },
-  { key: 'hasEmail', label: 'Client email' },
-];
-
-const OPTIONAL_LABELS: { key: keyof EoiPrerequisites; label: string }[] = [
-  { key: 'hasYacht', label: 'Yacht linked (name + dimensions)' },
-  { key: 'hasBerth', label: 'Berth linked (mooring number)' },
-];
+import { cn } from '@/lib/utils';
+import { useUIStore } from '@/stores/ui-store';
 
 const DOCUMENSO_TEMPLATE_VALUE = 'documenso-template';
 
@@ -61,58 +36,171 @@ interface InAppTemplate {
   templateType: string;
 }
 
-interface ListResponse {
-  data: InAppTemplate[];
+interface EoiContextResponse {
+  data: {
+    client: {
+      fullName: string;
+      nationality: string | null;
+      primaryEmail: string | null;
+      primaryPhone: string | null;
+      address: { street: string; city: string; country: string } | null;
+    };
+    yacht: {
+      name: string;
+      lengthFt: string | null;
+      widthFt: string | null;
+      draftFt: string | null;
+      hullNumber: string | null;
+      flag: string | null;
+    } | null;
+    berth: {
+      mooringNumber: string;
+      area: string | null;
+      lengthFt: string | null;
+    } | null;
+    eoiBerthRange: string;
+    port: { name: string };
+  };
 }
 
+interface EoiGenerateDialogProps {
+  interestId: string;
+  /** Used to wire the "Edit on client" deep-link inside the dialog. */
+  clientId?: string | null;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Pre-flight preview + generate dialog. Replaces the earlier ✓/✗
+ * checklist with the actual values that will be auto-filled into the
+ * EOI, so a sales rep can spot a wrong email or missing yacht
+ * dimensions before sending the document for signing.
+ *
+ * Editing is deliberately routed back to the canonical client / yacht
+ * detail pages (via "Edit on client" links) rather than allowing
+ * inline edits inside the dialog. Why: the EOI's source-of-truth is
+ * the underlying records, and forking the edit surface here would
+ * silently bypass tag/audit-log/permission flows that the entity
+ * detail pages enforce.
+ */
 export function EoiGenerateDialog({
   interestId,
+  clientId,
   open,
   onOpenChange,
-  prerequisites,
 }: EoiGenerateDialogProps) {
   const queryClient = useQueryClient();
+  const portSlug = useUIStore((s) => s.currentPortSlug);
   const [isGenerating, setIsGenerating] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [selectedTemplate, setSelectedTemplate] = useState<string>(DOCUMENSO_TEMPLATE_VALUE);
 
-  const requiredMet = REQUIRED_LABELS.every(({ key }) => prerequisites[key]);
+  // Resolved EOI context — the actual values the document will be
+  // auto-filled with. Loaded only while the dialog is open so we don't
+  // pay for the join tree on every interest detail page render.
+  const { data: ctxRes, isLoading: ctxLoading } = useQuery<EoiContextResponse>({
+    queryKey: ['interests', interestId, 'eoi-context'],
+    queryFn: () => apiFetch<EoiContextResponse>(`/api/v1/interests/${interestId}/eoi-context`),
+    enabled: open,
+    staleTime: 30_000,
+  });
 
-  // Load in-app EOI templates so the operator can pick one as an alternative
-  // to the Documenso external-signing flow.
-  const { data: templatesRes } = useQuery<ListResponse>({
+  const ctx = ctxRes?.data;
+
+  const { data: templatesRes } = useQuery<{ data: InAppTemplate[] }>({
     queryKey: ['document-templates', { templateType: 'eoi', isActive: true }],
     queryFn: () =>
-      apiFetch<ListResponse>('/api/v1/document-templates?templateType=eoi&isActive=true'),
+      apiFetch<{ data: InAppTemplate[] }>(
+        '/api/v1/document-templates?templateType=eoi&isActive=true',
+      ),
     enabled: open,
   });
 
   const inAppTemplates = useMemo(() => templatesRes?.data ?? [], [templatesRes]);
 
-  const handleGenerate = async () => {
-    if (!requiredMet) return;
+  // Required for the EOI's top paragraph (Section 2). Without these
+  // the document is unsignable, so generation is blocked.
+  const required = ctx
+    ? [
+        {
+          key: 'name',
+          label: 'Full name',
+          value: ctx.client.fullName,
+          present: !!ctx.client.fullName,
+        },
+        {
+          key: 'email',
+          label: 'Email address',
+          value: ctx.client.primaryEmail ?? null,
+          present: !!ctx.client.primaryEmail,
+        },
+        {
+          key: 'address',
+          label: 'Address',
+          value: ctx.client.address
+            ? [ctx.client.address.street, ctx.client.address.city, ctx.client.address.country]
+                .filter(Boolean)
+                .join(', ')
+            : null,
+          present: !!ctx.client.address,
+        },
+      ]
+    : [];
 
+  // Optional — Section 3 of the EOI. Generation proceeds without them.
+  const optional = ctx
+    ? [
+        {
+          key: 'yacht',
+          label: 'Yacht name',
+          value: ctx.yacht?.name ?? null,
+        },
+        {
+          key: 'dimensions',
+          label: 'Dimensions (L × W × D, ft)',
+          value: ctx.yacht
+            ? [ctx.yacht.lengthFt, ctx.yacht.widthFt, ctx.yacht.draftFt]
+                .map((v) => v ?? '—')
+                .join(' × ')
+            : null,
+        },
+        {
+          key: 'berth',
+          label: 'Berth (primary mooring)',
+          value: ctx.berth?.mooringNumber ?? null,
+        },
+        {
+          key: 'berthRange',
+          label: 'Berth bundle range',
+          value: ctx.eoiBerthRange || null,
+        },
+        {
+          key: 'phone',
+          label: 'Phone',
+          value: ctx.client.primaryPhone ?? null,
+        },
+      ]
+    : [];
+
+  const requiredMet = required.length > 0 && required.every((r) => r.present);
+
+  async function handleGenerate() {
+    if (!requiredMet) return;
     setIsGenerating(true);
     setError(null);
-
     try {
-      const isDocumensoPath = selectedTemplate === DOCUMENSO_TEMPLATE_VALUE;
+      const isDocumenso = selectedTemplate === DOCUMENSO_TEMPLATE_VALUE;
       const url = `/api/v1/document-templates/${encodeURIComponent(selectedTemplate)}/generate-and-sign`;
       await apiFetch(url, {
         method: 'POST',
         body: {
           interestId,
-          pathway: isDocumensoPath ? 'documenso-template' : 'inapp',
-          // Signers are derived server-side from EOI context for both pathways
-          // when the template type is EOI, so the dialog doesn't collect them.
+          pathway: isDocumenso ? 'documenso-template' : 'inapp',
+          // Signers derived server-side from EOI context for both pathways.
           signers: [],
         },
       });
-
-      // Invalidate all document list queries (hub counts + per-interest lists).
-      // The DocumentList component uses ['documents', { interestId, clientId }]
-      // and the hub uses ['documents', 'hub', ...] / ['documents', 'hub-counts'].
-      // Using a predicate avoids key-shape drift between callers.
       queryClient.invalidateQueries({
         predicate: (q) => q.queryKey[0] === 'documents',
       });
@@ -122,20 +210,23 @@ export function EoiGenerateDialog({
     } finally {
       setIsGenerating(false);
     }
-  };
+  }
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent className="sm:max-w-md">
+      <DialogContent className="sm:max-w-lg">
         <DialogHeader>
-          <DialogTitle>Generate Expression of Interest</DialogTitle>
+          <DialogTitle className="flex items-center gap-2">
+            <FileSignature className="size-4" />
+            Generate Expression of Interest
+          </DialogTitle>
           <DialogDescription>
-            Pick how to render the EOI. Documenso is the primary path; in-app templates use the same
-            source PDF but render and store the PDF locally before sending for signing.
+            Review the values that will be auto-filled into the EOI. Anything wrong? Edit it on the
+            client&apos;s record before generating.
           </DialogDescription>
         </DialogHeader>
 
-        <div className="space-y-4 py-2">
+        <div className="space-y-4 py-1">
           <div className="space-y-2">
             <Label htmlFor="eoi-template">Template</Label>
             <Select value={selectedTemplate} onValueChange={setSelectedTemplate}>
@@ -155,69 +246,76 @@ export function EoiGenerateDialog({
             </Select>
           </div>
 
-          <div className="space-y-3">
-            <div className="space-y-1.5">
-              <p className="text-xs font-medium text-muted-foreground">
-                Required (Section 2 of the EOI)
-              </p>
-              {REQUIRED_LABELS.map(({ key, label }) => (
-                <div key={key} className="flex items-center gap-3 text-sm">
-                  <span
-                    className={`flex h-5 w-5 items-center justify-center rounded-full text-xs font-bold ${
-                      prerequisites[key] ? 'bg-green-100 text-green-700' : 'bg-red-100 text-red-700'
-                    }`}
-                  >
-                    {prerequisites[key] ? '✓' : '✗'}
-                  </span>
-                  <span
-                    className={prerequisites[key] ? 'text-foreground' : 'text-muted-foreground'}
-                  >
-                    {label}
-                  </span>
-                </div>
-              ))}
+          {ctxLoading ? (
+            <div className="space-y-2">
+              <Skeleton className="h-4 w-full" />
+              <Skeleton className="h-4 w-3/4" />
+              <Skeleton className="h-4 w-2/3" />
             </div>
-
-            <div className="space-y-1.5">
-              <p className="text-xs font-medium text-muted-foreground">
-                Optional (Section 3 - left blank if absent)
-              </p>
-              {OPTIONAL_LABELS.map(({ key, label }) => (
-                <div key={key} className="flex items-center gap-3 text-sm">
-                  <span
-                    className={`flex h-5 w-5 items-center justify-center rounded-full text-xs font-bold ${
-                      prerequisites[key]
-                        ? 'bg-green-100 text-green-700'
-                        : 'bg-muted text-muted-foreground'
-                    }`}
+          ) : ctx ? (
+            <div className="space-y-3 rounded-md border bg-muted/20 p-3">
+              <div className="space-y-1">
+                <p className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
+                  Required (Section 2 of the EOI)
+                </p>
+                <dl className="space-y-1.5">
+                  {required.map((row) => (
+                    <PreviewRow
+                      key={row.key}
+                      label={row.label}
+                      value={row.value}
+                      missing={!row.present}
+                    />
+                  ))}
+                </dl>
+              </div>
+              <div className="space-y-1 border-t pt-2">
+                <p className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
+                  Optional (Section 3 — left blank if absent)
+                </p>
+                <dl className="space-y-1.5">
+                  {optional.map((row) => (
+                    <PreviewRow key={row.key} label={row.label} value={row.value} />
+                  ))}
+                </dl>
+              </div>
+              {portSlug && clientId && (
+                <div className="border-t pt-2">
+                  <Link
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    href={`/${portSlug}/clients/${clientId}` as any}
+                    className="inline-flex items-center gap-1 text-xs text-primary hover:underline"
+                    onClick={() => onOpenChange(false)}
                   >
-                    {prerequisites[key] ? '✓' : '–'}
-                  </span>
-                  <span
-                    className={prerequisites[key] ? 'text-foreground' : 'text-muted-foreground'}
-                  >
-                    {label}
-                  </span>
+                    <Pencil className="size-3" />
+                    Wrong details? Edit on the client&apos;s page
+                    <ExternalLink className="size-3" />
+                  </Link>
                 </div>
-              ))}
+              )}
             </div>
+          ) : (
+            <p className="rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-xs text-amber-900">
+              Couldn&apos;t load the EOI preview data. Try closing and reopening the dialog.
+            </p>
+          )}
 
-            {!requiredMet ? (
-              <p className="rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-xs text-amber-900">
-                Add the missing required details on the client&apos;s record before generating the
-                EOI.
-              </p>
-            ) : null}
-          </div>
+          {!ctxLoading && ctx && !requiredMet && (
+            <p className="flex items-start gap-2 rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-xs text-amber-900">
+              <AlertTriangle className="size-3.5 shrink-0 mt-0.5" />
+              Add the missing required details on the client&apos;s record before generating the
+              EOI.
+            </p>
+          )}
         </div>
 
         {error && <p className="text-sm text-destructive">{error}</p>}
 
         <DialogFooter>
-          <Button variant="outline" onClick={() => onOpenChange(false)}>
+          <Button variant="outline" onClick={() => onOpenChange(false)} disabled={isGenerating}>
             Cancel
           </Button>
-          <Button onClick={handleGenerate} disabled={!requiredMet || isGenerating}>
+          <Button onClick={handleGenerate} disabled={!requiredMet || isGenerating || ctxLoading}>
             {isGenerating ? 'Generating…' : 'Generate EOI'}
           </Button>
         </DialogFooter>
@@ -225,3 +323,31 @@ export function EoiGenerateDialog({
     </Dialog>
   );
 }
+
+function PreviewRow({
+  label,
+  value,
+  missing = false,
+}: {
+  label: string;
+  value: string | null;
+  missing?: boolean;
+}) {
+  return (
+    <div className="flex items-baseline gap-2 text-sm">
+      <dt className="w-32 shrink-0 text-xs text-muted-foreground">{label}</dt>
+      <dd
+        className={cn(
+          'flex-1 break-words',
+          missing
+            ? 'text-rose-700 font-medium'
+            : value
+              ? 'text-foreground'
+              : 'text-muted-foreground italic',
+        )}
+      >
+        {value ?? (missing ? 'Missing — required' : 'Not set')}
+      </dd>
+    </div>
+  );
+}