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/lib/services/notes.service.ts

@@ -3,13 +3,15 @@ import { eq, and, desc } from 'drizzle-orm';
 import { db } from '@/lib/db';
 import { clientNotes, clients } from '@/lib/db/schema/clients';
 import { interestNotes, interests } from '@/lib/db/schema/interests';
+import { yachtNotes, yachts } from '@/lib/db/schema/yachts';
+import { companyNotes, companies } from '@/lib/db/schema/companies';
 import { userProfiles } from '@/lib/db/schema/users';
 import { NotFoundError, ValidationError } from '@/lib/errors';
 import type { CreateNoteInput, UpdateNoteInput } from '@/lib/validators/notes';
 
 const EDIT_WINDOW_MS = 15 * 60 * 1000; // 15 minutes
 
-type EntityType = 'clients' | 'interests';
+type EntityType = 'clients' | 'interests' | 'yachts' | 'companies';
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -19,33 +21,43 @@ async function verifyParentBelongsToPort(
   portId: string,
 ): Promise<void> {
   if (entityType === 'clients') {
-    const client = await db
+    const r = await db
       .select({ id: clients.id })
       .from(clients)
       .where(and(eq(clients.id, entityId), eq(clients.portId, portId)))
       .limit(1);
-    if (!client.length) throw new NotFoundError('Client');
-  } else {
-    const interest = await db
+    if (!r.length) throw new NotFoundError('Client');
+  } else if (entityType === 'interests') {
+    const r = await db
       .select({ id: interests.id })
       .from(interests)
       .where(and(eq(interests.id, entityId), eq(interests.portId, portId)))
       .limit(1);
-    if (!interest.length) throw new NotFoundError('Interest');
+    if (!r.length) throw new NotFoundError('Interest');
+  } else if (entityType === 'yachts') {
+    const r = await db
+      .select({ id: yachts.id })
+      .from(yachts)
+      .where(and(eq(yachts.id, entityId), eq(yachts.portId, portId)))
+      .limit(1);
+    if (!r.length) throw new NotFoundError('Yacht');
+  } else {
+    const r = await db
+      .select({ id: companies.id })
+      .from(companies)
+      .where(and(eq(companies.id, entityId), eq(companies.portId, portId)))
+      .limit(1);
+    if (!r.length) throw new NotFoundError('Company');
   }
 }
 
 // ─── Service ─────────────────────────────────────────────────────────────────
 
