feat(platform): residential module + admin UI + reliability fixes

Residential platform
- New schema: residentialClients, residentialInterests (separate from
  marina/yacht clients) with migration 0010
- Service layer with CRUD + audit + sockets + per-port portal toggle
- v1 + public API routes (/api/v1/residential/*, /api/public/residential-inquiries)
- List + detail pages with inline editing for clients and interests
- Per-user residentialAccess toggle on userPortRoles (migration 0011)
- Permission keys: residential_clients, residential_interests
- Sidebar nav + role form integration
- Smoke spec covering page loads, UI create flow, public endpoint

Admin & shared UI
- Admin → Forms (form templates CRUD) with validators + service
- Notification preferences page (in-app + email per type)
- Email composition + accounts list + threads view
- Branded auth shell shared across CRM + portal auth surfaces
- Inline editing extended to yacht/company/interest detail pages
- InlineTagEditor + per-entity tags endpoints (yachts, companies)
- Notes service polymorphic across clients/interests/yachts/companies
- Client list columns: yachtCount + companyCount badges
- Reservation file-download via presigned URL (replaces stale <a href>)

Route handler refactor
- Extracted yachts/companies/berths reservation handlers to sibling
  handlers.ts files (Next.js 15 route.ts only allows specific exports)

Reliability fixes
- apiFetch double-stringify bug fixed across 13 components
  (apiFetch already JSON.stringifies its body; passing a stringified
  body produced double-encoded JSON which failed zod validation)
- SocketProvider gated behind useSyncExternalStore-based mount check
  to avoid useSession() SSR crashes under React 19 + Next 15
- apiFetch falls back to URL-pathname → port-id resolution when the
  Zustand store hasn't hydrated yet (fresh contexts, e2e tests)
- CRM invite flow (schema, service, route, email, dev script)
- Dashboard route → [portSlug]/dashboard/page.tsx + redirect
- Document the dev-server restart-after-migration gotcha in CLAUDE.md

Tests
- 5-case residential smoke spec
- Integration test updates for new service signatures

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

src/components/email/compose-dialog.tsx

@@ -0,0 +1,153 @@
+'use client';
+
+import { useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Textarea } from '@/components/ui/textarea';
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { apiFetch } from '@/lib/api/client';
+
+interface Account {
+  id: string;
+  emailAddress: string;
+  isActive: boolean;
+}
+
+interface ComposeDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  defaultTo?: string;
+  defaultSubject?: string;
+}
+
+export function ComposeDialog({
+  open,
+  onOpenChange,
+  defaultTo = '',
+  defaultSubject = '',
+}: ComposeDialogProps) {
+  const qc = useQueryClient();
+  const [accountId, setAccountId] = useState('');
+  const [to, setTo] = useState(defaultTo);
+  const [cc, setCc] = useState('');
+  const [subject, setSubject] = useState(defaultSubject);
+  const [body, setBody] = useState('');
+
+  const { data: accounts = [] } = useQuery<Account[]>({
+    queryKey: ['email', 'accounts'],
+    queryFn: () => apiFetch<{ data: Account[] }>('/api/v1/email/accounts').then((r) => r.data),
+  });
+
+  const activeAccounts = accounts.filter((a) => a.isActive);
+
+  const sendMutation = useMutation({
+    mutationFn: () =>
+      apiFetch('/api/v1/email/compose', {
+        method: 'POST',
+        body: {
+          accountId,
+          to: to
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean),
+          cc: cc
+            ? cc
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : undefined,
+          subject,
+          bodyHtml: body.replace(/\n/g, '<br>'),
+        },
+      }),
+    onSuccess: () => {
+      toast.success('Email sent');
+      qc.invalidateQueries({ queryKey: ['email', 'threads'] });
+      onOpenChange(false);
+      setTo('');
+      setCc('');
+      setSubject('');
+      setBody('');
+    },
+    onError: (err) => toast.error(err instanceof Error ? err.message : 'Send failed'),
+  });
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-2xl">
+        <DialogHeader>
+          <DialogTitle>Compose email</DialogTitle>
+        </DialogHeader>
+        <div className="space-y-3">
+          <div className="space-y-1">
+            <Label>From</Label>
+            <Select value={accountId} onValueChange={setAccountId}>
+              <SelectTrigger>
+                <SelectValue placeholder="Choose account" />
+              </SelectTrigger>
+              <SelectContent>
+                {activeAccounts.length === 0 ? (
+                  <div className="px-2 py-1.5 text-sm text-muted-foreground">
+                    No active accounts
+                  </div>
+                ) : (
+                  activeAccounts.map((a) => (
+                    <SelectItem key={a.id} value={a.id}>
+                      {a.emailAddress}
+                    </SelectItem>
+                  ))
+                )}
+              </SelectContent>
+            </Select>
+          </div>
+          <div className="space-y-1">
+            <Label>To (comma-separated)</Label>
+            <Input value={to} onChange={(e) => setTo(e.target.value)} />
+          </div>
+          <div className="space-y-1">
+            <Label>CC</Label>
+            <Input value={cc} onChange={(e) => setCc(e.target.value)} />
+          </div>
+          <div className="space-y-1">
+            <Label>Subject</Label>
+            <Input value={subject} onChange={(e) => setSubject(e.target.value)} />
+          </div>
+          <div className="space-y-1">
+            <Label>Message</Label>
+            <Textarea rows={10} value={body} onChange={(e) => setBody(e.target.value)} />
+          </div>
+        </div>
+        <DialogFooter>
+          <Button variant="ghost" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button
+            onClick={() => sendMutation.mutate()}
+            disabled={
+              sendMutation.isPending || !accountId || !to.trim() || !subject.trim() || !body.trim()
+            }
+          >
+            {sendMutation.isPending ? 'Sending…' : 'Send'}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

src/components/email/email-accounts-list.tsx

@@ -0,0 +1,264 @@
+'use client';
+
+import { useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Mail, Plus, Trash2, RefreshCw } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { 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 { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
+import { apiFetch } from '@/lib/api/client';
+
+interface Account {
+  id: string;
+  provider: 'google' | 'outlook' | 'custom';
+  emailAddress: string;
+  smtpHost: string;
+  smtpPort: number;
+  imapHost: string;
+  imapPort: number;
+  username: string;
+  isActive: boolean;
+  lastSyncAt: string | null;
+}
+
+const PROVIDER_DEFAULTS: Record<
+  string,
+  { smtpHost: string; smtpPort: number; imapHost: string; imapPort: number }
+> = {
+  google: { smtpHost: 'smtp.gmail.com', smtpPort: 587, imapHost: 'imap.gmail.com', imapPort: 993 },
+  outlook: {
+    smtpHost: 'smtp.office365.com',
+    smtpPort: 587,
+    imapHost: 'outlook.office365.com',
+    imapPort: 993,
+  },
+  custom: { smtpHost: '', smtpPort: 587, imapHost: '', imapPort: 993 },
+};
+
+export function EmailAccountsList() {
+  const qc = useQueryClient();
+  const [sheetOpen, setSheetOpen] = useState(false);
+  const [form, setForm] = useState({
+    provider: 'google' as 'google' | 'outlook' | 'custom',
+    emailAddress: '',
+    smtpHost: PROVIDER_DEFAULTS.google!.smtpHost,
+    smtpPort: PROVIDER_DEFAULTS.google!.smtpPort,
+    imapHost: PROVIDER_DEFAULTS.google!.imapHost,
+    imapPort: PROVIDER_DEFAULTS.google!.imapPort,
+    username: '',
+    password: '',
+  });
+
+  const { data: accounts = [], isLoading } = useQuery<Account[]>({
+    queryKey: ['email', 'accounts'],
+    queryFn: () => apiFetch<{ data: Account[] }>('/api/v1/email/accounts').then((r) => r.data),
+  });
+
+  const createMutation = useMutation({
+    mutationFn: () => apiFetch('/api/v1/email/accounts', { method: 'POST', body: form }),
+    onSuccess: () => {
+      toast.success('Account connected');
+      setSheetOpen(false);
+      qc.invalidateQueries({ queryKey: ['email', 'accounts'] });
+    },
+    onError: (err) => toast.error(err instanceof Error ? err.message : 'Failed to connect account'),
+  });
+
+  const toggleMutation = useMutation({
+    mutationFn: ({ id, isActive }: { id: string; isActive: boolean }) =>
+      apiFetch(`/api/v1/email/accounts/${id}`, {
+        method: 'PATCH',
+        body: { isActive },
+      }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['email', 'accounts'] }),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: (id: string) => apiFetch(`/api/v1/email/accounts/${id}`, { method: 'DELETE' }),
+    onSuccess: () => {
+      toast.success('Account removed');
+      qc.invalidateQueries({ queryKey: ['email', 'accounts'] });
+    },
+  });
+
+  const syncMutation = useMutation({
+    mutationFn: (id: string) => apiFetch(`/api/v1/email/accounts/${id}/sync`, { method: 'POST' }),
+    onSuccess: () => {
+      toast.success('Sync started');
+      qc.invalidateQueries({ queryKey: ['email', 'accounts'] });
+    },
+  });
+
+  function setProvider(provider: 'google' | 'outlook' | 'custom') {
+    const defaults = PROVIDER_DEFAULTS[provider]!;
+    setForm({ ...form, provider, ...defaults });
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex justify-between items-center">
+        <div>
+          <h2 className="text-lg font-semibold">Connected Accounts</h2>
+          <p className="text-sm text-muted-foreground">
+            IMAP/SMTP accounts used for sending and receiving client emails.
+          </p>
+        </div>
+        <Button onClick={() => setSheetOpen(true)}>
+          <Plus className="h-4 w-4 mr-1.5" />
+          Add account
+        </Button>
+      </div>
+
+      {isLoading ? (
+        <p className="text-sm text-muted-foreground">Loading…</p>
+      ) : accounts.length === 0 ? (
+        <div className="rounded-lg border border-dashed p-8 text-center text-muted-foreground">
+          <Mail className="mx-auto h-6 w-6 mb-2" />
+          <p className="text-sm">No email accounts connected.</p>
+        </div>
+      ) : (
+        <div className="rounded-lg border divide-y">
+          {accounts.map((a) => (
+            <div key={a.id} className="flex items-center gap-3 p-3">
+              <Mail className="h-5 w-5 text-muted-foreground" />
+              <div className="flex-1 min-w-0">
+                <div className="text-sm font-medium truncate">{a.emailAddress}</div>
+                <div className="text-xs text-muted-foreground">
+                  {a.provider} · {a.imapHost}
+                  {a.lastSyncAt && ` · last sync ${new Date(a.lastSyncAt).toLocaleString()}`}
+                </div>
+              </div>
+              <Switch
+                checked={a.isActive}
+                onCheckedChange={(v) => toggleMutation.mutate({ id: a.id, isActive: v })}
+              />
+              <Button
+                variant="ghost"
+                size="icon"
+                onClick={() => syncMutation.mutate(a.id)}
+                disabled={syncMutation.isPending}
+                title="Sync now"
+              >
+                <RefreshCw className="h-4 w-4" />
+              </Button>
+              <ConfirmationDialog
+                trigger={
+                  <Button variant="ghost" size="icon" className="text-destructive">
+                    <Trash2 className="h-4 w-4" />
+                  </Button>
+                }
+                title="Remove account"
+                description={`Disconnect ${a.emailAddress}?`}
+                confirmLabel="Remove"
+                onConfirm={() => deleteMutation.mutate(a.id)}
+              />
+            </div>
+          ))}
+        </div>
+      )}
+
+      <Sheet open={sheetOpen} onOpenChange={setSheetOpen}>
+        <SheetContent className="overflow-y-auto">
+          <SheetHeader>
+            <SheetTitle>Connect email account</SheetTitle>
+          </SheetHeader>
+          <div className="space-y-3 py-4">
+            <div className="space-y-1">
+              <Label>Provider</Label>
+              <Select
+                value={form.provider}
+                onValueChange={(v) => setProvider(v as 'google' | 'outlook' | 'custom')}
+              >
+                <SelectTrigger>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="google">Google</SelectItem>
+                  <SelectItem value="outlook">Outlook / Office 365</SelectItem>
+                  <SelectItem value="custom">Custom IMAP/SMTP</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+            <div className="space-y-1">
+              <Label>Email address</Label>
+              <Input
+                type="email"
+                value={form.emailAddress}
+                onChange={(e) =>
+                  setForm({ ...form, emailAddress: e.target.value, username: e.target.value })
+                }
+              />
+            </div>
+            <div className="space-y-1">
+              <Label>Username</Label>
+              <Input
+                value={form.username}
+                onChange={(e) => setForm({ ...form, username: e.target.value })}
+              />
+            </div>
+            <div className="space-y-1">
+              <Label>Password / App password</Label>
+              <Input
+                type="password"
+                value={form.password}
+                onChange={(e) => setForm({ ...form, password: e.target.value })}
+              />
+            </div>
+            <div className="grid grid-cols-2 gap-2">
+              <div className="space-y-1">
+                <Label>SMTP host</Label>
+                <Input
+                  value={form.smtpHost}
+                  onChange={(e) => setForm({ ...form, smtpHost: e.target.value })}
+                />
+              </div>
+              <div className="space-y-1">
+                <Label>SMTP port</Label>
+                <Input
+                  type="number"
+                  value={form.smtpPort}
+                  onChange={(e) => setForm({ ...form, smtpPort: Number(e.target.value) })}
+                />
+              </div>
+              <div className="space-y-1">
+                <Label>IMAP host</Label>
+                <Input
+                  value={form.imapHost}
+                  onChange={(e) => setForm({ ...form, imapHost: e.target.value })}
+                />
+              </div>
+              <div className="space-y-1">
+                <Label>IMAP port</Label>
+                <Input
+                  type="number"
+                  value={form.imapPort}
+                  onChange={(e) => setForm({ ...form, imapPort: Number(e.target.value) })}
+                />
+              </div>
+            </div>
+          </div>
+          <SheetFooter>
+            <Button variant="ghost" onClick={() => setSheetOpen(false)}>
+              Cancel
+            </Button>
+            <Button onClick={() => createMutation.mutate()} disabled={createMutation.isPending}>
+              {createMutation.isPending ? 'Connecting…' : 'Connect'}
+            </Button>
+          </SheetFooter>
+        </SheetContent>
+      </Sheet>
+    </div>
+  );
+}

src/components/email/email-threads-list.tsx

@@ -0,0 +1,70 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import { formatDistanceToNow } from 'date-fns';
+import { Mail } from 'lucide-react';
+
+import { apiFetch } from '@/lib/api/client';
+
+interface Thread {
+  id: string;
+  subject: string;
+  snippet: string | null;
+  lastMessageAt: string;
+  participants: string[];
+  unreadCount: number;
+}
+
+interface ThreadsResponse {
+  data: Thread[];
+  total: number;
+}
+
+export function EmailThreadsList() {
+  const { data, isLoading } = useQuery<ThreadsResponse>({
+    queryKey: ['email', 'threads'],
+    queryFn: () => apiFetch<ThreadsResponse>('/api/v1/email/threads'),
+  });
+
+  if (isLoading) {
+    return <p className="text-sm text-muted-foreground">Loading threads…</p>;
+  }
+
+  const threads = data?.data ?? [];
+
+  if (threads.length === 0) {
+    return (
+      <div className="rounded-lg border border-dashed p-8 text-center text-muted-foreground">
+        <Mail className="mx-auto h-6 w-6 mb-2" />
+        <p className="text-sm">No email threads yet.</p>
+        <p className="text-xs">
+          Connect an account and trigger a sync to see incoming threads here.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="rounded-lg border divide-y">
+      {threads.map((t) => (
+        <div key={t.id} className="p-3 hover:bg-muted/40">
+          <div className="flex items-center justify-between gap-2">
+            <div className="text-sm font-medium truncate">{t.subject || '(no subject)'}</div>
+            <div className="text-xs text-muted-foreground shrink-0">
+              {formatDistanceToNow(new Date(t.lastMessageAt), { addSuffix: true })}
+            </div>
+          </div>
+          <div className="text-xs text-muted-foreground truncate">{t.participants.join(', ')}</div>
+          {t.snippet && (
+            <div className="text-xs text-muted-foreground mt-1 line-clamp-1">{t.snippet}</div>
+          )}
+          {t.unreadCount > 0 && (
+            <span className="inline-block mt-1 rounded-full bg-primary/10 px-2 py-0.5 text-xs text-primary">
+              {t.unreadCount} unread
+            </span>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}