feat: autonomous backlog push — admin UX overhaul + storage parity + residential parity + Documenso Phase 1

Massive multi-area push driven by docs/admin-ux-backlog.md. Every byte
path now goes through getStorageBackend() so signed EOIs, contracts,
brochures, berth PDFs, files, avatars, branding logos, and DB backups
all work identically on S3 and filesystem backends.

USER SETTINGS (rebuild)
  - Country + Timezone selectors with cross-defaulting
  - Browser-detected timezone banner ("Looks like you're in Europe/Paris…")
  - Email change with verification flow (user_email_changes table,
    OLD-address cancel link + NEW-address confirm link)
    + EMAIL_CHANGE_INSTANT=true dev shortcut
  - Password reset triggered via better-auth requestPasswordReset
  - Profile photo upload + crop (square 256×256) via shared
    <ImageCropperDialog> + /api/v1/me/avatar

BRANDING
  - Shared <ImageCropperDialog> using react-easy-crop
  - Logo upload + crop in /admin/branding (writes via
    /api/v1/admin/settings/image -> storage backend)
  - Email header/footer HTML defaults injectable via "Insert default"
  - SettingsFormCard new field types: timezone (combobox), image-upload

STORAGE ADMIN OVERHAUL
  - S3 config form FIRST, swap action SECOND
  - Test connection before any switch
  - Two-button switch: "Switch + migrate" vs "Switch only" with
    warning modals
  - runMigration() honours skipMigration flag
  - /api/ready + system-monitoring health check use the active
    storage backend instead of always probing MinIO
  - Filesystem backend already had full feature parity — verified

BACKUP MANAGEMENT (real)
  - New backup_jobs table (id / status / trigger / size / storage_path)
  - runBackup() service spawns pg_dump --format=custom, streams to
    active storage backend via getStorageBackend().put()
  - /admin/backup page: trigger, history, download .dump for restore
  - Super-admin gated

AI ADMIN PANEL
  - /admin/ai consolidates master switch + monthly token cap +
    provider credentials
  - Per-feature settings (OCR, berth-PDF parser, recommender)
    linked from the same page

ONBOARDING WIZARD
  - /admin/onboarding now real with auto-checked steps
  - Reads each setting key + lists endpoint (roles/users/tags) to
    decide completion
  - Manual checkboxes for steps without an auto-detect signal
  - Progress bar + Mark done/Mark incomplete buttons
  - State persisted in system_settings.onboarding_manual_status

RESIDENTIAL PARITY (full)
  - New residential_client_notes + residential_interest_notes tables
    (mirror marina-side shape)
  - Polymorphic notes.service.ts extended (verifyParent, listForEntity,
    create, update, delete) for residential_clients/_interests
  - <NotesList> component accepts the new entity types
  - 4 new note endpoints (GET/POST/PATCH/DELETE for clients + interests)
  - 2 new activity endpoints (residential clients + interests)
  - residential-client-tabs.tsx + residential-interest-tabs.tsx use
    DetailLayout (Overview / Interests / Notes / Activity)
  - residential-client-detail-header.tsx mirrors marina-side strip
  - useBreadcrumbHint wired into both detail components
  - Configurable Assigned-to dropdown (residential_interests.view perm)

CONFIGURABLE RESIDENTIAL STAGES
  - residential-stages.service.ts with list / save / orphan-check
  - /api/v1/residential/stages GET/PUT
  - /admin/residential-stages admin UI with reassign-on-remove modal
  - Validators relaxed from z.enum to z.string

DOCUMENSO PHASE 1
  - Schema: document_signers.invited_at / opened_at /
    last_reminder_sent_at / signing_token (+ idx_ds_signing_token)
  - Schema: documents.completion_cc_emails (text[]) +
    auto_reminder_interval_days (int)
  - transformSigningUrl() now maps SignerRole -> URL segment via
    ROLE_TO_URL_SEGMENT (approver->cc, witness->witness) — fixes
    Risk #5 where approver invites landed on /sign/error
  - POST /api/v1/documents/[id]/send-invitation with auto-pick of
    next pending signer
  - Per-port settings: documenso_developer_label / _approver_label
    + documenso_developer_user_id / _approver_user_id (Phase 7
    Project Director RBAC binding fields)

ADMIN UX RAPID-FIRE
  - Sidebar collapse removed (always-expanded design)
  - Audit log: input sizes (h-9), date pickers w-44, action cell
    sub-label so single-row entries aren't blank
  - Sales email config: token list <details> + tooltips on
    threshold + body fields
  - Custom Settings card: long-form description
  - Reminder digest timezone uses TimezoneCombobox
  - Port form: currency dropdown (10 common currencies) + timezone
    combobox + brand color picker
  - Permissions count badge opens modal with granted/denied per
    resource
  - Role names display-normalized via prettifyRoleName
  - Tag form: native input type=color
  - Custom Fields page: amber heads-up about non-integration
  - Settings manager: select field type + fallthrough_policy as dropdown
  - Storage admin S3 fields ship as proper password + boolean

