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/db/migrations/0010_brave_joshua_kane.sql

@@ -0,0 +1,13 @@
+CREATE TABLE "crm_user_invites" (
+	"id" text PRIMARY KEY NOT NULL,
+	"email" text NOT NULL,
+	"name" text,
+	"token_hash" text NOT NULL,
+	"is_super_admin" boolean DEFAULT false NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"used_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_crm_invites_token_hash" ON "crm_user_invites" USING btree ("token_hash");--> statement-breakpoint
+CREATE INDEX "idx_crm_invites_email" ON "crm_user_invites" USING btree ("email");

src/lib/db/migrations/0011_red_cargill.sql

@@ -0,0 +1,43 @@
+CREATE TABLE "residential_clients" (
+	"id" text PRIMARY KEY NOT NULL,
+	"port_id" text NOT NULL,
+	"full_name" text NOT NULL,
+	"email" text,
+	"phone" text,
+	"place_of_residence" text,
+	"preferred_contact_method" text,
+	"status" text DEFAULT 'prospect' NOT NULL,
+	"source" text,
+	"notes" text,
+	"archived_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "residential_interests" (
+	"id" text PRIMARY KEY NOT NULL,
+	"port_id" text NOT NULL,
+	"residential_client_id" text NOT NULL,
+	"pipeline_stage" text DEFAULT 'new' NOT NULL,
+	"source" text,
+	"notes" text,
+	"preferences" text,
+	"assigned_to" text,
+	"date_first_contact" timestamp with time zone,
+	"date_last_contact" timestamp with time zone,
+	"archived_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "residential_clients" ADD CONSTRAINT "residential_clients_port_id_ports_id_fk" FOREIGN KEY ("port_id") REFERENCES "public"."ports"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "residential_interests" ADD CONSTRAINT "residential_interests_port_id_ports_id_fk" FOREIGN KEY ("port_id") REFERENCES "public"."ports"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "residential_interests" ADD CONSTRAINT "residential_interests_residential_client_id_residential_clients_id_fk" FOREIGN KEY ("residential_client_id") REFERENCES "public"."residential_clients"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "idx_residential_clients_port" ON "residential_clients" USING btree ("port_id");--> statement-breakpoint
+CREATE INDEX "idx_residential_clients_email" ON "residential_clients" USING btree ("email");--> statement-breakpoint
+CREATE INDEX "idx_residential_clients_archived" ON "residential_clients" USING btree ("port_id","archived_at");--> statement-breakpoint
+CREATE INDEX "idx_residential_interests_port" ON "residential_interests" USING btree ("port_id");--> statement-breakpoint
+CREATE INDEX "idx_residential_interests_client" ON "residential_interests" USING btree ("residential_client_id");--> statement-breakpoint
+CREATE INDEX "idx_residential_interests_stage" ON "residential_interests" USING btree ("port_id","pipeline_stage");--> statement-breakpoint
+CREATE INDEX "idx_residential_interests_assigned" ON "residential_interests" USING btree ("assigned_to");--> statement-breakpoint
+CREATE INDEX "idx_residential_interests_archived" ON "residential_interests" USING btree ("port_id","archived_at");

src/lib/db/migrations/0012_large_zarda.sql

@@ -0,0 +1 @@
+ALTER TABLE "user_port_roles" ADD COLUMN "residential_access" boolean DEFAULT false NOT NULL;

src/lib/db/migrations/meta/_journal.json

@@ -71,6 +71,27 @@
       "when": 1777210206070,
       "tag": "0009_outgoing_rumiko_fujikawa",
       "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1777303428222,
+      "tag": "0010_brave_joshua_kane",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1777307410311,
+      "tag": "0011_red_cargill",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1777308900666,
+      "tag": "0012_large_zarda",
+      "breakpoints": true
     }
   ]
 }

src/lib/db/schema/crm-invites.ts

