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>

tests/e2e/smoke/26-residential.spec.ts

@@ -0,0 +1,91 @@
+import { test, expect } from '@playwright/test';
+
+import { getPortId, login, navigateTo, waitForSheet } from './helpers';
+
+const RES_CLIENT_NAME = `E2E Res Client ${Date.now()}`;
+const RES_CLIENT_EMAIL = `e2e-res-${Date.now()}@test.example`;
+
+test.describe('Residential', () => {
+  test.beforeEach(async ({ page }) => {
+    await login(page, 'super_admin');
+  });
+
+  test('residential clients page loads with empty state or table', async ({ page }) => {
+    await navigateTo(page, '/residential/clients');
+    await expect(page.getByRole('heading', { name: /residential clients/i })).toBeVisible({
+      timeout: 10_000,
+    });
+    // Either table or empty state should render — both ok.
+    const hasTableOrEmpty = await Promise.race([
+      page
+        .locator('table')
+        .first()
+        .isVisible({ timeout: 5_000 })
+        .catch(() => false),
+      page
+        .getByRole('button', { name: /new/i })
+        .first()
+        .isVisible({ timeout: 5_000 })
+        .catch(() => false),
+    ]);
+    expect(hasTableOrEmpty).toBeTruthy();
+  });
+
+  test('create a residential client via UI', async ({ page }) => {
+    await navigateTo(page, '/residential/clients');
+    await page.locator('main').getByRole('button', { name: /^new$/i }).first().click();
+    await waitForSheet(page);
+
+    const sheet = page.locator('[role="dialog"]');
+    await sheet.locator('#rc-name').fill(RES_CLIENT_NAME);
+    await sheet.locator('#rc-email').fill(RES_CLIENT_EMAIL);
+
+    await sheet.getByRole('button', { name: /create|save/i }).click();
+    await expect(sheet).not.toBeVisible({ timeout: 30_000 });
+    await page.waitForTimeout(1500);
+
+    // Reload list and confirm row is present.
+    await navigateTo(page, '/residential/clients');
+    await expect(page.getByText(RES_CLIENT_NAME).first()).toBeVisible({ timeout: 30_000 });
+  });
+
+  test('residential interests page loads', async ({ page }) => {
+    await navigateTo(page, '/residential/interests');
+    await expect(page.getByRole('heading', { name: /residential interests/i })).toBeVisible({
+      timeout: 10_000,
+    });
+  });
+
+  test('residential nav section is visible in sidebar', async ({ page }) => {
+    await navigateTo(page, '/dashboard');
+    // Both residential links should appear for super_admin.
+    await expect(page.getByRole('link', { name: /residential clients/i }).first()).toBeVisible({
+      timeout: 10_000,
+    });
+    await expect(page.getByRole('link', { name: /residential interests/i }).first()).toBeVisible({
+      timeout: 10_000,
+    });
+  });
+
+  test('public residential inquiry endpoint accepts a submission', async ({ page }) => {
+    // Direct API call to the public endpoint — confirms wiring without UI.
+    // Public endpoint takes portId via query string (no auth, but the helper
+    // resolves the port ID for us via the admin API).
+    const portId = await getPortId(page);
+    const res = await page.request.post(
+      `/api/public/residential-inquiries?portId=${encodeURIComponent(portId)}`,
+      {
+        data: {
+          firstName: `Public${Date.now()}`,
+          lastName: 'Smoke',
+          email: `public-res-${Date.now()}@test.example`,
+          phone: '+1-555-0100',
+          notes: 'Smoke test inquiry',
+        },
+        headers: { 'Content-Type': 'application/json' },
+      },
+    );
+    // 201 success, 429 if rate-limit hit (also acceptable as proof endpoint exists).
+    expect([201, 429]).toContain(res.status());
+  });
+});

tests/helpers/factories.ts

@@ -365,6 +365,14 @@ export function makeFullPermissions(): RolePermissions {
       manage_tags: true,
       system_backup: true,
     },
+    residential_clients: { view: true, create: true, edit: true, delete: true },
+    residential_interests: {
+      view: true,
+      create: true,
+      edit: true,
+      delete: true,
+      change_stage: true,
+    },
   };
 }
 
@@ -434,6 +442,14 @@ export function makeViewerPermissions(): RolePermissions {
       manage_tags: false,
       system_backup: false,
     },
+    residential_clients: { view: false, create: false, edit: false, delete: false },
+    residential_interests: {
+      view: false,
+      create: false,
+      edit: false,
+      delete: false,
+      change_stage: false,
+    },
   };
 }
 
@@ -503,6 +519,14 @@ export function makeSalesAgentPermissions(): RolePermissions {
       manage_tags: false,
       system_backup: false,
     },
+    residential_clients: { view: false, create: false, edit: false, delete: false },
+    residential_interests: {
+      view: false,
+      create: false,
+      edit: false,
+      delete: false,
+      change_stage: false,
+    },
   };
 }
 
@@ -572,6 +596,14 @@ export function makeSalesManagerPermissions(): RolePermissions {
       manage_tags: true,
       system_backup: false,
     },
+    residential_clients: { view: true, create: true, edit: true, delete: true },
+    residential_interests: {
+      view: true,
+      create: true,
+      edit: true,
+      delete: true,
+      change_stage: true,
+    },
   };
 }
 

tests/integration/api/companies.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 
-import { listHandler, createHandler } from '@/app/api/v1/companies/route';
-import { getHandler, patchHandler, deleteHandler } from '@/app/api/v1/companies/[id]/route';
+import { listHandler, createHandler } from '@/app/api/v1/companies/handlers';
+import { getHandler, patchHandler, deleteHandler } from '@/app/api/v1/companies/[id]/handlers';
 import { autocompleteHandler } from '@/app/api/v1/companies/autocomplete/route';
 import { db } from '@/lib/db';
 import { companies } from '@/lib/db/schema';

tests/integration/api/reservations.test.ts

@@ -4,7 +4,7 @@ import { eq } from 'drizzle-orm';
 import {
   createHandler as createReservationHandler,
   listHandler as listReservationsHandler,
-} from '@/app/api/v1/berths/[id]/reservations/route';
+} from '@/app/api/v1/berths/[id]/reservations/handlers';
 import {
   getHandler as getReservationHandler,
   patchHandler as patchReservationHandler,

tests/integration/api/yachts-detail.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 
-import { getHandler, patchHandler, deleteHandler } from '@/app/api/v1/yachts/[id]/route';
+import { getHandler, patchHandler, deleteHandler } from '@/app/api/v1/yachts/[id]/handlers';
 import { transferHandler } from '@/app/api/v1/yachts/[id]/transfer/route';
 import { historyHandler } from '@/app/api/v1/yachts/[id]/ownership-history/route';
 import { autocompleteHandler } from '@/app/api/v1/yachts/autocomplete/route';

tests/integration/api/yachts.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 
-import { listHandler, createHandler, POST } from '@/app/api/v1/yachts/route';
+import { listHandler, createHandler } from '@/app/api/v1/yachts/handlers';
+import { POST } from '@/app/api/v1/yachts/route';
 import { withPermission } from '@/lib/api/helpers';
 import { makeMockCtx, makeMockRequest } from '../../helpers/route-tester';
 import {