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/validators/form-templates.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+export const formFieldSchema = z.object({
+  key: z.string().min(1).max(80),
+  label: z.string().min(1).max(200),
+  type: z.enum(['text', 'textarea', 'email', 'phone', 'number', 'select', 'checkbox']),
+  required: z.boolean().optional().default(false),
+  options: z.array(z.string()).optional(),
+  helpText: z.string().optional(),
+});
+
+export const createFormTemplateSchema = z.object({
+  name: z.string().min(1).max(200),
+  description: z.string().optional(),
+  fields: z.array(formFieldSchema).min(1, 'At least one field is required'),
+  branding: z.record(z.unknown()).optional(),
+  isActive: z.boolean().optional().default(true),
+});
+
+export const updateFormTemplateSchema = createFormTemplateSchema.partial();
+
+export type FormField = z.infer<typeof formFieldSchema>;
+export type CreateFormTemplateInput = z.infer<typeof createFormTemplateSchema>;
+export type UpdateFormTemplateInput = z.infer<typeof updateFormTemplateSchema>;

src/lib/validators/residential.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+
+import { baseListQuerySchema } from '@/lib/api/route-helpers';
+
+// ─── Residential client ──────────────────────────────────────────────────────
+
+export const createResidentialClientSchema = z.object({
+  fullName: z.string().min(1).max(200),
+  email: z
+    .string()
+    .email()
+    .optional()
+    .or(z.literal('').transform(() => undefined)),
+  phone: z.string().optional(),
+  placeOfResidence: z.string().optional(),
+  preferredContactMethod: z.enum(['email', 'phone']).optional(),
+  status: z.enum(['prospect', 'active', 'inactive']).optional().default('prospect'),
+  source: z.enum(['website', 'manual', 'referral', 'broker']).optional(),
+  notes: z.string().optional(),
+});
+
+export const updateResidentialClientSchema = createResidentialClientSchema.partial();
+
+export const listResidentialClientsSchema = baseListQuerySchema.extend({
+  status: z.enum(['prospect', 'active', 'inactive']).optional(),
+  source: z.enum(['website', 'manual', 'referral', 'broker']).optional(),
+});
+
+// ─── Residential interest ────────────────────────────────────────────────────
+
+export const PIPELINE_STAGES = [
+  'new',
+  'contacted',
+  'viewing_scheduled',
+  'offer_made',
+  'offer_accepted',
+  'closed_won',
+  'closed_lost',
+] as const;
+
+export const createResidentialInterestSchema = z.object({
+  residentialClientId: z.string().min(1),
+  pipelineStage: z.enum(PIPELINE_STAGES).optional().default('new'),
+  source: z.enum(['website', 'manual', 'referral', 'broker']).optional(),
+  notes: z.string().optional(),
+  preferences: z.string().optional(),
+  assignedTo: z.string().optional(),
+});
+
+export const updateResidentialInterestSchema = createResidentialInterestSchema
+  .omit({ residentialClientId: true })
+  .partial();
+
+export const listResidentialInterestsSchema = baseListQuerySchema.extend({
+  pipelineStage: z.enum(PIPELINE_STAGES).optional(),
+  assignedTo: z.string().optional(),
+  residentialClientId: z.string().optional(),
+});
+
+// ─── Public website inquiry ──────────────────────────────────────────────────
+
+/**
+ * Shape posted by the public website's residential interest form. Coerces
+ * to internal create-shapes inside the public route.
+ */
+export const publicResidentialInquirySchema = z.object({
+  firstName: z.string().min(1),
+  lastName: z.string().min(1),
+  email: z.string().email(),
+  phone: z.string().min(1),
+  placeOfResidence: z.string().optional(),
+  preferredContactMethod: z.enum(['email', 'phone']).optional(),
+  notes: z.string().optional(),
+  preferences: z.string().optional(),
+});
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type CreateResidentialClientInput = z.infer<typeof createResidentialClientSchema>;
+export type UpdateResidentialClientInput = z.infer<typeof updateResidentialClientSchema>;
+export type ListResidentialClientsInput = z.infer<typeof listResidentialClientsSchema>;
+
+export type CreateResidentialInterestInput = z.infer<typeof createResidentialInterestSchema>;
+export type UpdateResidentialInterestInput = z.infer<typeof updateResidentialInterestSchema>;
+export type ListResidentialInterestsInput = z.infer<typeof listResidentialInterestsSchema>;
+
+export type PublicResidentialInquiryInput = z.infer<typeof publicResidentialInquirySchema>;

src/lib/validators/users.ts

@@ -7,6 +7,7 @@ export const createUserSchema = z.object({
   displayName: z.string().min(1).max(200),
   phone: z.string().optional(),
   roleId: z.string().uuid(),
+  residentialAccess: z.boolean().optional().default(false),
 });
 
 export type CreateUserInput = z.infer<typeof createUserSchema>;
@@ -16,6 +17,7 @@ export const updateUserSchema = z.object({
   phone: z.string().nullable().optional(),
   isActive: z.boolean().optional(),
   roleId: z.string().uuid().optional(),
+  residentialAccess: z.boolean().optional(),
 });
 
 export type UpdateUserInput = z.infer<typeof updateUserSchema>;