LIST PAGES
  - Residential client list: clickable email/phone (mailto/tel/wa.me)
  - Residential interests + Documents Hub search inputs sized h-9

CURRENCY API
  - scripts/test-currency-api.ts verifies live Frankfurter fetch
    -> DB upsert -> getRate -> convert. Inverse-rate drift <=0.001

TESTS
  - 1185/1185 vitest passing
  - tsc clean
  - eslint 0 errors (16 pre-existing warnings)

Note: WEBSITE_INTAKE_SECRET added to .env.example but committed
separately due to pre-commit hook policy on .env* files.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/api/ready/route.ts

@@ -3,15 +3,14 @@ import { sql } from 'drizzle-orm';
 
 import { db } from '@/lib/db';
 import { redis } from '@/lib/redis';
-import { minioClient } from '@/lib/minio';
-import { env } from '@/lib/env';
+import { getStorageBackend } from '@/lib/storage';
 
 type CheckStatus = 'ok' | 'error';
 
 interface ReadyChecks {
   postgres: CheckStatus;
   redis: CheckStatus;
-  minio: CheckStatus;
+  storage: CheckStatus;
 }
 
 interface ReadyResponse {
@@ -21,7 +20,7 @@ interface ReadyResponse {
 }
 
 /**
- * Readiness probe - verifies that every backing service this process
+ * Readiness probe — verifies that every backing service this process
  * needs to serve traffic is reachable. A 503 should drop the pod from the
  * load balancer until the next probe succeeds; it should not trigger a
  * pod restart (that's what `/api/health` is for).
@@ -29,7 +28,9 @@ interface ReadyResponse {
  * Checks:
  *   - postgres: `SELECT 1` against the primary
  *   - redis:    `PING`
- *   - minio:    `bucketExists(<configured-bucket>)`
+ *   - storage:  HEAD on a sentinel key via the active storage backend
+ *               (S3 or filesystem). Health-checks whichever backend
+ *               this port is configured for, not always MinIO.
  *
  * Documenso + SMTP are intentionally not probed here: they're optional
  * integrations, and each tenant configures its own credentials. A
@@ -40,7 +41,7 @@ export async function GET(): Promise<NextResponse<ReadyResponse>> {
   const checks: ReadyChecks = {
     postgres: 'error',
     redis: 'error',
-    minio: 'error',
+    storage: 'error',
   };
 
   await Promise.allSettled([
@@ -62,14 +63,17 @@ export async function GET(): Promise<NextResponse<ReadyResponse>> {
         checks.redis = 'error';
       }),
 
-    minioClient
-      .bucketExists(env.MINIO_BUCKET)
-      .then(() => {
-        checks.minio = 'ok';
-      })
-      .catch(() => {
-        checks.minio = 'error';
-      }),
+    (async () => {
+      try {
+        const backend = await getStorageBackend();
+        // head() returns null for a missing object (both backends);
+        // the connection itself succeeding is what counts.
+        await backend.head('__health_probe__');
+        checks.storage = 'ok';
+      } catch {
+        checks.storage = 'error';
+      }
+    })(),
   ]);
 
   const allReady = Object.values(checks).every((s) => s === 'ok');

src/app/api/v1/admin/backup/[id]/download/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from 'next/server';
+
+import { requireSuperAdmin, withAuth } from '@/lib/api/helpers';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+import { getBackupDownloadUrl } from '@/lib/services/backup.service';
+
+export const GET = withAuth(async (_req, ctx, params) => {
+  try {
+    requireSuperAdmin(ctx, 'admin.backup.download');
+    const id = params.id;
+    if (!id) throw new NotFoundError('Backup');
+    const url = await getBackupDownloadUrl(id);
+    if (!url) throw new NotFoundError('Backup');
+    return NextResponse.json({ data: { url } });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/backup/route.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server';
+
+import { requireSuperAdmin, withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { listBackupJobs, runBackup } from '@/lib/services/backup.service';
+
+export const runtime = 'nodejs';
+
+export const GET = withAuth(async (_req, ctx) => {
+  try {
+    requireSuperAdmin(ctx, 'admin.backup.list');
+    const jobs = await listBackupJobs();
+    return NextResponse.json({ data: jobs });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+
+/** Trigger a fresh manual backup. Super-admin only. */
+export const POST = withAuth(async (_req, ctx) => {
+  try {
+    requireSuperAdmin(ctx, 'admin.backup.run');
+    const result = await runBackup({ trigger: 'manual', triggeredBy: ctx.userId });
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/admin/settings/image/route.ts

@@ -0,0 +1,74 @@
+import { NextResponse } from 'next/server';
+import { eq } from 'drizzle-orm';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { uploadFile } from '@/lib/services/files';
+import { errorResponse, ValidationError } from '@/lib/errors';
+import { env } from '@/lib/env';
+
+const MAX_BYTES = 5 * 1024 * 1024;
+
+/**
+ * Image upload for branding settings (logo, email banner, etc).
+ * Accepts a multipart `file` (cropped JPEG/PNG/WebP from the
+ * ImageCropperDialog) and returns a stable URL that the settings
+ * form stores as a `string` value on `system_settings`.
+ *
+ * The URL points at `/api/v1/files/<id>/preview` so swapping the
+ * storage backend (S3 ↔ filesystem) carries the asset transparently.
+ */
+export const POST = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const formData = await req.formData();
+      const fileEntry = formData.get('file');
+      if (!(fileEntry instanceof File)) {
+        throw new ValidationError('Missing `file` part');
+      }
+      if (fileEntry.size === 0) {
+        throw new ValidationError('Empty file');
+      }
+      if (fileEntry.size > MAX_BYTES) {
+        throw new ValidationError('Image exceeds 5 MB');
+      }
+
+      const port = ctx.portId
+        ? await db.query.ports.findFirst({ where: eq(ports.id, ctx.portId) })
+        : null;
+      if (!port) throw new ValidationError('No active port');
+
+      const buffer = Buffer.from(await fileEntry.arrayBuffer());
+      const record = await uploadFile(
+        port.id,
+        port.slug,
+        {
+          buffer,
+          originalName: fileEntry.name || 'branding.jpg',
+          mimeType: fileEntry.type || 'image/jpeg',
+          size: fileEntry.size,
+        },
+        {
+          filename: `branding-${Date.now()}.jpg`,
+          category: 'branding',
+          entityType: 'port',
+          entityId: port.id,
+        },
+        {
+          userId: ctx.userId,
+          portId: port.id,
+          ipAddress: ctx.ipAddress,
+          userAgent: ctx.userAgent,
+        },
+      );
+
+      const baseUrl = env.APP_URL.replace(/\/+$/, '');
+      const url = `${baseUrl}/api/v1/files/${record.id}/preview`;
+
+      return NextResponse.json({ data: { fileId: record.id, url } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/storage/migrate/route.ts

@@ -19,6 +19,7 @@ const schema = z.object({
   from: z.enum(['s3', 'filesystem']),
   to: z.enum(['s3', 'filesystem']),
   dryRun: z.boolean().default(false),
+  skipMigration: z.boolean().optional(),
 });
 
 export const runtime = 'nodejs';

src/app/api/v1/documents/[id]/send-invitation/route.ts

@@ -0,0 +1,92 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { and, asc, eq } from 'drizzle-orm';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { db } from '@/lib/db';
+import { documents, documentSigners } from '@/lib/db/schema/documents';
+import { ports } from '@/lib/db/schema/ports';
+import {
+  sendSigningInvitation,
+  type SignerRole,
+} from '@/lib/services/document-signing-emails.service';
+import { getPortDocumensoConfig } from '@/lib/services/port-config';
+import { errorResponse, NotFoundError, ValidationError } from '@/lib/errors';
+
+const bodySchema = z.object({
+  /** Optional — defaults to the next pending signer in signing-order. */
+  recipientId: z.string().optional(),
+});
+
+const DOC_TYPE_LABEL: Record<
+  string,
+  'Expression of Interest' | 'Sales Contract' | 'Reservation Agreement'
+> = {
+  eoi: 'Expression of Interest',
+  contract: 'Sales Contract',
+  reservation_agreement: 'Reservation Agreement',
+};
+
+/**
+ * Send a branded signing-invitation email to a specific recipient
+ * (defaults to the next-pending signer in signing-order). Used by:
+ *   - The auto-send path when port `eoi_send_mode = 'auto'`
+ *   - The "Send invitation" button in the EOI/Contract tab when
+ *     `eoi_send_mode = 'manual'`
+ *   - The cascading-email logic on DOCUMENT_SIGNED webhooks
+ */
+export const POST = withAuth(
+  withPermission('documents', 'send_for_signing', async (req, ctx, params) => {
+    try {
+      const documentId = params.id;
+      if (!documentId) throw new NotFoundError('Document');
+      const body = await parseBody(req, bodySchema);
+
+      const doc = await db.query.documents.findFirst({
+        where: and(eq(documents.id, documentId), eq(documents.portId, ctx.portId)),
+      });
+      if (!doc) throw new NotFoundError('Document');
+
+      const signers = await db
+        .select()
+        .from(documentSigners)
+        .where(eq(documentSigners.documentId, documentId))
+        .orderBy(asc(documentSigners.signingOrder));
+
+      const target = body.recipientId
+        ? signers.find((s) => s.id === body.recipientId)
+        : signers.find((s) => s.status === 'pending');
+      if (!target) {
+        throw new ValidationError('No pending signer found to invite');
+      }
+      if (!target.signingUrl) {
+        throw new ValidationError(
+          'Signer has no Documenso URL yet — generate or send the document first',
+        );
+      }
+
+      const port = await db.query.ports.findFirst({ where: eq(ports.id, ctx.portId) });
+      const docCfg = await getPortDocumensoConfig(ctx.portId);
+
+      await sendSigningInvitation({
+        portId: ctx.portId,
+        portName: port?.name ?? 'Port Nimara',
+        recipient: { name: target.signerName, email: target.signerEmail },
+        documensoSigningUrl: target.signingUrl,
+        documentLabel: DOC_TYPE_LABEL[doc.documentType] ?? 'Expression of Interest',
+        signerRole: (target.signerRole as SignerRole) ?? 'client',
+        senderName: docCfg.developerName ?? null,
+      });
+
+      await db
+        .update(documentSigners)
+        .set({ invitedAt: new Date() })
+        .where(eq(documentSigners.id, target.id));
+
+      return NextResponse.json({ data: { recipientId: target.id, sent: true } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/me/avatar/route.ts

@@ -0,0 +1,79 @@
+import { NextResponse } from 'next/server';
+import { eq } from 'drizzle-orm';
+
+import { withAuth } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { userProfiles } from '@/lib/db/schema/users';
+import { uploadFile } from '@/lib/services/files';
+import { errorResponse, ValidationError } from '@/lib/errors';
+
+const MAX_AVATAR_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Profile-photo upload. Accepts a multipart `file` (cropped JPEG/PNG
+ * from the ImageCropperDialog), persists it via the polymorphic files
+ * table (so an S3↔filesystem swap carries it correctly), and writes
+ * the file id into `user_profiles.avatar_file_id`.
+ *
+ * Files are scoped to the user's CURRENT port — the rep can't end up
+ * with an avatar that's only visible from one port. (Avatars render
+ * via the GET handler below, which presigns by id regardless of port.)
+ */
+export const POST = withAuth(async (req, ctx) => {
+  try {
+    const formData = await req.formData();
+    const fileEntry = formData.get('file');
+    if (!(fileEntry instanceof File)) {
+      throw new ValidationError('Missing `file` part');
+    }
+    if (fileEntry.size === 0) {
+      throw new ValidationError('Empty file');
+    }
+    if (fileEntry.size > MAX_AVATAR_BYTES) {
+      throw new ValidationError('Avatar exceeds 2 MB');
+    }
+
+    // Resolve the port slug for the storage path. Super-admins without
+    // an active port fall through to a synthetic 'global' bucket.
+    const port = ctx.portId
+      ? await db.query.ports.findFirst({ where: eq(ports.id, ctx.portId) })
+      : null;
+    const portSlug = port?.slug ?? 'global';
+    const portId = ctx.portId || port?.id || '';
+    if (!portId) throw new ValidationError('No active port');
+
+    const buffer = Buffer.from(await fileEntry.arrayBuffer());
+    const record = await uploadFile(
+      portId,
+      portSlug,
+      {
+        buffer,
+        originalName: fileEntry.name || 'avatar.jpg',
+        mimeType: fileEntry.type || 'image/jpeg',
+        size: fileEntry.size,
+      },
+      {
+        filename: `avatar-${ctx.userId}.jpg`,
+        category: 'avatar',
+        entityType: 'user',
+        entityId: ctx.userId,
+      },
+      {
+        userId: ctx.userId,
+        portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      },
+    );
+
+    await db
+      .update(userProfiles)
+      .set({ avatarFileId: record.id, updatedAt: new Date() })
+      .where(eq(userProfiles.userId, ctx.userId));
+
+    return NextResponse.json({ data: { avatarFileId: record.id } });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/me/email/cancel/[token]/route.ts

@@ -0,0 +1,54 @@
+import { NextResponse } from 'next/server';
+import { and, eq, isNull } from 'drizzle-orm';
+import crypto from 'node:crypto';
+
+import { db } from '@/lib/db';
+import { userEmailChanges } from '@/lib/db/schema/users';
+import { createAuditLog } from '@/lib/audit';
+import { errorResponse, ValidationError } from '@/lib/errors';
+import { env } from '@/lib/env';
+
+/**
+ * Cancel a pending email-change. Linked from the email sent to the
+ * OLD address as a safety net for "I didn't ask for this" reports.
+ */
+export async function GET(
+  _req: Request,
+  context: { params: Promise<{ token: string }> },
+): Promise<Response> {
+  try {
+    const { token } = await context.params;
+    if (!token) throw new ValidationError('Missing token');
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
+
+    const pending = await db.query.userEmailChanges.findFirst({
+      where: and(
+        eq(userEmailChanges.confirmTokenHash, tokenHash),
+        isNull(userEmailChanges.appliedAt),
+        isNull(userEmailChanges.cancelledAt),
+      ),
+    });
+    if (!pending) throw new ValidationError('Token is invalid or already used');
+
+    await db
+      .update(userEmailChanges)
+      .set({ cancelledAt: new Date() })
+      .where(eq(userEmailChanges.id, pending.id));
+
+    void createAuditLog({
+      userId: pending.userId,
+      portId: null,
+      action: 'update',
+      entityType: 'user_email_change',
+      entityId: pending.id,
+      newValue: { newEmail: pending.newEmail },
+      metadata: { type: 'email_change_cancelled' },
+      severity: 'warning',
+    });
+
+    const baseUrl = env.APP_URL.replace(/\/+$/, '');
+    return NextResponse.redirect(`${baseUrl}/settings?emailChange=cancelled`);
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

src/app/api/v1/me/email/confirm/[token]/route.ts

@@ -0,0 +1,75 @@
+import { NextResponse } from 'next/server';
+import { and, eq, isNull } from 'drizzle-orm';
+import crypto from 'node:crypto';
+
+import { db } from '@/lib/db';
+import { user, userEmailChanges } from '@/lib/db/schema/users';
+import { createAuditLog } from '@/lib/audit';
+import { errorResponse, ValidationError } from '@/lib/errors';
+import { env } from '@/lib/env';
+
+/**
+ * Public confirmation endpoint — clicked from the email sent to the
+ * NEW address. Applies the email change atomically and redirects the
+ * user back to /settings with a success flag.
+ *
+ * No auth wrapper because the email recipient may not be signed in
+ * (e.g. they clicked from another device). The token IS the proof.
+ */
+export async function GET(
+  _req: Request,
+  context: { params: Promise<{ token: string }> },
+): Promise<Response> {
+  try {
+    const { token } = await context.params;
+    if (!token) throw new ValidationError('Missing token');
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
+
+    const pending = await db.query.userEmailChanges.findFirst({
+      where: and(
+        eq(userEmailChanges.confirmTokenHash, tokenHash),
+        isNull(userEmailChanges.appliedAt),
+        isNull(userEmailChanges.cancelledAt),
+      ),
+    });
+    if (!pending) throw new ValidationError('Token is invalid or already used');
+    if (pending.expiresAt.getTime() < Date.now()) {
+      throw new ValidationError('Token has expired');
+    }
+
+    // Re-check uniqueness right before the swap so a race with another
+    // signup doesn't ship two accounts to the same email.
+    const conflict = await db.query.user.findFirst({
+      where: eq(user.email, pending.newEmail),
+    });
+    if (conflict && conflict.id !== pending.userId) {
+      throw new ValidationError('That email is already in use by another account');
+    }
+
+    await db
+      .update(user)
+      .set({ email: pending.newEmail, emailVerified: true, updatedAt: new Date() })
+      .where(eq(user.id, pending.userId));
+
+    await db
+      .update(userEmailChanges)
+      .set({ appliedAt: new Date() })
+      .where(eq(userEmailChanges.id, pending.id));
+
+    void createAuditLog({
+      userId: pending.userId,
+      portId: null,
+      action: 'update',
+      entityType: 'user',
+      entityId: pending.userId,
+      oldValue: { email: pending.oldEmail },
+      newValue: { email: pending.newEmail },
+      metadata: { type: 'email_change_confirmed', changeId: pending.id },
+    });
+
+    const baseUrl = env.APP_URL.replace(/\/+$/, '');
+    return NextResponse.redirect(`${baseUrl}/settings?emailChange=confirmed`);
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

src/app/api/v1/me/email/route.ts

@@ -0,0 +1,134 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { eq } from 'drizzle-orm';
+import crypto from 'node:crypto';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { db } from '@/lib/db';
+import { user, userEmailChanges } from '@/lib/db/schema/users';
+import { createAuditLog } from '@/lib/audit';
+import { ConflictError, errorResponse, ValidationError } from '@/lib/errors';
+import { env } from '@/lib/env';
+
+const updateEmailSchema = z.object({
+  email: z.string().email().toLowerCase(),
+});
+
+const VERIFY_TOKEN_TTL_MINUTES = 60;
+const REQUIRES_VERIFICATION = process.env.EMAIL_CHANGE_INSTANT !== 'true';
+
+/**
+ * Initiate an email-change for the signed-in user.
+ *
+ * Production flow (REQUIRES_VERIFICATION=true, default):
+ *   1. Create a user_email_changes row with sha256(token)
+ *   2. Email OLD address with a cancel link
+ *   3. Email NEW address with a confirm link
+ *   4. Change applies only when /api/v1/me/email/confirm/<token> is called
+ *
+ * Dev shortcut (set EMAIL_CHANGE_INSTANT=true):
+ *   - Updates user.email immediately, skipping the email round-trip.
+ *   - Useful for local testing where SMTP isn't wired.
+ */
+export const PATCH = withAuth(async (req, ctx) => {
+  try {
+    const { email } = await parseBody(req, updateEmailSchema);
+    if (email === ctx.user.email) {
+      return NextResponse.json({ ok: true, unchanged: true });
+    }
+
+    // Reject if another account already owns this address.
+    const conflict = await db.query.user.findFirst({ where: eq(user.email, email) });
+    if (conflict && conflict.id !== ctx.userId) {
+      throw new ConflictError('That email is already in use by another account');
+    }
+
+    if (!REQUIRES_VERIFICATION) {
+      // Instant change — dev only.
+      const [updated] = await db
+        .update(user)
+        .set({ email, emailVerified: false, updatedAt: new Date() })
+        .where(eq(user.id, ctx.userId))
+        .returning({ email: user.email });
+      if (!updated) throw new ValidationError('Failed to update email');
+      void createAuditLog({
+        userId: ctx.userId,
+        portId: ctx.portId || null,
+        action: 'update',
+        entityType: 'user',
+        entityId: ctx.userId,
+        oldValue: { email: ctx.user.email },
+        newValue: { email: updated.email },
+        metadata: { type: 'email_change_instant' },
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: { email: updated.email, instant: true } });
+    }
+
+    // Verification flow — generate a single-use token, hash it, persist.
+    const rawToken = crypto.randomBytes(32).toString('base64url');
+    const tokenHash = crypto.createHash('sha256').update(rawToken).digest('hex');
+    const expiresAt = new Date(Date.now() + VERIFY_TOKEN_TTL_MINUTES * 60 * 1000);
+
+    const [pending] = await db
+      .insert(userEmailChanges)
+      .values({
+        userId: ctx.userId,
+        oldEmail: ctx.user.email,
+        newEmail: email,
+        confirmTokenHash: tokenHash,
+        expiresAt,
+      })
+      .returning();
+    if (!pending) throw new ValidationError('Failed to create pending email-change row');
+
+    const baseUrl = env.APP_URL.replace(/\/+$/, '');
+    const confirmUrl = `${baseUrl}/api/v1/me/email/confirm/${rawToken}`;
+    const cancelUrl = `${baseUrl}/api/v1/me/email/cancel/${rawToken}`;
+
+    try {
+      const { sendEmail } = await import('@/lib/email');
+      await Promise.allSettled([
+        sendEmail(
+          email,
+          'Confirm your new Port Nimara CRM email address',
+          `<p>Hi,</p><p>You (or someone using your account) requested to change the sign-in email on your Port Nimara CRM account from <strong>${ctx.user.email}</strong> to <strong>${email}</strong>.</p><p><a href="${confirmUrl}">Click here to confirm this change</a> — the link expires in ${VERIFY_TOKEN_TTL_MINUTES} minutes.</p><p>If you didn't request this, ignore this email.</p>`,
+          undefined,
+          `Confirm new email: ${confirmUrl}`,
+        ),
+        sendEmail(
+          ctx.user.email,
+          'A change to your Port Nimara CRM email was requested',
+          `<p>Hi,</p><p>A change to your sign-in email was requested. If this wasn't you, <a href="${cancelUrl}">click here to cancel the change</a> immediately and consider rotating your password.</p>`,
+          undefined,
+          `Cancel email change: ${cancelUrl}`,
+        ),
+      ]);
+    } catch {
+      // Email send is best-effort; the row stays so the user can re-request.
+    }
+
+    void createAuditLog({
+      userId: ctx.userId,
+      portId: ctx.portId || null,
+      action: 'create',
+      entityType: 'user_email_change',
+      entityId: pending.id,
+      newValue: { newEmail: email },
+      metadata: { type: 'email_change_requested' },
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+
+    return NextResponse.json({
+      data: {
+        pendingChangeId: pending.id,
+        verificationSentTo: email,
+      },
+    });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/me/password-reset/route.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server';
+
+import { auth } from '@/lib/auth';
+import { withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+
+/**
+ * Self-service password reset for the signed-in CRM user. Calls
+ * better-auth's forgetPassword API server-side, which generates a
+ * one-time reset token and dispatches the email via the
+ * `sendResetPassword` callback configured in src/lib/auth/index.ts.
+ *
+ * The email always goes to the user's CURRENT account email — no way
+ * to redirect to a different inbox here, so the endpoint is safe even
+ * if a session is hijacked (the attacker can't move the reset email
+ * to themselves).
+ */
+export const POST = withAuth(async (_req, ctx) => {
+  try {
+    await auth.api.requestPasswordReset({
+      body: {
+        email: ctx.user.email,
+        redirectTo: '/reset-password',
+      },
+    });
+    return NextResponse.json({ ok: true });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/residential/assignable-users/route.ts

@@ -0,0 +1,49 @@
+import { NextResponse } from 'next/server';
+import { and, eq, or, sql } from 'drizzle-orm';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { roles, user, userPortRoles } from '@/lib/db/schema/users';
+import { errorResponse } from '@/lib/errors';
+
+/**
+ * Returns the set of users in the current port who can be assigned a
+ * residential interest. A user qualifies when ANY of their port-role
+ * grants either:
+ *   - role.permissions.residential_interests.view = true, OR
+ *   - role.permissions.residential_clients.view = true, OR
+ *   - the per-user `residentialAccess` toggle is set on this port
+ *
+ * Used by the residential-interest detail page's "Assigned to" picker.
+ * Returns minimal `{ id, name, email }` rows so the dropdown stays
+ * fast and the JSON payload doesn't leak more than the picker needs.
+ */
+export const GET = withAuth(
+  withPermission('residential_interests', 'view', async (_req, ctx) => {
+    try {
+      const rows = await db
+        .selectDistinct({
+          id: user.id,
+          name: user.name,
+          email: user.email,
+        })
+        .from(userPortRoles)
+        .innerJoin(roles, eq(roles.id, userPortRoles.roleId))
+        .innerJoin(user, eq(user.id, userPortRoles.userId))
+        .where(
+          and(
+            eq(userPortRoles.portId, ctx.portId),
+            or(
+              eq(userPortRoles.residentialAccess, true),
+              sql`${roles.permissions}->'residential_interests'->>'view' = 'true'`,
+              sql`${roles.permissions}->'residential_clients'->>'view' = 'true'`,
+            )!,
+          ),
+        )
+        .orderBy(user.name);
+      return NextResponse.json({ data: rows });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/clients/[id]/activity/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+import { eq, and } from 'drizzle-orm';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { residentialClients } from '@/lib/db/schema/residential';
+import { loadEntityActivity } from '@/lib/services/entity-activity.service';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+
+export const GET = withAuth(
+  withPermission('residential_clients', 'view', async (_req, ctx, params) => {
+    try {
+      const id = params.id;
+      if (!id) throw new NotFoundError('residential client');
+      const exists = await db
+        .select({ id: residentialClients.id })
+        .from(residentialClients)
+        .where(and(eq(residentialClients.id, id), eq(residentialClients.portId, ctx.portId)))
+        .limit(1);
+      if (exists.length === 0) throw new NotFoundError('residential client');
+      const data = await loadEntityActivity({
+        portId: ctx.portId,
+        entityType: 'residential_client',
+        entityId: id,
+      });
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/clients/[id]/notes/[noteId]/route.ts

@@ -0,0 +1,36 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { updateNoteSchema } from '@/lib/validators/notes';
+import * as notesService from '@/lib/services/notes.service';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+
+export const PATCH = withAuth(
+  withPermission('residential_clients', 'edit', async (req, ctx, params) => {
+    try {
+      const id = params.id;
+      const noteId = params.noteId;
+      if (!id || !noteId) throw new NotFoundError('Residential client note');
+      const body = await parseBody(req, updateNoteSchema);
+      const note = await notesService.update(ctx.portId, 'residential_clients', id, noteId, body);
+      return NextResponse.json({ data: note });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('residential_clients', 'edit', async (_req, ctx, params) => {
+    try {
+      const id = params.id;
+      const noteId = params.noteId;
+      if (!id || !noteId) throw new NotFoundError('Residential client note');
+      await notesService.deleteNote(ctx.portId, 'residential_clients', id, noteId);
+      return NextResponse.json({ ok: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/clients/[id]/notes/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { createNoteSchema } from '@/lib/validators/notes';
+import * as notesService from '@/lib/services/notes.service';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+
+export const GET = withAuth(
+  withPermission('residential_clients', 'view', async (_req, ctx, params) => {
+    try {
+      const id = params.id;
+      if (!id) throw new NotFoundError('Residential client');
+      const notes = await notesService.listForEntity(ctx.portId, 'residential_clients', id);
+      return NextResponse.json({ data: notes });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('residential_clients', 'edit', async (req, ctx, params) => {
+    try {
+      const id = params.id;
+      if (!id) throw new NotFoundError('Residential client');
+      const body = await parseBody(req, createNoteSchema);
+      const note = await notesService.create(
+        ctx.portId,
+        'residential_clients',
+        id,
+        ctx.userId,
+        body,
+      );
+      return NextResponse.json({ data: note }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/interests/[id]/activity/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+import { eq, and } from 'drizzle-orm';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { residentialInterests } from '@/lib/db/schema/residential';
+import { loadEntityActivity } from '@/lib/services/entity-activity.service';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+
+export const GET = withAuth(
+  withPermission('residential_interests', 'view', async (_req, ctx, params) => {
+    try {
+      const id = params.id;
+      if (!id) throw new NotFoundError('residential interest');
+      const exists = await db
+        .select({ id: residentialInterests.id })
+        .from(residentialInterests)
+        .where(and(eq(residentialInterests.id, id), eq(residentialInterests.portId, ctx.portId)))
+        .limit(1);
+      if (exists.length === 0) throw new NotFoundError('residential interest');
+      const data = await loadEntityActivity({
+        portId: ctx.portId,
+        entityType: 'residential_interest',
+        entityId: id,
+      });
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/interests/[id]/notes/[noteId]/route.ts

@@ -0,0 +1,36 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { updateNoteSchema } from '@/lib/validators/notes';
+import * as notesService from '@/lib/services/notes.service';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+
+export const PATCH = withAuth(
+  withPermission('residential_interests', 'edit', async (req, ctx, params) => {
+    try {
+      const id = params.id;
+      const noteId = params.noteId;
+      if (!id || !noteId) throw new NotFoundError('Residential interest note');
+      const body = await parseBody(req, updateNoteSchema);
+      const note = await notesService.update(ctx.portId, 'residential_interests', id, noteId, body);
+      return NextResponse.json({ data: note });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('residential_interests', 'edit', async (_req, ctx, params) => {
+    try {
+      const id = params.id;
+      const noteId = params.noteId;
+      if (!id || !noteId) throw new NotFoundError('Residential interest note');
+      await notesService.deleteNote(ctx.portId, 'residential_interests', id, noteId);
+      return NextResponse.json({ ok: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/interests/[id]/notes/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { createNoteSchema } from '@/lib/validators/notes';
+import * as notesService from '@/lib/services/notes.service';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+
+export const GET = withAuth(
+  withPermission('residential_interests', 'view', async (_req, ctx, params) => {
+    try {
+      const id = params.id;
+      if (!id) throw new NotFoundError('Residential interest');
+      const notes = await notesService.listForEntity(ctx.portId, 'residential_interests', id);
+      return NextResponse.json({ data: notes });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('residential_interests', 'edit', async (req, ctx, params) => {
+    try {
+      const id = params.id;
+      if (!id) throw new NotFoundError('Residential interest');
+      const body = await parseBody(req, createNoteSchema);
+      const note = await notesService.create(
+        ctx.portId,
+        'residential_interests',
+        id,
+        ctx.userId,
+        body,
+      );
+      return NextResponse.json({ data: note }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/stages/route.ts

@@ -0,0 +1,68 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import {
+  findOrphanInterests,
+  listStages,
+  saveStages,
+  type ResidentialStage,
+} from '@/lib/services/residential-stages.service';
+import { errorResponse } from '@/lib/errors';
+
+export const GET = withAuth(
+  withPermission('residential_interests', 'view', async (_req, ctx) => {
+    try {
+      const stages = await listStages(ctx.portId);
+      const orphans = await findOrphanInterests(
+        ctx.portId,
+        stages.map((s) => s.id),
+      );
+      return NextResponse.json({ data: { stages, orphans } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+const stageSchema: z.ZodType<ResidentialStage> = z.object({
+  id: z
+    .string()
+    .min(1)
+    .max(50)
+    .regex(/^[a-z0-9_]+$/, 'lowercase letters, digits, underscore only'),
+  label: z.string().min(1).max(80),
+  terminal: z.enum(['won', 'lost']).nullable(),
+});
+
+const putSchema = z.object({
+  stages: z.array(stageSchema).min(1),
+  reassignments: z.record(z.string(), z.string()).optional(),
+  force: z.boolean().optional(),
+});
+
+export const PUT = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, putSchema);
+      await saveStages(
+        {
+          portId: ctx.portId,
+          stages: body.stages,
+          reassignments: body.reassignments,
+          force: body.force,
+        },
+        {
+          userId: ctx.userId,
+          portId: ctx.portId,
+          ipAddress: ctx.ipAddress,
+          userAgent: ctx.userAgent,
+        },
+      );
+      return NextResponse.json({ ok: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);