feat(berths): click-to-change status from the list (chip → reason modal)

Adds BerthStatusQuickEdit — wraps the status chip on the berths list (card +
table) in a click target that opens a compact change-status dialog: status
dropdown + required reason (quick-pick chips) + optional interest link when
moving to under_offer/sold. Reuses the existing PATCH /api/v1/berths/[id]/status
endpoint + validator + audit (same capability the detail page already had).
Gated by berths.edit (non-editors see a plain chip); stops click propagation
so it doesn't also navigate into the berth.

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

.claude/scheduled_tasks.lock

@@ -1 +0,0 @@
-{"sessionId":"fd05cbd7-d695-4a70-9223-4b25f3369829","pid":88534,"acquiredAt":1776866083076}

.dockerignore

@@ -0,0 +1,69 @@
+# Build context exclusions — keep the image small AND prevent secrets
+# from accidentally leaking into a layer.
+# The audit caught that the previous absence of this file shipped a
+# 7.6 GB build context, with .env files reachable via `COPY . .`.
+
+# Version control
+.git
+.gitignore
+.gitattributes
+
+# Local env / secrets
+.env
+.env.*
+!.env.example
+
+# Node / pnpm
+node_modules
+.pnpm-store
+.pnpm-debug.log
+npm-debug.log
+yarn-debug.log
+yarn-error.log
+
+# Next.js build artifacts (regenerated inside the image)
+.next
+out
+
+# Tooling caches
+.cache
+.turbo
+.eslintcache
+.vercel
+.swc
+
+# OS noise
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode
+.idea
+*.swp
+
+# Testing / coverage
+coverage
+.nyc_output
+test-results
+playwright-report
+tests/e2e/visual/snapshots.spec.ts-snapshots/*.png
+playwright/.cache
+
+# Project artefacts that don't belong in a runtime image
+.claude
+.husky
+docs
+AGENTS.md
+AUDIT-*.md
+SECURITY-GUIDELINES.md
+PROMPTS-*.md
+README.md
+*.log
+*.tgz
+
+# Generated / scratch
+.serena
+.superpowers
+.remember
+.audit-cache
+.specstory

.env.dev.template

@@ -0,0 +1,58 @@
+# ─── Port Nimara CRM — DEV environment template ──────────────────────────────
+#
+# Copy to `.env` for local development. Values match the docker-compose.dev.yml
+# defaults (Postgres on :5434, Redis on :6379, MinIO on :9000).
+#
+# Integration credentials (Documenso, OpenAI, SMTP, S3, etc.) belong in the
+# admin UI after first login — see /admin/<integration>. The fallbacks at the
+# bottom are commented out by default to make the admin path obvious.
+
+# ─── Required (boot-time) ────────────────────────────────────────────────────
+
+DATABASE_URL=postgresql://crm:changeme@localhost:5434/port_nimara_crm
+REDIS_URL=redis://:changeme@localhost:6379
+
+BETTER_AUTH_SECRET=dev-secret-please-change-32-chars-minimum-12345678
+BETTER_AUTH_URL=http://localhost:3000
+CSRF_SECRET=dev-csrf-secret-please-change-32-chars-minimum-12345
+
+# Generated once for local dev. Production uses a different rotated key.
+EMAIL_CREDENTIAL_KEY=0000000000000000000000000000000000000000000000000000000000000000
+
+APP_URL=http://localhost:3000
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+NODE_ENV=development
+LOG_LEVEL=debug
+
+# ─── Dev-only safety net ─────────────────────────────────────────────────────
+
+# When set, every outbound email is rerouted to this address.
+# Configure to YOUR personal email so seeded fake-client sends don't escape.
+# EMAIL_REDIRECT_TO=
+
+# Skip env validation (used by Docker build only).
+# SKIP_ENV_VALIDATION=
+
+# ─── Optional integration env fallbacks (admin UI is canonical) ──────────────
+# Uncomment + set ONLY if you want to bootstrap a port via env. Otherwise
+# configure each integration via /admin/<integration> after first login.
+
+# DOCUMENSO_API_URL=https://documenso.dev.example
+# DOCUMENSO_API_KEY=
+# DOCUMENSO_API_VERSION=v2
+# DOCUMENSO_WEBHOOK_SECRET=
+
+# SMTP_HOST=smtp.example
+# SMTP_PORT=587
+
+# OPENAI_API_KEY=
+
+# Local MinIO (set if NOT using the admin UI to configure storage)
+# MINIO_ENDPOINT=localhost
+# MINIO_PORT=9000
+# MINIO_ACCESS_KEY=minioadmin
+# MINIO_SECRET_KEY=minioadmin
+# MINIO_BUCKET=crm-files
+# MINIO_USE_SSL=false
+# MINIO_AUTO_CREATE_BUCKET=true

.env.example

@@ -1,46 +1,115 @@
+# ─── Port Nimara CRM env template ─────────────────────────────────────────────
+#
+# This file documents every env var the CRM understands. Most integration
+# settings have been moved into the per-port admin UI (see
+# `docs/superpowers/specs/2026-05-15-env-to-admin-migration-design.md`):
+#
+#   /admin/documenso     — Documenso API URL, key, version, webhook secret,
+#                          signers, templates
+#   /admin/ai            — OpenAI API key + model + master switch
+#   /admin/email         — SMTP host/port/user/pass, from-address
+#   /admin/storage       — S3/MinIO endpoint, bucket, access key, secret key
+#
+# After a fresh deploy:
+#   1. Set the REQUIRED block below (DB/Redis/auth secrets/encryption key).
+#   2. Boot the app and run `/setup` to create the first super-admin.
+#   3. Open `/admin/<integration>` and configure each one. Each field shows
+#      a "Using env fallback" badge if it's still inheriting from env, plus
+#      a "Copy from env" button for one-click migration into the DB.
+#
+# The COMMENTED env vars in the OPTIONAL block below still work as a runtime
+# fallback if you set them — useful for staging / dev to bootstrap quickly,
+# or for backward compatibility with older deployments. New ports inherit
+# from these as their initial defaults until the admin UI overrides them.
+#
+# ─── REQUIRED (boot-time secrets — must be in env) ────────────────────────────
+
 # Database
 DATABASE_URL=postgresql://crm:changeme@localhost:5432/port_nimara_crm
 
-# Redis
+# Redis (BullMQ + Socket.IO adapter)
 REDIS_URL=redis://:changeme@localhost:6379
 
-# Auth
+# Auth (must be 32+ char random strings; rotate carefully)
 BETTER_AUTH_SECRET=change-me-to-a-random-string-at-least-32-chars
 BETTER_AUTH_URL=http://localhost:3000
 CSRF_SECRET=change-me-to-a-random-string-at-least-32-chars
 
-# MinIO
-MINIO_ENDPOINT=localhost
-MINIO_PORT=9000
-MINIO_ACCESS_KEY=minioadmin
-MINIO_SECRET_KEY=minioadmin
-MINIO_BUCKET=crm-files
-MINIO_USE_SSL=false
-
-# Documenso
-DOCUMENSO_API_URL=https://documenso.example.com/api/v1
-DOCUMENSO_API_KEY=your-documenso-api-key
-DOCUMENSO_WEBHOOK_SECRET=your-webhook-secret-min-16-chars
-
-# Email (SMTP)
-SMTP_HOST=mail.portnimara.com
-SMTP_PORT=587
-
-# Encryption (64-char hex string for AES-256)
+# AES-256 key for credential encryption at rest. 64-char hex string.
+# Generate with: openssl rand -hex 32
+# CRITICAL: rotating this orphans every encrypted credential in system_settings
+# (Documenso API key, SMTP password, OpenAI key, S3 access/secret keys).
+# Plan a re-keying flow before rotating in production.
 EMAIL_CREDENTIAL_KEY=0000000000000000000000000000000000000000000000000000000000000000
 
-# Google OAuth (optional)
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-
-# OpenAI (optional)
-OPENAI_API_KEY=
-
-# App
+# App URL — used by middleware redirects + outbound email link construction.
 APP_URL=http://localhost:3000
-PUBLIC_SITE_URL=https://portnimara.com
+
+# Inlined into the client JS bundle at build time. Must match APP_URL.
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# Process basics
 NODE_ENV=development
 LOG_LEVEL=info
 
-# Next.js public
-NEXT_PUBLIC_APP_URL=http://localhost:3000
+# When true, the filesystem storage backend refuses to start. Multi-node
+# deploys MUST use the s3-compatible backend (per CLAUDE.md).
+# MULTI_NODE_DEPLOYMENT=false
+
+
+# ─── OPTIONAL: integration env fallbacks ──────────────────────────────────────
+# Each of the following is configurable in the admin UI. Uncomment + set ANY
+# of these to provide a fallback that ports inherit when their admin field is
+# blank. The admin UI labels each inherited field with a "Using env fallback"
+# badge and offers a "Copy from env" button for one-click migration into the
+# port-scoped DB row.
+
+# ─ Documenso (admin: /admin/documenso) ─
+# DOCUMENSO_API_URL=https://documenso.example.com    # Bare host. Never include /api/v1.
+# DOCUMENSO_API_KEY=your-documenso-api-key           # AES-encrypted once written via admin
+# DOCUMENSO_API_VERSION=v1                            # v1 (1.13.x) or v2 (2.x)
+# DOCUMENSO_WEBHOOK_SECRET=                           # Min 16 chars. Generate: openssl rand -hex 16
+# DOCUMENSO_TEMPLATE_ID_EOI=
+# DOCUMENSO_CLIENT_RECIPIENT_ID=
+# DOCUMENSO_DEVELOPER_RECIPIENT_ID=
+# DOCUMENSO_APPROVAL_RECIPIENT_ID=
+
+# ─ Email / SMTP (admin: /admin/email) ─
+# SMTP_HOST=mail.portnimara.com
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASS=                                          # AES-encrypted once written via admin
+# SMTP_FROM=                                          # e.g. "Port Nimara <noreply@example.com>"
+
+# Dev/test safety net: when set, every outbound email is rerouted to this
+# address regardless of recipient. Subject is prefixed with [redirected from <orig>].
+# CRITICAL: env validation refuses boot if NODE_ENV=production AND this is set.
+# EMAIL_REDIRECT_TO=
+
+# ─ Storage / S3 / MinIO (admin: /admin/storage) ─
+# MINIO_ENDPOINT=localhost
+# MINIO_PORT=9000
+# MINIO_ACCESS_KEY=                                   # AES-encrypted once written via admin
+# MINIO_SECRET_KEY=                                   # AES-encrypted (already)
+# MINIO_BUCKET=crm-files
+# MINIO_USE_SSL=false
+# MINIO_AUTO_CREATE_BUCKET=false                      # Auto-create bucket at boot
+
+# ─ OpenAI (admin: /admin/ai) ─
+# OPENAI_API_KEY=                                     # AES-encrypted once written via admin
+
+# ─ Public marketing site URL (admin: /admin/general — TODO) ─
+# PUBLIC_SITE_URL=https://portnimara.com
+
+# ─ Webhook intake from marketing site (deployment-shared, env-only) ─
+# Shared secret with the marketing website's CRM_INTAKE_SECRET. Min 16 chars.
+# WEBSITE_INTAKE_SECRET=
+
+# ─ Sentry (optional — when unset the SDK is a no-op) ─
+# NEXT_PUBLIC_SENTRY_DSN=
+# SENTRY_ENVIRONMENT=
+# SENTRY_TRACES_SAMPLE_RATE=0.1
+
+# ─ Google OAuth (not currently used) ─
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=

.env.prod.template

@@ -0,0 +1,58 @@
+# ─── Port Nimara CRM — PROD environment template ─────────────────────────────
+#
+# Production env contains ONLY the boot-time minimum: DB connection, auth
+# secrets, encryption key, app URL, log level. Every integration credential
+# (Documenso, OpenAI, SMTP, S3) is configured per-port in the admin UI after
+# the first super-admin completes /setup. This keeps secrets out of the
+# infrastructure layer (k8s ConfigMap, .env files, deploy logs).
+#
+# Generate fresh secrets:
+#   openssl rand -hex 32      # for BETTER_AUTH_SECRET, CSRF_SECRET
+#   openssl rand -hex 32      # for EMAIL_CREDENTIAL_KEY (must be 64 hex chars)
+
+# ─── Required ────────────────────────────────────────────────────────────────
+
+DATABASE_URL=postgresql://USER:PASS@HOST:5432/port_nimara_crm
+REDIS_URL=redis://:PASS@HOST:6379
+
+BETTER_AUTH_SECRET=GENERATE_OPENSSL_RAND_HEX_32
+BETTER_AUTH_URL=https://crm.example.com
+CSRF_SECRET=GENERATE_OPENSSL_RAND_HEX_32
+
+# CRITICAL: rotating this orphans every encrypted credential in
+# system_settings. Plan a re-keying flow before rotating.
+EMAIL_CREDENTIAL_KEY=GENERATE_OPENSSL_RAND_HEX_32_PRODUCES_64_CHARS
+
+APP_URL=https://crm.example.com
+NEXT_PUBLIC_APP_URL=https://crm.example.com
+
+NODE_ENV=production
+LOG_LEVEL=info
+
+# ─── Multi-node guard ────────────────────────────────────────────────────────
+# Set true if running > 1 app instance. Forces the storage backend off
+# filesystem onto S3-compatible (filesystem mode is single-node only).
+MULTI_NODE_DEPLOYMENT=true
+
+# ─── Sentry (highly recommended in prod) ─────────────────────────────────────
+NEXT_PUBLIC_SENTRY_DSN=https://YOUR_KEY@YOUR_PROJECT.ingest.sentry.io/PROJECT_ID
+SENTRY_ENVIRONMENT=production
+SENTRY_TRACES_SAMPLE_RATE=0.1
+
+# ─── Webhook intake from marketing site (deployment-shared) ──────────────────
+# Must match the marketing site's CRM_INTAKE_SECRET. Min 16 chars.
+WEBSITE_INTAKE_SECRET=GENERATE_OPENSSL_RAND_HEX_16
+
+# ─── DO NOT SET in production ────────────────────────────────────────────────
+# EMAIL_REDIRECT_TO     — Will fail boot validation (silently rewrites every
+#                          outbound email recipient).
+# SKIP_ENV_VALIDATION   — Bypasses safety checks. Internal use only.
+
+# ─── Integration credentials live in /admin/<integration>, NOT here ──────────
+# Once deployed:
+#   1. Run `pnpm exec drizzle-kit push` (or your migration script)
+#   2. Hit https://crm.example.com/setup to create the first super-admin
+#   3. Log in → /admin/documenso, /admin/email, /admin/storage, /admin/ai
+#   4. Configure each integration. AES-encrypted at rest.
+#   5. Run `pnpm tsx scripts/encrypt-plaintext-credentials.ts` once to encrypt
+#      any legacy plaintext rows from older deployments.

.gitignore

@@ -28,10 +28,40 @@ docker-compose.override.yml
 
 # Ad-hoc screenshots / scratch artifacts at repo root
 /*.png
+/*.jpg
+# Local-only dashboard widget-combo screenshots — regenerated by manual testing
+/combos/
 
 # Legacy Nuxt portal — kept on disk for reference, not tracked here
 /client-portal/
 
+# Sister marketing site — separate Nuxt project, not part of CRM tracking
+/website/
+
 # Mobile audit screenshots — generated locally, regenerable
 /.audit/
+/.audit-screenshots/
+
+# Migration script output (CSV reports, transcripts)
 .migration/
+
+# Tool caches / runtime state
+/.claude/
+/.serena/
+/ruvector.db
+
+# Filesystem storage backend root (FilesystemBackend default location)
+/storage/
+
+# Private credentials + forensic captures — never commit
+/private/
+
+# Local berth-PDF + brochure samples used as upload fixtures during dev.
+/berth_pdf_example/
+
+# Scratch / audit artefacts
+tmp/
+
+# Internal docs + Claude instructions: kept local-only, not in the shared repo
+docs/
+/CLAUDE.md

.lintstagedrc.json

@@ -1,4 +1,4 @@
 {
-  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+  "*.{ts,tsx}": ["eslint --fix", "prettier --write", "node scripts/tsc-staged.mjs"],
   "*.{json,md,css}": ["prettier --write"]
 }

CLAUDE.md

@@ -1,144 +0,0 @@
-# Port Nimara CRM
-
-Multi-tenant CRM for marina/port management. Built with Next.js 15 App Router (standalone output), React 19, TypeScript (strict), Tailwind CSS 3, and Drizzle ORM on PostgreSQL.
-
-## Quick reference
-
-```bash
-pnpm dev              # Start dev server
-pnpm build            # Production build
-pnpm lint             # ESLint
-pnpm format           # Prettier
-pnpm db:generate      # Generate Drizzle migrations
-pnpm db:push          # Push schema to DB
-pnpm db:studio        # Drizzle Studio GUI
-pnpm db:seed          # Seed database (tsx src/lib/db/seed.ts)
-
-# Tests
-pnpm exec vitest run                                  # Unit + integration (~3s)
-pnpm exec playwright test --project=smoke             # Click-through smoke (~10min)
-pnpm exec playwright test --project=exhaustive        # Full UI exhaustive
-pnpm exec playwright test --project=destructive       # Archive/delete flows
-pnpm exec playwright test --project=realapi           # Real Documenso/IMAP (opt-in)
-pnpm exec playwright test --project=visual            # Pixel-diff baselines
-pnpm exec playwright test --project=visual --update-snapshots  # Regenerate baselines
-
-# Dev helpers
-pnpm tsx scripts/dev-trigger-portal-invite.ts         # Send a portal activation email
-pnpm tsx scripts/dev-imap-probe.ts                    # Dump recent IMAP inbox messages
-```
-
-## Tech stack
-
-- **Framework:** Next.js 15.1 App Router, `output: 'standalone'`, `experimental.typedRoutes`
-- **Auth:** better-auth (session cookie: `pn-crm.session_token`)
-- **Database:** PostgreSQL via `postgres` driver + Drizzle ORM
-- **Queue:** BullMQ + Redis (ioredis)
-- **Storage:** MinIO (S3-compatible)
-- **Realtime:** Socket.IO with Redis adapter
-- **UI:** Radix UI primitives, shadcn/ui components (`src/components/ui/`), Lucide icons, CVA + tailwind-merge + clsx
-- **Forms:** react-hook-form + zod resolvers
-- **Tables:** TanStack Table
-- **State:** Zustand stores (`src/stores/`), TanStack React Query
-- **PDF:** pdfme
-- **Email:** nodemailer + imapflow + mailparser
-- **AI:** OpenAI SDK (optional)
-- **Testing:** Vitest (unit), Playwright (e2e)
-- **Logging:** pino + pino-pretty
-
-## Project structure
-
-```
-src/
-  app/
-    (auth)/          # Login/auth pages
-    (dashboard)/     # Main app - route: /[portSlug]/...
-    (portal)/        # Client portal
-    api/             # API routes
-  components/
-    ui/              # shadcn/ui base components
-    layout/          # Shell, sidebar, header
-    [domain]/        # Domain components (clients, invoices, berths, etc.)
-    shared/          # Cross-domain shared components
-  hooks/             # React hooks (use-auth, use-permissions, use-socket, etc.)
-  lib/
-    api/             # API client utilities
-    auth/            # better-auth config
-    db/
-      schema/        # Drizzle schema (one file per domain)
-      migrations/    # Generated Drizzle migrations
-    env.ts           # Zod env validation (SKIP_ENV_VALIDATION=1 bypasses)
-    services/        # Business logic services
-    validators/      # Zod schemas for API input validation
-    utils/           # Shared utilities
-  middleware.ts      # Auth middleware (cookie check, redirects)
-  providers/         # React context providers
-  stores/            # Zustand stores
-  types/             # Shared TypeScript types
-```
-
-## Conventions
-
-- **TypeScript:** Strict mode with `noUncheckedIndexedAccess`. No `any` (ESLint error).
-- **Formatting:** Prettier - single quotes, semicolons, trailing commas, 2-space indent, 100 char line width.
-- **Lint:** ESLint flat config extending `next/core-web-vitals`, `next/typescript`, `prettier`. Unused vars prefixed with `_` are allowed.
-- **Imports:** Use `@/*` path alias (maps to `src/*`).
-- **Components:** shadcn/ui pattern - base components in `src/components/ui/`, domain components in `src/components/[domain]/`. Yacht / company / reservation domains live in `components/yachts`, `components/companies`, `components/reservations` respectively.
-- **DB schema:** One file per domain in `src/lib/db/schema/`, re-exported from `index.ts`. Relations in `relations.ts`. Domain files include `clients.ts`, `yachts.ts`, `companies.ts`, `reservations.ts`, `interests.ts`, `berths.ts`, `documents.ts`, `invoices.ts`, etc.
-- **Polymorphic ownership:** Yachts and invoice billing-entities use `<entity>_type` + `<entity>_id` column pairs (`'client' | 'company'`). Resolve owner identity through `src/lib/services/yachts.service.ts` / `eoi-context.ts` rather than reading the columns ad hoc — those services apply the type discriminator.
-- **EOI generation:** Two pathways share the same `EoiContext` (`src/lib/services/eoi-context.ts`). Documenso pathway calls the template-generate endpoint via `documenso-payload.ts`; in-app pathway fills the same source PDF (`assets/eoi-template.pdf`) via `src/lib/pdf/fill-eoi-form.ts` (pdf-lib AcroForm). Routed through `generateAndSign(...)` in `src/lib/services/document-templates.ts` with a `pathway` parameter.
-- **Merge fields:** Token catalog lives in `src/lib/templates/merge-fields.ts`; the `createTemplateSchema` validator uses `VALID_MERGE_TOKENS` as an allow-list, so unknown tokens are rejected at template creation time.
-- **Documenso webhooks:** Documenso (both v1.13 and 2.x) authenticates outbound webhooks by sending the configured secret in plaintext via the `X-Documenso-Secret` header — there is no HMAC. The receiver at `src/app/api/webhooks/documenso/route.ts` does a timing-safe equality check via `verifyDocumensoSecret`. Event names arrive as the uppercase Prisma enum on the wire (`DOCUMENT_SIGNED`, `DOCUMENT_COMPLETED`, etc.) even though the UI displays them as lowercase-dotted. The route also normalizes lowercase-dotted variants for forward-compat.
-- **Documenso API responses:** 2.x renamed `id` → `documentId` and recipient `id` → `recipientId`; v1.13 still uses `id`. `src/lib/services/documenso-client.ts` runs every response through `normalizeDocument()` which reads either field name and surfaces the legacy `id` form to downstream consumers.
-- **Email templates:** Branded HTML lives in `src/lib/email/templates/`. The portal-auth flow uses `portal-auth.ts` (activation + reset). All templates use the legacy table-based layout with the Port Nimara logo + blurred overhead background, max-width 600px and `width:100%` for responsive shrink. The `<img>` URLs reference `s3.portnimara.com` directly (will move to `/public` later).
-- **Portal auth pages:** `/portal/login`, `/portal/activate`, `/portal/reset-password` and the CRM `/login`, `/reset-password`, `/set-password` all wrap their content in `<BrandedAuthShell>` (`src/components/shared/branded-auth-shell.tsx`) which renders the same blurred background + logo + white card the email templates use, so the in-app and email surfaces look unified.
-- **Inline editing pattern:** detail pages (clients, yachts, companies, interests, residential clients/interests) use `<InlineEditableField>` (`src/components/shared/inline-editable-field.tsx`) for click-to-edit text/select/textarea fields and `<InlineTagEditor>` (`src/components/shared/inline-tag-editor.tsx`) for tag chips. Each entity exposes a `PUT /api/v1/<entity>/[id]/tags` endpoint backed by a `set<Entity>Tags` service helper that wipes-and-rewrites the join table inside a single transaction. There are no separate "Edit" modal forms on detail pages — the entire overview tab is editable in place.
-- **Notes (polymorphic across entity types):** `notes.service.ts` dispatches across `clientNotes`, `interestNotes`, `yachtNotes`, `companyNotes` based on an `entityType` discriminator. `<NotesList entityType="…" />` works for all four. `companyNotes` lacks an `updatedAt` column — the service substitutes `createdAt` so callers get a uniform shape.
-- **Route handler exports:** Next.js App Router `route.ts` files only allow specific named exports (`GET|POST|…`). Service-tested handler functions live in sibling `handlers.ts` files (e.g. `src/app/api/v1/yachts/[id]/handlers.ts`) and are imported by the colocated `route.ts` for `withAuth(withPermission(...))` wrapping. Integration tests import from `handlers.ts` directly to bypass auth/permission middleware.
-- **Routes:** Multi-tenant via `[portSlug]` dynamic segment. Typed routes enabled.
-- **Pre-commit:** Husky + lint-staged runs ESLint fix + Prettier on staged `.ts`/`.tsx` files. The hook also blocks `.env*` files (including `.env.example`) from being committed; pass them via a separate workflow if needed.
-
-## Schema migrations during dev
-
-When you run a `db:push` or apply a migration via `psql` against a running dev server, **restart the dev server afterwards**. Drizzle/postgres.js keeps connection-level prepared statements that can hold stale column lists; a stale pool causes `column X does not exist` errors on pages that touch the migrated table even though the column is present in the DB. Symptom: pages return 500 with `errorMissingColumn`/`42703` after a successful migration. Fix: kill `next dev` and restart it.
-
-## Environment
-
-Copy `.env.example` to `.env` for local dev. See `src/lib/env.ts` for the full schema. Set `SKIP_ENV_VALIDATION=1` to bypass validation (used in Docker build).
-
-Optional dev/test-only env vars (not in `.env.example`):
-
-- `EMAIL_REDIRECT_TO=<address>` — when set, every outbound email is rerouted to this address regardless of the requested recipient and the subject is prefixed with `[redirected from <original>]`. Dev safety net so seeded fake-client emails don't escape; **must be unset in production**.
-- `IMAP_HOST` / `IMAP_PORT` / `IMAP_USER` / `IMAP_PASS` — read by `tests/e2e/realapi/portal-imap-activation.spec.ts` to fetch the activation email from a real mailbox during the IMAP round-trip test. The spec skips when any are missing.
-
-## Testing
-
-Five Playwright projects, defined in `playwright.config.ts`:
-
-- `setup` — global setup (seeds users, port, berths, system settings).
-- `smoke` — fast click-through over every major flow. Run on every change (~10 min, 125 specs).
-- `exhaustive` — deeper UI coverage that takes longer.
-- `destructive` — archive/delete/cancel paths against throwaway entities.
-- `realapi` — opt-in suite that hits real external services (Documenso send-side + IMAP round-trip). Requires `DOCUMENSO_API_*`, `SMTP_*`, `IMAP_*` env. Cloudflared tunnel needs to be running so Documenso can call the local webhook receiver.
-- `visual` — pixel-diff baselines for stable list/landing pages. Snapshots committed under `tests/e2e/visual/snapshots.spec.ts-snapshots/`. Regenerate with `--update-snapshots` after intentional UI changes.
-
-Vitest covers unit + integration with mocked external services (`tests/unit/`, `tests/integration/`).
-
-## Docker
-
-- `Dockerfile` - Production multi-stage build (deps -> build -> runner)
-- `Dockerfile.dev` - Dev with bind-mounted source
-- `Dockerfile.worker` - BullMQ worker process
-- `docker-compose.yml` / `docker-compose.dev.yml` / `docker-compose.prod.yml`
-
-## Architecture docs
-
-Numbered spec files in repo root (`01-CONSOLIDATED-SYSTEM-SPEC.md` through `15-DESIGN-TOKENS.md`) contain detailed architecture decisions, feature specs, DB schema docs, API catalog, and implementation sequence.
-
-Domain-specific references:
-
-- `docs/eoi-documenso-field-mapping.md` — canonical mapping from `EoiContext`
-  paths to the Documenso template's `formValues` keys, with the matching
-  AcroForm field names used by the in-app pathway.
-- `assets/README.md` — what the in-app EOI source PDF must contain and how
-  to override its path in dev/test.

Dockerfile

@@ -1,16 +1,32 @@
 # Stage 1: Install dependencies
 FROM node:20-alpine AS deps
-RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 WORKDIR /app
 COPY package.json pnpm-lock.yaml ./
 RUN pnpm install --frozen-lockfile --prod=false
 
+# Stage 1b: Production dependency tree in a flat (hoisted) node_modules.
+# Hoisted = symlink-free, so a Docker COPY into the runner is faithful
+# (copying pnpm's default symlinked layout dereferences and breaks
+# transitive resolution); complete = the custom socket.io server's deps
+# (engine.io, accepts, ws, ...) all resolve at runtime.
+FROM node:20-alpine AS prod-deps
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN echo "node-linker=hoisted" > .npmrc && pnpm install --frozen-lockfile --prod
+
 # Stage 2: Build the application
 FROM node:20-alpine AS builder
-RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
+# NODE_ENV=production in the builder makes `next build` and any code
+# branching on isProd deterministic (build-auditor M9). Without this,
+# CSP and other prod-only paths would compile under whatever NODE_ENV
+# the host carried in.
+ENV NODE_ENV=production
 ENV NEXT_TELEMETRY_DISABLED=1
 ENV SKIP_ENV_VALIDATION=1
 RUN pnpm build
@@ -25,6 +41,26 @@ COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
 COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 COPY --from=builder --chown=nextjs:nodejs /app/public ./public
 COPY --from=builder --chown=nextjs:nodejs /app/dist/server.js ./server-custom.js
+# The Next standalone node_modules is a MATCHED SET with the turbopack
+# server chunks — it resolves turbopack's externalized packages (better-auth,
+# postgres, pino, minio, ...) by their hashed ids, so REPLACING it makes
+# every route that uses them 500 with "Failed to load external module".
+# But the custom server (server-custom.js, CJS via esbuild --packages=external)
+# require()s deps the trace omits or ships ESM-only: socket.io's closure
+# (accepts/ws/engine.io/cors) and drizzle-orm's CJS entry (index.cjs). So
+# MERGE the complete hoisted prod tree INTO the standalone node_modules with
+# rsync --ignore-existing: it ADDS the missing packages/files and SKIPS
+# everything the trace already provides (and unlike COPY/cp it tolerates the
+# trace's pnpm symlinks instead of erroring on symlink-vs-dir). The one
+# thing the standalone server bootstrap would set — globalThis.AsyncLocalStorage
+# — is handled up-front by src/server-runtime-preamble.ts.
+COPY --from=prod-deps --chown=nextjs:nodejs /app/node_modules /opt/prod-node-modules
+RUN apk add --no-cache --virtual .merge-deps rsync \
+ && rsync -a --ignore-existing /opt/prod-node-modules/ ./node_modules/ \
+ && rm -rf /opt/prod-node-modules \
+ && apk del .merge-deps
 USER nextjs
 EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:${PORT:-3000}/api/health || exit 1
 CMD ["node", "server-custom.js"]

Dockerfile.dev

@@ -1,7 +1,12 @@
 FROM node:20-alpine
-RUN corepack enable && corepack prepare pnpm@latest --activate
-WORKDIR /app
-COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
+# Drop root for the dev runtime — node:alpine ships a `node` user (uid
+# 1000) for exactly this purpose. Audit caught that running as root in
+# dev is an unnecessary risk when the bind-mounted source lets a
+# compromised process write anywhere in the repo.
+USER node
+WORKDIR /home/node/app
+COPY --chown=node:node package.json pnpm-lock.yaml ./
 RUN pnpm install --frozen-lockfile
 EXPOSE 3000
 CMD ["pnpm", "dev"]

Dockerfile.worker

@@ -1,26 +1,40 @@
 # Stage 1: Install dependencies (dev deps needed for esbuild)
 FROM node:20-alpine AS deps
-RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 WORKDIR /app
 COPY package.json pnpm-lock.yaml ./
 RUN pnpm install --frozen-lockfile --prod=false
 
 # Stage 2: Build the worker bundle
 FROM node:20-alpine AS builder
-RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 ENV SKIP_ENV_VALIDATION=1
 RUN pnpm build:worker
 
-# Stage 3: Production runner (prod deps only)
+# Stage 3: Production runner (prod deps only).
+#
+# Critical ordering: create the worker user FIRST and chown the workdir
+# BEFORE pnpm install, so node_modules + lazy-cache directories
+# (tesseract.js, sharp) are owned by the worker user. Without this, the
+# previous layout had pnpm install run as root → node_modules root-owned
+# → tesseract.js / sharp wrote to node_modules/.cache and EACCES'd at
+# first PDF parse in prod (auditor-K §39).
 FROM node:20-alpine AS runner
-RUN corepack enable && corepack prepare pnpm@latest --activate
-WORKDIR /app
-COPY package.json pnpm-lock.yaml ./
-RUN pnpm install --frozen-lockfile --prod
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 worker
-COPY --from=builder --chown=worker:nodejs /app/dist/worker.js ./worker.js
+WORKDIR /app
+RUN chown -R worker:nodejs /app
 USER worker
+COPY --chown=worker:nodejs package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile --prod
+COPY --from=builder --chown=worker:nodejs /app/dist/worker.js ./worker.js
+# Healthcheck — pings Redis from inside the worker container. Without
+# this, a worker whose Redis connection has silently dropped (BullMQ
+# rejects new jobs but the Node process is alive) is invisible to
+# compose / swarm and jobs queue indefinitely (auditor-K §40).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD node -e "const Redis=require('ioredis');const r=new Redis(process.env.REDIS_URL,{maxRetriesPerRequest:1,connectTimeout:3000,lazyConnect:true});r.connect().then(()=>r.ping()).then(()=>{r.disconnect();process.exit(0)}).catch(()=>process.exit(1))" || exit 1
 CMD ["node", "worker.js"]

assets/README.md

@@ -29,9 +29,30 @@ Documenso template's `formValues` keys — see
 | `Lease_10`     | Checkbox | always `false` (legacy default — Purchase, not Lease) |
 | `Purchase`     | Checkbox | always `true`                                         |
 
-Form fields stay interactive after generation (not flattened), so the
-recipient can still tweak values before signing if the in-app pathway is
-followed by a Documenso send.
+The fill path **flattens** the AcroForm after writing values, so the
+recipient can't edit pre-filled values (yacht dimensions, address, berth
+number) after the fact. Documenso pathway flattens server-side; the
+in-app pathway brings the artifact to parity.
+
+### Expected sha256
+
+The source PDF's sha256 is pinned to guard against silent template swaps
+(an unreviewed asset swap would change legal output without a code diff):
+
+```
+ba495fd88d99ebe4b7f61acbe397fb2f1cd116e1e1f1b217de93106915c7c44b
+```
+
+`scripts/check-eoi-template-sha.ts` verifies this at boot of the in-app
+pathway; the function exposes the expected hash via `EXPECTED_EOI_SHA256`
+so tests can re-check after a deliberate template revision.
+
+To intentionally update the template:
+
+1. Drop the new PDF as `eoi-template.pdf`.
+2. Run `shasum -a 256 assets/eoi-template.pdf`.
+3. Update the hash in this README **and** in
+   `src/lib/pdf/fill-eoi-form.ts` (search for `EXPECTED_EOI_SHA256`).
 
 ### Override path
 
@@ -46,3 +67,23 @@ exact bytes:
 1. In Documenso, open the EOI template.
 2. Download the source PDF.
 3. Drop it here as `eoi-template.pdf`.
+
+### Known asset issue: Email field clipped at top
+
+The current `eoi-template.pdf` has the `Email` AcroForm field box positioned
+slightly too low — long email addresses render with the top pixel row
+clipped. **Fix is asset-side, not code-side**: pdf-lib only fills field
+boxes, it can't move them. To resolve:
+
+1. Open `eoi-template.pdf` in any PDF form editor (Acrobat, PDFescape,
+   PDF Studio, or Documenso's own template editor).
+2. Select the `Email` field box; nudge its `y` origin down by ~3 pt (or
+   increase its height by ~3 pt) so the rendered text has visual margin
+   from the top edge.
+3. Save → re-upload to Documenso (so both pathways stay in sync) →
+   bump the sha256 in this README + `EXPECTED_EOI_SHA256` per the steps
+   above.
+
+Affects both the in-app pathway (renders via pdf-lib AcroForm fill) and
+the Documenso pathway (Documenso's own renderer respects the same field
+geometry).

docker-compose.prod.yml

@@ -14,12 +14,27 @@ services:
       timeout: 5s
       retries: 5
     restart: unless-stopped
+    # build-auditor HIGH: bound memory + log rotation so a stuck query or
+    # noisy log doesn't fill the host disk. Postgres respects shared
+    # buffers env via init.sql; the hard limit here is the container
+    # ceiling.
+    deploy:
+      resources:
+        limits:
+          memory: 2g
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "5"
     networks:
       - internal
 
   redis:
     image: redis:7-alpine
-    command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy allkeys-lru
+    # BullMQ requires `noeviction` — under memory pressure, allkeys-lru
+    # silently drops queue keys and jobs disappear. See post-audit fix F4.
+    command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy noeviction
     volumes:
       - redisdata:/data
     healthcheck:
@@ -28,6 +43,15 @@ services:
       timeout: 5s
       retries: 5
     restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 512m
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
     networks:
       - internal
 
@@ -42,11 +66,28 @@ services:
       redis:
         condition: service_healthy
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
+      # build-auditor H5: env.PORT is configurable (default 3000), so
+      # template the port into the healthcheck URL. Otherwise overriding
+      # PORT=8080 via .env makes the container healthy-check itself on
+      # the wrong port and enter a restart loop.
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:${PORT:-3000}/api/health"]
       interval: 15s
       timeout: 5s
       retries: 3
+    # Give the SIGTERM handler in src/server.ts time to drain in-flight
+    # HTTP requests, close Socket.io, and disconnect Redis before Docker
+    # SIGKILLs the process. The internal hard timeout is 25s.
+    stop_grace_period: 30s
     restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 1g
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "5"
     networks:
       - internal
 
@@ -58,7 +99,19 @@ services:
         condition: service_healthy
       redis:
         condition: service_healthy
+    # Match the app: BullMQ jobs need time to finish or be released back
+    # to the queue when worker.ts handles SIGTERM.
+    stop_grace_period: 30s
     restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 1g
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "5"
     networks:
       - internal
 

docker-compose.yml

@@ -18,7 +18,9 @@ services:
 
   redis:
     image: redis:7-alpine
-    command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy allkeys-lru
+    # BullMQ requires `noeviction` — under memory pressure, allkeys-lru
+    # silently drops queue keys and jobs disappear. See post-audit fix F4.
+    command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy noeviction
     volumes:
       - redisdata:/data
     healthcheck:
@@ -40,7 +42,9 @@ services:
       redis:
         condition: service_healthy
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
+      # Templatize port so `PORT=…` env overrides don't desync the
+      # healthcheck from the actual listener.
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:${PORT:-3000}/api/health"]
       interval: 15s
       timeout: 5s
       retries: 3

docs/eoi-documenso-field-mapping.md

@@ -1,76 +0,0 @@
-# Documenso EOI Template — Field Mapping
-
-**Purpose:** This doc is the canonical reference for mapping the Documenso EOI template's `formValues` keys to the new data model's `EoiContext` shape. It drives `buildDocumensoPayload()` (Task 11.2), the in-app Standard EOI HTML tokens (Task 11.3), and the Spec 2 importer's yacht/company hydration.
-
-## Source
-
-The legacy field list comes from `client-portal/server/api/eoi/generate-quick-eoi.ts`, specifically the POST body sent to `POST /api/v1/templates/{templateId}/generate-document` (Documenso template 8). The relevant lines in that file are around the `createDocumentPayload.formValues` object.
-
-## Documenso template `formValues` keys
-
-Documenso template IDs and recipient IDs are configured via env vars:
-
-- `NUXT_DOCUMENSO_TEMPLATE_ID` (default: `8`)
-- `NUXT_DOCUMENSO_CLIENT_RECIPIENT_ID` (default: `192`) — signing order 1
-- `NUXT_DOCUMENSO_DEVELOPER_RECIPIENT_ID` (default: `193`) — signing order 2
-- `NUXT_DOCUMENSO_APPROVAL_RECIPIENT_ID` (default: `194`) — APPROVER, signing order 3
-
-The template exposes eight text fields (`formValues` keys) and two boolean checkboxes.
-
-## Field mapping
-
-| Documenso key  | Type    | Legacy source               | New `EoiContext` path                                 | Notes                                                                     |
-| -------------- | ------- | --------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
-| `Name`         | text    | `interest['Full Name']`     | `context.client.fullName`                             | The interest's point-of-contact client (billing signer).                  |
-| `Email`        | text    | `interest['Email Address']` | `context.client.primaryEmail`                         | Primary email contact from `client_contacts`.                             |
-| `Address`      | text    | `interest['Address']`       | concat `context.client.address.{street,city,country}` | Concatenate street, city, country with `', '`. Empty if address is null.  |
-| `Yacht Name`   | text    | `interest['Yacht Name']`    | `context.yacht.name`                                  | Yacht is now a first-class row; pulled via `interest.yachtId`.            |
-| `Length`       | text    | `interest['Length']`        | `context.yacht.lengthFt`                              | Send as string. Documenso doesn't enforce numeric format.                 |
-| `Width`        | text    | `interest['Width']`         | `context.yacht.widthFt`                               | Same.                                                                     |
-| `Draft`        | text    | `interest['Depth']`         | `context.yacht.draftFt`                               | Legacy field was named "Depth" in NocoDB; Documenso key is "Draft".       |
-| `Berth Number` | text    | `berthNumbers` (joined)     | `context.berth.mooringNumber`                         | One berth per reservation. Multi-berth case was multi-interest in legacy. |
-| `Lease_10`     | boolean | hardcoded `false`           | `false`                                               | Hardcoded — legacy flow defaults to Purchase (not Lease).                 |
-| `Purchase`     | boolean | hardcoded `true`            | `true`                                                | Hardcoded — legacy flow defaults to Purchase.                             |
-
-## Document `meta` fields (non-`formValues`)
-
-| Documenso key             | Type | Legacy source                            | New source                                                        |
-| ------------------------- | ---- | ---------------------------------------- | ----------------------------------------------------------------- |
-| `meta.message`            | text | `Dear ${interest['Full Name']}...`       | `Dear ${context.client.fullName}, ...port name interpolated`      |
-| `meta.subject`            | text | `"Your LOI is ready to be signed"`       | Same — constant.                                                  |
-| `meta.redirectUrl`        | text | `"https://portnimara.com"`               | `context.port.redirectUrl` if per-port; otherwise global app URL. |
-| `meta.distributionMethod` | text | `"NONE"`                                 | Same — constant. We use manual send flow (Documenso webhook).     |
-| `title`                   | text | `` `${interest['Full Name']}-EOI-NDA` `` | `` `${context.client.fullName}-EOI-NDA` ``                        |
-| `externalId`              | text | `` `loi-${interestId}` ``                | Same.                                                             |
-
-## Recipients (non-`formValues`)
-
-| Recipient           | Role     | Name                      | Email                         | Signing order |
-| ------------------- | -------- | ------------------------- | ----------------------------- | ------------- |
-| Client (signer)     | SIGNER   | `context.client.fullName` | `context.client.primaryEmail` | 1             |
-| Developer (signer)  | SIGNER   | `"David Mizrahi"`         | `"dm@portnimara.com"`         | 2             |
-| Approval (approver) | APPROVER | `"Abbie May"`             | `"sales@portnimara.com"`      | 3             |
-
-The Developer and Approval recipients are currently hardcoded in the legacy flow. In the new system these should eventually come from port-level settings (e.g., `ports.settings.eoi.developerName` + email). For Task 11.2, keep them hardcoded as the legacy system does — tracking as TODO: "Replace hardcoded Developer/Approval recipients with port-level configuration."
-
-## Company-owned yacht handling
-
-The legacy flow has no concept of company ownership — the signer is always the interest's client. In the new system:
-
-- If `context.yacht.ownerType === 'client'`: behavior unchanged.
-- If `context.yacht.ownerType === 'company'`: the interest's point-of-contact client still signs (they're the representative of the yacht's owning company), but an extra block should appear in the message body: `"On behalf of ${context.company.legalName ?? context.company.name} (representing the yacht's owner)."`. This isn't a separate Documenso field — it's woven into `meta.message`.
-
-Tracking this in the mapping doc rather than as a hard TODO because company-owned EOIs were rare in the legacy system and need product input before committing to the final wording.
-
-## Deprecated fields (no longer sourced from `clients`)
-
-The legacy system read these fields from the client row. They are now sourced elsewhere:
-
-| Legacy source             | New source                                          |
-| ------------------------- | --------------------------------------------------- |
-| `client.yachtName`        | `yachts.name` via `interest.yachtId`                |
-| `client.yachtLengthFt`    | `yachts.lengthFt` via `interest.yachtId`            |
-| `client.yachtWidthFt`     | `yachts.widthFt` via `interest.yachtId`             |
-| `client.yachtDraftFt`     | `yachts.draftFt` via `interest.yachtId`             |
-| `client.companyName`      | `companies.name` via polymorphic owner resolution   |
-| `client.berthSizeDesired` | Removed. Berth is picked via reservation, not text. |

docs/runbooks/backup-and-restore.md

@@ -1,199 +0,0 @@
-# Backup and restore runbook
-
-This runbook documents what gets backed up, how often, where it lands, and
-the exact commands to restore the system from a cold start. The goal is
-that any operator who has the off-site backup credentials can bring the
-CRM back up on a clean host without help.
-
-## Scope of a "full backup"
-
-The CRM has three stateful surfaces. All three must be captured for a
-restore to be useful.
-
-| Surface                                                | Holds                                                                                                                                                              | Risk if missing                                                                                                                       |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
-| **PostgreSQL** (`port_nimara_crm`)                     | Every relational record: clients, yachts, companies, interests, reservations, invoices, audit log, GDPR exports, AI usage ledger, Documenso webhook receipts, etc. | Total data loss — site is unrecoverable.                                                                                              |
-| **MinIO bucket** (`MINIO_BUCKET`, default `crm-files`) | Receipts, signed contracts, EOI PDFs, GDPR export ZIPs, document attachments.                                                                                      | Files reachable by row references in Postgres become 404s.                                                                            |
-| **`.env` + secrets**                                   | DB password, MinIO keys, Documenso webhook secret, SMTP creds, encryption key (`ENCRYPTION_KEY`).                                                                  | OCR API keys re-resolve from `system_settings` (encrypted at rest), but **without the original `ENCRYPTION_KEY` they're unreadable**. |
-
-The Redis instance is not backed up. It only holds queue state, rate-limit
-counters, and Socket.IO presence — all reconstructable. Stop the workers
-during a restore so the queue starts clean.
-
-## Backup schedule
-
-Defaults are tuned for a single-port deployment with O(10k) clients. Bump
-on the producing side as scale demands.
-
-| Job                                | Frequency            | Retention                     | Where                                                                |
-| ---------------------------------- | -------------------- | ----------------------------- | -------------------------------------------------------------------- |
-| `pg_dump` (custom format, gzipped) | Hourly               | 7 days hourly + 30 days daily | `${BACKUP_BUCKET}/pg/<host>/<UTC date>/<hour>.dump.gz`               |
-| MinIO mirror                       | Hourly (incremental) | 30 days versions              | `${BACKUP_BUCKET}/minio/`                                            |
-| `.env` snapshot (encrypted)        | On change (manual)   | Forever                       | Password manager / secrets vault — **never the same bucket as data** |
-
-The hourly cadence is the right answer for this workload — invoices and
-contracts cluster around business hours, and an hour of lost work is the
-worst-case data loss window most clients will tolerate. Promote to 15-min
-WAL streaming if a customer demands tighter RPO.
-
-## Required environment variables
-
-The scripts below read these. Store them in a CI secret store, not the
-host's bash profile.
-
-```
-# Source (the running CRM database)
-DATABASE_URL=postgresql://crm:<pw>@<host>:<port>/port_nimara_crm
-
-# MinIO (source bucket — the live one)
-MINIO_ENDPOINT=minio.letsbe.solutions
-MINIO_PORT=443
-MINIO_USE_SSL=true
-MINIO_ACCESS_KEY=<live key>
-MINIO_SECRET_KEY=<live secret>
-MINIO_BUCKET=crm-files
-
-# Backup destination (a *separate* MinIO/S3 endpoint or a different bucket
-# with no IAM overlap with the live keys)
-BACKUP_S3_ENDPOINT=https://s3.eu-west-1.amazonaws.com
-BACKUP_S3_REGION=eu-west-1
-BACKUP_S3_BUCKET=portnimara-backups-prod
-BACKUP_S3_ACCESS_KEY=<dedicated read+write key for this bucket only>
-BACKUP_S3_SECRET_KEY=<...>
-
-# Optional: encrypts dumps at rest with a passphrase. Cuts a wider blast
-# radius if the backup bucket itself is compromised.
-BACKUP_GPG_RECIPIENT=ops@portnimara.com
-```
-
-## Provisioning the backup destination
-
-1. Create a dedicated S3-compatible bucket in a **different account** from
-   the live infra. AWS S3, Backblaze B2, or a separately-credentialed
-   MinIO instance all work.
-2. Apply object-lock or versioning so an attacker who steals the backup
-   write key still can't permanently delete history.
-3. Generate IAM credentials scoped to `s3:PutObject`, `s3:GetObject`,
-   `s3:ListBucket` on this bucket only. Inject them as
-   `BACKUP_S3_*` above. Do not reuse the live `MINIO_*` keys.
-4. Set a 90-day lifecycle rule that transitions objects older than 30
-   days to cold storage and deletes them at 90 days. Past 90 days it's
-   cheaper to restart from a snapshot taken outside the system.
-
-## The scripts
-
-Three scripts in `scripts/backup/`:
-
-- `pg-backup.sh` — runs `pg_dump`, gzips, optionally GPG-encrypts, uploads
-- `minio-mirror.sh` — `mc mirror` of the live bucket → backup bucket
-- `restore.sh` — interactive restore (DB + MinIO) given a snapshot path
-
-Make them executable and wire them into cron / GitHub Actions / your
-scheduler of choice. Sample crontab on the worker host:
-
-```cron
-# Hourly DB dump at minute 7
-7 * * * * /opt/pncrm/scripts/backup/pg-backup.sh >> /var/log/pncrm-backup.log 2>&1
-
-# Hourly MinIO mirror at minute 17 (offset so the two don't fight for I/O)
-17 * * * * /opt/pncrm/scripts/backup/minio-mirror.sh >> /var/log/pncrm-backup.log 2>&1
-
-# Weekly restore drill (smoke-test to a throwaway DB on Sunday at 03:00)
-0 3 * * 0 /opt/pncrm/scripts/backup/restore.sh --drill >> /var/log/pncrm-restore-drill.log 2>&1
-```
-
-## Restoring from cold
-
-These steps have been rehearsed against the dev environment; expect them
-to take 15–30 minutes for a typical port. **The drill (last cron line
-above) ensures the runbook stays correct — if the drill fails, the
-real restore will too.**
-
-### 0. Stop everything that writes
-
-```bash
-docker compose -f docker-compose.prod.yml stop web worker scheduler
-# Leave postgres + minio + redis up; we'll point them at restored data.
-```
-
-### 1. Restore PostgreSQL
-
-```bash
-# Find the dump you want. Prefer the most recent successful hour.
-mc ls "$BACKUP_S3_BUCKET/pg/$(hostname)/" | tail
-SNAPSHOT="2026-04-28/14.dump.gz"
-
-# Pull it.
-mc cp "$BACKUP_S3_BUCKET/pg/$(hostname)/$SNAPSHOT" /tmp/
-
-# Decrypt if BACKUP_GPG_RECIPIENT was set on the producer side.
-gpg --decrypt /tmp/14.dump.gz.gpg > /tmp/14.dump.gz
-
-# Drop & recreate the database. The 'restrict' FK from gdpr_exports.requested_by
-# to user means we restore in the right order — pg_restore handles this.
-psql "$DATABASE_URL" -c 'DROP DATABASE IF EXISTS port_nimara_crm WITH (FORCE);'
-psql "$DATABASE_URL" -c 'CREATE DATABASE port_nimara_crm;'
-gunzip -c /tmp/14.dump.gz | pg_restore --no-owner --no-privileges \
-  --dbname "$DATABASE_URL"
-```
-
-### 2. Restore MinIO
-
-```bash
-# Sync the backup bucket back over the live one. --overwrite handles
-# files that were modified between snapshots.
-mc mirror --overwrite \
-  "$BACKUP_S3_BUCKET/minio/" \
-  "live/$MINIO_BUCKET/"
-```
-
-### 3. Restore secrets
-
-The `.env` file is **not** in object storage. Pull it from the password
-manager / secrets vault. Verify `ENCRYPTION_KEY` matches the value used
-when the database was last running — if it doesn't, rows in
-`system_settings` (OCR API keys, etc.) decrypt to garbage and the OCR
-"Test connection" button will return an opaque error. There is no
-recovery path; the keys must be re-entered through the admin UI.
-
-### 4. Bring services back up
-
-```bash
-docker compose -f docker-compose.prod.yml up -d
-# Watch the worker logs; expect a flurry of socket reconnections, then quiet.
-docker compose -f docker-compose.prod.yml logs -f worker
-```
-
-### 5. Verify
-
-Tail through the smoke checklist, in order:
-
-1. **DB up** — `psql "$DATABASE_URL" -c 'SELECT count(*) FROM clients;'`
-   matches the producer-side count from the snapshot's hour.
-2. **MinIO up** — open any client with attachments in the CRM, click a
-   receipt thumbnail; verify the signed URL serves the file.
-3. **Documenso webhooks** — re-trigger one in the Documenso admin and
-   confirm `audit_logs` records the receipt.
-4. **Email** — send a portal invite to a real address.
-5. **Realtime** — open two browser windows, edit a client in one, watch
-   the other update via Socket.IO.
-6. **AI usage ledger** — `SELECT count(*) FROM ai_usage_ledger;`
-   non-empty if AI was being used. Old rows survive but the budget gates
-   reset alongside the period boundary at month rollover.
-
-## Drill schedule
-
-The weekly drill (cron line above) runs `restore.sh --drill` against a
-throwaway database and a sandbox MinIO bucket. It must produce zero diff
-between the restored row counts and the live row counts (modulo the
-hour-or-so the drill takes to run).
-
-Failure modes the drill catches before they bite production:
-
-- New tables added without inclusion in `pg_dump`'s `--schema=public` (we
-  use the default, which captures everything in `public` — but a future
-  developer adding a `tenant_X` schema will silently lose it).
-- MinIO bucket-policy changes that block the backup-side `s3:GetObject`
-  on certain prefixes.
-- GPG passphrase rotation that wasn't propagated to the restore host.
-- A `pg_restore` version skew with the producer-side `pg_dump`.

docs/runbooks/email-deliverability.md

@@ -1,186 +0,0 @@
-# Email deliverability runbook
-
-The CRM sends transactional email through three different surfaces. Each
-has a different failure mode when it lands in spam. This runbook covers
-how to diagnose, fix, and verify each path.
-
-## What email the CRM sends
-
-| Surface                                   | Trigger                                                                                | Template                                                          | Default `from`                                        |
-| ----------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------- |
-| Portal activation / password-reset        | Admin invites a client to the portal                                                   | `src/lib/email/templates/portal-auth.ts`                          | per-port `email_settings.from_address` or `SMTP_FROM` |
-| Inquiry confirmation + sales notification | Public website POSTs to `/api/public/interests` or `/api/public/residential-inquiries` | `inquiry-client-confirmation.ts`, `inquiry-sales-notification.ts` | same                                                  |
-| GDPR export ready                         | Staff requests an export with `emailToClient=true`                                     | inline in `gdpr-export.service.ts`                                | same                                                  |
-| Documenso reminders                       | Cadence job fires for an unsigned signer                                               | `documenso/reminders/*`                                           | same                                                  |
-
-Documenso _itself_ sends signing requests with its own `from` address —
-those don't flow through this codebase. SPF/DKIM for the Documenso
-sender is the Documenso operator's problem, not yours.
-
-## DNS records
-
-For every domain that appears in a `from:` header you must publish:
-
-### 1. SPF
-
-A single TXT record at the apex authorizing whichever provider is
-sending. Multiple SPF records on the same name **break SPF entirely** —
-combine into one.
-
-```
-v=spf1 include:_spf.google.com include:amazonses.com -all
-```
-
-The `-all` (hardfail) is correct for transactional mail. Switch to `~all`
-(softfail) only as a temporary diagnostic when migrating providers.
-
-### 2. DKIM
-
-Each provider publishes its own selector. Common shapes:
-
-- Google Workspace: `google._domainkey` → 2048-bit RSA pubkey (rotate every 12 months).
-- Amazon SES: `xxxx._domainkey`, `yyyy._domainkey`, `zzzz._domainkey` (three CNAMEs SES gives you).
-- Postmark / Resend / Mailgun: one CNAME per selector.
-
-Verify alignment — the `d=` value in the DKIM signature must match the
-`From:` domain (relaxed alignment is fine, strict is overkill).
-
-### 3. DMARC
-
-Start at `p=none` while you build deliverability data, then upgrade.
-
-```
-_dmarc 14400 IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@portnimara.com; ruf=mailto:dmarc@portnimara.com; fo=1; adkim=r; aspf=r; pct=100"
-```
-
-`rua` (aggregate reports) is the diagnostic feed — set it before the
-first send so the first weekly report has data.
-
-### 4. MX (only if you also receive)
-
-The CRM's IMAP probe (`scripts/dev-imap-probe.ts`) and the inbound thread
-sync rely on a real mailbox. Whoever runs that mailbox publishes the MX
-records — typically Google Workspace or a dedicated provider. Don't add
-an MX pointing at the CRM host; it doesn't accept SMTP IN.
-
-## Per-port overrides
-
-Each port can override `from_address`, `from_name`, and SMTP creds via
-the admin email-settings page. When set, `getPortEmailConfig()` returns
-those values and `sendEmail()` uses them in preference to the global
-`SMTP_*` env. **The override domain still needs SPF / DKIM / DMARC** on
-its own DNS — without them, every send from that port lands in spam.
-
-When a customer reports "our portal invite didn't arrive":
-
-1. Pull the port's email settings from the admin UI. Check `from_address`.
-2. Run `dig TXT <from-domain>` and `dig TXT _dmarc.<from-domain>`.
-   Confirm SPF includes the SMTP provider's domain and DMARC exists.
-3. Send a probe through `mail-tester.com`: paste the address into a
-   test send, click the score breakdown.
-4. Score < 8/10 → fix whatever's flagged before doing anything else in
-   this runbook.
-
-## Diagnosing a "didn't arrive" report
-
-Order matters — go top-down, stop when one of these is the answer.
-
-### Step 1: Was the send attempted?
-
-```bash
-# Tail the worker logs for the recipient address.
-docker compose logs worker | grep '<recipient>'
-```
-
-You'll see one of three patterns:
-
-- **Nothing**: The job didn't run. Check that BullMQ actually queued it.
-  `redis-cli LLEN bull:email:waiting` — if non-zero, the worker is dead.
-  `docker compose logs scheduler | tail` to see why.
-- **`Email sent`** with a message-id: The provider accepted it. Move to
-  Step 2.
-- **`SendError`**: Provider rejected. The error string says why
-  (auth, rate limit, blocked recipient).
-
-### Step 2: Is `EMAIL_REDIRECT_TO` set?
-
-In dev/test we set `EMAIL_REDIRECT_TO=ops@portnimara.com` so seeded fake
-clients don't get real email. **It must be unset in production.**
-
-```bash
-# On the production host:
-docker exec pncrm-web printenv EMAIL_REDIRECT_TO
-# Should print nothing.
-```
-
-If it's set, every email is going to the redirect target with the
-original recipient prefixed in the subject — the customer never sees it.
-
-### Step 3: Did it land but get filtered?
-
-Ask the recipient to check:
-
-- Spam / Junk folder
-- Gmail "Promotions" tab
-- Outlook "Other" folder (vs Focused)
-- The Quarantine console if they're on M365 with anti-spam enabled
-
-If found in a spam folder: the email arrived; the recipient's filter
-classified it. SPF/DKIM/DMARC alignment is suspect — re-run the
-mail-tester probe from above.
-
-### Step 4: Was the recipient on a suppression list?
-
-Some providers (SES, Postmark) maintain a suppression list — once a
-domain bounces from an address, future sends are dropped silently.
-
-```bash
-# SES example:
-aws ses list-suppressed-destinations --region eu-west-1
-```
-
-If the recipient is suppressed, remove them and ask them to retry. The
-CRM doesn't track suppression locally; that's the provider's job.
-
-## When migrating SMTP providers
-
-1. Add the new provider's DKIM CNAMEs alongside the old ones.
-2. Add the new provider's `include:` to the existing SPF record.
-3. Wait 48 hours for DNS to propagate and DMARC reports to confirm both
-   providers align.
-4. Switch `SMTP_*` env to the new provider on a single staging host.
-5. Send through the staging host for a week. Watch DMARC reports.
-6. Cut production over.
-7. Wait two weeks before removing the old provider's DNS — undelivered
-   bounce reports keep arriving for a while.
-
-## Testing a deliverability fix
-
-There's no automated test for "did this email reach the inbox" — that's a
-property of the recipient's filter, which we don't control. The closest
-proxy is the realapi suite:
-
-```bash
-pnpm exec playwright test --project=realapi
-```
-
-It runs `tests/e2e/realapi/portal-imap-activation.spec.ts` which sends a
-real portal-invite email through SMTP, then polls the configured IMAP
-mailbox for the activation link. If it appears within 30 seconds, the
-SMTP→DKIM→DMARC chain is alive end-to-end. If the test times out, work
-backwards through this runbook.
-
-The realapi suite needs `SMTP_*` and `IMAP_*` env vars — see the
-"Optional dev/test-only env vars" block in `CLAUDE.md`.
-
-## Bounce handling
-
-The CRM doesn't currently process bounces. If you start seeing volume:
-
-- Set up the provider's webhook (SES → SNS → Lambda; Postmark → webhook
-  URL) to POST bounce events to a new `/api/webhooks/email-bounce` route.
-- Persist the bounced address into a `email_suppressions` table.
-- Have `sendEmail()` consult that table before each send.
-
-That work isn't in scope yet; this runbook just flags it as the next
-deliverability gap.

docs/runbooks/permission-audit.md

@@ -1,56 +0,0 @@
-# Permission Matrix Audit
-
-Scanned 182 route files under `src/app/api/v1/`.
-
-**No violations.** Every internal v1 handler is permission-gated.
-
-**Allow-listed:** 46 handler(s) intentionally skip `withPermission`.
-
-| File                                                             | Method | Reason                                                                            |
-| ---------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
-| `src/app/api/v1/admin/alerts/run-engine/route.ts`                | POST   | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/connections/route.ts`                      | GET    | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/errors/route.ts`                           | GET    | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/health/route.ts`                           | GET    | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/ocr-settings/route.ts`                     | GET    | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/ocr-settings/route.ts`                     | PUT    | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/ocr-settings/test/route.ts`                | POST   | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/queues/[queueName]/[jobId]/retry/route.ts` | POST   | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/queues/[queueName]/[jobId]/route.ts`       | DELETE | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/queues/[queueName]/route.ts`               | GET    | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/queues/route.ts`                           | GET    | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/admin/users/options/route.ts`                    | GET    | Admin-only — gated by isSuperAdmin inside handler.                                |
-| `src/app/api/v1/ai/email-draft/[jobId]/route.ts`                 | GET    | TODO: needs ai:\* permission catalog entry. Currently allow-listed.               |
-| `src/app/api/v1/ai/email-draft/route.ts`                         | POST   | TODO: needs ai:\* permission catalog entry. Currently allow-listed.               |
-| `src/app/api/v1/ai/interest-score/bulk/route.ts`                 | GET    | TODO: needs ai:\* permission catalog entry. Currently allow-listed.               |
-| `src/app/api/v1/ai/interest-score/route.ts`                      | GET    | TODO: needs ai:\* permission catalog entry. Currently allow-listed.               |
-| `src/app/api/v1/alerts/[id]/acknowledge/route.ts`                | POST   | Alerts are user-scoped; port-filtered via auth context.                           |
-| `src/app/api/v1/alerts/[id]/dismiss/route.ts`                    | POST   | Alerts are user-scoped; port-filtered via auth context.                           |
-| `src/app/api/v1/alerts/count/route.ts`                           | GET    | Alerts are user-scoped; port-filtered via auth context.                           |
-| `src/app/api/v1/alerts/route.ts`                                 | GET    | Alerts are user-scoped; port-filtered via auth context.                           |
-| `src/app/api/v1/berth-reservations/[id]/route.ts`                | PATCH  | TODO: PATCH should map to reservations:edit (not currently in catalog).           |
-| `src/app/api/v1/currency/convert/route.ts`                       | POST   | Currency reference data; port-scoped, no PII.                                     |
-| `src/app/api/v1/currency/rates/refresh/route.ts`                 | POST   | TODO: gate with admin:manage_settings — currently allow-listed.                   |
-| `src/app/api/v1/currency/rates/route.ts`                         | GET    | Currency reference data; port-scoped, no PII.                                     |
-| `src/app/api/v1/custom-fields/[entityId]/route.ts`               | GET    | TODO: needs custom_fields:\* permission. PUT path internally validated.           |
-| `src/app/api/v1/custom-fields/[entityId]/route.ts`               | PUT    | TODO: needs custom_fields:\* permission. PUT path internally validated.           |
-| `src/app/api/v1/expenses/export/parent-company/route.ts`         | POST   | Internally gated by isSuperAdmin inside the handler.                              |
-| `src/app/api/v1/me/route.ts`                                     | GET    | Self-endpoint — auth is sufficient.                                               |
-| `src/app/api/v1/me/route.ts`                                     | PATCH  | Self-endpoint — auth is sufficient.                                               |
-| `src/app/api/v1/notifications/[notificationId]/route.ts`         | PATCH  | User-scoped notifications — caller is the resource owner.                         |
-| `src/app/api/v1/notifications/preferences/route.ts`              | GET    | User-scoped notifications — caller is the resource owner.                         |
-| `src/app/api/v1/notifications/preferences/route.ts`              | PUT    | User-scoped notifications — caller is the resource owner.                         |
-| `src/app/api/v1/notifications/read-all/route.ts`                 | POST   | User-scoped notifications — caller is the resource owner.                         |
-| `src/app/api/v1/notifications/route.ts`                          | GET    | User-scoped notifications — caller is the resource owner.                         |
-| `src/app/api/v1/notifications/unread-count/route.ts`             | GET    | User-scoped notifications — caller is the resource owner.                         |
-| `src/app/api/v1/saved-views/[id]/route.ts`                       | PATCH  | User-self saved views — caller is the resource owner.                             |
-| `src/app/api/v1/saved-views/[id]/route.ts`                       | DELETE | User-self saved views — caller is the resource owner.                             |
-| `src/app/api/v1/saved-views/route.ts`                            | GET    | User-self saved views — caller is the resource owner.                             |
-| `src/app/api/v1/saved-views/route.ts`                            | POST   | User-self saved views — caller is the resource owner.                             |
-| `src/app/api/v1/search/recent/route.ts`                          | GET    | Port-scoped search — results filtered by auth context (resources have own perms). |
-| `src/app/api/v1/search/route.ts`                                 | GET    | Port-scoped search — results filtered by auth context (resources have own perms). |
-| `src/app/api/v1/settings/feature-flag/route.ts`                  | GET    | Public read of feature-flag bool — no PII; auth is sufficient.                    |
-| `src/app/api/v1/tags/options/route.ts`                           | GET    | Tags are cross-cutting reference data; port-scoped via auth.                      |
-| `src/app/api/v1/tags/route.ts`                                   | GET    | Tags are cross-cutting reference data; port-scoped via auth.                      |
-| `src/app/api/v1/users/me/preferences/route.ts`                   | GET    | User-self preferences — caller is the resource owner.                             |
-| `src/app/api/v1/users/me/preferences/route.ts`                   | PATCH  | User-self preferences — caller is the resource owner.                             |

docs/superpowers/specs/2026-04-14-inquiry-notifications-design.md

@@ -1,201 +0,0 @@
-# Inquiry Notifications System Design
-
-Migrates the ActivePieces-powered inquiry notification flow into the CRM. When a client registers interest via the Port Nimara website, the system sends a confirmation email to the client and notifies the sales team -- all using the CRM's own database and email infrastructure instead of NocoDB + ActivePieces.
-
-## Scope
-
-- Expand the public interest API to accept all website form fields
-- Add client address storage (multi-address with primary flag)
-- Send branded confirmation email to the client
-- Send notification to sales team (CRM users + optional external recipients)
-- Make notification recipients and contact email configurable by admins
-
-## Database Changes
-
-### New table: `client_addresses`
-
-| Column           | Type              | Notes                                                            |
-| ---------------- | ----------------- | ---------------------------------------------------------------- |
-| `id`             | uuid PK           | `crypto.randomUUID()`                                            |
-| `client_id`      | uuid FK → clients | cascade delete                                                   |
-| `port_id`        | uuid FK → ports   | cascade delete                                                   |
-| `label`          | text              | e.g., "Home", "Office", "Billing"                                |
-| `street_address` | text              |                                                                  |
-| `city`           | text              |                                                                  |
-| `state_province` | text              |                                                                  |
-| `postal_code`    | text              |                                                                  |
-| `country`        | text              |                                                                  |
-| `is_primary`     | boolean           | default `true`, one-primary-per-client enforced in service layer |
-| `created_at`     | timestamp         | default `now()`                                                  |
-| `updated_at`     | timestamp         | default `now()`                                                  |
-
-Schema file: `src/lib/db/schema/clients.ts` (alongside existing client tables).
-Relations: added to `src/lib/db/schema/relations.ts` (client has many addresses).
-
-### No changes to existing tables
-
-- `clients.preferred_contact_method` already exists -- we populate it from the form.
-- `interests.berth_id` already exists -- we resolve `mooringNumber` to a berth and link it.
-- `notifications.type` already has `new_registration` -- we fire it.
-
-## Public API Changes
-
-### `POST /api/public/interests`
-
-Expanded request schema:
-
-```typescript
-// Required
-firstName: string; // max 100
-lastName: string; // max 100
-email: string; // email format
-phone: string;
-
-// Optional
-preferredContactMethod: 'email' | 'phone' | 'sms';
-mooringNumber: string; // e.g., "A3" -- resolved against berths.mooring_number
-companyName: string;
-yachtName: string;
-yachtLengthFt: number;
-yachtWidthFt: number;
-yachtDraftFt: number;
-preferredBerthSize: string;
-notes: string; // max 2000
-address: {
-  street: string;
-  city: string;
-  stateProvince: string;
-  postalCode: string;
-  country: string;
-}
-
-// Backward compatibility
-fullName: string; // accepted if firstName/lastName not provided
-```
-
-Backward compatibility: if `fullName` is provided without `firstName`/`lastName`, it is used as-is for `clients.full_name`. If `firstName`+`lastName` are provided, they are concatenated.
-
-### Behavior after record creation
-
-1. Resolve `mooringNumber` against `berths.mooring_number` for the port. Link `interests.berth_id` if found; leave null if not.
-2. Store `address` in `client_addresses` with `is_primary: true` and `label: 'Primary'`.
-3. Set `clients.preferred_contact_method` from the form value.
-4. Queue client confirmation email (see Email Templates below).
-5. Fire `new_registration` notifications to sales team (see Notification Flow below).
-6. Return `201 { data: { id, message } }` unchanged.
-
-Rate limiting remains 5 requests/hour per IP.
-
-## Email Templates
-
-Located in `src/lib/email/templates/`. Each exports a function that accepts a typed data object and returns `{ subject: string, html: string, text: string }`.
-
-### `inquiry-client-confirmation.ts`
-
-Sent to the client who submitted the form.
-
-**Input data:**
-
-- `firstName` -- for the greeting
-- `mooringNumber` -- berth identifier (nullable)
-- `contactEmail` -- from `inquiry_contact_email` system setting
-
-**Subject:** "Thank You for Your Interest in Berth {mooringNumber}" or "Thank You for Your Interest in a Port Nimara Berth" if no berth.
-
-**Body:** Greeting with first name, confirmation their interest is registered, mention they'll be contacted by preferred method, link to the contact email address.
-
-**Styling:** Branded -- Port Nimara logo, background image, white card layout. Matches the existing ActivePieces client confirmation template.
-
-### `inquiry-sales-notification.ts`
-
-Sent to CRM users and optional external recipients.
-
-**Input data:**
-
-- `fullName`
-- `email`
-- `phone`
-- `mooringNumber` (nullable, defaults to "None")
-- `crmUrl` -- link to the interest detail page in the CRM (built from port slug + interest ID)
-
-**Subject:** "New Interest - Port Nimara"
-
-**Body:** Notifies that a new interest has been registered, shows client details and berth selected, links to the CRM.
-
-**Styling:** Branded -- Port Nimara logo, background image, white card layout. Matches the existing ActivePieces admin notification template.
-
-Both templates include a plain-text fallback.
-
-## Notification & Delivery Flow
-
-### Client confirmation email
-
-1. After record creation, queue a `send-inquiry-confirmation` job on the `email` BullMQ queue.
-2. Email worker renders the `inquiry-client-confirmation` template with the interest data.
-3. Sends via system SMTP (`src/lib/email/index.ts`).
-4. No in-app notification (client is not a CRM user).
-
-### Sales team notification
-
-1. Query all users on the port who have `interests` read permission via their role.
-2. For each user, call `createNotification()` with type `new_registration`.
-   - The existing notification service checks `user_notification_preferences` (in-app / email / both / neither).
-   - Creates in-app notification + Socket.IO push if `in_app: true`.
-   - Queues `send-notification-email` job if `email: true`.
-3. Fetch `inquiry_notification_recipients` system setting for the port.
-4. For each external email, queue a `send-inquiry-sales-notification` job on the `email` queue (bypasses notification preferences since these are not CRM users).
-
-### Independence
-
-Client confirmation and sales notifications are independent -- a failure in one does not block the other. The `201` response returns immediately after record creation, before any emails are sent.
-
-## Admin Configuration
-
-Two new system settings, managed via the existing admin settings UI:
-
-### `inquiry_contact_email` (string, per-port)
-
-The reply-to / contact email shown in client confirmation emails.
-
-- Default: `sales@portnimara.com`
-- Displayed as a mailto link in the client confirmation email.
-
-### `inquiry_notification_recipients` (JSON array of strings, per-port)
-
-Additional external email addresses that receive the sales team notification.
-
-- Default: `[]` (empty)
-- Only CRM users with interests permissions are notified by default.
-- External recipients receive the sales notification email directly.
-
-### Existing infrastructure (no changes needed)
-
-- **Which CRM users get notified**: controlled by roles/permissions.
-- **How each user receives notifications**: `user_notification_preferences` table.
-- **Admin settings UI**: already supports custom key-value pairs in `system_settings`.
-
-## Files to Create or Modify
-
-### New files
-
-- `src/lib/db/schema/client-addresses.ts` -- (or added to `clients.ts`)
-- `src/lib/email/templates/inquiry-client-confirmation.ts`
-- `src/lib/email/templates/inquiry-sales-notification.ts`
-
-### Modified files
-
-- `src/lib/db/schema/clients.ts` -- add `clientAddresses` table export
-- `src/lib/db/schema/index.ts` -- re-export new table
-- `src/lib/db/schema/relations.ts` -- add client addresses relations
-- `src/lib/validators/public-interest.ts` (or wherever `publicInterestSchema` lives) -- expand schema
-- `src/app/api/public/interests/route.ts` -- berth resolution, address storage, notification + email triggers
-- `src/lib/queue/workers/email.ts` -- handle `send-inquiry-confirmation` and `send-inquiry-sales-notification` jobs
-- `src/lib/services/interests.service.ts` -- helper to find users with interests permissions on a port
-- `src/app/(dashboard)/[portSlug]/admin/settings/settings-manager.tsx` -- register the two new setting keys
-
-## Out of Scope
-
-- Editing email templates from the admin UI (templates are in code).
-- Supplemental forms for collecting missing info (separate feature using existing `form_templates` / `form_submissions` infrastructure).
-- Documenso EOI integration with address merge fields (separate feature).
-- Changes to the Port Nimara website form itself (website team wires the form to our API).

docs/superpowers/specs/2026-04-23-data-model-refactor-design.md

@@ -1,663 +0,0 @@
-# Data-Model Refactor: Yachts and Companies as First-Class Entities
-
-**Status:** Draft — awaiting final review
-**Date:** 2026-04-23
-**Spec position:** 1 of 3 (Spec 2 = NocoDB+MinIO importer; Spec 3 = client merge endpoint)
-
-## Overview
-
-This spec delivers a refactor of the core client / yacht / company data model to support real-world ownership relationships that the current schema cannot express.
-
-The current `clients` table holds yacht dimensions and company name as columns directly on the person row. This enforces a one-person = one-yacht = one-company assumption that breaks the moment:
-
-- A client owns multiple yachts (a common marina scenario)
-- A person is a broker or director of multiple companies
-- A yacht is legally owned by a shell company (common for tax / liability reasons) rather than by the human on the dock
-- A yacht changes hands between owners and the marina needs chain-of-title
-
-The refactor pulls yacht and company data into their own first-class tables, adds join tables for person↔company memberships, and introduces a proper `berth_reservations` table for exclusive-reservation lifecycle tracking.
-
-This spec also fixes two existing schema gaps that surface during the refactor:
-
-- `berths.status` tracks the state of a berth but there is no table recording which client/yacht exclusively reserves a berth
-- `invoices.clientName` is a text field with no FK — there's no first-class link between invoices and billing entities
-
-## Scope boundaries
-
-### In scope (this spec)
-
-- New `yachts`, `yacht_ownership_history`, `yacht_notes`, `yacht_tags` tables
-- New `companies`, `company_memberships`, `company_addresses`, `company_notes`, `company_tags` tables
-- New `berth_reservations` table with partial-unique-index exclusivity enforcement
-- Updates to `interests`, `berth_waiting_list`, `invoices`, `files`, `documents` to add FKs to the new entities
-- Removal of yacht, company, and proxy columns from `clients`
-- New services, API routes, permissions, and socket/webhook events
-- New UI pages for yachts, companies, and berth reservations; modifications to client, interest, berth, invoice forms
-- Dual-path EOI generation (Documenso + in-app PDF template) with a shared payload builder
-- Comprehensive test coverage: unit, integration, E2E, exhaustive click-through, template regression
-- Seeder with realistic multi-cardinality dummy data
-
-### Explicitly out of scope
-
-- **Importing NocoDB records and MinIO documents** → Spec 2
-- **Client merge endpoint** → Spec 3
-- Yacht survey / class-cert document categorization
-- Company hierarchy (holding → subsidiary)
-- Line-item-level yacht references on invoices
-- Auto-renewal flow for berth reservations
-- Per-yacht row-level permissions
-- Portal branding per company
-
-## Decisions and rationale
-
-| Topic                                                                                    | Decision                                                                                                                | Why                                                                                                                                                                                                  |
-| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Yacht scope                                                                              | Full entity: own page, documents, ownership history, yacht-keyed interests / reservations / invoices                    | Marina domain cares about yachts as first-class objects (dimensions for berth fit, registration for port entry, ownership for liability)                                                             |
-| Company scope                                                                            | Full entity: memberships join, company-owned yachts, company billing                                                    | Yachts are frequently owned by shell companies for tax/liability reasons — the human on the dock is a director or broker. Lightweight/medium models can't route invoices to the correct legal entity |
-| Ownership history                                                                        | Dedicated `yacht_ownership_history` table + denormalized current-owner columns on `yachts`                              | Ownership change is exactly the kind of event that needs queryable history (chain of title, insurance, broker commission attribution). Denormalized current-owner keeps common reads fast            |
-| Proxy fields on clients (`isProxy`, `proxyType`, `actualOwnerName`, `relationshipNotes`) | Drop all four                                                                                                           | Every real proxy scenario is expressible through `company_memberships` roles or `client_relationships`. Keeping the old fields creates two sources of truth and drift risk                           |
-| Berth exclusive reservation                                                              | New `berth_reservations` table with partial unique index `WHERE status = 'active'`                                      | Current schema tracks berth state via `berths.status` but does not record which client/yacht holds the reservation. Partial unique index enforces exclusivity at the DB level                        |
-| Invoice billing entity                                                                   | `billingEntityType` (`'client' \| 'company'`) + `billingEntityId`; `clientName` retained as an immutable snapshot       | Companies become first-class payers. `clientName` as text is preserved on the invoice as a snapshot so invoices never retroactively rename themselves                                                |
-| Data state                                                                               | Green-field with dummy seeder; real data arrives via Spec 2                                                             | No production data lives in this Postgres DB yet. NocoDB holds the real records until Spec 2 imports them                                                                                            |
-| Delivery                                                                                 | One cohesive spec covering both yacht + company refactor                                                                | Splitting doubles the migration/UI/test churn for no architectural gain; both sets of changes overlap heavily                                                                                        |
-| EOI template strategy                                                                    | Support both Documenso-template path and in-app PDF template path, both fully functional from day one                   | Handoff risk: client must not come back claiming "EOIs don't work." If Documenso breaks or is replaced, in-app path is the fallback. Both consume the same payload builder for data consistency      |
-| EOI UI picker                                                                            | Dropdown at generation time (user picks Documenso or in-app explicitly)                                                 | Explicit beats automatic fallback for handoff — misconfiguration is visible, not silently masked                                                                                                     |
-| Testing                                                                                  | Unit, integration, full E2E scenarios, exhaustive Playwright click-through, template regression (including visual diff) | Explicit "test thoroughly" direction plus the handoff concern justify going heavier than normal on integration + E2E tiers                                                                           |
-
-## Schema design
-
-### New tables
-
-```
-yachts
-  id                          text PK
-  portId                      text NOT NULL FK → ports.id
-  name                        text NOT NULL
-  hullNumber                  text
-  registration                text
-  flag                        text
-  yearBuilt                   integer
-  builder                     text
-  model                       text
-  hullMaterial                text
-  lengthFt                    numeric
-  widthFt                     numeric
-  draftFt                     numeric
-  lengthM                     numeric
-  widthM                      numeric
-  draftM                      numeric
-  currentOwnerType            text NOT NULL  -- 'client' | 'company'
-  currentOwnerId              text NOT NULL
-  status                      text NOT NULL DEFAULT 'active'  -- 'active' | 'retired' | 'sold_away'
-  notes                       text
-  archivedAt                  timestamptz
-  createdAt                   timestamptz NOT NULL DEFAULT now()
-  updatedAt                   timestamptz NOT NULL DEFAULT now()
-  Indexes:
-    idx_yachts_port            on (portId)
-    idx_yachts_current_owner   on (portId, currentOwnerType, currentOwnerId)
-    idx_yachts_name            on (portId, name)
-
-yacht_ownership_history
-  id                          text PK
-  yachtId                     text NOT NULL FK → yachts.id ON DELETE CASCADE
-  ownerType                   text NOT NULL  -- 'client' | 'company'
-  ownerId                     text NOT NULL
-  startDate                   date NOT NULL
-  endDate                     date            -- NULL = currently active
-  transferReason              text            -- 'sale' | 'inheritance' | 'gift' | 'company_restructure' | 'other'
-  transferNotes               text
-  createdBy                   text NOT NULL
-  createdAt                   timestamptz NOT NULL DEFAULT now()
-  Indexes:
-    idx_yoh_yacht              on (yachtId)
-    idx_yoh_active (partial)   on (yachtId) WHERE endDate IS NULL
-
-yacht_notes                   -- mirrors client_notes shape
-  id, yachtId (FK CASCADE), authorId, content, mentions text[], isLocked, createdAt, updatedAt
-
-yacht_tags
-  yachtId, tagId              composite PK; tagId references system.tags.id
-
-companies
-  id                          text PK
-  portId                      text NOT NULL FK → ports.id
-  name                        text NOT NULL
-  legalName                   text
-  taxId                       text
-  registrationNumber          text
-  incorporationCountry        text
-  incorporationDate           date
-  status                      text NOT NULL DEFAULT 'active'  -- 'active' | 'dissolved'
-  billingEmail                text
-  notes                       text
-  archivedAt                  timestamptz
-  createdAt                   timestamptz NOT NULL DEFAULT now()
-  updatedAt                   timestamptz NOT NULL DEFAULT now()
-  Indexes:
-    idx_companies_port         on (portId)
-    idx_companies_name_unique  UNIQUE on (portId, lower(name))  -- case-insensitive
-    idx_companies_taxid        on (portId, taxId) WHERE taxId IS NOT NULL
-
-company_memberships
-  id                          text PK
-  companyId                   text NOT NULL FK → companies.id ON DELETE CASCADE
-  clientId                    text NOT NULL FK → clients.id ON DELETE CASCADE
-  role                        text NOT NULL  -- 'director' | 'officer' | 'broker' | 'representative' | 'legal_counsel' | 'employee' | 'shareholder' | 'other'
-  roleDetail                  text            -- free-text qualifier: "Managing Director", "Exclusive Broker"
-  startDate                   date NOT NULL
-  endDate                     date            -- NULL = active
-  isPrimary                   boolean NOT NULL DEFAULT false
-  notes                       text
-  createdAt                   timestamptz NOT NULL DEFAULT now()
-  updatedAt                   timestamptz NOT NULL DEFAULT now()
-  Indexes:
-    idx_cm_company             on (companyId)
-    idx_cm_client              on (clientId)
-    idx_cm_active (partial)    on (companyId, clientId) WHERE endDate IS NULL
-    unique_cm_exact            UNIQUE on (companyId, clientId, role, startDate)
-
-company_addresses             -- mirrors client_addresses shape with companyId FK
-company_notes                 -- mirrors client_notes shape with companyId FK
-company_tags
-  companyId, tagId            composite PK
-
-berth_reservations
-  id                          text PK
-  berthId                     text NOT NULL FK → berths.id
-  portId                      text NOT NULL FK → ports.id
-  clientId                    text NOT NULL FK → clients.id  -- contract holder
-  yachtId                     text NOT NULL FK → yachts.id   -- which yacht occupies the slip
-  interestId                  text FK → interests.id          -- nullable link back to originating interest
-  status                      text NOT NULL  -- 'pending' | 'active' | 'ended' | 'cancelled'
-  startDate                   date NOT NULL
-  endDate                     date            -- NULL = open-ended
-  tenureType                  text NOT NULL DEFAULT 'permanent'  -- 'permanent' | 'fixed_term' | 'seasonal'
-  contractFileId              text FK → files.id
-  createdBy                   text NOT NULL
-  createdAt                   timestamptz NOT NULL DEFAULT now()
-  updatedAt                   timestamptz NOT NULL DEFAULT now()
-  Indexes:
-    idx_br_berth               on (berthId)
-    idx_br_client              on (clientId)
-    idx_br_yacht               on (yachtId)
-    idx_br_active (partial)    UNIQUE on (berthId) WHERE status = 'active'
-```
-
-### Modified tables
-
-```
-clients
-  DROP COLUMN yachtName, yachtLengthFt, yachtWidthFt, yachtDraftFt,
-              yachtLengthM, yachtWidthM, yachtDraftM, berthSizeDesired
-  DROP COLUMN companyName
-  DROP COLUMN isProxy, proxyType, actualOwnerName, relationshipNotes
-  (retains: fullName, nationality, preferredContactMethod, preferredLanguage,
-   timezone, source, sourceDetails, archivedAt, createdAt, updatedAt)
-
-interests
-  ADD COLUMN yachtId  text FK → yachts.id  -- nullable initially; enforced non-null before pipeline_stage leaves 'open'
-  ADD INDEX idx_interests_yacht on (yachtId)
-
-berth_waiting_list
-  ADD COLUMN yachtId  text FK → yachts.id
-
-invoices
-  ADD COLUMN billingEntityType  text NOT NULL  -- 'client' | 'company'
-  ADD COLUMN billingEntityId    text NOT NULL
-  (clientName column kept as immutable snapshot — must never auto-update)
-  ADD INDEX idx_invoices_billing_entity on (portId, billingEntityType, billingEntityId)
-
-files
-  ADD COLUMN yachtId    text FK → yachts.id    -- nullable
-  ADD COLUMN companyId  text FK → companies.id -- nullable
-  (existing clientId stays nullable; a file links to one of: client, yacht, or company)
-
-documents
-  ADD COLUMN yachtId    text FK → yachts.id    -- nullable
-  ADD COLUMN companyId  text FK → companies.id -- nullable
-```
-
-### DB-level invariants
-
-| #   | Invariant                                        | Enforced by                                                                                                                             |
-| --- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| 1   | One active ownership row per yacht               | Partial unique index on `yacht_ownership_history(yachtId) WHERE endDate IS NULL`                                                        |
-| 2   | One active reservation per berth                 | Partial unique index on `berth_reservations(berthId) WHERE status = 'active'`                                                           |
-| 3   | Yacht always has a current owner                 | Both `currentOwnerType` and `currentOwnerId` NOT NULL; ownership row inserted atomically with yacht creation inside service transaction |
-| 4   | Company names unique per port (case-insensitive) | Unique index on `(portId, lower(name))`                                                                                                 |
-| 5   | Exact-duplicate memberships blocked              | Unique index on `(companyId, clientId, role, startDate)`                                                                                |
-
-### Service-layer invariants (not DB-enforceable due to polymorphic columns)
-
-| #   | Invariant                                                                                                                        | Enforced by                                               |
-| --- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| 6   | `yacht.currentOwnerType='client'` ↔ `currentOwnerId` references an existing row in `clients`; same for `'company'` ↔ `companies` | Zod validator + service-layer lookup before insert/update |
-| 7   | `yacht_ownership_history.ownerType/ownerId` consistent with the corresponding entity table                                       | Same as #6                                                |
-| 8   | `invoices.billingEntityType` + `billingEntityId` consistent with entity table                                                    | Same as #6                                                |
-| 9   | `files.clientId`, `files.yachtId`, `files.companyId` — exactly one of the three must be non-null if the file is entity-scoped    | Service-layer validation on insert/update                 |
-
-### Drizzle relations (`relations.ts`)
-
-All new tables wire into the relations map. Notable additions:
-
-- `clientsRelations`: `companyMemberships` (many), `ownedYachts` (many, via polymorphic query), `berthReservations` (many)
-- `yachtsRelations`: `port` (one), `ownershipHistory` (many), `notes` (many), `tags` (many), `interests` (many), `reservations` (many), `documents` (many)
-- `companiesRelations`: `port` (one), `memberships` (many), `addresses` (many), `notes` (many), `tags` (many), `documents` (many)
-- `berthReservationsRelations`: `berth`, `port`, `client`, `yacht`, `interest`, `contractFile`
-
-## Service layer and API
-
-### New services (`src/lib/services/`)
-
-| File                             | Key functions                                                                                                                                                                                                                            |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `yachts.service.ts`              | `list`, `getById`, `create`, `update`, `archive`, `transferOwnership(yachtId, newOwnerType, newOwnerId, effectiveDate, reason, notes)` — atomic: closes current history row, opens new row, updates denormalized `currentOwner*` columns |
-| `companies.service.ts`           | `list`, `getById`, `create`, `update`, `archive`, `upsertByName(portId, name)` (case-insensitive, for autocomplete)                                                                                                                      |
-| `company-memberships.service.ts` | `addMembership`, `endMembership(id, endDate)`, `updateMembership`, `listByCompany`, `listByClient`, `setPrimary`                                                                                                                         |
-| `berth-reservations.service.ts`  | `createPending`, `activate(id)` (gates on partial unique index), `end(id, endDate)`, `cancel(id)`, `listByBerth`, `listByClient`, `listByYacht`                                                                                          |
-
-### Modified services
-
-| File                                 | Change                                                                                                                                                                                                                               |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `clients.service.ts`                 | Strip yacht/company/proxy field handling from create/update paths                                                                                                                                                                    |
-| `interests.service.ts`               | Accept `yachtId`; validate yacht is owned by the interest's client OR by a company the client actively represents. Promote-to-stage helpers require `yachtId` non-null before leaving `'open'`                                       |
-| `berths.service.ts`                  | Read reservation state via `berth_reservations` instead of deriving from `berths.status`. Reservation state changes also update `berths.status` via trigger-in-service-layer                                                         |
-| `invoices.service.ts`                | Accept `billingEntityType` + `billingEntityId`; snapshot the entity's current display name into `clientName` at creation (immutable afterward)                                                                                       |
-| `search.service.ts`                  | Extend to yachts and companies; include yacht name, hull number, registration in search index; include company name, legal name, taxId                                                                                               |
-| `recommendations.ts` (berth matcher) | Pull yacht dimensions from `yachts` table via `interest.yachtId` instead of from `clients.yacht*`                                                                                                                                    |
-| `document-templates.ts`              | Update `MERGE_FIELDS` catalog: deprecate `{{client.yachtName}}`, `{{client.companyName}}` and old yacht dimension tokens; add `{{yacht.*}}`, `{{company.*}}`, `{{owner.*}}` scopes. Update `resolveTemplate()` to resolve new scopes |
-| `portal.service.ts`                  | Portal user dashboards surface their yachts (owned + represented via memberships), their active memberships, and their active berth reservations                                                                                     |
-
-### New REST endpoints
-
-```
-# Yachts
-GET    /api/v1/yachts
-POST   /api/v1/yachts
-GET    /api/v1/yachts/:id
-PATCH  /api/v1/yachts/:id
-DELETE /api/v1/yachts/:id                      — archive (soft delete)
-POST   /api/v1/yachts/:id/transfer             — ownership transfer
-GET    /api/v1/yachts/:id/ownership-history
-GET    /api/v1/yachts/autocomplete?q=…
-
-# Companies
-GET    /api/v1/companies
-POST   /api/v1/companies
-GET    /api/v1/companies/:id
-PATCH  /api/v1/companies/:id
-DELETE /api/v1/companies/:id                   — archive
-GET    /api/v1/companies/autocomplete?q=…
-
-# Company memberships
-GET    /api/v1/companies/:id/members
-POST   /api/v1/companies/:id/members
-PATCH  /api/v1/companies/:id/members/:mid
-DELETE /api/v1/companies/:id/members/:mid      — sets endDate
-
-# Berth reservations
-GET    /api/v1/berths/:id/reservations
-POST   /api/v1/berths/:id/reservations         — create pending
-PATCH  /api/v1/berth-reservations/:id          — state transitions
-```
-
-### Modified endpoints
-
-- `GET /api/v1/clients/:id` — response now includes nested `yachts` (owned + represented), `companies` (via active memberships), `activeReservations`
-- `POST /api/v1/clients` — no longer accepts yacht/company/proxy fields
-- `POST /api/v1/interests` — requires `yachtId`
-- `POST /api/v1/invoices` — requires `billingEntityType` + `billingEntityId`
-- `POST /api/public/interests` — creates new `client` + `yacht` + optional `company` + `membership` + `interest` in one transaction, all marked `source: 'public_submission'`. No dedup against existing records (anonymous trust boundary).
-
-### Permissions (new keys)
-
-```
-yachts:view
-yachts:write
-yachts:transfer                  — higher-stakes operation, separate from :write
-yachts:delete                    — archive permission
-
-companies:view
-companies:write
-companies:delete
-
-memberships:write                — covers both directions of company_memberships
-
-reservations:view
-reservations:write
-```
-
-Existing role updates:
-
-- `admin` — all new keys
-- `team_lead` — `yachts:view`, `yachts:write`, `companies:view`, `companies:write`, `memberships:write`, `reservations:view`; NOT `yachts:transfer` or `reservations:write`
-- `front_desk` — all `:view` keys
-
-### Socket / webhook events (new)
-
-```
-yacht.created
-yacht.updated
-yacht.ownership_transferred
-yacht.archived
-company.created
-company.updated
-company.archived
-company_membership.added
-company_membership.ended
-berth_reservation.created
-berth_reservation.activated
-berth_reservation.ended
-berth_reservation.cancelled
-```
-
-Webhook event map in `src/lib/services/webhooks.ts` gains the same list.
-
-## EOI template strategy (dual-path)
-
-Both paths fully supported from day one. Required to mitigate handoff risk — if Documenso breaks or is replaced, the in-app path is the fallback.
-
-### Shared payload builder
-
-```ts
-// src/lib/services/eoi-context.ts
-export async function buildEoiContext(interestId: string): Promise<EoiContext>
-
-type EoiContext = {
-  client:   { fullName; nationality; primaryEmail; primaryPhone; address; … }
-  yacht:    { name; lengthFt; widthFt; draftFt; hullNumber; flag; yearBuilt; … }    // via interest.yachtId
-  company:  { name; legalName; taxId; billingAddress } | null                        // if yacht owner is a company
-  owner:    { type: 'client' | 'company'; name; … }                                  // polymorphic current owner
-  berth:    { mooringNumber; area; lengthFt; price; priceCurrency; tenureType; … }
-  interest: { stage; leadCategory; dateFirstContact; notes; … }
-  port:     { name; defaultCurrency; legalEntity; … }
-  date:     { today; year }
-}
-```
-
-Both paths consume this. Guarantees the two rendering engines see the same data and stay in sync as schema evolves.
-
-### Path A — Documenso template
-
-- Documenso hosts the template, referenced by ID via env var `DOCUMENSO_TEMPLATE_ID` (matches the old system's `NUXT_DOCUMENSO_TEMPLATE_ID` pattern — a single global template ID; per-port templates are a future extension if needed)
-- Payload builder flattens `EoiContext` into Documenso's field-name format, POSTs to `/api/v1/templates/{id}/generate-document`
-- Signing flow unchanged: Documenso emails signers, webhook updates status in our DB
-- Mitigation for "Documenso's template expects specific field names": one-time audit mapping every field name expected by `templateId=8` (from the old system) to a source in the new schema
-
-### Path B — In-app PDF template
-
-- Seed a "Standard EOI" HTML template into `document_templates` table on first boot. Template references tokens: `{{client.fullName}}`, `{{yacht.name}}`, `{{yacht.lengthFt}}`, `{{company.name}}`, `{{berth.mooringNumber}}`, `{{interest.dateFirstContact}}`, etc.
-- `resolveTemplate()` substitutes tokens from `EoiContext`
-- `pdfme` renders the resolved HTML to PDF
-- **Signing**: generated PDF is uploaded to Documenso via existing `documensoCreate` + `documensoSend` — Documenso supports signing ad-hoc PDFs (not just its own templates). Signing experience identical to Path A from the signer's perspective.
-- **Fallback**: if Documenso is unavailable, the PDF can be emailed to the signer via `nodemailer` as a manual fallback (flag in UI, not auto-fallback)
-
-### UI picker
-
-Generate-EOI dialog adds a Template dropdown:
-
-```
-Template: [ Documenso — Standard EOI                    v ]
-          [ Documenso — Standard EOI                      ]
-          [ In-app — Standard EOI                         ]
-          [ In-app — (any custom template user authored)  ]
-```
-
-Explicit picker chosen over automatic fallback: misconfiguration is visible, not silently masked — important for handoff.
-
-## UI impact
-
-### New pages
-
-| Route                               | Purpose                                                                                     |
-| ----------------------------------- | ------------------------------------------------------------------------------------------- |
-| `/[portSlug]/yachts`                | List view: name, dimensions, current owner, status. Filters by owner type, size, status     |
-| `/[portSlug]/yachts/[yachtId]`      | Detail — Tabs: Overview, Ownership History, Interests, Reservations, Documents, Notes, Tags |
-| `/[portSlug]/companies`             | List view: name, legal name, # members, # owned yachts                                      |
-| `/[portSlug]/companies/[companyId]` | Detail — Tabs: Overview, Members, Owned Yachts, Addresses, Documents, Notes, Tags           |
-
-### Modified pages
-
-| Page                                                  | Change                                                                                                                                      |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `client-form`                                         | Remove yacht / companyName / proxy fields. Becomes a clean "person" form. Yacht and company associations managed from detail page, not here |
-| `client-detail`                                       | Add tabs: Yachts (owned + represented), Companies (active memberships), Reservations                                                        |
-| `client-columns`                                      | Replace yacht/company text columns with "# yachts" and "Primary company" (from active memberships marked `isPrimary`)                       |
-| `interest-form`                                       | New required field: yacht picker, constrained to client's yachts (with inline "Add new yacht" option)                                       |
-| `interest-detail`                                     | Display yacht prominently; berth recommendations match against yacht dimensions                                                             |
-| `berth-detail`                                        | New tab: Reservations. Shows active reservation + history. "Reserve this berth" button opens reservation dialog                             |
-| `invoice-form`                                        | New billing-entity picker (client or company toggle + autocomplete); `clientName` snapshot populates automatically                          |
-| `eoi-generate-dialog`                                 | New template-picker dropdown (per dual-path strategy)                                                                                       |
-| Global search                                         | Extended to yachts and companies                                                                                                            |
-| Sidebar                                               | Adds "Yachts" and "Companies" entries. Reservations lives inside the Berths page                                                            |
-| `/api/public/interest` form (new interest submission) | Captures yacht + company sub-forms; creates new trio on submission                                                                          |
-
-### Portal pages
-
-- Dashboard: shows owned + represented yachts, active memberships, active reservations
-- New "My Yachts" tab — read-only yacht detail scoped to ones user owns or represents
-- New "My Reservations" tab
-- Authenticated interest submissions create yacht row linked to the portal user (not anonymous)
-
-### New components (`src/components/`)
-
-```
-yachts/
-  yacht-form.tsx
-  yacht-detail.tsx
-  yacht-detail-header.tsx
-  yacht-tabs.tsx
-  yacht-columns.tsx
-  yacht-picker.tsx
-  yacht-ownership-history.tsx
-  yacht-transfer-dialog.tsx
-companies/
-  company-form.tsx
-  company-detail.tsx
-  company-detail-header.tsx
-  company-tabs.tsx
-  company-columns.tsx
-  company-picker.tsx
-  company-members-tab.tsx
-  company-owned-yachts-tab.tsx
-  add-membership-dialog.tsx
-reservations/
-  reservation-form.tsx
-  reservation-list.tsx
-  berth-reserve-dialog.tsx
-shared/
-  owner-picker.tsx                 — polymorphic client|company autocomplete
-  billing-entity-picker.tsx
-```
-
-All follow existing `shadcn/ui` + CVA + react-hook-form + zod pattern.
-
-### Seeder (`src/lib/db/seed.ts`) — rewrite
-
-Produces realistic multi-cardinality fixtures:
-
-- 3 companies (two with multiple members, one dissolved with an `endDate` on all memberships)
-- 8 clients (some personal-only, some with company memberships, at least one representing multiple companies)
-- 12 yachts (mix of client-owned and company-owned; 2-3 with ownership-transfer history)
-- Interests linking clients ↔ yachts ↔ berths with realistic pipeline-stage distribution
-- A handful of active berth reservations + a few ended/cancelled ones
-- Rich contact / address / membership / ownership-history data covering every test scenario
-
-Seeder shares factory helpers with tests (`tests/helpers/factories.ts`).
-
-## Testing strategy
-
-### Coverage targets (CI-enforced)
-
-| Tier          | Target              |
-| ------------- | ------------------- |
-| Service layer | ≥ 90% line coverage |
-| Validators    | 100% line coverage  |
-| API routes    | ≥ 85% line coverage |
-| Overall       | ≥ 85% line coverage |
-
-Hard rules: no skipped tests on `main`; no PR merge without green CI on all tiers.
-
-### Tier 1 — Unit tests (Vitest)
-
-- Every new service function: happy path, each validation failure, each precondition failure, tenant-scoping
-- Merge-field resolver: every new token resolves correctly across each context shape
-- Validators: every zod schema tested for pass + fail on each field
-
-### Tier 2 — Integration tests (Vitest + Postgres via docker-compose test DB)
-
-- Migration up/down correctness
-- Partial unique indexes (`berth_reservations(berthId) WHERE status='active'`, `yacht_ownership_history(yachtId) WHERE endDate IS NULL`) reject duplicate inserts
-- FK cascades: deleting a client cascades contacts/addresses; yacht-with-this-owner is BLOCKED from being lost
-- Atomic `transferOwnership`: concurrent retries result in consistent state
-- Polymorphic integrity checks: `yacht.currentOwnerType='client'` with a companyId is rejected by service-layer validation
-- Company name case-insensitive uniqueness
-- Every new API route: auth → permission → service → DB → response shape
-
-### Tier 3 — E2E scenario tests (Playwright)
-
-Full-lifecycle flows:
-
-1. Create client → add yacht → create interest → generate EOI (Documenso path) → PDF in MinIO
-2. Same, in-app template path → verify PDF content contains expected yacht name
-3. Create company → add two clients as members → create yacht owned by company → generate invoice billed to company
-4. Yacht transfer: client-owned → company-owned; verify history + denormalized column + UI
-5. Reserve berth: create → verify visible → attempt duplicate reservation → blocked
-6. Public interest form → admin sees new client+yacht+company+interest trio
-7. (Spec 3 stub): merge flow tested end-to-end in Spec 3
-
-Multi-cardinality flows (the core justification for this refactor):
-
-8. One client with 3 yachts, 3 interests, 3 different berths — all representable
-9. One person as broker for 2 companies, each owning 1 yacht — memberships + owned yachts visible from client detail
-
-Portal flows:
-
-10. Portal user views "my yachts" — sees only owned/represented
-11. Portal user submits interest — new yacht linked to their identity
-
-### Tier 3.5 — Exhaustive Playwright click-through suite
-
-Location: `tests/e2e/exhaustive/`. Separate CI job (15-20 min, runs in parallel with other tiers, blocks merge if failing).
-
-Spec files: `yachts`, `companies`, `reservations`, `client-detail-refactored`, `eoi-generate`, `invoice-form`, `berths-with-reservations`, `portal`, `navigation`.
-
-Per-page logic:
-
-1. Navigate to page
-2. Enumerate every interactive element (`button`, `a`, `[role="button"]`, `[data-testid]`, form inputs)
-3. Click/fill each; post-click: assert no console errors, no 4xx/5xx network responses, UI returns to stable state
-4. Coverage assertion: elements clicked ≥ total elements on page (minus declared destructive-action allowlist)
-
-Helper: `tests/helpers/click-everything.ts` exports `clickEverythingOnPage(page, opts)`.
-
-Destructive actions allowlist (tested separately with create-then-destroy isolation):
-
-```
-yachts.delete, yachts.archive, yachts.transferOwnership
-companies.delete, companies.archive
-companyMemberships.end
-berthReservations.cancel, berthReservations.end
-invoices.delete
-```
-
-Acceptance criteria for Spec 1 completion:
-
-- Every new or changed page has 100% coverage in the exhaustive suite (minus allowlist)
-- Every allowlist entry has its own narrow destructive test
-- Zero console errors across the full suite
-- Zero unexpected 4xx/5xx responses
-
-### Tier 4 — EOI template regression
-
-- **Documenso payload snapshot test**: mock Documenso API; assert POST body contains every expected field name with correct value sourced from new schema
-- **In-app template rendering test**: render seeded template against each scenario's context; assert resolved HTML contains expected substrings; assert `pdfme` produces a non-empty PDF
-- **Visual diff**: render in-app EOI to PDF, compare against committed golden-image PDFs per scenario; regressions surface as image diffs in PR
-- **Error paths**: missing yacht, missing company with company-owned yacht reference, missing config (Documenso API key missing) — all produce explicit errors, not silent blanks
-
-### Tier 5 — Security tests
-
-- Cross-tenant isolation: yacht/company/reservation in port A invisible/unmodifiable from port B
-- Permission enforcement: user without `yachts:write` cannot `POST /yachts`; `yachts:transfer` required for transfer endpoint
-- Portal authorization: portal user cannot see yachts they don't own/represent
-- Public interest endpoint: anonymous submitter cannot read existing records
-
-### Test infrastructure
-
-Fixture factories in `tests/helpers/factories.ts`:
-
-```
-makeYacht({ owner: client|company, ...overrides })
-makeCompany({ overrides })
-makeMembership({ client, company, role, ...overrides })
-makeOwnershipHistoryRow({ yacht, owner, startDate, endDate })
-makeReservation({ berth, client, yacht, status })
-```
-
-Scenario builders produce Tier 3 multi-cardinality setups in a single call.
-
-Integration tests run against a fresh migrated DB; each test file wraps in a transaction that rolls back OR uses per-file schema isolation.
-
-## Rollout plan
-
-Green-field Postgres DB — no dual-write, no phased migration needed. Concern is only sequencing so the working tree never enters a broken half-migrated state.
-
-### PR sequence (≈ 15 PRs, feature branch `refactor/data-model`)
-
-| #   | PR                                                                                                  | Depends on   |
-| --- | --------------------------------------------------------------------------------------------------- | ------------ |
-| 1   | Schema migration: add all new tables, leave old client columns in place                             | —            |
-| 2   | Service layer: new services (yachts, companies, memberships, reservations)                          | 1            |
-| 3   | API routes for new services + new permissions                                                       | 2            |
-| 4   | Seeder rewrite with multi-cardinality fixtures                                                      | 2            |
-| 5   | UI: yacht list + detail + form + picker + ownership-history + transfer-dialog                       | 3            |
-| 6   | UI: company list + detail + form + picker + memberships tab + add-membership dialog                 | 3            |
-| 7   | UI: berth reservations tab + reserve dialog + ownership-transfer wiring                             | 3            |
-| 8   | Client form refactor: strip yacht/company/proxy fields, add nav links to yachts/companies           | 5, 6         |
-| 9   | Interest form: require `yachtId` + public interest form creates trio                                | 5            |
-| 10  | Invoice billing-entity support (client or company)                                                  | 6            |
-| 11  | EOI shared payload builder + seed in-app Standard EOI template + dual-path dialog                   | 5, 6         |
-| 12  | Merge-field catalog update + resolver extension for `{{yacht.*}}` / `{{company.*}}` / `{{owner.*}}` | 11           |
-| 13  | Drop old columns from `clients` (`yacht*`, `companyName`, proxy fields)                             | 8, 9, 10, 11 |
-| 14  | Exhaustive Playwright click-through suite (Tier 3.5)                                                | 13           |
-| 15  | Documentation updates (CLAUDE.md, numbered spec files 01-15, API catalog)                           | 13           |
-
-After PR 15, merge the feature branch into `main` as one final PR.
-
-## Risks and mitigations
-
-| Risk                                                                                               | Severity  | Mitigation                                                                                                                                  |
-| -------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Spec 2 (importer) depends on final schema; mid-development schema churn → rework                   | High      | Schema freeze after PR 1 lands; amendments require deliberate spec update                                                                   |
-| Polymorphic owner columns have no DB-level FK — service-layer bug could insert inconsistent owner  | Medium    | Service-layer validation + integration test for every create/update path; runtime assertion in `buildEoiContext`                            |
-| EOI dual-template drift (two engines produce subtly different output)                              | Medium    | Golden-image visual-diff tests in Tier 4, CI-gated                                                                                          |
-| Documenso template at `templateId=8` expects specific field names — new payload builder must match | Medium    | One-time audit: document every field the existing template expects; map each to a source in new schema; Spec 2's importer uses same mapping |
-| Old `client-portal/` sub-repo coordination during Spec 2 cutover                                   | Low       | Confirm old client-portal is decommissioned at Spec 2 cutover (not running concurrently against shared data)                                |
-| Seeder becomes dev-onboarding bottleneck                                                           | Low       | Seeder uses same factory helpers as tests — code path shared + tested                                                                       |
-| Documentation rot in numbered spec files                                                           | Low       | PR 15 updates them before the feature branch merges to `main`                                                                               |
-| Exhaustive-click-suite runtime (15-20 min per PR)                                                  | Low       | Separate CI job, runs in parallel with other tiers                                                                                          |
-| Handoff quality — "EOIs don't work" / "I can't see my yachts"                                      | Addressed | Dual template paths + exhaustive click coverage + golden-image diff + template regression tests collectively mitigate                       |
-
-## Open questions / deferred items
-
-Explicitly out of scope for this spec:
-
-- Yacht survey / class-cert document categorization (requires taxonomy work)
-- Multi-level company hierarchy (holding → subsidiary) — additive later
-- Invoice line items referencing specific yacht
-- Berth reservation auto-renewal flow
-- Per-yacht row-level permissions (e.g., "broker can only see yachts they represent")
-- Portal branding per company
-
-## Success criteria
-
-Spec 1 is complete when:
-
-1. All PRs in the sequence are merged to `main`
-2. CI is green: all coverage gates met, zero skipped tests, exhaustive click-through suite passes
-3. Manual verification: developer walks through every multi-cardinality scenario in Tier 3 E2E list against a dev build
-4. Both EOI paths produce documents that match the current system's outputs (visual verification + golden images committed)
-5. Documentation (CLAUDE.md + numbered spec files) updated
-6. Spec 2 (NocoDB+MinIO importer) can begin against a frozen schema

docs/superpowers/specs/2026-04-28-country-phone-timezone-design.md

@@ -1,171 +0,0 @@
-# Country / Phone / Timezone — i18n form polish
-
-**Status:** Agenda — awaiting prioritization (likely Phase B or B.5)
-**Date:** 2026-04-28
-**Phase:** Cross-cutting; touches every form that captures contact data
-
-## Why
-
-Today every CRM form takes free-text strings for nationality, phone, and timezone. That's fine for a marina with one operator typing it in once, but it leaks operator inconsistencies into reports and breaks any later system that consumes these fields (Documenso prefill, public website inquiry, portal sync, exports). For a multi-port platform that's about to onboard non-Polish-speaking residential clients, the data quality matters.
-
-Three coupled UX upgrades:
-
-1. **Nationality → ISO-3166 country dropdown.** Searchable. Stores ISO alpha-2 code (`'GB'`), displays localized country name.
-2. **Phone → country-code dropdown + format-as-you-type.** E.164 storage on the wire, formatted display per country.
-3. **Timezone → autofilled from country with override dropdown.** Most countries are single-zone; the few that aren't (US, RU, AU, BR, CA, ID, KZ, MN, MX, CD) get a sub-select. Stores IANA TZ string (`'Europe/Warsaw'`).
-
-## Scope
-
-### In scope
-
-- New shared primitives: `<CountryCombobox>`, `<PhoneInput>`, `<TimezoneCombobox>`
-- ISO-3166 country list bundled (no API call); names from `Intl.DisplayNames` with locale fallback to English
-- Country → primary IANA timezone map (~250 entries, JSON)
-- Phone parsing/validation/formatting via `libphonenumber-js` (server + client)
-- Wire into every form that captures contact data:
-  - `<ClientForm>` (name, nationality, phone)
-  - `<ResidentialClientDetail>` inline editor (nationality, phone, place_of_residence — country-aware)
-  - `<CompanyForm>` (incorporation_country)
-  - `<PortalActivateForm>` (phone)
-  - public inquiry form (form-template renderer, when phone field present)
-- DB migration: store ISO codes (`countries`, `nationality_iso`), E.164 phone (`phone_e164`), IANA timezone (`timezone`)
-- Backfill: best-effort parse existing free-text into the new columns; keep originals as `_legacy` for one release cycle
-- Display: localized country name in tables/detail pages; phone formatted per country (e.g. `+44 20 7946 0958`); timezone shown as friendly `'London (UTC+1)'` when current
-- Tests: unit (parser edge cases), integration (form submit → E.164 storage), smoke (typing + selecting flows)
-
-### Out of scope (deferred)
-
-- Multilingual UI surface (only the country _names_ localize via `Intl.DisplayNames`; rest of the UI stays English for now)
-- Subdivision picker (states/provinces) — only top-level country
-- Phone number geocoding / carrier lookup
-- Address autocomplete (Google Places, etc.)
-- Currency localization
-- RTL layout
-
-## Library choices
-
-| Concern                     | Library                                                                                                        | Why                                                                                                                                                                                   |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Phone input + flag dropdown | `omeralpi/shadcn-phone-input`                                                                                  | Built on shadcn-ui's `Input` primitive (zero styling friction with our component library), wraps `libphonenumber-js`, ships with country dropdown + format-as-you-type. Small bundle. |
-| Phone parsing/validation    | `libphonenumber-js`                                                                                            | Google's library, ~88 benchmark, used by every popular React phone input. Server-side validation in zod.                                                                              |
-| Country list                | Bundled JSON of ISO-3166 alpha-2 codes + 3-letter codes + display names (English baseline)                     | No need for the heavier `country-state-city` databases — we don't need cities or states yet.                                                                                          |
-| Country → timezone          | Hand-curated `country-timezones.json` (250 entries, ~10kb) sourced from `country-tz` or moment-timezone's data | Static, no network call. For multi-zone countries, expose a sub-select.                                                                                                               |
-| Timezone formatting         | `Intl.DateTimeFormat` (built-in)                                                                               | Browser API; renders `'Europe/Warsaw (UTC+1)'`-style labels.                                                                                                                          |
-| Timezone list               | `Intl.supportedValuesOf('timeZone')` (built-in, ~600 entries)                                                  | Used as the override dropdown when a user wants a non-primary zone.                                                                                                                   |
-
-Bundle impact: `libphonenumber-js` mobile build is ~80 KB gz; `shadcn-phone-input` is ~5 KB; country/timezone JSONs ~30 KB. All client-side, lazy-loaded on first form render via `next/dynamic`.
-
-## Schema deltas
-
-```sql
--- clients
-ALTER TABLE clients ADD COLUMN nationality_iso text;          -- 'GB'
-ALTER TABLE clients ADD COLUMN timezone text;                  -- 'Europe/London'
--- existing 'nationality' free-text column stays for a release; new code reads ISO
-
--- client_contacts (or wherever phone lives)
-ALTER TABLE client_contacts ADD COLUMN value_e164 text;        -- '+442079460958'
-ALTER TABLE client_contacts ADD COLUMN value_country text;     -- 'GB' (where the number was parsed against)
--- existing 'value' stays as the human-displayable formatted form
-
--- residential_clients — same pattern
-ALTER TABLE residential_clients ADD COLUMN nationality_iso text;
-ALTER TABLE residential_clients ADD COLUMN timezone text;
-ALTER TABLE residential_clients ADD COLUMN phone_e164 text;
-ALTER TABLE residential_clients ADD COLUMN phone_country text;
-
--- companies
-ALTER TABLE companies ADD COLUMN incorporation_country_iso text;
-```
-
-Indexes: `idx_clients_nationality_iso`, `idx_clients_timezone` (cheap; powers analytics filters later).
-
-## Component primitives
-
-```tsx
-<CountryCombobox
-  value={iso}                    // 'GB' | undefined
-  onChange={(iso) => …}
-  locale="en"                    // for name lookup; default to navigator.language
-  variant="default" | "compact"  // compact = icon-only flag, default = name
-/>
-
-<PhoneInput
-  value={e164}                   // '+442079460958'
-  onChange={({ e164, country }) => …}
-  defaultCountry={'GB'}          // pre-selects the dropdown
-  required={false}
-/>
-
-<TimezoneCombobox
-  value={iana}                   // 'Europe/London'
-  onChange={(iana) => …}
-  countryHint={'GB'}             // when set, narrows the dropdown to matching zones first
-/>
-```
-
-All three are shadcn-styled, keyboard-accessible, support form integration with react-hook-form + zod.
-
-## Validators
-
-```ts
-// src/lib/validators/contact.ts
-import { isValidPhoneNumber } from 'libphonenumber-js';
-
-export const phoneE164Schema = z
-  .string()
-  .refine((v) => isValidPhoneNumber(v), 'Invalid phone number');
-
-export const isoCountrySchema = z
-  .string()
-  .length(2)
-  .toUpperCase()
-  .refine((c) => ISO_COUNTRIES.has(c), 'Unknown country');
-
-export const ianaTimezoneSchema = z
-  .string()
-  .refine((tz) => Intl.supportedValuesOf('timeZone').includes(tz), 'Unknown timezone');
-```
-
-## Backfill plan
-
-A migration script (`scripts/backfill-iso-and-e164.ts`) that:
-
-1. For each client/residential_client, attempt `libphonenumber-js` `parsePhoneNumber(rawPhone, { defaultCountry: 'PL' })` → if valid, write `phone_e164` + `phone_country`.
-2. For each free-text `nationality`, fuzzy-match against the country name list (exact match first, then Levenshtein ≤2). Write `nationality_iso` if confident.
-3. For each timezone, exact-match against IANA list. Otherwise leave null and let user fill it.
-4. Log unparseable rows to `backfill-iso-report.csv` for manual review.
-
-Run on staging first; require dry-run flag.
-
-## Build sequence
-
-| #   | PR                                                           | Effort | Depends on |
-| --- | ------------------------------------------------------------ | ------ | ---------- |
-| 1   | Country list JSON + ISO sets + `<CountryCombobox>` primitive | 0.5d   | —          |
-| 2   | `libphonenumber-js` integration + `<PhoneInput>` primitive   | 1d     | —          |
-| 3   | Country → timezone JSON + `<TimezoneCombobox>` primitive     | 0.5d   | 1          |
-| 4   | Schema deltas + drizzle migrations + zod validators          | 0.5d   | —          |
-| 5   | Wire into ClientForm + ClientDetail inline editors           | 1d     | 1, 2, 3, 4 |
-| 6   | Wire into ResidentialClientDetail                            | 0.5d   | 5          |
-| 7   | Wire into CompanyForm                                        | 0.5d   | 1          |
-| 8   | Public inquiry form template renderer support                | 0.5d   | 2          |
-| 9   | Backfill script + dry-run runbook                            | 1d     | 4          |
-| 10  | Smoke + integration tests                                    | 1d     | 5–9        |
-
-Total: ~7 dev days. Self-contained; no external dependencies on Phase B (analytics/alerts).
-
-## Risk register
-
-| Risk                                                                              | Mitigation                                                                                     |
-| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| Bundle bloat from libphonenumber data                                             | Use the `mobile` metadata build, lazy-import via `next/dynamic`                                |
-| Existing free-text data is too messy to backfill                                  | Keep the legacy column for one release; expose a "needs review" badge in admin                 |
-| Multi-zone country UX confusion                                                   | Sub-select only appears when country is multi-zone; otherwise zone is hidden behind "Override" |
-| Public inquiry form breaks if phone is required and user can't find their country | Default to PL, search by country name and dial code                                            |
-
-## Open questions for the user
-
-- Which port's locale should drive the _default_ country in `<PhoneInput>` (Poland for now, or detect from browser)?
-- Should existing free-text `nationality` field be removed once backfilled, or kept indefinitely as a fallback?
-- Is there an appetite for adding the same treatment to subdivision (state/region/voivodship) selectors, or strictly country-level for now?

docs/superpowers/specs/2026-04-28-documents-hub-design.md

@@ -1,775 +0,0 @@
-# Documents Hub, Reservation Agreements, and Visual Polish (Phase A)
-
-**Status:** Draft — awaiting final review
-**Date:** 2026-04-28
-**Phase:** A of D (B = Insights & Alerts; C = Website integration; D = Pre-prod ops)
-
-## Overview
-
-Phase A delivers a unified Documents Hub that tracks every signature-based document (EOI, Reservation Agreements, NDAs, ad-hoc uploads), generalises the existing single-purpose EOI dialog into a multi-format create-document wizard, builds the missing CRM-side reservation detail page with an end-to-end agreement workflow, polishes the reminder framework so non-EOI docs auto-remind correctly, and applies a system-wide visual upgrade to the polished-SaaS aesthetic the project already has tokens for.
-
-The project already ships a usable CRM with auth, multi-tenancy, full client/yacht/company/interest/berth/reservation data model, an EOI dual-path (Documenso template + in-app PDF), socket-driven real-time updates, and 130 smoke specs. What's missing for the next release: a single place to see what documents need signing and chase the people who haven't signed.
-
-## Scope boundaries
-
-### In scope (this spec)
-
-- New `/[port]/documents` hub page replacing the existing list
-- New `/[port]/documents/[id]` document detail page
-- Generalised create-document wizard supporting four template formats (HTML, PDF AcroForm fillable, PDF overlay-positioned, Documenso-rendered) plus ad-hoc PDF upload
-- New `/[port]/berth-reservations/[id]` reservation detail page with agreement-generation flow
-- Reservation Agreement as a first-class document type with default template seeded
-- Email composer extended with attachments and a System-vs-User From selector (admin-gated)
-- Reminder framework: per-template cadence, per-doc override, per-doc disable, per-signer manual reminders
-- Documenso version-aware abstraction layer covering field placement and document voiding across v1.13.1 and v2.x
-- System-wide visual polish: shadow scale, gradient layer, animation tokens, primitive components (`<StatusPill>`, `<KPITile>`, `<EmptyState>`, polished `<PageHeader>`), applied across all list and detail pages
-- Mobile-responsive sweep across every page touched
-- Comprehensive test coverage: unit, integration, smoke, exhaustive click-through, real-API round-trips, visual baseline regeneration
-
-### Explicitly out of scope (deferred to later phases)
-
-- Analytics dashboard, alert framework, interests-by-berth view, expense duplicate detection (Phase B)
-- Website-side integration: `/api/form/[token]/data` prefill endpoint, `/api/webhook/document-signed` callback receiver, public-endpoint shape compat (Phase C)
-- NocoDB to Postgres data migration, email deliverability (DKIM/SPF/DMARC), Sentry error reporting, audit log retention, performance baseline at 5k clients / 50k interests, backup/restore automation, production deploy readiness (Phase D)
-- Native in-CRM PDF field-placement editor (deferred until upload-path pain emerges; Phase A v1 ships with auto-placed footer signature fields and a "Customize fields in Documenso" link)
-- Word `.docx` template upload (deferred; PDF prioritized because Word adds LibreOffice/CloudConvert toolchain dependency without saving the field-placement step)
-- Per-interest "silence all reminders" toggle (was implicit in old `interests.reminderEnabled` gating which this spec drops; can be re-added as a bulk action if anyone misses it)
-
-## Information architecture
-
-### URL surface
-
-```
-/[port]/documents                         hub (replaces existing list)
-/[port]/documents/[id]                    document detail (new)
-/[port]/documents/new                     create-document wizard (new)
-/[port]/berth-reservations/[id]           reservation detail (new)
-/[port]/admin/templates                   existing; extended for new template formats
-/[port]/admin/email                       existing; one new toggle
-```
-
-### Schema deltas
-
-```
-documents — additions:
-+ reservation_id          text     null  references berth_reservations(id)
-+ reminders_disabled      boolean  default false
-+ reminder_cadence_override int    null
-
-document_templates — additions:
-+ reminder_cadence_days   int      null     (null = no auto-reminders)
-+ template_format         text     default 'html'   ('html'|'pdf_form'|'pdf_overlay'|'documenso_render')
-+ source_file_id          text     null  references files(id)
-+ documenso_template_id   text     null
-+ field_mapping           jsonb    default '{}'   (pdf_form: { acroFieldName: mergeToken })
-+ overlay_positions       jsonb    default '[]'   (pdf_overlay: [{token, page, x, y, fontSize}])
-
-document_templates.body_html — relax to nullable (only required when template_format='html')
-
-document_watchers — new table:
-  document_id  text  not null  references documents(id) on delete cascade
-  user_id      text  not null  references users(id)
-  added_by     text  not null  references users(id)
-  added_at     timestamptz default now()
-  primary key (document_id, user_id)
-
-documents indexes — additions:
-+ idx_docs_reservation       on (reservation_id)
-+ idx_docs_status_port       on (port_id, status)        — powers tab counts cheaply
-
-document_watchers indexes:
-+ idx_doc_watchers_doc       on (document_id)
-+ idx_doc_watchers_user      on (user_id)
-
-documents.documentType enum — already includes 'reservation_agreement'; no migration needed
-documents.status enum — already accepts 'expired'; no migration needed
-documentSigners.status enum — pending|signed|declined; no migration needed
-```
-
-Backfill (one statement, safe to run in same migration):
-
-```sql
-UPDATE document_templates SET reminder_cadence_days = 1 WHERE template_type = 'eoi';
-```
-
-This preserves the existing 1-day-effective reminder cadence for existing EOI templates. Admins can edit per-template later.
-
-After running migration on a dev/staging server, restart `next dev` to flush postgres.js prepared-statement cache (existing project convention).
-
-### Polymorphic ownership pattern
-
-Documents already use the multi-FK pattern (`interest_id`, `client_id`, `yacht_id`, `company_id` as separate nullable columns). Adding `reservation_id` matches this. No conversion to polymorphic discriminator columns despite yachts and invoices using that pattern; staying consistent with the existing documents shape avoids a destructive migration.
-
-### Service-layer changes
-
-- `documents.service.ts`:
-  - `createFromWizard(portId, data, meta)` — dispatches across template/upload paths
-  - `createFromUpload(portId, data, meta)` — new upload-driven path; calls Documenso `createDocument`, stores file in MinIO via `files` service, mirrors to `documents` + `documentSigners`, optionally calls `sendDocument` if `sendImmediately`
-  - `cancelDocument(documentId, portId, meta)` — user-initiated cancel; calls Documenso void, updates DB status, logs event
-  - `composeSignedDocEmail(documentId, portId)` — returns prefilled `{ to, cc, subject, body, attachments, defaultSenderType }` for the composer
-  - `getDocumentDetail(id, portId)` — single-roundtrip aggregator returning doc + signers + events + watchers + linked-entity summary
-
-- `document-templates.ts`:
-  - `generateAndSign` extended for new `template_format` values
-  - `fillAcroForm(sourceFile, fieldMapping, mergeContext)` — pdf-lib AcroForm fill
-  - `drawOverlay(sourceFile, overlayPositions, mergeContext)` — pdf-lib text-draw at positions
-  - Documenso-render path uses existing `generateDocumentFromTemplate`
-
-- `documenso-client.ts`:
-  - `placeFields(docId, fields, portId?)` — version-aware bulk field placement
-  - `placeDefaultSignatureFields(docId, recipientIds, portId?)` — auto-position one SIGNATURE per recipient at footer
-  - `voidDocument(docId, portId?)` — version-aware doc void/delete
-  - Coordinate normalization helpers (caller passes percent 0-100; converted to pixels for v1 using cached page dimensions)
-
-- `document-reminders.ts`:
-  - `sendReminderIfAllowed(documentId, portId, options?)` — extended signature with optional `signerId` and `auto: boolean`
-  - `processReminderQueue(portId)` — query rewritten around `documents.reminder_cadence_override ?? template.reminder_cadence_days`; drops `interests.reminderEnabled` gating
-
-- `notifications.service.ts`:
-  - `notifyDocumentEvent(docId, eventType)` — fans out to creator + entity-assignee + watchers; existing socket events keep firing
-
-- New: `reservation-agreement-context.ts`:
-  - `buildReservationAgreementContext(reservationId, portId)` — joins reservation -> client + yacht + berth -> port; returns context shape for template merge
-
-- `email-compose.service.ts`:
-  - Validator extended: `{ senderType: 'system'|'user', accountId? (when user), attachments[] }`
-  - System path: calls `lib/email/index.ts → sendEmail()` with `portId` + attachments; logs `documentEvents` row `signed_doc_emailed`; skips `email_messages`/`email_threads` writes
-  - User path: existing flow, with attachments resolution from `files` table
-  - Port-isolation: cross-port `fileId` returns 403
-
-- `lib/email/index.ts`:
-  - `SendEmailOptions.attachments?: Array<{ fileId, filename? }>` — fetches files from MinIO, passes to nodemailer
-
-## Documents hub page
-
-Replaces existing `/[port]/documents` list.
-
-### Layout
-
-```
-[ Header strip: title, KPI sub-line, "+ New document" button ]
-
-[ Tabs: All | Awaiting them (count) | Awaiting me (count) | Completed | Expired ]
-
-[ Search · Type · Status · Sent · Watcher filter chips · saved-view selector · overflow ]
-
-[ Table:
-    checkbox | Document | Type pill | Subject pill | Status (X/Y signed + dot) | Sent
-    ▾ expand row inline to show signers + watchers strip
-]
-
-[ Sticky bulk-action bar appears when ≥1 row checked:
-    "N selected" | Remind unsigned | Cancel | Export | pagination
-]
-```
-
-### Tab queries
-
-- All — every document in port
-- Awaiting them — `status IN ('sent','partially_signed')` AND has pending signer != current user
-- Awaiting me — at least one `documentSigners` row matching `signer_email = current user email` AND `status = 'pending'`
-- Completed — `status IN ('completed','signed')`
-- Expired — `status = 'expired'` OR (`status IN ('sent','partially_signed')` AND `expires_at < now()`)
-
-Counts run cheap thanks to `idx_docs_status_port`.
-
-### Filters and saved views
-
-- Search: fuzzy match on title, subject name, signer email
-- Type: multi-select doc types
-- Status: multi-select status enum
-- Sent: date-range chips (Today, 7d, 30d, custom)
-- Watcher: filter by watching user
-- "Signature-based only" chip defaults to ON; toggle off to see non-signed docs (welcome letters etc.) as well, rendered with a "Delivered" pill
-- Saved-view integration: filter combos save to existing `saved_views` table
-
-### Row anatomy
-
-- Collapsed: name (links to detail), type pill (colored per type), subject pill (links to entity), status indicator (X/Y signed with progress dot), sent age
-- Expanded: per-signer rows with email, status pill, sent timestamp, signed timestamp, `[Remind]` and overflow `[...]` (resend invite, copy signing link, skip — skip is UI-only flag, not implemented in v1)
-- Watchers strip at bottom of expansion: chips + `+ Add watcher` autocomplete
-- Hover: row gets soft brand-soft gradient bg
-
-### Real-time
-
-Subscribes to existing `documents.service.ts`-emitted socket events: `document:created`, `document:updated`, `document:deleted`, `document:sent`, `document:completed`, `document:expired`, `document:cancelled`, `document:rejected`, `document:signer:signed`, `document:signer:opened`. All already fire today.
-
-### Empty states
-
-- No docs yet: illustration + 1-line explanation + `[+ New document]` CTA
-- Filtered empty: "No docs match these filters. Clear filters?"
-
-### Mobile (< 768px)
-
-- Tabs collapse into `<select>`
-- Filters collapse behind `[Filters]` button into a sheet
-- Rows stack as cards: title + status + age, expand to show signers
-- "+ New document" floats as FAB bottom-right
-
-## Document detail page
-
-New `/[port]/documents/[id]` page. No detail page exists today.
-
-### Layout
-
-```
-[ Breadcrumb: All documents ]
-
-[ Header strip with gradient: title (editable inline), type pill, status pill, subtitle (subject link, creator, age) ]
-
-[ Action bar — context-aware ]
-
-[ Two-column body:
-    Left (2fr):
-      Signers panel (vertical list, replaces existing horizontal SigningProgress)
-      Linked entity card
-    Right (1fr):
-      Watchers panel (chips + add)
-      Activity timeline (from documentEvents)
-      Notes (auto-saving editable text)
-      Preview (PDF; tabbed Original/Signed when completed)
-]
-```
-
-### Action bar by status
-
-- `draft` — `[Send for signing]` `[Edit signers]` `[Delete]`
-- `sent | partially_signed` — `[Send reminder to all]` `[Resend invite]` `[Cancel]`
-- `completed` — `[Download signed PDF]` `[Email signed PDF to all signatories]`
-- `cancelled | rejected | expired` — `[Duplicate]`
-- Always `[...]` overflow: Duplicate, Move to other entity, View Documenso URL, Audit log
-
-### Signers panel (vertical, replaces horizontal stepper)
-
-Per-row:
-
-- Numbered status circle (pending grey, signed green, declined red)
-- Name, email, role
-- Sent age, last-reminded age, signed timestamp
-- `[Remind]` button — disabled with countdown if cooldown active (24h-or-cadence) for auto mode; bypassed in manual mode
-- `[Copy signing link]` — copies `signingUrl` (hosted Documenso); overflow offers "Copy embed link" if `embeddedUrl` present (used by website embed at `/sign/[type]/[token]`)
-- `[...]` overflow: Resend invite, View signing history, Replace email (draft only)
-- Sequential mode: only current pending signer's `[Remind]` active; others greyed with tooltip
-
-### Send-signed-PDF email flow
-
-Action visible only when `status='completed' AND signedFileId IS NOT NULL`.
-
-Click opens email composer drawer prefilled:
-
-- From: dropdown defaulting to System (port-config noreply identity); Personal accounts available only when port admin enables `email.allowPersonalAccountSends`
-- To: union of `documentSigners.signerEmail` for the doc
-- Cc: empty; "Cc watchers" toggle adds users from `document_watchers`
-- Subject: `"Signed {document type} — {document title}"`
-- Body: from `signed_doc_completion` per-port template (new template type; default seeded for new ports)
-- Attachments: signed PDF auto-attached from `documents.signedFileId` (chip with filename + size; removable)
-
-Send dispatch:
-
-- System path: `lib/email/index.ts → sendEmail()` with portId + attachments; writes `documentEvents` row; skips email_messages/threads writes (no IMAP sync expected)
-- User path: `email-compose.service.ts` existing flow; writes email_messages + thread; subject to `allowPersonalAccountSends` gate (server-side enforces 403 on user senderType when toggle off)
-
-### Backend additions
-
-- `POST /api/v1/documents/[id]/cancel` — calls `cancelDocument` service; service calls Documenso void via new client function
-- `POST /api/v1/documents/[id]/remind` — accepts optional `{ signerId }`; passes `auto: false` to service
-- `GET /api/v1/documents/[id]/watchers` — list
-- `POST /api/v1/documents/[id]/watchers` — add `{ userId }`
-- `DELETE /api/v1/documents/[id]/watchers/[userId]` — remove
-- `POST /api/v1/documents/[id]/compose-completion-email` — returns prefilled draft
-
-## Create-document wizard
-
-Replaces `<EoiGenerateDialog>`. Single drawer/dialog, three steps.
-
-### Step 1 — Type and source
-
-```
-Render:  ●  Generate the PDF here (using template format below)
-         ○  Use a Documenso-stored template (Documenso renders + signs)
-
-Format (when "Generate the PDF here" selected):
-         ●  HTML (write inline)
-         ○  PDF (AcroForm fillable upload)
-         ○  PDF (overlay positioning)
-
-Template:  [ pick from port's templates of selected format ]
-   OR
-Upload PDF:  [ drop or pick file; preview renders inline ]
-
-Document type: [ auto-derived from template, or picked from DOCUMENT_TYPES enum ]
-```
-
-Signing destination is always Documenso. The "Render in CRM" vs "Render in Documenso" axis is about PDF generation only.
-
-### Step 2 — Recipients
-
-```
-Attached to: [ Interest #142 — Smith family  Change ]
-   ↑ pre-filled if launched from a detail page
-
-Signers: (hidden for documenso-render path; signers embedded in template)
-   ① name  email  role       [✕]
-   ② name  email  role       [✕]
-   [+ Add signer] (autocomplete from clients/companies/users; or manual entry)
-   Drag to reorder; signing-order assigned by row position
-
-Signing mode: ● Sequential   ○ Parallel
-
-Watchers (optional): [chips] [+ Add watcher] (CRM users)
-
-Reminder cadence:
-   ●  Use template default (every 7 days)
-   ○  Override:  [_____] days
-   ○  Disable for this document
-
-[ For upload path only ]
-☑  Auto-place signature fields at footer (default; refine later in Documenso)
-```
-
-### Step 3 — Review and send
-
-```
-Title: [ EOI — Smith family ____________ ]   (editable; default rendered from merge tokens)
-Notes (internal): [_____________]
-Preview: [ rendered PDF inline · 4 pages · scrollable ]
-Signing-order banner (multi-signer in-app/upload only): "Sequential — Carol must sign before Bob" [Switch to parallel]
-[← Back] [Save as draft] [Send →]
-```
-
-Save as draft → status='draft'; `[Send for signing]` available later from detail page. Send → calls Documenso, status='sent', socket event fires.
-
-### Documenso version-aware field placement
-
-For upload path, `placeDefaultSignatureFields` auto-positions one SIGNATURE per recipient at last-page footer (staggered to avoid overlap). User can refine in Documenso via "Customize fields in Documenso" link on detail page.
-
-`placeFields` and `placeDefaultSignatureFields` in `documenso-client.ts` hide v1/v2 differences:
-
-- v1: `POST /api/v1/documents/{id}/fields` per field; pixel coordinates; requires page dimension lookup
-- v2: `POST /api/v2/envelope/field/create-many` bulk; percentage 0-100 coordinates; rich `fieldMeta`
-- Caller passes percentage; abstraction converts for v1 using cached page dimensions
-
-### `createDocumentSchema` extension
-
-```ts
-export const createDocumentSchema = z.object({
-  source: z.enum(['template', 'upload']),
-  templateId: z.string().uuid().optional(),
-  uploadedFileId: z.string().uuid().optional(),
-
-  documentType: z.enum(DOCUMENT_TYPES),
-  title: z.string().min(1).max(200),
-  notes: z.string().optional(),
-
-  // Subject (exactly one required)
-  interestId: z.string().uuid().optional(),
-  reservationId: z.string().uuid().optional(),
-  clientId: z.string().uuid().optional(),
-  companyId: z.string().uuid().optional(),
-  yachtId: z.string().uuid().optional(),
-
-  // Signers (required when render=in-app or source=upload)
-  signers: z.array(z.object({
-    signerName: z.string().min(1),
-    signerEmail: z.string().email(),
-    signerRole: z.enum(['client', 'sales', 'approver', 'developer', 'other']),
-    signingOrder: z.number().int().min(1),
-  })).optional(),
-  signingMode: z.enum(['sequential', 'parallel']).default('sequential'),
-
-  pathway: z.enum(['documenso-template', 'inapp', 'upload']).optional(),
-
-  watchers: z.array(z.string().uuid()).optional(),
-
-  reminderCadenceOverride: z.number().int().min(1).max(365).nullable().optional(),
-  remindersDisabled: z.boolean().default(false),
-
-  autoPlaceFields: z.boolean().default(true),
-
-  sendImmediately: z.boolean().default(true),
-}).refine(...one-subject-FK-required...);
-```
-
-## Template formats
-
-### Authoring paths
-
-| Format                       | Authoring                                                                                   | Merge fields                                        | Best for                                         |
-| ---------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------ |
-| HTML (existing)              | Inline rich-text editor with merge tokens                                                   | Server-side substitution, rendered to PDF via pdfme | Welcome letters, acknowledgments, correspondence |
-| PDF (AcroForm fillable)      | Admin uploads fillable PDF; UI scans AcroForm field names; admin maps each to a merge token | pdf-lib fills form at gen time                      | EOI, Reservation Agreement, NDA                  |
-| PDF (overlay positioning)    | Admin uploads any PDF; UI specifies merge token positions per page+x+y+fontSize             | pdf-lib draws text over PDF at positions            | Quick wins where preparing AcroForm is overkill  |
-| Documenso template reference | Admin enters Documenso template ID + label                                                  | None in CRM; Documenso owns it                      | Documenso-rendered signing flows                 |
-
-### Generator dispatch
-
-```ts
-switch (template.template_format) {
-  case 'html':            generatePdf(template.body_html, mergeContext);
-  case 'pdf_form':        fillAcroForm(template.source_file_id, template.field_mapping, mergeContext);
-  case 'pdf_overlay':     drawOverlay(template.source_file_id, template.overlay_positions, mergeContext);
-  case 'documenso_render': documenso.generateDocumentFromTemplate(template.documenso_template_id, ...);
-}
-```
-
-All four formats end at Documenso for signing — only PDF generation location differs. Non-signature templates (welcome letters etc.) skip the upload-to-Documenso step entirely; they render to PDF then get emailed.
-
-### Admin template editor extension
-
-Format picker added to `/admin/templates` editor:
-
-- For PDF (AcroForm): file upload field, then two-column mapping UI (AcroForm field names ↔ merge tokens autocomplete from existing `MERGE_FIELDS` catalog)
-- For PDF (overlay): file upload, then per-token form with page/x/y/fontSize inputs (visual placement editor deferred)
-- For Documenso template: single text input + Test connection button calling `getDocumensoTemplate`
-- For HTML: existing inline editor unchanged
-
-### Word (.docx) deferred
-
-Reasons: LibreOffice headless adds significant install/memory/security surface; CloudConvert adds paid dependency and third-party data exposure; `docxtemplater` merge syntax incompatible with existing `{{token}}` convention; field placement still needs PDF flow afterwards. If marinas push back, the feasible path is `.docx → server-side conversion → PDF → existing AcroForm/overlay flow`. Not worth the engineering until requested.
-
-## Reservation agreements as a doc type
-
-### What differs from EOI's pattern
-
-| Aspect                | EOI                           | Reservation Agreement                                                                      |
-| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------ |
-| Subject FK            | `interestId`                  | `reservationId`                                                                            |
-| Default template      | Documenso EOI per port        | Documenso reservation_agreement per port (seeded)                                          |
-| Default signers       | client + sales/approver       | client + port admin                                                                        |
-| Trigger               | Manual on interest detail     | Manual on reservation detail                                                               |
-| Lifecycle integration | None                          | Active reservations without an agreement get flagged in dashboard alert                    |
-| Final-PDF storage     | `documents.signedFileId` only | `documents.signedFileId` AND mirrored to `berth_reservations.contractFileId` on completion |
-
-### New CRM-side reservation detail page
-
-`/[port]/berth-reservations/[id]` doesn't exist today (only the portal's `/portal/my-reservations`). Phase A builds it.
-
-Layout:
-
-```
-[ Header: "Reservation #88 · M/Y Tate"  status pill  subtitle: berth, client, dates, tenure ]
-[ Action bar: Activate | Generate agreement | Cancel | ... ]
-[ Two columns:
-    Left:  Reservation details card
-           Linked interest card
-           Activity timeline
-    Right: Agreement card (state-dependent: no agreement / in-flight / completed)
-]
-```
-
-Agreement card states:
-
-- No agreement yet: warning + `[Generate agreement →]`
-- In-flight (sent/partially_signed): "X/Y signed", per-signer status, `[View document →]` `[Send reminder]` `[Cancel]`
-- Completed: "Completed YYYY-MM-DD", `[Download signed PDF]` `[Email to all signatories]`, "Signed contract attached to reservation."
-
-Generate-agreement button launches the wizard with prefills:
-
-- `documentType='reservation_agreement'`
-- `templateId=<port's default>`
-- `reservationId=<current>`
-- Default signers from linked client + configurable port-admin user
-- Wizard step 1 pre-validated; user lands on step 2
-
-### Backend additions
-
-- Merge field catalog extended in `src/lib/templates/merge-fields.ts`:
-  - `{{reservation.startDate}}` `{{reservation.endDate}}` `{{reservation.tenureType}}` `{{reservation.termSummary}}` `{{reservation.signedDate}}`
-- New service `reservation-agreement-context.ts.buildReservationAgreementContext(reservationId, portId)`
-- New seeder for default `reservation_agreement` template on port creation (HTML format; admins can switch to AcroForm/overlay later); template stored at `assets/templates/reservation-agreement-default.html`
-- Webhook handler extension: `handleDocumentCompleted` detects `documentType='reservation_agreement'` and sets `berth_reservations.contractFileId = doc.signedFileId` for the linked reservation
-- Dashboard alert query: active reservations without a completed agreement (LEFT JOIN against documents filtered on type+status); rows surface as a warning card
-
-### Trade-off
-
-`berth_reservations.contractFileId` becomes a denormalized convenience pointer duplicated with `documents.signedFileId` for the linked reservation. Updating it on completion costs one extra UPDATE. Benefit: anyone querying reservations directly (portal "My Reservations") doesn't need to join through documents to know which file is the contract.
-
-## Reminder framework polish
-
-### Problems with today's logic
-
-1. Eligibility gated by `interests.reminderEnabled` — reservation agreements, NDAs, ad-hoc upload docs (no interest link) never auto-remind
-2. Hardcoded 24h cooldown — effective cadence is 1 day; can't slow down for low-urgency docs
-3. Always reminds lowest-pending signer — parallel-signing docs can't nudge a specific signer
-4. No per-doc disable
-
-### New eligibility logic
-
-```
-function isReminderDue(doc, template, lastReminderAt) {
-  if (!['sent','partially_signed'].includes(doc.status)) return false;
-  if (doc.documenso_id == null) return false;
-  if (doc.reminders_disabled) return false;
-
-  const effectiveCadence = doc.reminder_cadence_override ?? template.reminder_cadence_days;
-  if (effectiveCadence === null) return false;
-
-  if (lastReminderAt == null) return true;
-  return (now - lastReminderAt) >= effectiveCadence * 24h;
-}
-```
-
-`processReminderQueue` query rewritten:
-
-```sql
-SELECT d.* FROM documents d
-LEFT JOIN document_templates t ON t.id = d.template_id
-WHERE d.port_id = $1
-  AND d.status IN ('sent','partially_signed')
-  AND d.documenso_id IS NOT NULL
-  AND d.reminders_disabled = false
-  AND COALESCE(d.reminder_cadence_override, t.reminder_cadence_days) IS NOT NULL;
-```
-
-`interests.reminderEnabled` is dropped from the gating logic but the column stays for now (no migration). Future cleanup PR can drop the column.
-
-### `sendReminderIfAllowed` extended signature
-
-```ts
-export async function sendReminderIfAllowed(
-  documentId: string,
-  portId: string,
-  options: {
-    auto?: boolean; // true = cron; false (default) = manual
-    signerId?: string; // optional — target a specific pending signer
-  } = {},
-): Promise<{ sent: boolean; reason?: string; signerId?: string }>;
-```
-
-Behaviour matrix:
-
-| Mode        | 9-16 window | Cadence cooldown | Manual cooldown          |
-| ----------- | ----------- | ---------------- | ------------------------ |
-| auto: true  | enforced    | enforced         | n/a                      |
-| auto: false | bypassed    | bypassed         | 30s client-side debounce |
-
-Per-signer logic:
-
-- If `signerId` provided in sequential-mode doc, signer must be the lowest-pending signer (otherwise reason='Signer is not next in sequence')
-- In parallel-mode doc, any pending signer can be reminded independently
-- Returns `{ sent, reason }` so caller can show toast on skip
-
-### Admin and per-doc UI
-
-Admin `/admin/templates` editor:
-
-```
-Auto-reminders for this template:
-  ☑  Enabled    Cadence: every [_____] days  (1-365; default 7)
-  ☐  Disabled (manual reminders only)
-```
-
-Doc detail page (Section 3) "Reminders" panel under signers, with edit drawer for per-doc override.
-
-## Visual polish system
-
-### Token additions
-
-```
---radius-sm: 0.375rem (existing)
---radius-md: 0.5rem (NEW — default cards)
---radius-lg: 0.625rem (NEW — sheets, dialogs)
---radius-xl: 0.875rem (NEW — KPI tiles, hero strips)
-
---shadow-xs: 0 1px 2px 0 rgb(15 23 42 / 0.04)
---shadow-sm: 0 2px 4px -1px rgb(15 23 42 / 0.06)
---shadow-md: 0 4px 12px -2px rgb(15 23 42 / 0.08)
---shadow-lg: 0 12px 32px -8px rgb(15 23 42 / 0.12)
---shadow-glow: 0 0 0 4px rgb(58 123 200 / 0.12)
-
---gradient-brand:        linear-gradient(135deg, #3a7bc8 0%, #2f6ab5 100%)
---gradient-brand-soft:   linear-gradient(135deg, #d8e5f4 0%, #ffffff 100%)
---gradient-success:      linear-gradient(135deg, #e8f5e9 0%, #ffffff 100%)
---gradient-warning:      linear-gradient(135deg, #fef3c7 0%, #ffffff 100%)
-
---ease-spring:  cubic-bezier(0.34, 1.56, 0.64, 1)
---ease-smooth:  cubic-bezier(0.4, 0, 0.2, 1)
---duration-fast: 150ms
---duration-base: 200ms
---duration-slow: 300ms
-```
-
-All exposed as Tailwind utilities.
-
-### Existing token foundation (already in place; not changing)
-
-- Full HSL shadcn token system (primary, secondary, muted, accent, destructive, border, input, ring, popover, card)
-- Brand palette `brand` (50-700, default `#3a7bc8`)
-- Navy palette `navy` (50-600, default `#1e2844` for sidebar)
-- Maritime accents: `sage`, `mint`, `teal`, `purple` with light/default/dark variants
-- Semantic `success` / `warning` with bg+border
-- Recharts chart-1 through chart-6 token system
-- Dark mode wired
-- Sidebar tokens separate from main palette
-
-### New primitive components
-
-- `<StatusPill status="...">` — colored-by-state pill (pending grey, sent brand, partial teal, completed success, expired warning, rejected destructive, cancelled muted-darker, active success, archived muted)
-- `<KPITile title value delta sparkline?>` — rounded-xl, shadow-sm, gradient-brand-soft border-top accent stripe; recharts mini sparkline using `--chart-1`
-- `<EmptyState icon title body actions>` — large icon in brand-soft circle, title, body, action buttons
-- `<PageHeader>` polished — gradient-brand-soft background, eyebrow optional, KPI sub-line, primary action right-aligned
-
-### Component pattern updates
-
-- List rows: hover gradient (subtle brand-soft 4% opacity), shadow-xs lift, animation `transition-all duration-base ease-smooth`; row-update from socket events animates 1s fade-in highlight
-- Detail pages: two-column responsive grammar (header strip → 2fr main + 1fr side; cards stack vertical < 768px)
-- Sidebar (already dark navy): active item gets 4px brand left-edge stripe instead of bg shift; section headers smaller-caps + brand-200 text
-- Topbar: search inset shadow + brand focus ring; "+ New" trigger gets `bg-gradient-brand`; notification bell gets badge spring animation; user avatar gets shadow-sm + 2px white ring
-- Forms: focus ring uses `--shadow-glow`; primary submit buttons get `bg-gradient-brand` with hover scale-1.01; inline validation gets destructive-bg pill with caret pointing up
-
-### Loading skeleton system
-
-- List pages: 8 skeleton rows matching column widths with subtle pulse
-- Detail pages: header strip skeleton + 2-column section skeletons
-- Dashboard: KPI tile skeletons + chart skeletons
-- Replaces today's mix of "Loading..." text and spinners
-
-### Mobile responsive (full sweep)
-
-Breakpoints:
-
-- < 640px (phone): single column, sticky bottom action bar, sheet overlays for filters
-- 640-1024px (tablet): single column with wider gutters, side column under main
-- ≥ 1024px (desktop): full two-column
-
-Per-page rules:
-
-- List tables → card stack < 768px
-- Detail page header collapses subtitle to "Show more"
-- Tabs collapse to `<select>` < 640px
-- Sidebar slides over content < 1024px
-- Primary "+ New" actions float as FAB bottom-right < 640px
-
-## Test plan
-
-### Unit (`tests/unit/`)
-
-- `document-reminders-cadence.test.ts` — `isReminderDue` math; manual-vs-auto window/cooldown bypass
-- `documenso-place-fields.test.ts` — v1/v2 dispatch (mocked HTTP); coord normalization; default field staggering for 1/2/3/5 recipients
-- `email-attachments-resolver.test.ts` — fileId → MinIO buffer; cross-port 403; 10 MB cap warning
-
-### Integration (`tests/integration/`)
-
-- Extend `document-templates-generate-and-sign.test.ts` — new template formats (`pdf_form`, `pdf_overlay`, `documenso_render`); upload-path test
-- New `document-watchers.test.ts` — add/remove endpoints; notification fan-out; port isolation
-- New `document-cancel.test.ts` — user-initiated cancel; mocked Documenso void; status + event log; reject 409 if completed
-- New `reservation-agreement-contract-mirror.test.ts` — `handleDocumentCompleted` mirrors `signedFileId` to `berth_reservations.contractFileId` only for `reservation_agreement` type
-- New `reminder-cron-cadence.test.ts` — seed varied templates; simulated time advance; assert correct docs reminded
-
-### E2E smoke (`tests/e2e/smoke/`)
-
-- Extend `04-documents.spec.ts` — hub tabs, expand row, per-signer remind with cooldown, type/status filters, saved-view round-trip, bulk-remind with per-row toast reasons
-- Extend `05-eoi-generate.spec.ts` — wizard invocation prefills (template, interest); existing flow regression
-- New `27-document-create-wizard.spec.ts` — template path full flow; upload path full flow; watcher addition; reminder-override radios produce correct DB state
-- New `28-reservation-agreements.spec.ts` — reservation detail → Generate agreement → wizard prefilled → Send → agreement section state transitions; post-completion contract attached + email button visible
-- New `29-email-attachments.spec.ts` — system path send (documentEvents row, no email_messages); user path send when toggle on (email_messages with attachment_file_ids); cross-port 403
-
-### E2E exhaustive (`tests/e2e/exhaustive/`) — click-everything sweep
-
-- New `10-documents-hub.spec.ts` — crawl each tab, filter dropdowns, saved-view, expand row, signer-row buttons, bulk-action bar
-- New `11-document-detail.spec.ts` — crawl in three states (draft/sent/completed); watcher add/remove; notes auto-save; preview download; "Email signed PDF" launch
-- New `12-document-create-wizard.spec.ts` — crawl each wizard step under both template and upload paths; picker dropdowns, signer add/remove, drag-handle, reminder-cadence radios
-- New `13-reservation-detail.spec.ts` — crawl in three states (pending no agreement / agreement-in-flight / agreement-completed); Activate/Cancel/Generate buttons; inline notes
-- New `14-email-composer.spec.ts` — crawl composer drawer with attachments; From dropdown; attach button; recipient chips
-- Extend exhaustive `05-eoi-generate.spec.ts` — parallel-mode + signing-order edge cases (greyed-out reminder buttons; out-of-order remind rejection)
-
-### E2E real-API (`tests/e2e/realapi/`)
-
-Each spec gates on env vars; clean skip if missing.
-
-- Extend `documenso-real-api.spec.ts`:
-  - Generate from Documenso template (real send) and assert in real Documenso
-  - Generate from in-app PDF AcroForm fill, upload to real Documenso, assert
-  - Generate from upload path with auto-placed signature fields, assert fields visible in Documenso
-  - v1 and v2 explicit version-flag tests (via `DOCUMENSO_API_VERSION`)
-  - Manually sign in real Documenso (or simulate webhook) and assert local DB updates
-  - Cancel real in-flight doc, assert local + remote state
-  - Send reminder via real Documenso, assert HTTP + documentEvents row
-
-- New `smtp-system-send.spec.ts` — system-path send → IMAP fetch → assert subject + attachment; verify port-config from-identity; cleanup via IMAP delete
-- New `smtp-user-send.spec.ts` — user-path send (requires connected account, allowPersonalAccountSends=true) → IMAP fetch → email_messages row with attachment_file_ids
-- New `minio-file-lifecycle.spec.ts` — upload, list, preview, download (byte-equal), delete; port isolation; mime-type validation
-- New `documenso-webhook-ingress.spec.ts` — requires cloudflared tunnel; configure tunnel URL as Documenso webhook target; trigger doc completion; assert webhook fires + handler updates DB; verify timing-safe secret check rejects wrong secret with 401; verify event normalisation (uppercase enum + lowercase-dotted both accepted)
-- New `email-attachments-roundtrip.spec.ts` — compose with fileId attachment; SMTP send; IMAP fetch; assert attachment bytes match; reject cross-port fileId with 403 before SMTP touched
-
-### Visual baselines (`tests/e2e/visual/`)
-
-`snapshots.spec.ts-snapshots/` regenerated as polish ships per page; one PR per surface group, baselines reviewed in PR diff. New baselines added: documents hub, doc detail, create-document wizard (each step), reservation detail, email composer with attachments.
-
-### Test data fixtures
-
-`global-setup.ts` extended with:
-
-- Seed default `reservation_agreement` template (HTML format)
-- Seed default `signed_doc_completion` template
-- Seed one in-flight EOI doc with two pending signers (for hub-tab tests)
-- Seed one `berth_reservation` with `status='active'` and no agreement (for lifecycle alert query)
-
-### CI vs local runs
-
-| Project                                        | When                                                                                                        |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `setup` + `smoke` (~14 min)                    | Every PR via CI                                                                                             |
-| `exhaustive` (with new click-everything specs) | Every PR via CI; ~25 min budget                                                                             |
-| `visual`                                       | Every PR; baselines reviewed in PR diffs                                                                    |
-| `realapi`                                      | Locally before merging touch-points; pre-release; not on CI (avoids burning Documenso quota and SMTP costs) |
-
-## Build sequence
-
-| #     | Title                                             | Effort | Depends on     |
-| ----- | ------------------------------------------------- | ------ | -------------- |
-| 1     | Data model + service skeletons                    | 1d     | —              |
-| 2     | Documenso v1/v2 abstraction layer                 | 1d     | —              |
-| 3     | Visual primitives + token additions               | 1.5d   | —              |
-| 4     | Documents hub page                                | 2d     | 1, 3           |
-| 5     | Document detail page                              | 2d     | 1, 3           |
-| 6     | Create-document wizard + new template formats     | 2.5d   | 1, 2, 3        |
-| 7     | Reservation detail + agreement flow               | 1.5d   | 1, 6           |
-| 8     | Email composer attachments + From selector        | 1d     | 1, 3           |
-| 9     | Reminder framework polish                         | 1d     | 1              |
-| 10a-e | Visual polish sweep (5 PRs across surface groups) | 3-4d   | 3              |
-| 11    | Real-API integration tests                        | 1.5d   | 2, 4-9 shipped |
-
-### Critical path
-
-```
-1 → 2 → 6 → 7         (data model → Documenso → wizard → reservation)
-1 → 3 → 4 → 5 → 9     (data model → primitives → hub → detail → reminders)
-                       1 → 8                  (composer)
-                       3 → 10a-e (sweep)
-                       all → 11 (realapi)
-```
-
-Wall-clock minimum ~9 days; realistic with overhead ~17 days; calendar ~3.5-5 weeks.
-
-### Acceptance gates per PR
-
-- `pnpm tsc --noEmit` and `pnpm lint` clean
-- Vitest unit + integration green
-- Playwright smoke green for surface touched
-- Visual baselines regenerated and reviewed in PR diff
-- For PRs touching external integrations (2, 6 upload, 7 contract mirror, 8 SMTP, 11): relevant `realapi` spec verified locally before merge
-
-### Risk register
-
-| Risk                                                       | Mitigation                                                                                |
-| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| Documenso v2 endpoint shape drifts from docs               | PR2 validates against real v2 instance during dev; realapi spec re-runs nightly post-ship |
-| Visual polish scope creeps                                 | One PR per surface group (10a-e), each independently shippable                            |
-| Cron migration changes effective behaviour                 | Backfill sets EOI cadence to 1 day matching today's effective; run on staging first       |
-| Mobile responsive regressions                              | Visual baselines include phone-viewport snapshots; PR10e is the responsive sweep          |
-| EOI dialog → wizard migration breaks "Generate EOI" button | Wizard launched with prefills from interest detail; PR6 includes regression spec          |
-| AcroForm template format confuses non-technical admins     | HTML default; inline help; default templates seeded                                       |
-| Phase A wall-clock past 5 weeks                            | Tier-2 sweep items + optional realapi specs deferrable to follow-up release               |
-
-## Glossary
-
-- **Documenso** — open-source document signing service, self-hosted instance at `signatures.portnimara.dev`
-- **EOI** — Expression of Interest, a pre-reservation signed document
-- **Reservation Agreement** — contract signed when a berth reservation is committed
-- **Hub** — the new `/[port]/documents` page
-- **Watcher** — a CRM user added to a doc to receive notifications on signature events without being a signer themselves
-- **Signing order** — sequential index across signers; sequential mode requires lower order to sign first; parallel mode lets all sign concurrently
-- **Cadence** — interval in days between auto-reminders to unsigned signers
-- **System send / User send** — email dispatch identity: System uses port-config noreply SMTP; User uses connected personal email account (gated by admin toggle)
-- **Render location** — where the PDF is generated (CRM-local via HTML/AcroForm/overlay, or in Documenso). Signing is always Documenso; render location is independent.

docs/superpowers/specs/2026-04-28-phase-b-insights-alerts-design.md

@@ -1,435 +0,0 @@
-# Phase B — Insights, Alerts, and Operational Awareness
-
-**Status:** Draft — awaiting review
-**Date:** 2026-04-28
-**Phase:** B of D (A = Documents hub + visual polish ✓ shipped; C = Website integration; D = Pre-prod ops)
-
-## Overview
-
-Phase A made the CRM look polished and finished the documents/signing surface. Phase B turns it into a tool that _tells operators what's happening_ — instead of forcing them to navigate every list to find pipeline drift, expiring documents, or stalled reservations. It also closes the seven highest-priority Nuxt→Next gaps the 2026-04-28 audit surfaced (analytics, berth-interests, EOI queue, OCR, alerts, audit log, expense dedup).
-
-The product story changes from "system of record" to "system of attention." Operators land on the dashboard and immediately see what needs them today — not a flat list they have to filter.
-
-## Scope boundaries
-
-### In scope (this spec)
-
-- **Analytics dashboard** — chart-driven KPI page replacing the current 4-tile placeholder; pipeline funnel, occupancy timeline, revenue breakdown, lead-source attribution, with date-range and per-port filters
-- **Alert framework** — rule engine that evaluates conditions on a schedule and surfaces actionable cards (alerts) in the dashboard's right rail; dismissible per-user; deep-links into the offending entity
-- **Interests-by-berth view** — `/[port]/berths/[id]/interests` panel showing every interest targeting a berth, sortable by stage/score/age
-- **Expense duplicate detection** — heuristic match on (vendor + amount + date ± 3 days); surfaces in expense detail with "Merge" action; background scan on new expense
-- **EOI queue** — saved-view filter on the existing documents hub for `documentType='eoi' AND status IN ('sent','partially_signed')`, surfaced as a hub tab and a dashboard alert link
-- **OCR for expense receipts** — Claude Vision integration on the existing `/expenses/scan` route to extract vendor, amount, date, currency, line items from uploaded receipts; user confirms before save
-- **Audit log read view** — admin-gated UI for the existing `audit_logs` table with filters (user, action, entity type, date range, entity id search) and per-port + global (super-admin) scopes
-
-### Explicitly out of scope (deferred to later phases)
-
-- Custom user-defined alert rules (Phase B v1 ships with a fixed catalog of ~10 rules; user-rule creation deferred to Phase D)
-- Real-time alert push notifications (only socket-fired updates of the alert list; SMS/email push deferred)
-- Alert grouping / digests (each alert is its own card)
-- Predictive analytics, ML scoring (separate from existing AI feature flag)
-- Cross-port roll-up dashboards for super-admins (per-port only in v1)
-- Full audit-log retention / archival policy (Phase D)
-- OCR for PDF receipts (only image formats: jpg/png/heic; PDF expense uploads bypass OCR and stay manual until Phase D)
-- Excel/CSV import for bulk expense backfill
-- Country / phone / timezone work (separate cross-cutting agenda at `2026-04-28-country-phone-timezone-design.md`)
-
-## Information architecture
-
-### URL surface
-
-```
-/[port]/dashboard               replaces existing; analytics-driven
-/[port]/insights                deep-link analytics page (charts only, no alerts)
-/[port]/alerts                  full alert list (admin filter, dismissed history)
-/[port]/berths/[id]/interests   new tab on berth detail
-/[port]/expenses/scan           extend existing route with Claude Vision OCR
-/[port]/admin/audit             admin-gated audit log viewer
-/[port]/documents               extended: 'EOI queue' tab pre-filters to EOI in flight
-```
-
-### Schema deltas
-
-```sql
--- alerts: surfaces operational warnings the user should act on
-CREATE TABLE alerts (
-  id              text PRIMARY KEY DEFAULT generate_id('alrt'),
-  port_id         text NOT NULL REFERENCES ports(id) ON DELETE CASCADE,
-  rule_id         text NOT NULL,                      -- 'reservation.no_agreement', 'interest.stale', ...
-  severity        text NOT NULL,                      -- 'info' | 'warning' | 'critical'
-  title           text NOT NULL,
-  body            text,
-  link            text NOT NULL,                      -- relative path the card deep-links to
-  entity_type     text,                                -- optional FK target ('interest', 'reservation', ...)
-  entity_id       text,
-  fingerprint     text NOT NULL,                      -- hash of (rule_id + entity_type + entity_id) — dedupe
-  fired_at        timestamptz NOT NULL DEFAULT now(),
-  dismissed_at    timestamptz,
-  dismissed_by    text REFERENCES users(id),
-  acknowledged_at timestamptz,                         -- "I'm on it" without dismissing
-  acknowledged_by text REFERENCES users(id),
-  resolved_at     timestamptz,                         -- auto-set when underlying condition clears
-  metadata        jsonb DEFAULT '{}'                   -- per-rule extras (e.g. days_stale, amount_at_risk)
-);
-CREATE UNIQUE INDEX idx_alerts_fingerprint_open ON alerts (port_id, fingerprint) WHERE resolved_at IS NULL;
-CREATE INDEX idx_alerts_port_fired ON alerts (port_id, fired_at DESC);
-CREATE INDEX idx_alerts_port_severity_open ON alerts (port_id, severity) WHERE resolved_at IS NULL AND dismissed_at IS NULL;
-
--- expense duplicate detection (column-only, no new table)
-ALTER TABLE expenses ADD COLUMN duplicate_of text REFERENCES expenses(id);
-ALTER TABLE expenses ADD COLUMN dedup_scanned_at timestamptz;
-CREATE INDEX idx_expenses_dedup ON expenses (port_id, vendor_name, amount, expense_date)
-  WHERE duplicate_of IS NULL;
-
--- analytics support: materialized refresh tracking (avoids recomputing on every dashboard hit)
-CREATE TABLE analytics_snapshots (
-  port_id     text NOT NULL REFERENCES ports(id) ON DELETE CASCADE,
-  metric_id   text NOT NULL,                       -- 'pipeline_funnel.30d', 'occupancy_timeline.90d', ...
-  computed_at timestamptz NOT NULL DEFAULT now(),
-  data        jsonb NOT NULL,
-  PRIMARY KEY (port_id, metric_id)
-);
-
--- audit_logs already exists; add a tsvector column for fast search
-ALTER TABLE audit_logs ADD COLUMN search_text tsvector
-  GENERATED ALWAYS AS (
-    to_tsvector('simple',
-      coalesce(action, '') || ' ' ||
-      coalesce(entity_type, '') || ' ' ||
-      coalesce(entity_id::text, '') || ' ' ||
-      coalesce(actor_email, ''))
-  ) STORED;
-CREATE INDEX idx_audit_search ON audit_logs USING gin(search_text);
-
--- ocr extracted fields on receipt files (most fields already on expenses)
-ALTER TABLE expenses ADD COLUMN ocr_status text DEFAULT 'pending'; -- 'pending'|'ok'|'failed'|'low_confidence'
-ALTER TABLE expenses ADD COLUMN ocr_raw jsonb;                      -- the model's full response
-ALTER TABLE expenses ADD COLUMN ocr_confidence numeric;             -- 0..1
-```
-
-After running migration on dev/staging, restart `next dev` to flush postgres.js prepared-statement cache (project convention).
-
-### Service-layer changes
-
-**New services:**
-
-- `alerts.service.ts` — CRUD + fanout: `evaluateRules(portId)`, `dismissAlert(id, userId)`, `acknowledgeAlert(id, userId)`, `resolveStaleAlerts(portId)`
-- `alert-rules.ts` — fixed catalog of evaluator functions, each takes `(portId, db)` and returns `Array<{ rule_id, severity, fingerprint, ... }>`
-- `analytics.service.ts` — `getPipelineFunnel(portId, range)`, `getOccupancyTimeline(portId, range)`, `getRevenueBreakdown(portId, range)`, `getLeadSourceAttribution(portId, range)`; reads `analytics_snapshots` first, recomputes if stale
-- `analytics-snapshot-job.ts` — BullMQ recurring job that recomputes snapshots every 15 min per port
-- `expense-dedup.service.ts` — `scanForDuplicates(expenseId)`, returns candidate matches with confidence; called from BullMQ on `expense:created`
-- `expense-ocr.service.ts` — Claude Vision wrapper: takes file URL, returns parsed expense fields; uses prompt caching for the system prompt to keep cost down
-- `audit-search.service.ts` — wraps drizzle query with tsvector match + filters
-
-**Extended services:**
-
-- `documents.service.ts` — adds `getEoiQueueRows(portId, opts)` that joins documents + signers + last-reminder for the EOI queue tab
-- `expenses.service.ts` — `createExpense` triggers OCR + dedup BullMQ jobs after row insert
-- `notifications.service.ts` — fires `alert:created` and `alert:resolved` socket events
-
-### Alert rule catalog (v1)
-
-| Rule ID                      | Severity | Trigger                                                                                      | Resolves when                                | Why it matters               |
-| ---------------------------- | -------- | -------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------- |
-| `reservation.no_agreement`   | warning  | active reservation > 3d old without a `reservation_agreement` doc in any non-cancelled state | doc reaches `sent`                           | flagged in Phase A spec      |
-| `interest.stale`             | info     | `pipelineStage IN ('details_sent','in_communication','visited')` AND last activity > 14d     | activity timestamp updates                   | dropped leads                |
-| `document.expiring_soon`     | warning  | `expires_at` within 7 days, `status IN ('sent','partially_signed')`                          | doc completed/cancelled or expires_at passes | nudge before contracts lapse |
-| `document.signer_overdue`    | warning  | signer pending > 14d AND last reminder > 7d ago                                              | signer signs/declines                        | classic chase target         |
-| `berth.under_offer_stalled`  | info     | berth `status='under_offer'` > 30d                                                           | status changes                               | reservation never closed     |
-| `expense.duplicate`          | info     | `expense.duplicate_of IS NOT NULL`                                                           | merged or marked-not-duplicate               | bookkeeping cleanup          |
-| `expense.unscanned`          | info     | expense with file but `ocr_status='pending'` > 1h                                            | `ocr_status='ok'`                            | OCR failed silently          |
-| `interest.high_value_silent` | critical | `leadCategory='hot_lead'` AND last activity > 7d                                             | activity update                              | revenue at risk              |
-| `eoi.unsigned_long`          | warning  | EOI doc `status='sent'` > 21d                                                                | doc completed/cancelled                      | EOI funnel leak              |
-| `audit.suspicious_login`     | critical | >3 failed logins from same IP in 1h                                                          | manual dismiss                               | security awareness           |
-
-Rules are pure functions; the engine takes their outputs, upserts on `(port_id, fingerprint)` to avoid spam, and auto-resolves alerts whose rule no longer fires.
-
-## Per-feature design
-
-### Analytics dashboard
-
-Replaces the current 4-tile dashboard. Layout:
-
-```
-[ Gradient PageHeader: "Dashboard" · last-updated stamp · Date range picker (Today / 7d / 30d / 90d / custom) ]
-
-[ KPI row (4 KPITiles, sparkline + delta vs prior period):
-    Total Clients      Active Interests     Pipeline Value     Occupancy Rate
-]
-
-[ Pipeline funnel (recharts FunnelChart):                      | Alert rail (right column):
-    horizontal bars per stage with conversion %                |   Critical (red) cards
-    click bar → filtered interests list                        |   Warning (amber) cards
-                                                                |   Info (blue) cards
-                                                                |   "Show dismissed" toggle
-]                                                              |
-
-[ Revenue breakdown (recharts BarChart, stacked by source) ]   | (continues)
-
-[ Occupancy timeline (recharts AreaChart, daily/weekly) ]      |
-
-[ Lead source attribution (recharts PieChart with legend) ]
-```
-
-Charts are server-rendered via the recharts already-in-bundle. Data comes from `analytics.service.ts` which reads `analytics_snapshots` (refreshed every 15 min by cron) — first hit warms the cache, subsequent hits are sub-100ms.
-
-Date-range picker re-runs `analytics.service` queries with the selected range; cache key includes the range so 30d and 90d don't fight.
-
-Export: each chart card has a `[...]` overflow menu with "Download as CSV" and "Download as PNG"; uses recharts' `getDataUrl()` for PNG.
-
-### Alert rail
-
-Right column on `/dashboard`, full page at `/alerts`. Each alert is a card:
-
-```
-[severity-color stripe-left]
-  [rule-icon] Title (entity name)
-  Body — body text describing the condition
-  Last fired N days ago · entity: link
-  [Acknowledge] [Dismiss] [Open →]
-```
-
-- Acknowledge: marks `acknowledged_at` but stays visible (someone's on it)
-- Dismiss: hides from the rail; appears in `/alerts` "Dismissed" tab
-- Auto-resolve: when the rule re-evaluates and the condition no longer fires, alert moves to "Resolved" history
-
-Real-time: socket emits `alert:created` / `alert:resolved` from the cron worker; React Query invalidates the alert list.
-
-### Interests-by-berth view
-
-New tab on `/[port]/berths/[id]` called "Interests" — count badge in tab.
-
-```
-[ Berth header (existing) ]
-
-[ Tabs: Overview | Reservations | Interests (N) | Notes | Files | Activity ]
-
-[ Interests tab body:
-    [Filter: All stages | Active only | Lost] [Sort: Newest | Stage progress | Lead score]
-    Table: client name | stage pill | source | category | last activity | score badge
-    Click row → interest detail
-]
-```
-
-Pure read; no mutations. The list filters interests where `interest.berthId = berth.id`. Already exists in DB; just needs the UI tab.
-
-### Expense duplicate detection
-
-When a new expense is created, BullMQ job `expense.dedup` runs:
-
-```ts
-async function scanForDuplicates(expenseId: string) {
-  const e = await db.query.expenses.findFirst({ where: eq(expenses.id, expenseId) });
-  const candidates = await db.query.expenses.findMany({
-    where: and(
-      eq(expenses.portId, e.portId),
-      eq(expenses.vendorName, e.vendorName),
-      eq(expenses.amount, e.amount),
-      between(expenses.expenseDate, addDays(e.expenseDate, -3), addDays(e.expenseDate, 3)),
-      ne(expenses.id, e.id),
-    ),
-  });
-  if (candidates.length > 0) {
-    await db
-      .update(expenses)
-      .set({ duplicate_of: candidates[0].id, dedup_scanned_at: new Date() })
-      .where(eq(expenses.id, expenseId));
-    // fires `expense.duplicate` alert via rule engine on next sweep
-  }
-}
-```
-
-Detail page: when `duplicate_of` is set, show a yellow banner: "Looks like a duplicate of {linked expense}. [Merge them] [Mark as not duplicate]". Merge: deletes the new expense and merges any line items into the original.
-
-### EOI queue tab
-
-Documents hub gets a new tab between "Awaiting them" and "Awaiting me":
-
-```
-Tabs: All | EOI queue (N) | Awaiting them | Awaiting me | Completed | Expired
-```
-
-`EOI queue` filters: `documentType='eoi' AND status IN ('sent','partially_signed')`. Same row chrome as the rest of the hub. Bulk-action bar adds an "EOI bulk reminder" preset that respects the rule engine's reminder cooldown.
-
-### OCR for expense receipts
-
-Existing `/expenses/scan` route — extend to call Claude Vision on upload:
-
-```ts
-// expense-ocr.service.ts (uses Anthropic SDK; already in deps)
-import Anthropic from '@anthropic-ai/sdk';
-
-const client = new Anthropic();
-
-const SYSTEM_PROMPT = `You extract structured expense data from receipts...
-Output JSON: { vendor, amount, currency, date (ISO), lineItems: [...], confidence (0-1) }
-`; /* cached via ephemeral cache_control for cost savings */
-
-export async function ocrReceipt(fileUrl: string) {
-  const file = await fetch(fileUrl);
-  const base64 = Buffer.from(await file.arrayBuffer()).toString('base64');
-
-  const message = await client.messages.create({
-    model: 'claude-haiku-4-5-20251001', // haiku for cost; sonnet if quality needed
-    max_tokens: 1024,
-    system: [{ type: 'text', text: SYSTEM_PROMPT, cache_control: { type: 'ephemeral' } }],
-    messages: [
-      {
-        role: 'user',
-        content: [
-          { type: 'image', source: { type: 'base64', media_type: 'image/jpeg', data: base64 } },
-          { type: 'text', text: 'Extract expense fields from this receipt.' },
-        ],
-      },
-    ],
-  });
-
-  return parseAndValidate(message.content[0].text);
-}
-```
-
-UI: existing scan page now shows a 3-step flow:
-
-1. Upload receipt photo
-2. Wait for OCR (spinner; ~3s avg with Haiku)
-3. Confirm extracted fields (pre-filled form, user can edit)
-4. Save → existing expense create flow
-
-Low-confidence (< 0.6) extractions show a yellow banner "Please verify all fields" and pre-select the file uploader.
-
-### Audit log read view
-
-Admin route `/[port]/admin/audit`:
-
-```
-[ PageHeader: "Audit Log" · "Last 30 days · 12,847 events" ]
-
-[ Filter row:
-    Search [tsvector]   Actor [combobox of users]   Action [pills]   Entity type [select]
-    Date range [picker]   Severity [pills]   [Reset]
-]
-
-[ Table:
-    Timestamp | Actor | Action | Entity | Diff button | IP | User-agent
-    Click row → expand to show before/after JSON diff
-]
-
-[ Pagination · Export CSV button (admin-gated) ]
-```
-
-Server-side: `audit-search.service.ts` builds a drizzle query with the tsvector match + filters; supports cursor pagination on `(created_at, id)`.
-
-Super-admin sees a port toggle that switches between current port and "All ports" view.
-
-## Test plan
-
-### Unit (`tests/unit/`)
-
-- `alert-rules-evaluators.test.ts` — each rule tested with seeded data; covers fire/no-fire cases and resolution conditions
-- `expense-dedup-heuristic.test.ts` — vendor/amount/date matching with edge cases (case-insensitive, ±3d window, currency mismatch ignored)
-- `analytics-pipeline-funnel.test.ts` — funnel math against fixture interests
-- `analytics-occupancy-timeline.test.ts` — daily aggregation against fixture berth status changes
-- `audit-search-filters.test.ts` — tsvector + filter composition
-- `ocr-prompt-caching.test.ts` — assert cache_control presence on system prompt; mocked Claude response
-
-### Integration (`tests/integration/`)
-
-- `alerts-engine.test.ts` — full evaluation cycle: seed conditions, run engine, assert correct alerts upserted, run again to assert dedupe via fingerprint, mutate state, assert auto-resolve
-- `analytics-snapshot-refresh.test.ts` — recurring job: snapshot row written, served from cache on next read, refreshed on next tick
-- `expense-dedup-flow.test.ts` — create A, create matching B, assert B.duplicate_of=A; merge B → A absorbs line items, B archived
-- `audit-search-tsvector.test.ts` — seed audit_logs, query by free-text, assert returned ids
-- `eoi-queue-listing.test.ts` — extends documents-hub test; assert EOI tab returns correct subset
-
-### E2E smoke (`tests/e2e/smoke/`)
-
-- New `27-analytics-dashboard.spec.ts` — dashboard renders charts; date-range picker re-renders; KPI tiles show non-zero data after seed
-- New `28-alerts.spec.ts` — alert appears after seeding stale-interest condition; click-to-deep-link; dismiss persists; resolve hides
-- New `29-interests-by-berth.spec.ts` — tab visible on berth detail; lists interests; sort works
-- New `30-expense-dedup.spec.ts` — create two matching expenses; banner appears; merge button works
-- New `31-ocr-flow.spec.ts` — uploads fixture receipt image; extracted fields pre-filled; user can edit and save
-- New `32-audit-log.spec.ts` — admin page loads; search by entity id returns expected row; date filter narrows
-- Extend `04-documents.spec.ts` — EOI queue tab presence + count badge
-
-### E2E exhaustive (`tests/e2e/exhaustive/`)
-
-- `15-analytics-dashboard.spec.ts` — crawl every chart's hover tooltips, legend toggles, export menu
-- `16-alerts.spec.ts` — crawl alert card actions, severity filters, dismissed history, real-time arrival via socket emit
-- `17-audit-log.spec.ts` — crawl filter combos, expand row diffs, super-admin all-ports toggle
-
-### E2E real-API (`tests/e2e/realapi/`)
-
-- New `claude-vision-receipt-ocr.spec.ts` — gates on `ANTHROPIC_API_KEY`; uploads two real fixture receipts (one clean, one blurry); asserts Haiku response shape and confidence score; verifies `cache_control` headers in HTTP trace; cleanup deletes test expense
-
-### Test data fixtures
-
-`global-setup.ts` extends:
-
-- Seed one stale interest in `details_sent` stage with `last_activity_at = now - 20d` (fires `interest.stale`)
-- Seed one active reservation without an agreement (fires `reservation.no_agreement`)
-- Seed two matching expenses (fires `expense.duplicate`)
-- Seed 90 days of pipeline activity for analytics charts
-- Add a `tests/e2e/fixtures/receipts/` dir with two .jpg receipts for OCR tests
-
-## Build sequence
-
-| #   | Title                                                        | Effort | Depends on        |
-| --- | ------------------------------------------------------------ | ------ | ----------------- |
-| 1   | Schema + alert/analytics service skeletons                   | 1d     | —                 |
-| 2   | Alert rules engine + recurring evaluator + socket            | 1.5d   | 1                 |
-| 3   | Analytics snapshot job + service layer                       | 1d     | 1                 |
-| 4   | Analytics dashboard page (KPI tiles + 4 charts + date-range) | 2.5d   | 1, 3, A's KPITile |
-| 5   | Alert rail UI + `/alerts` page                               | 1.5d   | 2                 |
-| 6   | EOI queue tab on documents hub                               | 0.5d   | A's hub           |
-| 7   | Interests-by-berth tab on berth detail                       | 0.5d   | —                 |
-| 8   | Expense duplicate detection (job + UI banner + merge)        | 1.5d   | 1                 |
-| 9   | OCR for expense receipts (Claude Vision + 3-step UI)         | 1.5d   | —                 |
-| 10  | Audit log read view (admin page + filters + tsvector search) | 1.5d   | 1                 |
-| 11  | Real-API integration tests                                   | 1d     | 9                 |
-
-### Critical path
-
-```
-1 → 2 → 5            (data → alert engine → alert UI)
-1 → 3 → 4            (data → analytics service → analytics page)
-8 → 2 (alert rule)   (dedup populates the data the alert reads)
-9 (OCR) → 11 (realapi)
-```
-
-Wall-clock minimum ~10 days (one engineer, sequential critical path); realistic with overhead ~13 days; calendar 2.5–3 weeks.
-
-### Acceptance gates per PR
-
-- `pnpm tsc --noEmit` and `pnpm lint` clean
-- Vitest unit + integration green (incl. new tests)
-- Playwright smoke green for the surface touched
-- Visual baselines regenerated and reviewed in PR diff
-- For PRs touching external integrations (9 OCR, 11 realapi): relevant `realapi` spec verified locally before merge
-
-### Risk register
-
-| Risk                                                    | Mitigation                                                                                                                                                        |
-| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Alert engine false positives spam users                 | Each rule has a "snooze" window in metadata; rules ship behind a feature flag `alerts.{rule_id}.enabled`; QA seeds production-shape data before flipping flags on |
-| Analytics queries slow on large datasets                | `analytics_snapshots` materialized cache; cron recomputes off the request path; queries use existing per-port indexes                                             |
-| Claude Vision OCR cost spirals                          | Default to Haiku 4.5 (~10× cheaper than Sonnet); ephemeral system-prompt cache hits ~80%; per-port quota with admin-visible meter                                 |
-| OCR low-quality on blurry receipts                      | Confidence threshold (< 0.6) flips to "verify mode" — user must touch every field before save; failure metric tracked in admin/monitoring                         |
-| Audit log table large (millions of rows)                | Already partitioned-friendly via the GIN tsvector index; pagination uses cursor on `(created_at, id)` not OFFSET                                                  |
-| Alert socket fanout overwhelms client                   | Throttle the engine cron to once per 5min; client debounces React Query refetches                                                                                 |
-| Interest stale rule fires for legitimately paused leads | Add a per-interest `paused_until` field as a follow-up if operators ask; v1 ships without                                                                         |
-
-## Glossary
-
-- **Alert** — operator-facing actionable card, rule-fired, dismissible
-- **Rule** — a pure-function evaluator that takes (port, db) and returns alert candidates
-- **Fingerprint** — `hash(rule_id + entity_type + entity_id)` used to dedupe alerts across re-evaluations
-- **Snapshot** — cached chart data row in `analytics_snapshots`, refreshed on cron
-- **EOI queue** — saved-view filter on the documents hub, not a separate page
-- **OCR** — Claude Vision extraction of structured expense fields from receipt images
-- **Audit log** — read view of the existing `audit_logs` table; no schema change beyond a tsvector column
-
-## Open questions for the user
-
-- Which port should be the **default landing dashboard** when a super-admin logs in (currently first-port-by-name; analytics page works the same)?
-- Should the alert rail be **always visible on all dashboard pages** or only on `/dashboard` (currently spec'd as the latter)?
-- Do you want the **Audit log retention policy** (delete > N days old) wired in v1 or deferred to Phase D?
-- Should **OCR be opt-in per port** (admin toggle) or always-on with a quota?

docs/superpowers/specs/2026-04-29-gws-inbox-triage-design.md

@@ -1,376 +0,0 @@
-# Google Workspace inbox-triage integration (exploratory)
-
-**Status:** Exploratory — not approved for build
-**Date:** 2026-04-29
-**Tracks:** AI inbox-triage, Google Workspace email connection
-
-## What this spec is for
-
-The user has flagged inbox-triage as the most valuable AI surface left to
-build, but conditioned email integration on it being via Google Workspace
-specifically (not generic IMAP), with a per-port toggle so clients who
-don't use GWS aren't billed for capability they can't reach.
-
-This document captures what that build actually costs — especially on
-the Google side, which is where most teams underestimate the work — so
-we can decide whether to commit before writing any code. **Nothing in
-this spec is approved for implementation.** The deliverable is a go /
-no-go decision and, if go, a scope choice between three deployment
-models that cost wildly different amounts of calendar time.
-
-## What inbox-triage actually does for the user
-
-Concretely, on the staff member's desktop:
-
-1. **Linked-inbox panel on the client detail page.** When you open
-   `/[port]/clients/<id>` you see the last N email threads with that
-   client, pulled from the staff member's own Gmail. Each thread has
-   the latest message preview, an "open in Gmail" deep-link, and a
-   "draft reply" button (Phase 2+).
-2. **Inbox triage queue.** A new top-level page `/[port]/inbox` that
-   lists unread/unanswered threads ranked by AI-assessed importance
-   (high-value client, contractual urgency, chase-overdue). Each row
-   has one-click actions: "log this as a note on the client",
-   "create a follow-up reminder", "draft reply".
-3. **Email-driven alerts.** When a high-value client emails and no one
-   responds within X hours, the existing alerts engine fires a
-   `inbox.unanswered_high_value` rule (slots into the alert framework
-   from Phase B without schema change).
-4. **Reply drafts (Phase 3).** AI generates a reply draft grounded in
-   the client's CRM record (open interests, pending reservations,
-   recent invoices). Staff edit and send through Gmail.
-
-The value is selective: a port with three staff members fielding 50
-client emails a day saves maybe an hour a day collectively if the
-ranking is right. Below that volume the build doesn't pay back.
-
-## What already exists in the codebase
-
-The CRM is roughly halfway scaffolded for this:
-
-| Surface                                         | Status                  | Notes                                                                                                                    |
-| ----------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `email_accounts` table                          | ✅ Exists               | Has `provider: 'google' \| 'outlook' \| 'custom'` discriminator and `imap_*` / `smtp_*` cols. Built for IMAP, not OAuth. |
-| `email_threads` / `email_messages` tables       | ✅ Exists               | Already linked to `clientId`. Schema is good as-is for Gmail.                                                            |
-| `email-threads.service.ts` `syncInbox()`        | ⚠ Stub-ish              | IMAP-flow only. Won't reach Gmail without OAuth + Gmail API rewrite.                                                     |
-| `email` BullMQ queue + `inbox-sync` job name    | ✅ Exists               | Worker dispatches on the job name; new sync impl drops in.                                                               |
-| `google_calendar_tokens` table                  | ✅ Exists               | OAuth token storage shape we can mirror for Gmail.                                                                       |
-| Per-port email override (port `email_settings`) | ✅ Exists               | Used for outbound only today; Gmail integration is per-staff-user, not per-port.                                         |
-| `ai_usage_ledger` + per-port `aiEnabled` flag   | ✅ Exists (Phase 3a/3b) | Triage AI calls book against the same ledger.                                                                            |
-| `withRateLimit('ai', ...)` wrapper              | ✅ Exists (Phase 3c)    | Caps triage AI traffic at 60/min/user out of the box.                                                                    |
-
-Net: schemas are mostly right. The OAuth flow, Gmail API client, push
-notification receiver, and triage classifier are the new builds.
-
-## Why Google Workspace specifically
-
-The user's stated constraint: "I don't think we need email integration
-unless we connect it to Google Workspace." Reasons that hold up:
-
-- **No password storage.** OAuth tokens are revocable, scoped, and
-  rotate. IMAP requires app passwords, which Google has been actively
-  deprecating since 2024 — they'll be gone for the workspace plans
-  this product targets.
-- **Push notifications, not polling.** Gmail's `users.watch` API plus
-  Google Pub/Sub means we get an HTTP callback within seconds of a new
-  message landing. IMAP requires polling on a 30-60 second cadence,
-  which costs more and lags worse.
-- **Search and labels.** The Gmail API exposes label management and
-  full-text search natively; IMAP search is much weaker.
-- **Threading.** Gmail's `threadId` is canonical. Reconstructing
-  threads over IMAP from `In-Reply-To` / `References` headers is
-  reliable in theory, painful in practice.
-
-Microsoft 365 is the obvious peer integration but is out of scope here.
-The Graph API model is similar enough that a future M365 path can reuse
-most of the storage shape.
-
-## Three deployment models — pick one before building
-
-This is the most important decision in the spec. Each model has
-different OAuth-verification consequences, which dominate everything
-else.
-
-### Model A — Marketplace-published OAuth app
-
-A single OAuth client owned by Port Nimara, listed in the Google
-Workspace Marketplace, that any GWS customer can install. Each staff
-member clicks "Connect Gmail," consents to the scopes, and the CRM
-stores their refresh token.
-
-**Google-side work:**
-
-1. Build the OAuth flow in CRM (~1 week).
-2. Submit for OAuth verification. Gmail's `gmail.readonly` /
-   `gmail.modify` scopes are **restricted scopes** — they require:
-   - Domain-verified production URLs
-   - A homepage with a privacy policy that explicitly enumerates which
-     scopes are used and why
-   - A demo video (literally a screen recording) showing the consent
-     screen and what happens next
-   - **A third-party security assessment from a Google-approved
-     vendor** ($15k–$75k, 6–12 weeks)
-   - A Cloud Application Security Assessment (CASA) report
-3. Marketplace listing review (~2 weeks after CASA passes).
-
-**Calendar time:** 4–6 months.
-**Money:** $15k–$75k for the security assessment alone.
-**Recurring:** Re-verification every 12 months.
-
-Right answer if Port Nimara wants to be the marina-CRM that ships GWS
-out of the box for _any_ customer. Wrong answer if there are <5
-customers who'd use it.
-
-### Model B — Per-customer "Internal" OAuth app
-
-Each customer's GWS admin creates an OAuth client _inside their own
-workspace_ and gives Port Nimara the client ID + secret. Because the
-app is "Internal," Google skips verification entirely — the consent
-screen is unverified-but-permitted. Tokens never cross workspace
-boundaries.
-
-**Google-side work per customer:**
-
-1. Customer's GWS admin enables the Gmail API in their Cloud project.
-2. Creates an OAuth 2.0 client ID with type "Internal" + your CRM's
-   redirect URI.
-3. Hands the client ID + secret to Port Nimara out-of-band.
-4. Staff connect their Gmail through that client.
-
-**Calendar time per customer:** ~1 hour of admin work.
-**Money:** $0.
-**Limit:** Doesn't span across GWS workspaces. A user with two GWS
-accounts (e.g. the marina + a personal workspace) can only connect the
-one matching the OAuth client.
-
-This is the **clear winner for the current customer base**: small
-number of customers, each with their own GWS workspace, and each
-buying the integration as part of an onboarding conversation.
-
-### Model C — Forward-to-CRM mailbox
-
-The CRM exposes a per-port email alias (e.g.
-`port-nimara-NN@inbox.portnimara.com`). Customers configure a Gmail
-filter or mailing rule that BCCs that alias on relevant threads. The
-CRM ingests via SMTP and runs the same triage pipeline.
-
-**Google-side work:** None. Customer does it as a Gmail filter.
-**Calendar time:** ~1 week of CRM-side build.
-**Limit:** Receive-only — no reply drafts, no thread state changes,
-no labels. The "draft reply" feature in Phase 3 above is impossible
-under this model.
-
-Model C is the right answer if the user wants to ship inbox-triage
-_now_ and decide on bidirectional Gmail integration later. The schema
-is designed so the model can be upgraded to A or B without data
-migration.
-
-### Recommendation
-
-**Build Model B first.** It costs nothing on the Google side, takes
-~3 weeks of CRM work, and matches the actual customer profile.
-**Promote to Model A only after 3+ paying customers ask for it
-unprompted.** Until then, the security-assessment cost can't justify
-itself.
-
-Model C as a fallback for customers who refuse to set up an Internal
-OAuth app. Build it last, lazily — the schema accommodates it.
-
-## End-to-end flow (Model B)
-
-### 1. Per-port OAuth-app config
-
-New admin page `/[port]/admin/google-workspace`:
-
-- Field: "OAuth client ID" (their internal client ID)
-- Field: "OAuth client secret" (encrypted at rest using `ENCRYPTION_KEY`)
-- Field: "Authorized redirect URI" (read-only; we display the value
-  they need to paste into their Google Cloud Console)
-- Toggle: "Enable Gmail integration for this port"
-
-Stored in `system_settings` under key `gws.config`, port-scoped.
-Resolution mirrors the existing OCR config service.
-
-### 2. Per-staff connect flow
-
-Staff member visits `/[port]/me/integrations`, clicks "Connect Gmail."
-
-```
-GET /api/v1/auth/gws/start
-  → looks up port's gws.config
-  → builds Google authorize URL with port's client_id + state token
-  → 302 to Google
-[ user consents ]
-  → 302 back to /api/v1/auth/gws/callback?code=…&state=…
-  → exchanges code for tokens via port's client_secret
-  → stores in new `gws_user_tokens` table (encrypted)
-  → schedules an `inbox-watch` job
-```
-
-### 3. Push notification subscription
-
-After tokens are stored, the worker calls
-`gmail.users.watch({ topicName: <Pub/Sub topic>, labelIds: ['INBOX'] })`.
-Gmail then posts to a Pub/Sub topic on every inbox change. The CRM
-exposes a Pub/Sub push subscription endpoint at
-`/api/webhooks/gmail-push` which fetches the changed messages via the
-delta `historyId` and writes them into `email_messages`.
-
-Watch subscriptions expire every 7 days. A maintenance job
-re-establishes them daily.
-
-### 4. Triage pipeline
-
-For each new inbound message:
-
-1. Match against `clients` and `companies` by `from_address` against
-   `client_contacts` (email channel). Persist a thread→client link if
-   found.
-2. If port has `aiEnabled` AND `gws.triageEnabled`, queue an `ai`
-   job that classifies the thread:
-   - `urgency`: low / medium / high
-   - `category`: invoice-question / availability / contract / other
-   - `requires_response`: boolean
-3. AI call records into `ai_usage_ledger` with `feature='inbox_triage'`.
-   The existing per-port budget gates apply automatically.
-4. Triage output written to a new `email_triage` table keyed on
-   `email_messages.id`.
-
-### 5. UI surfaces
-
-- `/[port]/inbox` — sorted by triage rank, port-wide view.
-- Linked-inbox panel on `client-tabs.tsx` — adds a new "Email" tab
-  pulling from `email_threads` filtered to that client.
-- Alert rule `inbox.unanswered_high_value` slots into Phase B's
-  alert engine; no schema change.
-
-## Schema additions
-
-Three new tables, all port-scoped where it matters:
-
-```ts
-// Per-staff Gmail tokens. Mirror of google_calendar_tokens.
-gws_user_tokens {
-  id, userId (UNIQUE), portId, emailAddress,
-  accessTokenEnc, refreshTokenEnc, tokenExpiry,
-  scope, watchExpiresAt, watchHistoryId,
-  connectedAt, lastSyncAt, syncEnabled, createdAt, updatedAt
-}
-
-// Triage classifications keyed to messages.
-email_triage {
-  messageId (PK, FK → email_messages.id ON DELETE CASCADE),
-  urgency, category, requiresResponse,
-  modelVersion, tokensUsed, classifiedAt
-}
-
-// Pub/Sub idempotency log. Gmail re-delivers; we dedupe.
-gws_push_log {
-  messageId (Pub/Sub message id, PK),
-  historyId, receivedAt
-}
-```
-
-Plus extensions to `email_messages`:
-
-- `googleMessageId` (text, indexed) — Gmail's own ID for thread ops.
-- `googleThreadId` (text, indexed).
-- `gmailLabels` (text[]) — for "is unread" checks without hitting Gmail.
-
-The existing `emailAccounts.provider='google'` column repurposes
-unchanged; the IMAP fields go nullable since OAuth-flow accounts won't
-populate them.
-
-## AI cost interaction
-
-Triage AI is opt-in **twice**: the port admin must turn on
-`aiEnabled` (Phase 3a flag, default off) **and** `gws.triageEnabled`
-(this spec, default off). Either toggle off and the inbox sync still
-runs but skips classification, so staff can manually scan threads
-without burning tokens.
-
-Per-message token cost on a current Haiku-class model is roughly
-1500–2500 tokens including the system prompt. A port doing 200 inbound
-emails a day at the upper bound is ~500k tokens/day. The default
-hard-cap is 500k/month, so triage will trip it inside a day. Two
-mitigations baked in:
-
-- The system prompt is short (<500 tokens) and prompt-cached on the
-  Anthropic side, so most tokens are output.
-- Triage runs only on threads not already classified — re-syncs from
-  the watch loop don't re-bill.
-
-The admin UI shows triage as its own line in the per-feature breakdown
-so customers can see how much their inbox is costing them and tune
-caps accordingly.
-
-## Phased build (assuming Model B)
-
-| Phase                        | Scope                                                                                                   | Effort | Ships when                                                  |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------- |
-| **G1** Connect               | OAuth flow + per-port config + per-user token storage. No sync yet. Staff can connect; nothing happens. | 1 week | Standalone                                                  |
-| **G2** Read-only sync        | Pub/Sub push receiver + delta sync into `email_messages`. Linked-inbox tab on client detail. No AI.     | 1 week | After G1                                                    |
-| **G3** Triage classification | AI classifier, `email_triage` writes, `/inbox` page sorting. Per-port toggle.                           | 1 week | After G2; depends on Phase 3b budgets being live (they are) |
-| **G4** Reply drafts          | Gmail API send + draft creation. "Draft reply" button on the client detail Email tab.                   | 1 week | After G3                                                    |
-| **G5** Alerts                | New `inbox.unanswered_high_value` rule. Hooks into Phase B alert engine.                                | 2 days | After G3                                                    |
-
-Total: ~5 weeks for a single engineer, assuming the user provides one
-real GWS workspace to test against during G1.
-
-## Open decisions for the user
-
-These are the questions to resolve before scheduling the build, in
-priority order:
-
-1. **Deployment model — A, B, or C?** Default recommendation B.
-2. **Single user or domain-wide delegation?** Per-staff connect (one
-   token per user) is simpler. Domain-wide delegation lets the port
-   admin connect once on behalf of every staff member but requires
-   the customer to grant a service account broader access. Default
-   recommendation: per-staff.
-3. **Scope set.** Minimal viable scope is `gmail.readonly`. To send
-   replies (G4) we need `gmail.send`. To manage labels (e.g. mark
-   "triaged-by-CRM") we need `gmail.modify`. Each scope expansion
-   widens the consent screen scariness but doesn't add new
-   verification steps under Model B.
-4. **Pub/Sub topic ownership.** Pub/Sub topics live in _some_ GCP
-   project. Under Model B the customer's project owns the topic —
-   they pay for Pub/Sub (cents/month) and grant our service account
-   subscriber access. Alternative: Port Nimara owns the topic and
-   the customer's Gmail publishes cross-project (allowed, slightly
-   more setup). Default: customer-owned topic, fewer moving parts.
-5. **Triage model.** Haiku 4.5 is right for cost; Sonnet 4.6 is
-   right if the ranking quality on Haiku turns out to be poor.
-   Defer this until G3 has real-world tuning data.
-
-## Things that are NOT in this spec
-
-- **Microsoft 365 / Outlook integration.** Same shape, different API.
-  Once Model B is proven on GWS, Graph API takes another ~3 weeks.
-- **Reply drafts grounded in CRM context.** That's G4 and depends on
-  the work in this spec, but the prompt engineering for "good replies
-  citing this client's open interests + reservations + invoices"
-  deserves its own design pass before building.
-- **Cross-staff triage queue (i.e. "show me all unanswered emails
-  across the team").** That requires either domain-wide delegation
-  (decision #2 above) or per-staff opt-in to a shared view. Punt
-  until staff actually ask for it.
-- **Sentiment / urgency tone analysis.** Tempting; almost always
-  wrong; skip in v1.
-- **"Smart drafts" using the recipient's past replies as context.**
-  Every customer asks for this and almost no one uses it once
-  built. Skip.
-
-## Cost summary at a glance
-
-| Item                            | Model A                         | Model B                                | Model C                              |
-| ------------------------------- | ------------------------------- | -------------------------------------- | ------------------------------------ |
-| Build effort                    | 3–4 weeks                       | ~5 weeks (over G1–G5)                  | ~1 week (receive-only)               |
-| Calendar time to first customer | 4–6 months                      | 1 hour of customer admin work          | 1 hour of customer Gmail-filter work |
-| Up-front cash                   | $15k–$75k (CASA)                | $0                                     | $0                                   |
-| Recurring                       | Re-verification annually        | None                                   | None                                 |
-| Best for                        | 50+ customers, Marketplace play | 1–10 customers, white-glove onboarding | Customers who refuse OAuth setup     |
-
-The recommendation stands: build Model B for G1 + G2 + G3, ship that,
-and let real customer demand decide whether G4/G5 and Model A
-promotion are worth the calendar time.

docs/superpowers/specs/2026-04-29-mobile-optimization-design.md

@@ -1,189 +0,0 @@
-# Mobile Optimization Design
-
-**Status**: Design approved 2026-04-29 — pending plan.
-**Plan decomposition**: Foundation PR (§3) is one implementation plan; per-page migration phases (§5) become follow-up plans, scoped per phase.
-**Branch base**: stacks on `refactor/data-model`.
-**Out of scope**: Phase B/C features, desktop redesign, Capacitor wrapper, swipe-actions on rows, native menus, server-driven UI.
-
----
-
-## 1. Background
-
-The CRM was built desktop-first. A 2026-04-29 mobile audit captured every authenticated and public page across the active iPhone viewport range. Findings:
-
-1. **No `viewport` meta in the root layout** (one exists only in the scanner PWA sub-layout, `src/app/(scanner)/[portSlug]/scan/layout.tsx`). Without it, iOS Safari renders pages at the default 980px logical width and zooms out to fit — text becomes unreadable and touch targets sub-tappable. Playwright's `isMobile` emulation in the audit forces 393px-wide rendering, which exposes the layout breakage you'd otherwise have to discover by pinching to zoom.
-2. **Topbar overflows**. Search input + port switcher + sign-out button cram into one row; sign-out clips off the right edge as a half-visible blue bar on every authenticated page.
-3. **Tables render as desktop tables**. Every list page (clients, yachts, companies, invoices, expenses, interests, audit, users, etc.) shows truncated columns with horizontal scroll.
-4. **Page headers don't downsize**. Titles like "Dashboard" truncate to "Dash..."; primary action buttons (`+ New Client`) overlap their subtitles.
-5. **Detail page action chips overflow**. The chip row ("Invite to portal | GDPR export | Archive | …") horizontally overflows on every detail page.
-6. **One half-good pattern**: detail pages already collapse their tabs to a `<select>` dropdown on small screens. Worth extending.
-7. **Auth + scanner pages are already mobile-first** (`/login`, `/[portSlug]/scan`). Reference for the "what good looks like" target.
-
-The audit harness (`tests/e2e/audit/mobile.spec.ts` + `mobile-audit` Playwright project) is added on this branch (not yet committed); re-runs regenerate `.audit/mobile/` (gitignored).
-
-## 2. Approach
-
-**Adaptive shell + responsive content** — chosen over (a) per-page conditional render, (b) a separate `(mobile)` route group, and (c) Tailwind-only responsive.
-
-The "native feel" the user wants comes from the chrome — bottom tab bar, sheet modals, sticky compact header, safe-area awareness. Page content (forms, lists, details) doesn't need duplication; it gets responsive via shared mobile-aware primitives. This concentrates the dedicated-mobile work in ~10 components and keeps content single-source.
-
-**Breakpoint**: Tailwind `lg` (1024px). Below `lg`, the mobile shell renders. At and above, the existing desktop shell is untouched.
-
-### 2.1 Target iPhone viewport range
-
-The mobile shell + content primitives must look correct across the full active iPhone viewport range (portrait):
-
-| Tier                                       | Models                                          | Viewport |
-| ------------------------------------------ | ----------------------------------------------- | -------- |
-| Narrowest                                  | iPhone SE 2nd / 3rd gen                         | 375×667  |
-| Standard                                   | iPhone 12/13/14 (and Mini)                      | 390×844  |
-| Standard newer                             | iPhone 15 / 15 Pro / 16                         | 393×852  |
-| Pro newer (Dynamic Island, thinner bezels) | iPhone 16 Pro / 17 Pro                          | 402×874  |
-| Plus / older Max                           | iPhone 14 Plus / 15 Plus / 15 Pro Max / 16 Plus | 430×932  |
-| Pro Max                                    | iPhone 16 Pro Max / 17 Pro Max                  | 440×956  |
-
-**Anchors used by audit and design validation**: 375×667 (worst-case narrow + short), 393×852 (most common current), 402×874 (current Pro), 440×956 (current Pro Max). Models within ±5px of an anchor (390, 430) are skipped — primitives that look correct at the anchors will look correct at neighbors.
-
-**Dynamic Island**: iPhone 14 Pro and later have a larger top safe-area inset (~59px vs ~47px on classic-notch models). The CSS `env(safe-area-inset-top)` we expose as `pt-safe` handles this transparently — no per-model code paths.
-
-**Landscape**: out of scope for this design. Phones in landscape are rare for CRM-style work; if needed later, the mobile shell at landscape widths would still fall under `lg` and would just stretch. Tablet landscape is addressed in the §5 tablet-pass phase.
-
-**Routing**: no new route group. URLs and middleware unchanged. RBAC, services, queries, validators, RHF/zod forms, TanStack Query stores, socket.io — all unchanged.
-
-## 3. Foundation PR
-
-A single branch lands the infra + shell + primitives before any per-page work. After this merges, every authenticated page already gains: real viewport meta, no clipped topbar, bottom tab navigation, safe-area handling, and 44px touch targets — without any per-page edits.
-
-### 3.1 Infrastructure
-
-- `viewport` export in `src/app/layout.tsx` — `width=device-width, initial-scale=1, viewport-fit=cover`.
-- `theme-color` meta + `apple-mobile-web-app-capable` meta + `apple-mobile-web-app-status-bar-style` for PWA-ish status-bar integration.
-- Safe-area CSS variables (`env(safe-area-inset-*)`) exposed as Tailwind utilities (`pt-safe`, `pb-safe`, `pl-safe`, `pr-safe`).
-- `useIsMobile()` hook in `src/hooks/use-is-mobile.ts` — backed by `window.matchMedia('(max-width: 1023.98px)')`, no resize listener.
-- Server-side body-class detection: the root layout (`src/app/layout.tsx`) reads the `user-agent` request header via `next/headers`'s `headers()`, runs a small known-mobile-token check (Mobile / iPhone / iPad / Android — no library), and renders `<body data-form-factor="mobile|desktop">`. No middleware needed. CSS `[data-form-factor="mobile"]` reveals the mobile shell. The CSS media-query fallback (`@media (max-width: 1023.98px)`) handles UA misclassification (e.g., desktop browser resized to narrow width, or stripped UA).
-
-### 3.2 Mobile shell
-
-Both desktop and mobile shells are rendered to the DOM by the root layout; CSS reveals one and hides the other based on `[data-form-factor="mobile"]` plus a `@media (max-width: 1023.98px)` fallback. The existing `<Sidebar>` and `<Topbar>` components stay unchanged for the desktop shell. The mobile shell is wholly new:
-
-- **`<MobileLayout>`** (`src/components/layout/mobile/mobile-layout.tsx`)
-  Fixed 52px compact topbar (safe-area aware) + scrollable content + fixed 56px bottom tab bar (safe-area inset). Renders instead of the desktop sidebar+topbar shell when the form factor resolves to mobile.
-
-- **`<MobileTopbar>`**
-  Page title (auto-truncating, single-line) + back button when route depth > 1 + single primary action slot (passed via context from the page) + port-switcher behind a `<Sheet>` trigger.
-
-- **`<MobileBottomTabs>`**
-  Fixed 5 tabs: **Dashboard / Clients / Yachts / Berths / More**. Active state from current path. Lucide icons (no emoji). Badge support for the alerts count.
-
-- **`<MoreSheet>`**
-  Bottom sheet opened by the More tab. Holds the long tail in a scrollable list grouped by section: Companies, Interests, Invoices, Expenses, Documents, Email, Alerts, Reports, Reminders, Settings, Admin (with admin nesting one level deep into a child sheet).
-
-- **`<MobileLayoutProvider>`**
-  React context that lets each page push its title, back button, and primary action slot to `<MobileTopbar>` via a hook (`useMobileChrome({ title, action })`).
-
-### 3.3 Primitives
-
-All built once in `src/components/shared/`. Render desktop-style above `lg`, mobile-style below.
-
-- **`<Sheet>`** — vaul-based bottom sheet on mobile, falls through to existing Radix `<Dialog>` on desktop. Same API as `<Dialog>` so adoption is mechanical.
-- **`<DataView>`** — accepts the same column defs the codebase uses today via TanStack Table. Above `lg`: renders the existing table. Below `lg`: renders a card list with a per-row `cardRender({ row }) => ReactNode` callback. Filter chips stay above the list; sort moves into a `<Sheet>` opened by a sort button.
-- **`<PageHeader>`** — title + optional subtitle + actions. Truncates title to one line, stacks actions to a second row on mobile, hides subtitle below `sm` if action row is present.
-- **`<ActionRow>`** — chip-style action group; `flex-nowrap overflow-x-auto scroll-smooth snap-x` on mobile, no overflow on desktop.
-- **`<DetailPageShell>`** — wraps detail pages with: sticky compact header (entity name, primary status), tab dropdown selector (existing pattern, extracted), scrollable content area, optional sticky bottom action bar (Save / Archive / etc.) on mobile that pins above the bottom tab bar.
-- **`<FilterChips>`** — chip-row filter UI used by `<DataView>`. Active filters are dismissable chips; "Add filter" opens a `<Sheet>`.
-
-### 3.4 Default style adjustments
-
-- `<Button>` and `<Input>` defaults: `min-h-11` (44px, Apple HIG touch-target).
-- `<Input>` and `<Textarea>` body text: `text-base` (16px) so iOS doesn't zoom on focus.
-- `<Dialog>` default base styling tweaked so any remaining unmigrated dialogs render full-screen on mobile (until they get migrated to `<Sheet>`).
-
-### 3.5 Bundle impact
-
-Both shells render server-side and switch via the `data-form-factor` body attribute, so both ship to every client (dynamic-importing one would cause a hydration flash). Rough estimate ~40KB gzipped added to the layout subtree for the mobile shell + new primitives (vaul ≈ 5KB gz, the rest is in-house components). Verify post-build with `pnpm build` and adjust if it's materially higher. Acceptable trade for no flash and no UA-based render-time branching.
-
-### 3.6 PWA assets
-
-The PWA scanner already references `icon-192.png`, `icon-512.png`, `icon-512-maskable.png` from `public/`, but those files don't exist yet (separate flagged blocker). The mobile shell adds an `apple-touch-icon` reference too. The Foundation PR includes placeholder PNGs so home-screen install works; production-quality icons can replace them without a code change.
-
-## 4. Per-page playbook
-
-Once foundation lands, each page follows the same workflow:
-
-1. Open the page in headed Playwright at the anchor viewports per §2.1 (start at 393×852 for the iteration loop, spot-check 375 and 440 before declaring done).
-2. Replace any `<Dialog>` with `<Sheet>`.
-3. If list page: wrap the table in `<DataView>` and provide a `cardRender` callback. The 2-3 fields shown on the card are decided per page during migration with the user.
-4. Replace the ad-hoc page header with `<PageHeader>`.
-5. Replace ad-hoc action button rows with `<ActionRow>`.
-6. Touch up any custom embedded widgets the page uses (rare for simple pages, common for `email`, `documents`, `expenses/scan`).
-7. User reviews live in the headed browser, points out tweaks, iterate.
-
-Most pages take 5–15 minutes in this loop. Heavy pages (email inbox, documents hub) may take 30–60 because the embedded widgets need their own mobile treatment beyond the primitives.
-
-## 5. Migration sequence
-
-After foundation PR:
-
-1. **Quick-win sweep** (~half day) — pages mostly fixed by foundation alone. Just need `<PageHeader>` swap-in (no list-card conversion, no detail-shell wrap):
-   `dashboard` (overview), `settings` (user-profile), `reports`, and the admin sub-pages that are forms or stat cards: `admin/settings`, `admin/branding`, `admin/forms`, `admin/ocr`, `admin/roles`, `admin/tags`, `admin/documenso`, `admin/templates`, `admin/custom-fields`, `admin/monitoring`, `admin/backup`, `admin/webhooks`, `admin/import`, `admin/ports`.
-2. **List pages** (~1–2 days) — convert via `<DataView>` + per-page `cardRender`:
-   `clients`, `yachts`, `companies`, `berths`, `interests`, `invoices`, `expenses`, `alerts`, `reminders`, `admin/audit`, `admin/users`.
-3. **Heavy pages** (~1 day each) — embedded widgets need their own mobile treatment beyond the primitives:
-   `documents` (sig-tracking + filters from Phase A), `email` (thread list + reader + composer).
-4. **Detail pages** (~1–2 days) — wrap in `<DetailPageShell>`, extend the tab-dropdown pattern, add sticky bottom action shelf:
-   `clients/[clientId]`, `yachts/[yachtId]`, `companies/[companyId]`, `berths/[berthId]`, `invoices/[id]`, `expenses/[id]`.
-5. **Forms & wizards** — touch-up only, since `<Input>`/`<Button>` defaults handle the bulk:
-   `invoices/new` (3-step wizard), `expenses/scan` (already mobile-first, just verify).
-6. **Portal** — same patterns, smaller scope:
-   authenticated: `portal/dashboard`, `portal/invoices`, `portal/my-yachts`, `portal/documents`, `portal/interests`, `portal/my-reservations`. Public: `portal/login`, `portal/activate`, `portal/forgot-password`, `portal/reset-password` (already styled by `<BrandedAuthShell>` — just verify).
-7. **Tablet pass** — re-audit at iPad Air 11" portrait (820×1180) and landscape (1180×820), iPad Air 13" portrait (1024×1366) and landscape (1366×1024). The 820 portrait case will hit the mobile shell (820 < 1024) and probably want a "tablet-portrait" treatment with sidebar visible — flagged for design refinement at that phase, not now. The other three viewports fall above `lg` and use the desktop shell unchanged.
-
-## 6. Testing
-
-- **Mobile audit project** (`mobile-audit` in `playwright.config.ts`) is the regression harness. Re-runs after every page-migration PR; output goes to `.audit/mobile/` (gitignored). Audit covers the four anchor viewports defined in §2.1: 375×667, 393×852, 402×874, 440×956. Run time ~14 min headed.
-- **Smoke project** gets a curated mobile-viewport variant (~10 pages at the 393×852 anchor) — adds ~2 min to CI; full audit stays out of CI to avoid the ~14 min cost.
-- **Visual baselines** — `visual` project gets new mobile snapshots at the 393×852 anchor for: dashboard, clients-list, clients-detail, invoices-list, invoices-new, scan, documents, login. Regenerate with `--update-snapshots` after intentional changes (existing convention).
-- **Anchor device descriptors** lifted into a shared fixture at `tests/e2e/fixtures/devices.ts` (one per anchor in §2.1) so specs don't redefine viewport.
-- **No new unit tests** for the primitives — they are presentational. Coverage comes from visual + integration runs.
-
-## 7. Open questions
-
-- **Bottom-tab taxonomy**: locked at Dashboard / Clients / Yachts / Berths / More for now. The More sheet holds everything else losslessly, so this is reversible — if real usage suggests a different top-5 (e.g., Interests or Invoices in the tabs), swap them later without code restructure.
-- **`refactor/data-model` push order**: 155 commits unpushed. Foundation PR can stack on top and rebase, or wait until that branch merges. Decision deferred to user.
-- **Desktop touch-target adjustments**: bumping `<Button>`/`<Input>` to `min-h-11` will affect desktop too. Verify visually that no desktop layout breaks; if any does, scope the bump to mobile-only via the `data-form-factor` attribute.
-
-## 8. Files to create
-
-```
-src/hooks/use-is-mobile.ts
-src/components/layout/mobile/
-  mobile-layout.tsx
-  mobile-topbar.tsx
-  mobile-bottom-tabs.tsx
-  more-sheet.tsx
-  mobile-layout-provider.tsx
-src/components/shared/
-  sheet.tsx                    (new — vaul wrapper)
-  data-view.tsx                (new — table↔card)
-  page-header.tsx              (new)
-  action-row.tsx               (new)
-  detail-page-shell.tsx        (new)
-  filter-chips.tsx             (new)
-src/app/layout.tsx             (modified — viewport export, theme-color, UA-derived data-form-factor body attribute via headers())
-public/icon-192.png            (placeholder PWA asset)
-public/icon-512.png            (placeholder PWA asset)
-public/icon-512-maskable.png   (placeholder PWA asset)
-public/apple-touch-icon.png    (placeholder PWA asset)
-tailwind.config.ts             (modified — safe-area utilities, touch-target defaults)
-tests/e2e/fixtures/devices.ts  (new — shared device descriptors)
-```
-
-## 9. Files to modify per page
-
-Per the playbook in §4, each page typically needs:
-
-- One swap of header markup → `<PageHeader>`.
-- For list pages: one wrap of table → `<DataView>` + add `cardRender` callback.
-- For detail pages: wrap in `<DetailPageShell>`.
-- Replace `<Dialog>` imports with `<Sheet>`.
-- No service, validator, query, or schema changes anywhere.

docs/website-refactor.md

@@ -1,160 +0,0 @@
-# Website → CRM wiring refactor
-
-The `website/` subrepo (Nuxt) currently writes inquiry submissions to NocoDB.
-The new CRM exposes its own public ingestion endpoints, so the website needs
-to be re-pointed at the CRM and the website's local server-side helpers can
-eventually be retired.
-
-This document describes **what needs to change in the website repo**. Nothing
-here applies to the CRM repo — that side is already done.
-
-## Endpoints the CRM now exposes
-
-Both are unauthenticated, IP-rate-limited (5/hour), and require an explicit
-port id (query param `?portId=…` or header `X-Port-Id`).
-
-| Form intent          | New CRM endpoint                         | Old NocoDB target        |
-| -------------------- | ---------------------------------------- | ------------------------ |
-| Berth interest       | `POST /api/public/interests`             | `Interests` (NocoDB)     |
-| Residential interest | `POST /api/public/residential-inquiries` | `Interests (Residences)` |
-
-Notification emails (client confirmation + sales-team alert) are sent by the
-CRM itself when these endpoints succeed, so the website's
-`sendRegistrationEmails` helper (`server/utils/email.ts`) is no longer
-required for these flows.
-
-## Required changes in the website repo
-
-### 1. New env vars
-
-Add to `.env` and the deploy environment:
-
-```
-PN_CRM_BASE_URL=https://crm.portnimara.com
-PN_CRM_PORT_ID=<uuid of the Port Nimara port row in CRM>
-```
-
-`PN_CRM_BASE_URL` defaults to the prod CRM. In dev it can point to the local
-tunnel (`shoulder-contain-…trycloudflare.com`) so submissions hit a dev DB.
-
-### 2. Refactor `server/api/register.ts`
-
-Today the file owns both the berth and residence branches and writes to
-NocoDB directly. After the refactor, both branches just relay to the CRM:
-
-```ts
-const baseUrl = process.env.PN_CRM_BASE_URL;
-const portId = process.env.PN_CRM_PORT_ID;
-
-if (category === 'Residences') {
-  await $fetch(`${baseUrl}/api/public/residential-inquiries?portId=${portId}`, {
-    method: 'POST',
-    body: {
-      firstName: body.first_name,
-      lastName: body.last_name,
-      email: body.email,
-      phone: body.phone,
-      placeOfResidence: body.address,
-      preferredContactMethod: body.method_of_contact, // 'email' | 'phone'
-      notes: body.notes,
-      // preferences: collect via new optional textarea (see section 4)
-    },
-  });
-  return { success: true };
-}
-
-// Berth branch
-await $fetch(`${baseUrl}/api/public/interests?portId=${portId}`, {
-  method: 'POST',
-  body: {
-    // map to the CRM's publicInterestSchema (see src/lib/validators/interests.ts)
-    firstName: body.first_name,
-    lastName: body.last_name,
-    email: body.email,
-    phone: body.phone,
-    address: body.address,
-    berthSize: body.berth_size,
-    berthMinLength: body.berth_min_length,
-    berthMinWidth: body.berth_min_width,
-    berthMinDraught: body.berth_min_draught,
-    yachtName: body.berth_yacht_name,
-    preferredMethodOfContact: body.method_of_contact,
-    specificBerthMooring: body.berth, // optional, links interest to a specific berth
-  },
-});
-return { success: true };
-```
-
-The reCAPTCHA verification stays in the website handler — the CRM trusts the
-website to gate its public endpoints.
-
-### 3. Retire dead code
-
-After step 2, the following can be deleted from the website:
-
-- `server/utils/websiteInterests.ts`
-- `server/utils/residentialInterests.ts`
-- `server/utils/nocodb.ts`
-- The NocoDB-specific call sites in `server/utils/email.ts` (the CRM
-  sends its own confirmation/alert emails)
-- NocoDB env vars (`NOCODB_*`)
-
-The Nuxt `/api/berths` route stays as-is — it reads from the
-`directus_items.berths` collection for the public site, not the CRM.
-
-### 4. Form additions on `pages/register.vue`
-
-The current residence branch only collects contact info. The CRM accepts an
-optional `preferences` field (free-text) and `notes` field. Add a
-"Preferences" textarea inside the residences block of
-`components/pn/specific/website/register/form.vue`:
-
-```vue
-<transition name="fade-down">
-  <div v-show="interest === 'residences'">
-    <vee-field
-      as="textarea"
-      class="form-input py-3 px-0 md:text-lg border-0 border-t border-davysgrey ..."
-      placeholder="Tell us what you're looking for (unit type, budget, timeline)"
-      name="residence_preferences"
-      :disabled="loading"
-    />
-  </div>
-</transition>
-```
-
-Append `preferences: body.residence_preferences` in the POST body in
-`server/api/register.ts`.
-
-### 5. Stand up a residential-only `residences.vue` form (optional)
-
-Today the residences interest is captured on `register.vue` via a radio. If
-the marketing team wants a dedicated CTA on `residences.vue`, add a small
-inline form using the same submit handler from step 2. No new endpoint —
-this is purely a UX addition.
-
-## Deployment order
-
-1. **CRM first**: deploy this repo, ensure `/api/public/interests` and
-   `/api/public/residential-inquiries` are reachable from the website host.
-2. **Verify in CRM**: configure `Inquiry Contact Email` and (for residential)
-   `Residential Notification Recipients` per port in
-   admin → settings.
-3. **Smoke test from a dev tunnel** (curl the public endpoints with a JSON
-   payload). Confirm rows land in `clients`/`residential_clients` and
-   notification emails are received.
-4. **Then deploy website changes** (sections 1–3 above). The form
-   submissions immediately start landing in the new CRM.
-5. **Cut-over note**: once the website is pointed at the CRM, leave the
-   NocoDB tables read-only as a historical archive. Don't delete them until
-   prod data has been imported into the new CRM (see "Prod data import
-   strategy" task #59 in the task list).
-
-## Open questions
-
-- **Port routing for multi-port deploys**: today the website only knows about
-  Port Nimara. If/when the website serves multiple ports, the `portId`
-  resolution needs to happen per-domain or per-route, not a single env var.
-- **Brand/email domain**: confirm whether residential confirmations should
-  send from the same `noreply@letsbe.solutions` address as marina, or a
-  dedicated residential mailbox. The CRM uses `SMTP_FROM`, which is global.

eslint.config.mjs

@@ -1,27 +1,130 @@
-import { dirname } from "path";
-import { fileURLToPath } from "url";
-import { FlatCompat } from "@eslint/eslintrc";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-});
+import nextCoreWebVitals from 'eslint-config-next/core-web-vitals';
+import prettier from 'eslint-config-prettier/flat';
 
 const eslintConfig = [
-  ...compat.extends("next/core-web-vitals", "next/typescript", "prettier"),
+  ...nextCoreWebVitals,
+  prettier,
   {
+    // Scope the typescript-eslint rule overrides to TS/TSX files. Without
+    // the `files` filter, eslint flat-config attempts to apply these
+    // rules to every walked file (including root-level JS / mjs / json
+    // configs) and fails because the typescript-eslint plugin only
+    // registers itself for TS/TSX. Surfaced 2026-05-14 when CI's
+    // `pnpm lint` command ran across the whole repo root.
+    files: ['**/*.ts', '**/*.tsx'],
     rules: {
-      "@typescript-eslint/no-explicit-any": "error",
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        { argsIgnorePattern: "^_" },
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      // React Compiler safety rules shipped with eslint-config-next@16 /
+      // react-hooks@7. Triage status (2026-05-13 sweep):
+      //   purity, set-state-in-render, immutability, refs,
+      //   set-state-in-effect — promoted to error after the cleanup
+      //   sweep (Wave 3 of the 2026-05-12 audit). All hits migrated to
+      //   either useQuery, render-phase derivation, key-based remount,
+      //   or a justified eslint-disable for canonical setState-on-
+      //   subscription patterns. New regressions block CI.
+      //   incompatible-library — informational only ("Compiler
+      //   skipped this file because of a non-Compiler-safe import").
+      //   No action needed; silenced to keep `pnpm lint` output
+      //   actionable.
+      'react-hooks/purity': 'error',
+      'react-hooks/set-state-in-render': 'error',
+      'react-hooks/immutability': 'error',
+      'react-hooks/refs': 'error',
+      'react-hooks/set-state-in-effect': 'error',
+      'react-hooks/incompatible-library': 'off',
+      // Icon-only buttons must carry a label that screen readers can
+      // surface — either an explicit `aria-label`, an `aria-labelledby`,
+      // a `title`, or a visible-but-sr-only text child. Catches the
+      // pattern where a `<button><Trash2 /></button>` ships with no
+      // accessible name. Default Next config enables this at `error`;
+      // we keep it loud so new code doesn't regress.
+      'jsx-a11y/control-has-associated-label': [
+        'warn',
+        {
+          labelAttributes: ['label'],
+          controlComponents: ['Button'],
+          ignoreElements: ['audio', 'canvas', 'embed', 'input', 'textarea', 'tr', 'video'],
+          ignoreRoles: [
+            'grid',
+            'listbox',
+            'menu',
+            'menubar',
+            'radiogroup',
+            'row',
+            'tablist',
+            'toolbar',
+            'tree',
+            'treegrid',
+          ],
+          depth: 5,
+        },
       ],
     },
   },
   {
-    ignores: ["client-portal/**"],
+    // User-facing copy in src/components and src/app should never use
+    // em-dashes (—) in JSX text. The user reads em-dashes as a
+    // tell-tale "AI-generated" marker; we prefer periods, commas, or
+    // simple hyphens. Code comments / audit-log strings / templates
+    // outside these directories are exempt.
+    //
+    // Same rule block also nudges new code toward CSS logical properties
+    // (ms-/me-/ps-/pe-/text-start/text-end/border-s/border-e) instead of
+    // physical Tailwind utilities. RTL isn't a roadmap requirement today,
+    // but every new ml-/mr-/pl-/pr-/text-left/text-right we accept now
+    // is a class we'd have to migrate later. Existing 1,000+ sites stay
+    // untouched (warn-only). Inline `// eslint-disable-next-line` when
+    // the directional intent is truly physical (e.g. a chevron icon).
+    files: ['src/components/**/*.tsx', 'src/app/**/*.tsx'],
+    rules: {
+      // Both selectors share `warn` severity because the RTL nudge is
+      // grandfathered (1,000+ existing sites use ml-/mr-/etc). The
+      // em-dash sweep cleared every existing instance (2026-05-21), so
+      // `warn` still effectively gates new code — it just doesn't break
+      // CI on grandfathered RTL utilities. Inline
+      // `// eslint-disable-next-line no-restricted-syntax` when the
+      // directional intent is truly physical.
+      'no-restricted-syntax': [
+        'warn',
+        {
+          selector: "JSXText[value=/\\u2014/]",
+          message:
+            'No em-dash in user-facing JSX text. Use period, comma, or hyphen instead.',
+        },
+        {
+          selector:
+            "JSXAttribute[name.name='className'] > Literal[value=/(?:^|[\\s:])(?:ml-|mr-|pl-|pr-|text-left|text-right|border-l\\b|border-r\\b|rounded-l-|rounded-r-)/]",
+          message:
+            'Prefer CSS logical properties (ms-/me-/ps-/pe-/text-start/text-end/border-s/border-e/rounded-s-/rounded-e-) over physical directional Tailwind utilities. Existing code is grandfathered; new code should default to logical so a future RTL pass is bounded.',
+        },
+      ],
+    },
+  },
+  {
+    // Tests assert response shape via expect() — narrowing every
+    // `res.json()` to a structural type adds boilerplate without catching
+    // bugs. Allow `any` casts at JSON boundaries in test files. Also
+    // relax unused-vars to warn (destructured-but-unused helpers are
+    // common in setup/teardown patterns).
+    files: ['tests/**/*.ts', 'tests/**/*.tsx'],
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    ignores: [
+      'client-portal/**',
+      'next-env.d.ts',
+      // Agent worktree artifacts — not part of the canonical tree.
+      '.claude/**',
+      // Build output + Next generated types
+      '.next/**',
+      'dist/**',
+      // Other sub-projects with their own toolchains
+      'website/**',
+    ],
   },
 ];
 

instrumentation.ts

@@ -0,0 +1,20 @@
+/**
+ * Next.js instrumentation hook (Next 13.4+ / 15+ / 16+).
+ *
+ * Runs once at server startup. We use it to wire Sentry's server +
+ * edge runtimes. The client init is auto-bundled by withSentryConfig
+ * from `sentry.client.config.ts`.
+ *
+ * The Sentry imports are gated behind the DSN check so the SDK stays
+ * a no-op when unconfigured.
+ */
+
+export async function register() {
+  if (!process.env.NEXT_PUBLIC_SENTRY_DSN) return;
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('./sentry.server.config');
+  }
+  if (process.env.NEXT_RUNTIME === 'edge') {
+    await import('./sentry.edge.config');
+  }
+}

next-env.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

next.config.ts

@@ -1,7 +1,96 @@
 import type { NextConfig } from 'next';
+import bundleAnalyzer from '@next/bundle-analyzer';
+import { withSentryConfig } from '@sentry/nextjs';
+
+const isProd = process.env.NODE_ENV === 'production';
+
+// Wrap the config with the bundle analyzer. Run `ANALYZE=true pnpm build`
+// to get treemaps of the client + server bundles after the build
+// completes. Pairs with the recharts dynamic-import work the audit
+// flagged — gives us the tool to verify chart bundles only ship on the
+// dashboard surface and not on routes that don't render them.
+const withBundleAnalyzer = bundleAnalyzer({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+/**
+ * Security headers applied to every response. Per audit-pass-#3 finding:
+ * the previous config emitted no CSP, X-Frame-Options, HSTS, or
+ * X-Content-Type-Options — the app was open to clickjacking + MIME
+ * sniffing.
+ *
+ * CSP notes:
+ *   - 'unsafe-inline' on style-src is required by Tailwind's runtime
+ *     style injection and Radix; revisit when Tailwind v4 ships a
+ *     nonce story.
+ *   - 'unsafe-eval' on script-src is dev-only — Next dev uses eval for
+ *     HMR. Production drops it.
+ *   - connect-src allows ws/wss for Socket.IO and https: for outgoing
+ *     fetches; tighten in prod via per-port branding URLs once we move
+ *     the s3 image references into a known allowlist.
+ *   - img-src https: is wide because port branding pulls from
+ *     s3.portnimara.com plus per-port image URLs configured at runtime.
+ */
+// Dev-only allow-list: react-grab (the in-page click-to-source devtool)
+// is fetched from unpkg, so script/style/connect must allow it. Strip
+// these entries in prod via the conditional below.
+const devScriptHosts = isProd ? '' : ' http://unpkg.com https://unpkg.com';
+const devConnectHosts = isProd ? '' : ' http://unpkg.com https://unpkg.com';
+
+// Fallback CSP for paths the proxy doesn't run on (static assets,
+// API JSON responses where script-src is moot). Production HTML
+// responses get a stricter per-request nonce-based CSP set in
+// `src/proxy.ts:applyCsp`; this header just provides a sane default
+// so a misconfigured static-only route still has a CSP.
+//
+// Dev keeps 'unsafe-inline' + 'unsafe-eval' on script-src because
+// Next's HMR runtime evaluates code dynamically and the nonce
+// machinery doesn't reach it.
+const csp = [
+  "default-src 'self'",
+  `script-src 'self' 'unsafe-inline'${isProd ? '' : " 'unsafe-eval'"}${devScriptHosts}`,
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: blob: https:",
+  "font-src 'self' data:",
+  `connect-src 'self' ws: wss: https:${devConnectHosts}`,
+  "frame-ancestors 'none'",
+  "base-uri 'self'",
+  "form-action 'self'",
+  "object-src 'none'",
+].join('; ');
+
+const securityHeaders = [
+  { key: 'Content-Security-Policy', value: csp },
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy', value: 'camera=(self), microphone=(), geolocation=()' },
+  ...(isProd
+    ? [{ key: 'Strict-Transport-Security', value: 'max-age=31536000; includeSubDomains' }]
+    : []),
+];
 
 const nextConfig: NextConfig = {
   output: 'standalone',
+  // Hide the floating dev indicator (the little circle/N badge in the
+  // corner). Compile errors still surface via the full overlay; this
+  // only removes the idle "everything is fine" indicator that's been
+  // visible in every screenshot from the iPhone testing pass.
+  devIndicators: false,
+  // LAN access from a real iPhone hits the dev server via the Mac's
+  // local IP (e.g. 192.168.x.x), not localhost. Next surfaces a warning
+  // and blocks cross-origin /_next/* fetches (incl. HMR) unless we
+  // allow-list the origins explicitly. When HMR is blocked the page
+  // never fully hydrates and form click handlers fall back to native
+  // submits — the symptom that bit us with a hard-coded IP. Wildcards
+  // cover any LAN device without a per-network config edit.
+  ...(isProd ? {} : { allowedDevOrigins: ['192.168.*.*', '10.*.*.*', '172.16.*.*', '172.20.*.*'] }),
+  // Native/CJS-leaning server-only packages — list here so Next doesn't
+  // bundle them into the route trace (slower cold start + risk that
+  // native bindings fail at runtime). Build-auditor C3+M3: socket.io
+  // is only imported by the custom server entry point, so the Next
+  // tracer has no reason to include it; listing here makes the
+  // dependency visible to the build system.
   serverExternalPackages: [
     'pino',
     'pino-pretty',
@@ -11,19 +100,69 @@ const nextConfig: NextConfig = {
     'postgres',
     'better-auth',
     'nodemailer',
+    'socket.io',
+    '@socket.io/redis-adapter',
+    'imapflow',
+    'mailparser',
+    'pdf-lib',
+    'sharp',
+    'tesseract.js',
+    '@react-pdf/renderer',
+    'unpdf',
   ],
   images: {
     remotePatterns: [{ protocol: 'https', hostname: '*.portnimara.com' }],
   },
-  experimental: {
-    typedRoutes: true,
-  },
+  typedRoutes: true,
+  // ECharts ships ES modules that older Next/webpack versions can't parse
+  // without a transpile-pass. Listing here is the official recommendation
+  // from echarts-for-react when used inside Next.
+  transpilePackages: ['echarts', 'zrender', 'echarts-for-react'],
   outputFileTracingIncludes: {
     // Bundle the EOI source PDF so the in-app EOI pathway can read it at
     // runtime in the standalone build. Reading via fs.readFile from
     // process.cwd() requires the file to be traced explicitly.
     '/api/v1/document-templates/**': ['./assets/eoi-template.pdf'],
   },
+  async redirects() {
+    return [
+      {
+        source: '/:portSlug/documents/files',
+        destination: '/:portSlug/documents',
+        permanent: true,
+      },
+      {
+        source: '/:portSlug/documents/files/:path*',
+        destination: '/:portSlug/documents',
+        permanent: true,
+      },
+    ];
+  },
+  async headers() {
+    return [
+      {
+        source: '/:path*',
+        headers: securityHeaders,
+      },
+    ];
+  },
 };
 
-export default nextConfig;
+// Sentry wrapper is conditional: if NEXT_PUBLIC_SENTRY_DSN isn't set we
+// skip its build-time source-map upload + middleware injection so dev
+// builds stay fast and CI doesn't need credentials. When the DSN is
+// present, withSentryConfig adds instrumentation hooks that route
+// errors + traces to Sentry.
+const withSentry = process.env.NEXT_PUBLIC_SENTRY_DSN
+  ? (cfg: NextConfig) =>
+      withSentryConfig(cfg, {
+        silent: true,
+        widenClientFileUpload: true,
+        // We host on our own infra — disable Vercel-specific tunneling.
+        tunnelRoute: undefined,
+        // Strip Sentry debug logger from prod bundle.
+        disableLogger: true,
+      })
+  : (cfg: NextConfig) => cfg;
+
+export default withSentry(withBundleAnalyzer(nextConfig));

nginx/conf.d/proxy_params.conf

@@ -4,6 +4,10 @@ proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header Connection "";
+# Defense-in-depth for CVE-2025-29927: strip the header attackers use to
+# skip Next.js middleware. Patched in next>=15.2.3, but neutralizing the
+# input at the edge means a future regression cannot reopen the bypass.
+proxy_set_header X-Middleware-Subrequest "";
 proxy_cache_bypass $http_upgrade;
 proxy_read_timeout 60s;
 proxy_send_timeout 60s;

package.json

@@ -2,39 +2,49 @@
   "name": "port-nimara-crm",
   "version": "0.1.0",
   "private": true,
+  "packageManager": "pnpm@10.33.2",
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev --turbopack -H 0.0.0.0",
     "build": "next build && pnpm build:server",
     "build:server": "esbuild src/server.ts --bundle --platform=node --target=node20 --format=cjs --outdir=dist --packages=external --tsconfig=tsconfig.server.json",
     "build:worker": "esbuild src/worker.ts --bundle --platform=node --target=node20 --format=cjs --outdir=dist --packages=external --tsconfig=tsconfig.server.json",
     "start": "next start",
-    "lint": "next lint",
+    "lint": "eslint .",
     "format": "prettier --write \"src/**/*.{ts,tsx,json,css}\"",
     "db:generate": "drizzle-kit generate",
     "db:push": "drizzle-kit push",
+    "db:migrate": "tsx scripts/db-migrate.ts apply",
+    "db:migrate:status": "tsx scripts/db-migrate.ts status",
+    "db:migrate:baseline": "tsx scripts/db-migrate.ts baseline",
     "db:studio": "drizzle-kit studio",
     "db:seed": "tsx src/lib/db/seed.ts",
+    "db:seed:realistic": "tsx src/lib/db/seed.ts",
+    "db:seed:synthetic": "tsx src/lib/db/seed-synthetic.ts",
+    "db:seed:wide-synthetic": "tsx src/lib/db/seed-wide-synthetic.ts",
+    "db:reset": "tsx scripts/db-reset.ts --confirm",
+    "db:reseed:realistic": "pnpm db:reset && pnpm db:seed:realistic",
+    "db:reseed:synthetic": "pnpm db:reset && pnpm db:seed:synthetic",
+    "db:backfill:doc-folders": "tsx scripts/backfill-document-folders.ts",
     "test:e2e": "playwright test",
     "test:e2e:smoke": "playwright test --project=smoke",
     "test:e2e:exhaustive": "playwright test --project=exhaustive",
     "test:e2e:destructive": "playwright test --project=destructive",
-    "prepare": "husky"
+    "prepare": "husky || true"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@hookform/resolvers": "^3.9.0",
-    "@pdfme/common": "^5.5.8",
-    "@pdfme/generator": "^5.5.8",
-    "@pdfme/schemas": "^5.5.8",
+    "@formkit/auto-animate": "^0.9.0",
+    "@hookform/resolvers": "^5.2.2",
+    "@next/bundle-analyzer": "^16.2.6",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-alert-dialog": "^1.1.15",
     "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-icons": "^1.3.0",
+    "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-navigation-menu": "^1.2.14",
     "@radix-ui/react-popover": "^1.1.15",
@@ -48,75 +58,128 @@
     "@radix-ui/react-switch": "^1.2.6",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "@react-email/components": "^1.0.12",
+    "@react-pdf/renderer": "^4.5.1",
+    "@sentry/nextjs": "^10.53.1",
     "@socket.io/redis-adapter": "^8.3.0",
-    "@tanstack/react-query": "^5.62.0",
-    "@tanstack/react-query-devtools": "^5.62.0",
+    "@tanstack/query-broadcast-client-experimental": "^5.100.10",
+    "@tanstack/react-query": "^5.100.10",
+    "@tanstack/react-query-devtools": "^5.100.10",
     "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "^3.13.24",
+    "@types/pdfkit": "^0.17.6",
+    "@umami/node": "^0.4.0",
+    "@use-gesture/react": "^10.3.1",
     "archiver": "^7.0.1",
-    "better-auth": "^1.2.0",
-    "bullmq": "^5.25.0",
-    "class-variance-authority": "^0.7.0",
+    "better-auth": "^1.6.11",
+    "browser-image-compression": "^2.0.2",
+    "bullmq": "^5.76.8",
+    "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "country-flag-icons": "^1.6.17",
+    "cron-parser": "^5.5.0",
     "date-fns": "^4.1.0",
-    "drizzle-orm": "^0.38.0",
-    "imapflow": "^1.2.13",
-    "ioredis": "^5.4.0",
+    "docx-preview": "^0.3.7",
+    "drizzle-orm": "^0.45.2",
+    "echarts": "^6.0.0",
+    "echarts-for-react": "^3.0.6",
+    "embla-carousel-react": "^8.6.0",
+    "exceljs": "^4.4.0",
+    "imapflow": "^1.3.3",
+    "ioredis": "^5.10.1",
     "iso-3166-2": "^1.0.0",
-    "jose": "^6.2.1",
-    "libphonenumber-js": "^1.12.42",
-    "lucide-react": "^0.460.0",
-    "mailparser": "^3.9.4",
-    "minio": "^8.0.0",
-    "next": "15.1.0",
-    "next-themes": "^0.4.0",
-    "nodemailer": "^6.9.0",
-    "openai": "^6.27.0",
+    "isomorphic-dompurify": "^3.12.0",
+    "jose": "^6.2.3",
+    "libphonenumber-js": "^1.13.1",
+    "lucide-react": "^1.14.0",
+    "mailparser": "^3.9.8",
+    "minio": "^8.0.7",
+    "motion": "^12.38.0",
+    "next": "16.2.6",
+    "next-themes": "^0.4.6",
+    "nodemailer": "^8.0.7",
+    "openai": "^6.37.0",
+    "p-limit": "^7.3.0",
+    "p-queue": "^9.2.0",
+    "p-retry": "^8.0.0",
+    "papaparse": "^5.5.3",
     "pdf-lib": "^1.17.1",
-    "pino": "^9.5.0",
-    "pino-pretty": "^13.0.0",
-    "postgres": "^3.4.0",
-    "react": "^19.0.0",
-    "react-day-picker": "^9.14.0",
-    "react-dom": "^19.0.0",
-    "react-hook-form": "^7.54.0",
-    "recharts": "^3.8.0",
-    "socket.io": "^4.8.0",
-    "socket.io-client": "^4.8.0",
-    "sonner": "^1.7.0",
-    "tailwind-merge": "^2.6.0",
-    "tailwindcss-animate": "^1.0.7",
+    "pdfjs-dist": "^5.7.284",
+    "pdfkit": "^0.18.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "postgres": "^3.4.9",
+    "react": "^19.2.6",
+    "react-day-picker": "^10.0.0",
+    "react-dom": "^19.2.6",
+    "react-easy-crop": "^5.5.7",
+    "react-email": "^6.1.3",
+    "react-hook-form": "^7.75.0",
+    "react-image-crop": "^11.0.10",
+    "react-number-format": "^5.4.5",
+    "react-pdf": "^10.4.1",
+    "react-resizable-panels": "^3.0.6",
+    "react-virtuoso": "^4.18.7",
+    "recharts": "^3.8.1",
+    "sharp": "^0.34.5",
+    "socket.io": "^4.8.3",
+    "socket.io-client": "^4.8.3",
+    "sonner": "^2.0.7",
+    "svgo": "^4.0.1",
+    "tailwind-merge": "^3.6.0",
     "tesseract.js": "^7.0.0",
+    "ts-pattern": "^5.9.0",
+    "tw-animate-css": "^1.4.0",
+    "unpdf": "^1.6.2",
     "vaul": "^1.1.2",
-    "zod": "^3.24.0",
-    "zustand": "^5.0.0"
+    "web-vitals": "^5.2.0",
+    "yet-another-react-lightbox": "^3.32.0",
+    "zod": "^4.4.3",
+    "zustand": "^5.0.13"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3.3.5",
-    "@playwright/test": "^1.58.2",
+    "@axe-core/playwright": "^4.11.3",
+    "@faker-js/faker": "^10.4.0",
+    "@hookform/devtools": "^4.4.0",
+    "@playwright/test": "^1.60.0",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@total-typescript/ts-reset": "^0.6.1",
     "@types/archiver": "^7.0.0",
+    "@types/geojson": "^7946.0.16",
     "@types/iso-3166-2": "^1.0.4",
     "@types/mailparser": "^3.4.6",
-    "@types/node": "^22.0.0",
-    "@types/nodemailer": "^6.4.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "autoprefixer": "^10.4.27",
-    "dotenv": "^17.3.1",
-    "drizzle-kit": "^0.30.0",
-    "esbuild": "^0.25.0",
-    "eslint": "^9.0.0",
-    "eslint-config-next": "15.1.0",
-    "eslint-config-prettier": "^9.1.0",
-    "husky": "^9.1.0",
-    "lint-staged": "^15.2.0",
-    "postcss": "^8.4.0",
-    "prettier": "^3.4.0",
-    "react-grab": "^0.1.32",
-    "tailwindcss": "^3.4.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "vitest": "^4.1.0"
+    "@types/node": "^20.19.0",
+    "@types/nodemailer": "^8.0.0",
+    "@types/papaparse": "^5.5.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/topojson-client": "^3.1.5",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^4.1.6",
+    "dotenv": "^17.4.2",
+    "drizzle-kit": "^0.31.10",
+    "drizzle-zod": "^0.8.3",
+    "esbuild": "^0.28.0",
+    "eslint": "^9.39.4",
+    "eslint-config-next": "16.2.6",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.4",
+    "postcss": "^8.5.14",
+    "prettier": "^3.8.3",
+    "react-grab": "^0.1.34",
+    "tailwindcss": "^4.3.0",
+    "tsx": "^4.21.0",
+    "type-fest": "^5.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "8.0.5",
+      "esbuild": ">=0.25.0",
+      "postcss": ">=8.5.10"
+    }
   }
 }

postcss.config.mjs

@@ -1,8 +1,7 @@
 /** @type {import('postcss-load-config').Config} */
 const config = {
   plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
+    '@tailwindcss/postcss': {},
   },
 };
 

public/manifest.json

@@ -0,0 +1,30 @@
+{
+  "name": "Port Nimara CRM",
+  "short_name": "Port Nimara",
+  "description": "Marina/port management CRM",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#f2f2f2",
+  "theme_color": "#0f172a",
+  "orientation": "any",
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icon-512-maskable.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ]
+}

scripts/audit-permissions.ts

@@ -73,10 +73,6 @@ const ALLOW_LIST: ReadonlyArray<{ pattern: RegExp; reason: string }> = [
     pattern: /\/custom-fields\/\[entityId\]\//,
     reason: 'TODO: needs custom_fields:* permission. PUT path internally validated.',
   },
-  {
-    pattern: /\/berth-reservations\/\[id\]\/route\.ts$/,
-    reason: 'TODO: PATCH should map to reservations:edit (not currently in catalog).',
-  },
 ];
 
 interface Finding {

scripts/backfill-document-folders.ts

@@ -0,0 +1,246 @@
+/**
+ * Idempotent backfill: ensure every port has the three system roots
+ * (Clients / Companies / Yachts), every entity with attached files
+ * has a per-entity subfolder, every file with entity FKs has
+ * `folder_id` set, and every signed file from a completed workflow
+ * has the workflow's entity FKs propagated onto it.
+ *
+ * Safe to re-run: all writes target only rows where the relevant
+ * column is NULL. Per-port `pg_advisory_xact_lock` serializes
+ * concurrent runs.
+ *
+ * Usage:
+ *   pnpm tsx scripts/backfill-document-folders.ts
+ *   pnpm tsx scripts/backfill-document-folders.ts --port <portId>
+ */
+
+import 'dotenv/config';
+import { and, eq, isNotNull, isNull, sql } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { files, documents } from '@/lib/db/schema/documents';
+import {
+  ensureSystemRoots,
+  ensureEntityFolder,
+  type EntityType,
+} from '@/lib/services/document-folders.service';
+import { logger } from '@/lib/logger';
+
+export interface BackfillOptions {
+  /** When provided, only backfill this port. Otherwise all ports. */
+  portId?: string;
+  /** User ID recorded in `created_by` for any folders created. */
+  systemUserId?: string;
+}
+
+/**
+ * Per-port counters surfaced through the return value so the CLI can
+ * print them and operators (or follow-up scripts) can sanity-check that
+ * a re-run shrinks each number toward zero.
+ */
+export interface PortBackfillStats {
+  portId: string;
+  /** Total files inspected at Step 3 (with `folderId IS NULL`). */
+  filesProcessed: number;
+  /** Files updated with `folder_id` set in Step 3. */
+  filesWithFolderIdSet: number;
+  /** New folder rows created via `ensureEntityFolder` during Step 3. */
+  foldersCreated: number;
+  /** Completed-doc rows whose signed file got an entity FK propagated in Step 2. */
+  fksPropagated: number;
+}
+
+/**
+ * One-time idempotent backfill. See module-level JSDoc for full
+ * description of what each step does.
+ */
+export async function runBackfill(opts: BackfillOptions = {}): Promise<PortBackfillStats[]> {
+  const portRows = opts.portId
+    ? [{ id: opts.portId }]
+    : await db.select({ id: ports.id }).from(ports);
+
+  const systemUser = opts.systemUserId ?? 'system-backfill';
+  const allStats: PortBackfillStats[] = [];
+
+  for (const { id: portId } of portRows) {
+    const stats: PortBackfillStats = {
+      portId,
+      filesProcessed: 0,
+      filesWithFolderIdSet: 0,
+      foldersCreated: 0,
+      fksPropagated: 0,
+    };
+    await db.transaction(async (tx) => {
+      // Serialize concurrent runs on a per-port lock so two simultaneous
+      // backfills can't race on folder inserts.
+      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${portId})::bigint)`);
+
+      // ── Step 1: Ensure system roots exist for this port ──────────────────
+      await ensureSystemRoots(portId, systemUser);
+
+      // ── Step 2: Propagate entity FKs from completed workflows onto their
+      //            signed file rows (pre-auto-deposit legacy completions). ──
+      const completedDocs = await tx
+        .select({
+          id: documents.id,
+          signedFileId: documents.signedFileId,
+          clientId: documents.clientId,
+          companyId: documents.companyId,
+          yachtId: documents.yachtId,
+        })
+        .from(documents)
+        .where(
+          and(
+            eq(documents.portId, portId),
+            eq(documents.status, 'completed'),
+            isNotNull(documents.signedFileId),
+          ),
+        );
+
+      for (const d of completedDocs) {
+        if (!d.signedFileId) continue;
+
+        const owner: { type: EntityType; id: string } | null = d.clientId
+          ? { type: 'client', id: d.clientId }
+          : d.companyId
+            ? { type: 'company', id: d.companyId }
+            : d.yachtId
+              ? { type: 'yacht', id: d.yachtId }
+              : null;
+
+        if (!owner) continue;
+
+        // Build the update object with ONLY the matching FK column so we
+        // never pass column references to .set() (Drizzle syntax bug fix).
+        const update =
+          owner.type === 'client'
+            ? { clientId: owner.id }
+            : owner.type === 'company'
+              ? { companyId: owner.id }
+              : { yachtId: owner.id };
+
+        const matchingFkColumn =
+          owner.type === 'client'
+            ? files.clientId
+            : owner.type === 'company'
+              ? files.companyId
+              : files.yachtId;
+
+        const propagated = await tx
+          .update(files)
+          .set(update)
+          .where(
+            and(eq(files.id, d.signedFileId), eq(files.portId, portId), isNull(matchingFkColumn)),
+          )
+          .returning({ id: files.id });
+        stats.fksPropagated += propagated.length;
+      }
+
+      // ── Step 3: For every file with entity FKs but no folder_id,
+      //            create the entity subfolder and set folder_id. ──────────
+      const fileRows = await tx
+        .select()
+        .from(files)
+        .where(and(eq(files.portId, portId), isNull(files.folderId)));
+      stats.filesProcessed = fileRows.length;
+
+      const folderIdsCreatedThisRun = new Set<string>();
+      const folderIdsSeenThisRun = new Set<string>();
+      for (const f of fileRows) {
+        const owner: { type: EntityType; id: string } | null = f.clientId
+          ? { type: 'client', id: f.clientId }
+          : f.companyId
+            ? { type: 'company', id: f.companyId }
+            : f.yachtId
+              ? { type: 'yacht', id: f.yachtId }
+              : null;
+
+        if (!owner) continue;
+
+        try {
+          const beforeExisted = folderIdsSeenThisRun.has(`${owner.type}:${owner.id}`);
+          const folder = await ensureEntityFolder(portId, owner.type, owner.id, systemUser);
+          folderIdsSeenThisRun.add(`${owner.type}:${owner.id}`);
+          if (!beforeExisted && !folderIdsCreatedThisRun.has(folder.id)) {
+            // Heuristic: first time we encountered this entity in this
+            // backfill run + the folder is freshly returned ⇒ assume the
+            // folder was created (or existed already but we're double-
+            // counting at most once per entity, which is fine).
+            folderIdsCreatedThisRun.add(folder.id);
+          }
+          await tx
+            .update(files)
+            .set({ folderId: folder.id })
+            .where(and(eq(files.id, f.id), eq(files.portId, portId)));
+          stats.filesWithFolderIdSet += 1;
+        } catch (err) {
+          // Best-effort: log and skip rather than abort the whole port.
+          logger.warn({ err, fileId: f.id, portId }, 'backfill: ensureEntityFolder failed');
+        }
+      }
+      stats.foldersCreated = folderIdsCreatedThisRun.size;
+    });
+
+    logger.info(
+      {
+        portId,
+        filesProcessed: stats.filesProcessed,
+        filesWithFolderIdSet: stats.filesWithFolderIdSet,
+        foldersCreated: stats.foldersCreated,
+        fksPropagated: stats.fksPropagated,
+      },
+      'backfill: port complete',
+    );
+    allStats.push(stats);
+  }
+  return allStats;
+}
+
+// ── CLI entry point ────────────────────────────────────────────────────────────
+// tsx compiles TypeScript to CJS at runtime, so `require.main === module`
+// is the standard guard. The test suite imports `runBackfill` as a named
+// export; the CLI invocation hits this block and runs main().
+
+if (require.main === module) {
+  const portIdArg = process.argv.indexOf('--port');
+  let portId: string | undefined;
+  if (portIdArg !== -1) {
+    const next = process.argv[portIdArg + 1];
+    if (!next || next.startsWith('--')) {
+      logger.error('--port requires a value');
+      process.exit(1);
+    }
+    portId = next;
+  }
+  runBackfill({ portId })
+    .then((stats) => {
+      console.log('\nBackfill complete.');
+      console.log('Per-port summary:');
+      let totalFiles = 0;
+      let totalFilesSet = 0;
+      let totalFolders = 0;
+      let totalFks = 0;
+      for (const s of stats) {
+        totalFiles += s.filesProcessed;
+        totalFilesSet += s.filesWithFolderIdSet;
+        totalFolders += s.foldersCreated;
+        totalFks += s.fksPropagated;
+        console.log(
+          `  port=${s.portId}: filesProcessed=${s.filesProcessed} ` +
+            `filesWithFolderIdSet=${s.filesWithFolderIdSet} ` +
+            `foldersCreated=${s.foldersCreated} fksPropagated=${s.fksPropagated}`,
+        );
+      }
+      console.log(
+        `Totals: ports=${stats.length} filesProcessed=${totalFiles} ` +
+          `filesWithFolderIdSet=${totalFilesSet} foldersCreated=${totalFolders} ` +
+          `fksPropagated=${totalFks}`,
+      );
+      process.exit(0);
+    })
+    .catch((err) => {
+      logger.error({ err }, 'Backfill failed');
+      process.exit(1);
+    });
+}

scripts/backfill-eoi-signers.ts

@@ -0,0 +1,158 @@
+/**
+ * Backfill `document_signers` rows for EOI documents that were generated
+ * before the per-recipient signer-row insert landed (pre-2026-05-15).
+ *
+ * Symptom on the affected docs: the EOI tab's "Signing progress" panel
+ * reads "No signers loaded" forever because the webhook handler updates
+ * existing rows (by token / email) and never inserts new ones.
+ *
+ * This script walks every documents row that has a documensoId, status
+ * in ('sent', 'partially_signed', 'completed'), and zero signer rows.
+ * For each, it pulls the envelope from Documenso and recreates the
+ * signer rows from the recipients array. Idempotent — safe to re-run.
+ *
+ * Usage:
+ *   pnpm tsx scripts/backfill-eoi-signers.ts            # dry-run, lists candidates
+ *   pnpm tsx scripts/backfill-eoi-signers.ts --apply    # actually inserts
+ */
+
+import 'dotenv/config';
+import { and, inArray, isNotNull, sql } from 'drizzle-orm';
+
+import { db, closeDb } from '@/lib/db';
+import { documents, documentSigners } from '@/lib/db/schema/documents';
+import { getDocument as getDocumensoDoc } from '@/lib/services/documenso-client';
+import { logger } from '@/lib/logger';
+
+interface BackfillStats {
+  scanned: number;
+  withZeroSigners: number;
+  inserted: number;
+  failed: number;
+  skipped: number;
+}
+
+async function main() {
+  const apply = process.argv.includes('--apply');
+
+  // 1. Find candidate documents: in-flight or completed EOIs with a
+  //    documensoId and no signer rows.
+  const candidates = await db
+    .select({
+      id: documents.id,
+      portId: documents.portId,
+      documensoId: documents.documensoId,
+      status: documents.status,
+      documentType: documents.documentType,
+      title: documents.title,
+      signerCount: sql<number>`(
+        SELECT COUNT(*)::int FROM ${documentSigners}
+        WHERE ${documentSigners.documentId} = ${documents.id}
+      )`,
+    })
+    .from(documents)
+    .where(
+      and(
+        inArray(documents.status, ['sent', 'partially_signed', 'completed']),
+        isNotNull(documents.documensoId),
+      ),
+    );
+
+  const stats: BackfillStats = {
+    scanned: candidates.length,
+    withZeroSigners: 0,
+    inserted: 0,
+    failed: 0,
+    skipped: 0,
+  };
+
+  const needsBackfill = candidates.filter((c) => c.signerCount === 0);
+  stats.withZeroSigners = needsBackfill.length;
+
+  console.log(
+    `Scanned ${stats.scanned} document${stats.scanned === 1 ? '' : 's'}; ${stats.withZeroSigners} need backfill.`,
+  );
+  if (!apply) {
+    console.log('\nDRY RUN (pass --apply to insert):');
+    for (const doc of needsBackfill) {
+      console.log(`  - ${doc.id} (${doc.title}) — port=${doc.portId}, status=${doc.status}`);
+    }
+    await closeDb();
+    return;
+  }
+
+  // 2. For each candidate, fetch the envelope from Documenso and insert
+  //    the signer rows. Failures are logged + counted; processing
+  //    continues so one broken doc doesn't halt the run.
+  for (const doc of needsBackfill) {
+    if (!doc.documensoId) {
+      stats.skipped++;
+      continue;
+    }
+    try {
+      const envelope = await getDocumensoDoc(doc.documensoId, doc.portId);
+      if (envelope.recipients.length === 0) {
+        logger.warn({ documentId: doc.id }, 'Backfill: envelope has no recipients — skipping');
+        stats.skipped++;
+        continue;
+      }
+
+      // Use the same role-mapping logic as the create-time flow:
+      //   - signingOrder=1 + role SIGNER  →  'client' (positional)
+      //   - SIGNER otherwise              →  'signer'
+      //   - APPROVER                      →  'approver'
+      //   - CC / VIEWER                   →  pass-through
+      const rows = envelope.recipients.map((r) => {
+        const cleanName = (r.name || r.email)
+          .replace(/\s*\(was:[^)]*\)/i, '')
+          .replace(/\s*\(placeholder\)/i, '')
+          .trim();
+        const upRole = r.role.toUpperCase();
+        const role =
+          upRole === 'SIGNER' && r.signingOrder === 1
+            ? 'client'
+            : upRole === 'APPROVER'
+              ? 'approver'
+              : upRole === 'CC'
+                ? 'cc'
+                : upRole === 'VIEWER'
+                  ? 'viewer'
+                  : 'signer';
+        return {
+          documentId: doc.id,
+          signerName: cleanName || r.email,
+          signerEmail: r.email,
+          signerRole: role,
+          signingOrder: r.signingOrder,
+          status: (r.status === 'SIGNED' ? 'signed' : 'pending') as 'signed' | 'pending',
+          signingUrl: r.signingUrl ?? null,
+          embeddedUrl: r.embeddedUrl ?? null,
+          signingToken: r.token ?? null,
+          // No invitedAt — the backfill can't reconstruct the original
+          // dispatch timestamp. Reps see the card as "Not yet invited"
+          // for any pending signer; clicking Send invitation re-stamps.
+          invitedAt: null,
+        };
+      });
+
+      await db.insert(documentSigners).values(rows);
+      stats.inserted += rows.length;
+      console.log(`  ✓ ${doc.id} (${doc.title}) — inserted ${rows.length} signer row(s)`);
+    } catch (err) {
+      stats.failed++;
+      logger.error(
+        { err: err instanceof Error ? err.message : err, documentId: doc.id },
+        'Backfill failed for document',
+      );
+      console.log(`  ✗ ${doc.id} — ${err instanceof Error ? err.message : 'unknown error'}`);
+    }
+  }
+
+  console.log(`\nDone. inserted=${stats.inserted} failed=${stats.failed} skipped=${stats.skipped}`);
+  await closeDb();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

scripts/backfill-legacy-lead-source.ts

@@ -0,0 +1,135 @@
+/**
+ * One-shot: backfill `interests.source` for legacy NocoDB-imported rows.
+ *
+ * Why this exists: the legacy NocoDB Interests table left the `Source`
+ * column null for ~95 % of rows. The migration mapped null → null, so the
+ * Lead Source Attribution chart shows them as "Unspecified". Per the
+ * operator's best knowledge, almost all of those legacy rows came in
+ * through the website (web form / portal) — the few that didn't are the
+ * ones that already carry an explicit `Source` value (Form / portal /
+ * External). Defaulting null → 'website' is therefore the closest
+ * truth we can reconstruct without per-row sales notes review.
+ *
+ * Idempotent: only updates rows where `source IS NULL` AND the row has a
+ * `migration_source_links` entry tying it back to the legacy NocoDB import,
+ * so net-new manually-created interests with null source aren't touched.
+ *
+ * Usage:
+ *   pnpm tsx scripts/backfill-legacy-lead-source.ts --port-slug port-nimara [--dry-run]
+ */
+import 'dotenv/config';
+import { eq, and, isNull, inArray } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { interests } from '@/lib/db/schema/interests';
+import { migrationSourceLinks } from '@/lib/db/schema/migration';
+
+interface CliArgs {
+  portSlug: string | null;
+  dryRun: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = { portSlug: null, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--port-slug') args.portSlug = argv[++i] ?? null;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '-h' || a === '--help') {
+      console.log(
+        'Usage: pnpm tsx scripts/backfill-legacy-lead-source.ts --port-slug <slug> [--dry-run]',
+      );
+      process.exit(0);
+    }
+  }
+  if (!args.portSlug) {
+    console.error('Missing required --port-slug');
+    process.exit(1);
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const [port] = await db
+    .select({ id: ports.id, name: ports.name })
+    .from(ports)
+    .where(eq(ports.slug, args.portSlug!))
+    .limit(1);
+  if (!port) {
+    console.error(`No port found with slug "${args.portSlug}"`);
+    process.exit(1);
+  }
+  console.log(`[backfill] target: ${port.name} (${port.id})`);
+
+  // Pull every interest id this port owns that has a NULL source.
+  const candidateInterests = await db
+    .select({ id: interests.id })
+    .from(interests)
+    .where(and(eq(interests.portId, port.id), isNull(interests.source)));
+
+  console.log(`[backfill] interests with NULL source in this port: ${candidateInterests.length}`);
+
+  if (candidateInterests.length === 0) {
+    console.log('Nothing to backfill.');
+    return;
+  }
+
+  // Filter to ONLY those that came in via the legacy migration — preserves
+  // null on net-new rows where the operator hasn't picked a source yet.
+  const candidateIds = candidateInterests.map((r) => r.id);
+  const legacyLinks = await db
+    .select({ targetEntityId: migrationSourceLinks.targetEntityId })
+    .from(migrationSourceLinks)
+    .where(
+      and(
+        eq(migrationSourceLinks.sourceSystem, 'nocodb_interests'),
+        eq(migrationSourceLinks.targetEntityType, 'interest'),
+        inArray(migrationSourceLinks.targetEntityId, candidateIds),
+      ),
+    );
+
+  const legacyIds = new Set(legacyLinks.map((l) => l.targetEntityId));
+  const toUpdate = candidateIds.filter((id) => legacyIds.has(id));
+
+  console.log(
+    `[backfill] of those, ${toUpdate.length} are legacy migration rows (will set source='website')`,
+  );
+  console.log(
+    `[backfill] ${candidateInterests.length - toUpdate.length} are net-new rows (left untouched)`,
+  );
+
+  if (args.dryRun) {
+    console.log('[backfill] --dry-run set; no writes.');
+    return;
+  }
+
+  if (toUpdate.length === 0) {
+    console.log('Nothing to write.');
+    return;
+  }
+
+  // Update in chunks of 500 to keep query size sane.
+  const CHUNK = 500;
+  let updated = 0;
+  for (let i = 0; i < toUpdate.length; i += CHUNK) {
+    const chunk = toUpdate.slice(i, i + CHUNK);
+    // Belt-and-suspenders: re-assert `source IS NULL` in the WHERE so
+    // a concurrent process that set source on one of these rows
+    // between SELECT and UPDATE doesn't get its value clobbered.
+    const result = await db
+      .update(interests)
+      .set({ source: 'website' })
+      .where(and(inArray(interests.id, chunk), isNull(interests.source)))
+      .returning({ id: interests.id });
+    updated += result.length;
+  }
+  console.log(`[backfill] updated ${updated} rows.`);
+}
+
+main().catch((err) => {
+  console.error('FATAL', err);
+  process.exit(1);
+});

scripts/backfill-nested-document-folders.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env tsx
+/**
+ * Phase 2 nested-subfolders backfill.
+ *
+ * Re-files every existing `files` row that has `entity_type='interest'`
+ * (or a non-null `interest_id`) under a nested
+ * `Clients/<Name>/<Interest folder>/` subfolder. Idempotent — already-
+ * filed rows are skipped.
+ *
+ * Run dry-first to confirm the row count:
+ *   pnpm tsx scripts/backfill-nested-document-folders.ts
+ *
+ * Apply for real:
+ *   pnpm tsx scripts/backfill-nested-document-folders.ts --apply
+ *
+ * Per-port advisory lock so two operators can't race a backfill on the
+ * same port. Lock id is the FNV-1a hash of `port_id` so concurrent
+ * backfills against different ports don't block each other.
+ */
+
+import { sql } from 'drizzle-orm';
+
+import { db } from '../src/lib/db';
+import { ensureEntityFolder } from '../src/lib/services/document-folders.service';
+
+const APPLY = process.argv.includes('--apply');
+
+function fnv1a(input: string): number {
+  // Simple deterministic 32-bit hash — used as the advisory-lock id so
+  // the lock is stable across runs. PostgreSQL accepts a bigint here.
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+async function main() {
+  console.log(`[backfill-nested-folders] dry-run=${!APPLY}`);
+
+  // 1. Gather every (port_id, interest_id) pair whose files need to be
+  //    nested. We only need to ensure the folder exists — the
+  //    `files.interest_id` column is populated separately by Phase 1.
+  const rows = await db.execute<{ port_id: string; interest_id: string; row_count: number }>(
+    sql`
+      SELECT f.port_id, f.interest_id, COUNT(*)::int AS row_count
+      FROM files f
+      WHERE f.interest_id IS NOT NULL
+        AND f.archived_at IS NULL
+      GROUP BY f.port_id, f.interest_id
+      ORDER BY f.port_id, f.interest_id
+    `,
+  );
+
+  // postgres-js returns the raw result iterable; the `.rows` property is
+  // pgnative-only — iterate the result directly.
+  const list = Array.isArray(rows) ? rows : ((rows as { rows?: typeof rows }).rows ?? rows);
+  console.log(`[backfill-nested-folders] ${list.length} (port, interest) pairs to process`);
+  for (const row of list as Array<{ port_id: string; interest_id: string; row_count: number }>) {
+    const lockId = fnv1a(row.port_id);
+    if (APPLY) {
+      await db.execute(sql`SELECT pg_advisory_xact_lock(${lockId}::bigint)`);
+      // ensureEntityFolder is idempotent — running it for a pair that
+      // already has its folder is a cheap select.
+      await ensureEntityFolder(row.port_id, 'interest', row.interest_id, 'system');
+    }
+    console.log(
+      `  ${APPLY ? '✓' : '·'} port=${row.port_id.slice(0, 8)} interest=${row.interest_id.slice(
+        0,
+        8,
+      )} files=${row.row_count}`,
+    );
+  }
+
+  console.log(`[backfill-nested-folders] done.`);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('[backfill-nested-folders] failed', err);
+  process.exit(1);
+});

scripts/backfill-phone-e164.ts

@@ -0,0 +1,144 @@
+/**
+ * Backfill `client_contacts.value_e164` from `value` for phone / whatsapp
+ * contacts where it's null or empty.
+ *
+ * The legacy seed (and pre-normalization production data) stored phone
+ * numbers in `value` as free text — "+33 4 93 00 0002" — but `value_e164`
+ * is what every UI surface and dedup matcher reads. This script runs the
+ * raw `value` through libphonenumber-js (via the script-safe wrapper to
+ * avoid the Node 25 metadata-loader bug) and writes the canonical E.164
+ * form back.
+ *
+ * Usage:
+ *   pnpm tsx scripts/backfill-phone-e164.ts            # dry-run report
+ *   pnpm tsx scripts/backfill-phone-e164.ts --apply    # actually write
+ *
+ * The dry-run report prints, for each unparseable row, the contact id +
+ * raw value so you can hand-clean before re-running.
+ */
+import 'dotenv/config';
+import { and, eq, inArray, isNull, or, sql } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { clientContacts } from '@/lib/db/schema/clients';
+import { parsePhoneScriptSafe } from '@/lib/dedup/phone-parse';
+import type { CountryCode } from '@/lib/i18n/countries';
+
+const APPLY = process.argv.includes('--apply');
+
+interface PhoneRow {
+  id: string;
+  channel: string;
+  value: string | null;
+  valueCountry: string | null;
+}
+
+async function main() {
+  console.log(`Phone E.164 backfill — ${APPLY ? 'APPLY MODE' : 'dry-run'}`);
+  console.log('');
+
+  // Find candidate rows: phone or whatsapp contacts with a `value` set but
+  // `value_e164` null/empty.
+  const rows: PhoneRow[] = await db
+    .select({
+      id: clientContacts.id,
+      channel: clientContacts.channel,
+      value: clientContacts.value,
+      valueCountry: clientContacts.valueCountry,
+    })
+    .from(clientContacts)
+    .where(
+      and(
+        inArray(clientContacts.channel, ['phone', 'whatsapp']),
+        or(isNull(clientContacts.valueE164), eq(clientContacts.valueE164, '')),
+        sql`${clientContacts.value} IS NOT NULL AND ${clientContacts.value} <> ''`,
+      ),
+    );
+
+  console.log(`  found ${rows.length} candidate rows`);
+
+  let parsedFull = 0;
+  let parsedE164Only = 0;
+  let unparseable = 0;
+  const updates: Array<{
+    id: string;
+    valueE164: string;
+    valueCountry: CountryCode | null;
+  }> = [];
+  const fails: Array<{ id: string; value: string; reason: string }> = [];
+
+  for (const row of rows) {
+    if (!row.value) continue;
+    const defaultCountry = (row.valueCountry as CountryCode | null) ?? undefined;
+    const parsed1 = parsePhoneScriptSafe(row.value, defaultCountry);
+
+    if (parsed1.e164 && parsed1.country) {
+      // Both e164 + country resolved — best case.
+      updates.push({ id: row.id, valueE164: parsed1.e164, valueCountry: parsed1.country });
+      parsedFull++;
+    } else if (parsed1.e164) {
+      // E.164 came back but country didn't (e.g. UK +44 7700 900xxx
+      // fictional/reserved range — libphonenumber returns the e164 form
+      // but refuses to assign a country). Still safe to write — the e164
+      // is canonical. Country stays null.
+      updates.push({
+        id: row.id,
+        valueE164: parsed1.e164,
+        valueCountry: (row.valueCountry as CountryCode | null) ?? null,
+      });
+      parsedE164Only++;
+    } else {
+      fails.push({
+        id: row.id,
+        value: row.value,
+        reason: row.value.trim().startsWith('+')
+          ? 'has + prefix but parse failed'
+          : 'no leading + and no country hint',
+      });
+      unparseable++;
+    }
+  }
+
+  console.log('');
+  console.log('  ✓ parsed cleanly (e164 + country)', parsedFull);
+  console.log('  ✓ parsed e164 only (no country) ', parsedE164Only);
+  console.log('  ✗ unparseable                   ', unparseable);
+  console.log('');
+
+  if (fails.length > 0) {
+    console.log('Failures (first 10):');
+    for (const f of fails.slice(0, 10)) {
+      console.log(`  [${f.id}] "${f.value}" — ${f.reason}`);
+    }
+    console.log('');
+  }
+
+  if (!APPLY) {
+    console.log('Dry-run only. Re-run with --apply to write the updates.');
+    return;
+  }
+
+  if (updates.length === 0) {
+    console.log('No updates to write.');
+    return;
+  }
+
+  console.log(`Writing ${updates.length} updates...`);
+
+  for (const u of updates) {
+    await db
+      .update(clientContacts)
+      .set({
+        valueE164: u.valueE164,
+        valueCountry: u.valueCountry,
+      })
+      .where(eq(clientContacts.id, u.id));
+  }
+
+  console.log(`  ✓ wrote ${updates.length} rows`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

scripts/db-migrate.ts

@@ -0,0 +1,275 @@
+/**
+ * Production migration runner.
+ *
+ * Why this exists (and why `drizzle-kit migrate` isn't enough):
+ *
+ *   - Drizzle's bundled `migrate()` wraps every migration in a single
+ *     transaction. Postgres forbids `CREATE INDEX CONCURRENTLY` inside
+ *     a transaction (raises 25001) — so any migration containing
+ *     CONCURRENTLY silently aborts or, worse, leaves the migration
+ *     marked applied with the index missing. `0052_audit_critical_fixes.sql`
+ *     ships six CONCURRENTLY composite indexes today and they never
+ *     landed in prod.
+ *
+ *   - `drizzle-kit push` skips DDL the kit can't infer from the schema —
+ *     e.g. CHECK constraints, partial unique indexes, the berth-pdf
+ *     circular FK. push-only deployments diverge from migration-tracked
+ *     truth.
+ *
+ * This script:
+ *   1. Reads migrations in journal order from `src/lib/db/migrations`.
+ *   2. Tracks applied state in `drizzle.__drizzle_migrations` (matching
+ *      Drizzle's schema so other tooling sees the same source of truth).
+ *   3. For each pending migration: splits on `--> statement-breakpoint`,
+ *      classifies each statement as concurrency-safe (CREATE INDEX
+ *      CONCURRENTLY / REINDEX CONCURRENTLY → outside tx) or
+ *      transactional (everything else → batched in one tx per migration).
+ *   4. Records hash + when-applied so re-runs are no-ops.
+ *
+ * Modes:
+ *   `pnpm db:migrate`           — apply pending migrations
+ *   `pnpm db:migrate:status`    — show pending vs applied without applying
+ *   `pnpm db:migrate:baseline`  — mark every migration as applied without
+ *                                 running it. Use ONCE per environment when
+ *                                 the schema was bootstrapped via `db:push`
+ *                                 (dev + the original prod cutover). After
+ *                                 baseline, all future migrations go through
+ *                                 `db:migrate` and are tracked in
+ *                                 `__drizzle_migrations`.
+ */
+
+import 'dotenv/config';
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import postgres from 'postgres';
+
+const STATEMENT_BREAKPOINT = '--> statement-breakpoint';
+const MIGRATIONS_DIR = join(process.cwd(), 'src/lib/db/migrations');
+const SCHEMA_NAME = 'drizzle';
+const TABLE_NAME = '__drizzle_migrations';
+
+interface JournalEntry {
+  idx: number;
+  version: string;
+  when: number;
+  tag: string;
+  breakpoints: boolean;
+}
+
+interface Journal {
+  version: string;
+  dialect: string;
+  entries: JournalEntry[];
+}
+
+interface MigrationFile {
+  tag: string;
+  /** Folder millis from journal `when` — Drizzle uses this as the
+   *  primary key in `__drizzle_migrations`. */
+  folderMillis: number;
+  /** Full file contents. */
+  sql: string;
+  /** SHA-256 hex of the raw file for re-application detection. */
+  hash: string;
+}
+
+interface Statement {
+  /** Raw SQL text (trimmed). */
+  sql: string;
+  /** True when the statement must execute outside a transaction. */
+  needsAutocommit: boolean;
+}
+
+function isConcurrencyDDL(sql: string): boolean {
+  const head = sql
+    .replace(/^\s*--.*$/gm, '')
+    .trim()
+    .toUpperCase();
+  return (
+    /\bCREATE\s+INDEX\s+CONCURRENTLY\b/.test(head) ||
+    /\bREINDEX\s+\w*\s*CONCURRENTLY\b/.test(head) ||
+    /\bDROP\s+INDEX\s+CONCURRENTLY\b/.test(head)
+  );
+}
+
+function readMigrations(): MigrationFile[] {
+  const journal = JSON.parse(
+    readFileSync(join(MIGRATIONS_DIR, 'meta', '_journal.json'), 'utf8'),
+  ) as Journal;
+
+  const files = readdirSync(MIGRATIONS_DIR).filter((f) => f.endsWith('.sql'));
+  const byTag = new Map(files.map((f) => [f.replace(/\.sql$/, ''), f]));
+
+  return journal.entries.map((entry) => {
+    const filename = byTag.get(entry.tag);
+    if (!filename) {
+      throw new Error(`Migration ${entry.tag} in journal but ${entry.tag}.sql not on disk`);
+    }
+    const sql = readFileSync(join(MIGRATIONS_DIR, filename), 'utf8');
+    const hash = createHash('sha256').update(sql).digest('hex');
+    return { tag: entry.tag, folderMillis: entry.when, sql, hash };
+  });
+}
+
+function splitStatements(sql: string): Statement[] {
+  // Drizzle inserts `--> statement-breakpoint` between every statement
+  // when `breakpoints: true` in drizzle.config. We split on those AND
+  // strip trailing semicolons. Anything before the first breakpoint
+  // counts too.
+  const parts = sql.split(STATEMENT_BREAKPOINT);
+  const out: Statement[] = [];
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed || trimmed.startsWith('--')) {
+      // Comment-only chunks (pre-breakpoint header etc.) — skip if
+      // they have no executable SQL.
+      const nonComment = trimmed
+        .split('\n')
+        .filter((line) => !line.trim().startsWith('--') && line.trim().length > 0);
+      if (nonComment.length === 0) continue;
+    }
+    out.push({ sql: trimmed, needsAutocommit: isConcurrencyDDL(trimmed) });
+  }
+  return out;
+}
+
+async function ensureMigrationsTable(sql: postgres.Sql): Promise<void> {
+  await sql.unsafe(`CREATE SCHEMA IF NOT EXISTS "${SCHEMA_NAME}"`);
+  await sql.unsafe(`
+    CREATE TABLE IF NOT EXISTS "${SCHEMA_NAME}"."${TABLE_NAME}" (
+      id SERIAL PRIMARY KEY,
+      hash text NOT NULL,
+      created_at bigint
+    )
+  `);
+}
+
+async function getAppliedHashes(sql: postgres.Sql): Promise<Set<string>> {
+  const rows = await sql.unsafe<{ hash: string }[]>(
+    `SELECT hash FROM "${SCHEMA_NAME}"."${TABLE_NAME}"`,
+  );
+  return new Set(rows.map((r) => r.hash));
+}
+
+async function applyMigration(sql: postgres.Sql, migration: MigrationFile): Promise<void> {
+  const statements = splitStatements(migration.sql);
+  if (statements.length === 0) {
+    console.log(`  [${migration.tag}] no executable statements, skipping`);
+    return;
+  }
+
+  const autocommit = statements.filter((s) => s.needsAutocommit);
+  const transactional = statements.filter((s) => !s.needsAutocommit);
+
+  // Transactional batch first — schema changes that CONCURRENTLY ops
+  // depend on (e.g. column adds before CREATE INDEX) need to exist
+  // before the index build runs. Drizzle migrations are written in
+  // this order; we preserve it within each phase.
+  if (transactional.length > 0) {
+    await sql.begin(async (tx) => {
+      for (const stmt of transactional) {
+        await tx.unsafe(stmt.sql);
+      }
+    });
+  }
+
+  // CONCURRENTLY ops run one at a time, each as its own implicit tx.
+  // No `BEGIN`/`COMMIT` wrapping — postgres-js's `sql.unsafe` runs
+  // each call as an independent transaction.
+  for (const stmt of autocommit) {
+    await sql.unsafe(stmt.sql);
+  }
+
+  // Record the migration as applied. created_at mirrors Drizzle's own
+  // schema so `drizzle-kit migrate` (if ever invoked) sees the same
+  // state we wrote.
+  await sql.unsafe(
+    `INSERT INTO "${SCHEMA_NAME}"."${TABLE_NAME}" (hash, created_at) VALUES ($1, $2)`,
+    [migration.hash, migration.folderMillis],
+  );
+}
+
+async function main(): Promise<void> {
+  const url = process.env.DATABASE_URL;
+  if (!url) {
+    console.error('DATABASE_URL must be set');
+    process.exit(1);
+  }
+
+  const mode = process.argv[2] ?? 'apply';
+  if (!['apply', 'status', 'baseline'].includes(mode)) {
+    console.error(`Unknown mode: ${mode}. Use 'apply' (default), 'status', or 'baseline'.`);
+    process.exit(1);
+  }
+
+  const sql = postgres(url, { max: 1, prepare: false });
+
+  try {
+    await ensureMigrationsTable(sql);
+    const applied = await getAppliedHashes(sql);
+    const migrations = readMigrations();
+    const pending = migrations.filter((m) => !applied.has(m.hash));
+
+    if (mode === 'status') {
+      console.log(`Applied: ${applied.size}`);
+      console.log(`Pending: ${pending.length}`);
+      if (pending.length > 0) {
+        console.log('');
+        console.log('Pending migrations:');
+        for (const m of pending) {
+          const statements = splitStatements(m.sql);
+          const conc = statements.filter((s) => s.needsAutocommit).length;
+          const tx = statements.length - conc;
+          console.log(`  ${m.tag} — ${tx} transactional + ${conc} concurrency-safe`);
+        }
+      }
+      return;
+    }
+
+    if (mode === 'baseline') {
+      if (pending.length === 0) {
+        console.log('All migrations already tracked. Nothing to baseline.');
+        return;
+      }
+      console.log(
+        `Baselining ${pending.length} migration${
+          pending.length === 1 ? '' : 's'
+        } as applied without running them.`,
+      );
+      console.log(
+        'This is correct ONLY when the schema is already in place (e.g. created via db:push).',
+      );
+      for (const m of pending) {
+        await sql.unsafe(
+          `INSERT INTO "${SCHEMA_NAME}"."${TABLE_NAME}" (hash, created_at) VALUES ($1, $2)`,
+          [m.hash, m.folderMillis],
+        );
+        console.log(`  → ${m.tag} marked as applied`);
+      }
+      console.log(`Done. ${pending.length} baselined.`);
+      return;
+    }
+
+    if (pending.length === 0) {
+      console.log('No pending migrations.');
+      return;
+    }
+
+    console.log(`Applying ${pending.length} migration${pending.length === 1 ? '' : 's'}...`);
+    for (const m of pending) {
+      const statements = splitStatements(m.sql);
+      const conc = statements.filter((s) => s.needsAutocommit).length;
+      console.log(`  → ${m.tag} (${statements.length} statements, ${conc} CONCURRENTLY)`);
+      await applyMigration(sql, m);
+    }
+    console.log(`Done. ${pending.length} applied.`);
+  } finally {
+    await sql.end({ timeout: 5 });
+  }
+}
+
+main().catch((err) => {
+  console.error('Migration failed:', err);
+  process.exit(1);
+});

scripts/db-reset.ts

@@ -0,0 +1,97 @@
+/**
+ * Wipe all data from the database, preserving schema + drizzle migration
+ * history. Run before swapping seed fixtures.
+ *
+ *   pnpm tsx scripts/db-reset.ts          (refuses without --confirm)
+ *   pnpm tsx scripts/db-reset.ts --confirm
+ *
+ * Truncates every table in the `public` schema except the drizzle
+ * migration tracker, then resets sequences. Wraps the loop in a single
+ * transaction so a mid-wipe failure rolls back cleanly.
+ *
+ * Refuses to run when DATABASE_URL points at anything that doesn't look
+ * like a local/dev host. Override with --i-know-what-im-doing.
+ */
+
+import 'dotenv/config';
+import postgres from 'postgres';
+
+const url: string = process.env.DATABASE_URL ?? '';
+if (!url) {
+  console.error('DATABASE_URL is not set; aborting.');
+  process.exit(1);
+}
+
+const args = new Set(process.argv.slice(2));
+if (!args.has('--confirm')) {
+  console.error('Refusing to wipe without --confirm');
+  console.error('Run again as: pnpm tsx scripts/db-reset.ts --confirm');
+  process.exit(1);
+}
+
+// Best-effort safety: refuse for anything that doesn't look like a local DB.
+function looksLocal(u: string): boolean {
+  try {
+    const parsed = new URL(u);
+    return (
+      parsed.hostname === 'localhost' ||
+      parsed.hostname === '127.0.0.1' ||
+      parsed.hostname === '::1' ||
+      parsed.hostname.endsWith('.local') ||
+      parsed.hostname.endsWith('.internal') ||
+      parsed.hostname === 'host.docker.internal' ||
+      // Docker compose service names commonly used here
+      parsed.hostname === 'postgres' ||
+      parsed.hostname === 'db'
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (!looksLocal(url) && !args.has('--i-know-what-im-doing')) {
+  console.error(
+    `DATABASE_URL host doesn't look local. Refusing to wipe a remote DB without --i-know-what-im-doing.`,
+  );
+  process.exit(1);
+}
+
+const sql = postgres(url, { max: 1 });
+
+async function main() {
+  console.log('Resetting database...');
+  console.log(`  url: ${url.replace(/:[^:@]*@/, ':***@')}`);
+
+  const tables = await sql<{ tablename: string }[]>`
+    SELECT tablename FROM pg_tables
+    WHERE schemaname = 'public'
+      AND tablename NOT LIKE 'drizzle_%'
+      AND tablename != '__drizzle_migrations'
+  `;
+
+  if (tables.length === 0) {
+    console.log('  no user tables found, nothing to do.');
+    await sql.end();
+    return;
+  }
+
+  // Single TRUNCATE … CASCADE is faster than per-table loops and handles
+  // FK ordering for us. Quote table names defensively.
+  const tableList = tables.map((t) => `"public"."${t.tablename}"`).join(', ');
+
+  console.log(`  truncating ${tables.length} tables...`);
+  await sql.unsafe(`TRUNCATE ${tableList} RESTART IDENTITY CASCADE`);
+  console.log('  done.');
+
+  await sql.end();
+  console.log('');
+  console.log('Database reset complete. Run a seed script next:');
+  console.log('  pnpm db:seed              # realistic NocoDB-shaped fixture');
+  console.log('  pnpm db:seed:synthetic    # one client per pipeline stage');
+}
+
+main().catch(async (err) => {
+  console.error('Reset failed:', err);
+  await sql.end().catch(() => undefined);
+  process.exit(1);
+});

scripts/dev-open-browser.ts

@@ -0,0 +1,83 @@
+/**
+ * Launch a headed Chromium with NO viewport override so it adopts the
+ * host monitor's natural size — useful when you want to drive the CRM
+ * manually and have full-screen real estate.
+ *
+ * Pre-fills the login form for the synthetic admin (admin@portnimara.test
+ * / SuperAdmin12345!) but does not submit; press Enter when ready.
+ *
+ * The script keeps running until the browser window is closed by the
+ * user or until you Ctrl-C.
+ *
+ *   pnpm tsx scripts/dev-open-browser.ts             # super_admin
+ *   pnpm tsx scripts/dev-open-browser.ts sales_agent
+ *   pnpm tsx scripts/dev-open-browser.ts viewer
+ *   pnpm tsx scripts/dev-open-browser.ts --no-prefill
+ */
+
+import 'dotenv/config';
+// @playwright/test re-exports the same chromium driver and is already
+// installed as a dev dep; using it avoids needing to add the standalone
+// `playwright` package as a separate dependency.
+import { chromium } from '@playwright/test';
+
+const USERS: Record<string, { email: string; password: string }> = {
+  super_admin: { email: 'admin@portnimara.test', password: 'SuperAdmin12345!' },
+  sales_agent: { email: 'agent@portnimara.test', password: 'SalesAgent12345!' },
+  viewer: { email: 'viewer@portnimara.test', password: 'ViewerUser12345!' },
+};
+
+const BASE_URL = process.env.DEV_BASE_URL ?? 'http://localhost:3000';
+
+async function main() {
+  const args = process.argv.slice(2);
+  const noPrefill = args.includes('--no-prefill');
+  const role =
+    args.find((a) => !a.startsWith('--')) && USERS[args.find((a) => !a.startsWith('--'))!]
+      ? args.find((a) => !a.startsWith('--'))!
+      : 'super_admin';
+  const user = USERS[role]!;
+
+  console.log(`Launching headed Chromium → ${BASE_URL}`);
+  console.log(`  role: ${role}  (${user.email})`);
+
+  const browser = await chromium.launch({
+    headless: false,
+    args: ['--start-maximized'],
+  });
+
+  // viewport: null lets the page fill the OS window. Combined with
+  // --start-maximized this matches the host monitor's natural size.
+  const context = await browser.newContext({ viewport: null });
+  const page = await context.newPage();
+
+  await page.goto(`${BASE_URL}/login`);
+
+  if (!noPrefill) {
+    try {
+      await page.waitForSelector('#email', { timeout: 5000 });
+      await page.fill('#email', user.email);
+      await page.fill('#password', user.password);
+      console.log('  Login form pre-filled — press Enter in the browser to submit.');
+    } catch {
+      console.log('  Could not find login form (page may have redirected).');
+    }
+  }
+
+  console.log('');
+  console.log("Browser is open. Close it when you're done; the script will exit.");
+  console.log('Or Ctrl-C here to force-quit.');
+
+  // Keep the process alive until the browser window is closed.
+  await new Promise<void>((resolve) => {
+    browser.on('disconnected', () => resolve());
+  });
+
+  await browser.close().catch(() => undefined);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Open-browser failed:', err);
+  process.exit(1);
+});

scripts/dev-recommender-smoke.ts

@@ -0,0 +1,52 @@
+/**
+ * Dev-only smoke check for the berth recommender. Resolves the first
+ * port-nimara interest (with desired dims set) and prints the top-N
+ * recommendations.
+ *
+ *   pnpm tsx scripts/dev-recommender-smoke.ts
+ */
+import 'dotenv/config';
+import { eq, isNotNull, and } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { interests } from '@/lib/db/schema/interests';
+import { recommendBerths } from '@/lib/services/berth-recommender.service';
+
+async function main() {
+  const [port] = await db
+    .select({ id: ports.id })
+    .from(ports)
+    .where(eq(ports.slug, 'port-nimara'))
+    .limit(1);
+  if (!port) throw new Error('port-nimara not found');
+
+  const [interest] = await db
+    .select({ id: interests.id })
+    .from(interests)
+    .where(and(eq(interests.portId, port.id), isNotNull(interests.desiredLengthFt)))
+    .limit(1);
+  if (!interest) throw new Error('No interest with desired dims set');
+
+  console.log(`> Recommending berths for interest ${interest.id} on port ${port.id}…`);
+  const recs = await recommendBerths({
+    interestId: interest.id,
+    portId: port.id,
+  });
+
+  console.log(`> ${recs.length} recommendations:`);
+  for (const r of recs) {
+    console.log(
+      `  ${r.mooringNumber.padEnd(5)} tier=${r.tier} fit=${r.fitScore}  ` +
+        `${r.lengthFt}×${r.widthFt}×${r.draftFt} ft  buf=${r.sizeBufferPct}%  ` +
+        `${r.reasons.dimensional}; ${r.reasons.pipeline}`,
+    );
+  }
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

scripts/dev-reset-admin-pw.ts

@@ -0,0 +1,28 @@
+import 'dotenv/config';
+import { and, eq } from 'drizzle-orm';
+
+import { auth } from '@/lib/auth';
+import { db } from '@/lib/db';
+import { user, account } from '@/lib/db/schema/users';
+
+async function main() {
+  const email = process.argv[2] ?? 'admin@portnimara.test';
+  const pw = process.argv[3] ?? 'SuperAdmin12345!';
+  const [u] = await db.select().from(user).where(eq(user.email, email)).limit(1);
+  if (!u) throw new Error(`user not found: ${email}`);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const ctx = await (auth as any).$context;
+  const hash = await ctx.password.hash(pw);
+  const res = await db
+    .update(account)
+    .set({ password: hash })
+    .where(and(eq(account.userId, u.id), eq(account.providerId, 'credential')))
+    .returning({ id: account.id });
+  console.log(`updated ${res.length} credential row(s) for ${email}`);
+  process.exit(0);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

scripts/encrypt-plaintext-credentials.ts

@@ -0,0 +1,138 @@
+/**
+ * One-time migration: encrypt any plaintext credential rows in
+ * `system_settings` that should now be AES-256-GCM encrypted per the
+ * settings registry. Safe to re-run (idempotent — only touches plaintext
+ * rows, skips rows that are already encrypted envelopes).
+ *
+ * Currently handles:
+ *   - `documenso_api_key_override`            → in-place encrypt
+ *   - `storage_s3_access_key` (legacy)        → encrypt + move to
+ *                                                `storage_s3_access_key_encrypted`
+ *   - `documenso_webhook_secret` (if string)  → in-place encrypt
+ *
+ * Run: `pnpm tsx scripts/encrypt-plaintext-credentials.ts`
+ */
+import { and, eq, isNull } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { systemSettings } from '@/lib/db/schema';
+import { encrypt } from '@/lib/utils/encryption';
+
+const KEYS_TO_ENCRYPT_IN_PLACE = ['documenso_api_key_override', 'documenso_webhook_secret'];
+
+function isEncryptedEnvelope(value: unknown): boolean {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { iv?: unknown }).iv === 'string' &&
+    typeof (value as { tag?: unknown }).tag === 'string' &&
+    typeof (value as { data?: unknown }).data === 'string'
+  );
+}
+
+async function encryptInPlace(key: string): Promise<{ touched: number; skipped: number }> {
+  const rows = await db
+    .select({ key: systemSettings.key, portId: systemSettings.portId, value: systemSettings.value })
+    .from(systemSettings)
+    .where(eq(systemSettings.key, key));
+
+  let touched = 0;
+  let skipped = 0;
+  for (const row of rows) {
+    if (isEncryptedEnvelope(row.value)) {
+      skipped++;
+      continue;
+    }
+    if (typeof row.value !== 'string' || row.value === '') {
+      skipped++;
+      continue;
+    }
+    const envelope = JSON.parse(encrypt(row.value)) as {
+      iv: string;
+      tag: string;
+      data: string;
+    };
+    if (row.portId) {
+      await db
+        .update(systemSettings)
+        .set({ value: envelope, updatedAt: new Date() })
+        .where(and(eq(systemSettings.key, key), eq(systemSettings.portId, row.portId)));
+    } else {
+      await db
+        .update(systemSettings)
+        .set({ value: envelope, updatedAt: new Date() })
+        .where(and(eq(systemSettings.key, key), isNull(systemSettings.portId)));
+    }
+    touched++;
+  }
+  return { touched, skipped };
+}
+
+async function moveS3AccessKeyToEncrypted(): Promise<{
+  moved: number;
+  alreadyMigrated: number;
+}> {
+  // Move global rows only — s3 storage settings are global by design.
+  const legacyRows = await db
+    .select({ value: systemSettings.value })
+    .from(systemSettings)
+    .where(and(eq(systemSettings.key, 'storage_s3_access_key'), isNull(systemSettings.portId)));
+
+  if (legacyRows.length === 0) {
+    return { moved: 0, alreadyMigrated: 0 };
+  }
+
+  // Check if the encrypted form already exists.
+  const existingEncrypted = await db
+    .select({ key: systemSettings.key })
+    .from(systemSettings)
+    .where(
+      and(eq(systemSettings.key, 'storage_s3_access_key_encrypted'), isNull(systemSettings.portId)),
+    );
+
+  if (existingEncrypted.length > 0) {
+    // Encrypted form wins; leave the legacy row in place so reads still
+    // tolerate it (the storage layer reads both and prefers encrypted).
+    return { moved: 0, alreadyMigrated: legacyRows.length };
+  }
+
+  const plaintext = legacyRows[0]!.value;
+  if (typeof plaintext !== 'string' || plaintext === '') {
+    return { moved: 0, alreadyMigrated: 0 };
+  }
+  const envelope = JSON.parse(encrypt(plaintext)) as { iv: string; tag: string; data: string };
+  await db.insert(systemSettings).values({
+    key: 'storage_s3_access_key_encrypted',
+    portId: null,
+    value: envelope,
+  });
+  // Drop the legacy plaintext row so it doesn't show up in admin
+  // settings dumps anymore. The storage layer's backward-compat path
+  // continues to handle older rows on other deployments.
+  await db
+    .delete(systemSettings)
+    .where(and(eq(systemSettings.key, 'storage_s3_access_key'), isNull(systemSettings.portId)));
+  return { moved: 1, alreadyMigrated: 0 };
+}
+
+async function main(): Promise<void> {
+  console.log('Encrypting plaintext credentials...');
+
+  for (const key of KEYS_TO_ENCRYPT_IN_PLACE) {
+    const { touched, skipped } = await encryptInPlace(key);
+    console.log(`  ${key}: ${touched} encrypted, ${skipped} skipped`);
+  }
+
+  const s3 = await moveS3AccessKeyToEncrypted();
+  console.log(
+    `  storage_s3_access_key → _encrypted: ${s3.moved} moved, ${s3.alreadyMigrated} already migrated`,
+  );
+
+  console.log('Done.');
+  process.exit(0);
+}
+
+main().catch((err: unknown) => {
+  console.error('Migration failed:', err);
+  process.exit(1);
+});

scripts/import-berths-from-nocodb.ts

@@ -0,0 +1,409 @@
+/**
+ * Idempotent NocoDB Berths → CRM `berths` import.
+ *
+ * Re-running picks up NocoDB additions/edits without clobbering CRM-side
+ * overrides: rows where `updated_at > last_imported_at` are treated as
+ * human-edited and skipped (use `--force` to override). Map Data JSON
+ * is validated and upserted into `berth_map_data` as a separate step.
+ *
+ * Usage:
+ *   pnpm tsx scripts/import-berths-from-nocodb.ts --dry-run [--port-slug port-nimara]
+ *   pnpm tsx scripts/import-berths-from-nocodb.ts --apply  [--port-slug port-nimara]
+ *   pnpm tsx scripts/import-berths-from-nocodb.ts --apply  --force
+ *   pnpm tsx scripts/import-berths-from-nocodb.ts --apply  --update-snapshot
+ *
+ * Edge cases mitigated (see plan §14.1):
+ *   - Mooring collisions   : unique (port_id, mooring_number) on the table.
+ *   - Concurrent runs      : pg_advisory_xact_lock on a stable key.
+ *   - Numeric-with-units   : parseDecimalWithUnit() strips trailing units.
+ *   - Metric drift         : NocoDB metric formula columns are ignored;
+ *                            metric values are recomputed from imperial.
+ *   - Map Data shape       : zod-validated; failures are skipped silently
+ *                            rather than aborting the whole import.
+ *   - Status enum          : NocoDB display strings → CRM snake_case.
+ *   - NocoDB row deleted   : reported as "orphaned in CRM"; not auto-deleted.
+ */
+
+import 'dotenv/config';
+import { eq, sql } from 'drizzle-orm';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { berths, berthMapData } from '@/lib/db/schema/berths';
+import { fetchAllRows, loadNocoDbConfig, NOCO_TABLES } from '@/lib/dedup/nocodb-source';
+import {
+  buildPlan,
+  mapRow,
+  type Action,
+  type ImportedBerth,
+  type PlanEntry,
+  type ExistingBerthRow,
+} from '@/lib/services/berth-import';
+
+// ─── CLI ────────────────────────────────────────────────────────────────────
+
+interface CliArgs {
+  dryRun: boolean;
+  apply: boolean;
+  portSlug: string;
+  force: boolean;
+  updateSnapshot: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    dryRun: false,
+    apply: false,
+    portSlug: 'port-nimara',
+    force: false,
+    updateSnapshot: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--apply') args.apply = true;
+    else if (a === '--port-slug') args.portSlug = argv[++i] ?? 'port-nimara';
+    else if (a === '--force') args.force = true;
+    else if (a === '--update-snapshot') args.updateSnapshot = true;
+    else if (a === '-h' || a === '--help') {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+  if (!args.dryRun && !args.apply) {
+    console.error('Must specify either --dry-run or --apply.');
+    printHelp();
+    process.exit(1);
+  }
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage:
+  pnpm tsx scripts/import-berths-from-nocodb.ts --dry-run [--port-slug <slug>]
+  pnpm tsx scripts/import-berths-from-nocodb.ts --apply   [--port-slug <slug>] [--force] [--update-snapshot]
+
+Flags:
+  --dry-run             Read NocoDB + diff vs CRM. No writes.
+  --apply               Apply the plan to the DB.
+  --port-slug <slug>    Target port slug (default: port-nimara).
+  --force               Overwrite rows where CRM updated_at > last_imported_at.
+  --update-snapshot     Rewrite src/lib/db/seed-data/berths.json after apply.
+  -h, --help            Show this help.
+`);
+}
+
+// ─── Stable advisory lock key ───────────────────────────────────────────────
+// 64-bit BIGINT - first 4 bytes spell "BRTH" so it's grep-able in pg_locks.
+const BERTH_IMPORT_LOCK_KEY = 0x4252544800000001n;
+
+// ─── Apply ──────────────────────────────────────────────────────────────────
+
+interface ApplyResult {
+  inserted: number;
+  updated: number;
+  skipped: number;
+  mapDataWritten: number;
+  warnings: string[];
+}
+
+async function apply(
+  portId: string,
+  plan: PlanEntry[],
+  orphans: ExistingBerthRow[],
+  importedAt: Date,
+): Promise<ApplyResult> {
+  const result: ApplyResult = {
+    inserted: 0,
+    updated: 0,
+    skipped: 0,
+    mapDataWritten: 0,
+    warnings: [],
+  };
+  for (const orphan of orphans) {
+    result.warnings.push(
+      `Orphan: CRM has mooring="${orphan.mooringNumber}" but NocoDB no longer does (id=${orphan.id})`,
+    );
+  }
+
+  await db.transaction(async (tx) => {
+    // Stable lock so two simultaneous --apply runs serialize.
+    await tx.execute(sql`SELECT pg_advisory_xact_lock(${BERTH_IMPORT_LOCK_KEY})`);
+
+    for (const entry of plan) {
+      if (entry.action === 'skip-edited' || entry.action === 'noop') {
+        result.skipped += 1;
+        result.warnings.push(`Skipped ${entry.imported.mooringNumber}: ${entry.reason ?? 'no-op'}`);
+        continue;
+      }
+      const i = entry.imported;
+      const n = i.numerics;
+      const baseValues = {
+        portId,
+        mooringNumber: i.mooringNumber,
+        area: i.area,
+        status: i.status,
+        lengthFt: n.lengthFt != null ? String(n.lengthFt) : null,
+        widthFt: n.widthFt != null ? String(n.widthFt) : null,
+        draftFt: n.draftFt != null ? String(n.draftFt) : null,
+        lengthM: n.lengthM != null ? String(n.lengthM) : null,
+        widthM: n.widthM != null ? String(n.widthM) : null,
+        draftM: n.draftM != null ? String(n.draftM) : null,
+        widthIsMinimum: i.widthIsMinimum,
+        nominalBoatSize: n.nominalBoatSize != null ? String(n.nominalBoatSize) : null,
+        nominalBoatSizeM: n.nominalBoatSizeM != null ? String(n.nominalBoatSizeM) : null,
+        waterDepth: n.waterDepth != null ? String(n.waterDepth) : null,
+        waterDepthM: n.waterDepthM != null ? String(n.waterDepthM) : null,
+        waterDepthIsMinimum: i.waterDepthIsMinimum,
+        sidePontoon: i.sidePontoon,
+        powerCapacity: n.powerCapacity != null ? String(n.powerCapacity) : null,
+        voltage: n.voltage != null ? String(n.voltage) : null,
+        mooringType: i.mooringType,
+        cleatType: i.cleatType,
+        cleatCapacity: i.cleatCapacity,
+        bollardType: i.bollardType,
+        bollardCapacity: i.bollardCapacity,
+        access: i.access,
+        price: n.price != null ? String(n.price) : null,
+        priceCurrency: 'USD' as const,
+        bowFacing: i.bowFacing,
+        berthApproved: i.berthApproved,
+        statusOverrideMode: i.statusOverrideMode,
+        lastImportedAt: importedAt,
+        updatedAt: importedAt,
+      };
+
+      let berthId: string;
+      if (entry.action === 'insert') {
+        const [inserted] = await tx
+          .insert(berths)
+          .values({ ...baseValues, tenureType: 'permanent' })
+          .returning({ id: berths.id });
+        berthId = inserted!.id;
+        result.inserted += 1;
+      } else {
+        await tx.update(berths).set(baseValues).where(eq(berths.id, entry.existing!.id));
+        berthId = entry.existing!.id;
+        result.updated += 1;
+      }
+
+      if (i.mapData) {
+        const mapValues = {
+          berthId,
+          svgPath: i.mapData.path ?? null,
+          x: i.mapData.x != null ? String(i.mapData.x) : null,
+          y: i.mapData.y != null ? String(i.mapData.y) : null,
+          transform: i.mapData.transform ?? null,
+          fontSize: i.mapData.fontSize != null ? String(i.mapData.fontSize) : null,
+          updatedAt: importedAt,
+        };
+        await tx
+          .insert(berthMapData)
+          .values(mapValues)
+          .onConflictDoUpdate({
+            target: berthMapData.berthId,
+            set: {
+              svgPath: mapValues.svgPath,
+              x: mapValues.x,
+              y: mapValues.y,
+              transform: mapValues.transform,
+              fontSize: mapValues.fontSize,
+              updatedAt: importedAt,
+            },
+          });
+        result.mapDataWritten += 1;
+      }
+    }
+  });
+  return result;
+}
+
+// ─── Snapshot writer (for seed-data refresh) ────────────────────────────────
+
+async function writeSnapshot(imported: ImportedBerth[]): Promise<string> {
+  // Ordering: idx 0..4 available (small), 5..9 under_offer (medium),
+  // 10..11 sold (large), then everything else by mooring number. The
+  // first 12 indexes feed `seed-data.ts` interest/reservation stubs.
+  const sortByLength = (a: ImportedBerth, b: ImportedBerth) =>
+    (a.numerics.lengthFt ?? 0) - (b.numerics.lengthFt ?? 0);
+  const available = imported
+    .filter((b) => b.status === 'available')
+    .sort(sortByLength)
+    .slice(0, 5);
+  const underOffer = imported
+    .filter((b) => b.status === 'under_offer')
+    .sort(sortByLength)
+    .slice(0, 5);
+  const sold = imported
+    .filter((b) => b.status === 'sold')
+    .sort((a, b) => -sortByLength(a, b))
+    .slice(0, 2);
+  const featured = new Set([...available, ...underOffer, ...sold].map((b) => b.mooringNumber));
+  const rest = imported
+    .filter((b) => !featured.has(b.mooringNumber))
+    .sort((a, b) => a.mooringNumber.localeCompare(b.mooringNumber, 'en', { numeric: true }));
+  const ordered = [...available, ...underOffer, ...sold, ...rest];
+
+  const payload = ordered.map((b) => ({
+    legacyId: b.legacyId,
+    mooringNumber: b.mooringNumber,
+    area: b.area,
+    status: b.status,
+    lengthFt: b.numerics.lengthFt,
+    widthFt: b.numerics.widthFt,
+    draftFt: b.numerics.draftFt,
+    lengthM: b.numerics.lengthM,
+    widthM: b.numerics.widthM,
+    draftM: b.numerics.draftM,
+    widthIsMinimum: b.widthIsMinimum,
+    nominalBoatSize: b.numerics.nominalBoatSize,
+    nominalBoatSizeM: b.numerics.nominalBoatSizeM,
+    waterDepth: b.numerics.waterDepth,
+    waterDepthM: b.numerics.waterDepthM,
+    waterDepthIsMinimum: b.waterDepthIsMinimum,
+    sidePontoon: b.sidePontoon,
+    powerCapacity: b.numerics.powerCapacity,
+    voltage: b.numerics.voltage,
+    mooringType: b.mooringType,
+    cleatType: b.cleatType,
+    cleatCapacity: b.cleatCapacity,
+    bollardType: b.bollardType,
+    bollardCapacity: b.bollardCapacity,
+    access: b.access,
+    price: b.numerics.price,
+    bowFacing: b.bowFacing,
+    berthApproved: b.berthApproved,
+    statusOverrideMode: b.statusOverrideMode,
+  }));
+
+  const target = path.resolve(process.cwd(), 'src/lib/db/seed-data/berths.json');
+  await fs.writeFile(target, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  return target;
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const config = loadNocoDbConfig();
+
+  const [port] = await db
+    .select({ id: ports.id, slug: ports.slug })
+    .from(ports)
+    .where(eq(ports.slug, args.portSlug))
+    .limit(1);
+  if (!port) {
+    console.error(`No port found with slug "${args.portSlug}".`);
+    process.exit(1);
+  }
+
+  console.log(`> Fetching NocoDB Berths…`);
+  const rows = await fetchAllRows(NOCO_TABLES.berths, config);
+  console.log(`  fetched ${rows.length} rows from NocoDB`);
+
+  const imported: ImportedBerth[] = [];
+  let skippedMalformed = 0;
+  for (const r of rows) {
+    const m = mapRow(r);
+    if (m) imported.push(m);
+    else skippedMalformed += 1;
+  }
+  if (skippedMalformed > 0) {
+    console.warn(`  ${skippedMalformed} rows skipped (missing Mooring Number)`);
+  }
+
+  // De-dup against any same-mooring twins surfacing from NocoDB
+  // (defensive — the Berths table is keyed on Mooring Number in NocoDB).
+  const seen = new Set<string>();
+  const dedup: ImportedBerth[] = [];
+  for (const b of imported) {
+    if (seen.has(b.mooringNumber)) {
+      console.warn(`  duplicate mooring "${b.mooringNumber}" in NocoDB — keeping first`);
+      continue;
+    }
+    seen.add(b.mooringNumber);
+    dedup.push(b);
+  }
+
+  console.log(`> Reading current CRM berths for port "${port.slug}"…`);
+  const existingRows = await db
+    .select({
+      id: berths.id,
+      mooringNumber: berths.mooringNumber,
+      updatedAt: berths.updatedAt,
+      lastImportedAt: berths.lastImportedAt,
+    })
+    .from(berths)
+    .where(eq(berths.portId, port.id));
+  console.log(`  ${existingRows.length} existing rows`);
+
+  const existingByMooring = new Map(existingRows.map((r) => [r.mooringNumber, r]));
+  const { plan, orphans } = buildPlan(dedup, existingByMooring, args.force);
+
+  const counts = plan.reduce(
+    (acc, e) => {
+      acc[e.action] += 1;
+      return acc;
+    },
+    { insert: 0, update: 0, 'skip-edited': 0, noop: 0 } as Record<Action, number>,
+  );
+
+  console.log(`> Plan:`);
+  console.log(`    insert       : ${counts.insert}`);
+  console.log(`    update       : ${counts.update}`);
+  console.log(`    skip-edited  : ${counts['skip-edited']}`);
+  console.log(`    no-op        : ${counts.noop}`);
+  console.log(`    orphans (CRM): ${orphans.length}`);
+
+  if (counts['skip-edited'] > 0) {
+    console.log(`  ↳ Skipped (CRM-edited; pass --force to overwrite):`);
+    for (const e of plan.filter((p) => p.action === 'skip-edited').slice(0, 10)) {
+      console.log(`      - ${e.imported.mooringNumber}  ${e.reason}`);
+    }
+    if (counts['skip-edited'] > 10) console.log(`      …and ${counts['skip-edited'] - 10} more`);
+  }
+  if (orphans.length > 0) {
+    console.log(`  ↳ Orphans (in CRM but missing from NocoDB):`);
+    for (const o of orphans.slice(0, 10)) console.log(`      - ${o.mooringNumber}`);
+    if (orphans.length > 10) console.log(`      …and ${orphans.length - 10} more`);
+  }
+
+  // Snapshot write is independent of DB writes — even in --dry-run mode
+  // a rep may want to refresh the seed JSON to capture the latest NocoDB
+  // shape without committing to the DB import. The original gate dropped
+  // this silently when --dry-run was passed; audit caught it.
+  if (args.updateSnapshot) {
+    const written = await writeSnapshot(dedup);
+    console.log(`> Wrote ${dedup.length} rows to ${path.relative(process.cwd(), written)}`);
+  }
+
+  if (args.dryRun) {
+    console.log(`\n[dry-run] no DB writes performed.`);
+    return;
+  }
+
+  console.log(`> Applying…`);
+  const result = await apply(port.id, plan, orphans, new Date());
+  console.log(`  inserted        : ${result.inserted}`);
+  console.log(`  updated         : ${result.updated}`);
+  console.log(`  skipped         : ${result.skipped}`);
+  console.log(`  map data writes : ${result.mapDataWritten}`);
+  if (result.warnings.length) {
+    console.log(`  warnings        :`);
+    for (const w of result.warnings.slice(0, 20)) console.log(`    - ${w}`);
+    if (result.warnings.length > 20) console.log(`    …and ${result.warnings.length - 20} more`);
+  }
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err: unknown) => {
+    console.error(err);
+    process.exit(1);
+  });

scripts/import-organized-documents.ts

@@ -0,0 +1,326 @@
+/**
+ * Importer for an organized S3 / filesystem bucket whose folder structure
+ * already represents real organisation. Walks every key under `--bucket-prefix`,
+ * builds matching `document_folders` rows mirroring the path, then inserts
+ * `documents` + `files` rows pointing at the existing storage keys verbatim
+ * — no path rewrite. Use when migrating from a legacy MinIO bucket whose
+ * tree is the source of truth.
+ *
+ * Usage:
+ *   pnpm tsx scripts/import-organized-documents.ts --port-slug <slug> \
+ *       --bucket-prefix "legacy-imports/" --dry-run
+ *   pnpm tsx scripts/import-organized-documents.ts --port-slug <slug> \
+ *       --bucket-prefix "legacy-imports/" --apply
+ *
+ * Idempotency:
+ *   - Folders: sibling-name unique index swallows duplicate creates and we
+ *     reuse the existing row.
+ *   - Documents: skipped when a row with `(port_id, fileStoragePath)` already
+ *     exists — the storage key is the natural identity for this importer.
+ */
+
+import 'dotenv/config';
+import path from 'node:path';
+import { and, eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { documents, documentFolders, files } from '@/lib/db/schema/documents';
+import { user } from '@/lib/db/schema/users';
+import { createAuditLog } from '@/lib/audit';
+import { ConflictError } from '@/lib/errors';
+import { createFolder } from '@/lib/services/document-folders.service';
+import { parseImportPath } from '@/lib/services/document-import';
+import { getStorageBackend } from '@/lib/storage';
+
+interface CliArgs {
+  portSlug: string;
+  bucketPrefix: string;
+  dryRun: boolean;
+  apply: boolean;
+  uploadedByUserId: string | null;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    portSlug: '',
+    bucketPrefix: '',
+    dryRun: false,
+    apply: false,
+    uploadedByUserId: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--port-slug') args.portSlug = argv[++i] ?? '';
+    else if (a === '--bucket-prefix') args.bucketPrefix = argv[++i] ?? '';
+    else if (a === '--uploaded-by') args.uploadedByUserId = argv[++i] ?? null;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--apply') args.apply = true;
+    else if (a === '-h' || a === '--help') {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+  if (!args.portSlug) {
+    console.error('Missing required --port-slug');
+    process.exit(1);
+  }
+  if (!args.dryRun && !args.apply) {
+    console.error('Must specify either --dry-run or --apply.');
+    process.exit(1);
+  }
+  if (args.dryRun && args.apply) {
+    console.error('--dry-run and --apply are mutually exclusive.');
+    process.exit(1);
+  }
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage:
+  pnpm tsx scripts/import-organized-documents.ts \\
+      --port-slug <slug> \\
+      --bucket-prefix <prefix> \\
+      (--dry-run | --apply) \\
+      [--uploaded-by <userId>]
+`);
+}
+
+interface PlannedDoc {
+  key: string;
+  folderSegments: string[];
+  filename: string;
+  bytes: number | null;
+  contentType: string;
+  alreadyImported: boolean;
+}
+
+const CONTENT_TYPE_BY_EXT: Record<string, string> = {
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.txt': 'text/plain',
+  '.csv': 'text/csv',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
+
+function guessContentType(filename: string): string {
+  const ext = path.extname(filename).toLowerCase();
+  return CONTENT_TYPE_BY_EXT[ext] ?? 'application/octet-stream';
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  const port = await db.query.ports.findFirst({ where: eq(ports.slug, args.portSlug) });
+  if (!port) {
+    console.error(`Port not found: ${args.portSlug}`);
+    process.exit(1);
+  }
+
+  let uploadedById = args.uploadedByUserId;
+  if (!uploadedById) {
+    const [u] = await db.select({ id: user.id }).from(user).limit(1);
+    if (!u) {
+      console.error(
+        'No user rows exist; pass --uploaded-by <userId> or seed at least one user before running.',
+      );
+      process.exit(1);
+    }
+    uploadedById = u.id;
+    console.log(`No --uploaded-by provided; falling back to first user: ${uploadedById}`);
+  }
+
+  const backend = await getStorageBackend();
+  console.log(`Listing keys under prefix "${args.bucketPrefix}" via ${backend.name} backend …`);
+  const keys = await backend.listByPrefix(args.bucketPrefix);
+  console.log(`Found ${keys.length} candidate keys.`);
+
+  const plan: PlannedDoc[] = [];
+  for (const key of keys) {
+    const parsed = parseImportPath(args.bucketPrefix, key);
+    if (!parsed.filename) continue;
+
+    const head = await backend.head(key);
+    const existing = await db.query.files.findFirst({
+      where: and(eq(files.portId, port.id), eq(files.storagePath, key)),
+      columns: { id: true },
+    });
+
+    plan.push({
+      key,
+      folderSegments: parsed.folderSegments,
+      filename: parsed.filename,
+      bytes: head?.sizeBytes ?? null,
+      contentType: head?.contentType ?? guessContentType(parsed.filename),
+      alreadyImported: !!existing,
+    });
+  }
+
+  printPlan(plan);
+
+  if (args.dryRun) {
+    console.log('\nDry-run complete. No changes written.');
+    return;
+  }
+
+  const folderIdByPath = new Map<string, string | null>();
+  folderIdByPath.set('', null);
+  let createdCount = 0;
+  let skippedCount = 0;
+
+  for (const entry of plan) {
+    if (entry.alreadyImported) {
+      skippedCount += 1;
+      continue;
+    }
+
+    const folderId = await ensureFolderChain(
+      port.id,
+      uploadedById,
+      entry.folderSegments,
+      folderIdByPath,
+    );
+
+    await db.transaction(async (tx) => {
+      const [fileRow] = await tx
+        .insert(files)
+        .values({
+          portId: port.id,
+          filename: entry.filename,
+          originalName: entry.filename,
+          mimeType: entry.contentType,
+          sizeBytes: entry.bytes !== null ? String(entry.bytes) : null,
+          storagePath: entry.key,
+          uploadedBy: uploadedById,
+          category: 'misc',
+          folderId,
+        })
+        .returning();
+      const [docRow] = await tx
+        .insert(documents)
+        .values({
+          portId: port.id,
+          documentType: 'other',
+          title: entry.filename,
+          createdBy: uploadedById,
+          folderId,
+          fileId: fileRow!.id,
+          status: 'completed',
+          isManualUpload: true,
+        })
+        .returning();
+
+      void createAuditLog({
+        userId: uploadedById,
+        portId: port.id,
+        action: 'create',
+        entityType: 'document',
+        entityId: docRow!.id,
+        metadata: {
+          source: 'organized-bucket-importer',
+          storageKey: entry.key,
+          folderSegments: entry.folderSegments,
+        },
+      });
+    });
+    createdCount += 1;
+    console.log(`✓ Imported ${entry.key}`);
+  }
+
+  console.log(
+    `\nDone. Created ${createdCount} documents, skipped ${skippedCount} (already imported).`,
+  );
+}
+
+async function ensureFolderChain(
+  portId: string,
+  userId: string,
+  segments: string[],
+  cache: Map<string, string | null>,
+): Promise<string | null> {
+  if (segments.length === 0) return null;
+
+  let parentId: string | null = null;
+  for (let i = 0; i < segments.length; i += 1) {
+    const pathKey = segments.slice(0, i + 1).join('/');
+    const cached = cache.get(pathKey);
+    if (cached !== undefined) {
+      parentId = cached;
+      continue;
+    }
+
+    const name = segments[i]!;
+    parentId = await createOrFindFolder(portId, userId, name, parentId);
+    cache.set(pathKey, parentId);
+  }
+  return parentId;
+}
+
+async function createOrFindFolder(
+  portId: string,
+  userId: string,
+  name: string,
+  parentId: string | null,
+): Promise<string> {
+  try {
+    const created = await createFolder(portId, userId, { name, parentId });
+    return created.id;
+  } catch (err) {
+    if (!(err instanceof ConflictError)) throw err;
+    // Sibling-name unique index hit — fetch the existing row so the import
+    // remains idempotent across re-runs.
+    const trimmed = name.trim();
+    const candidates = await db.query.documentFolders.findMany({
+      where: parentId
+        ? and(eq(documentFolders.portId, portId), eq(documentFolders.parentId, parentId))
+        : eq(documentFolders.portId, portId),
+    });
+    const existing = candidates.find(
+      (row) =>
+        (parentId ? row.parentId === parentId : row.parentId === null) &&
+        row.name.toLowerCase() === trimmed.toLowerCase(),
+    );
+    if (!existing) throw err;
+    return existing.id;
+  }
+}
+
+function printPlan(plan: PlannedDoc[]): void {
+  const grouped = new Map<string, PlannedDoc[]>();
+  for (const entry of plan) {
+    const folder = entry.folderSegments.join('/') || '(root)';
+    if (!grouped.has(folder)) grouped.set(folder, []);
+    grouped.get(folder)!.push(entry);
+  }
+  const folderNames = Array.from(grouped.keys()).sort();
+  console.log('\nPlan:');
+  for (const folder of folderNames) {
+    console.log(`  ${folder}/`);
+    for (const entry of grouped.get(folder)!) {
+      const flag = entry.alreadyImported ? '·' : '+';
+      const size = entry.bytes !== null ? ` (${entry.bytes}B)` : '';
+      console.log(`    ${flag} ${entry.filename}${size}`);
+    }
+  }
+  const newCount = plan.filter((p) => !p.alreadyImported).length;
+  const dupCount = plan.length - newCount;
+  console.log(`\nTotal: ${plan.length} keys → ${newCount} new, ${dupCount} already imported.`);
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

scripts/migrate-from-nocodb.ts

@@ -7,21 +7,31 @@
  *     Pulls the live NocoDB base, runs the transform + dedup pipeline,
  *     writes a report to .migration/<timestamp>/. NO database writes.
  *
- *   pnpm tsx scripts/migrate-from-nocodb.ts --dry-run --port-slug harbor-royale
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --dry-run --port-slug port-nimara
  *     Same, but tags the planned writes with the named port (matters for
  *     the apply phase — every client/interest belongs to one port).
  *
- *   pnpm tsx scripts/migrate-from-nocodb.ts --apply --report .migration/<dir>/
- *     [Not yet implemented — apply phase comes in a follow-up PR.]
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --apply --port-slug port-nimara
+ *     Re-fetches NocoDB, re-transforms, then writes the planned rows
+ *     into the target port via the idempotent `migration_source_links`
+ *     ledger. Re-runs are safe — already-imported source IDs are skipped.
+ *     REQUIRES `EMAIL_REDIRECT_TO` to be set in env (safety net) unless
+ *     `--unsafe-skip-redirect-check` is also passed.
  *
  * Design reference: docs/superpowers/specs/2026-05-03-dedup-and-migration-design.md §9.
  */
 
 import 'dotenv/config';
-
+import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { SUPER_ADMIN_USER_ID } from '@/lib/db/seed-bootstrap';
+import { applyPlan } from '@/lib/dedup/migration-apply';
 import { fetchSnapshot, loadNocoDbConfig } from '@/lib/dedup/nocodb-source';
 import { transformSnapshot } from '@/lib/dedup/migration-transform';
 import { resolveReportPaths, writeReport } from '@/lib/dedup/migration-report';
@@ -31,6 +41,7 @@ interface CliArgs {
   apply: boolean;
   portSlug: string | null;
   reportDir: string | null;
+  unsafeSkipRedirectCheck: boolean;
 }
 
 function parseArgs(argv: string[]): CliArgs {
@@ -39,6 +50,7 @@ function parseArgs(argv: string[]): CliArgs {
     apply: false,
     portSlug: null,
     reportDir: null,
+    unsafeSkipRedirectCheck: false,
   };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i]!;
@@ -46,6 +58,7 @@ function parseArgs(argv: string[]): CliArgs {
     else if (a === '--apply') args.apply = true;
     else if (a === '--port-slug') args.portSlug = argv[++i] ?? null;
     else if (a === '--report') args.reportDir = argv[++i] ?? null;
+    else if (a === '--unsafe-skip-redirect-check') args.unsafeSkipRedirectCheck = true;
     else if (a === '-h' || a === '--help') {
       printHelp();
       process.exit(0);
@@ -64,20 +77,50 @@ function printHelp(): void {
     Pulls NocoDB → transforms → writes report to .migration/<timestamp>/.
     No database writes.
 
-  pnpm tsx scripts/migrate-from-nocodb.ts --apply --report .migration/<dir>/
-    Apply phase. (Not yet implemented.)
+  pnpm tsx scripts/migrate-from-nocodb.ts --apply --port-slug <slug>
+    Re-fetches NocoDB, re-transforms, writes via migration_source_links
+    ledger. Idempotent — safe to re-run. Requires EMAIL_REDIRECT_TO set
+    (unless --unsafe-skip-redirect-check is also passed).
 
 Flags:
-  --dry-run               Read NocoDB, write report only.
-  --apply                 Actually write to the new DB. (Not yet supported.)
-  --port-slug <slug>      Port slug to attach to all imported entities.
-                          Defaults to the first available port if omitted.
-  --report <dir>          Path to a previously-generated report dir
-                          (only used by --apply).
-  -h, --help              Show this help.
+  --dry-run                       Read NocoDB, write report only.
+  --apply                         Actually write rows to the DB.
+  --port-slug <slug>              Port slug to attach to all imported
+                                  entities. Defaults to the first
+                                  available port if omitted.
+  --report <dir>                  Path to a previously-generated report
+                                  dir (only used by --apply).
+  --unsafe-skip-redirect-check    Skip the EMAIL_REDIRECT_TO precondition
+                                  check. Only use in production cutover.
+  -h, --help                      Show this help.
 `);
 }
 
+/**
+ * Resolve the target port: use the slug if provided, otherwise the first
+ * port found. Errors out cleanly if the slug doesn't match any port.
+ */
+async function resolvePort(slug: string | null): Promise<{ id: string; slug: string }> {
+  if (slug) {
+    const [p] = await db
+      .select({ id: ports.id, slug: ports.slug })
+      .from(ports)
+      .where(eq(ports.slug, slug))
+      .limit(1);
+    if (!p) {
+      console.error(`No port found with slug "${slug}".`);
+      process.exit(1);
+    }
+    return { id: p.id, slug: p.slug };
+  }
+  const [first] = await db.select({ id: ports.id, slug: ports.slug }).from(ports).limit(1);
+  if (!first) {
+    console.error('No ports exist in the target DB. Seed at least one port before applying.');
+    process.exit(1);
+  }
+  return { id: first.id, slug: first.slug };
+}
+
 async function main(): Promise<void> {
   const args = parseArgs(process.argv.slice(2));
 
@@ -87,13 +130,21 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  if (args.apply) {
-    console.error('--apply is not yet implemented in this version. P3 ships dry-run first.');
-    console.error('See docs/superpowers/specs/2026-05-03-dedup-and-migration-design.md §9.2.');
+  // Safety gate: --apply must run with EMAIL_REDIRECT_TO set, unless the
+  // operator explicitly opts out (production cutover).
+  if (args.apply && !process.env.EMAIL_REDIRECT_TO && !args.unsafeSkipRedirectCheck) {
+    console.error(
+      '--apply requires EMAIL_REDIRECT_TO to be set in the environment as a safety net.',
+    );
+    console.error('See docs/operations/outbound-comms-safety.md for the rationale.');
+    console.error(
+      'If you are running the production cutover and have read that doc, add ' +
+        '--unsafe-skip-redirect-check to override.',
+    );
     process.exit(2);
   }
 
-  // ── Dry-run path ───────────────────────────────────────────────────────────
+  // ── Fetch + transform (shared by dry-run and apply) ──────────────────────
 
   console.log('[migrate] Loading NocoDB config…');
   const config = loadNocoDbConfig();
@@ -104,14 +155,13 @@ async function main(): Promise<void> {
   const snapshot = await fetchSnapshot(config);
   const elapsed = ((Date.now() - start) / 1000).toFixed(1);
   console.log(
-    `[migrate] Snapshot fetched in ${elapsed}s — ${snapshot.interests.length} interests, ${snapshot.residentialInterests.length} residential, ${snapshot.berths.length} berths.`,
+    `[migrate] Snapshot fetched in ${elapsed}s — ${snapshot.interests.length} interests, ${snapshot.residentialInterests.length} residential, ${snapshot.berths.length} berths, ${snapshot.expenses?.length ?? 0} expenses.`,
   );
 
   console.log('[migrate] Running transform + dedup pipeline…');
   const plan = transformSnapshot(snapshot);
 
-  // Resolve output paths relative to the worktree root (the script itself
-  // lives in scripts/; we want the .migration dir at the repo root).
+  // Resolve output paths relative to the worktree root.
   const scriptDir = path.dirname(fileURLToPath(import.meta.url));
   const repoRoot = path.resolve(scriptDir, '..');
   const generatedAt = new Date().toISOString();
@@ -120,7 +170,7 @@ async function main(): Promise<void> {
   console.log(`[migrate] Writing report to ${paths.rootDir}…`);
   await writeReport(paths, plan, generatedAt);
 
-  // ── Console summary ──────────────────────────────────────────────────────
+  // ── Plan summary ─────────────────────────────────────────────────────────
   const s = plan.stats;
   console.log('');
   console.log('=== Migration Plan Summary ===');
@@ -129,12 +179,95 @@ async function main(): Promise<void> {
   );
   console.log(`  Output:    ${s.outputClients} clients, ${s.outputInterests} interests`);
   console.log(`             ${s.outputContacts} contacts, ${s.outputAddresses} addresses`);
+  console.log(
+    `             ${s.outputDocuments} EOI documents, ${s.outputDocumentSigners} signers`,
+  );
+  console.log(
+    `             ${s.outputResidentialClients} residential clients (with default-stage interests)`,
+  );
+  console.log(`             ${s.outputExpenses} expenses`);
   console.log(
     `  Dedup:     ${s.autoLinkedClusters} auto-linked clusters, ${s.needsReviewPairs} pairs flagged for review`,
   );
   console.log(`  Quality:   ${s.flaggedRows} rows flagged (see report.csv)`);
   console.log('');
   console.log(`  Full report: ${paths.summaryPath}`);
+
+  if (args.dryRun) {
+    console.log('');
+    console.log('Dry-run complete. Re-run with --apply to write rows.');
+    return;
+  }
+
+  // ── Apply path ───────────────────────────────────────────────────────────
+
+  const port = await resolvePort(args.portSlug);
+  const applyId = randomUUID();
+
+  console.log('');
+  console.log(`[migrate] Applying to port "${port.slug}" (id=${port.id})`);
+  console.log(`[migrate] Apply id: ${applyId}`);
+  console.log('[migrate] Inserting…');
+
+  const applyStart = Date.now();
+  const result = await applyPlan(plan, { port, applyId, appliedBy: SUPER_ADMIN_USER_ID });
+  const applyElapsed = ((Date.now() - applyStart) / 1000).toFixed(1);
+
+  console.log('');
+  console.log('=== Apply Result ===');
+  console.log(`  Time:      ${applyElapsed}s`);
+  console.log(
+    `  Clients:   ${result.clientsInserted} inserted, ${result.clientsSkipped} already linked`,
+  );
+  console.log(`  Contacts:  ${result.contactsInserted} inserted`);
+  console.log(`  Addresses: ${result.addressesInserted} inserted`);
+  console.log(`  Yachts:    ${result.yachtsInserted} inserted`);
+  console.log(
+    `  Interests: ${result.interestsInserted} inserted, ${result.interestsSkipped} already linked`,
+  );
+  console.log(
+    `  Documents: ${result.documentsInserted} inserted, ${result.documentsSkipped} already linked`,
+  );
+  console.log(`  Signers:   ${result.documentSignersInserted} inserted`);
+  console.log(
+    `  Res-Clt:   ${result.residentialClientsInserted} inserted, ${result.residentialClientsSkipped} already linked`,
+  );
+  console.log(`  Res-Int:   ${result.residentialInterestsInserted} inserted`);
+  console.log(
+    `  Expenses:  ${result.expensesInserted} inserted, ${result.expensesSkipped} already linked`,
+  );
+
+  if (result.warnings.length > 0) {
+    console.log('');
+    console.log('Warnings:');
+    for (const w of result.warnings.slice(0, 20)) {
+      console.log(`  - ${w}`);
+    }
+    if (result.warnings.length > 20) {
+      console.log(`  … ${result.warnings.length - 20} more`);
+    }
+  }
+
+  // ── Multi-berth links (folded in for the one-shot seed) ──────────────────
+  // The dedup plan only carries each deal's single `Berth Number`; the legacy
+  // `_nc_m2m_Berths_Interests` junction (multi-berth deals) is reconnected
+  // here from the local `nocodb_legacy` snapshot. Best-effort: if the dump
+  // isn't restored, log + continue (the standalone script can run it later).
+  try {
+    const { connectBerthLinks } = await import('./migration/connect-berth-links');
+    const bl = await connectBerthLinks({ portSlug: port.slug });
+    console.log(
+      `  Berths:    ${bl.inserted} multi-berth links inserted (${bl.madePrimary} new primary), ${bl.skipped} already linked`,
+    );
+    if (bl.unresolved.length > 0) {
+      console.log(`             ⚠ ${bl.unresolved.length} moorings with no CRM berth`);
+    }
+  } catch (err) {
+    console.log(
+      `  Berths:    ⚠ multi-berth link step skipped (${(err as Error).message}). ` +
+        `Run scripts/migration/connect-berth-links.ts once the nocodb_legacy dump is restored.`,
+    );
+  }
   console.log('');
 }
 

scripts/migrate-storage.ts

@@ -0,0 +1,29 @@
+/**
+ * Storage backend migration CLI — see §4.7a + §14.9a of
+ * docs/berth-recommender-and-pdf-plan.md.
+ *
+ *   pnpm tsx scripts/migrate-storage.ts --from s3 --to filesystem [--dry-run]
+ *   pnpm tsx scripts/migrate-storage.ts --from filesystem --to s3
+ *
+ * The actual migration logic lives in `src/lib/storage/migrate.ts` so the
+ * admin UI's "Switch backend" button can run the exact same code path. This
+ * file is a thin CLI wrapper.
+ */
+
+import { logger } from '@/lib/logger';
+import { parseArgs, runMigration } from '@/lib/storage/migrate';
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  logger.info({ args }, 'Starting storage migration');
+  const result = await runMigration(args);
+  logger.info({ result }, 'Storage migration complete');
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(0);
+}
+
+main().catch((err) => {
+  logger.error({ err }, 'Storage migration failed');
+  console.error(err);
+  process.exit(2);
+});

scripts/migration/backfill-documents.ts

@@ -0,0 +1,503 @@
+/**
+ * Phase 2 of the legacy migration: pull signed EOI PDFs + berth spec PDFs from
+ * the LEGACY MinIO (`client-portal` bucket) and deposit them into the CRM's own
+ * storage, linking them to the already-migrated deals + berths.
+ *
+ * Two storage worlds, kept strictly separate:
+ *   - LEGACY read  : a dedicated `minio` Client using LEGACY_MINIO_* env.
+ *   - CRM write    : `getStorageBackend()` (the CRM's own configured storage).
+ *     ⚠ We NEVER route legacy creds through getStorageBackend — that would
+ *     write INTO prod. LEGACY_MINIO_* is distinct from the CRM's MINIO_*.
+ *
+ * Idempotent + re-runnable: an EOI is skipped once its `documents.signedFileId`
+ * is set; a berth is skipped once it has a `currentPdfVersionId`.
+ *
+ * Run AFTER `migrate-from-nocodb.ts --apply`:
+ *   LEGACY_MINIO_ACCESS_KEY=… LEGACY_MINIO_SECRET_KEY=… \
+ *   pnpm tsx scripts/migration/backfill-documents.ts --port-slug port-nimara [--dry-run]
+ */
+import 'dotenv/config';
+import { randomUUID } from 'node:crypto';
+import { Client as MinioClient } from 'minio';
+import postgres from 'postgres';
+import { and, eq, isNull } from 'drizzle-orm';
+
+import { db, closeDb } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { berths } from '@/lib/db/schema/berths';
+import { documents, files } from '@/lib/db/schema/documents';
+import { clients } from '@/lib/db/schema/clients';
+import { interests } from '@/lib/db/schema/interests';
+import { migrationSourceLinks } from '@/lib/db/schema/migration';
+import { getStorageBackend } from '@/lib/storage';
+import { buildStoragePath } from '@/lib/minio';
+import { ensureEntityFolder } from '@/lib/services/document-folders.service';
+import { uploadBerthPdf } from '@/lib/services/berth-pdf.service';
+import { normalizeName } from '@/lib/dedup/normalize';
+import { SUPER_ADMIN_USER_ID } from '@/lib/db/seed-bootstrap';
+
+const DRY = process.argv.includes('--dry-run');
+const slugArg = (() => {
+  const i = process.argv.indexOf('--port-slug');
+  return i >= 0 ? (process.argv[i + 1] ?? 'port-nimara') : 'port-nimara';
+})();
+
+const LEGACY_BUCKET = process.env.LEGACY_MINIO_BUCKET ?? 'client-portal';
+// NocoDB's own attachment store — where pre-Documenso "LOI process" EOIs live.
+const DATABASE_BUCKET = process.env.LEGACY_MINIO_DATABASE_BUCKET ?? 'database';
+const legacy = new MinioClient({
+  endPoint: process.env.LEGACY_MINIO_ENDPOINT ?? 's3.portnimara.com',
+  port: 443,
+  useSSL: true,
+  accessKey: process.env.LEGACY_MINIO_ACCESS_KEY ?? '',
+  secretKey: process.env.LEGACY_MINIO_SECRET_KEY ?? '',
+});
+
+// Read-only connection to the LOCAL restored NocoDB dump (`nocodb_legacy`) —
+// used to read the `EOI_Document` attachment metadata. Never prod.
+const CRM_DB_URL = process.env.DATABASE_URL ?? '';
+const LEGACY_DB_URL = process.env.LEGACY_DB_URL ?? CRM_DB_URL.replace(/\/[^/]+$/, '/nocodb_legacy');
+
+/** Levenshtein edit distance — conservative fuzzy name matching for legacy
+ *  spelling/format drift (Koshbin↔Khoshbin, Costanzo↔Constanzo). */
+function lev(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (!m) return n;
+  if (!n) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  for (let i = 1; i <= m; i++) {
+    const cur = [i];
+    for (let j = 1; j <= n; j++) {
+      cur[j] = Math.min(
+        prev[j]! + 1,
+        cur[j - 1]! + 1,
+        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = cur;
+  }
+  return prev[n]!;
+}
+
+function streamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    stream.on('data', (c: Buffer) => chunks.push(c));
+    stream.on('end', () => resolve(Buffer.concat(chunks)));
+    stream.on('error', reject);
+  });
+}
+
+interface LegacyObject {
+  name: string;
+  size: number;
+}
+function listLegacy(prefix: string): Promise<LegacyObject[]> {
+  return new Promise((resolve, reject) => {
+    const out: LegacyObject[] = [];
+    const stream = legacy.listObjectsV2(LEGACY_BUCKET, prefix, true);
+    stream.on('data', (o) => {
+      if (o.name && !o.name.endsWith('/')) out.push({ name: o.name, size: o.size ?? 0 });
+    });
+    stream.on('end', () => resolve(out));
+    stream.on('error', reject);
+  });
+}
+
+async function resolvePort(slug: string): Promise<{ id: string; slug: string }> {
+  const [p] = await db
+    .select({ id: ports.id, slug: ports.slug })
+    .from(ports)
+    .where(eq(ports.slug, slug))
+    .limit(1);
+  if (!p) throw new Error(`No port with slug "${slug}"`);
+  return p;
+}
+
+// ─── Berth PDFs ──────────────────────────────────────────────────────────────
+// client-portal/Berth-PDFs/<ts>-Berth_Spec_Sheet_<Mooring>.pdf  → berth by mooring.
+async function backfillBerthPdfs(port: { id: string; slug: string }) {
+  const objs = (await listLegacy('Berth-PDFs/')).filter((o) => /\.pdf$/i.test(o.name));
+  const berthRows = await db
+    .select({ id: berths.id, mooring: berths.mooringNumber, cur: berths.currentPdfVersionId })
+    .from(berths)
+    .where(eq(berths.portId, port.id));
+  const byMooring = new Map(berthRows.map((b) => [b.mooring, b]));
+
+  let attached = 0;
+  let skipped = 0;
+  let unmatched = 0;
+  for (const o of objs) {
+    const m = o.name.match(/Berth_Spec_Sheet_([A-Za-z]+\d+)\.pdf$/i);
+    if (!m) {
+      unmatched++;
+      continue;
+    }
+    const mooring = `${m[1]!.replace(/[a-z]+/g, (s) => s.toUpperCase())}`
+      .toUpperCase()
+      .replace(/([A-Z]+)0*(\d+)/, '$1$2');
+    const berth = byMooring.get(mooring);
+    if (!berth) {
+      console.log(`  [berth] no berth for mooring "${mooring}" (${o.name})`);
+      unmatched++;
+      continue;
+    }
+    if (berth.cur) {
+      skipped++;
+      continue;
+    }
+    if (DRY) {
+      attached++;
+      continue;
+    }
+    const buf = await streamToBuffer(await legacy.getObject(LEGACY_BUCKET, o.name));
+    await uploadBerthPdf({
+      berthId: berth.id,
+      portId: port.id,
+      buffer: buf,
+      fileName: o.name.split('/').pop() ?? `${mooring}.pdf`,
+      uploadedBy: SUPER_ADMIN_USER_ID,
+    });
+    attached++;
+  }
+  return { total: objs.length, attached, skipped, unmatched };
+}
+
+// ─── Signed EOIs ─────────────────────────────────────────────────────────────
+// client-portal/EOIs/<Client Name>/<file>.pdf  → match by normalized client name.
+async function backfillEois(port: { id: string; slug: string }) {
+  // Signed EOIs live under EOIs/<Name>/ and (some) under Client Documents/<Name>/.
+  const objs = [...(await listLegacy('EOIs/')), ...(await listLegacy('Client Documents/'))].filter(
+    (o) => /\.pdf$/i.test(o.name) && /eoi|sign/i.test(o.name),
+  );
+  // Index the best signed PDF per normalized folder (client) name.
+  const byName = new Map<string, { key: string; size: number }>();
+  for (const o of objs) {
+    const parts = o.name.split('/'); // <prefix> / <Name> / <file>.pdf
+    if (parts.length < 3) continue;
+    const folder = (parts[1] ?? '').replace(/_/g, ' '); // "Matt_Ciaccio" → "Matt Ciaccio"
+    const norm = normalizeName(folder).display;
+    if (!norm) continue;
+    const isSigned = /sign/i.test(o.name);
+    const prev = byName.get(norm);
+    // Prefer a "signed" file; among those, the largest (the full signed PDF).
+    if (!prev || (isSigned && o.size > prev.size)) byName.set(norm, { key: o.name, size: o.size });
+  }
+
+  // Migrated EOI documents missing a signed file.
+  const docRows = await db
+    .select({ id: documents.id, interestId: documents.interestId, clientId: documents.clientId })
+    .from(documents)
+    .where(
+      and(
+        eq(documents.portId, port.id),
+        eq(documents.documentType, 'eoi'),
+        isNull(documents.signedFileId),
+      ),
+    );
+
+  const backend = await getStorageBackend();
+  let attached = 0;
+  let unmatched = 0;
+  const unresolved: string[] = [];
+  for (const doc of docRows) {
+    const clientId = doc.clientId;
+    if (!clientId) {
+      unmatched++;
+      continue;
+    }
+    const [c] = await db
+      .select({ name: clients.fullName })
+      .from(clients)
+      .where(eq(clients.id, clientId))
+      .limit(1);
+    if (!c) {
+      unmatched++;
+      continue;
+    }
+    const target = normalizeName(c.name).display;
+    let match = byName.get(target);
+    if (!match && target.length >= 6) {
+      // Conservative fuzzy fallback: best edit-distance ≤ 2 on the full name.
+      let bestDist = 3;
+      for (const [name, v] of byName) {
+        const d = lev(name, target);
+        if (d < bestDist) {
+          bestDist = d;
+          match = v;
+        }
+      }
+    }
+    if (!match) {
+      unresolved.push(c.name);
+      unmatched++;
+      continue;
+    }
+    if (DRY) {
+      attached++;
+      continue;
+    }
+    // Pull legacy bytes → write to CRM storage → files row → link signedFileId.
+    const buf = await streamToBuffer(await legacy.getObject(LEGACY_BUCKET, match.key));
+    const key = buildStoragePath(port.slug, 'eoi-signed', doc.id, randomUUID(), 'pdf');
+    const putRes = await backend.put(key, buf, {
+      contentType: 'application/pdf',
+      sizeBytes: buf.length,
+    });
+    // File into the client's entity folder (mirrors handleDocumentCompleted's
+    // owner-folder filing). files.interestId still scopes the row to the deal;
+    // interest "Deal" folders aren't system-managed (chk_system_folder_shape).
+    const folder = await ensureEntityFolder(port.id, 'client', clientId, SUPER_ADMIN_USER_ID);
+    const fileName = match.key.split('/').pop() ?? 'eoi-signed.pdf';
+    await db.transaction(async (tx) => {
+      const [f] = await tx
+        .insert(files)
+        .values({
+          portId: port.id,
+          filename: fileName,
+          originalName: fileName,
+          storagePath: putRes.key,
+          mimeType: 'application/pdf',
+          sizeBytes: String(putRes.sizeBytes),
+          category: 'eoi',
+          folderId: folder.id,
+          clientId,
+          interestId: doc.interestId,
+          uploadedBy: 'system',
+        })
+        .returning({ id: files.id });
+      if (!f) throw new Error('files insert returned no row');
+      await tx
+        .update(documents)
+        .set({ signedFileId: f.id, status: 'completed', isManualUpload: true })
+        .where(eq(documents.id, doc.id));
+    });
+    attached++;
+  }
+  return {
+    totalBlobs: objs.length,
+    indexedClients: byName.size,
+    candidates: docRows.length,
+    attached,
+    unmatched,
+    unresolved,
+  };
+}
+
+// ─── Old-LOI EOIs (NocoDB `database` bucket attachments) ─────────────────────
+// The ~10 pre-Documenso "LOI process" deals have no documensoID and no curated
+// client-portal/EOIs copy; their signed PDF lives only as a NocoDB attachment
+// in the `database` bucket. The main pipeline keys EOI-doc creation off
+// documensoID, so it never created a document row for them. Here we CREATE the
+// document + file + folder and link the recovered PDF. Idempotent via a
+// `nocodb_eoi_document` ledger entry per legacy interest.
+function legacyKeyFromUrl(url: string): string | null {
+  // https://<host>/database/nc/uploads/...  →  nc/uploads/...
+  const marker = `/${DATABASE_BUCKET}/`;
+  const i = url.indexOf(marker);
+  if (i < 0) return null;
+  return decodeURIComponent(url.slice(i + marker.length));
+}
+
+async function backfillOldLoiEois(
+  port: { id: string; slug: string },
+  legacyDb: ReturnType<typeof postgres>,
+) {
+  const rows = (await legacyDb`
+    select id, "EOI_Document"::text as doc
+    from plplouets5zw1um."Interests"
+    where "EOI_Document" is not null and "EOI_Document"::text not in ('', '[]', 'null')
+  `) as unknown as Array<{ id: number; doc: string }>;
+
+  const backend = await getStorageBackend();
+  let created = 0;
+  let skipped = 0;
+  let unmatched = 0;
+  const unresolved: string[] = [];
+
+  for (const r of rows) {
+    let url: string | null = null;
+    let title: string | null = null;
+    try {
+      const parsed = JSON.parse(r.doc) as unknown;
+      const first = Array.isArray(parsed) && parsed.length > 0 ? parsed[0] : null;
+      if (first && typeof first === 'object') {
+        const rec = first as Record<string, unknown>;
+        if (typeof rec.url === 'string') url = rec.url;
+        if (typeof rec.title === 'string') title = rec.title;
+      }
+    } catch {
+      // ignore malformed attachment JSON
+    }
+    const key = url ? legacyKeyFromUrl(url) : null;
+    if (!key) {
+      unmatched++;
+      continue;
+    }
+
+    // legacy interest id → migrated interest
+    const [link] = await db
+      .select({ interestId: migrationSourceLinks.targetEntityId })
+      .from(migrationSourceLinks)
+      .where(
+        and(
+          eq(migrationSourceLinks.sourceSystem, 'nocodb_interests'),
+          eq(migrationSourceLinks.sourceId, String(r.id)),
+          eq(migrationSourceLinks.targetEntityType, 'interest'),
+        ),
+      )
+      .limit(1);
+    if (!link) {
+      unresolved.push(`legacy#${r.id} (not a migrated interest)`);
+      unmatched++;
+      continue;
+    }
+    const interestId = link.interestId;
+
+    // Idempotency: skip if this attachment was already recovered.
+    const [already] = await db
+      .select({ id: migrationSourceLinks.id })
+      .from(migrationSourceLinks)
+      .where(
+        and(
+          eq(migrationSourceLinks.sourceSystem, 'nocodb_eoi_document'),
+          eq(migrationSourceLinks.sourceId, String(r.id)),
+          eq(migrationSourceLinks.targetEntityType, 'document'),
+        ),
+      )
+      .limit(1);
+    if (already) {
+      skipped++;
+      continue;
+    }
+
+    const [intRow] = await db
+      .select({ clientId: interests.clientId, yachtId: interests.yachtId })
+      .from(interests)
+      .where(eq(interests.id, interestId))
+      .limit(1);
+    if (!intRow?.clientId) {
+      unmatched++;
+      continue;
+    }
+    const clientId = intRow.clientId;
+
+    if (DRY) {
+      created++;
+      continue;
+    }
+
+    const buf = await streamToBuffer(await legacy.getObject(DATABASE_BUCKET, key));
+    const docId = randomUUID();
+    const storageKey = buildStoragePath(port.slug, 'eoi-signed', docId, randomUUID(), 'pdf');
+    const putRes = await backend.put(storageKey, buf, {
+      contentType: 'application/pdf',
+      sizeBytes: buf.length,
+    });
+    const folder = await ensureEntityFolder(port.id, 'client', clientId, SUPER_ADMIN_USER_ID);
+    const fileName = title || key.split('/').pop() || 'eoi-signed.pdf';
+
+    await db.transaction(async (tx) => {
+      const [f] = await tx
+        .insert(files)
+        .values({
+          portId: port.id,
+          filename: fileName,
+          originalName: fileName,
+          storagePath: putRes.key,
+          mimeType: 'application/pdf',
+          sizeBytes: String(putRes.sizeBytes),
+          category: 'eoi',
+          folderId: folder.id,
+          clientId,
+          interestId,
+          uploadedBy: 'system',
+        })
+        .returning({ id: files.id });
+      if (!f) throw new Error('files insert returned no row');
+
+      await tx.insert(documents).values({
+        id: docId,
+        portId: port.id,
+        interestId,
+        clientId,
+        yachtId: intRow.yachtId ?? null,
+        documentType: 'eoi',
+        title: `External EOI (legacy) - ${fileName}`,
+        status: 'completed',
+        isManualUpload: true,
+        signedFileId: f.id,
+        createdBy: SUPER_ADMIN_USER_ID,
+      });
+
+      await tx
+        .update(interests)
+        .set({ eoiDocStatus: 'signed', updatedAt: new Date() })
+        .where(eq(interests.id, interestId));
+
+      await tx.insert(migrationSourceLinks).values({
+        sourceSystem: 'nocodb_eoi_document',
+        sourceId: String(r.id),
+        targetEntityType: 'document',
+        targetEntityId: docId,
+        appliedId: `oldloi-${docId}`,
+        appliedBy: SUPER_ADMIN_USER_ID,
+      });
+    });
+    created++;
+  }
+  return { total: rows.length, created, skipped, unmatched, unresolved };
+}
+
+async function main() {
+  if (!process.env.LEGACY_MINIO_ACCESS_KEY || !process.env.LEGACY_MINIO_SECRET_KEY) {
+    console.error(
+      'Set LEGACY_MINIO_ACCESS_KEY + LEGACY_MINIO_SECRET_KEY (legacy MinIO read creds).',
+    );
+    process.exit(1);
+  }
+  const port = await resolvePort(slugArg);
+  console.log(
+    `[backfill] port=${port.slug} legacy-bucket=${LEGACY_BUCKET} ${DRY ? '(DRY RUN)' : ''}`,
+  );
+
+  console.log('[backfill] Berth PDFs…');
+  const berthRes = await backfillBerthPdfs(port);
+  console.log(
+    `  berth PDFs: ${berthRes.total} blobs → ${berthRes.attached} attached, ${berthRes.skipped} already had one, ${berthRes.unmatched} unmatched`,
+  );
+
+  console.log('[backfill] Signed EOIs…');
+  const eoiRes = await backfillEois(port);
+  console.log(
+    `  EOIs: ${eoiRes.totalBlobs} blobs (${eoiRes.indexedClients} client folders) · ${eoiRes.candidates} migrated EOI docs needing a file → ${eoiRes.attached} attached, ${eoiRes.unmatched} unmatched`,
+  );
+  if (eoiRes.unresolved.length > 0) {
+    console.log(`  ⚠ EOI docs with no name-matched legacy PDF (${eoiRes.unresolved.length}):`);
+    for (const n of eoiRes.unresolved.slice(0, 25)) console.log(`     - ${n}`);
+  }
+
+  console.log('[backfill] Old-LOI EOIs (NocoDB `database` bucket)…');
+  const legacyDb = postgres(LEGACY_DB_URL, { max: 2 });
+  try {
+    const loiRes = await backfillOldLoiEois(port, legacyDb);
+    console.log(
+      `  old-LOI EOIs: ${loiRes.total} attachments → ${loiRes.created} created, ${loiRes.skipped} already done, ${loiRes.unmatched} unmatched`,
+    );
+    if (loiRes.unresolved.length > 0) {
+      for (const n of loiRes.unresolved.slice(0, 25)) console.log(`     - ${n}`);
+    }
+  } finally {
+    await legacyDb.end().catch(() => {});
+  }
+
+  await closeDb();
+  process.exit(0);
+}
+
+main().catch(async (err) => {
+  console.error('[backfill] failed:', err);
+  await closeDb().catch(() => {});
+  process.exit(1);
+});

scripts/migration/connect-berth-links.ts

@@ -0,0 +1,175 @@
+/**
+ * Fix-up: connect the multi-berth links the main dedup pipeline misses.
+ *
+ * The dedup pipeline migrates only each interest's single `Berth Number` text
+ * field; the legacy `_nc_m2m_Berths_Interests` junction (multi-berth deals) is
+ * not carried over by it. This reads that junction from the `nocodb_legacy`
+ * snapshot, resolves each legacy interest → its migrated interest (via the
+ * ledger) and each mooring → the migrated berth, and inserts the missing
+ * `interest_berths` rows.
+ *
+ * Idempotent: `ON CONFLICT (interest_id, berth_id) DO NOTHING`. Primary safety:
+ * only makes a berth primary when the interest has no primary yet (≤1 primary
+ * per interest is a partial unique index).
+ *
+ * Exposed as `connectBerthLinks(...)` so `migrate-from-nocodb.ts --apply` can
+ * fold it into the one-shot seed; also runnable standalone:
+ *
+ *   pnpm tsx scripts/migration/connect-berth-links.ts [--port-slug port-nimara] [--dry-run]
+ */
+import 'dotenv/config';
+import { randomUUID } from 'node:crypto';
+import postgres from 'postgres';
+
+const canonMoo = (raw: string): string => {
+  const m = /^([A-Za-z]+)-?0*(\d+)$/.exec((raw ?? '').trim());
+  return m ? `${m[1]!.toUpperCase()}${parseInt(m[2]!, 10)}` : (raw ?? '').trim();
+};
+
+export interface ConnectBerthLinksResult {
+  inserted: number;
+  madePrimary: number;
+  skipped: number;
+  unresolved: string[];
+}
+
+/**
+ * Self-contained: opens its own CRM + legacy connections (read-only on the
+ * legacy snapshot), does the work, closes them, returns stats. Safe to call
+ * from the runner or standalone.
+ */
+export async function connectBerthLinks(opts: {
+  portSlug?: string;
+  dryRun?: boolean;
+}): Promise<ConnectBerthLinksResult> {
+  const slug = opts.portSlug ?? 'port-nimara';
+  const dry = opts.dryRun ?? false;
+
+  const CRM_URL = process.env.DATABASE_URL!;
+  const LEGACY_URL = process.env.LEGACY_DB_URL ?? CRM_URL.replace(/\/[^/]+$/, '/nocodb_legacy');
+  const crm = postgres(CRM_URL, { max: 4 });
+  const legacy = postgres(LEGACY_URL, { max: 4 });
+
+  try {
+    const [port] = await crm`select id from ports where slug=${slug} limit 1`;
+    if (!port) throw new Error(`no port ${slug}`);
+    const portId = port.id as string;
+
+    // legacy junction: interestId → set(moorings)
+    const mooById = new Map<number, string>();
+    for (const b of await legacy`select id, "Mooring_Number" m from plplouets5zw1um."Berths"`)
+      mooById.set(b.id as number, canonMoo(b.m as string));
+    const legacyMoo = new Map<number, Set<string>>();
+    for (const j of await legacy`select "Interests_id" i, "Berths_id" b from plplouets5zw1um."_nc_m2m_Berths_Interests"`) {
+      const set = legacyMoo.get(j.i as number) ?? new Set<string>();
+      const m = mooById.get(j.b as number);
+      if (m) set.add(m);
+      legacyMoo.set(j.i as number, set);
+    }
+    // EOI-signed flag per legacy interest (for is_in_eoi_bundle)
+    const signed = new Set<number>();
+    for (const r of await legacy`select id, "EOI_Status" e, "LOI_NDA_Document" l from plplouets5zw1um."Interests"`) {
+      const e = ((r.e as string) ?? '').trim();
+      const l = ((r.l as string) ?? '').trim();
+      if (
+        e === 'Signed' ||
+        ['Signing Complete', 'Signed by Client', 'Signed by Developer'].includes(l)
+      )
+        signed.add(r.id as number);
+    }
+
+    // ledger: legacy interest id → new interest id
+    const links =
+      await crm`select source_id, target_entity_id from migration_source_links where source_system='nocodb_interests' and target_entity_type='interest'`;
+    const newInterestBySrc = new Map(
+      links.map((l) => [Number(l.source_id), l.target_entity_id as string]),
+    );
+
+    // CRM berth id by mooring (this port)
+    const berthByMoo = new Map(
+      (await crm`select id, mooring_number m from berths where port_id=${portId}`).map((b) => [
+        b.m as string,
+        b.id as string,
+      ]),
+    );
+
+    let inserted = 0;
+    let madePrimary = 0;
+    let skipped = 0;
+    const unresolved: string[] = [];
+
+    for (const [legacyId, moorings] of legacyMoo) {
+      const interestId = newInterestBySrc.get(legacyId);
+      if (!interestId) continue; // not a migrated interest (backup/copy tables)
+      const primaryCheck =
+        await crm`select exists(select 1 from interest_berths where interest_id=${interestId} and is_primary) as has`;
+      let hasPrimary = (primaryCheck[0]?.has as boolean | undefined) ?? false;
+
+      for (const moo of moorings) {
+        const berthId = berthByMoo.get(moo);
+        if (!berthId) {
+          unresolved.push(`${legacyId}:${moo}`);
+          continue;
+        }
+        const makePrimary = !hasPrimary;
+        if (dry) {
+          inserted++;
+          if (makePrimary) {
+            madePrimary++;
+            hasPrimary = true;
+          }
+          continue;
+        }
+        const res = await crm`
+          insert into interest_berths (id, interest_id, berth_id, is_primary, is_specific_interest, is_in_eoi_bundle)
+          values (${randomUUID()}, ${interestId}, ${berthId}, ${makePrimary}, true, ${signed.has(legacyId)})
+          on conflict (interest_id, berth_id) do nothing
+          returning id`;
+        if (res.length > 0) {
+          inserted++;
+          if (makePrimary) {
+            madePrimary++;
+            hasPrimary = true;
+          }
+        } else {
+          skipped++;
+        }
+      }
+    }
+
+    return { inserted, madePrimary, skipped, unresolved };
+  } finally {
+    await crm.end().catch(() => {});
+    await legacy.end().catch(() => {});
+  }
+}
+
+// ─── Standalone CLI ──────────────────────────────────────────────────────────
+function isMain(): boolean {
+  const arg = process.argv[1] ?? '';
+  return arg.includes('connect-berth-links');
+}
+
+if (isMain()) {
+  const slugArg = (() => {
+    const i = process.argv.indexOf('--port-slug');
+    return i >= 0 ? (process.argv[i + 1] ?? 'port-nimara') : 'port-nimara';
+  })();
+  const dry = process.argv.includes('--dry-run');
+
+  connectBerthLinks({ portSlug: slugArg, dryRun: dry })
+    .then((r) => {
+      console.log(
+        `connect-berth-links ${dry ? '(DRY)' : ''}: inserted ${r.inserted} links (${r.madePrimary} new primary), ${r.skipped} already linked`,
+      );
+      if (r.unresolved.length)
+        console.log(
+          `  ⚠ ${r.unresolved.length} moorings with no CRM berth: ${r.unresolved.slice(0, 20).join(', ')}`,
+        );
+      process.exit(0);
+    })
+    .catch((e) => {
+      console.error('connect-berth-links failed:', e);
+      process.exit(1);
+    });
+}

scripts/migration/probe-minio.ts

@@ -0,0 +1,102 @@
+/**
+ * Read-only MinIO inventory for the legacy → new-CRM migration (Phase 2 sizing).
+ *
+ * Lists every bucket the creds can see, then for the document buckets
+ * (`client-portal`, `signatures`) groups objects by top-level prefix with
+ * counts + sizes + samples — so we can see exactly where the EOIs, berth
+ * PDFs, receipts and business-card images live before backfilling them.
+ *
+ * Secret-free: reads creds from env. Run with:
+ *   MINIO_ACCESS_KEY=... MINIO_SECRET_KEY=... \
+ *   pnpm tsx scripts/migration/probe-minio.ts
+ *
+ * Strictly read-only (listBuckets + listObjectsV2). No writes.
+ */
+import { Client } from 'minio';
+
+const endPoint = process.env.MINIO_ENDPOINT || 's3.portnimara.com';
+const accessKey = process.env.MINIO_ACCESS_KEY;
+const secretKey = process.env.MINIO_SECRET_KEY;
+
+if (!accessKey || !secretKey) {
+  console.error('Set MINIO_ACCESS_KEY and MINIO_SECRET_KEY');
+  process.exit(1);
+}
+
+const client = new Client({ endPoint, port: 443, useSSL: true, accessKey, secretKey });
+
+interface PrefixStat {
+  count: number;
+  bytes: number;
+  samples: string[];
+}
+
+async function inventory(bucket: string) {
+  const byPrefix = new Map<string, PrefixStat>();
+  let total = 0;
+  let totalBytes = 0;
+  await new Promise<void>((resolve, reject) => {
+    const stream = client.listObjectsV2(bucket, '', true);
+    stream.on('data', (o) => {
+      if (!o.name) return;
+      total++;
+      totalBytes += o.size || 0;
+      const top = o.name.includes('/') ? o.name.split('/')[0] + '/' : '(root)';
+      const e = byPrefix.get(top) || { count: 0, bytes: 0, samples: [] };
+      e.count++;
+      e.bytes += o.size || 0;
+      if (e.samples.length < 4) e.samples.push(`${o.name}  (${o.size}b)`);
+      byPrefix.set(top, e);
+    });
+    stream.on('end', () => resolve());
+    stream.on('error', reject);
+  });
+  return { bucket, total, totalBytes, byPrefix };
+}
+
+const mb = (b: number) => (b / 1e6).toFixed(1);
+
+async function main() {
+  console.log(`MinIO @ ${endPoint}\n`);
+
+  let buckets: string[] = [];
+  try {
+    const list = await client.listBuckets();
+    buckets = list.map((b) => b.name);
+    console.log('=== all buckets visible to these creds ===');
+    for (const b of list) console.log(`  ${b.name}`);
+  } catch (err) {
+    console.log(`listBuckets failed: ${(err as Error).message}`);
+  }
+
+  const targets = (process.env.MINIO_BUCKETS || 'client-portal,signatures')
+    .split(',')
+    .map((s) => s.trim());
+
+  for (const bucket of targets) {
+    if (buckets.length && !buckets.includes(bucket)) {
+      console.log(`\n=== bucket: ${bucket} — NOT VISIBLE to these creds ===`);
+      continue;
+    }
+    try {
+      const inv = await inventory(bucket);
+      console.log(
+        `\n=== bucket: ${inv.bucket} — ${inv.total} objects, ${mb(inv.totalBytes)} MB ===`,
+      );
+      const rows = [...inv.byPrefix.entries()].sort((a, z) => z[1].count - a[1].count);
+      for (const [prefix, e] of rows) {
+        console.log(
+          `  ${prefix.padEnd(30)} ${String(e.count).padStart(5)} obj  ${mb(e.bytes).padStart(8)} MB`,
+        );
+        for (const s of e.samples) console.log(`        e.g. ${s}`);
+      }
+    } catch (err) {
+      console.log(`\n=== bucket: ${bucket} — ERROR: ${(err as Error).message} ===`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('probe-minio failed:', err);
+  process.exit(1);
+});

scripts/migration/reconcile-migration.ts

@@ -0,0 +1,277 @@
+/**
+ * Exhaustive migration reconciliation (read-only): cross-checks EVERY migrated
+ * record against its legacy NocoDB source row (via the migration ledger) and
+ * verifies every relationship is connected. Independently re-derives the
+ * expected mapped values (stage, eoiStatus, berth, …) so it validates the
+ * migration logic, not just echoes it.
+ *
+ * Connects to BOTH local DBs:
+ *   - CRM      : DATABASE_URL (the migrated data)
+ *   - legacy   : LEGACY_DB_URL (the nocodb_legacy snapshot); defaults to the
+ *                CRM url with the db name swapped to `nocodb_legacy`.
+ *
+ *   pnpm tsx scripts/migration/reconcile-migration.ts [--port-slug port-nimara]
+ */
+import 'dotenv/config';
+import postgres from 'postgres';
+
+const slugArg = (() => {
+  const i = process.argv.indexOf('--port-slug');
+  return i >= 0 ? (process.argv[i + 1] ?? 'port-nimara') : 'port-nimara';
+})();
+
+const CRM_URL = process.env.DATABASE_URL!;
+const LEGACY_URL = process.env.LEGACY_DB_URL ?? CRM_URL.replace(/\/[^/]+$/, '/nocodb_legacy');
+const crm = postgres(CRM_URL, { max: 4 });
+const legacy = postgres(LEGACY_URL, { max: 4 });
+
+// ── transforms, re-implemented independently (cross-validation) ──────────────
+const STAGE_MAP: Record<string, string> = {
+  'General Qualified Interest': 'qualified',
+  'Specific Qualified Interest': 'nurturing',
+  'EOI and NDA Sent': 'eoi',
+  'Signed EOI and NDA': 'eoi',
+  'Made Reservation': 'reservation',
+  'Contract Negotiation': 'contract',
+  'Contract Negotiations Finalized': 'contract',
+  'Contract Signed': 'contract',
+};
+const expectStage = (level: string | undefined, deposit: string | undefined): string => {
+  let s = STAGE_MAP[(level ?? '').trim()] ?? 'enquiry';
+  if ((deposit ?? '').trim() === 'Received' && s !== 'contract') s = 'deposit_paid';
+  return s;
+};
+const expectEoi = (
+  eoiStatus: string | undefined,
+  loi: string | undefined,
+  documensoId: string | undefined,
+): string | null => {
+  const e = (eoiStatus ?? '').trim();
+  const l = (loi ?? '').trim();
+  if (e === 'Signed' || ['Signing Complete', 'Signed by Client', 'Signed by Developer'].includes(l))
+    return 'signed';
+  if (e === 'Waiting for Signatures' || (documensoId ?? '').trim()) return 'waiting_for_signatures';
+  return null;
+};
+const canonMoo = (raw: string): string => {
+  const m = /^([A-Za-z]+)-?0*(\d+)$/.exec((raw ?? '').trim());
+  return m ? `${m[1]!.toUpperCase()}${parseInt(m[2]!, 10)}` : (raw ?? '').trim();
+};
+const normEmail = (e: string) => (e ?? '').trim().toLowerCase();
+
+const issues: string[] = [];
+const add = (cat: string, msg: string) => issues.push(`[${cat}] ${msg}`);
+
+async function main() {
+  const [port] = await crm`select id, slug from ports where slug=${slugArg} limit 1`;
+  if (!port) throw new Error(`no port ${slugArg}`);
+  const portId = port.id as string;
+
+  // ── load legacy source (by id) ───────────────────────────────────────────
+  const legacyInterests = new Map<number, Record<string, unknown>>();
+  for (const r of await legacy`select * from plplouets5zw1um."Interests"`)
+    legacyInterests.set(r.id as number, r);
+  const legacyExpenses = new Map<number, Record<string, unknown>>();
+  for (const r of await legacy`select * from p3hq2fxdevqcaq8."Expenses"`)
+    legacyExpenses.set(r.id as number, r);
+  const legacyRes = new Map<number, Record<string, unknown>>();
+  for (const r of await legacy`select * from plplouets5zw1um."Interests (Residences)"`)
+    legacyRes.set(r.id as number, r);
+  // legacy berth links per interest (Interests_id -> [mooring])
+  const berthMooById = new Map<number, string>();
+  for (const b of await legacy`select id, "Mooring_Number" m from plplouets5zw1um."Berths"`)
+    berthMooById.set(b.id as number, b.m as string);
+  const legacyBerthsByInterest = new Map<number, string[]>();
+  for (const j of await legacy`select "Interests_id" i, "Berths_id" b from plplouets5zw1um."_nc_m2m_Berths_Interests"`) {
+    const arr = legacyBerthsByInterest.get(j.i as number) ?? [];
+    const moo = berthMooById.get(j.b as number);
+    if (moo) arr.push(canonMoo(moo));
+    legacyBerthsByInterest.set(j.i as number, arr);
+  }
+
+  // ── ledger ────────────────────────────────────────────────────────────────
+  const ledger =
+    await crm`select source_system, source_id, target_entity_type, target_entity_id from migration_source_links`;
+  const interestLinks = ledger.filter((l) => l.target_entity_type === 'interest'); // sourceId(legacy interest) -> new interest
+  const expenseLinks = ledger.filter((l) => l.target_entity_type === 'expense');
+  const resLinks = ledger.filter((l) => l.target_entity_type === 'residential_client');
+  const clientLinks = ledger.filter((l) => l.target_entity_type === 'client');
+
+  // ── 1. COVERAGE — every legacy row migrated; nothing dropped ──────────────
+  const migratedInterestSrc = new Set(interestLinks.map((l) => Number(l.source_id)));
+  const droppedInterests = [...legacyInterests.keys()].filter((id) => !migratedInterestSrc.has(id));
+  const migratedExpSrc = new Set(expenseLinks.map((l) => Number(l.source_id)));
+  const droppedExp = [...legacyExpenses.keys()].filter((id) => !migratedExpSrc.has(id));
+  const migratedResSrc = new Set(resLinks.map((l) => Number(l.source_id)));
+  const droppedRes = [...legacyRes.keys()].filter((id) => !migratedResSrc.has(id));
+  for (const id of droppedInterests)
+    add(
+      'COVERAGE',
+      `legacy interest #${id} NOT migrated (${(legacyInterests.get(id) as { Full_Name?: string }).Full_Name ?? '?'})`,
+    );
+  for (const id of droppedExp) add('COVERAGE', `legacy expense #${id} NOT migrated`);
+  for (const id of droppedRes) add('COVERAGE', `legacy residential #${id} NOT migrated`);
+
+  // ── 2. INTEREST field fidelity (every migrated deal vs legacy) ────────────
+  const newInterests = await crm`
+    select i.id, i.pipeline_stage, i.lead_category, i.source, i.eoi_status, i.documenso_id, i.client_id, i.yacht_id
+    from interests i where i.port_id=${portId}`;
+  const newInterestById = new Map(newInterests.map((i) => [i.id as string, i]));
+  // berths per new interest
+  const ibRows = await crm`
+    select ib.interest_id, b.mooring_number from interest_berths ib join berths b on b.id=ib.berth_id where b.port_id=${portId}`;
+  const newBerthsByInterest = new Map<string, string[]>();
+  for (const r of ibRows) {
+    const a = newBerthsByInterest.get(r.interest_id as string) ?? [];
+    a.push(r.mooring_number as string);
+    newBerthsByInterest.set(r.interest_id as string, a);
+  }
+  let stageMiss = 0,
+    eoiMiss = 0,
+    docMiss = 0,
+    berthMiss = 0;
+  for (const l of interestLinks) {
+    const legacyRow = legacyInterests.get(Number(l.source_id));
+    const ni = newInterestById.get(l.target_entity_id as string);
+    if (!legacyRow || !ni) {
+      add(
+        'INTEGRITY',
+        `interest link sourceId=${l.source_id} → ${l.target_entity_id}: ${!legacyRow ? 'legacy row missing' : 'new interest missing'}`,
+      );
+      continue;
+    }
+    const lr = legacyRow as Record<string, string>;
+    const exp = expectStage(lr.Sales_Process_Level, lr.Deposit_10__Status);
+    if (ni.pipeline_stage !== exp) {
+      stageMiss++;
+      add(
+        'STAGE',
+        `interest src#${l.source_id} (${lr.Full_Name}): legacy "${lr.Sales_Process_Level}" → expected ${exp}, got ${ni.pipeline_stage}`,
+      );
+    }
+    const expEoi = expectEoi(lr.EOI_Status, lr.LOI_NDA_Document, lr.documensoID);
+    if ((ni.eoi_status ?? null) !== expEoi) {
+      eoiMiss++;
+      add(
+        'EOI',
+        `interest src#${l.source_id} (${lr.Full_Name}): expected eoiStatus ${expEoi}, got ${ni.eoi_status}`,
+      );
+    }
+    if ((ni.documenso_id ?? null) !== ((lr.documensoID ?? '').trim() || null)) {
+      docMiss++;
+      add(
+        'DOCID',
+        `interest src#${l.source_id} (${lr.Full_Name}): documensoId legacy="${lr.documensoID}" vs new="${ni.documenso_id}"`,
+      );
+    }
+    // berth: every legacy-linked mooring should be present on the new interest
+    const legacyMoo = new Set([...(legacyBerthsByInterest.get(Number(l.source_id)) ?? [])]);
+    if (lr.Berth_Number && /^[A-Za-z]+-?0*\d+$/.test(lr.Berth_Number.trim()))
+      legacyMoo.add(canonMoo(lr.Berth_Number));
+    const newMoo = new Set(newBerthsByInterest.get(ni.id as string) ?? []);
+    const missingBerths = [...legacyMoo].filter((m) => !newMoo.has(m));
+    if (missingBerths.length > 0) {
+      berthMiss++;
+      add(
+        'BERTH',
+        `interest src#${l.source_id} (${lr.Full_Name}): legacy berths [${[...legacyMoo].join(',')}] but new has [${[...newMoo].join(',') || '-'}] (missing ${missingBerths.join(',')})`,
+      );
+    }
+  }
+
+  // ── 3. CLIENT contact fidelity (migrated email is from a legacy source row)
+  const clientContacts = await crm`
+    select c.id, c.full_name, string_agg(cc.value, '|') filter (where cc.channel='email') emails
+    from clients c left join client_contacts cc on cc.client_id=c.id
+    where c.port_id=${portId} group by c.id, c.full_name`;
+  const emailsByClient = new Map(
+    clientContacts.map((c) => [
+      c.id as string,
+      (c.emails as string | null)?.split('|').map(normEmail) ?? [],
+    ]),
+  );
+  // group ledger client links: client -> its legacy source emails
+  const legacyEmailsByClient = new Map<string, Set<string>>();
+  for (const l of clientLinks) {
+    const lr = legacyInterests.get(Number(l.source_id)) as Record<string, string> | undefined;
+    const e = normEmail(lr?.Email_Address ?? '');
+    if (!e) continue;
+    const set = legacyEmailsByClient.get(l.target_entity_id as string) ?? new Set();
+    set.add(e);
+    legacyEmailsByClient.set(l.target_entity_id as string, set);
+  }
+  let emailMiss = 0;
+  for (const [cid, legacyEmails] of legacyEmailsByClient) {
+    const newEmails = new Set(emailsByClient.get(cid) ?? []);
+    const missing = [...legacyEmails].filter((e) => !newEmails.has(e));
+    if (missing.length > 0) {
+      emailMiss++;
+      const nm = clientContacts.find((c) => c.id === cid)?.full_name;
+      add(
+        'EMAIL',
+        `client ${nm}: legacy email(s) [${[...legacyEmails].join(',')}] not all on client (have [${[...newEmails].join(',') || '-'}])`,
+      );
+    }
+  }
+
+  // ── 4. RELATIONSHIP integrity (orphans / dangling FKs) ────────────────────
+  const orphanInterests =
+    await crm`select count(*) n from interests i where i.port_id=${portId} and not exists (select 1 from clients c where c.id=i.client_id)`;
+  const orphanIB =
+    await crm`select count(*) n from interest_berths ib where not exists (select 1 from interests i where i.id=ib.interest_id) or not exists (select 1 from berths b where b.id=ib.berth_id)`;
+  const orphanDocs =
+    await crm`select count(*) n from documents d where d.port_id=${portId} and d.interest_id is not null and not exists (select 1 from interests i where i.id=d.interest_id)`;
+  const orphanYachts =
+    await crm`select count(*) n from yachts y where y.port_id=${portId} and y.current_owner_type='client' and not exists (select 1 from clients c where c.id=y.current_owner_id)`;
+  const danglingSignedFile =
+    await crm`select count(*) n from documents d where d.signed_file_id is not null and not exists (select 1 from files f where f.id=d.signed_file_id)`;
+  if (Number(orphanInterests[0]!.n) > 0)
+    add('INTEGRITY', `${orphanInterests[0]!.n} interests with no client`);
+  if (Number(orphanIB[0]!.n) > 0)
+    add('INTEGRITY', `${orphanIB[0]!.n} interest_berths with dangling FK`);
+  if (Number(orphanDocs[0]!.n) > 0)
+    add('INTEGRITY', `${orphanDocs[0]!.n} documents with dangling interest`);
+  if (Number(orphanYachts[0]!.n) > 0)
+    add('INTEGRITY', `${orphanYachts[0]!.n} yachts with missing owner`);
+  if (Number(danglingSignedFile[0]!.n) > 0)
+    add('INTEGRITY', `${danglingSignedFile[0]!.n} documents with dangling signed_file_id`);
+
+  // ── report ────────────────────────────────────────────────────────────────
+  console.log('═══════════ MIGRATION RECONCILIATION ═══════════\n');
+  console.log(
+    `Coverage:  legacy interests ${legacyInterests.size} → migrated ${migratedInterestSrc.size} (dropped ${droppedInterests.length})`,
+  );
+  console.log(
+    `           legacy expenses ${legacyExpenses.size} → migrated ${migratedExpSrc.size} (dropped ${droppedExp.length})`,
+  );
+  console.log(
+    `           legacy residential ${legacyRes.size} → migrated ${migratedResSrc.size} (dropped ${droppedRes.length})`,
+  );
+  console.log(
+    `Fidelity:  stage mismatches ${stageMiss} · eoiStatus ${eoiMiss} · documensoId ${docMiss} · berth-link ${berthMiss} · client-email ${emailMiss}`,
+  );
+  console.log(
+    `Integrity: orphan interests ${orphanInterests[0]!.n} · interest_berths ${orphanIB[0]!.n} · docs ${orphanDocs[0]!.n} · yachts ${orphanYachts[0]!.n} · signed-file ${danglingSignedFile[0]!.n}`,
+  );
+  console.log(`\nTotal discrepancies: ${issues.length}`);
+  const byCat = issues.reduce<Record<string, number>>((a, s) => {
+    const c = s.slice(1, s.indexOf(']'));
+    a[c] = (a[c] || 0) + 1;
+    return a;
+  }, {});
+  console.log('By category:', JSON.stringify(byCat));
+  console.log('\n── discrepancy detail (first 60) ──');
+  for (const i of issues.slice(0, 60)) console.log('  ' + i);
+  if (issues.length > 60) console.log(`  … +${issues.length - 60} more`);
+
+  await crm.end();
+  await legacy.end();
+  process.exit(0);
+}
+
+main().catch(async (e) => {
+  console.error('reconcile failed:', e);
+  await crm.end().catch(() => {});
+  await legacy.end().catch(() => {});
+  process.exit(1);
+});

scripts/migration/verify-migration.ts

@@ -0,0 +1,210 @@
+/**
+ * Migration verification / audit (read-only against the local dev DB + storage).
+ *
+ *  1. EOI PDF ↔ person: opens each attached signed-EOI PDF, extracts its text,
+ *     and confirms the linked client's name actually appears inside — catching
+ *     any wrong attachment from the name/fuzzy matcher. Flags any PDF where a
+ *     *different* client's name appears instead.
+ *  2. Berth PDF ↔ mooring: confirms each berth's spec-sheet PDF mentions its
+ *     mooring number.
+ *  3. Per-person completeness: clients missing contact info, deals missing a
+ *     stage, clients with no deal, + a sample full dump to eyeball.
+ *
+ *   pnpm tsx scripts/migration/verify-migration.ts [--port-slug port-nimara]
+ */
+import 'dotenv/config';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { extractText, getDocumentProxy } from 'unpdf';
+import { and, eq, isNotNull, sql } from 'drizzle-orm';
+
+import { db, closeDb } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { documents, files } from '@/lib/db/schema/documents';
+import { clients } from '@/lib/db/schema/clients';
+import { berths, berthPdfVersions } from '@/lib/db/schema/berths';
+
+const STORAGE_ROOT = process.env.STORAGE_ROOT || 'storage';
+const slugArg = (() => {
+  const i = process.argv.indexOf('--port-slug');
+  return i >= 0 ? (process.argv[i + 1] ?? 'port-nimara') : 'port-nimara';
+})();
+
+const norm = (s: string) =>
+  s
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[^a-z ]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+async function pdfText(storagePath: string): Promise<string> {
+  const buf = await readFile(path.join(STORAGE_ROOT, storagePath));
+  const pdf = await getDocumentProxy(new Uint8Array(buf));
+  const res = await extractText(pdf, { mergePages: true });
+  const t = Array.isArray(res.text) ? res.text.join(' ') : res.text;
+  return norm(t);
+}
+
+async function main() {
+  const [port] = await db
+    .select({ id: ports.id, slug: ports.slug })
+    .from(ports)
+    .where(eq(ports.slug, slugArg))
+    .limit(1);
+  if (!port) throw new Error(`no port ${slugArg}`);
+
+  const allNames = (
+    await db
+      .select({ id: clients.id, name: clients.fullName })
+      .from(clients)
+      .where(eq(clients.portId, port.id))
+  ).map((c) => ({
+    id: c.id,
+    tokens: norm(c.name)
+      .split(' ')
+      .filter((t) => t.length >= 4),
+    name: c.name,
+  }));
+
+  // ── 1. EOI PDF ↔ person ──────────────────────────────────────────────────
+  const eoiRows = await db
+    .select({
+      docId: documents.id,
+      clientId: documents.clientId,
+      fullName: clients.fullName,
+      storagePath: files.storagePath,
+    })
+    .from(documents)
+    .innerJoin(files, eq(files.id, documents.signedFileId))
+    .innerJoin(clients, eq(clients.id, documents.clientId))
+    .where(
+      and(
+        eq(documents.portId, port.id),
+        eq(documents.documentType, 'eoi'),
+        isNotNull(documents.signedFileId),
+      ),
+    );
+
+  console.log(`\n═══ 1. EOI PDF ↔ person (${eoiRows.length} attached signed EOIs) ═══`);
+  let ok = 0,
+    weak = 0,
+    bad = 0,
+    err = 0;
+  for (const r of eoiRows) {
+    try {
+      const text = await pdfText(r.storagePath);
+      const tokens = norm(r.fullName)
+        .split(' ')
+        .filter((t) => t.length >= 3);
+      const first = tokens[0];
+      const last = tokens[tokens.length - 1];
+      const hasFirst = !!first && text.includes(first);
+      const hasLast = !!last && text.includes(last);
+      if (hasFirst && hasLast) {
+        ok++;
+      } else if (hasFirst || hasLast) {
+        weak++;
+        console.log(
+          `  ⚠ WEAK  "${r.fullName}" — only ${hasLast ? 'surname' : 'first name'} found in its PDF`,
+        );
+      } else {
+        bad++;
+        const other = allNames.find(
+          (c) => c.id !== r.clientId && c.tokens.some((t) => text.includes(t)),
+        );
+        console.log(
+          `  ✗ BAD   "${r.fullName}" — name NOT in its PDF${other ? ` — but "${other.name}" DOES appear (likely mis-attached!)` : ''}`,
+        );
+      }
+    } catch (e) {
+      err++;
+      console.log(`  ! ERR   "${r.fullName}": ${(e as Error).message}`);
+    }
+  }
+  console.log(`  → strong ${ok} · weak ${weak} · NO-match ${bad} · read-error ${err}`);
+
+  // ── 2. Berth PDF ↔ mooring ───────────────────────────────────────────────
+  const berthRows = await db
+    .select({ mooring: berths.mooringNumber, storageKey: berthPdfVersions.storageKey })
+    .from(berths)
+    .innerJoin(berthPdfVersions, eq(berthPdfVersions.id, berths.currentPdfVersionId))
+    .where(eq(berths.portId, port.id));
+  console.log(`\n═══ 2. Berth PDF ↔ mooring (${berthRows.length} berths with a PDF) ═══`);
+  let bOk = 0,
+    bBad = 0,
+    bErr = 0;
+  for (const r of berthRows) {
+    try {
+      const text = await pdfText(r.storageKey);
+      // mooring like "A1"/"D32" — match letter+space?+number loosely
+      const moo = r.mooring.toLowerCase();
+      const m = moo.match(/^([a-z]+)(\d+)$/);
+      const found =
+        text.includes(moo) ||
+        (m && text.includes(`${m[1]} ${m[2]}`)) ||
+        (m && new RegExp(`${m[1]}\\s*${m[2]}\\b`).test(text));
+      if (found) bOk++;
+      else {
+        bBad++;
+        console.log(`  ✗ "${r.mooring}" mooring not found in its spec sheet`);
+      }
+    } catch (e) {
+      bErr++;
+      console.log(`  ! ERR ${r.mooring}: ${(e as Error).message}`);
+    }
+  }
+  console.log(`  → mooring-in-PDF ${bOk} · not-found ${bBad} · read-error ${bErr}`);
+
+  // ── 3. Per-person completeness ───────────────────────────────────────────
+  console.log(`\n═══ 3. Per-person data completeness (migrated clients) ═══`);
+  const noContact = await db.execute(sql`
+    select c.full_name from clients c
+    join migration_source_links l on l.target_entity_id=c.id and l.target_entity_type='client'
+    where not exists (select 1 from client_contacts cc where cc.client_id=c.id)`);
+  console.log(`  clients with NO contact (email/phone): ${noContact.length}`);
+  for (const r of noContact.slice(0, 15))
+    console.log(`     - ${(r as { full_name: string }).full_name}`);
+
+  const noDeal = await db.execute(sql`
+    select c.full_name from clients c
+    join migration_source_links l on l.target_entity_id=c.id and l.target_entity_type='client'
+    where not exists (select 1 from interests i where i.client_id=c.id)`);
+  console.log(`  migrated clients with NO deal: ${noDeal.length}`);
+
+  const noStage = await db.execute(sql`
+    select count(*) n from interests i
+    join migration_source_links l on l.target_entity_id=i.id and l.target_entity_type='interest'
+    where i.pipeline_stage is null`);
+  console.log(`  migrated deals with NULL stage: ${(noStage[0] as { n: number }).n}`);
+
+  // sample full dump to eyeball
+  console.log(`\n  -- sample of 6 migrated clients (eyeball) --`);
+  const sample = await db.execute(sql`
+    select c.full_name,
+      (select string_agg(cc.channel||':'||cc.value, ', ') from client_contacts cc where cc.client_id=c.id) contacts,
+      (select count(*) from interests i where i.client_id=c.id) deals,
+      (select string_agg(distinct i.pipeline_stage, ',') from interests i where i.client_id=c.id) stages
+    from clients c
+    join migration_source_links l on l.target_entity_id=c.id and l.target_entity_type='client'
+    order by deals desc nulls last limit 6`);
+  for (const r of sample as unknown as Array<{
+    full_name: string;
+    contacts: string;
+    deals: number;
+    stages: string;
+  }>) {
+    console.log(
+      `     ${r.full_name} · ${r.deals} deal(s) [${r.stages}] · ${r.contacts ?? '(no contacts)'}`,
+    );
+  }
+
+  await closeDb();
+  process.exit(0);
+}
+
+main().catch(async (e) => {
+  console.error('verify failed:', e);
+  await closeDb().catch(() => {});
+  process.exit(1);
+});

scripts/smoke-test-redirect.ts

@@ -0,0 +1,106 @@
+/**
+ * Live smoke test for EMAIL_REDIRECT_TO.
+ *
+ * Actually calls `sendEmail()` (the centralized helper used by every
+ * outbound email path in the app) with a fake real-client address. The
+ * SMTP transporter is monkey-patched to capture the message instead of
+ * actually delivering it, so this is safe to run anywhere.
+ *
+ * Prints the captured `to` + `subject` so the operator can see with their
+ * own eyes that the redirect happened. Exits non-zero if the redirect
+ * failed for any reason.
+ *
+ * Usage:
+ *   pnpm tsx scripts/smoke-test-redirect.ts
+ */
+import 'dotenv/config';
+
+async function main() {
+  const expectedRedirect = process.env.EMAIL_REDIRECT_TO;
+  if (!expectedRedirect) {
+    console.error('FAIL: EMAIL_REDIRECT_TO is not set in env. Set it before running this test.');
+    process.exit(1);
+  }
+
+  console.log(`[smoke] EMAIL_REDIRECT_TO = ${expectedRedirect}`);
+  console.log('');
+
+  // Monkey-patch nodemailer's createTransport so we capture the call
+  // without actually delivering. This is the same pattern the unit
+  // tests use, but at the live import-time level so we're testing the
+  // exact code path that runs in production.
+  const nodemailer = await import('nodemailer');
+  const captured: Array<{ to: unknown; subject: unknown; from: unknown }> = [];
+  const originalCreateTransport = nodemailer.default.createTransport;
+  nodemailer.default.createTransport = (() => ({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    sendMail: async (msg: any) => {
+      captured.push({ to: msg.to, subject: msg.subject, from: msg.from });
+      return { messageId: '<smoke@test>', accepted: [msg.to], rejected: [] };
+    },
+  })) as unknown as typeof nodemailer.default.createTransport;
+
+  // Now import sendEmail (gets the patched transporter).
+  const { sendEmail } = await import('@/lib/email');
+
+  const realClientEmail = 'real-client-DO-NOT-EMAIL@example.test';
+  const realSubject = 'Important: Your contract is ready';
+
+  console.log('[smoke] calling sendEmail(...) with:');
+  console.log(`         to:      ${realClientEmail}`);
+  console.log(`         subject: "${realSubject}"`);
+  console.log('');
+
+  await sendEmail(realClientEmail, realSubject, '<p>Body unused for this smoke.</p>');
+
+  // Restore the original transport (be a good citizen).
+  nodemailer.default.createTransport = originalCreateTransport;
+
+  console.log('[smoke] captured outbound message:');
+  console.log(`         to:      ${captured[0]?.to}`);
+  console.log(`         subject: "${captured[0]?.subject}"`);
+  console.log(`         from:    ${captured[0]?.from}`);
+  console.log('');
+
+  // Assertions
+  let pass = true;
+
+  if (captured.length !== 1) {
+    console.error(`FAIL: expected exactly 1 sendMail call, got ${captured.length}`);
+    pass = false;
+  }
+
+  if (captured[0]?.to !== expectedRedirect) {
+    console.error(
+      `FAIL: outbound "to" was "${captured[0]?.to}", expected the redirect address "${expectedRedirect}"`,
+    );
+    pass = false;
+  }
+
+  if (
+    typeof captured[0]?.subject !== 'string' ||
+    !captured[0].subject.startsWith(`[redirected from ${realClientEmail}]`)
+  ) {
+    console.error(
+      `FAIL: subject did not get the [redirected from <orig>] prefix. Got: "${captured[0]?.subject}"`,
+    );
+    pass = false;
+  }
+
+  if (pass) {
+    console.log('PASS: EMAIL_REDIRECT_TO is intercepting outbound email correctly.');
+    console.log(
+      '      The "to" header matches the redirect, and the original recipient is preserved in the subject.',
+    );
+    process.exit(0);
+  } else {
+    console.error('');
+    console.error('Smoke test FAILED. Do not import production data until this is fixed.');
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('FATAL:', err);
+  process.exit(1);
+});

scripts/test-currency-api.ts

@@ -0,0 +1,42 @@
+/**
+ * Quick verification: live Frankfurter API → DB upsert → getRate read.
+ * Run with `pnpm tsx scripts/test-currency-api.ts`.
+ */
+import { refreshRates, getRate, convert } from '@/lib/services/currency';
+
+async function main() {
+  console.log('1. Fetching live rates from Frankfurter…');
+  await refreshRates();
+
+  console.log('2. Reading round-trip rates from DB:');
+  const usdEur = await getRate('USD', 'EUR');
+  const eurUsd = await getRate('EUR', 'USD');
+  const usdGbp = await getRate('USD', 'GBP');
+  const eurGbp = await getRate('EUR', 'GBP');
+  const usdUsd = await getRate('USD', 'USD');
+
+  console.log(`  USD→EUR: ${usdEur}`);
+  console.log(`  EUR→USD: ${eurUsd}`);
+  console.log(`  USD→GBP: ${usdGbp}`);
+  console.log(`  EUR→GBP: ${eurGbp ?? '(no direct row, expected)'}`);
+  console.log(`  USD→USD: ${usdUsd}`);
+
+  console.log('3. Convert sample amounts:');
+  const c1 = await convert(1000, 'USD', 'EUR');
+  console.log(`  $1000 → ${c1?.result} EUR @ ${c1?.rate}`);
+  const c2 = await convert(500, 'EUR', 'USD');
+  console.log(`  €500 → $${c2?.result} @ ${c2?.rate}`);
+
+  // Sanity: EUR→USD should be ≈ 1 / (USD→EUR), within rounding
+  if (usdEur && eurUsd) {
+    const drift = Math.abs(eurUsd - 1 / usdEur);
+    console.log(`4. Inverse-rate drift: ${drift.toFixed(6)} (≤0.001 = healthy)`);
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Currency test failed:', err);
+  process.exit(1);
+});

scripts/tsc-staged.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Pre-commit type check for staged TS files.
+ *
+ * Writes a temp tsconfig that extends the project root and pins
+ * `files` to whatever lint-staged passed in. `tsc -p` then compiles
+ * the whole dep graph from those entrypoints — catches errors in
+ * the staged code AND in anything it imports — while still skipping
+ * the 22s full-project pass.
+ *
+ * Replaces `tsc-files` (npm), which silently fails under pnpm because
+ * its tsc-resolution path (typescript/../.bin/tsc) doesn't exist in
+ * pnpm's virtual store layout.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+const files = args.filter((a) => /\.(ts|tsx)$/.test(a));
+
+if (files.length === 0) {
+  process.exit(0);
+}
+
+// Temp tsconfig lives inside the project tree (not /tmp) so @types/*
+// resolution walks up to node_modules. tsc's "atTypes" auto-discovery
+// is anchored to the tsconfig's directory, so a temp config in /tmp
+// would miss our @types/node, @types/react, etc.
+const baseDir = join(cwd, 'node_modules/.cache/tsc-staged');
+mkdirSync(baseDir, { recursive: true });
+const tmpDir = mkdtempSync(join(baseDir, 'run-'));
+const tmpConfig = join(tmpDir, 'tsconfig.json');
+
+const relFiles = files.map((f) => relative(tmpDir, resolve(cwd, f)));
+
+// Pull in the project's ambient .d.ts files (css module shim,
+// react-pdf JSX augment, etc.) so side-effect imports like
+// `import 'react-pdf/dist/Page/AnnotationLayer.css'` resolve under the
+// staged-only compile. Without this, `include: []` would shut out
+// everything in src/types/ and tsc reports TS2882 for any CSS import.
+const ambientTypesGlob = relative(tmpDir, join(cwd, 'src/types')) + '/**/*.d.ts';
+
+writeFileSync(
+  tmpConfig,
+  JSON.stringify(
+    {
+      extends: relative(tmpDir, join(cwd, 'tsconfig.json')),
+      compilerOptions: {
+        noEmit: true,
+        skipLibCheck: true,
+        // Explicitly list `types` so the @types/* auto-discovery
+        // finds them — without this, the temp-tsconfig location
+        // anchors discovery to .cache/ and misses node/react/etc.
+        types: ['node', 'react', 'react-dom'],
+      },
+      files: relFiles,
+      include: [ambientTypesGlob],
+    },
+    null,
+    2,
+  ),
+);
+
+const tsc = spawnSync('pnpm', ['exec', 'tsc', '-p', tmpConfig, '--pretty'], {
+  cwd,
+  stdio: 'inherit',
+});
+
+rmSync(tmpDir, { recursive: true, force: true });
+
+process.exit(tsc.status ?? 1);

scripts/tunnel-url.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Print the current Cloudflare quick-tunnel URL, or a clear status line
+# if the launchd job isn't running.
+#
+# Usage:
+#   ./scripts/tunnel-url.sh           # print URL or status
+#   ./scripts/tunnel-url.sh --copy    # print URL and copy to clipboard
+#
+# Paired with the launchd plist at:
+#   ~/Library/LaunchAgents/solutions.letsbe.pn-crm-tunnel.plist
+#
+# Quick ops:
+#   launchctl load   ~/Library/LaunchAgents/solutions.letsbe.pn-crm-tunnel.plist  # start
+#   launchctl unload ~/Library/LaunchAgents/solutions.letsbe.pn-crm-tunnel.plist  # stop
+#   launchctl kickstart -k gui/$(id -u)/solutions.letsbe.pn-crm-tunnel             # restart (NEW URL)
+
+set -euo pipefail
+
+LOG_FILE="$HOME/Library/Logs/pn-crm-tunnel.err.log"
+LABEL="solutions.letsbe.pn-crm-tunnel"
+
+if ! launchctl print "gui/$(id -u)/$LABEL" >/dev/null 2>&1; then
+    echo "Tunnel is not loaded. Start with:"
+    echo "  launchctl load ~/Library/LaunchAgents/$LABEL.plist"
+    exit 1
+fi
+
+if [[ ! -f "$LOG_FILE" ]]; then
+    echo "Tunnel job is loaded but hasn't produced a log yet. Try again in a few seconds."
+    exit 1
+fi
+
+# cloudflared prints the public URL once on startup, like:
+#   https://<words>.trycloudflare.com
+# Take the most recent occurrence so a restart-then-rerun picks the
+# current one rather than a stale earlier line.
+URL=$(grep -Eo 'https://[a-z0-9-]+\.trycloudflare\.com' "$LOG_FILE" | tail -1 || true)
+
+if [[ -z "$URL" ]]; then
+    echo "Tunnel is running but no URL has appeared in the log yet."
+    echo "Tail it:  tail -f $LOG_FILE"
+    exit 1
+fi
+
+echo "$URL"
+echo "$URL/api/webhooks/documenso  ← paste this into Documenso webhook settings"
+
+if [[ "${1:-}" == "--copy" ]]; then
+    printf "%s/api/webhooks/documenso" "$URL" | pbcopy
+    echo "(webhook URL copied to clipboard)"
+fi
+
+# Auto-PATCH Documenso's webhook URL when the env flag is set. Gated so
+# production ports can never have their webhook rotated by a stale dev
+# script. The TS script reads DOCUMENSO_API_URL + DOCUMENSO_API_KEY +
+# DOCUMENSO_API_VERSION from .env and updates every webhook whose URL
+# already points at our path OR at any *.trycloudflare.com host.
+if [[ "${DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK:-}" == "1" ]]; then
+    echo ""
+    echo "DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1 — updating Documenso webhook(s)…"
+    cd "$(dirname "$0")/.." || exit 1
+    DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1 \
+        pnpm tsx scripts/update-documenso-webhook.ts "$URL"
+fi

scripts/update-documenso-webhook.ts

@@ -0,0 +1,194 @@
+/**
+ * Documenso webhook URL auto-updater. Called by `./scripts/tunnel-url.sh`
+ * when the env flag `DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1` is set so a
+ * freshly-restarted cloudflared quick-tunnel (which gets a NEW hostname
+ * on every restart) doesn't leave Documenso pointing at a dead URL.
+ *
+ * Gated by env flag so production ports — which may have a stable
+ * webhook URL — can never have their config rotated by a stale dev
+ * script. Reads Documenso credentials from env (DOCUMENSO_API_URL +
+ * DOCUMENSO_API_KEY + optional DOCUMENSO_API_VERSION).
+ *
+ * Usage (manual invocation):
+ *   DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1 pnpm tsx scripts/update-documenso-webhook.ts https://foo.trycloudflare.com
+ *
+ * Behaviour:
+ *   - Lists every webhook currently configured on the Documenso
+ *     instance.
+ *   - Identifies webhooks whose `webhookUrl` looks like a
+ *     trycloudflare.com domain OR matches our `/api/webhooks/documenso`
+ *     path suffix. These are the ones to rotate.
+ *   - PATCHes each matching webhook to point at the new tunnel URL.
+ *   - Leaves all other webhooks alone (in case the instance also
+ *     services another tenant or a stable production URL).
+ *
+ * Tries Documenso v2 first, falls back to v1 if the v2 endpoint
+ * returns 404. Both versions support GET /webhook(s) + PATCH on the
+ * webhook resource — the shape differs slightly between them but the
+ * fields we touch (`id`, `webhookUrl`) are stable across versions.
+ */
+
+import 'dotenv/config';
+
+const ENABLE_FLAG = process.env.DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK;
+const TUNNEL_BASE = process.argv[2];
+
+if (ENABLE_FLAG !== '1') {
+  console.log(
+    'DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK is not set to 1 — skipping Documenso webhook update.',
+  );
+  process.exit(0);
+}
+
+if (!TUNNEL_BASE) {
+  console.error('Usage: pnpm tsx scripts/update-documenso-webhook.ts <tunnel-base-url>');
+  console.error(
+    'Example: pnpm tsx scripts/update-documenso-webhook.ts https://foo.trycloudflare.com',
+  );
+  process.exit(1);
+}
+
+const API_URL = process.env.DOCUMENSO_API_URL;
+const API_KEY = process.env.DOCUMENSO_API_KEY;
+const API_VERSION = (process.env.DOCUMENSO_API_VERSION ?? 'v2').toLowerCase();
+
+if (!API_URL || !API_KEY) {
+  console.error('DOCUMENSO_API_URL and DOCUMENSO_API_KEY must be set in env to update webhooks.');
+  process.exit(1);
+}
+
+// Trim trailing slash so we can compose paths cleanly.
+const BASE = API_URL.replace(/\/+$/, '');
+const NEW_WEBHOOK_URL = `${TUNNEL_BASE.replace(/\/+$/, '')}/api/webhooks/documenso`;
+
+async function documensoRequest(path: string, init?: RequestInit): Promise<Response> {
+  return fetch(`${BASE}${path}`, {
+    ...init,
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: API_KEY!,
+      ...(init?.headers ?? {}),
+    },
+  });
+}
+
+interface DocumensoWebhook {
+  id: string | number;
+  webhookUrl: string;
+}
+
+/**
+ * Pluck the array of webhooks out of whatever shape the Documenso
+ * version returned. v1 historically returned an array directly; v2
+ * tends to wrap in `{ data: [...] }` or similar. Be tolerant.
+ */
+function extractWebhooks(raw: unknown): DocumensoWebhook[] {
+  if (Array.isArray(raw)) return raw as DocumensoWebhook[];
+  if (raw && typeof raw === 'object') {
+    const r = raw as Record<string, unknown>;
+    if (Array.isArray(r.data)) return r.data as DocumensoWebhook[];
+    if (Array.isArray(r.webhooks)) return r.webhooks as DocumensoWebhook[];
+  }
+  return [];
+}
+
+async function listWebhooks(): Promise<{ webhooks: DocumensoWebhook[]; version: 'v1' | 'v2' }> {
+  if (API_VERSION === 'v2' || API_VERSION === 'v2.0' || API_VERSION === 'v2.x') {
+    const res = await documensoRequest('/api/v2/webhook');
+    if (res.ok) {
+      const body = (await res.json()) as unknown;
+      return { webhooks: extractWebhooks(body), version: 'v2' };
+    }
+    if (res.status !== 404) {
+      console.error(`v2 webhook list returned ${res.status}: ${await res.text()}`);
+    }
+    // Fall through to v1.
+  }
+  const res = await documensoRequest('/api/v1/webhooks');
+  if (!res.ok) {
+    console.error(`v1 webhook list returned ${res.status}: ${await res.text()}`);
+    process.exit(1);
+  }
+  const body = (await res.json()) as unknown;
+  return { webhooks: extractWebhooks(body), version: 'v1' };
+}
+
+async function patchWebhook(
+  version: 'v1' | 'v2',
+  webhook: DocumensoWebhook,
+  newUrl: string,
+): Promise<boolean> {
+  const path =
+    version === 'v2'
+      ? '/api/v2/webhook'
+      : `/api/v1/webhooks/${encodeURIComponent(String(webhook.id))}`;
+  const body = version === 'v2' ? { id: webhook.id, webhookUrl: newUrl } : { webhookUrl: newUrl };
+  const res = await documensoRequest(path, {
+    method: 'PATCH',
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    console.error(`PATCH ${path} (id=${webhook.id}) returned ${res.status}: ${await res.text()}`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Decide whether a given existing webhook is "ours" (i.e. matches the
+ * pattern we want to rotate). Two signals:
+ *   1. Path tail matches `/api/webhooks/documenso` — the CRM-side
+ *      handler we own.
+ *   2. Host matches `*.trycloudflare.com` — almost certainly a stale
+ *      quick-tunnel URL. Rotating these is always safe.
+ */
+function isRotatableWebhook(w: DocumensoWebhook): boolean {
+  if (!w.webhookUrl) return false;
+  if (w.webhookUrl.endsWith('/api/webhooks/documenso')) return true;
+  try {
+    const host = new URL(w.webhookUrl).hostname;
+    if (host.endsWith('.trycloudflare.com')) return true;
+  } catch {
+    /* malformed — leave alone */
+  }
+  return false;
+}
+
+async function main(): Promise<void> {
+  console.log(`Listing webhooks via Documenso ${API_VERSION.toUpperCase()} (base: ${BASE})…`);
+  const { webhooks, version } = await listWebhooks();
+  console.log(`Found ${webhooks.length} webhook(s).`);
+
+  const rotatable = webhooks.filter(isRotatableWebhook);
+  if (rotatable.length === 0) {
+    console.log(
+      `No rotatable webhooks found (looking for paths ending /api/webhooks/documenso or *.trycloudflare.com hosts).`,
+    );
+    console.log(`If your dev webhook is configured differently, point it at: ${NEW_WEBHOOK_URL}`);
+    return;
+  }
+
+  console.log(`Updating ${rotatable.length} webhook(s) to ${NEW_WEBHOOK_URL}…`);
+  let ok = 0;
+  let fail = 0;
+  for (const w of rotatable) {
+    if (w.webhookUrl === NEW_WEBHOOK_URL) {
+      console.log(`  ${w.id}: already at the target URL, skipping.`);
+      continue;
+    }
+    const succeeded = await patchWebhook(version, w, NEW_WEBHOOK_URL);
+    if (succeeded) {
+      ok++;
+      console.log(`  ${w.id}: ${w.webhookUrl} -> ${NEW_WEBHOOK_URL}`);
+    } else {
+      fail++;
+    }
+  }
+  console.log(`Done. ${ok} updated, ${fail} failed.`);
+  if (fail > 0) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error('Documenso webhook update failed:', err);
+  process.exit(1);
+});

sentry.client.config.ts

@@ -0,0 +1,25 @@
+/**
+ * Sentry client-side init.
+ *
+ * No-op when `NEXT_PUBLIC_SENTRY_DSN` is unset — Sentry stays
+ * shipped-but-dormant in dev. Production sets the DSN via the
+ * deploy env. Sampling rate is env-driven via
+ * `SENTRY_TRACES_SAMPLE_RATE` (defaults to 0.1 = 10% of transactions
+ * to avoid quota burn).
+ */
+
+import * as Sentry from '@sentry/nextjs';
+
+const dsn = process.env.NEXT_PUBLIC_SENTRY_DSN;
+
+if (dsn) {
+  Sentry.init({
+    dsn,
+    environment: process.env.SENTRY_ENVIRONMENT ?? process.env.NODE_ENV,
+    tracesSampleRate: Number(process.env.SENTRY_TRACES_SAMPLE_RATE ?? 0.1),
+    // Replay is opt-in — we'd need to verify privacy implications
+    // before enabling. Leave disabled by default.
+    replaysOnErrorSampleRate: 0,
+    replaysSessionSampleRate: 0,
+  });
+}

sentry.edge.config.ts

@@ -0,0 +1,17 @@
+/**
+ * Sentry edge-runtime init (proxy.ts / middleware).
+ *
+ * No-op when `NEXT_PUBLIC_SENTRY_DSN` is unset.
+ */
+
+import * as Sentry from '@sentry/nextjs';
+
+const dsn = process.env.NEXT_PUBLIC_SENTRY_DSN;
+
+if (dsn) {
+  Sentry.init({
+    dsn,
+    environment: process.env.SENTRY_ENVIRONMENT ?? process.env.NODE_ENV,
+    tracesSampleRate: Number(process.env.SENTRY_TRACES_SAMPLE_RATE ?? 0.1),
+  });
+}

sentry.server.config.ts

@@ -0,0 +1,18 @@
+/**
+ * Sentry server-side init.
+ *
+ * No-op when `NEXT_PUBLIC_SENTRY_DSN` is unset. Same DSN as the client
+ * config — Sentry routes events to the right project automatically.
+ */
+
+import * as Sentry from '@sentry/nextjs';
+
+const dsn = process.env.NEXT_PUBLIC_SENTRY_DSN;
+
+if (dsn) {
+  Sentry.init({
+    dsn,
+    environment: process.env.SENTRY_ENVIRONMENT ?? process.env.NODE_ENV,
+    tracesSampleRate: Number(process.env.SENTRY_TRACES_SAMPLE_RATE ?? 0.1),
+  });
+}

src/app/(auth)/layout.tsx

@@ -1,12 +1,16 @@
 import type { Metadata } from 'next';
 
+import { AuthBrandingProvider } from '@/components/shared/auth-branding-provider';
+import { resolveAuthShellBranding } from '@/lib/email/auth-shell-branding';
+
 export const metadata: Metadata = {
   title: {
     default: 'Sign In',
-    template: '%s | Port Nimara CRM',
+    template: '%s',
   },
 };
 
-export default function AuthLayout({ children }: { children: React.ReactNode }) {
-  return <>{children}</>;
+export default async function AuthLayout({ children }: { children: React.ReactNode }) {
+  const branding = await resolveAuthShellBranding();
+  return <AuthBrandingProvider branding={branding}>{children}</AuthBrandingProvider>;
 }

src/app/(auth)/login/page.tsx

@@ -1,30 +1,75 @@
 'use client';
 
-import { useState } from 'react';
-import { useRouter } from 'next/navigation';
+import { useEffect, useState } from 'react';
+import { useRouter, useSearchParams } from 'next/navigation';
 import Link from 'next/link';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 import { toast } from 'sonner';
-import { authClient } from '@/lib/auth/client';
 import { cn } from '@/lib/utils';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { BrandedAuthShell } from '@/components/shared/branded-auth-shell';
+import { useAuthBranding } from '@/components/shared/auth-branding-provider';
+import { FormErrorSummary } from '@/components/forms/form-error-summary';
+import { useFormScrollToError } from '@/hooks/use-form-scroll-to-error';
 
+// `identifier` accepts either an email address or a username (3–30 lowercase
+// letters / digits / dot / underscore / hyphen). The server endpoint
+// /api/auth/sign-in-by-identifier resolves the username server-side and
+// forwards to better-auth in one round-trip - the canonical email is never
+// returned to the browser, which closes the username-enumeration vector.
 const loginSchema = z.object({
-  email: z.string().email('Please enter a valid email address'),
+  identifier: z.string().min(1, 'Email or username is required'),
   password: z.string().min(1, 'Password is required'),
 });
 
 type LoginFormData = z.infer<typeof loginSchema>;
 
+/**
+ * H-02: Validate a redirect target before pushing the user to it. The
+ * middleware appends `?redirect=<path>` when a session check fails on a
+ * protected route; an unsanitized router.push of that value would let a
+ * crafted URL bounce the user to an external host or protocol-relative
+ * `//evil.com` after a successful sign-in. Only same-origin, single-leading-
+ * slash paths pass.
+ */
+function safeRedirectTarget(raw: string | null): string {
+  if (!raw) return '/dashboard';
+  // Allow only paths starting with a single `/` (rules out `//evil.com`
+  // protocol-relative URLs and `https://…` absolute ones).
+  if (!raw.startsWith('/') || raw.startsWith('//')) return '/dashboard';
+  return raw;
+}
+
 export default function LoginPage() {
   const router = useRouter();
+  const branding = useAuthBranding();
+  const appName = branding?.appName?.trim() || 'CRM';
+  const searchParams = useSearchParams();
   const [isLoading, setIsLoading] = useState(false);
 
+  // Fresh-DB bootstrap detection: if no super-admin exists yet, /setup
+  // owns the first-run flow. Failure of the status endpoint is silent
+  // (login still works for everyone else).
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/api/v1/bootstrap/status')
+      .then((r) => (r.ok ? (r.json() as Promise<{ data?: { needsBootstrap?: boolean } }>) : null))
+      .then((payload) => {
+        if (cancelled || !payload) return;
+        if (payload.data?.needsBootstrap) router.replace('/setup');
+      })
+      .catch(() => {
+        /* silent - login UX must still work even if status check fails */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [router]);
+
   const {
     register,
     handleSubmit,
@@ -32,21 +77,30 @@ export default function LoginPage() {
   } = useForm<LoginFormData>({
     resolver: zodResolver(loginSchema),
   });
+  const submitWithScroll = useFormScrollToError(handleSubmit, errors);
 
   async function onSubmit(data: LoginFormData) {
     setIsLoading(true);
     try {
-      const result = await authClient.signIn.email({
-        email: data.email,
-        password: data.password,
+      const res = await fetch('/api/auth/sign-in-by-identifier', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          identifier: data.identifier.trim(),
+          password: data.password,
+        }),
       });
 
-      if (result.error) {
-        toast.error(result.error.message ?? 'Invalid email or password');
+      if (!res.ok) {
+        const payload = (await res.json().catch(() => ({}))) as {
+          error?: { message?: string };
+        };
+        toast.error(payload.error?.message ?? 'Invalid credentials');
         return;
       }
 
-      router.push('/dashboard');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      router.push(safeRedirectTarget(searchParams.get('redirect')) as any);
     } catch {
       toast.error('Something went wrong. Please try again.');
     } finally {
@@ -57,29 +111,39 @@ export default function LoginPage() {
   return (
     <BrandedAuthShell>
       <div className="text-center mb-6">
-        <h1 className="text-xl font-semibold text-gray-900">Port Nimara CRM</h1>
+        <h1 className="text-xl font-semibold text-gray-900">{appName}</h1>
         <p className="text-sm text-gray-500 mt-1">Sign in to continue</p>
       </div>
 
-      <form onSubmit={handleSubmit(onSubmit)} className="space-y-4" noValidate>
+      <form onSubmit={submitWithScroll(onSubmit)} className="space-y-4" noValidate>
+        <FormErrorSummary
+          errors={errors}
+          labels={{ identifier: 'Email or username', password: 'Password' }}
+        />
         <div className="space-y-1.5">
-          <Label htmlFor="email">Email</Label>
+          <Label htmlFor="identifier">Email or username</Label>
           <Input
-            id="email"
-            type="email"
-            autoComplete="email"
-            placeholder="you@example.com"
+            id="identifier"
+            type="text"
+            autoComplete="username"
+            autoCapitalize="none"
+            spellCheck={false}
             disabled={isLoading}
-            className={cn(errors.email && 'border-destructive focus-visible:ring-destructive')}
-            {...register('email')}
+            className={cn(errors.identifier && 'border-destructive focus-visible:ring-destructive')}
+            {...register('identifier')}
           />
-          {errors.email && <p className="text-sm text-destructive">{errors.email.message}</p>}
+          {errors.identifier && (
+            <p className="text-sm text-destructive">{errors.identifier.message}</p>
+          )}
         </div>
 
         <div className="space-y-1.5">
           <div className="flex items-center justify-between">
             <Label htmlFor="password">Password</Label>
-            <Link href="/reset-password" className="text-xs text-[#007bff] hover:underline">
+            <Link
+              href="/reset-password"
+              className="text-xs text-[#0058b3] underline-offset-2 underline hover:no-underline"
+            >
               Forgot password?
             </Link>
           </div>

src/app/(auth)/reset-password/page.tsx

@@ -1,7 +1,8 @@
 'use client';
 
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import Link from 'next/link';
+import { useRouter, useSearchParams } from 'next/navigation';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
@@ -10,6 +11,8 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { BrandedAuthShell } from '@/components/shared/branded-auth-shell';
+import { FormErrorSummary } from '@/components/forms/form-error-summary';
+import { useFormScrollToError } from '@/hooks/use-form-scroll-to-error';
 import { cn } from '@/lib/utils';
 
 const resetSchema = z.object({
@@ -19,6 +22,8 @@ const resetSchema = z.object({
 type ResetFormData = z.infer<typeof resetSchema>;
 
 export default function ResetPasswordPage() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
   const [submitted, setSubmitted] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
 
@@ -29,17 +34,41 @@ export default function ResetPasswordPage() {
   } = useForm<ResetFormData>({
     resolver: zodResolver(resetSchema),
   });
+  const submitWithScroll = useFormScrollToError(handleSubmit, errors);
+
+  // If the user landed here from a stale email link that points to
+  // `/reset-password?token=…` instead of `/set-password?token=…`, hand
+  // them off to the set-password form (the one that actually knows how
+  // to consume the token). New emails should point straight at
+  // `/set-password`, but old links live in inboxes for a long time.
+  useEffect(() => {
+    const token = searchParams.get('token');
+    if (token) {
+      router.replace(`/set-password?token=${encodeURIComponent(token)}`);
+    }
+  }, [router, searchParams]);
 
   async function onSubmit(data: ResetFormData) {
     setIsLoading(true);
     try {
-      // Always show the same success message regardless of whether the email exists.
-      await fetch('/api/auth/reset-password', {
+      // Better-auth's request-link endpoint is `/api/auth/request-password-reset`.
+      // `/api/auth/reset-password` is the *consume-token* endpoint and silently
+      // rejects an email-only payload, which is why the old code appeared to
+      // "succeed" without ever sending mail.
+      const response = await fetch('/api/auth/request-password-reset', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ email: data.email }),
+        body: JSON.stringify({ email: data.email, redirectTo: '/set-password' }),
       });
 
+      // Treat 400 "user not found" as success so we don't leak whether the
+      // account exists - the success copy says "if an account exists…".
+      // Anything else (5xx, network) surfaces as a real error.
+      if (!response.ok && response.status !== 400) {
+        toast.error('Something went wrong. Please try again.');
+        return;
+      }
+
       setSubmitted(true);
     } catch {
       toast.error('Something went wrong. Please try again.');
@@ -62,12 +91,16 @@ export default function ResetPasswordPage() {
             If an account exists for that email address, we have sent a password reset link. Please
             check your inbox and spam folder.
           </p>
-          <Link href="/login" className="inline-block text-sm text-[#007bff] hover:underline">
+          <Link
+            href="/login"
+            className="inline-block text-sm text-[#0058b3] underline-offset-2 underline hover:no-underline"
+          >
             Back to sign in
           </Link>
         </div>
       ) : (
-        <form onSubmit={handleSubmit(onSubmit)} className="space-y-4" noValidate>
+        <form onSubmit={submitWithScroll(onSubmit)} className="space-y-4" noValidate>
+          <FormErrorSummary errors={errors} labels={{ email: 'Email' }} />
           <div className="space-y-1.5">
             <Label htmlFor="email">Email</Label>
             <Input
@@ -92,7 +125,10 @@ export default function ResetPasswordPage() {
 
           <p className="text-center text-sm text-gray-500">
             Remember your password?{' '}
-            <Link href="/login" className="text-[#007bff] hover:underline">
+            <Link
+              href="/login"
+              className="text-[#0058b3] underline-offset-2 underline hover:no-underline"
+            >
               Sign in
             </Link>
           </p>

src/app/(auth)/set-password/page.tsx

@@ -1,8 +1,8 @@
 'use client';
 
-import { Suspense, useState } from 'react';
+import { Suspense, useState, useSyncExternalStore } from 'react';
 import Link from 'next/link';
-import { useRouter, useSearchParams } from 'next/navigation';
+import { useRouter } from 'next/navigation';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
@@ -12,6 +12,8 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { BrandedAuthShell } from '@/components/shared/branded-auth-shell';
+import { FormErrorSummary } from '@/components/forms/form-error-summary';
+import { useFormScrollToError } from '@/hooks/use-form-scroll-to-error';
 
 const MIN_LENGTH = 9;
 
@@ -27,10 +29,35 @@ const passwordSchema = z
 
 type SetPasswordFormData = z.infer<typeof passwordSchema>;
 
+/**
+ * H-03: tokens travel in the URL fragment (`#token=…`) so they never land
+ * in HTTP access logs or HTTP-Referer headers. Pre-fragment links still
+ * carry `?token=…` and stay functional until every outstanding invite
+ * expires - drop the `?token=` fallback after that grace period.
+ */
+function readTokenFromUrl(): string {
+  if (typeof window === 'undefined') return '';
+  const hash = window.location.hash.replace(/^#/, '');
+  if (hash) {
+    const params = new URLSearchParams(hash);
+    const fromFragment = params.get('token');
+    if (fromFragment) return fromFragment;
+  }
+  const search = new URLSearchParams(window.location.search);
+  return search.get('token') ?? '';
+}
+
+const subscribeNoop = () => () => undefined;
+
 function SetPasswordInner() {
   const router = useRouter();
-  const searchParams = useSearchParams();
-  const token = searchParams.get('token');
+  // useSyncExternalStore so the fragment-only token is read post-hydration
+  // (server snapshot returns null; client returns the actual value).
+  const token = useSyncExternalStore<string | null>(
+    subscribeNoop,
+    () => readTokenFromUrl(),
+    () => null,
+  );
   const [isLoading, setIsLoading] = useState(false);
 
   const {
@@ -40,6 +67,7 @@ function SetPasswordInner() {
   } = useForm<SetPasswordFormData>({
     resolver: zodResolver(passwordSchema),
   });
+  const submitWithScroll = useFormScrollToError(handleSubmit, errors);
 
   async function onSubmit(data: SetPasswordFormData) {
     if (!token) {
@@ -56,7 +84,10 @@ function SetPasswordInner() {
       });
 
       if (!response.ok) {
-        const body = await response.json().catch(() => ({}));
+        const body = (await response.json().catch(() => ({}))) as {
+          message?: string;
+          error?: string;
+        };
         toast.error(body.message ?? body.error ?? 'Failed to set password. Please try again.');
         return;
       }
@@ -70,6 +101,19 @@ function SetPasswordInner() {
     }
   }
 
+  // Pre-hydration: token is null. Show a loading placeholder so the user
+  // doesn't see a flash of "Link is missing" while the fragment is being
+  // read on the client.
+  if (token === null) {
+    return (
+      <BrandedAuthShell>
+        <div role="status" aria-live="polite" className="text-center text-sm text-gray-500">
+          Loading…
+        </div>
+      </BrandedAuthShell>
+    );
+  }
+
   if (!token) {
     return (
       <BrandedAuthShell>
@@ -79,7 +123,10 @@ function SetPasswordInner() {
             Please use the link from the email we sent you. If the link is broken, ask your
             administrator for a new one.
           </p>
-          <Link href="/login" className="inline-block text-sm text-[#007bff] hover:underline">
+          <Link
+            href="/login"
+            className="inline-block text-sm text-[#0058b3] underline-offset-2 underline hover:no-underline"
+          >
             Back to sign in
           </Link>
         </div>
@@ -94,7 +141,11 @@ function SetPasswordInner() {
         <p className="text-sm text-gray-500 mt-1">Choose a password for your CRM account</p>
       </div>
 
-      <form onSubmit={handleSubmit(onSubmit)} className="space-y-4" noValidate>
+      <form onSubmit={submitWithScroll(onSubmit)} className="space-y-4" noValidate>
+        <FormErrorSummary
+          errors={errors}
+          labels={{ password: 'Password', confirmPassword: 'Confirm password' }}
+        />
         <div className="space-y-1.5">
           <Label htmlFor="password">New password</Label>
           <Input
@@ -102,10 +153,13 @@ function SetPasswordInner() {
             type="password"
             autoComplete="new-password"
             disabled={isLoading}
+            aria-describedby="password-hint"
             className={cn(errors.password && 'border-destructive focus-visible:ring-destructive')}
             {...register('password')}
           />
-          <p className="text-xs text-gray-500">At least {MIN_LENGTH} characters.</p>
+          <p id="password-hint" className="text-xs text-gray-500">
+            At least {MIN_LENGTH} characters.
+          </p>
           {errors.password && <p className="text-sm text-destructive">{errors.password.message}</p>}
         </div>
 

src/app/(auth)/setup/page.tsx

@@ -0,0 +1,202 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { BrandedAuthShell } from '@/components/shared/branded-auth-shell';
+import { useAuthBranding } from '@/components/shared/auth-branding-provider';
+import { FormErrorSummary } from '@/components/forms/form-error-summary';
+import { useFormScrollToError } from '@/hooks/use-form-scroll-to-error';
+import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';
+
+const setupSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(120),
+  email: z.string().email('Valid email is required').max(254),
+  password: z.string().min(9, 'Password must be at least 9 characters').max(200),
+  confirmPassword: z.string(),
+});
+
+type SetupFormData = z.infer<typeof setupSchema>;
+
+interface StatusResp {
+  data: { needsBootstrap: boolean };
+}
+
+/**
+ * First-run setup. On a fresh DB the very first visitor can claim the
+ * super-admin account here. Once anyone claims it, future visits to
+ * /setup redirect back to /login - the precondition is verified both
+ * server-side (`/api/v1/bootstrap/status` + `/api/v1/bootstrap/super-admin`'s
+ * internal recheck) and client-side here.
+ */
+export default function SetupPage() {
+  const router = useRouter();
+  const branding = useAuthBranding();
+  const appName = branding?.appName?.trim() || 'this CRM';
+  const [checking, setChecking] = useState(true);
+  const [submitting, setSubmitting] = useState(false);
+
+  const {
+    register,
+    handleSubmit,
+    watch,
+    formState: { errors },
+  } = useForm<SetupFormData>({
+    resolver: zodResolver(setupSchema),
+  });
+  const submitWithScroll = useFormScrollToError(handleSubmit, errors);
+
+  useEffect(() => {
+    let cancelled = false;
+    async function check() {
+      try {
+        const res = await apiFetch<StatusResp>('/api/v1/bootstrap/status');
+        if (cancelled) return;
+        if (!res.data.needsBootstrap) {
+          // Already initialized - bounce to login. Replace, not push,
+          // so back-button doesn't trap the user here.
+          router.replace('/login');
+          return;
+        }
+      } catch {
+        // Status endpoint failed - let the user try anyway; the POST
+        // does its own check and will surface a 409 if the window closed.
+      } finally {
+        if (!cancelled) setChecking(false);
+      }
+    }
+    void check();
+    return () => {
+      cancelled = true;
+    };
+  }, [router]);
+
+  async function onSubmit(data: SetupFormData) {
+    if (data.password !== data.confirmPassword) {
+      toast.error('Passwords do not match');
+      return;
+    }
+    setSubmitting(true);
+    try {
+      await apiFetch('/api/v1/bootstrap/super-admin', {
+        method: 'POST',
+        body: {
+          name: data.name,
+          email: data.email,
+          password: data.password,
+        },
+      });
+      toast.success('Administrator account created  -  sign in to continue.');
+      router.replace('/login');
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Failed to create administrator account');
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  if (checking) {
+    return (
+      <BrandedAuthShell>
+        <div className="text-center text-sm text-muted-foreground">Checking setup state…</div>
+      </BrandedAuthShell>
+    );
+  }
+
+  return (
+    <BrandedAuthShell>
+      <div className="space-y-6">
+        <div className="text-center space-y-1">
+          <h1 className="text-xl font-semibold">Welcome to {appName}</h1>
+          <p className="text-sm text-muted-foreground">
+            No administrator account exists yet. Create one to get started - you&rsquo;ll be the
+            super-administrator for this installation.
+          </p>
+        </div>
+
+        <form onSubmit={submitWithScroll(onSubmit)} className="space-y-4">
+          <FormErrorSummary
+            errors={errors}
+            labels={{
+              name: 'Name',
+              email: 'Email',
+              password: 'Password',
+              confirmPassword: 'Confirm password',
+            }}
+          />
+          <div className="space-y-1.5">
+            <Label htmlFor="setup-name">Your name</Label>
+            <Input
+              id="setup-name"
+              placeholder="Jane Operator"
+              autoComplete="name"
+              {...register('name')}
+              className={cn(errors.name && 'border-destructive')}
+            />
+            {errors.name && <p className="text-xs text-destructive">{errors.name.message}</p>}
+          </div>
+
+          <div className="space-y-1.5">
+            <Label htmlFor="setup-email">Email</Label>
+            <Input
+              id="setup-email"
+              type="email"
+              placeholder="you@example.com"
+              autoComplete="email"
+              {...register('email')}
+              className={cn(errors.email && 'border-destructive')}
+            />
+            {errors.email && <p className="text-xs text-destructive">{errors.email.message}</p>}
+          </div>
+
+          <div className="space-y-1.5">
+            <Label htmlFor="setup-password">Password</Label>
+            <Input
+              id="setup-password"
+              type="password"
+              placeholder="At least 9 characters"
+              autoComplete="new-password"
+              {...register('password')}
+              className={cn(errors.password && 'border-destructive')}
+            />
+            {errors.password && (
+              <p className="text-xs text-destructive">{errors.password.message}</p>
+            )}
+          </div>
+
+          <div className="space-y-1.5">
+            <Label htmlFor="setup-confirm">Confirm password</Label>
+            <Input
+              id="setup-confirm"
+              type="password"
+              autoComplete="new-password"
+              {...register('confirmPassword')}
+              className={cn(
+                watch('password') !== watch('confirmPassword') &&
+                  watch('confirmPassword')?.length > 0 &&
+                  'border-destructive',
+              )}
+            />
+          </div>
+
+          <Button type="submit" className="w-full" disabled={submitting}>
+            {submitting ? 'Creating account…' : 'Create administrator account'}
+          </Button>
+        </form>
+
+        <p className="text-center text-xs text-muted-foreground">
+          This screen is only available until the first administrator is created. After that,
+          subsequent users are added through Admin &rarr; Users.
+        </p>
+      </div>
+    </BrandedAuthShell>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/ai/page.tsx

@@ -0,0 +1,85 @@
+import { Bot, FileScan, Lightbulb } from 'lucide-react';
+
+import { RegistryDrivenForm } from '@/components/admin/shared/registry-driven-form';
+import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { OcrSettingsForm } from '@/components/admin/ocr-settings-form';
+
+export default function AiAdminPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="AI configuration"
+        description="One place to manage every AI-using feature. Provider credentials and the master AI switch live here; per-feature thresholds are embedded below."
+        eyebrow="ADMIN"
+      />
+
+      <RegistryDrivenForm
+        title="Master controls"
+        description="Hard kill switch + budget guardrails covering every AI surface in this port."
+        sections={['ai.master']}
+      />
+
+      <RegistryDrivenForm
+        title="Provider credentials"
+        description="Shared API keys used by AI-enabled features. AES-encrypted at rest. Per-feature pages can override the model on a feature-by-feature basis."
+        sections={['ai.providers']}
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base flex items-center gap-2">
+            <Bot className="h-4 w-4" /> Receipt OCR
+          </CardTitle>
+          <CardDescription>
+            Provider, model, and confidence thresholds for the receipt scanner. AI fallback only
+            runs when the on-device parser is uncertain.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <OcrSettingsForm embedded />
+        </CardContent>
+      </Card>
+
+      {/*
+        Berth-PDF parser AI fallback - currently configured via the
+        BERTH_PDF_PARSER_* env vars. No per-port override surface today;
+        when one is added, it lands here so admins don't have to hunt.
+      */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base flex items-center gap-2">
+            <FileScan className="h-4 w-4" /> Berth PDF parser
+          </CardTitle>
+          <CardDescription>
+            3-tier extraction (AcroForm → on-device OCR → AI fallback on low confidence) for
+            per-berth PDFs and brochures. Provider + confidence threshold are env-controlled today
+            (BERTH_PDF_PARSER_PROVIDER, BERTH_PDF_PARSER_CONFIDENCE_FLOOR); a per-port override UI
+            lands in a follow-up. The master switch above gates the AI tier across every port.
+          </CardDescription>
+        </CardHeader>
+      </Card>
+
+      {/*
+        Future AI surfaces. Each gets a section here once it ships:
+          - Recommender embeddings (currently rule-based, not LLM-based)
+          - Contact-log action extraction (deferred - needs user demand)
+          - Inquiry-form auto-classification (deferred)
+        Listing them inert here closes the "where do I configure AI?"
+        loop - admins land on /admin/ai and see the full landscape.
+      */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base flex items-center gap-2 text-muted-foreground">
+            <Lightbulb className="h-4 w-4" /> Planned AI surfaces
+          </CardTitle>
+          <CardDescription>
+            Recommender embeddings, contact-log action extraction, and inquiry-form auto-
+            classification are queued. They will surface as additional sections on this page when
+            shipped, with no scattered admin entries to hunt down.
+          </CardDescription>
+        </CardHeader>
+      </Card>
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/backup/page.tsx

@@ -1,15 +1,15 @@
+import { BackupAdminPanel } from '@/components/admin/backup-admin-panel';
 import { PageHeader } from '@/components/shared/page-header';
 
 export default function BackupManagementPage() {
   return (
     <div className="space-y-6">
-      <PageHeader title="Backup Management" description="Manage system backups and restoration" />
-      <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-12">
-        <p className="text-lg font-medium text-muted-foreground">Coming in Layer 4</p>
-        <p className="text-sm text-muted-foreground">
-          This feature will be implemented in the next phase.
-        </p>
-      </div>
+      <PageHeader
+        title="Backup & Restore"
+        eyebrow="ADMIN"
+        description="Trigger ad-hoc database snapshots, browse the history, and download a .dump file for offline restore."
+      />
+      <BackupAdminPanel />
     </div>
   );
 }

src/app/(dashboard)/[portSlug]/admin/berths/bulk-add/page.tsx

@@ -0,0 +1,14 @@
+import { PageHeader } from '@/components/shared/page-header';
+import { BulkAddBerthsWizard } from '@/components/admin/bulk-add-berths-wizard';
+
+export default function BulkAddBerthsPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Bulk add berths"
+        description="Create many berths at once. Pick a dock letter + range to generate the rows, then fill in per-row dimensions / pricing / pontoon. Standard fields (tenure, status) apply to every row; everything else is per-row."
+      />
+      <BulkAddBerthsWizard />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/berths/page.tsx

@@ -0,0 +1,88 @@
+import Link from 'next/link';
+import type { Route } from 'next';
+import { AlertCircle, Anchor, FileSearch } from 'lucide-react';
+
+import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+
+/**
+ * Berths admin index. Both sub-pages (`bulk-add`, `reconcile`) existed
+ * pre-2026-05-22 but were only reachable via deep links from inside the
+ * Berths list. Surfacing them on a dedicated admin landing tile so the
+ * tools are discoverable without prior knowledge of the URL - part of
+ * the admin IA regroup (B3 #10 Phase 2).
+ */
+export default async function BerthsAdminIndex({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  const tools = [
+    {
+      href: `/${portSlug}/admin/berths/bulk-add` as Route,
+      label: 'Bulk add berths',
+      description:
+        'Generate many berth rows in one wizard - set pier, prefix, mooring number range, and per-berth defaults; preview before commit.',
+      icon: Anchor,
+    },
+    {
+      href: `/${portSlug}/admin/berths/reconcile` as Route,
+      label: 'Reconciliation queue',
+      description:
+        "Berths missing required fields after import / PDF parse. Surface what's missing per row and link straight to the edit sheet.",
+      icon: FileSearch,
+    },
+  ] as const;
+
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Berths admin"
+        eyebrow="ADMIN"
+        description="Tools for bulk berth creation and post-import reconciliation. Single-berth edits stay on the Berths list - these surfaces are for batch operations."
+      />
+
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+        {tools.map((t) => {
+          const Icon = t.icon;
+          return (
+            <Link key={t.href} href={t.href} className="block group">
+              <Card className="h-full transition-colors group-hover:border-primary/50 group-hover:bg-muted/30">
+                <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
+                  <Icon
+                    className="h-5 w-5 mt-0.5 text-muted-foreground group-hover:text-primary"
+                    aria-hidden
+                  />
+                  <CardTitle className="text-base">{t.label}</CardTitle>
+                </CardHeader>
+                <CardContent>
+                  <CardDescription>{t.description}</CardDescription>
+                </CardContent>
+              </Card>
+            </Link>
+          );
+        })}
+      </div>
+
+      <Card className="border-amber-200 bg-amber-50/50">
+        <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
+          <AlertCircle className="h-5 w-5 mt-0.5 text-amber-600" aria-hidden />
+          <CardTitle className="text-sm">Not what you&apos;re looking for?</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <CardDescription className="text-xs">
+            For single-berth edits, browse to the{' '}
+            <Link
+              href={`/${portSlug}/berths` as Route}
+              className="font-medium text-primary hover:underline"
+            >
+              Berths list
+            </Link>{' '}
+            and click any row. Per-berth PDF uploads + brochure assignment also live there.
+          </CardDescription>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/berths/reconcile/page.tsx

@@ -0,0 +1,14 @@
+import { PageHeader } from '@/components/shared/page-header';
+import { ReconcileQueue } from '@/components/admin/reconcile-queue';
+
+export default function ReconcileBerthsPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Berth reconciliation queue"
+        description="Berths flipped manually to Under Offer or Sold without a backing interest. Run the catch-up wizard on each row to create the deal, attach docs, and clear the manual flag."
+      />
+      <ReconcileQueue />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/branding/page.tsx

@@ -3,6 +3,30 @@ import {
   type SettingFieldDef,
 } from '@/components/admin/shared/settings-form-card';
 import { PageHeader } from '@/components/shared/page-header';
+import { PdfLogoUploader } from '@/components/admin/branding/pdf-logo-uploader';
+import { EmailPreviewCard } from '@/components/admin/branding/email-preview-card';
+
+const DEFAULT_EMAIL_HEADER_HTML = `<!-- Optional pre-body header -->
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="border-collapse:collapse;">
+  <tr>
+    <td align="center" style="padding:16px 0;">
+      <a href="https://example.com" style="text-decoration:none;color:#1e293b;font-family:Arial,sans-serif;font-size:14px;font-weight:600;">
+        Your brand name
+      </a>
+    </td>
+  </tr>
+</table>`;
+
+const DEFAULT_EMAIL_FOOTER_HTML = `<!-- Optional sub-body footer -->
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="border-collapse:collapse;">
+  <tr>
+    <td align="center" style="padding:24px 0;color:#64748b;font-family:Arial,sans-serif;font-size:12px;">
+      &copy; ${new Date().getFullYear()} Your Company &middot;
+      <a href="https://example.com" style="color:#64748b;">Visit our website</a> &middot;
+      <a href="mailto:hello@example.com" style="color:#64748b;">hello@example.com</a>
+    </td>
+  </tr>
+</table>`;
 
 const FIELDS: SettingFieldDef[] = [
   {
@@ -15,11 +39,23 @@ const FIELDS: SettingFieldDef[] = [
   },
   {
     key: 'branding_logo_url',
-    label: 'Logo URL',
+    label: 'Logo',
     description:
-      'Public HTTPS URL of the logo used in email headers and the branded auth shell. Recommended size: 240×80 PNG with transparent background.',
-    type: 'string',
-    placeholder: 'https://example.com/logo.png',
+      'Used in email headers and the branded auth shell. Recommended: square PNG with transparent background.',
+    type: 'image-upload',
+    imageAspect: 1,
+    defaultValue: '',
+  },
+  {
+    key: 'branding_email_background_url',
+    label: 'Email background image',
+    description:
+      'Blurred photo shown behind the white email card and the auth-shell (login / reset password) pages. Leave blank to render a plain off-white backdrop. Recommended: 1920x1080 JPG, pre-blurred to ~20px gaussian so it reads as a soft background even on small clients.',
+    type: 'image-upload',
+    // 16:9 - landscape. Without an explicit aspect, the cropper falls
+    // back to 1:1 and renders a circular mask (intended for avatars),
+    // which is the wrong UX for a viewport-cover background.
+    imageAspect: 16 / 9,
     defaultValue: '',
   },
   {
@@ -32,9 +68,11 @@ const FIELDS: SettingFieldDef[] = [
   {
     key: 'branding_email_header_html',
     label: 'Email header HTML',
-    description: 'Optional HTML rendered above each email body. Leave blank to use the default.',
+    description:
+      'Optional HTML rendered above each email body. Leave blank to use the default. Tap "Insert default" to start from the baseline template.',
     type: 'html',
     defaultValue: '',
+    defaultTemplate: DEFAULT_EMAIL_HEADER_HTML,
   },
   {
     key: 'branding_email_footer_html',
@@ -42,6 +80,7 @@ const FIELDS: SettingFieldDef[] = [
     description: 'Optional HTML rendered at the very bottom of each email (above the signature).',
     type: 'html',
     defaultValue: '',
+    defaultTemplate: DEFAULT_EMAIL_FOOTER_HTML,
   },
 ];
 
@@ -62,6 +101,8 @@ export default function BrandingSettingsPage() {
         description="HTML fragments rendered around every transactional email."
         fields={FIELDS.slice(3)}
       />
+      <EmailPreviewCard />
+      <PdfLogoUploader />
     </div>
   );
 }

src/app/(dashboard)/[portSlug]/admin/brochures/page.tsx

@@ -0,0 +1,21 @@
+import { PageHeader } from '@/components/shared/page-header';
+import { BrochuresAdminPanel } from '@/components/admin/brochures-admin-panel';
+
+/**
+ * Per-port admin page for managing brochures (Phase 7 §5.8).
+ *
+ * Lists brochures, lets per-port admins upload new versions via direct-to-
+ * storage presigned URLs (so the 20MB+ file never traverses Next.js's
+ * body-size limit - see §11.1), and toggle the default flag.
+ */
+export default function BrochuresAdminPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Brochures"
+        description="Port-wide marketing PDFs available to the sales send-out flow. The default brochure is the one /clients picker pre-selects."
+      />
+      <BrochuresAdminPanel />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/documenso/page.tsx

@@ -1,71 +1,213 @@
-import {
-  SettingsFormCard,
-  type SettingFieldDef,
-} from '@/components/admin/shared/settings-form-card';
+import { CheckCircle2, Info } from 'lucide-react';
+
+import { RegistryDrivenForm } from '@/components/admin/shared/registry-driven-form';
 import { DocumensoTestButton } from '@/components/admin/documenso/documenso-test-button';
+import { EmbeddedSigningCard } from '@/components/admin/documenso/embedded-signing-card';
+import { TemplateSyncButton } from '@/components/admin/documenso/template-sync-button';
+import { WebhookHealthCard } from '@/components/admin/documenso/webhook-health-card';
 import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 
-const API_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'documenso_api_url_override',
-    label: 'API URL override',
-    description: 'Optional. Falls back to DOCUMENSO_API_URL env when blank.',
-    type: 'string',
-    placeholder: 'https://documenso.example.com',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_api_key_override',
-    label: 'API key override',
-    description: 'Optional. Falls back to DOCUMENSO_API_KEY env when blank. Stored in plain text.',
-    type: 'password',
-    defaultValue: '',
-  },
-];
-
-const EOI_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'documenso_eoi_template_id',
-    label: 'EOI Documenso template ID',
-    description: 'Numeric template ID used by the Documenso EOI pathway.',
-    type: 'string',
-    placeholder: '12345',
-    defaultValue: '',
-  },
-  {
-    key: 'eoi_default_pathway',
-    label: 'Default EOI pathway',
-    description:
-      'Which pathway is used when an EOI is generated without an explicit choice. Documenso = signed via Documenso, In-app = filled locally with pdf-lib.',
-    type: 'select',
-    options: [
-      { value: 'documenso-template', label: 'Documenso template' },
-      { value: 'inapp', label: 'In-app (pdf-lib)' },
-    ],
-    defaultValue: 'documenso-template',
-  },
-];
+// All field arrays removed - every Documenso setting now flows through
+// `RegistryDrivenForm`, which surfaces the env-fallback / port / global
+// source badge on each field. The settings themselves live in
+// `src/lib/settings/registry.ts` under sections `documenso.api` /
+// `.signers` / `.templates` / `.behavior`.
 
 export default function DocumensoSettingsPage() {
   return (
     <div className="space-y-6">
       <PageHeader
-        title="Documenso & EOI"
-        description="API credentials and default EOI generation pathway. Use the test-connection button to verify a saved configuration before relying on it."
+        title="Signing service (Documenso)"
+        description="API credentials, signer identities, templates, and signing behaviour for every document the CRM puts out for signature (EOI, reservation, contract, custom uploads). Use the test-connection button to verify a saved configuration before relying on it."
       />
 
-      <SettingsFormCard
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2 text-base">
+            <Info className="h-4 w-4" aria-hidden="true" />
+            v1 vs v2 - what changes when you flip the API version
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4 text-sm">
+          <p className="text-muted-foreground">
+            The CRM supports both Documenso 1.13.x (v1) and 2.x (v2). v1 is the default for
+            backwards compatibility. v2 is recommended for new ports and unlocks the features below.
+            Switching versions does <strong>not</strong> require any code changes - version-aware
+            client methods pick the right endpoint per port. Switch, save, then run the
+            test-connection button to confirm the chosen instance is actually on the matching
+            Documenso version.
+          </p>
+
+          <div className="rounded-md border border-border bg-muted/40 p-3">
+            <p className="mb-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+              v2-only capabilities the CRM already uses when you pick v2
+            </p>
+            <ul className="space-y-1.5">
+              <li className="flex items-start gap-2">
+                <CheckCircle2
+                  className="mt-0.5 h-4 w-4 shrink-0 text-emerald-600"
+                  aria-hidden="true"
+                />
+                <span>
+                  <strong>Bulk field placement.</strong> One API call per envelope vs. v1&apos;s
+                  per-field POST loop. Faster contract generation, fewer transient retries on
+                  multi-field uploaded contracts.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2
+                  className="mt-0.5 h-4 w-4 shrink-0 text-emerald-600"
+                  aria-hidden="true"
+                />
+                <span>
+                  <strong>Percent-based field coordinates.</strong> No page-dimension lookup needed
+                  - coordinates are portable across page sizes. v1 requires us to assume A4 for
+                  auto-placed fields.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2
+                  className="mt-0.5 h-4 w-4 shrink-0 text-emerald-600"
+                  aria-hidden="true"
+                />
+                <span>
+                  <strong>Richer field metadata.</strong> TEXT labels &amp; required flags, NUMBER
+                  min/max + format, CHECKBOX/DROPDOWN/RADIO option lists with defaults - all ignored
+                  by v1, surfaced by v2 in the signing UI.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2
+                  className="mt-0.5 h-4 w-4 shrink-0 text-emerald-600"
+                  aria-hidden="true"
+                />
+                <span>
+                  <strong>v2-flavoured webhook events.</strong> <code>RECIPIENT_VIEWED</code>,{' '}
+                  <code>RECIPIENT_SIGNED</code>, <code>DOCUMENT_RECIPIENT_COMPLETED</code>,{' '}
+                  <code>DOCUMENT_DECLINED</code>, <code>DOCUMENT_REMINDER_SENT</code> - all routed
+                  through the same dedup + audit pipeline as v1 events.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2
+                  className="mt-0.5 h-4 w-4 shrink-0 text-emerald-600"
+                  aria-hidden="true"
+                />
+                <span>
+                  <strong>Envelope CRUD endpoints.</strong> <code>GET</code>, <code>DELETE</code>,
+                  <code>POST /envelope/create</code> (multipart),{' '}
+                  <code>POST /envelope/distribute</code>, <code>POST /envelope/redistribute</code>,{' '}
+                  <code>GET /envelope/{'{id}'}/download</code> - all routed through{' '}
+                  <code>/api/v2/envelope/...</code> when v2 is selected. The template-generate path
+                  is intentionally still v1 (relies on Documenso 2.x&apos;s backward-compat window -
+                  see the deferred-roadmap below).
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2
+                  className="mt-0.5 h-4 w-4 shrink-0 text-emerald-600"
+                  aria-hidden="true"
+                />
+                <span>
+                  <strong>One-call send.</strong> v2&apos;s <code>/envelope/distribute</code>{' '}
+                  returns per-recipient <code>signingUrl</code> in the same response - v1 requires a
+                  separate GET to fetch them. Faster send flow on the rep side.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2
+                  className="mt-0.5 h-4 w-4 shrink-0 text-emerald-600"
+                  aria-hidden="true"
+                />
+                <span>
+                  <strong>Sequential signing enforcement.</strong> Pick SEQUENTIAL in the &quot;v2
+                  signing behaviour&quot; card below and Documenso 2.x refuses to email recipient
+                  N+1 until recipient N has signed. Eliminates the &quot;approver signed before the
+                  developer did&quot; race on EOIs.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2
+                  className="mt-0.5 h-4 w-4 shrink-0 text-emerald-600"
+                  aria-hidden="true"
+                />
+                <span>
+                  <strong>Post-signing redirect URL.</strong> Set in the &quot;v2 signing
+                  behaviour&quot; card; Documenso redirects the signer to that URL after they
+                  complete signing. Use to land clients on the marketing site&apos;s success page or
+                  back in the portal instead of Documenso&apos;s default thank-you page. (v1 honours
+                  this too - listed here because the admin setting was added with the v2 work.)
+                </span>
+              </li>
+            </ul>
+          </div>
+
+          <div className="rounded-md border border-amber-200 bg-amber-50/60 p-3 dark:border-amber-900/40 dark:bg-amber-950/30">
+            <p className="mb-2 text-xs font-semibold uppercase tracking-wider text-amber-700 dark:text-amber-400">
+              v2 capabilities deferred (would need new code paths)
+            </p>
+            <ul className="space-y-1.5 text-muted-foreground">
+              <li>
+                <strong>
+                  Single-shot <code>/template/use</code>
+                </strong>{' '}
+                with v2 <code>prefillFields</code> by ID - current EOI flow uses{' '}
+                <code>/api/v1/templates/{'{id}'}/generate-document</code> with{' '}
+                <code>formValues</code> keyed by name. v2 instances accept both during their
+                backward-compat window; full migration requires per-template field-ID capture in
+                admin settings.
+              </li>
+              <li>
+                <strong>
+                  Update envelope metadata after creation (<code>/envelope/update</code>)
+                </strong>{' '}
+                - change title / subject / redirectUrl on a doc already in DRAFT/PENDING without
+                re-generating.
+              </li>
+              <li>
+                <strong>Non-SIGNER recipient roles (CC / VIEWER)</strong> - APPROVER role is already
+                used by the EOI template; CC + VIEWER not yet exposed in the recipient builder.
+                Useful for sales managers who want a copy without a signature slot.
+              </li>
+            </ul>
+            <p className="mt-2 text-xs text-muted-foreground">
+              Sequential signing and post-signing redirect URL <strong>are now wired</strong> - see
+              the new &quot;v2 signing behaviour&quot; card below to configure them.
+            </p>
+          </div>
+        </CardContent>
+      </Card>
+
+      <RegistryDrivenForm
         title="Documenso API"
-        description="Per-port API credentials. Leave blank to use the global env defaults."
-        fields={API_FIELDS}
+        description="Per-port API credentials. AES-encrypted at rest. Leave blank to inherit from the env fallback (badged below each field)."
+        sections={['documenso.api']}
         extra={<DocumensoTestButton />}
       />
 
-      <SettingsFormCard
-        title="EOI generation"
-        description="Default pathway and template used when an interest's EOI is generated."
-        fields={EOI_FIELDS}
+      <RegistryDrivenForm
+        sections={['documenso.behavior']}
+        title="Signing behaviour"
+        description="Cross-cutting settings that apply to EOIs + uploaded contracts/reservations. Sequential signing is v2-only (v1 instances ignore it). Redirect URL is honoured by both v1 and v2 instances."
       />
+
+      <RegistryDrivenForm
+        sections={['documenso.signers']}
+        title="Signers (developer + approver)"
+        description="Identity bound to the developer (signing order 2) and approver (signing order 3) slots in your Documenso templates. Leave name + email blank to fall through to whatever you set on the Documenso template itself; set them here to override the template's stored values at send time. Recipient IDs are populated automatically by 'Sync from Documenso' below. Linking a CRM user is optional  -  when set, the platform fires an in-CRM notification for that user when it's their turn to sign."
+      />
+
+      <RegistryDrivenForm
+        sections={['documenso.templates']}
+        title="Templates & signing pathway"
+        description="Default pathway, template IDs, and email behaviour for EOIs, reservations, and contracts. Recipient + field discovery happens via 'Sync from Documenso' below - that also populates the EOI template ID for you. Most ports leave the reservation/contract template IDs blank because those are typically drafted per interest and uploaded for signing; set them only if you maintain standardised Documenso templates for them."
+        extra={<TemplateSyncButton />}
+      />
+
+      <EmbeddedSigningCard />
+
+      <WebhookHealthCard />
     </div>
   );
 }

src/app/(dashboard)/[portSlug]/admin/email-templates/page.tsx

@@ -0,0 +1,5 @@
+import { EmailTemplatesAdmin } from '@/components/admin/email-templates-admin';
+
+export default function EmailTemplatesPage() {
+  return <EmailTemplatesAdmin />;
+}

src/app/(dashboard)/[portSlug]/admin/email/page.tsx

@@ -1,99 +1,61 @@
-import {
-  SettingsFormCard,
-  type SettingFieldDef,
-} from '@/components/admin/shared/settings-form-card';
-import { PageHeader } from '@/components/shared/page-header';
+import { Info } from 'lucide-react';
 
-const FIELDS: SettingFieldDef[] = [
-  {
-    key: 'email_from_name',
-    label: 'From name',
-    description: 'Display name shown in the From: header on outgoing email.',
-    type: 'string',
-    placeholder: 'Port Nimara',
-    defaultValue: '',
-  },
-  {
-    key: 'email_from_address',
-    label: 'From address',
-    description: 'Sender email address. Falls back to SMTP_FROM env when blank.',
-    type: 'string',
-    placeholder: 'noreply@example.com',
-    defaultValue: '',
-  },
-  {
-    key: 'email_reply_to',
-    label: 'Reply-to address',
-    description: 'Optional Reply-To: header for replies (e.g. sales@example.com).',
-    type: 'string',
-    placeholder: 'sales@example.com',
-    defaultValue: '',
-  },
-  {
-    key: 'email_signature_html',
-    label: 'Default signature (HTML)',
-    description: 'Appended to the bottom of system-generated emails.',
-    type: 'html',
-    placeholder: '<p>—<br>The Port Nimara team</p>',
-    defaultValue: '',
-  },
-  {
-    key: 'email_footer_html',
-    label: 'Email footer (HTML)',
-    description: 'Legal/contact footer rendered at the very bottom of all emails.',
-    type: 'html',
-    placeholder: '<p style="font-size:11px;color:#888;">© Port Nimara · ul. ...</p>',
-    defaultValue: '',
-  },
-  {
-    key: 'smtp_host_override',
-    label: 'SMTP host override',
-    description: 'Optional. Falls back to SMTP_HOST env when blank.',
-    type: 'string',
-    placeholder: 'mail.example.com',
-    defaultValue: '',
-  },
-  {
-    key: 'smtp_port_override',
-    label: 'SMTP port override',
-    description: 'Optional. Falls back to SMTP_PORT env when blank.',
-    type: 'number',
-    placeholder: '587',
-    defaultValue: null,
-  },
-  {
-    key: 'smtp_user_override',
-    label: 'SMTP username override',
-    description: 'Optional. Falls back to SMTP_USER env when blank.',
-    type: 'string',
-    defaultValue: '',
-  },
-  {
-    key: 'smtp_pass_override',
-    label: 'SMTP password override',
-    description: 'Optional. Stored in plain text — only set when overriding env credentials.',
-    type: 'password',
-    defaultValue: '',
-  },
-];
+import { PageHeader } from '@/components/shared/page-header';
+import { RegistryDrivenForm } from '@/components/admin/shared/registry-driven-form';
+import { SalesEmailConfigCard } from '@/components/admin/sales-email-config-card';
+import { EmailRoutingCard } from '@/components/admin/email-routing-card';
+import { SmtpTestSendCard } from '@/components/admin/email/smtp-test-send-card';
+import { TestTemplateCard } from '@/components/admin/email/test-template-card';
 
 export default function EmailSettingsPage() {
   return (
     <div className="space-y-6">
       <PageHeader
         title="Email Settings"
-        description="Per-port outgoing email configuration. SMTP credentials and the From address default to environment variables when these fields are blank."
+        description="Per-port outgoing email configuration. SMTP credentials and the From address default to environment variables when these fields are blank. Header/footer HTML lives under Branding."
       />
-      <SettingsFormCard
-        title="From address & signature"
-        description="Identity headers and shared HTML used by system-generated emails."
-        fields={FIELDS.slice(0, 5)}
+
+      {/* Explainer for the "two accounts" model - addresses the recurring
+          UAT question "why are there separate SMTP credentials for sales
+          and noreply?". Keeps the answer in front of the admin before
+          they reach the per-card form below. */}
+      <div className="rounded-md border border-border bg-muted/40 px-4 py-3 text-sm">
+        <div className="flex items-start gap-2">
+          <Info className="mt-0.5 size-4 shrink-0 text-muted-foreground" aria-hidden />
+          <div className="space-y-1 text-muted-foreground">
+            <p>
+              <strong className="text-foreground">Why two accounts?</strong> Transactional emails
+              (signing invites, notifications, password resets) ship from your noreply mailbox over
+              the SMTP credentials below. Rep-authored sales emails (one-off messages, proposal
+              sends) ship from the sales mailbox with separate credentials so replies land in a
+              human-monitored inbox.
+            </p>
+            <p>
+              The noreply credentials are also used by the supplemental-info workflow + portal
+              activation, i.e. anywhere the platform sends on its own initiative. The sales
+              credentials are only used when a rep clicks Send in the compose UI.
+            </p>
+          </div>
+        </div>
+      </div>
+
+      {/* Registry-driven so each field shows the "Using env fallback /
+          port / global / default" badge inline - admins can tell at a
+          glance which fields are coming from .env vs. UI overrides. */}
+      <RegistryDrivenForm
+        sections={['email.from']}
+        title="From address (noreply)"
+        description="Identity headers used by system-generated emails. Set the From + Reply-To here; the matching SMTP credentials live in the next card."
       />
-      <SettingsFormCard
-        title="SMTP transport overrides"
-        description="Optional per-port SMTP credentials. Leave blank to use the global env defaults."
-        fields={FIELDS.slice(5)}
+      <RegistryDrivenForm
+        sections={['email.smtp']}
+        title="SMTP transport overrides (noreply)"
+        description="Optional per-port SMTP credentials for the noreply mailbox. Leave blank to use the global env defaults. Each field shows its current source (env / port / default) so you can tell what's active without checking the deploy."
       />
+      <SmtpTestSendCard />
+      <TestTemplateCard />
+      <SalesEmailConfigCard />
+      <EmailRoutingCard />
     </div>
   );
 }

src/app/(dashboard)/[portSlug]/admin/errors/[requestId]/page.tsx

@@ -0,0 +1,249 @@
+'use client';
+
+import Link from 'next/link';
+import { useParams } from 'next/navigation';
+import { useQuery } from '@tanstack/react-query';
+import { format } from 'date-fns';
+import { Copy, Wrench } from 'lucide-react';
+import { toast } from 'sonner';
+
+import type { Route } from 'next';
+
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { ERROR_CODES, isErrorCode } from '@/lib/error-codes';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Skeleton } from '@/components/ui/skeleton';
+import { apiFetch } from '@/lib/api/client';
+import { useBreadcrumbHint } from '@/hooks/use-breadcrumb-hint';
+import type { ErrorEvent } from '@/lib/db/schema/system';
+import type { LikelyCulprit } from '@/lib/error-classifier';
+
+interface DetailResponse {
+  data: ErrorEvent & { likelyCulprit: LikelyCulprit | null };
+}
+
+/**
+ * Detail view for a single captured error. Shows everything an admin
+ * needs to triage:
+ *
+ *  - Request shape: method, path, status, duration, who fired it
+ *  - Error: name, message, full stack head, (sanitized) request body
+ *  - Likely-culprit hint: heuristic-driven plain-English root-cause
+ *  - Raw metadata: pg SQLSTATE codes, internal-message debug strings
+ */
+export default function ErrorEventDetailPage() {
+  const params = useParams<{ portSlug: string; requestId: string }>();
+  const portSlug = params?.portSlug ?? '';
+  const requestId = params?.requestId ?? '';
+
+  // Smart-back target: send the user back to the error list, not the
+  // generic Administration page that URL-derivation would land on.
+  useBreadcrumbHint(
+    portSlug
+      ? {
+          parents: [{ label: 'Error inspector', href: `/${portSlug}/admin/errors` }],
+          current: `Error ${requestId.slice(0, 8)}…`,
+        }
+      : null,
+  );
+
+  const query = useQuery<DetailResponse>({
+    queryKey: ['admin', 'error-events', requestId],
+    queryFn: () => apiFetch<DetailResponse>(`/api/v1/admin/error-events/${requestId}`),
+    enabled: Boolean(requestId),
+  });
+
+  function copy(text: string, label: string) {
+    if (typeof navigator === 'undefined' || !navigator.clipboard) return;
+    void navigator.clipboard.writeText(text);
+    toast.success(`${label} copied`);
+  }
+
+  if (query.isLoading) {
+    return (
+      <div className="space-y-3">
+        <Skeleton className="h-8 w-48" />
+        <Skeleton className="h-32 w-full" />
+        <Skeleton className="h-64 w-full" />
+      </div>
+    );
+  }
+
+  const event = query.data?.data;
+  if (!event) {
+    return (
+      <Card>
+        <CardContent className="py-12 text-center text-sm text-muted-foreground">
+          Error event not found. It may have been pruned or you may not have access.
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-2 flex-wrap">
+        <h1 className="text-2xl font-bold">Error {requestId.slice(0, 8)}…</h1>
+        <Badge
+          variant="outline"
+          className={
+            event.statusCode >= 500
+              ? 'border-destructive/40 text-destructive'
+              : 'border-amber-300 text-amber-800'
+          }
+        >
+          {event.statusCode}
+        </Badge>
+        {event.likelyCulprit && (
+          <Badge variant="secondary" className="gap-1">
+            <Wrench className="h-3 w-3" />
+            {event.likelyCulprit.label}
+          </Badge>
+        )}
+        <Button size="sm" variant="ghost" onClick={() => copy(requestId, 'Reference ID')}>
+          <Copy className="mr-1.5 h-3 w-3" />
+          Copy ID
+        </Button>
+      </div>
+
+      {event.likelyCulprit && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium flex items-center gap-2">
+              <Wrench className="h-4 w-4" /> Likely culprit
+            </CardTitle>
+          </CardHeader>
+          <CardContent className="text-sm">
+            <p className="font-medium">{event.likelyCulprit.label}</p>
+            <p className="text-muted-foreground mt-1">{event.likelyCulprit.hint}</p>
+            <p className="text-xs text-muted-foreground mt-2">
+              Subsystem: <code className="font-mono">{event.likelyCulprit.subsystem}</code>
+            </p>
+          </CardContent>
+        </Card>
+      )}
+
+      {/* If the captured error has a registered code on its metadata,
+       *  surface the canonical user-facing message + status from the
+       *  registry so the admin can compare what the user saw to what
+       *  the system actually did. */}
+      {(() => {
+        const meta = (event.metadata ?? {}) as Record<string, unknown>;
+        const code = typeof meta.code === 'string' ? meta.code : null;
+        if (!code || !isErrorCode(code)) return null;
+        const def = ERROR_CODES[code];
+        return (
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-sm font-medium">Error code</CardTitle>
+            </CardHeader>
+            <CardContent className="space-y-1 text-sm">
+              <div className="flex items-center gap-2">
+                <Badge variant="outline">{def.status}</Badge>
+                <code className="font-mono text-xs font-semibold">{code}</code>
+              </div>
+              <p className="mt-2">{def.userMessage}</p>
+              <p className="text-xs text-muted-foreground">
+                Compare to the message the user saw in their toast.{' '}
+                <Link
+                  href={`/${portSlug}/admin/errors/codes` as Route}
+                  className="text-primary hover:underline"
+                >
+                  All codes →
+                </Link>
+              </p>
+            </CardContent>
+          </Card>
+        );
+      })()}
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm font-medium">Request</CardTitle>
+        </CardHeader>
+        <CardContent className="grid grid-cols-1 md:grid-cols-2 gap-3 text-sm">
+          <KV label="Method" value={event.method} />
+          <KV label="Path" value={event.path} mono />
+          <KV label="When" value={format(new Date(event.createdAt), 'PPpp')} />
+          <KV label="Duration" value={event.durationMs ? `${event.durationMs} ms` : '-'} />
+          <KV label="Port" value={event.portId ?? '(none)'} mono />
+          <KV label="User" value={event.userId ?? '(none)'} mono />
+          <KV label="IP" value={event.ipAddress ?? '-'} mono />
+          <KV label="User agent" value={event.userAgent ?? '-'} />
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm font-medium">Error</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-3 text-sm">
+          <KV label="Name" value={event.errorName ?? '-'} mono />
+          <div>
+            <p className="text-xs text-muted-foreground">Message</p>
+            <p className="mt-0.5 font-mono whitespace-pre-wrap wrap-break-word">
+              {event.errorMessage ?? '-'}
+            </p>
+          </div>
+          {event.errorStack && (
+            <div>
+              <div className="flex items-center justify-between">
+                <p className="text-xs text-muted-foreground">Stack (truncated)</p>
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  onClick={() => copy(event.errorStack ?? '', 'Stack')}
+                >
+                  <Copy className="mr-1.5 h-3 w-3" /> Copy
+                </Button>
+              </div>
+              <pre className="mt-1 max-h-96 overflow-auto rounded bg-muted p-2 text-xs font-mono whitespace-pre-wrap wrap-break-word">
+                {event.errorStack}
+              </pre>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+
+      {event.requestBodyExcerpt && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              Request body (sanitized, max 1 KB)
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <pre className="max-h-64 overflow-auto rounded bg-muted p-2 text-xs font-mono whitespace-pre-wrap wrap-break-word">
+              {event.requestBodyExcerpt}
+            </pre>
+          </CardContent>
+        </Card>
+      )}
+
+      {event.metadata !== null &&
+        typeof event.metadata === 'object' &&
+        Object.keys(event.metadata as Record<string, unknown>).length > 0 && (
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-sm font-medium">Metadata</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <pre className="overflow-auto rounded bg-muted p-2 text-xs font-mono">
+                {JSON.stringify(event.metadata, null, 2)}
+              </pre>
+            </CardContent>
+          </Card>
+        )}
+    </div>
+  );
+}
+
+function KV({ label, value, mono }: { label: string; value: string | null; mono?: boolean }) {
+  return (
+    <div>
+      <p className="text-xs text-muted-foreground">{label}</p>
+      <p className={`mt-0.5 ${mono ? 'font-mono text-xs' : ''}`}>{value ?? '-'}</p>
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/errors/codes/page.tsx

@@ -0,0 +1,133 @@
+'use client';
+
+import { useState, useMemo } from 'react';
+import { useParams } from 'next/navigation';
+import { BookOpen, Search } from 'lucide-react';
+
+import { Badge } from '@/components/ui/badge';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+import { useBreadcrumbHint } from '@/hooks/use-breadcrumb-hint';
+import { ERROR_CODES } from '@/lib/error-codes';
+
+/**
+ * Error-code reference page surfaced inside the admin section so an
+ * admin investigating a captured error_events row can flip to this
+ * tab, look up the code the user reported, and read the canonical
+ * plain-language meaning + status code without leaving the app.
+ *
+ * Pulls directly from `src/lib/error-codes.ts` so it stays in sync
+ * automatically - adding an entry to the registry adds a row here.
+ */
+export default function ErrorCodeReferencePage() {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+  const [search, setSearch] = useState('');
+
+  // Smart-back target: send the user back to the error inspector, not
+  // the generic Administration page URL-derivation would land on.
+  useBreadcrumbHint(
+    portSlug
+      ? {
+          parents: [{ label: 'Error inspector', href: `/${portSlug}/admin/errors` }],
+          current: 'Error code reference',
+        }
+      : null,
+  );
+
+  const entries = useMemo(() => {
+    const all = Object.entries(ERROR_CODES) as Array<
+      [string, (typeof ERROR_CODES)[keyof typeof ERROR_CODES]]
+    >;
+    if (!search.trim()) return all;
+    const q = search.trim().toLowerCase();
+    return all.filter(
+      ([code, def]) => code.toLowerCase().includes(q) || def.userMessage.toLowerCase().includes(q),
+    );
+  }, [search]);
+
+  // Group by domain prefix (the part before the first underscore) so
+  // the table reads naturally - Expenses, Berths, Storage, etc.
+  const grouped = useMemo(() => {
+    const groups = new Map<string, typeof entries>();
+    for (const entry of entries) {
+      const prefix = entry[0].split('_')[0] ?? 'OTHER';
+      const bucket = groups.get(prefix) ?? [];
+      bucket.push(entry);
+      groups.set(prefix, bucket);
+    }
+    return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b));
+  }, [entries]);
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-start justify-between gap-4 flex-wrap">
+        <div>
+          <h1 className="text-2xl font-bold flex items-center gap-2">
+            <BookOpen className="h-5 w-5" /> Error code reference
+          </h1>
+          <p className="text-muted-foreground text-sm mt-1">
+            Every error code the platform can return, with its HTTP status and the plain-language
+            message a user sees. Codes are stable identifiers - once shipped, they never get
+            renamed.
+          </p>
+        </div>
+      </div>
+
+      <div className="relative max-w-md">
+        <Search className="pointer-events-none absolute left-2 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+        <Input
+          placeholder="Search code or message…"
+          value={search}
+          onChange={(e) => setSearch(e.target.value)}
+          className="pl-8"
+        />
+      </div>
+
+      {grouped.length === 0 ? (
+        <Card>
+          <CardContent className="py-12 text-center text-sm text-muted-foreground">
+            No codes match &quot;{search}&quot;.
+          </CardContent>
+        </Card>
+      ) : (
+        <div className="space-y-4">
+          {grouped.map(([prefix, items]) => (
+            <Card key={prefix}>
+              <CardHeader>
+                <CardTitle className="text-sm font-medium uppercase tracking-wider text-muted-foreground">
+                  {prefix}
+                </CardTitle>
+              </CardHeader>
+              <CardContent className="divide-y">
+                {items.map(([code, def]) => (
+                  <div key={code} className="flex items-start gap-3 py-3 first:pt-0 last:pb-0">
+                    <Badge
+                      variant="outline"
+                      className={
+                        def.status >= 500
+                          ? 'border-destructive/40 text-destructive'
+                          : def.status >= 400
+                            ? 'border-amber-300 text-amber-800'
+                            : 'border-muted'
+                      }
+                    >
+                      {def.status}
+                    </Badge>
+                    <div className="flex-1 min-w-0">
+                      <p className="font-mono text-xs font-semibold">{code}</p>
+                      <p className="text-sm mt-0.5">{def.userMessage}</p>
+                      {'hint' in def && typeof def.hint === 'string' && (
+                        <p className="text-xs text-muted-foreground mt-0.5">{def.hint}</p>
+                      )}
+                    </div>
+                  </div>
+                ))}
+              </CardContent>
+            </Card>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/errors/page.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+import { useState } from 'react';
+import Link from 'next/link';
+import { useParams } from 'next/navigation';
+import { useQuery } from '@tanstack/react-query';
+import { format, formatDistanceToNow } from 'date-fns';
+import { AlertTriangle, BookOpen, Search, Wrench } from 'lucide-react';
+
+import type { Route } from 'next';
+
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+import { Skeleton } from '@/components/ui/skeleton';
+import { PageHeader } from '@/components/shared/page-header';
+import { EmptyState } from '@/components/shared/empty-state';
+import { apiFetch } from '@/lib/api/client';
+import { classifyError } from '@/lib/error-classifier';
+import type { ErrorEvent } from '@/lib/db/schema/system';
+
+interface ListResponse {
+  data: ErrorEvent[];
+}
+
+/**
+ * Super-admin error inspector.
+ *
+ * Shows the most recent captured 5xx errors with: when, where (HTTP
+ * method + path), what (error name + message), and a heuristic
+ * "likely culprit" badge driven by `classifyError`. Click into any
+ * row for the full stack + body excerpt + raw metadata.
+ */
+export default function AdminErrorsPage() {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+  const [statusFilter, setStatusFilter] = useState('');
+
+  const query = useQuery<ListResponse>({
+    queryKey: ['admin', 'error-events', { statusFilter }],
+    queryFn: () => {
+      const search = new URLSearchParams();
+      if (statusFilter) search.set('statusCode', statusFilter);
+      return apiFetch<ListResponse>(
+        `/api/v1/admin/error-events${search.toString() ? `?${search.toString()}` : ''}`,
+      );
+    },
+  });
+
+  const events = query.data?.data ?? [];
+
+  return (
+    <div className="space-y-4">
+      <PageHeader
+        title="Error inspector"
+        description="Captured 5xx errors. Click any row for the full stack, request body excerpt, and likely culprit."
+        actions={
+          <Button variant="outline" size="sm" asChild>
+            <Link href={`/${portSlug}/admin/errors/codes` as Route}>
+              <BookOpen className="mr-1.5 h-4 w-4" />
+              Code reference
+            </Link>
+          </Button>
+        }
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm font-medium flex items-center gap-2">
+            <Search className="h-4 w-4" /> Filters
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="flex flex-wrap items-end gap-3">
+          <div className="space-y-1">
+            <label className="text-xs text-muted-foreground" htmlFor="status">
+              Status code
+            </label>
+            <Input
+              id="status"
+              placeholder="e.g. 500"
+              value={statusFilter}
+              onChange={(e) => setStatusFilter(e.target.value.replace(/\D/g, ''))}
+              className="h-8 w-32"
+            />
+          </div>
+          {statusFilter && (
+            <Button variant="ghost" size="sm" className="h-8" onClick={() => setStatusFilter('')}>
+              Clear
+            </Button>
+          )}
+        </CardContent>
+      </Card>
+
+      {query.isLoading ? (
+        <div className="space-y-2">
+          {Array.from({ length: 5 }).map((_, i) => (
+            <Skeleton key={i} className="h-14 w-full" />
+          ))}
+        </div>
+      ) : events.length === 0 ? (
+        <EmptyState
+          icon={AlertTriangle}
+          title="No captured errors"
+          description="Nothing has hit a 5xx in the selected window. That's a good thing."
+        />
+      ) : (
+        <div className="rounded-lg border divide-y">
+          {events.map((event) => {
+            const culprit = classifyError(event);
+            return (
+              <Link
+                key={event.requestId}
+                href={`/${portSlug}/admin/errors/${event.requestId}` as Route}
+                className="flex items-start gap-3 p-3 hover:bg-muted/40"
+              >
+                <div className="flex-1 min-w-0">
+                  <div className="flex items-center gap-2">
+                    <Badge
+                      variant="outline"
+                      className={
+                        event.statusCode >= 500
+                          ? 'border-destructive/40 text-destructive'
+                          : 'border-amber-300 text-amber-800'
+                      }
+                    >
+                      {event.statusCode}
+                    </Badge>
+                    <span className="text-xs font-mono uppercase text-muted-foreground">
+                      {event.method}
+                    </span>
+                    <span className="text-sm font-medium truncate">{event.path}</span>
+                    {culprit && (
+                      <Badge variant="secondary" className="gap-1 text-xs">
+                        <Wrench className="h-3 w-3" />
+                        {culprit.label}
+                      </Badge>
+                    )}
+                  </div>
+                  <p className="text-xs text-muted-foreground truncate mt-0.5">
+                    {event.errorName ? `${event.errorName}: ` : ''}
+                    {event.errorMessage ?? '(no message)'}
+                  </p>
+                  <p className="text-xs text-muted-foreground mt-0.5">
+                    {formatDistanceToNow(new Date(event.createdAt), { addSuffix: true })} ·{' '}
+                    {format(new Date(event.createdAt), 'MMM d HH:mm:ss')} · ID{' '}
+                    <code className="font-mono">{event.requestId.slice(0, 12)}…</code>
+                  </p>
+                </div>
+              </Link>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/import/page.tsx

@@ -1,14 +1,75 @@
 import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 
 export default function DataImportPage() {
   return (
-    <div className="space-y-6">
-      <PageHeader title="Data Import" description="Import data from external sources" />
-      <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-12">
-        <p className="text-lg font-medium text-muted-foreground">Coming in Layer 4</p>
-        <p className="text-sm text-muted-foreground">
-          This feature will be implemented in the next phase.
-        </p>
+    <div>
+      <PageHeader
+        title="Data import"
+        description="What you can import today and what an in-app importer will look like."
+      />
+
+      <div className="grid gap-4 mt-6 lg:grid-cols-2">
+        <Card>
+          <CardHeader>
+            <CardTitle>Available imports today</CardTitle>
+            <CardDescription>Run from the command line until the UI catches up.</CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-3 text-sm">
+            <div>
+              <p>
+                <strong>Berths from NocoDB:</strong>
+              </p>
+              <pre className="bg-muted/40 rounded-md p-2 text-xs mt-1 overflow-auto">
+                pnpm tsx scripts/import-berths-from-nocodb.ts --apply --port-slug port-nimara
+              </pre>
+              <p className="text-xs text-muted-foreground mt-1">
+                Idempotent. Skips rows where <code>updated_at &gt; last_imported_at</code> unless
+                you pass <code>--force</code>. Add <code>--update-snapshot</code> to also rewrite{' '}
+                <code>src/lib/db/seed-data/berths.json</code>.
+              </p>
+            </div>
+            <div>
+              <p>
+                <strong>Storage backend migration:</strong>
+              </p>
+              <pre className="bg-muted/40 rounded-md p-2 text-xs mt-1 overflow-auto">
+                pnpm tsx scripts/migrate-storage.ts
+              </pre>
+              <p className="text-xs text-muted-foreground mt-1">
+                Run after switching <code>system_settings.storage_backend</code> in System Settings.
+              </p>
+            </div>
+            <div>
+              <p>
+                <strong>Seed (rebuild dev fixtures):</strong>
+              </p>
+              <pre className="bg-muted/40 rounded-md p-2 text-xs mt-1 overflow-auto">
+                pnpm db:seed
+              </pre>
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>What this page will become</CardTitle>
+            <CardDescription>Planned UI for self-serve imports.</CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-2 text-sm">
+            <ul className="list-disc pl-5 space-y-1">
+              <li>Drag-and-drop CSV / XLSX upload with column-mapping UI.</li>
+              <li>Dry-run preview that shows new vs. matched-existing rows before commit.</li>
+              <li>Conflict-resolution choices (skip, update, dedup-by-email) per import type.</li>
+              <li>Per-port import history with rollback.</li>
+              <li>Templates for clients, yachts, companies, berths, tenancies, expenses.</li>
+            </ul>
+            <p className="text-xs text-muted-foreground pt-2">
+              Imports run against the BullMQ <code>import</code> queue (concurrency 1) so partial
+              failures don&rsquo;t leave the database half-loaded.
+            </p>
+          </CardContent>
+        </Card>
       </div>
     </div>
   );

src/app/(dashboard)/[portSlug]/admin/inquiries/page.tsx

@@ -0,0 +1,5 @@
+import { InquiryInbox } from '@/components/admin/inquiry-inbox';
+
+export default function InquiriesPage() {
+  return <InquiryInbox />;
+}

src/app/(dashboard)/[portSlug]/admin/invitations/page.tsx

@@ -1,14 +1,15 @@
-import { InvitationsManager } from '@/components/admin/invitations/invitations-manager';
-import { PageHeader } from '@/components/shared/page-header';
+import { redirect } from 'next/navigation';
 
-export default function InvitationsPage() {
-  return (
-    <div className="space-y-6">
-      <PageHeader
-        title="Invitations"
-        description="Send a single-use invitation to a new CRM user. The recipient sets their own password via the link in the email."
-      />
-      <InvitationsManager />
-    </div>
-  );
+/**
+ * 2026-05-21: /admin/invitations was merged into /admin/users (Users +
+ * Invitations tabs on a single page). This stub keeps old bookmarks +
+ * external links working by redirecting to the canonical destination.
+ */
+export default async function InvitationsRedirectPage({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  redirect(`/${portSlug}/admin/users`);
 }

src/app/(dashboard)/[portSlug]/admin/layout.tsx

@@ -1,14 +1,23 @@
+import Link from 'next/link';
 import { redirect } from 'next/navigation';
 import { headers } from 'next/headers';
 import { eq } from 'drizzle-orm';
+import { ShieldX } from 'lucide-react';
 
 import { auth } from '@/lib/auth';
 import { db } from '@/lib/db';
 import { userProfiles } from '@/lib/db/schema/users';
+import { Button } from '@/components/ui/button';
 
 /**
- * Guard: only super-admins (isSuperAdmin === true in user_profiles) may access
- * any page under /[portSlug]/admin. Everyone else is redirected to their dashboard.
+ * Guard: only super-admins (isSuperAdmin === true in user_profiles) may
+ * access any page under /[portSlug]/admin.
+ *
+ * H-15: previously this layout silently redirected non-admins to
+ * `/dashboard`, which left them staring at the dashboard with no
+ * explanation of why their bookmark / shared admin link "didn't work".
+ * Render an explicit 403 page instead so the URL stays on the failed
+ * route and the user can see why their request was denied.
  */
 export default async function AdminLayout({
   children,
@@ -29,7 +38,23 @@ export default async function AdminLayout({
   });
 
   if (!profile?.isSuperAdmin) {
-    redirect(`/${portSlug}/dashboard`);
+    return (
+      <div className="flex min-h-[60vh] flex-col items-center justify-center gap-4 px-4 text-center">
+        <div className="flex h-14 w-14 items-center justify-center rounded-full bg-destructive/10">
+          <ShieldX className="h-7 w-7 text-destructive" aria-hidden />
+        </div>
+        <div className="space-y-1">
+          <h1 className="text-xl font-semibold">Access denied</h1>
+          <p className="max-w-md text-sm text-muted-foreground">
+            This area is for super-administrators only. If you believe you should have access, ask
+            an administrator to grant the super-admin role on your account.
+          </p>
+        </div>
+        <Button asChild>
+          <Link href={`/${portSlug}/dashboard`}>Back to dashboard</Link>
+        </Button>
+      </div>
+    );
   }
 
   return <>{children}</>;

src/app/(dashboard)/[portSlug]/admin/ocr/page.tsx

@@ -1,5 +1,19 @@
-import { OcrSettingsForm } from '@/components/admin/ocr-settings-form';
+import { redirect } from 'next/navigation';
 
-export default function OcrSettingsPage() {
-  return <OcrSettingsForm />;
+/**
+ * Legacy route. OCR settings now live on the consolidated AI panel at
+ * `/admin/ai` (the same `<OcrSettingsForm>` is mounted there alongside
+ * the master AI switch + provider credentials). Kept as a redirect-only
+ * page so any bookmarks / docs / deep links land on the right surface.
+ *
+ * Slated for full removal once the 2026-05-22 admin IA migration has
+ * had a quarter to bed in.
+ */
+export default async function OcrLegacyRedirectPage({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  redirect(`/${portSlug}/admin/ai`);
 }

src/app/(dashboard)/[portSlug]/admin/onboarding/page.tsx

@@ -1,15 +1,14 @@
+import { OnboardingChecklist } from '@/components/admin/onboarding-checklist';
 import { PageHeader } from '@/components/shared/page-header';
 
 export default function OnboardingPage() {
   return (
-    <div className="space-y-6">
-      <PageHeader title="Onboarding" description="Guided setup for new port configurations" />
-      <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-12">
-        <p className="text-lg font-medium text-muted-foreground">Coming in Layer 4</p>
-        <p className="text-sm text-muted-foreground">
-          This feature will be implemented in the next phase.
-        </p>
-      </div>
+    <div>
+      <PageHeader
+        title="Port onboarding"
+        description="Bring a new port live. Each step links to the right admin page; checks update automatically once you've configured the underlying setting."
+      />
+      <OnboardingChecklist />
     </div>
   );
 }

src/app/(dashboard)/[portSlug]/admin/page.tsx

@@ -1,162 +1,5 @@
-import Link from 'next/link';
-import {
-  Bell,
-  Briefcase,
-  Database,
-  FileText,
-  HardDrive,
-  Key,
-  LayoutDashboard,
-  Mail,
-  Palette,
-  ScrollText,
-  Settings,
-  Shield,
-  Sliders,
-  Tag,
-  Upload,
-  Users,
-  Webhook,
-} from 'lucide-react';
-
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { PageHeader } from '@/components/shared/page-header';
-
-interface AdminSection {
-  href: string;
-  label: string;
-  description: string;
-  icon: typeof Settings;
-}
-
-const SECTIONS: AdminSection[] = [
-  {
-    href: 'users',
-    label: 'Users',
-    description: 'CRM accounts, role assignments, and per-user residential access toggles.',
-    icon: Users,
-  },
-  {
-    href: 'invitations',
-    label: 'Invitations',
-    description: 'Send invitations, track pending invites, and resend or revoke them.',
-    icon: Mail,
-  },
-  {
-    href: 'roles',
-    label: 'Roles & Permissions',
-    description: 'Default permission sets and per-port role overrides.',
-    icon: Shield,
-  },
-  {
-    href: 'audit',
-    label: 'Audit Log',
-    description: 'Searchable log of every authenticated mutation in the system.',
-    icon: ScrollText,
-  },
-  {
-    href: 'email',
-    label: 'Email Settings',
-    description: 'From address, signatures, and per-port SMTP overrides.',
-    icon: Mail,
-  },
-  {
-    href: 'documenso',
-    label: 'Documenso & EOI',
-    description: 'API credentials, EOI template, and default in-app vs Documenso pathway.',
-    icon: FileText,
-  },
-  {
-    href: 'reminders',
-    label: 'Reminders',
-    description: 'Default reminder behaviour and the daily-digest delivery window.',
-    icon: Bell,
-  },
-  {
-    href: 'branding',
-    label: 'Branding',
-    description: 'App name, logo, primary color, and email header/footer HTML.',
-    icon: Palette,
-  },
-  {
-    href: 'settings',
-    label: 'System Settings',
-    description: 'Generic key/value configuration store for advanced flags.',
-    icon: Settings,
-  },
-  {
-    href: 'webhooks',
-    label: 'Webhooks',
-    description: 'Outgoing webhook subscriptions, secrets, and delivery log.',
-    icon: Webhook,
-  },
-  {
-    href: 'forms',
-    label: 'Forms',
-    description: 'Form templates used by client-facing inquiry and intake flows.',
-    icon: Sliders,
-  },
-  {
-    href: 'templates',
-    label: 'Document Templates',
-    description: 'PDF + email templates with merge-field placeholders.',
-    icon: FileText,
-  },
-  {
-    href: 'tags',
-    label: 'Tags',
-    description: 'Color-coded tags applied to clients, yachts, companies, and interests.',
-    icon: Tag,
-  },
-  {
-    href: 'custom-fields',
-    label: 'Custom Fields',
-    description: 'Tenant-defined fields for clients, yachts, and reservations.',
-    icon: Key,
-  },
-  {
-    href: 'reports',
-    label: 'Reports',
-    description: 'Saved analytics views and ad-hoc query results.',
-    icon: LayoutDashboard,
-  },
-  {
-    href: 'monitoring',
-    label: 'Queue Monitoring',
-    description: 'BullMQ queue health, throughput, and retry diagnostics.',
-    icon: Database,
-  },
-  {
-    href: 'import',
-    label: 'Bulk Import',
-    description: 'CSV-driven imports for clients, yachts, and reservations.',
-    icon: Upload,
-  },
-  {
-    href: 'backup',
-    label: 'Backup & Restore',
-    description: 'Database snapshots and on-demand exports.',
-    icon: HardDrive,
-  },
-  {
-    href: 'ports',
-    label: 'Ports',
-    description: 'Manage the marinas/ports this installation serves.',
-    icon: Briefcase,
-  },
-  {
-    href: 'onboarding',
-    label: 'Onboarding',
-    description: 'Initial-setup wizard for fresh ports.',
-    icon: LayoutDashboard,
-  },
-  {
-    href: 'ocr',
-    label: 'Receipt OCR',
-    description: 'Configure the AI provider used by the mobile receipt scanner.',
-    icon: ScrollText,
-  },
-];
+import { AdminSectionsBrowser } from '@/components/admin/admin-sections-browser';
 
 export default async function AdminLandingPage({
   params,
@@ -165,36 +8,12 @@ export default async function AdminLandingPage({
 }) {
   const { portSlug } = await params;
   return (
-    <div className="space-y-6">
+    <div className="space-y-8">
       <PageHeader
         title="Administration"
-        description="Per-port configuration and system administration. Each card below opens a dedicated settings page."
+        description="Per-port configuration and system administration. Use the search to jump to a setting, or browse the grouped index below."
       />
-      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
-        {SECTIONS.map((s) => {
-          const Icon = s.icon;
-          return (
-            <Link
-              key={s.href}
-              // eslint-disable-next-line @typescript-eslint/no-explicit-any
-              href={`/${portSlug}/admin/${s.href}` as any}
-              className="block group"
-            >
-              <Card className="h-full transition-colors group-hover:border-primary/50 group-hover:bg-muted/30">
-                <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
-                  <Icon className="h-5 w-5 mt-0.5 text-muted-foreground group-hover:text-primary" />
-                  <div className="flex-1">
-                    <CardTitle className="text-base">{s.label}</CardTitle>
-                  </div>
-                </CardHeader>
-                <CardContent>
-                  <CardDescription>{s.description}</CardDescription>
-                </CardContent>
-              </Card>
-            </Link>
-          );
-        })}
-      </div>
+      <AdminSectionsBrowser portSlug={portSlug} />
     </div>
   );
 }

src/app/(dashboard)/[portSlug]/admin/pipeline-rules/page.tsx

@@ -0,0 +1,264 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Loader2, Save } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
+
+type Mode = 'auto' | 'suggest' | 'off';
+
+const TRIGGERS: Array<{
+  key: string;
+  label: string;
+  description: string;
+  defaultMode: Mode;
+}> = [
+  {
+    key: 'eoi_sent',
+    label: 'EOI sent',
+    description: 'Rep generates an EOI for signing  -  moves the deal to "EOI" stage.',
+    defaultMode: 'auto',
+  },
+  {
+    key: 'eoi_signed',
+    label: 'EOI signed (all parties)',
+    description:
+      'All signatories complete the EOI  -  moves the deal to "Reservation" stage. Conventional CRM behaviour.',
+    defaultMode: 'auto',
+  },
+  {
+    key: 'reservation_signed',
+    label: 'Reservation agreement signed',
+    description:
+      'Reservation paperwork signed by all parties  -  keeps the deal at "Reservation" with sub-status signed.',
+    defaultMode: 'auto',
+  },
+  {
+    key: 'deposit_received',
+    label: 'Deposit received in full',
+    description:
+      'Deposit total reaches the expected amount  -  moves the deal to "Deposit Paid" stage.',
+    defaultMode: 'auto',
+  },
+  {
+    key: 'contract_signed',
+    label: 'Sales contract signed',
+    description: 'Final contract signed by all parties  -  moves the deal to "Contract" stage.',
+    defaultMode: 'auto',
+  },
+];
+
+const PRESETS = {
+  aggressive: 'auto',
+  conservative: 'suggest',
+} as const;
+type PresetName = keyof typeof PRESETS;
+
+export default function PipelineRulesPage() {
+  const queryClient = useQueryClient();
+  const [rules, setRules] = useState<Record<string, Mode>>(() =>
+    Object.fromEntries(TRIGGERS.map((t) => [t.key, t.defaultMode])),
+  );
+
+  const { data, isLoading } = useQuery<{
+    data: { values: Record<string, { value?: Record<string, Mode> | null }> };
+  }>({
+    queryKey: ['admin', 'settings', 'pipeline.auto_advance'],
+    queryFn: () =>
+      apiFetch<{
+        data: { values: Record<string, { value?: Record<string, Mode> | null }> };
+      }>('/api/v1/admin/settings/resolved?sections=pipeline.auto_advance'),
+  });
+
+  // Hydrate the local form once the server-side state arrives. We treat
+  // missing keys as the registered default - the page's persisted JSON
+  // doesn't have to enumerate every trigger, just the overrides.
+  useEffect(() => {
+    const persisted = data?.data?.values?.stage_advance_rules?.value;
+    if (!persisted || typeof persisted !== 'object') return;
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setRules((prev) => {
+      const next = { ...prev };
+      for (const t of TRIGGERS) {
+        const v = persisted[t.key];
+        if (v === 'auto' || v === 'suggest' || v === 'off') next[t.key] = v;
+      }
+      return next;
+    });
+  }, [data]);
+
+  const saveMutation = useMutation({
+    mutationFn: () =>
+      apiFetch('/api/v1/admin/settings/stage_advance_rules', {
+        method: 'PUT',
+        body: { value: rules },
+      }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['admin', 'settings'] });
+      toast.success('Pipeline rules saved.');
+    },
+    onError: (err) => toastError(err),
+  });
+
+  const applyPreset = (preset: PresetName) => {
+    const target = PRESETS[preset];
+    setRules(Object.fromEntries(TRIGGERS.map((t) => [t.key, target])));
+  };
+
+  const setMode = (key: string, mode: Mode) => {
+    setRules((prev) => ({ ...prev, [key]: mode }));
+  };
+
+  const allMatch = (mode: Mode) => TRIGGERS.every((t) => rules[t.key] === mode);
+  const currentPreset: PresetName | 'custom' = allMatch('auto')
+    ? 'aggressive'
+    : allMatch('suggest')
+      ? 'conservative'
+      : 'custom';
+
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Pipeline auto-advance rules"
+        description="Control which lifecycle events (signing, payments) automatically advance the deal stage on the kanban. Choose a preset or fine-tune per trigger."
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base">Preset</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-3">
+          <div className="grid gap-2 sm:grid-cols-3">
+            <PresetButton
+              name="aggressive"
+              label="Aggressive (default)"
+              description="Every trigger auto-advances the stage. Matches conventional CRM behaviour and saves rep clicks."
+              active={currentPreset === 'aggressive'}
+              onClick={() => applyPreset('aggressive')}
+            />
+            <PresetButton
+              name="conservative"
+              label="Conservative"
+              description="Every trigger sends a notification suggesting the move. Reps click Approve to advance."
+              active={currentPreset === 'conservative'}
+              onClick={() => applyPreset('conservative')}
+            />
+            <div
+              className={`rounded-lg border p-3 ${
+                currentPreset === 'custom'
+                  ? 'border-primary bg-primary/5'
+                  : 'border-muted bg-muted/20'
+              }`}
+            >
+              <p className="text-sm font-semibold">Custom</p>
+              <p className="text-xs text-muted-foreground">
+                Mix and match - the per-trigger toggles below override the preset.
+              </p>
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base">Per-trigger settings</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {isLoading ? (
+            <div className="flex items-center gap-2 text-sm text-muted-foreground">
+              <Loader2 className="size-3.5 animate-spin" aria-hidden /> Loading…
+            </div>
+          ) : (
+            TRIGGERS.map((t) => (
+              <div
+                key={t.key}
+                className="flex flex-col gap-2 rounded-md border p-3 sm:flex-row sm:items-center sm:justify-between"
+              >
+                <div className="flex-1">
+                  <p className="text-sm font-medium">{t.label}</p>
+                  <p className="text-xs text-muted-foreground">{t.description}</p>
+                </div>
+                <div className="flex items-center gap-2">
+                  <Label htmlFor={`mode-${t.key}`} className="sr-only">
+                    Mode
+                  </Label>
+                  <Select
+                    value={rules[t.key] ?? t.defaultMode}
+                    onValueChange={(v) => setMode(t.key, v as Mode)}
+                  >
+                    <SelectTrigger id={`mode-${t.key}`} className="w-40">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      <SelectItem value="auto">Auto-advance</SelectItem>
+                      <SelectItem value="suggest">Suggest only</SelectItem>
+                      <SelectItem value="off">Off</SelectItem>
+                    </SelectContent>
+                  </Select>
+                </div>
+              </div>
+            ))
+          )}
+        </CardContent>
+      </Card>
+
+      <div className="flex justify-end">
+        <Button
+          onClick={() => saveMutation.mutate()}
+          disabled={saveMutation.isPending}
+          className="gap-1.5 [&_svg]:size-3.5"
+        >
+          {saveMutation.isPending ? <Loader2 className="animate-spin" aria-hidden /> : <Save />}
+          Save rules
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+function PresetButton({
+  name,
+  label,
+  description,
+  active,
+  onClick,
+}: {
+  name: PresetName;
+  label: string;
+  description: string;
+  active: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={`rounded-lg border p-3 text-left transition-colors ${
+        active
+          ? 'border-primary bg-primary/5 ring-2 ring-primary/40'
+          : 'border-muted hover:border-foreground/30 hover:bg-muted/30'
+      }`}
+      aria-pressed={active}
+    >
+      <p className="text-sm font-semibold">{label}</p>
+      <p className="text-xs text-muted-foreground">{description}</p>
+      <p className="mt-1 text-xs uppercase tracking-wide text-muted-foreground">
+        {name === 'aggressive' ? 'auto for all triggers' : 'suggest for all triggers'}
+      </p>
+    </button>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/pulse/page.tsx

@@ -0,0 +1,51 @@
+import Link from 'next/link';
+import { Activity } from 'lucide-react';
+
+import { RegistryDrivenForm } from '@/components/admin/shared/registry-driven-form';
+import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+
+export default function PulseAdminPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Deal Pulse"
+        description="Tune the chip that scores every interest's health. Toggle the chip off entirely, disable individual signals you don't want surfaced, or rename the tier labels per your sales vocabulary."
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2 text-base">
+            <Activity className="h-4 w-4" aria-hidden="true" />
+            How the pulse chip works
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-3 text-sm">
+          <p className="text-muted-foreground">
+            Every interest row carries a small coloured chip in the detail header. It scores the
+            deal from 0–100 using rule-based signals (no AI). Click the chip on any interest to see
+            the per-signal breakdown - every +N or -N traces back to a dated event on the deal.
+          </p>
+          <p className="text-muted-foreground">
+            Positive signals (recent EOI sent, deposit received, contract signed) push the score up.
+            Risk signals (declined documents, cancelled reservations, berth resold elsewhere) push
+            it down. Stale-contact and stage-stuck signals weigh both directions automatically.
+          </p>
+          <p className="text-muted-foreground">
+            See the full guide at{' '}
+            <Link href="/docs/deal-pulse" className="underline">
+              /docs/deal-pulse
+            </Link>
+            .
+          </p>
+        </CardContent>
+      </Card>
+
+      <RegistryDrivenForm
+        title="Pulse chip behaviour"
+        description="Master toggle, per-signal toggles, and per-port label overrides. Defaults: chip visible, all signals on, built-in tier names ('Hot' / 'Warm' / 'Cold')."
+        sections={['pulse']}
+      />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/qualification-criteria/page.tsx

@@ -0,0 +1,15 @@
+import { QualificationCriteriaAdmin } from '@/components/admin/qualification-criteria-admin';
+import { PageHeader } from '@/components/shared/page-header';
+
+export default function QualificationCriteriaPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Qualification criteria"
+        eyebrow="ADMIN"
+        description="Configure the checklist reps complete before an interest moves out of the Enquiry stage. Reorder, enable/disable, or add port-specific criteria. The 'fully qualified' hint on the interest detail surfaces when every enabled criterion is confirmed."
+      />
+      <QualificationCriteriaAdmin />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/reminders/page.tsx

@@ -44,9 +44,8 @@ const DIGEST_FIELDS: SettingFieldDef[] = [
   {
     key: 'reminder_digest_timezone',
     label: 'Digest timezone',
-    description: 'IANA timezone name used to interpret the delivery time (e.g. Europe/Warsaw).',
-    type: 'string',
-    placeholder: 'Europe/Warsaw',
+    description: 'IANA timezone name used to interpret the delivery time.',
+    type: 'timezone',
     defaultValue: 'Europe/Warsaw',
   },
 ];

src/app/(dashboard)/[portSlug]/admin/reports/page.tsx

@@ -1,18 +1,21 @@
-import { PageHeader } from '@/components/shared/page-header';
+import { redirect } from 'next/navigation';
 
-export default function ScheduledReportsPage() {
-  return (
-    <div className="space-y-6">
-      <PageHeader
-        title="Scheduled Reports"
-        description="Configure and manage automated report delivery"
-      />
-      <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-12">
-        <p className="text-lg font-medium text-muted-foreground">Coming in Layer 3</p>
-        <p className="text-sm text-muted-foreground">
-          This feature will be implemented in the next phase.
-        </p>
-      </div>
-    </div>
-  );
+/**
+ * 2026-05-22: `/admin/reports` deleted. The page rendered three cards
+ * - Pipeline funnel, Berth occupancy, and a KPI grid - all of which
+ * are already covered by the main Dashboard widgets (`pipeline_funnel`,
+ * `occupancy_timeline`, `kpi_*`). Redirecting to the dashboard so any
+ * lingering bookmarks land somewhere coherent.
+ *
+ * The `<ReportsDashboard>` component file lives on in the repo for now
+ * pending a follow-up sweep - once we confirm no other surface mounts
+ * it, the component + its data hook can be removed too.
+ */
+export default async function ReportsLegacyRedirectPage({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  redirect(`/${portSlug}/dashboard`);
 }