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/providers/socket-provider.tsx

@@ -1,6 +1,13 @@
 'use client';
 
-import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from 'react';
 import { io, type Socket } from 'socket.io-client';
 
 import { useSession } from '@/lib/auth/client';
@@ -8,7 +15,28 @@ import { usePortStore } from '@/stores/ui-store';
 
 const SocketContext = createContext<Socket | null>(null);
 
+/** Returns true once the component has mounted on the client. Avoids calling
+ *  better-auth's `useSession()` (which dispatches React hooks via nanostores)
+ *  during the SSR pass — that combo throws "Invalid hook call" intermittently
+ *  in Next.js 15 dev mode. */
+function useHasMounted(): boolean {
+  return useSyncExternalStore(
+    () => () => {},
+    () => true,
+    () => false,
+  );
+}
+
 export function SocketProvider({ children }: { children: ReactNode }) {
+  const hasMounted = useHasMounted();
+  return hasMounted ? (
+    <SocketProviderClient>{children}</SocketProviderClient>
+  ) : (
+    <SocketContext.Provider value={null}>{children}</SocketContext.Provider>
+  );
+}
+
+function SocketProviderClient({ children }: { children: ReactNode }) {
   const { data: session } = useSession();
   const currentPortId = usePortStore((s) => s.currentPortId);
   const [socket, setSocket] = useState<Socket | null>(null);
@@ -32,11 +60,7 @@ export function SocketProvider({ children }: { children: ReactNode }) {
     };
   }, [session?.user, currentPortId]);
 
-  return (
-    <SocketContext.Provider value={socket}>
-      {children}
-    </SocketContext.Provider>
-  );
+  return <SocketContext.Provider value={socket}>{children}</SocketContext.Provider>;
 }
 
 export function useSocket() {