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/lib/email/templates/document-signing.ts

@@ -0,0 +1,245 @@
+/**
+ * Branded transactional emails for the Documenso signing lifecycle.
+ *
+ * Three template families:
+ *
+ *   1. `signingInvitation` — sent to a single signer when their turn
+ *      to sign comes up. Used both for the initial client invite (after
+ *      EOI/contract/reservation generation) AND for the cascading
+ *      "your turn" emails when an earlier signer completes (developer
+ *      after client signs, approver after developer signs, etc).
+ *
+ *   2. `signingCompleted` — sent to ALL signers (with the finalized
+ *      signed PDF as an attachment) when the document reaches a fully
+ *      signed state. Mirrors the old system's
+ *      `sendFinalizedDocumentToSignatories` flow.
+ *
+ *   3. `signingReminder` — sent when a rep nudges an unsigned recipient
+ *      manually OR when the rate-limited reminder service fires. Same
+ *      visual shape as `signingInvitation` with different copy.
+ *
+ * All three use the per-port `BrandingShell` (logo + primary color +
+ * header/footer HTML) so each tenant's outbound emails match its
+ * brand. The signing URL passed in is expected to already be
+ * embedded-format (e.g. `https://portnimara.com/sign/<type>/<token>`)
+ * — the caller (interest service / webhook handler) does the
+ * transformation from the raw Documenso URL.
+ */
+
+import { brandingPrimaryColor, renderShell, type BrandingShell } from '@/lib/email/shell';
+
+interface RenderOpts {
+  subject?: string | null;
+  branding?: BrandingShell | null;
+}
+
+interface InvitationData {
+  /** Display name for the recipient — used in the greeting. */
+  recipientName: string;
+  /** Friendly document type label. e.g. "Expression of Interest", "Sales Contract", "Reservation Agreement". */
+  documentLabel: string;
+  /** Optional. The signer's role: 'client' | 'developer' | 'approver' | 'witness' etc. Drives copy nuance. */
+  signerRole?: string | null;
+  /** Embedded signing URL (already wrapped to the public branded host). */
+  signingUrl: string;
+  /** Port name to brand the email. */
+  portName: string;
+  /** Sales rep / sender name shown in the closing. Falls back to "{portName} team". */
+  senderName?: string | null;
+  /** Optional plain-text message from the rep to include above the CTA. */
+  customMessage?: string | null;
+}
+
+export function signingInvitationEmail(
+  data: InvitationData,
+  overrides?: RenderOpts,
+): { subject: string; html: string; text: string } {
+  const accent = brandingPrimaryColor(overrides?.branding);
+  const docLabelEsc = escapeHtml(data.documentLabel);
+  const subject = overrides?.subject
+    ? overrides.subject
+        .replace(/\{\{documentLabel\}\}/g, data.documentLabel)
+        .replace(/\{\{portName\}\}/g, data.portName)
+        .replace(/\{\{recipientName\}\}/g, data.recipientName)
+    : `${data.documentLabel} ready to sign — ${data.portName}`;
+
+  const greeting = `Dear ${escapeHtml(data.recipientName)},`;
+  const closer = data.senderName
+    ? `${escapeHtml(data.senderName)}<br /><strong>${escapeHtml(data.portName)}</strong>`
+    : `<strong>The ${escapeHtml(data.portName)} team</strong>`;
+
+  // Slightly different lead paragraph based on signer role so the
+  // developer / approver emails don't read as if they're the client.
+  const isClient = (data.signerRole ?? 'client') === 'client';
+  const leadCopy = isClient
+    ? `Your ${docLabelEsc} for <strong>${escapeHtml(data.portName)}</strong> is ready for signing. Click the button below to review and sign — it should only take a couple of minutes.`
+    : data.signerRole === 'approver'
+      ? `An ${docLabelEsc} is awaiting your approval. The earlier signers have completed their parts; please review and sign to finalise the document.`
+      : `An ${docLabelEsc} is awaiting your signature. The client has already signed; you're the next signer in the chain.`;
+
+  const customMessageBlock = data.customMessage
+    ? `<p style="margin:20px 0; font-size:15px; line-height:1.6; color:#444; padding:14px 18px; background:#f8f9fb; border-left:3px solid ${accent}; border-radius:4px;">${escapeHtml(data.customMessage).replace(/\n/g, '<br />')}</p>`
+    : '';
+
+  const body = `
+              <p style="margin-bottom:14px; font-size:18px; font-weight:bold; color:${accent};">
+                ${docLabelEsc} ready to sign
+              </p>
+              <p style="margin-bottom:14px; font-size:16px; line-height:1.6;">${greeting}</p>
+              <p style="margin-bottom:18px; font-size:16px; line-height:1.6;">${leadCopy}</p>
+              ${customMessageBlock}
+              <p style="text-align:center; margin:30px 0;">
+                <a href="${data.signingUrl}" style="display:inline-block; background-color:${accent}; color:#ffffff; text-decoration:none; padding:14px 36px; border-radius:5px; font-weight:bold; font-size:16px;">
+                  Review &amp; sign
+                </a>
+              </p>
+              <p style="font-size:13px; color:#666; line-height:1.5; padding:14px 0; border-top:1px solid #eee; margin-top:24px;">
+                If the button doesn't work, paste this link into your browser:<br />
+                <a href="${data.signingUrl}" style="color:${accent}; text-decoration:underline; word-break:break-all;">${data.signingUrl}</a>
+              </p>
+              <p style="font-size:14px; color:#666; line-height:1.5; margin-top:18px;">
+                Signing happens directly inside our website — your data isn't sent to a third-party signing service.
+              </p>
+              <p style="font-size:16px; margin-top:30px;">
+                Thank you,<br />
+                ${closer}
+              </p>`;
+
+  const text = `${greeting}\n\n${stripTags(leadCopy)}\n\n${data.customMessage ? data.customMessage + '\n\n' : ''}Sign here: ${data.signingUrl}\n\nThank you,\n${data.senderName ?? `The ${data.portName} team`}`;
+
+  return {
+    subject,
+    html: renderShell({ title: subject, body, branding: overrides?.branding }),
+    text,
+  };
+}
+
+interface CompletedData {
+  recipientName: string;
+  documentLabel: string;
+  /** Identity of the linked client (the deal's primary subject). */
+  clientName: string;
+  portName: string;
+  /** When the document reached fully-signed state. */
+  completedAt: Date;
+}
+
+export function signingCompletedEmail(
+  data: CompletedData,
+  overrides?: RenderOpts,
+): { subject: string; html: string; text: string } {
+  const accent = brandingPrimaryColor(overrides?.branding);
+  const docLabelEsc = escapeHtml(data.documentLabel);
+  const subject = overrides?.subject
+    ? overrides.subject
+        .replace(/\{\{documentLabel\}\}/g, data.documentLabel)
+        .replace(/\{\{clientName\}\}/g, data.clientName)
+        .replace(/\{\{portName\}\}/g, data.portName)
+    : `${data.documentLabel} fully signed — ${data.clientName}`;
+
+  const greeting = `Dear ${escapeHtml(data.recipientName)},`;
+  const completedDateStr = data.completedAt.toLocaleString('en-GB', {
+    day: '2-digit',
+    month: '2-digit',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+
+  const body = `
+              <p style="margin-bottom:14px; font-size:18px; font-weight:bold; color:${accent};">
+                ${docLabelEsc} signed by all parties
+              </p>
+              <p style="margin-bottom:14px; font-size:16px; line-height:1.6;">${greeting}</p>
+              <p style="margin-bottom:18px; font-size:16px; line-height:1.6;">
+                The ${docLabelEsc} for <strong>${escapeHtml(data.clientName)}</strong> has been signed by every party as of ${completedDateStr}.
+              </p>
+              <p style="margin-bottom:18px; font-size:16px; line-height:1.6;">
+                The fully signed PDF is attached to this email for your records. A copy has also been stored in the ${escapeHtml(data.portName)} CRM.
+              </p>
+              <p style="font-size:16px; margin-top:30px;">
+                Thank you,<br />
+                <strong>The ${escapeHtml(data.portName)} team</strong>
+              </p>`;
+
+  const text = `${greeting}\n\nThe ${data.documentLabel} for ${data.clientName} has been signed by all parties on ${completedDateStr}. The signed PDF is attached for your records.\n\nThank you,\nThe ${data.portName} team`;
+
+  return {
+    subject,
+    html: renderShell({ title: subject, body, branding: overrides?.branding }),
+    text,
+  };
+}
+
+interface ReminderData {
+  recipientName: string;
+  documentLabel: string;
+  signingUrl: string;
+  portName: string;
+  /** Human-readable string of how long ago the original invitation was sent. */
+  invitedAgo: string;
+  customMessage?: string | null;
+}
+
+export function signingReminderEmail(
+  data: ReminderData,
+  overrides?: RenderOpts,
+): { subject: string; html: string; text: string } {
+  const accent = brandingPrimaryColor(overrides?.branding);
+  const docLabelEsc = escapeHtml(data.documentLabel);
+  const subject = overrides?.subject
+    ? overrides.subject
+        .replace(/\{\{documentLabel\}\}/g, data.documentLabel)
+        .replace(/\{\{portName\}\}/g, data.portName)
+    : `Friendly reminder: ${data.documentLabel} still awaiting your signature — ${data.portName}`;
+
+  const greeting = `Dear ${escapeHtml(data.recipientName)},`;
+  const customMessageBlock = data.customMessage
+    ? `<p style="margin:20px 0; font-size:15px; line-height:1.6; color:#444; padding:14px 18px; background:#f8f9fb; border-left:3px solid ${accent}; border-radius:4px;">${escapeHtml(data.customMessage).replace(/\n/g, '<br />')}</p>`
+    : '';
+
+  const body = `
+              <p style="margin-bottom:14px; font-size:18px; font-weight:bold; color:${accent};">
+                Just a quick reminder
+              </p>
+              <p style="margin-bottom:14px; font-size:16px; line-height:1.6;">${greeting}</p>
+              <p style="margin-bottom:18px; font-size:16px; line-height:1.6;">
+                We sent you a ${docLabelEsc} ${escapeHtml(data.invitedAgo)} that's still awaiting your signature. If you've already signed, please disregard this message — it can take a few minutes for our system to catch up.
+              </p>
+              ${customMessageBlock}
+              <p style="text-align:center; margin:30px 0;">
+                <a href="${data.signingUrl}" style="display:inline-block; background-color:${accent}; color:#ffffff; text-decoration:none; padding:14px 36px; border-radius:5px; font-weight:bold; font-size:16px;">
+                  Sign now
+                </a>
+              </p>
+              <p style="font-size:13px; color:#666; line-height:1.5; padding:14px 0; border-top:1px solid #eee; margin-top:24px;">
+                Direct link: <a href="${data.signingUrl}" style="color:${accent}; text-decoration:underline; word-break:break-all;">${data.signingUrl}</a>
+              </p>
+              <p style="font-size:16px; margin-top:30px;">
+                Thank you,<br />
+                <strong>The ${escapeHtml(data.portName)} team</strong>
+              </p>`;
+
+  const text = `${greeting}\n\nWe sent you a ${data.documentLabel} ${data.invitedAgo} that's still awaiting your signature. ${data.customMessage ? '\n\n' + data.customMessage + '\n\n' : ''}\n\nSign here: ${data.signingUrl}\n\nThank you,\nThe ${data.portName} team`;
+
+  return {
+    subject,
+    html: renderShell({ title: subject, body, branding: overrides?.branding }),
+    text,
+  };
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function escapeHtml(input: string): string {
+  return input
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function stripTags(html: string): string {
+  return html.replace(/<[^>]+>/g, '');
+}