-export async function listForEntity(
-  portId: string,
-  entityType: EntityType,
-  entityId: string,
-) {
+export async function listForEntity(portId: string, entityType: EntityType, entityId: string) {
   await verifyParentBelongsToPort(entityType, entityId, portId);
 
   if (entityType === 'clients') {
-    const rows = await db
+    return db
       .select({
         id: clientNotes.id,
         clientId: clientNotes.clientId,
@@ -61,9 +73,8 @@ export async function listForEntity(
       .leftJoin(userProfiles, eq(userProfiles.userId, clientNotes.authorId))
       .where(eq(clientNotes.clientId, entityId))
       .orderBy(desc(clientNotes.createdAt));
-    return rows;
-  } else {
-    const rows = await db
+  } else if (entityType === 'interests') {
+    return db
       .select({
         id: interestNotes.id,
         interestId: interestNotes.interestId,
@@ -79,7 +90,40 @@ export async function listForEntity(
       .leftJoin(userProfiles, eq(userProfiles.userId, interestNotes.authorId))
       .where(eq(interestNotes.interestId, entityId))
       .orderBy(desc(interestNotes.createdAt));
-    return rows;
+  } else if (entityType === 'yachts') {
+    return db
+      .select({
+        id: yachtNotes.id,
+        yachtId: yachtNotes.yachtId,
+        authorId: yachtNotes.authorId,
+        content: yachtNotes.content,
+        mentions: yachtNotes.mentions,
+        isLocked: yachtNotes.isLocked,
+        createdAt: yachtNotes.createdAt,
+        updatedAt: yachtNotes.updatedAt,
+        authorName: userProfiles.displayName,
+      })
+      .from(yachtNotes)
+      .leftJoin(userProfiles, eq(userProfiles.userId, yachtNotes.authorId))
+      .where(eq(yachtNotes.yachtId, entityId))
+      .orderBy(desc(yachtNotes.createdAt));
+  } else {
+    return db
+      .select({
+        id: companyNotes.id,
+        companyId: companyNotes.companyId,
+        authorId: companyNotes.authorId,
+        content: companyNotes.content,
+        mentions: companyNotes.mentions,
+        isLocked: companyNotes.isLocked,
+        createdAt: companyNotes.createdAt,
+        updatedAt: companyNotes.createdAt,
+        authorName: userProfiles.displayName,
+      })
+      .from(companyNotes)
+      .leftJoin(userProfiles, eq(userProfiles.userId, companyNotes.authorId))
+      .where(eq(companyNotes.companyId, entityId))
+      .orderBy(desc(companyNotes.createdAt));
   }
 }
 
@@ -92,6 +136,32 @@ export async function create(
 ) {
   await verifyParentBelongsToPort(entityType, entityId, portId);
 
+  if (entityType === 'yachts') {
+    const [note] = await db
+      .insert(yachtNotes)
+      .values({ yachtId: entityId, authorId, content: data.content })
+      .returning();
+    if (!note) throw new Error('Insert failed');
+    const profile = await db
+      .select({ displayName: userProfiles.displayName })
+      .from(userProfiles)
+      .where(eq(userProfiles.userId, authorId))
+      .limit(1);
+    return { ...note, authorName: profile[0]?.displayName ?? null };
+  }
+  if (entityType === 'companies') {
+    const [note] = await db
+      .insert(companyNotes)
+      .values({ companyId: entityId, authorId, content: data.content })
+      .returning();
+    if (!note) throw new Error('Insert failed');
+    const profile = await db
+      .select({ displayName: userProfiles.displayName })
+      .from(userProfiles)
+      .where(eq(userProfiles.userId, authorId))
+      .limit(1);
+    return { ...note, authorName: profile[0]?.displayName ?? null, updatedAt: note.createdAt };
+  }
   if (entityType === 'clients') {
     const [note] = await db
       .insert(clientNotes)
@@ -165,6 +235,7 @@ export async function create(
 
     return { ...note, authorName };
   }
+  throw new Error(`Unsupported entityType: ${entityType as string}`);
 }
 
 export async function update(
@@ -176,6 +247,56 @@ export async function update(
 ) {
   await verifyParentBelongsToPort(entityType, entityId, portId);
 
+  if (entityType === 'yachts') {
+    const [existing] = await db
+      .select()
+      .from(yachtNotes)
+      .where(and(eq(yachtNotes.id, noteId), eq(yachtNotes.yachtId, entityId)))
+      .limit(1);
+    if (!existing) throw new NotFoundError('Note');
+    if (Date.now() - new Date(existing.createdAt).getTime() > EDIT_WINDOW_MS) {
+      throw new ValidationError('Note edit window has expired (15 minutes)');
+    }
+    const [updated] = await db
+      .update(yachtNotes)
+      .set({ content: data.content, updatedAt: new Date() })
+      .where(eq(yachtNotes.id, noteId))
+      .returning();
+    if (!updated) throw new NotFoundError('Note');
+    const profile = await db
+      .select({ displayName: userProfiles.displayName })
+      .from(userProfiles)
+      .where(eq(userProfiles.userId, updated.authorId))
+      .limit(1);
+    return { ...updated, authorName: profile[0]?.displayName ?? null };
+  }
+  if (entityType === 'companies') {
+    const [existing] = await db
+      .select()
+      .from(companyNotes)
+      .where(and(eq(companyNotes.id, noteId), eq(companyNotes.companyId, entityId)))
+      .limit(1);
+    if (!existing) throw new NotFoundError('Note');
+    if (Date.now() - new Date(existing.createdAt).getTime() > EDIT_WINDOW_MS) {
+      throw new ValidationError('Note edit window has expired (15 minutes)');
+    }
+    const [updated] = await db
+      .update(companyNotes)
+      .set({ content: data.content })
+      .where(eq(companyNotes.id, noteId))
+      .returning();
+    if (!updated) throw new NotFoundError('Note');
+    const profile = await db
+      .select({ displayName: userProfiles.displayName })
+      .from(userProfiles)
+      .where(eq(userProfiles.userId, updated.authorId))
+      .limit(1);
+    return {
+      ...updated,
+      authorName: profile[0]?.displayName ?? null,
+      updatedAt: updated.createdAt,
+    };
+  }
   if (entityType === 'clients') {
     const [existing] = await db
       .select()
@@ -241,6 +362,32 @@ export async function deleteNote(
 ) {
   await verifyParentBelongsToPort(entityType, entityId, portId);
 
+  if (entityType === 'yachts') {
+    const [existing] = await db
+      .select()
+      .from(yachtNotes)
+      .where(and(eq(yachtNotes.id, noteId), eq(yachtNotes.yachtId, entityId)))
+      .limit(1);
+    if (!existing) throw new NotFoundError('Note');
+    if (Date.now() - new Date(existing.createdAt).getTime() > EDIT_WINDOW_MS) {
+      throw new ValidationError('Note edit window has expired (15 minutes)');
+    }
+    await db.delete(yachtNotes).where(eq(yachtNotes.id, noteId));
+    return existing;
+  }
+  if (entityType === 'companies') {
+    const [existing] = await db
+      .select()
+      .from(companyNotes)
+      .where(and(eq(companyNotes.id, noteId), eq(companyNotes.companyId, entityId)))
+      .limit(1);
+    if (!existing) throw new NotFoundError('Note');
+    if (Date.now() - new Date(existing.createdAt).getTime() > EDIT_WINDOW_MS) {
+      throw new ValidationError('Note edit window has expired (15 minutes)');
+    }
+    await db.delete(companyNotes).where(eq(companyNotes.id, noteId));
+    return existing;
+  }
   if (entityType === 'clients') {
     const [existing] = await db
       .select()