@@ -0,0 +1,32 @@
+import { pgTable, text, boolean, timestamp, index, uniqueIndex } from 'drizzle-orm/pg-core';
+
+/**
+ * Single-use admin-issued invites for CRM users (better-auth realm).
+ *
+ * `tokenHash` is a SHA-256 hash of the raw token sent in the email. Lookups
+ * happen by hash so a DB compromise never leaks active tokens. The invite
+ * is consumed at /set-password — the route creates the better-auth `user`
+ * row + `account` credential and the matching `user_profiles` extension.
+ */
+export const crmUserInvites = pgTable(
+  'crm_user_invites',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    email: text('email').notNull(),
+    name: text('name'),
+    tokenHash: text('token_hash').notNull(),
+    isSuperAdmin: boolean('is_super_admin').notNull().default(false),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    usedAt: timestamp('used_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('idx_crm_invites_token_hash').on(table.tokenHash),
+    index('idx_crm_invites_email').on(table.email),
+  ],
+);
+
+export type CrmUserInvite = typeof crmUserInvites.$inferSelect;
+export type NewCrmUserInvite = typeof crmUserInvites.$inferInsert;

src/lib/db/schema/index.ts

@@ -34,6 +34,13 @@ export * from './email';
 // Portal (client-portal auth)
 export * from './portal';
 
+// CRM admin invites (better-auth realm)
+export * from './crm-invites';
+
+// Residential (parallel domain — separate clients & interests for the
+// external residential team)
+export * from './residential';
+
 // Operations
 export * from './operations';
 

src/lib/db/schema/relations.ts

@@ -86,6 +86,7 @@ import {
   customFieldDefinitions,
   customFieldValues,
 } from './system';
+import { residentialClients, residentialInterests } from './residential';
 
 // ─── Ports ────────────────────────────────────────────────────────────────────
 
@@ -116,6 +117,8 @@ export const portsRelations = relations(ports, ({ many }) => ({
   savedViews: many(savedViews),
   userNotificationPreferences: many(userNotificationPreferences),
   customFieldDefinitions: many(customFieldDefinitions),
+  residentialClients: many(residentialClients),
+  residentialInterests: many(residentialInterests),
   berthMaintenanceLogs: many(berthMaintenanceLog),
   clientMergeLogs: many(clientMergeLog),
   clientRelationships: many(clientRelationships),
@@ -819,3 +822,24 @@ export const customFieldValuesRelations = relations(customFieldValues, ({ one })
     references: [customFieldDefinitions.id],
   }),
 }));
+
+// ─── Residential ──────────────────────────────────────────────────────────────
+
+export const residentialClientsRelations = relations(residentialClients, ({ one, many }) => ({
+  port: one(ports, {
+    fields: [residentialClients.portId],
+    references: [ports.id],
+  }),
+  interests: many(residentialInterests),
+}));
+
+export const residentialInterestsRelations = relations(residentialInterests, ({ one }) => ({
+  port: one(ports, {
+    fields: [residentialInterests.portId],
+    references: [ports.id],
+  }),
+  client: one(residentialClients, {
+    fields: [residentialInterests.residentialClientId],
+    references: [residentialClients.id],
+  }),
+}));

src/lib/db/schema/residential.ts

