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/admin/audit/audit-log-list.tsx

@@ -230,23 +230,30 @@ export function AuditLogList() {
     {
       accessorKey: 'action',
       header: 'Action',
-      cell: ({ row }) => (
-        <div className="flex items-center gap-1.5">
-          <Badge
-            className={`${ACTION_COLORS[row.original.action] ?? 'bg-gray-500'} text-white text-xs`}
-          >
-            {row.original.action}
-          </Badge>
-          {row.original.severity !== 'info' && (
-            <Badge
-              className={`${SEVERITY_BADGE[row.original.severity] ?? ''} text-[10px] px-1.5 py-0 uppercase`}
-              variant="outline"
-            >
-              {row.original.severity}
-            </Badge>
-          )}
-        </div>
-      ),
+      cell: ({ row }) => {
+        const verbLabel = row.original.action.replace(/_/g, ' ');
+        const entityLabel = row.original.entityType.replace(/_/g, ' ');
+        return (
+          <div className="flex flex-col gap-1">
+            <div className="flex items-center gap-1.5">
+              <Badge
+                className={`${ACTION_COLORS[row.original.action] ?? 'bg-gray-500'} text-white text-xs`}
+              >
+                {verbLabel}
+              </Badge>
+              {row.original.severity !== 'info' && (
+                <Badge
+                  className={`${SEVERITY_BADGE[row.original.severity] ?? ''} text-[10px] px-1.5 py-0 uppercase`}
+                  variant="outline"
+                >
+                  {row.original.severity}
+                </Badge>
+              )}
+            </div>
+            <span className="text-xs text-muted-foreground capitalize">{entityLabel}</span>
+          </div>
+        );
+      },
       size: 180,
     },
     {
@@ -342,7 +349,7 @@ export function AuditLogList() {
             <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
             <Input
               id="audit-search"
-              className="pl-9"
+              className="pl-9 h-9"
               placeholder="entity id, action, vendor…"
               value={search}
               onChange={(e) => setSearch(e.target.value)}
@@ -440,7 +447,7 @@ export function AuditLogList() {
           </Label>
           <Input
             id="audit-user"
-            className="w-44"
+            className="w-44 h-9"
             placeholder="exact user id"
             value={userId}
             onChange={(e) => setUserId(e.target.value)}
@@ -454,7 +461,7 @@ export function AuditLogList() {
           <Input
             id="audit-from"
             type="date"
-            className="w-36"
+            className="w-44 h-9"
             value={dateFrom}
             onChange={(e) => setDateFrom(e.target.value)}
           />
@@ -467,7 +474,7 @@ export function AuditLogList() {
           <Input
             id="audit-to"
             type="date"
-            className="w-36"
+            className="w-44 h-9"
             value={dateTo}
             onChange={(e) => setDateTo(e.target.value)}
           />

src/components/admin/backup-admin-panel.tsx

@@ -0,0 +1,208 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { Loader2, Download, Database, RefreshCw, AlertTriangle } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
+
+interface BackupJob {
+  id: string;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  trigger: 'manual' | 'cron';
+  triggeredBy: string | null;
+  sizeBytes: number | null;
+  storagePath: string | null;
+  errorMessage: string | null;
+  startedAt: string;
+  completedAt: string | null;
+}
+
+const STATUS_TONE: Record<string, string> = {
+  pending: 'bg-muted text-muted-foreground',
+  running: 'bg-amber-100 text-amber-900',
+  completed: 'bg-emerald-100 text-emerald-900',
+  failed: 'bg-rose-100 text-rose-900',
+};
+
+function formatBytes(n: number | null): string {
+  if (n === null) return '—';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+
+export function BackupAdminPanel() {
+  const [jobs, setJobs] = useState<BackupJob[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [running, setRunning] = useState(false);
+  const [confirmOpen, setConfirmOpen] = useState(false);
+
+  useEffect(() => {
+    void load();
+  }, []);
+
+  async function load() {
+    setLoading(true);
+    try {
+      const res = await apiFetch<{ data: BackupJob[] }>('/api/v1/admin/backup');
+      setJobs(res.data);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function trigger() {
+    setConfirmOpen(false);
+    setRunning(true);
+    try {
+      const res = await apiFetch<{
+        data: { id: string; status: 'completed' | 'failed'; error?: string };
+      }>('/api/v1/admin/backup', { method: 'POST' });
+      if (res.data.status === 'completed') {
+        toast.success('Backup completed');
+      } else {
+        toast.error(`Backup failed: ${res.data.error ?? 'unknown error'}`);
+      }
+      await load();
+    } catch (err) {
+      toastError(err);
+    } finally {
+      setRunning(false);
+    }
+  }
+
+  async function download(id: string) {
+    try {
+      const res = await apiFetch<{ data: { url: string } }>(`/api/v1/admin/backup/${id}/download`);
+      const a = document.createElement('a');
+      a.href = res.data.url;
+      a.download = `backup-${id}.dump`;
+      a.click();
+    } catch (err) {
+      toastError(err);
+    }
+  }
+
+  return (
+    <div className="space-y-4">
+      <Card>
+        <CardHeader className="flex flex-row items-start justify-between gap-3 space-y-0">
+          <div>
+            <CardTitle className="text-base flex items-center gap-2">
+              <Database className="h-4 w-4" />
+              Run a backup now
+            </CardTitle>
+            <CardDescription>
+              Triggers <code>pg_dump --format=custom</code> against the live database and uploads
+              the result to the active storage backend.
+            </CardDescription>
+          </div>
+          <div className="flex gap-2">
+            <Button variant="ghost" size="sm" onClick={load} disabled={loading || running}>
+              <RefreshCw className="mr-1.5 h-3.5 w-3.5" />
+              Refresh
+            </Button>
+            <Button onClick={() => setConfirmOpen(true)} disabled={running}>
+              {running && <Loader2 className="mr-1.5 h-4 w-4 animate-spin" />}
+              {running ? 'Running…' : 'Run backup'}
+            </Button>
+          </div>
+        </CardHeader>
+        <CardContent className="text-xs text-muted-foreground">
+          Backups land at <code>backups/&lt;id&gt;.dump</code> via{' '}
+          <code>getStorageBackend().put()</code>. Restore is intentionally not exposed in the UI —
+          download the .dump file and run <code>pg_restore</code> manually.
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base">History</CardTitle>
+          <CardDescription>Last 50 backup jobs.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          {loading ? (
+            <div className="flex items-center gap-2 text-sm text-muted-foreground">
+              <Loader2 className="h-4 w-4 animate-spin" /> Loading…
+            </div>
+          ) : jobs.length === 0 ? (
+            <p className="text-sm text-muted-foreground">No backups yet.</p>
+          ) : (
+            <ul className="divide-y">
+              {jobs.map((j) => (
+                <li key={j.id} className="flex items-center justify-between gap-3 py-2">
+                  <div className="min-w-0 flex-1">
+                    <div className="flex items-center gap-2">
+                      <span
+                        className={`text-[10px] uppercase font-medium px-1.5 py-0.5 rounded-full ${STATUS_TONE[j.status]}`}
+                      >
+                        {j.status}
+                      </span>
+                      <span className="text-xs text-muted-foreground">
+                        {new Date(j.startedAt).toLocaleString()}
+                      </span>
+                      {j.trigger === 'cron' && (
+                        <span className="text-[10px] text-muted-foreground">cron</span>
+                      )}
+                    </div>
+                    {j.errorMessage && (
+                      <p className="mt-1 text-xs text-rose-700 truncate">{j.errorMessage}</p>
+                    )}
+                  </div>
+                  <div className="flex items-center gap-3 shrink-0">
+                    <span className="text-xs text-muted-foreground">
+                      {formatBytes(j.sizeBytes)}
+                    </span>
+                    {j.status === 'completed' && (
+                      <Button size="sm" variant="outline" onClick={() => download(j.id)}>
+                        <Download className="mr-1.5 h-3.5 w-3.5" />
+                        Download
+                      </Button>
+                    )}
+                  </div>
+                </li>
+              ))}
+            </ul>
+          )}
+        </CardContent>
+      </Card>
+
+      <Dialog open={confirmOpen} onOpenChange={setConfirmOpen}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle className="flex items-center gap-2">
+              <AlertTriangle className="h-5 w-5 text-amber-600" />
+              Run a fresh backup now?
+            </DialogTitle>
+            <DialogDescription>
+              This streams the entire database through <code>pg_dump</code> and stores the result in
+              the active backend. On large databases the operation can take several minutes. The CRM
+              stays online throughout.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setConfirmOpen(false)}>
+              Cancel
+            </Button>
+            <Button onClick={trigger} disabled={running}>
+              Run backup
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}

src/components/admin/custom-fields/custom-fields-manager.tsx

@@ -11,10 +11,7 @@ import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { apiFetch } from '@/lib/api/client';
-import {
-  CustomFieldForm,
-  type CustomFieldDefinition,
-} from './custom-field-form';
+import { CustomFieldForm, type CustomFieldDefinition } from './custom-field-form';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -47,9 +44,7 @@ export function CustomFieldsManager() {
   const fetchFields = useCallback(async () => {
     setLoading(true);
     try {
-      const res = await apiFetch<{ data: CustomFieldDefinition[] }>(
-        '/api/v1/admin/custom-fields',
-      );
+      const res = await apiFetch<{ data: CustomFieldDefinition[] }>('/api/v1/admin/custom-fields');
       setFields(res.data);
     } finally {
       setLoading(false);
@@ -90,16 +85,12 @@ export function CustomFieldsManager() {
     {
       accessorKey: 'fieldName',
       header: 'Name',
-      cell: ({ row }) => (
-        <span className="font-mono text-sm">{row.original.fieldName}</span>
-      ),
+      cell: ({ row }) => <span className="font-mono text-sm">{row.original.fieldName}</span>,
     },
     {
       accessorKey: 'fieldLabel',
       header: 'Label',
-      cell: ({ row }) => (
-        <span className="font-medium">{row.original.fieldLabel}</span>
-      ),
+      cell: ({ row }) => <span className="font-medium">{row.original.fieldLabel}</span>,
     },
     {
       accessorKey: 'fieldType',
@@ -126,9 +117,7 @@ export function CustomFieldsManager() {
       accessorKey: 'sortOrder',
       header: 'Order',
       cell: ({ row }) => (
-        <span className="tabular-nums text-muted-foreground">
-          {row.original.sortOrder}
-        </span>
+        <span className="tabular-nums text-muted-foreground">{row.original.sortOrder}</span>
       ),
     },
     {
@@ -136,11 +125,7 @@ export function CustomFieldsManager() {
       header: '',
       cell: ({ row }) => (
         <div className="flex items-center justify-end gap-1">
-          <Button
-            variant="ghost"
-            size="sm"
-            onClick={() => handleEdit(row.original)}
-          >
+          <Button variant="ghost" size="sm" onClick={() => handleEdit(row.original)}>
             <Pencil className="h-4 w-4" />
             <span className="sr-only">Edit</span>
           </Button>
@@ -182,6 +167,15 @@ export function CustomFieldsManager() {
         }
       />
 
+      <div className="rounded-md border border-amber-300 bg-amber-50 px-3 py-2.5 text-xs text-amber-900">
+        <strong>Heads up:</strong> custom fields render in detail-page sidebars and the entity
+        export, but they don&rsquo;t plug into core platform behaviour: search doesn&rsquo;t index
+        them, the recommender doesn&rsquo;t score on them, audit logs don&rsquo;t diff them, and
+        merge-tokens won&rsquo;t expand them in EOI/contract templates. Use them for rep-only
+        annotations (e.g. &ldquo;Berth visit notes&rdquo;, &ldquo;Referral source&rdquo;) — anything
+        load-bearing for the deal flow needs a first-class column.
+      </div>
+
       <Tabs value={activeTab} onValueChange={(v) => setActiveTab(v as EntityTab)}>
         <TabsList>
           {(Object.keys(TAB_LABELS) as EntityTab[]).map((tab) => (

src/components/admin/onboarding-checklist.tsx

@@ -0,0 +1,261 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import Link from 'next/link';
+import { useParams } from 'next/navigation';
+import { Check, Circle, Loader2, ExternalLink } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Progress } from '@/components/ui/progress';
+import { apiFetch } from '@/lib/api/client';
+
+interface OnboardingStep {
+  id: string;
+  href: string;
+  label: string;
+  description: string;
+  /** Setting key whose presence proves the step is done. When set, the
+   *  checkmark auto-fills from the settings list. When undefined, the
+   *  step relies on the manual checkbox in `onboarding_status`. */
+  autoCheckSettingKey?: string;
+  /** Override: read this many users / tags / roles from a list endpoint
+   *  and consider the step done when count > 0. */
+  autoCheckListEndpoint?: string;
+}
+
+const STEPS: OnboardingStep[] = [
+  {
+    id: 'branding',
+    href: 'branding',
+    label: 'Set port name, logo, primary colour',
+    description: 'Branding flows into the navbar, emails, EOI PDFs, and the public auth shell.',
+    autoCheckSettingKey: 'branding_logo_url',
+  },
+  {
+    id: 'email',
+    href: 'email',
+    label: 'Configure outgoing email',
+    description:
+      'From-address, signature, footer, plus per-port SMTP overrides if you don’t use the global account.',
+    autoCheckSettingKey: 'sales_email_smtp_host',
+  },
+  {
+    id: 'documenso',
+    href: 'documenso',
+    label: 'Connect Documenso for EOIs',
+    description:
+      'API credentials and the EOI template id, plus the in-app vs Documenso pathway choice.',
+    autoCheckSettingKey: 'documenso_api_url',
+  },
+  {
+    id: 'settings',
+    href: 'settings',
+    label: 'Tune business rules + recommender weights',
+    description:
+      'Pipeline weights, net-10 discount, berth recommender knobs (heat weights, fall-through policy).',
+    autoCheckSettingKey: 'recommender_top_n_default',
+  },
+  {
+    id: 'roles',
+    href: 'roles',
+    label: 'Create roles & assign users',
+    description: 'Per-port roles inherit from system roles; override permissions here.',
+    autoCheckListEndpoint: '/api/v1/admin/roles',
+  },
+  {
+    id: 'users',
+    href: 'users',
+    label: 'Invite the rest of the team',
+    description:
+      'Invite users, assign roles, optionally grant residential access. Track pending vs accepted.',
+    autoCheckListEndpoint: '/api/v1/admin/users',
+  },
+  {
+    id: 'tags',
+    href: 'tags',
+    label: 'Define starter tags',
+    description: 'Color-coded labels used across clients, yachts, companies, and interests.',
+    autoCheckListEndpoint: '/api/v1/tags/options',
+  },
+  {
+    id: 'storage',
+    href: 'storage',
+    label: 'Configure storage backend',
+    description:
+      'Verify S3/filesystem and run a test connection before going live so PDFs and avatars persist correctly.',
+    autoCheckSettingKey: 'storage_backend',
+  },
+  {
+    id: 'forms',
+    href: '../',
+    label: 'Wire the website intake forms',
+    description:
+      'Inquiry forms on the marketing site dual-write into the CRM via /api/public/website-inquiries. Manually mark complete when verified.',
+  },
+];
+
+interface SettingRow {
+  key: string;
+  value: unknown;
+  portId: string | null;
+}
+interface SettingsResp {
+  data: { portSettings: SettingRow[]; globalSettings: SettingRow[] };
+}
+
+export function OnboardingChecklist() {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+  const [autoChecks, setAutoChecks] = useState<Record<string, boolean>>({});
+  const [manualChecks, setManualChecks] = useState<Record<string, boolean>>({});
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState<string | null>(null);
+
+  useEffect(() => {
+    void load();
+  }, []);
+
+  async function load() {
+    setLoading(true);
+    try {
+      const settings = await apiFetch<SettingsResp>('/api/v1/admin/settings');
+      const all = [...settings.data.portSettings, ...settings.data.globalSettings];
+      const byKey = new Map(all.map((r) => [r.key, r.value]));
+
+      const checks: Record<string, boolean> = {};
+      const listChecks = await Promise.all(
+        STEPS.map(async (s) => {
+          if (s.autoCheckSettingKey) {
+            const v = byKey.get(s.autoCheckSettingKey);
+            return [s.id, v !== undefined && v !== null && v !== '' && v !== false] as const;
+          }
+          if (s.autoCheckListEndpoint) {
+            try {
+              const res = await apiFetch<{ data: unknown[] }>(s.autoCheckListEndpoint);
+              return [s.id, Array.isArray(res.data) && res.data.length > 0] as const;
+            } catch {
+              return [s.id, false] as const;
+            }
+          }
+          return [s.id, false] as const;
+        }),
+      );
+      for (const [id, done] of listChecks) checks[id] = done;
+      setAutoChecks(checks);
+
+      // Pull the manual-checkbox state from system_settings.
+      const manual = (byKey.get('onboarding_manual_status') ?? {}) as Record<string, boolean>;
+      setManualChecks(manual);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function toggleManual(id: string) {
+    const next = { ...manualChecks, [id]: !manualChecks[id] };
+    setManualChecks(next);
+    setSaving(id);
+    try {
+      await apiFetch('/api/v1/admin/settings', {
+        method: 'PUT',
+        body: { key: 'onboarding_manual_status', value: next },
+      });
+    } finally {
+      setSaving(null);
+    }
+  }
+
+  const stepDone = (id: string) => Boolean(autoChecks[id]) || Boolean(manualChecks[id]);
+  const completed = STEPS.filter((s) => stepDone(s.id)).length;
+  const percent = Math.round((completed / STEPS.length) * 100);
+
+  return (
+    <div className="mt-6 space-y-6">
+      <Card>
+        <CardHeader>
+          <CardTitle>Setup checklist</CardTitle>
+          <CardDescription>
+            {completed} of {STEPS.length} complete. Auto-checked steps update when you save the
+            underlying setting; manual ones (like website-form integration) need the checkbox.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-5">
+          <Progress value={percent} className="h-2" />
+
+          <ol className="space-y-3">
+            {STEPS.map((step, idx) => {
+              const auto = Boolean(autoChecks[step.id]);
+              const manual = Boolean(manualChecks[step.id]);
+              const done = auto || manual;
+              return (
+                <li
+                  key={step.id}
+                  className={
+                    done
+                      ? 'flex items-start gap-3 rounded-md border border-emerald-200 bg-emerald-50/50 p-3'
+                      : 'flex items-start gap-3 rounded-md border p-3'
+                  }
+                >
+                  <span
+                    className={
+                      done
+                        ? 'mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-emerald-500 text-white'
+                        : 'mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-muted text-muted-foreground'
+                    }
+                  >
+                    {done ? (
+                      <Check className="h-4 w-4" />
+                    ) : loading ? (
+                      <Loader2 className="h-4 w-4 animate-spin" />
+                    ) : (
+                      <Circle className="h-4 w-4" />
+                    )}
+                  </span>
+                  <div className="flex-1 min-w-0">
+                    <div className="flex items-start justify-between gap-2">
+                      <div>
+                        <Link
+                          href={`/${portSlug}/admin/${step.href}` as never}
+                          className="text-sm font-medium hover:underline inline-flex items-center gap-1"
+                        >
+                          {idx + 1}. {step.label}
+                          <ExternalLink className="h-3 w-3 opacity-50" />
+                        </Link>
+                        <p className="mt-0.5 text-xs text-muted-foreground">{step.description}</p>
+                        {auto && (
+                          <p className="mt-1 text-[11px] text-emerald-700">
+                            Auto-detected complete via{' '}
+                            <code className="text-[10px]">
+                              {step.autoCheckSettingKey ?? step.autoCheckListEndpoint}
+                            </code>
+                          </p>
+                        )}
+                      </div>
+                      {!auto && (
+                        <Button
+                          size="sm"
+                          variant={manual ? 'secondary' : 'outline'}
+                          disabled={saving === step.id}
+                          onClick={() => toggleManual(step.id)}
+                        >
+                          {saving === step.id ? (
+                            <Loader2 className="h-3.5 w-3.5 animate-spin" />
+                          ) : manual ? (
+                            'Mark incomplete'
+                          ) : (
+                            'Mark done'
+                          )}
+                        </Button>
+                      )}
+                    </div>
+                  </div>
+                </li>
+              );
+            })}
+          </ol>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

src/components/admin/ports/port-form.tsx

@@ -6,9 +6,34 @@ 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 {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter } from '@/components/ui/sheet';
+import { TimezoneCombobox } from '@/components/shared/timezone-combobox';
 import { apiFetch } from '@/lib/api/client';
 
+// ISO-4217 currency shortlist for the port-currency dropdown.
+// Marina deals price in a small set; an admin who needs an exotic
+// currency can add it here without a schema change.
+const CURRENCY_OPTIONS: Array<{ value: string; label: string }> = [
+  { value: 'USD', label: 'USD — US Dollar' },
+  { value: 'EUR', label: 'EUR — Euro' },
+  { value: 'GBP', label: 'GBP — British Pound' },
+  { value: 'CHF', label: 'CHF — Swiss Franc' },
+  { value: 'AED', label: 'AED — UAE Dirham' },
+  { value: 'SAR', label: 'SAR — Saudi Riyal' },
+  { value: 'PLN', label: 'PLN — Polish Złoty' },
+  { value: 'AUD', label: 'AUD — Australian Dollar' },
+  { value: 'CAD', label: 'CAD — Canadian Dollar' },
+  { value: 'NZD', label: 'NZD — New Zealand Dollar' },
+  { value: 'JPY', label: 'JPY — Japanese Yen' },
+];
+
 interface PortFormProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
@@ -154,25 +179,23 @@ export function PortForm({ open, onOpenChange, port, onSuccess }: PortFormProps)
           <div className="grid grid-cols-2 gap-4">
             <div className="space-y-2">
               <Label htmlFor="port-currency">Currency</Label>
-              <Input
-                id="port-currency"
-                value={defaultCurrency}
-                onChange={(e) => setDefaultCurrency(e.target.value.toUpperCase())}
-                placeholder="USD"
-                maxLength={3}
-                required
-              />
+              <Select value={defaultCurrency} onValueChange={setDefaultCurrency}>
+                <SelectTrigger id="port-currency">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {CURRENCY_OPTIONS.map((c) => (
+                    <SelectItem key={c.value} value={c.value}>
+                      {c.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
             </div>
 
             <div className="space-y-2">
-              <Label htmlFor="port-timezone">Timezone</Label>
-              <Input
-                id="port-timezone"
-                value={timezone}
-                onChange={(e) => setTimezone(e.target.value)}
-                placeholder="America/Anguilla"
-                required
-              />
+              <Label>Timezone</Label>
+              <TimezoneCombobox value={timezone} onChange={(tz) => setTimezone(tz ?? '')} />
             </div>
           </div>
 

src/components/admin/residential-stages-admin.tsx

@@ -0,0 +1,329 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { GripVertical, Plus, Trash2, Loader2, Save, AlertTriangle } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
+import { toast } from 'sonner';
+
+interface Stage {
+  id: string;
+  label: string;
+  terminal: 'won' | 'lost' | null;
+}
+
+interface Orphan {
+  id: string;
+  pipelineStage: string;
+}
+
+interface Resp {
+  data: { stages: Stage[]; orphans: Orphan[] };
+}
+
+export function ResidentialStagesAdmin() {
+  const [stages, setStages] = useState<Stage[]>([]);
+  const [originalIds, setOriginalIds] = useState<Set<string>>(new Set());
+  const [orphans, setOrphans] = useState<Orphan[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [reassignDialog, setReassignDialog] = useState<{
+    affected: Orphan[];
+    reassignments: Record<string, string>;
+  } | null>(null);
+
+  useEffect(() => {
+    void load();
+  }, []);
+
+  async function load() {
+    setLoading(true);
+    try {
+      const res = await apiFetch<Resp>('/api/v1/residential/stages');
+      setStages(res.data.stages);
+      setOriginalIds(new Set(res.data.stages.map((s) => s.id)));
+      setOrphans(res.data.orphans);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  function move(idx: number, dir: -1 | 1) {
+    const next = [...stages];
+    const swap = idx + dir;
+    if (swap < 0 || swap >= next.length) return;
+    [next[idx], next[swap]] = [next[swap]!, next[idx]!];
+    setStages(next);
+  }
+
+  function update(idx: number, patch: Partial<Stage>) {
+    setStages((prev) => prev.map((s, i) => (i === idx ? { ...s, ...patch } : s)));
+  }
+
+  function add() {
+    setStages((prev) => [
+      ...prev,
+      { id: `stage_${prev.length + 1}`, label: 'New stage', terminal: null },
+    ]);
+  }
+
+  function remove(idx: number) {
+    setStages((prev) => prev.filter((_, i) => i !== idx));
+  }
+
+  async function attemptSave(force: boolean, reassignments?: Record<string, string>) {
+    setSaving(true);
+    try {
+      await apiFetch('/api/v1/residential/stages', {
+        method: 'PUT',
+        body: { stages, reassignments, force },
+      });
+      toast.success('Stages saved');
+      setReassignDialog(null);
+      await load();
+    } catch (err: unknown) {
+      // The service throws ConflictError when interests sit on a removed
+      // stage. Open the reassignment dialog so the admin can fix it
+      // before retrying.
+      const msg = err instanceof Error ? err.message : '';
+      if (/sit on a stage/.test(msg)) {
+        // Build the affected list from the current orphan-snapshot
+        // filtered to stages NOT in the new list.
+        const newIds = new Set(stages.map((s) => s.id));
+        const affected = orphans.filter((o) => !newIds.has(o.pipelineStage));
+        setReassignDialog({ affected, reassignments: {} });
+      } else {
+        toastError(err);
+      }
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  const stageIds = stages.map((s) => s.id);
+
+  const removedStageIds = Array.from(originalIds).filter((id) => !stageIds.includes(id));
+
+  if (loading) {
+    return (
+      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+        <Loader2 className="h-4 w-4 animate-spin" /> Loading stages…
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      <Card>
+        <CardHeader>
+          <CardTitle>Stages</CardTitle>
+          <CardDescription>
+            Drag-style ordering via the up/down handles on the right. Stages with terminal
+            &ldquo;won&rdquo; or &ldquo;lost&rdquo; mark the funnel ends and feed reports.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-3">
+          {stages.map((stage, idx) => (
+            <div
+              key={`${stage.id}-${idx}`}
+              className="flex items-center gap-3 rounded-md border p-3"
+            >
+              <GripVertical className="h-4 w-4 text-muted-foreground" />
+              <div className="flex-1 grid grid-cols-1 sm:grid-cols-3 gap-2">
+                <div className="space-y-1">
+                  <Label className="text-[11px] uppercase tracking-wide text-muted-foreground">
+                    Id
+                  </Label>
+                  <Input
+                    value={stage.id}
+                    onChange={(e) => update(idx, { id: e.target.value })}
+                    className="font-mono text-xs h-8"
+                  />
+                </div>
+                <div className="space-y-1">
+                  <Label className="text-[11px] uppercase tracking-wide text-muted-foreground">
+                    Label
+                  </Label>
+                  <Input
+                    value={stage.label}
+                    onChange={(e) => update(idx, { label: e.target.value })}
+                    className="h-8"
+                  />
+                </div>
+                <div className="space-y-1">
+                  <Label className="text-[11px] uppercase tracking-wide text-muted-foreground">
+                    Terminal
+                  </Label>
+                  <Select
+                    value={stage.terminal ?? 'none'}
+                    onValueChange={(v) =>
+                      update(idx, {
+                        terminal: v === 'none' ? null : (v as 'won' | 'lost'),
+                      })
+                    }
+                  >
+                    <SelectTrigger className="h-8">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      <SelectItem value="none">In-progress</SelectItem>
+                      <SelectItem value="won">Closed — won</SelectItem>
+                      <SelectItem value="lost">Closed — lost</SelectItem>
+                    </SelectContent>
+                  </Select>
+                </div>
+              </div>
+              <div className="flex flex-col gap-1">
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  className="h-7 px-2"
+                  onClick={() => move(idx, -1)}
+                  disabled={idx === 0}
+                >
+                  ↑
+                </Button>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  className="h-7 px-2"
+                  onClick={() => move(idx, 1)}
+                  disabled={idx === stages.length - 1}
+                >
+                  ↓
+                </Button>
+              </div>
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                onClick={() => remove(idx)}
+                className="text-destructive"
+              >
+                <Trash2 className="h-3.5 w-3.5" />
+              </Button>
+            </div>
+          ))}
+
+          <Button type="button" variant="outline" size="sm" onClick={add}>
+            <Plus className="mr-1.5 h-3.5 w-3.5" />
+            Add stage
+          </Button>
+        </CardContent>
+      </Card>
+
+      {removedStageIds.length > 0 && (
+        <div className="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-900">
+          <AlertTriangle className="mr-2 inline h-4 w-4" />
+          Removing: {removedStageIds.join(', ')}. Any interests parked on these stages will need to
+          be reassigned before save.
+        </div>
+      )}
+
+      <div className="flex items-center gap-3">
+        <Button onClick={() => attemptSave(false)} disabled={saving}>
+          {saving ? (
+            <Loader2 className="mr-1.5 h-4 w-4 animate-spin" />
+          ) : (
+            <Save className="mr-1.5 h-4 w-4" />
+          )}
+          Save stages
+        </Button>
+      </div>
+
+      <Dialog open={!!reassignDialog} onOpenChange={(o) => !o && setReassignDialog(null)}>
+        <DialogContent className="max-w-lg">
+          <DialogHeader>
+            <DialogTitle>Reassign interests</DialogTitle>
+            <DialogDescription>
+              These residential interests sit on a stage you&apos;re removing. Pick a new stage for
+              each before saving.
+            </DialogDescription>
+          </DialogHeader>
+          {reassignDialog && (
+            <div className="space-y-3 max-h-80 overflow-y-auto">
+              {reassignDialog.affected.map((o) => (
+                <div key={o.id} className="flex items-center justify-between gap-3 text-sm">
+                  <div className="min-w-0">
+                    <code className="text-xs">{o.id.slice(0, 12)}…</code>
+                    <p className="text-xs text-muted-foreground">
+                      currently: <code className="text-xs">{o.pipelineStage}</code>
+                    </p>
+                  </div>
+                  <Select
+                    value={reassignDialog.reassignments[o.id] ?? ''}
+                    onValueChange={(v) =>
+                      setReassignDialog((prev) =>
+                        prev
+                          ? {
+                              ...prev,
+                              reassignments: { ...prev.reassignments, [o.id]: v },
+                            }
+                          : prev,
+                      )
+                    }
+                  >
+                    <SelectTrigger className="w-44 h-8">
+                      <SelectValue placeholder="Choose stage…" />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {stages.map((s) => (
+                        <SelectItem key={s.id} value={s.id}>
+                          {s.label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </div>
+              ))}
+            </div>
+          )}
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setReassignDialog(null)}>
+              Cancel
+            </Button>
+            <Button
+              onClick={() => {
+                if (!reassignDialog) return;
+                const allAssigned = reassignDialog.affected.every(
+                  (o) => reassignDialog.reassignments[o.id],
+                );
+                if (!allAssigned) {
+                  toast.error('Pick a new stage for every listed interest first.');
+                  return;
+                }
+                void attemptSave(true, reassignDialog.reassignments);
+              }}
+              disabled={saving}
+            >
+              {saving && <Loader2 className="mr-1.5 h-4 w-4 animate-spin" />}
+              Reassign + save
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}

src/components/admin/roles/role-list.tsx

@@ -9,9 +9,32 @@ import { PageHeader } from '@/components/shared/page-header';
 import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
 import { apiFetch } from '@/lib/api/client';
 import { RoleForm } from './role-form';
 
+/**
+ * Display-normalize a stored role name. Roles are stored with whatever
+ * key the admin entered (snake_case, kebab-case, free text). For UI
+ * display we titlecase + space-separate so "super_admin" reads as
+ * "Super Admin" and "Some role!" reads as "Some Role!" Display-only —
+ * code paths that compare role names use the stored verbatim value.
+ */
+function prettifyRoleName(name: string): string {
+  return name
+    .replace(/[_-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
 interface Role {
   id: string;
   name: string;
@@ -28,6 +51,7 @@ export function RoleList() {
   const [formOpen, setFormOpen] = useState(false);
   const [editingRole, setEditingRole] = useState<Role | null>(null);
   const [deletingId, setDeletingId] = useState<string | null>(null);
+  const [viewingPermissions, setViewingPermissions] = useState<Role | null>(null);
 
   const fetchRoles = useCallback(async () => {
     setLoading(true);
@@ -81,7 +105,11 @@ export function RoleList() {
       header: 'Name',
       cell: ({ row }) => (
         <div className="flex items-center gap-2">
-          <span className="font-medium">{row.original.name}</span>
+          {/* Display-normalize: snake_case → "Snake Case" so admin-
+              created roles with arbitrary keys still read cleanly.
+              The underlying name is stored verbatim and is what code
+              checks against — display is purely cosmetic. */}
+          <span className="font-medium">{prettifyRoleName(row.original.name)}</span>
           {row.original.isSystem && (
             <Badge variant="outline" className="text-xs">
               <Lock className="mr-1 h-3 w-3" />
@@ -102,7 +130,19 @@ export function RoleList() {
       id: 'permissions',
       header: 'Permissions',
       cell: ({ row }) => (
-        <Badge variant="secondary">{countPermissions(row.original.permissions)}</Badge>
+        <button
+          type="button"
+          onClick={() => setViewingPermissions(row.original)}
+          className="inline-flex"
+          title="View permission breakdown"
+        >
+          <Badge
+            variant="secondary"
+            className="cursor-pointer hover:bg-secondary/80 transition-colors"
+          >
+            {countPermissions(row.original.permissions)}
+          </Badge>
+        </button>
       ),
     },
     {
@@ -171,6 +211,72 @@ export function RoleList() {
         role={editingRole}
         onSuccess={fetchRoles}
       />
+
+      {/* Permissions inspector — opens when admin clicks the count
+          badge in the table. Lists granted vs denied per resource so
+          they can spot gaps before opening the editor. */}
+      <Dialog open={!!viewingPermissions} onOpenChange={(o) => !o && setViewingPermissions(null)}>
+        <DialogContent className="max-w-2xl max-h-[80vh] overflow-y-auto">
+          <DialogHeader>
+            <DialogTitle>
+              Permissions — {viewingPermissions ? prettifyRoleName(viewingPermissions.name) : ''}
+            </DialogTitle>
+            <DialogDescription>
+              Granted vs total per resource. Click Edit to change.
+            </DialogDescription>
+          </DialogHeader>
+          {viewingPermissions && (
+            <div className="space-y-3">
+              {Object.entries(viewingPermissions.permissions).map(([resource, actions]) => {
+                const granted = Object.values(actions).filter(Boolean).length;
+                const total = Object.keys(actions).length;
+                return (
+                  <div key={resource} className="rounded-md border px-3 py-2">
+                    <div className="flex items-center justify-between mb-1.5">
+                      <span className="text-sm font-medium capitalize">
+                        {resource.replace(/_/g, ' ')}
+                      </span>
+                      <Badge variant="secondary" className="text-xs">
+                        {granted}/{total}
+                      </Badge>
+                    </div>
+                    <div className="flex flex-wrap gap-1.5">
+                      {Object.entries(actions).map(([action, allowed]) => (
+                        <span
+                          key={action}
+                          className={
+                            allowed
+                              ? 'inline-flex items-center rounded-full bg-emerald-50 text-emerald-900 px-2 py-0.5 text-[11px] font-medium'
+                              : 'inline-flex items-center rounded-full bg-muted text-muted-foreground px-2 py-0.5 text-[11px] font-medium line-through opacity-60'
+                          }
+                        >
+                          {action.replace(/_/g, ' ')}
+                        </span>
+                      ))}
+                    </div>
+                  </div>
+                );
+              })}
+            </div>
+          )}
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setViewingPermissions(null)}>
+              Close
+            </Button>
+            {viewingPermissions && (
+              <Button
+                onClick={() => {
+                  const role = viewingPermissions;
+                  setViewingPermissions(null);
+                  handleEditRole(role);
+                }}
+              >
+                Edit
+              </Button>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
     </div>
   );
 }

src/components/admin/sales-email-config-card.tsx

@@ -23,6 +23,7 @@ import { Label } from '@/components/ui/label';
 import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
 import { apiFetch } from '@/lib/api/client';
+import { VALID_MERGE_TOKENS } from '@/lib/templates/merge-fields';
 import { toastError } from '@/lib/api/toast-error';
 
 interface SalesConfigResponse {
@@ -308,7 +309,23 @@ export function SalesEmailConfigCard() {
           </CardDescription>
         </CardHeader>
         <CardContent className="space-y-4">
-          <Field label="Berth PDF body" id="sef-tmpl-berth">
+          <details className="rounded-md border bg-muted/30 px-3 py-2 text-xs">
+            <summary className="cursor-pointer font-medium text-foreground">
+              Available tokens ({Array.from(VALID_MERGE_TOKENS).length})
+            </summary>
+            <div className="mt-2 grid grid-cols-2 gap-x-3 gap-y-0.5 font-mono text-[11px] text-muted-foreground sm:grid-cols-3">
+              {Array.from(VALID_MERGE_TOKENS)
+                .sort()
+                .map((tok) => (
+                  <span key={tok}>{tok}</span>
+                ))}
+            </div>
+          </details>
+          <Field
+            label="Berth PDF body"
+            id="sef-tmpl-berth"
+            help="Sent when a rep emails a berth's PDF spec to a prospect. Markdown supported."
+          >
             <Textarea
               id="sef-tmpl-berth"
               rows={6}
@@ -317,7 +334,11 @@ export function SalesEmailConfigCard() {
               className="font-mono text-sm"
             />
           </Field>
-          <Field label="Brochure body" id="sef-tmpl-broc">
+          <Field
+            label="Brochure body"
+            id="sef-tmpl-broc"
+            help="Sent when a rep emails the port's master brochure to a prospect."
+          >
             <Textarea
               id="sef-tmpl-broc"
               rows={6}
@@ -337,7 +358,11 @@ export function SalesEmailConfigCard() {
                 }
               />
             </Field>
-            <Field label="Attach-vs-link threshold (MB)" id="sef-attach">
+            <Field
+              label="Attach-vs-link threshold (MB)"
+              id="sef-attach"
+              help="Files smaller than this go in the email as an attachment. Larger files send a 24-hour signed download link instead so the message stays under SMTP size limits and doesn't bounce. Default 15 MB."
+            >
               <Input
                 id="sef-attach"
                 type="number"
@@ -372,10 +397,23 @@ export function SalesEmailConfigCard() {
   );
 }
 
-function Field({ label, id, children }: { label: string; id: string; children: React.ReactNode }) {
+function Field({
+  label,
+  id,
+  children,
+  help,
+}: {
+  label: string;
+  id: string;
+  children: React.ReactNode;
+  /** Plain-text caption rendered below the label. Use for any setting
+   *  whose meaning isn't immediately obvious from the label alone. */
+  help?: string;
+}) {
   return (
     <div className="space-y-1">
       <Label htmlFor={id}>{label}</Label>
+      {help && <p className="text-xs text-muted-foreground">{help}</p>}
       {children}
     </div>
   );

src/components/admin/settings/settings-manager.tsx

@@ -11,6 +11,13 @@ import { Label } from '@/components/ui/label';
 import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
 import { Separator } from '@/components/ui/separator';
 import { apiFetch } from '@/lib/api/client';
 
@@ -27,8 +34,9 @@ const KNOWN_SETTINGS: Array<{
   key: string;
   label: string;
   description: string;
-  type: 'boolean' | 'number' | 'json' | 'string';
+  type: 'boolean' | 'number' | 'json' | 'string' | 'select';
   defaultValue: unknown;
+  options?: Array<{ value: string; label: string }>;
 }> = [
   {
     key: 'client_portal_enabled',
@@ -137,10 +145,23 @@ const KNOWN_SETTINGS: Array<{
   {
     key: 'fallthrough_policy',
     label: 'Recommender — fall-through policy',
-    description:
-      'How berths re-enter the recommender after a lost deal. One of: immediate_with_heat, cooldown, never_auto_recommend.',
-    type: 'string',
+    description: 'How berths re-enter the recommender after a lost deal.',
+    type: 'select',
     defaultValue: 'immediate_with_heat',
+    options: [
+      {
+        value: 'immediate_with_heat',
+        label: 'Immediate (with heat boost) — surface again right away',
+      },
+      {
+        value: 'cooldown',
+        label: 'Cooldown — wait N days (see below)',
+      },
+      {
+        value: 'never_auto_recommend',
+        label: 'Never — only re-surface via manual rep search',
+      },
+    ],
   },
   {
     key: 'fallthrough_cooldown_days',
@@ -303,52 +324,76 @@ export function SettingsManager() {
           </CardContent>
         </Card>
 
-        {/* String Settings */}
-        {KNOWN_SETTINGS.some((s) => s.type === 'string') && (
+        {/* String + Select Settings — both render in the same card.
+            'select' settings get a Select dropdown bound to setting.options;
+            'string' settings get a free-text Input. */}
+        {KNOWN_SETTINGS.some((s) => s.type === 'string' || s.type === 'select') && (
           <Card>
             <CardHeader>
               <CardTitle>Inquiry Settings</CardTitle>
               <CardDescription>Configure inquiry notification behavior</CardDescription>
             </CardHeader>
             <CardContent className="space-y-4">
-              {KNOWN_SETTINGS.filter((s) => s.type === 'string').map((setting) => (
-                <div
-                  key={setting.key}
-                  // Stack label/description above the input on phone widths.
-                  // The previous flex row crushed the label column into a
-                  // narrow vertical stripe ("Inquiry / Contact / Email" wrapping
-                  // one word per line) while the input took the rest.
-                  className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between sm:gap-4"
-                >
-                  <div className="flex-1">
-                    <Label>{setting.label}</Label>
-                    <p className="text-xs text-muted-foreground">{setting.description}</p>
+              {KNOWN_SETTINGS.filter((s) => s.type === 'string' || s.type === 'select').map(
+                (setting) => (
+                  <div
+                    key={setting.key}
+                    // Stack label/description above the input on phone widths.
+                    // The previous flex row crushed the label column into a
+                    // narrow vertical stripe ("Inquiry / Contact / Email" wrapping
+                    // one word per line) while the input took the rest.
+                    className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between sm:gap-4"
+                  >
+                    <div className="flex-1">
+                      <Label>{setting.label}</Label>
+                      <p className="text-xs text-muted-foreground">{setting.description}</p>
+                    </div>
+                    <div className="flex items-center gap-2">
+                      {setting.type === 'select' && setting.options ? (
+                        <Select
+                          value={String(getEffectiveValue(setting.key, setting.defaultValue) ?? '')}
+                          onValueChange={(v) =>
+                            setValues((prev) => ({ ...prev, [setting.key]: v }))
+                          }
+                        >
+                          <SelectTrigger className="w-full sm:w-72">
+                            <SelectValue />
+                          </SelectTrigger>
+                          <SelectContent>
+                            {setting.options.map((opt) => (
+                              <SelectItem key={opt.value} value={opt.value}>
+                                {opt.label}
+                              </SelectItem>
+                            ))}
+                          </SelectContent>
+                        </Select>
+                      ) : (
+                        <Input
+                          type="text"
+                          className="w-full sm:w-64"
+                          value={String(getEffectiveValue(setting.key, setting.defaultValue) ?? '')}
+                          onChange={(e) =>
+                            setValues((prev) => ({
+                              ...prev,
+                              [setting.key]: e.target.value,
+                            }))
+                          }
+                        />
+                      )}
+                      <Button
+                        size="sm"
+                        variant="outline"
+                        disabled={saving === setting.key}
+                        onClick={() =>
+                          saveSetting(setting.key, values[setting.key] ?? setting.defaultValue)
+                        }
+                      >
+                        <Save className="h-3.5 w-3.5" />
+                      </Button>
+                    </div>
                   </div>
-                  <div className="flex items-center gap-2">
-                    <Input
-                      type="text"
-                      className="w-full sm:w-64"
-                      value={String(getEffectiveValue(setting.key, setting.defaultValue) ?? '')}
-                      onChange={(e) =>
-                        setValues((prev) => ({
-                          ...prev,
-                          [setting.key]: e.target.value,
-                        }))
-                      }
-                    />
-                    <Button
-                      size="sm"
-                      variant="outline"
-                      disabled={saving === setting.key}
-                      onClick={() =>
-                        saveSetting(setting.key, values[setting.key] ?? setting.defaultValue)
-                      }
-                    >
-                      <Save className="h-3.5 w-3.5" />
-                    </Button>
-                  </div>
-                </div>
-              ))}
+                ),
+              )}
             </CardContent>
           </Card>
         )}
@@ -450,7 +495,14 @@ export function SettingsManager() {
         <Card>
           <CardHeader>
             <CardTitle>Custom Settings</CardTitle>
-            <CardDescription>Additional key-value settings for this port</CardDescription>
+            <CardDescription>
+              Free-form key-value entries that aren&apos;t covered by the typed forms above. Use
+              this for one-off feature flags, integration secrets, or experimental tunables that the
+              platform reads at runtime via{' '}
+              <code className="text-xs">getSystemSetting(portId, key)</code>. Values can be JSON
+              objects, plain strings, numbers, or booleans. Most reps will never need this section —
+              touch only if you know which key affects what.
+            </CardDescription>
           </CardHeader>
           <CardContent className="space-y-4">
             {customSettings.map((setting) => (

src/components/admin/shared/settings-form-card.tsx

@@ -10,6 +10,8 @@ import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Switch } from '@/components/ui/switch';
 import { Textarea } from '@/components/ui/textarea';
+import { TimezoneCombobox } from '@/components/shared/timezone-combobox';
+import { ImageCropperDialog } from '@/components/shared/image-cropper-dialog';
 import {
   Select,
   SelectContent,
@@ -28,7 +30,9 @@ export type SettingFieldType =
   | 'textarea'
   | 'html'
   | 'select'
-  | 'color';
+  | 'color'
+  | 'timezone'
+  | 'image-upload';
 
 export interface SettingFieldDef {
   key: string;
@@ -38,6 +42,13 @@ export interface SettingFieldDef {
   placeholder?: string;
   defaultValue: unknown;
   options?: Array<{ value: string; label: string }>;
+  /** For 'image-upload' fields: aspect ratio for the cropper (default 1).
+   *  For 'html' fields: when set, renders an "Insert default" button that
+   *  pastes this text into the textarea — used for email-template defaults
+   *  so admins can see the baseline before editing. */
+  defaultTemplate?: string;
+  /** For 'image-upload' fields: cropper aspect ratio. */
+  imageAspect?: number;
 }
 
 interface SettingsRowResponse {
@@ -198,13 +209,26 @@ function FieldRow({
     case 'html':
       return (
         <div className="space-y-1">
-          <Label htmlFor={id}>{field.label}</Label>
+          <div className="flex items-center justify-between">
+            <Label htmlFor={id}>{field.label}</Label>
+            {field.defaultTemplate && (
+              <Button
+                type="button"
+                size="sm"
+                variant="ghost"
+                className="h-7 text-xs"
+                onClick={() => onChange(field.defaultTemplate)}
+              >
+                Insert default
+              </Button>
+            )}
+          </div>
           {field.description && (
             <p className="text-xs text-muted-foreground">{field.description}</p>
           )}
           <Textarea
             id={id}
-            rows={field.type === 'html' ? 6 : 3}
+            rows={field.type === 'html' ? 8 : 3}
             value={typeof value === 'string' ? value : ''}
             placeholder={field.placeholder}
             onChange={(e) => onChange(e.target.value)}
@@ -213,6 +237,16 @@ function FieldRow({
         </div>
       );
 
+    case 'image-upload':
+      return (
+        <ImageUploadField
+          id={id}
+          field={field}
+          value={typeof value === 'string' ? value : ''}
+          onChange={onChange}
+        />
+      );
+
     case 'select':
       return (
         <div className="space-y-1">
@@ -255,6 +289,20 @@ function FieldRow({
         </div>
       );
 
+    case 'timezone':
+      return (
+        <div className="space-y-1">
+          <Label htmlFor={id}>{field.label}</Label>
+          {field.description && (
+            <p className="text-xs text-muted-foreground">{field.description}</p>
+          )}
+          <TimezoneCombobox
+            value={typeof value === 'string' ? value : null}
+            onChange={(tz) => onChange(tz)}
+          />
+        </div>
+      );
+
     case 'color':
       return (
         <div className="space-y-1">
@@ -315,3 +363,104 @@ function FieldRow({
       );
   }
 }
+
+/**
+ * Image-upload sub-form: shows current image preview, lets admin pick
+ * a file, opens the cropper, and on success replaces the setting value
+ * with the resulting public URL. Used for branding logos.
+ */
+function ImageUploadField({
+  id,
+  field,
+  value,
+  onChange,
+}: {
+  id: string;
+  field: SettingFieldDef;
+  value: string;
+  onChange: (next: unknown) => void;
+}) {
+  const [pendingFile, setPendingFile] = useState<File | null>(null);
+  const [open, setOpen] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  function handlePicked(e: React.ChangeEvent<HTMLInputElement>) {
+    const f = e.target.files?.[0] ?? null;
+    if (!f) return;
+    setPendingFile(f);
+    setOpen(true);
+    if (inputRef.current) inputRef.current.value = '';
+  }
+
+  async function uploadCropped(blob: Blob) {
+    const fd = new FormData();
+    fd.append('file', new File([blob], 'image.jpg', { type: 'image/jpeg' }));
+    const res = await fetch('/api/v1/admin/settings/image', { method: 'POST', body: fd });
+    if (!res.ok) {
+      const err = (await res.json().catch(() => ({}))) as { error?: { message?: string } };
+      throw new Error(err.error?.message ?? 'Image upload failed');
+    }
+    const json = (await res.json()) as { data: { url: string } };
+    onChange(json.data.url);
+  }
+
+  return (
+    <div className="space-y-2">
+      <Label htmlFor={id}>{field.label}</Label>
+      {field.description && <p className="text-xs text-muted-foreground">{field.description}</p>}
+      <div className="flex items-start gap-3">
+        <div className="h-20 w-20 shrink-0 rounded-md border bg-muted/30 flex items-center justify-center overflow-hidden">
+          {}
+          {value ? (
+            <img src={value} alt="" className="h-full w-full object-contain" />
+          ) : (
+            <span className="text-[10px] text-muted-foreground">No image</span>
+          )}
+        </div>
+        <div className="flex-1 space-y-2">
+          <div className="flex flex-wrap items-center gap-2">
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() => inputRef.current?.click()}
+            >
+              {value ? 'Replace image' : 'Upload image'}
+            </Button>
+            {value && (
+              <Button type="button" variant="ghost" size="sm" onClick={() => onChange('')}>
+                Remove
+              </Button>
+            )}
+          </div>
+          <Input
+            id={id}
+            value={value}
+            onChange={(e) => onChange(e.target.value)}
+            placeholder="https://example.com/logo.png"
+            className="text-xs"
+          />
+          <p className="text-[11px] text-muted-foreground">
+            Upload to use the platform&apos;s storage backend, or paste an external URL.
+          </p>
+        </div>
+      </div>
+      <input
+        ref={inputRef}
+        type="file"
+        accept="image/jpeg,image/png,image/webp"
+        onChange={handlePicked}
+        className="hidden"
+      />
+      <ImageCropperDialog
+        open={open}
+        onOpenChange={setOpen}
+        file={pendingFile}
+        aspect={field.imageAspect ?? 1}
+        outputWidth={field.imageAspect && field.imageAspect > 1 ? 1024 : 512}
+        title={`Crop ${field.label.toLowerCase()}`}
+        onUpload={uploadCropped}
+      />
+    </div>
+  );
+}

src/components/admin/storage-admin-panel.tsx

@@ -2,7 +2,15 @@
 
 import { useState } from 'react';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { CheckCircle2, HardDrive, Loader2, RefreshCw, ServerCog, XCircle } from 'lucide-react';
+import {
+  AlertTriangle,
+  CheckCircle2,
+  HardDrive,
+  Loader2,
+  RefreshCw,
+  ServerCog,
+  XCircle,
+} from 'lucide-react';
 import { toast } from 'sonner';
 
 import { PageHeader } from '@/components/shared/page-header';
@@ -16,6 +24,10 @@ import {
   DialogHeader,
   DialogTitle,
 } from '@/components/ui/dialog';
+import {
+  SettingsFormCard,
+  type SettingFieldDef,
+} from '@/components/admin/shared/settings-form-card';
 import { apiFetch } from '@/lib/api/client';
 import { toastError } from '@/lib/api/toast-error';
 
@@ -37,10 +49,78 @@ interface MigrationResult {
   dryRun: boolean;
 }
 
+const S3_FIELDS: SettingFieldDef[] = [
+  {
+    key: 'storage_s3_endpoint',
+    label: 'S3 endpoint URL',
+    description:
+      'For AWS use https://s3.<region>.amazonaws.com. For MinIO/Backblaze/R2/Wasabi/Tigris paste the provider-supplied URL.',
+    type: 'string',
+    placeholder: 'https://s3.us-east-1.amazonaws.com',
+    defaultValue: '',
+  },
+  {
+    key: 'storage_s3_region',
+    label: 'S3 region',
+    description: 'AWS region code (e.g. us-east-1, eu-west-1). Use "auto" for Cloudflare R2.',
+    type: 'string',
+    placeholder: 'us-east-1',
+    defaultValue: 'us-east-1',
+  },
+  {
+    key: 'storage_s3_bucket',
+    label: 'S3 bucket name',
+    description: 'Existing bucket the CRM should read/write to. Must already exist.',
+    type: 'string',
+    placeholder: 'port-nimara-storage',
+    defaultValue: '',
+  },
+  {
+    key: 'storage_s3_access_key',
+    label: 'S3 access key',
+    description: 'IAM access key id (or provider equivalent).',
+    type: 'string',
+    placeholder: 'AKIA…',
+    defaultValue: '',
+  },
+  {
+    key: 'storage_s3_secret_key_encrypted',
+    label: 'S3 secret key',
+    description:
+      'Stored AES-encrypted at rest; the field shows blank after save and is replaced only when you type a new value.',
+    type: 'password',
+    placeholder: '(unchanged)',
+    defaultValue: '',
+  },
+  {
+    key: 'storage_s3_force_path_style',
+    label: 'Force path-style URLs',
+    description:
+      'On for MinIO and most self-hosted S3-compatible servers. Off for AWS S3 (which uses virtual-hosted-style by default).',
+    type: 'boolean',
+    defaultValue: false,
+  },
+];
+
+const FS_FIELDS: SettingFieldDef[] = [
+  {
+    key: 'storage_filesystem_root',
+    label: 'Filesystem root path',
+    description:
+      'Absolute path on the server where files are stored. Must be writable by the CRM process. Single-node deployments only.',
+    type: 'string',
+    placeholder: '/var/lib/port-nimara/storage',
+    defaultValue: '/var/lib/port-nimara/storage',
+  },
+];
+
 export function StorageAdminPanel() {
   const queryClient = useQueryClient();
   const [confirmOpen, setConfirmOpen] = useState(false);
   const [dryRun, setDryRun] = useState<MigrationResult | null>(null);
+  const [confirmMode, setConfirmMode] = useState<'switch-only' | 'switch-and-migrate'>(
+    'switch-and-migrate',
+  );
   const [testResult, setTestResult] = useState<{ ok: boolean; error?: string } | null>(null);
 
   const status = useQuery({
@@ -62,7 +142,7 @@ export function StorageAdminPanel() {
   });
 
   const migrateMutation = useMutation({
-    mutationFn: async (opts: { from: BackendName; to: BackendName }) =>
+    mutationFn: async (opts: { from: BackendName; to: BackendName; skipMigration: boolean }) =>
       apiFetch<{ data: MigrationResult }>('/api/v1/admin/storage/migrate', {
         method: 'POST',
         body: JSON.stringify({ ...opts, dryRun: false }),
@@ -71,7 +151,11 @@ export function StorageAdminPanel() {
       setConfirmOpen(false);
       setDryRun(null);
       const copied = result.data.rowsMigrated ?? 0;
-      toast.success(`Storage migration complete (${copied} file${copied === 1 ? '' : 's'} copied)`);
+      toast.success(
+        copied > 0
+          ? `Storage migration complete (${copied} file${copied === 1 ? '' : 's'} copied)`
+          : 'Storage backend switched (no migration performed)',
+      );
       queryClient.invalidateQueries({ queryKey: ['admin', 'storage', 'status'] });
     },
     onError: (e) => toastError(e),
@@ -99,70 +183,41 @@ export function StorageAdminPanel() {
   const s = status.data.data;
   const otherBackend: BackendName = s.backend === 's3' ? 'filesystem' : 's3';
 
+  function openConfirm(mode: 'switch-only' | 'switch-and-migrate') {
+    setConfirmMode(mode);
+    if (mode === 'switch-and-migrate') {
+      // Dry run first so the dialog shows the exact rows + bytes.
+      dryRunMutation.mutate({ from: s.backend, to: otherBackend });
+    } else {
+      // Switch-only — no dry run, just show the warning.
+      setDryRun(null);
+      setConfirmOpen(true);
+    }
+  }
+
   return (
     <div className="space-y-6">
       <PageHeader
         title="Storage Backend"
-        description="Where the CRM stores per-berth PDFs, brochures, GDPR exports, and other binary files."
+        description="Where the CRM stores per-berth PDFs, brochures, GDPR exports, profile photos, and other binary files."
       />
 
-      <div className="grid gap-4 lg:grid-cols-3">
-        <Card className="lg:col-span-2">
-          <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
-            {s.backend === 's3' ? (
-              <ServerCog className="mt-0.5 h-5 w-5 text-muted-foreground" />
-            ) : (
-              <HardDrive className="mt-0.5 h-5 w-5 text-muted-foreground" />
-            )}
-            <div>
-              <CardTitle className="text-base">Active backend: {s.backend}</CardTitle>
-              <CardDescription>
-                {s.backend === 's3'
-                  ? 'Files stored in an S3-compatible object store (MinIO, AWS S3, Backblaze B2, Cloudflare R2, Wasabi, Tigris).'
-                  : 'Files stored on the local filesystem under storage_filesystem_root. Single-node deployments only.'}
-              </CardDescription>
-            </div>
-          </CardHeader>
-          <CardContent className="space-y-4">
-            <dl className="grid grid-cols-2 gap-3 text-sm">
-              <div>
-                <dt className="text-muted-foreground">Tracked tables</dt>
-                <dd>
-                  {s.tablesTracked.length === 0
-                    ? '(none yet — Phase 6b)'
-                    : s.tablesTracked.join(', ')}
-                </dd>
-              </div>
-              <div>
-                <dt className="text-muted-foreground">File count</dt>
-                <dd>{s.fileCount}</dd>
-              </div>
-            </dl>
-
-            <div className="flex flex-wrap gap-3">
-              <Button
-                variant="outline"
-                disabled={dryRunMutation.isPending}
-                onClick={() => dryRunMutation.mutate({ from: s.backend, to: otherBackend })}
-              >
-                {dryRunMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
-                Switch to {otherBackend}
-              </Button>
-              {s.backend === 's3' && (
-                <Button
-                  variant="outline"
-                  onClick={() => testMutation.mutate()}
-                  disabled={testMutation.isPending}
-                >
-                  {testMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
-                  Test connection
-                </Button>
-              )}
-              <Button variant="ghost" onClick={() => status.refetch()} disabled={status.isFetching}>
-                <RefreshCw className="mr-2 h-4 w-4" /> Refresh
-              </Button>
-            </div>
-
+      {/* STEP 1: configure connection details for the OTHER backend so the
+          admin can prep + test BEFORE attempting any switch. */}
+      <SettingsFormCard
+        title="S3 configuration"
+        description="Provider connection details. Save these first, run Test connection, and only then switch the active backend below. You can edit S3 config while filesystem is active without touching live storage."
+        fields={S3_FIELDS}
+        extra={
+          <div className="space-y-3 pt-2 border-t">
+            <Button
+              variant="outline"
+              onClick={() => testMutation.mutate()}
+              disabled={testMutation.isPending}
+            >
+              {testMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+              Test S3 connection
+            </Button>
             {testResult && (
               <div className="rounded-md border p-3 text-sm">
                 {testResult.ok ? (
@@ -176,6 +231,78 @@ export function StorageAdminPanel() {
                 )}
               </div>
             )}
+          </div>
+        }
+      />
+
+      <SettingsFormCard
+        title="Filesystem configuration"
+        description="Used when the active backend is filesystem. Only single-node deployments — multi-node servers must use S3."
+        fields={FS_FIELDS}
+      />
+
+      {/* STEP 2: visualize current state + switch options. Both options
+          are gated behind a confirmation dialog. */}
+      <div className="grid gap-4 lg:grid-cols-3">
+        <Card className="lg:col-span-2">
+          <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
+            {s.backend === 's3' ? (
+              <ServerCog className="mt-0.5 h-5 w-5 text-muted-foreground" />
+            ) : (
+              <HardDrive className="mt-0.5 h-5 w-5 text-muted-foreground" />
+            )}
+            <div>
+              <CardTitle className="text-base">Active backend: {s.backend}</CardTitle>
+              <CardDescription>
+                {s.backend === 's3'
+                  ? 'Files stored in an S3-compatible object store (AWS, MinIO, R2, B2, Wasabi, Tigris).'
+                  : 'Files stored on the local filesystem under storage_filesystem_root. Single-node only.'}
+              </CardDescription>
+            </div>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <dl className="grid grid-cols-2 gap-3 text-sm">
+              <div>
+                <dt className="text-muted-foreground">Tracked tables</dt>
+                <dd>{s.tablesTracked.length === 0 ? '(none yet)' : s.tablesTracked.join(', ')}</dd>
+              </div>
+              <div>
+                <dt className="text-muted-foreground">File count</dt>
+                <dd>{s.fileCount}</dd>
+              </div>
+            </dl>
+
+            <div className="space-y-2">
+              <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                Switch active backend
+              </p>
+              <div className="flex flex-wrap gap-2">
+                <Button
+                  variant="outline"
+                  disabled={dryRunMutation.isPending}
+                  onClick={() => openConfirm('switch-and-migrate')}
+                >
+                  {dryRunMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+                  Switch + migrate existing files to {otherBackend}
+                </Button>
+                <Button variant="outline" onClick={() => openConfirm('switch-only')}>
+                  Switch only (new files only) → {otherBackend}
+                </Button>
+                <Button
+                  variant="ghost"
+                  onClick={() => status.refetch()}
+                  disabled={status.isFetching}
+                >
+                  <RefreshCw className="mr-2 h-4 w-4" /> Refresh
+                </Button>
+              </div>
+              <p className="text-xs text-muted-foreground">
+                <strong>Switch + migrate</strong> copies every existing file to the new backend then
+                flips the pointer atomically. Reversible with a follow-up reverse-migration.{' '}
+                <strong>Switch only</strong> flips the pointer immediately — old files become
+                inaccessible until you migrate them or revert the backend.
+              </p>
+            </div>
           </CardContent>
         </Card>
 
@@ -208,13 +335,19 @@ export function StorageAdminPanel() {
       <Dialog open={confirmOpen} onOpenChange={setConfirmOpen}>
         <DialogContent>
           <DialogHeader>
-            <DialogTitle>Switch storage backend</DialogTitle>
+            <DialogTitle className="flex items-center gap-2">
+              <AlertTriangle className="h-5 w-5 text-amber-600" />
+              {confirmMode === 'switch-and-migrate'
+                ? `Switch + migrate to ${otherBackend}?`
+                : `Switch active backend to ${otherBackend}?`}
+            </DialogTitle>
             <DialogDescription>
-              Move all tracked files from the current backend to the new backend, verify each file
-              via sha256, then atomically flip the active backend.
+              {confirmMode === 'switch-and-migrate'
+                ? 'Copy every existing file to the new backend, verify each via sha256, then atomically flip the active backend. The dry-run summary below shows what will move.'
+                : 'Flip the pointer immediately. Existing files stay on the old backend and become inaccessible until you migrate them or revert. Use this when you intentionally want a fresh storage tier (rare).'}
             </DialogDescription>
           </DialogHeader>
-          {dryRun && (
+          {dryRun && confirmMode === 'switch-and-migrate' && (
             <div className="rounded-md border p-3 text-sm">
               <dl className="grid grid-cols-2 gap-2">
                 <dt className="text-muted-foreground">Rows considered</dt>
@@ -226,16 +359,30 @@ export function StorageAdminPanel() {
               </dl>
             </div>
           )}
+          {confirmMode === 'switch-only' && (
+            <div className="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-900">
+              <strong>Warning:</strong> {s.fileCount} existing file
+              {s.fileCount === 1 ? '' : 's'} on <code className="text-xs">{s.backend}</code> will
+              not be reachable from the CRM after the switch unless you migrate them later. This is
+              rarely the right choice — prefer Switch + migrate.
+            </div>
+          )}
           <DialogFooter>
             <Button variant="outline" onClick={() => setConfirmOpen(false)}>
               Cancel
             </Button>
             <Button
               disabled={migrateMutation.isPending}
-              onClick={() => migrateMutation.mutate({ from: s.backend, to: otherBackend })}
+              onClick={() =>
+                migrateMutation.mutate({
+                  from: s.backend,
+                  to: otherBackend,
+                  skipMigration: confirmMode === 'switch-only',
+                })
+              }
             >
               {migrateMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
-              Migrate now
+              {confirmMode === 'switch-and-migrate' ? 'Migrate now' : 'Switch now'}
             </Button>
           </DialogFooter>
         </DialogContent>

src/components/admin/tags/tag-form.tsx

@@ -111,12 +111,22 @@ export function TagForm({ open, onOpenChange, tag, onSuccess }: TagFormProps) {
               ))}
             </div>
             <div className="flex items-center gap-2 mt-2">
-              <div className="h-7 w-7 rounded-full border" style={{ backgroundColor: color }} />
+              {/* Native colour picker — clicking the swatch opens the
+               *  OS picker, and the chosen colour writes back as a
+               *  hex string. Keeps a manual hex input next to it for
+               *  pasting brand colours from spec sheets. */}
+              <input
+                type="color"
+                value={color}
+                onChange={(e) => setColor(e.target.value)}
+                className="h-7 w-7 rounded-full border cursor-pointer"
+                aria-label="Pick custom color"
+              />
               <Input
                 value={color}
                 onChange={(e) => setColor(e.target.value)}
                 placeholder="#6B7280"
-                className="w-28 font-mono text-sm"
+                className="w-28 font-mono text-sm h-9"
                 maxLength={7}
               />
             </div>