@@ -0,0 +1,94 @@
+import { pgTable, text, timestamp, index } from 'drizzle-orm/pg-core';
+
+import { ports } from './ports';
+
+/**
+ * Residential clients — physically separated from `clients` because the
+ * residential side is handled by an external team that should never see
+ * marina-side data, and vice versa. The two domains share a port but no
+ * tables, so the access boundary is enforced at the schema level.
+ */
+export const residentialClients = pgTable(
+  'residential_clients',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    portId: text('port_id')
+      .notNull()
+      .references(() => ports.id),
+    fullName: text('full_name').notNull(),
+    email: text('email'),
+    phone: text('phone'),
+    placeOfResidence: text('place_of_residence'),
+    preferredContactMethod: text('preferred_contact_method'), // email | phone
+    /**
+     * Lifecycle: prospect | active | inactive. Distinct from
+     * pipeline_stage on residential_interests (which is per-inquiry).
+     */
+    status: text('status').notNull().default('prospect'),
+    source: text('source'), // website | manual | referral | broker
+    notes: text('notes'),
+    archivedAt: timestamp('archived_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index('idx_residential_clients_port').on(table.portId),
+    index('idx_residential_clients_email').on(table.email),
+    index('idx_residential_clients_archived').on(table.portId, table.archivedAt),
+  ],
+);
+
+/**
+ * Residential interests — one per inquiry/lead. A residential_client can
+ * have multiple interests over time (e.g. inquired about a unit in 2025,
+ * came back about a different unit in 2026).
+ *
+ * Pipeline stages: new | contacted | viewing_scheduled | offer_made |
+ * offer_accepted | closed_won | closed_lost.
+ */
+export const residentialInterests = pgTable(
+  'residential_interests',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    portId: text('port_id')
+      .notNull()
+      .references(() => ports.id),
+    residentialClientId: text('residential_client_id')
+      .notNull()
+      .references(() => residentialClients.id, { onDelete: 'cascade' }),
+    pipelineStage: text('pipeline_stage').notNull().default('new'),
+    source: text('source'), // website | manual | referral | broker
+    notes: text('notes'),
+    /**
+     * Free-text capture of unit-type / size / floor / budget preferences —
+     * residential leads are exploratory and the external team uses notes
+     * heavily. Schema can grow into structured columns later if needed.
+     */
+    preferences: text('preferences'),
+    /**
+     * better-auth user id of the residential team member working this lead.
+     */
+    assignedTo: text('assigned_to'),
+    dateFirstContact: timestamp('date_first_contact', { withTimezone: true }),
+    dateLastContact: timestamp('date_last_contact', { withTimezone: true }),
+    archivedAt: timestamp('archived_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index('idx_residential_interests_port').on(table.portId),
+    index('idx_residential_interests_client').on(table.residentialClientId),
+    index('idx_residential_interests_stage').on(table.portId, table.pipelineStage),
+    index('idx_residential_interests_assigned').on(table.assignedTo),
+    index('idx_residential_interests_archived').on(table.portId, table.archivedAt),
+  ],
+);
+
+export type ResidentialClient = typeof residentialClients.$inferSelect;
+export type NewResidentialClient = typeof residentialClients.$inferInsert;
+export type ResidentialInterest = typeof residentialInterests.$inferSelect;
+export type NewResidentialInterest = typeof residentialInterests.$inferInsert;

src/lib/db/schema/users.ts

@@ -118,6 +118,19 @@ export type RolePermissions = {
     manage_tags: boolean;
     system_backup: boolean;
   };
+  residential_clients: {
+    view: boolean;
+    create: boolean;
+    edit: boolean;
+    delete: boolean;
+  };
+  residential_interests: {
+    view: boolean;
+    create: boolean;
+    edit: boolean;
+    delete: boolean;
+    change_stage: boolean;
+  };
 };
 
 export type UserPreferences = {
@@ -251,6 +264,13 @@ export const userPortRoles = pgTable(
     roleId: text('role_id')
       .notNull()
       .references(() => roles.id, { onDelete: 'cascade' }),
+    /**
+     * Per-user per-port toggle that grants full residential domain access
+     * (residential_clients.* and residential_interests.*) on top of the
+     * user's primary role. Lets admins flip residential access for sales
+     * staff individually without minting a second role.
+     */
+    residentialAccess: boolean('residential_access').notNull().default(false),
     assignedBy: text('assigned_by'), // user ID of who assigned this
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
   },

src/lib/db/seed.ts

@@ -91,6 +91,14 @@ const ALL_PERMISSIONS: 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,
+  },
 };
 
 const DIRECTOR_PERMISSIONS: RolePermissions = {
@@ -157,6 +165,14 @@ const DIRECTOR_PERMISSIONS: 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,
+  },
 };
 
 const SALES_MANAGER_PERMISSIONS: RolePermissions = {
@@ -223,6 +239,14 @@ const SALES_MANAGER_PERMISSIONS: RolePermissions = {
     manage_tags: true,
     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,
+  },
 };
 
 const SALES_AGENT_PERMISSIONS: RolePermissions = {
@@ -289,6 +313,14 @@ const SALES_AGENT_PERMISSIONS: RolePermissions = {
     manage_tags: true,
     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,
+  },
 };
 
 const VIEWER_PERMISSIONS: RolePermissions = {
@@ -355,6 +387,14 @@ const VIEWER_PERMISSIONS: 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,
+  },
 };
 
 // ─── Port Definitions ────────────────────────────────────────────────────────