chore(style): codebase em-dash sweep + minor layout polish

Replaces every em-dash and en-dash with regular ASCII hyphens
across comments, JSX strings, and dev-facing logs. Mostly cosmetic
but stops the inconsistent mix that crept in over the last few
months (some files used em-dashes in comments, others didn't,
some used both).

Bundles two small dashboard-layout tweaks that touch a couple of
already-modified files:
- (dashboard)/layout.tsx main padding goes from p-6 to pt-3 px-6
  pb-6 so page content sits closer to the topbar.
- Sidebar now receives the ports list it needs for the footer
  port switcher.

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

.claude/scheduled_tasks.lock

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

.gitignore

@@ -20,10 +20,30 @@ tsconfig.tsbuildinfo
 docker-compose.override.yml
 .remember/
 .DS_Store
-eoi/
+# Root-only ad-hoc EOI scratch dir; routes under src/app/.../eoi/ must NOT match.
+/eoi/
 
 # Brainstorming companion mockup files
 .superpowers/
 
 # Ad-hoc screenshots / scratch artifacts at repo root
 /*.png
+/*.jpg
+
+# 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

docs/operations/outbound-comms-safety.md

@@ -0,0 +1,123 @@
+# Outbound communications safety net
+
+**Last reviewed:** 2026-05-03
+**Owner:** matt@portnimara.com
+
+This doc enumerates every channel through which the CRM can produce
+outbound communication (email, document signing, webhooks) and describes
+how each channel respects the `EMAIL_REDIRECT_TO` env var. The goal: a
+single environment flip pauses **all** outbound traffic, so a production
+data import, dedup migration dry-run, or staging environment can run
+against real data without anyone getting paged or spammed.
+
+> **Single env switch:** when `EMAIL_REDIRECT_TO` is set to an address,
+> all outbound communication is rerouted there or short-circuited. Unset
+> it in production.
+
+---
+
+## Channels
+
+### 1. Direct email (`sendEmail`)
+
+**Path:** `src/lib/email/index.ts` → `sendEmail()` → nodemailer SMTP transport.
+
+**Safety:** YES — covered.
+
+When `EMAIL_REDIRECT_TO` is set, `sendEmail()` rewrites the `to` header
+to the redirect address and prefixes the subject with
+`[redirected from <orig>]`. The original recipient is logged.
+
+**Call sites** (all flow through `sendEmail`, so all are covered):
+
+- `src/lib/services/portal-auth.service.ts` — portal activation + reset
+- `src/lib/services/crm-invite.service.ts` — CRM user invitations
+- `src/lib/services/document-templates.ts` — template-generated PDFs sent
+  as attachments (the PDF body is generated locally; the email itself
+  goes through SMTP)
+- `src/lib/services/email-compose.service.ts` — ad-hoc emails composed
+  in the in-app UI
+- `src/lib/services/gdpr-export.service.ts` — GDPR export delivery
+
+### 2. Documenso e-signature recipients
+
+**Path:** `src/lib/services/documenso-client.ts` → `createDocument()` /
+`generateDocumentFromTemplate()` → Documenso REST API.
+
+**Safety:** YES — covered as of 2026-05-03.
+
+Documenso's own server sends the signing-request email on our behalf.
+We can't intercept that at the SMTP layer because it's external. The
+fix is at the REST-call boundary: when `EMAIL_REDIRECT_TO` is set,
+`createDocument` rewrites every recipient's email to the redirect
+address and prefixes the recipient name with `(was: <orig email>)` so
+the doc is still traceable to its intended recipient.
+`generateDocumentFromTemplate` does the same for both shapes the
+template-generate endpoint accepts (v1.13 `formValues.*Email` keys and
+v2.x `recipients` array).
+
+The redirect happens **before** the API call, so even if Documenso has
+its own retry logic the original email never leaves our process.
+
+### 3. Webhooks (outbound to user-configured URLs)
+
+**Path:** `src/lib/queue/workers/webhooks.ts` → BullMQ job → `fetch(webhook.url, ...)`.
+
+**Safety:** YES — covered as of 2026-05-03.
+
+When `EMAIL_REDIRECT_TO` is set, the webhook worker short-circuits
+before the HTTP call. The delivery row is marked `dead_letter` with a
+human-readable reason so it's still visible in the deliveries listing.
+The SSRF guard remains in place independently.
+
+### 4. WhatsApp / phone deep-links
+
+**Path:** `<a href="https://wa.me/...">` and `<a href="tel:...">` in
+client / interest detail headers.
+
+**Safety:** N/A — user-initiated only.
+
+These are deep links the user explicitly clicks. No automated dispatch.
+A deep link click opens the user's WhatsApp / phone app, which is the
+intended interaction. No safety net needed.
+
+### 5. SMS
+
+Not implemented. The `interests.preferredContactMethod` enum includes
+`'sms'` as a value but no sending path exists. If/when SMS is added (e.g.
+via Twilio), the new send function should respect `EMAIL_REDIRECT_TO`
+the same way `sendEmail` does — log the original number, drop the
+message, or reroute to a configurable `SMS_REDIRECT_TO` env.
+
+---
+
+## Verification checklist before importing real data
+
+- [ ] `.env` has `EMAIL_REDIRECT_TO=<my-address>` set.
+- [ ] Restart dev server (or worker) so the new env is picked up — env
+      vars are read at import time in some paths.
+- [ ] Send a test email via `pnpm tsx scripts/dev-trigger-portal-invite.ts`
+      or similar. Confirm subject is prefixed with `[redirected from ...]`.
+- [ ] Trigger an EOI send through the UI (any client). Confirm Documenso
+      shows the redirect address as recipient (not the real client email).
+- [ ] If any webhooks are configured, trigger an event that fires one and
+      confirm the delivery is recorded as `dead_letter` with the
+      "EMAIL_REDIRECT_TO is set" reason.
+- [ ] Run the NocoDB migration `--dry-run` to count clients/interests; the
+      `--apply` step is what creates real records but emails/webhooks are
+      still gated by the redirect env.
+
+## Production cutover
+
+When ready to go live:
+
+1. Run a final dry-run of the data migration with `EMAIL_REDIRECT_TO` set
+   to a sandbox address.
+2. Verify the snapshot looks right (counts, client coverage).
+3. Unset `EMAIL_REDIRECT_TO` in the production env.
+4. Restart the app + worker.
+5. Run the migration with `--apply`. From this point forward, real
+   recipients will receive real comms.
+
+If you ever need to re-pause outbound (e.g. handling a security incident,
+re-importing on top of existing data), set `EMAIL_REDIRECT_TO` again.

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

@@ -0,0 +1,189 @@
+# 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/superpowers/specs/2026-05-03-dedup-and-migration-design.md

@@ -0,0 +1,564 @@
+# Client Deduplication and NocoDB Migration Design
+
+**Status**: Design draft 2026-05-03 — pending approval.
+**Plan decomposition**: Three implementation plans stack from this design — (P1) normalization + dedup core library; (P2) admin settings + at-create + interest-level guards (runtime); (P3) NocoDB migration script + review queue UI. P1 unblocks P2 and P3.
+**Branch base**: stacks on `feat/mobile-foundation` once it merges to `main`.
+**Out of scope**: live merge of two clients across ports (cross-tenant), automated AI-judged matches, profile-photo / face-match dedup, web-of-trust referrer relationships.
+
+---
+
+## 1. Background
+
+### 1.1 Why this exists
+
+The legacy CRM lives in a NocoDB base whose `Interests` table conflates _the human_ with _the deal_. A row contains `Full Name`, `Email Address`, `Phone Number`, `Address`, `Place of Residence` _and_ the sales-pipeline state for one specific berth. A single human pursuing two berths becomes two rows with semi-duplicated personal data. A 2026-05-03 read-only audit confirmed:
+
+- **252 Interests rows** in NocoDB, against an estimated ~190–200 unique humans (~20–25% duplication rate).
+- **35 Residential Interests rows** in a parallel residential pathway with the same conflation.
+- **64 Website Interest Submissions + 47 Website Contact Form Submissions + 1 EOI Supplemental Form** as inbound capture surfaces.
+- **No Clients table.** The conflated structure is structural, not accidental.
+
+The new CRM (`src/lib/db/schema/clients.ts`) splits this into `clients` (people) ↔ `interests` (deals), with `clientContacts` (multi-channel), `clientAddresses` (multi-address), and a pre-existing `clientMergeLog` table that anticipates merge with undo. The design has been ready; what's missing is (a) a normalization + matching library, (b) the at-create / at-import surfaces that use it, and (c) the migration of the existing 252+35 records.
+
+### 1.2 Real duplicate patterns observed in the live data
+
+Sampled 200 of the 252 NocoDB Interests rows. Confirmed duplicate clusters fall into six patterns:
+
+| Pattern                      | Example rows                                                                                                                                                                    | Signature                                                              |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **A. Pure double-submit**    | Deepak Ramchandani #624/#625; John Lynch #716/#725                                                                                                                              | All fields identical; created same day                                 |
+| **B. Phone format variance** | Howard Wiarda #236/#536 (`574-274-0548` vs `+15742740548`); Christophe Zasso #701/#702 (`0651381036` vs `0033651381036`)                                                        | Same email, normalize-equal phone                                      |
+| **C. Name capitalization**   | Nicolas Ruiz #681/#682/#683; Jean-Charles Miege/MIEGE #37/#163; John Farmer/FARMER #35/#161                                                                                     | Same email or empty; surname case differs                              |
+| **D. Name shortening**       | Chris vs Christopher Allen #700/#534; Emma c vs Emma Cauchefer #661/#673                                                                                                        | Same email + phone; given-name truncated                               |
+| **E. Resubmit with typo**    | Christopher Camazou #649/#650 (phone last 4 digits typo); Gianfranco Di Constanzo/Costanzo #585/#336 (surname typo, **different yacht** — should be ONE client + TWO interests) | Score-on-everything-else high, one field has small-edit-distance noise |
+| **F. Hard cases**            | Etiennette Clamouze #188/#717 (same name, different country phone + email); Bruno Joyerot #18 with email belonging to Bruce Hearn #19 (couple sharing contact)                  | Cannot resolve without a human                                         |
+
+This dataset will be the fixture for the dedup library's tests — every pattern above must be either auto-detected or flagged for review, and the false-positive bar must be high enough that Pattern F doesn't get force-merged.
+
+### 1.3 Dirty data inventory
+
+The migration normalizer must survive these real values from production:
+
+**Phone fields**: `+1-264-235-8840\r` (with carriage return), `'+1.214.603.4235` (apostrophe + dots), `0677580750/0690511494` (two numbers in one field), `00447956657022` (00 prefix), `+447000000000` (placeholder all-zeros), `+4901637039672` (impossible — stripped 0 + country prefix), various unprefixed local formats, dashed US numbers without country code.
+
+**Email fields**: mixed case rampant (`Arthur@laser-align.com` vs `arthur@laser-align.com`); ALL-CAPS local parts; trailing whitespace.
+
+**Name fields**: ALL-CAPS surnames mixed with title-case given names; embedded `\n` and `\r`; double spaces; lowercase-only entries; slash-with-company variants (`Daniel Wainstein / 7 Knots, LLC`, `Bruno Joyerot / SAS TIKI`); placeholder `Mr DADER`, `TBC`.
+
+**Place of Residence (free text)**: `Saint barthelemy`, `St Barth`, `Saint-Barthélemy` (same place, three forms); `anguilla`, `United States `, `USA`, `Kansas City` (city without country), `Sag Harbor Y` (typo).
+
+### 1.4 Existing battle-tested algorithm
+
+`client-portal/server/utils/duplicate-detection.ts` already implements blocking + weighted-rules dedup against this same NocoDB. It runs in production today. We **port it forward** (don't reinvent), then add: soundex/metaphone for surname matching, compounded-confidence when multiple rules match, and negative evidence (same email + different country phone reduces confidence).
+
+### 1.5 Why the website is no longer the source of new dirty data
+
+The website forms (`website/components/pn/specific/website/{berths-item,register,form}/form.vue`) use `<v-phone-input>` with a country picker (`prefer-countries: ['US', 'GB', 'DE', 'FR']`) and `[(value) => !!value || 'Phone number is required']` validation. Output is E.164-shaped. The 252 dirty rows are legacy — pre-form-redesign submissions, sales-rep manual entries, and external CSV imports. Future inbound is clean.
+
+---
+
+## 2. Approach
+
+Three artifacts, layered:
+
+1. **A pure-logic normalization + matching library** at `src/lib/dedup/`. JSX-free, vitest-native (proven pattern: `realtime-invalidation-core.ts`). Tested against the dirty-data fixture corpus drawn from §1.2.
+2. **Three runtime surfaces** that use the library: at-create suggestion in client/interest forms; interest-level same-berth guard; admin review queue powered by a nightly background scoring job.
+3. **A one-shot migration script** that pulls NocoDB → normalizes → dedupes → writes new schema → produces a CSV report with auto-merge log + flagged-for-review pile.
+
+**Configurability via admin settings** (`system_settings` per port) so the team can tune sensitivity without code changes. Defaults err on the safe side — a flagged review is cheaper than a wrongly-merged record.
+
+**Reversibility**: every merge writes a `client_merge_log` row containing the loser's full pre-state JSON. A 7-day undo window lets a wrong merge be reversed without engineering involvement. After 7 days the snapshot is purged for GDPR; merges become permanent.
+
+---
+
+## 3. Normalization library
+
+Lives at `src/lib/dedup/normalize.ts`. Pure functions, no DB, vitest-tested. Used by the dedup algorithm AND by all create-paths so what gets stored is already normalized.
+
+### 3.1 `normalizeName(raw: string)`
+
+```ts
+export function normalizeName(raw: string): {
+  display: string; // human-readable, kept for UI
+  normalized: string; // for matching
+  surnameToken?: string; // for surname-based blocking
+};
+```
+
+- Trim leading/trailing whitespace
+- Replace `\r`, `\n`, tabs with single space
+- Collapse consecutive whitespace to single space
+- Smart title-case: keep particles (`van`, `de`, `del`, `O'`, `di`, `le`, `da`) lowercase except as first token
+- `display` preserves user's intent (slash-with-company stays intact)
+- `normalized` is `display.toLowerCase()` for comparison
+- `surnameToken` is the last non-particle token for blocking
+
+### 3.2 `normalizeEmail(raw: string)`
+
+```ts
+export function normalizeEmail(raw: string): string | null;
+```
+
+- Trim + lowercase
+- Validate via `zod.email()` schema
+- Returns `null` for empty / invalid (caller decides what to do)
+- **Does NOT strip plus-aliases** (`user+tag@domain.com`) — both intentional (real distinct addresses) and malicious-prevention apply. Compare by full localpart.
+
+### 3.3 `normalizePhone(raw: string, defaultCountry: string)`
+
+```ts
+export function normalizePhone(
+  raw: string,
+  defaultCountry: string,
+): {
+  e164: string | null; // canonical, e.g. '+15742740548'
+  country: string | null; // ISO-3166-1 alpha-2
+  display: string | null; // user-facing pretty
+  flagged?: 'multi_number' | 'placeholder' | 'unparseable';
+} | null;
+```
+
+Pipeline:
+
+1. Strip `\r`, `\n`, tabs, single quotes, dots, dashes, parens, spaces
+2. If contains `/` or `;` or `,` → flag `multi_number`, take first segment
+3. If matches `+\d{2}0+$` (e.g., `+447000000000`) → flag `placeholder`, return null
+4. If starts with `00` → replace with `+`
+5. If starts with `+` → parse as E.164
+6. Else if `defaultCountry` provided → parse against that country
+7. Else return null (caller's problem)
+
+Backed by `libphonenumber-js` (already in deps via `tests/integration/factories.ts` usage if not, will add). The hostile cases above all need explicit handling — naïve regex won't survive.
+
+### 3.4 `resolveCountry(text: string)`
+
+```ts
+export function resolveCountry(text: string): {
+  iso: string | null; // ISO-3166-1 alpha-2
+  confidence: 'exact' | 'fuzzy' | 'city' | null;
+};
+```
+
+Reuses `src/lib/i18n/countries.ts`. Pipeline:
+
+1. Lowercase + strip diacritics
+2. Exact match against country names (any locale we ship)
+3. Fuzzy match (Levenshtein ≤ 2 against canonical English names)
+4. City fallback — small in-package mapping for high-frequency cities seen in legacy data (`Sag Harbor → US`, `Kansas City → US`, `St Barth → BL`, etc.). Order: exact → city → fuzzy.
+
+The mapping is opinionated and small (~30 entries covering the actual values seen in the 252-row dataset). Anything that fails to resolve returns `null` and lands in the migration's flagged pile.
+
+---
+
+## 4. Dedup algorithm
+
+Lives at `src/lib/dedup/find-matches.ts`. Pure function. Vitest-tested against the §1.2 cluster fixtures.
+
+### 4.1 Public API
+
+```ts
+export interface MatchCandidate {
+  id: string;
+  fullName: string | null;
+  emails: string[]; // already normalized
+  phonesE164: string[]; // already normalized E.164
+  countryIso: string | null;
+}
+
+export interface MatchResult {
+  candidate: MatchCandidate;
+  score: number; // 0–100
+  reasons: string[]; // human-readable, e.g. ["email match", "phone match"]
+  confidence: 'high' | 'medium' | 'low';
+}
+
+export function findClientMatches(
+  input: MatchCandidate,
+  pool: MatchCandidate[],
+  thresholds: DedupThresholds,
+): MatchResult[];
+```
+
+### 4.2 Scoring rules (compound)
+
+Each rule produces a score addition. **Compounding**: when two strong rules match (e.g., email AND phone), the result is ~95+ rather than max(50, 50). Negative evidence subtracts.
+
+| Rule                                                            | Score | Notes                                                  |
+| --------------------------------------------------------------- | ----- | ------------------------------------------------------ |
+| Exact email match (case-insensitive, normalized)                | +60   | One match suffices                                     |
+| Exact phone E.164 match (≥ 8 significant digits)                | +50   | Excludes placeholder all-zeros                         |
+| Exact normalized full-name match                                | +20   | Many "John Smith"s exist                               |
+| Surname soundex match + given-name fuzzy match (Lev ≤ 1)        | +15   | Catches `Constanzo/Costanzo`, `Christophe/Christopher` |
+| Same address (normalized fuzzy ≥ 0.8)                           | +10   | Bonus signal                                           |
+| **Negative**: Same email but different country code on phone    | −15   | Suggests spouse / coworker / shared inbox              |
+| **Negative**: Same name but DIFFERENT email AND DIFFERENT phone | −20   | Two distinct people with the same name                 |
+
+### 4.3 Confidence tiers (post-compound)
+
+- **score ≥ 90 — `high`** — email AND phone match, or email + name + address. Block-create suggest "Use existing." Auto-link on public-form submit by default.
+- **score 50–89 — `medium`** — single strong signal (email or phone alone), or email + same-name + different country (Etiennette case). Soft-warn but allow.
+- **score < 50 — `low`** — weak signals only. Don't surface in UI; only relevant in background-job review queue.
+
+### 4.4 Blocking strategy
+
+For O(n) scan over a pool of N existing clients, build three lookup maps once per scan:
+
+- `byEmail: Map<string, MatchCandidate[]>` — keyed by normalized email
+- `byPhoneE164: Map<string, MatchCandidate[]>` — keyed by E.164
+- `bySurnameToken: Map<string, MatchCandidate[]>` — keyed by `normalizeName(...).surnameToken`
+
+For an incoming `MatchCandidate`, the candidate set to compare is the union of pool entries reachable through any of its emails/phones/surname-token. Typically 0–5 candidates per query, regardless of N.
+
+### 4.5 Performance budget
+
+For migration: 252 rows compared pairwise once. ~30k comparisons after blocking — a few seconds.
+
+For runtime at-create: incoming candidate against existing pool of N clients per port. Expected pool size at maturity: 1k–10k. With blocking: <10 comparisons, <1ms target. No DB query needed beyond the initial pool fetch (which itself uses the indexed columns).
+
+For background nightly job: full pairwise within port, blocked. 10k clients → ~50k pairwise checks per port → <30s. Fine for a nightly cron.
+
+---
+
+## 5. Configurable thresholds (admin settings)
+
+New rows in `system_settings` per port. Default values err safe (more confirmation, less auto-action).
+
+| Key                            | Default           | Effect                                                                                                                                                                               |
+| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `dedup_block_create_threshold` | `90`              | Score above which the client-create form interrupts: "Use existing client?"                                                                                                          |
+| `dedup_soft_warn_threshold`    | `50`              | Score above which a soft-warn panel surfaces below the form                                                                                                                          |
+| `dedup_review_queue_threshold` | `40`              | Background job lands pairs ≥ this score in `/admin/duplicates`                                                                                                                       |
+| `dedup_public_form_auto_link`  | `true`            | When a public-form submission scores ≥ block-threshold against existing client, attach the new interest to that client without prompting. **Safe**: no merge, just attaching a deal. |
+| `dedup_auto_merge_threshold`   | `null` (disabled) | If non-null, merges happen automatically at this threshold without human confirmation. Recommend leaving null until the team is comfortable; `95` is a reasonable cautious value.    |
+| `dedup_undo_window_days`       | `7`               | How long the loser's pre-state JSON is retained for merge-undo. After this, the snapshot is purged (GDPR) and merges are permanent.                                                  |
+
+Each setting is a row in `system_settings`. UI surface in `/[portSlug]/admin/dedup` (a new admin page) with an "Advanced" toggle to expose the thresholds and brief explanations.
+
+If the sales team complains the safer mode is too click-heavy, an admin flips `dedup_auto_merge_threshold` to `95` without any code change.
+
+---
+
+## 6. Merge service contract
+
+### 6.1 Data flow
+
+`mergeClients(winnerId, loserId, fieldChoices, ctx)` does, in a single transaction:
+
+1. **Snapshot loser** — full row + all attached `clientContacts`, `clientAddresses`, `clientNotes`, `clientTags`, plus a count of dependent rows about to be moved (interests, yacht-memberships, etc.). Stored as `mergeDetails` JSONB in `clientMergeLog`.
+2. **Reattach** — every row pointing at `loserId` updates to point at `winnerId`:
+   - `interests.clientId`
+   - `clientContacts.clientId` — with conflict handling: if winner already has the same email, keep winner's; flag the duplicate for the user
+   - `clientAddresses.clientId` — same conflict handling
+   - `clientNotes.clientId` — preserve `authorId` + `createdAt` (never overwrite)
+   - `clientTags.clientId`
+   - `clientYachtMembership.clientId` (or whatever the table is called)
+   - `auditLogs.entityId` — annotate, don't move (audit truth)
+3. **Apply fieldChoices** — for each field where the user picked the loser's value, copy that into the winner row.
+4. **Soft-archive loser** — `loser.archivedAt = now()`, `loser.mergedIntoClientId = winnerId`. Row stays in DB so the merge is reversible.
+5. **Write `clientMergeLog`** — `{ winnerId, loserId, mergedBy, mergedAt, mergeDetails: <snapshot>, fieldChoices }`.
+6. **Audit log** — top-level `auditLogs` row: `{ action: 'merge', entityType: 'client', entityId: winnerId, metadata: { loserId, score, reasons } }`.
+
+### 6.2 Schema additions (migration)
+
+`clients` table gets a new column:
+
+```ts
+mergedIntoClientId: text('merged_into_client_id').references(() => clients.id),
+```
+
+The existing `clientMergeLog` table is reused. Add a partial index for the undo-window query:
+
+```sql
+CREATE INDEX idx_cml_recent ON client_merge_log (port_id, created_at DESC) WHERE created_at > NOW() - INTERVAL '7 days';
+```
+
+A daily maintenance job (using the existing `maintenance-cleanup.test.ts` infrastructure) purges `mergeDetails` JSONB older than `dedup_undo_window_days` setting.
+
+### 6.3 Undo
+
+`unmergeClients(mergeLogId, ctx)`:
+
+1. Within the undo window, look up the snapshot
+2. Restore loser: clear `archivedAt`, `mergedIntoClientId`
+3. Restore loser's contacts/addresses/notes/tags from snapshot
+4. Detach reattached rows: `interests` etc. that were touching `winnerId` and originally belonged to loser go back. The snapshot stores the original `(rowType, rowId)` list explicitly so this is deterministic.
+5. Mark log row `undoneAt = now()`, `undoneBy = userId`
+
+After 7 days the snapshot is gone and unmerge returns `410 Gone`.
+
+### 6.4 Concurrency
+
+Both merge and unmerge wrap in a single transaction with `SELECT … FOR UPDATE` on `clients.id` of both winner and loser. A second merge attempt against the same loser sees `mergedIntoClientId` already set and refuses (clear error: "Already merged into …").
+
+---
+
+## 7. Runtime surfaces
+
+### 7.1 Layer 1 — At-create suggestion
+
+In `ClientForm` (and the public `register` form once that hits the new system):
+
+- Debounced 300ms after email or phone field changes
+- Calls `findClientMatches` against current port's clients
+- Renders top-1 match if score ≥ `dedup_soft_warn_threshold`:
+  ```
+  ┌─────────────────────────────────────┐
+  │ This looks like an existing client   │
+  │  ML  Marcus Laurent                  │
+  │      marcus@…   +33 6 12 34 56 78    │
+  │      2 interests · last 9d ago        │
+  │  [ Use this client ]   [ Create new ] │
+  └─────────────────────────────────────┘
+  ```
+- "Use this client" → form switches to "create new interest under existing client" mode (preserves whatever other fields the user typed)
+- "Create new" → audit-log `dedup_override` with the candidate's id and reasons (so we have data on false positives)
+
+### 7.2 Layer 2 — Interest-level same-berth guard
+
+Cheap one-liner in `createInterest` service:
+
+- Check `(clientId, berthId)` against existing non-archived interests
+- If hit, throw `BerthDuplicateError` with the existing interest details
+- UI catches and prompts: "Update existing or create separate?"
+
+This is NOT the same as client-level dedup. Same client legitimately can pursue the same berth a second time after it falls through. But the prompt-before-create catches the accidental double-submit case.
+
+### 7.3 Layer 3 — Background scoring + review queue
+
+- A nightly cron (using existing BullMQ infrastructure — search for `scheduled-tasks` in repo) runs `findClientMatches` over each port's full client pool
+- Pairs scoring ≥ `dedup_review_queue_threshold` land in a `client_merge_candidates` table:
+  ```ts
+  export const clientMergeCandidates = pgTable('client_merge_candidates', {
+    id: text('id').primaryKey()...,
+    portId: text('port_id').notNull()...,
+    clientAId: text('client_a_id').notNull()...,
+    clientBId: text('client_b_id').notNull()...,
+    score: integer('score').notNull(),
+    reasons: jsonb('reasons').notNull(),
+    status: text('status').notNull().default('pending'), // pending | dismissed | merged
+    createdAt: timestamp('created_at')...,
+    resolvedAt: timestamp('resolved_at'),
+    resolvedBy: text('resolved_by'),
+  })
+  ```
+- `/[portSlug]/admin/duplicates` lists pending candidates sorted by score desc, with `[Review →]` opening a side-by-side merge dialog
+- Dismissing a candidate marks it `status=dismissed` so the job doesn't re-surface the same pair tomorrow (a future score increase re-creates it).
+
+---
+
+## 8. NocoDB → new system field mapping
+
+This is the explicit mapping the migration script applies. One NocoDB Interest row produces multiple new rows.
+
+### 8.1 Top-level transform
+
+```
+NocoDB Interests row
+  ─→ 0–1 client (deduped against existing pool)
+  ─→ 0–1 client_address
+  ─→ 0–2 client_contacts (email, phone)
+  ─→ exactly 1 interest
+  ─→ 0–1 yacht (when Yacht Name present and not "TBC"/"Na"/empty placeholders)
+  ─→ 0–1 document (when documensoID present)
+```
+
+### 8.2 Field map
+
+| NocoDB field                                                      | Target                                                             | Transform                                                                    |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `Full Name`                                                       | `clients.fullName`                                                 | `normalizeName().display`                                                    |
+| `Email Address`                                                   | `clientContacts(channel='email', value=...)`                       | `normalizeEmail()`                                                           |
+| `Phone Number`                                                    | `clientContacts(channel='phone', valueE164=..., valueCountry=...)` | `normalizePhone(raw, defaultCountry)`                                        |
+| `Address`                                                         | `clientAddresses.streetAddress` (LongText preserved)               | trim                                                                         |
+| `Place of Residence`                                              | `clientAddresses.countryIso` AND `clients.nationalityIso`          | `resolveCountry()`                                                           |
+| `Contact Method Preferred`                                        | `clients.preferredContactMethod`                                   | lowercase, mapped: Email→email, Phone→phone                                  |
+| `Source`                                                          | `clients.source`                                                   | mapped: portal→website, Form→website, External→manual; null → manual         |
+| `Date Added`                                                      | `interests.createdAt` (fallback to NocoDB `Created At` then now)   | parse: try `DD-MM-YYYY`, then `YYYY-MM-DD`, then ISO                         |
+| `Sales Process Level`                                             | `interests.pipelineStage`                                          | see §8.3                                                                     |
+| `Lead Category`                                                   | `interests.leadCategory`                                           | General→general_interest, Friends and Family→general_interest with tag       |
+| `Berth` (FK)                                                      | `interests.berthId`                                                | resolve via `Berths` table by `Mooring Number`                               |
+| `Berth Size Desired`                                              | `interests.notes` (appended)                                       | preserve                                                                     |
+| `Yacht Name`, `Length`, `Width`, `Depth`                          | `yachts.name`, `lengthM`, `widthM`, `draughtM`                     | skip if name in {`TBC`, `Na`, ``, null}; ft→m via `\* 0.3048`                |
+| `EOI Status`                                                      | `interests.eoiStatus`                                              | Awaiting Further Details→pending; Waiting for Signatures→sent; Signed→signed |
+| `Deposit 10% Status`                                              | `interests.depositStatus`                                          | Pending→pending; Received→received                                           |
+| `Contract Status`                                                 | `interests.contractStatus`                                         | Pending→pending; 40% Received→partial; Complete→complete                     |
+| `EOI Time Sent`                                                   | `interests.dateEoiSent`                                            | parse                                                                        |
+| `clientSignTime` / `developerSignTime` / `all_signed_notified_at` | `interests.dateEoiSigned` (use latest)                             | parse                                                                        |
+| `Time LOI Sent`                                                   | `interests.dateContractSent`                                       | parse                                                                        |
+| `Internal Notes` + `Extra Comments`                               | `clientNotes` (one row, system author)                             | concatenate with section markers                                             |
+| `documensoID`                                                     | `documents.documensoId` (when present, type='eoi')                 | preserve                                                                     |
+| `Signature Link Client/CC/Developer`, `EmbeddedSignature*`        | `documents.signers[]`                                              | one row per non-null signer                                                  |
+| `reminder_enabled`, `last_reminder_sent`, etc.                    | `interests.reminderEnabled`, `interests.reminderLastFired`         | parse, default true                                                          |
+
+### 8.3 Sales-stage mapping (8 → 9)
+
+| NocoDB                          | New (PIPELINE_STAGES)                                                    |
+| ------------------------------- | ------------------------------------------------------------------------ |
+| General Qualified Interest      | `open`                                                                   |
+| Specific Qualified Interest     | `details_sent`                                                           |
+| EOI and NDA Sent                | `eoi_sent`                                                               |
+| Signed EOI and NDA              | `eoi_signed`                                                             |
+| Made Reservation                | `deposit_10pct`                                                          |
+| Contract Negotiation            | `contract_sent`                                                          |
+| Contract Negotiations Finalized | `contract_sent` (with audit-note: legacy "negotiations finalized")       |
+| Contract Signed                 | `contract_signed` (or `completed` when deposit + contract both complete) |
+
+### 8.4 Other tables
+
+- **Residential Interests** (35 rows) — same shape as Interests but maps to `residentialClients` + `residentialInterests`. Smaller and cleaner. Same dedup runs within this pool independently.
+- **Website - Interest Submissions** (64 rows) — these are **inbound capture, not yet a client**. Treat as if each row is a fresh public-form submission today: run dedup against the migrated client pool. Auto-link if `dedup_public_form_auto_link` setting allows.
+- **Website - Contact Form Submissions** (47 rows) — sparse data (just name + email + interest type). Skip migration; export as CSV for manual triage. Not the source of truth for any deal.
+- **Website - Berth EOI Details Supplements** (1 row) — single record, preserved as a one-off attached to the matching Interest.
+- **Newsletter Sending** (69 rows) — out of scope; that's a marketing surface, not CRM.
+- **Interests Backup, Interests copy** — historical artifacts. Skipped by default. A `--include-backups` flag attaches them as audit-note entries on the corresponding live Interest if the user wants the history.
+
+---
+
+## 9. Migration script
+
+Located at `scripts/migrate-from-nocodb.ts`. Idempotent: safe to re-run. Three main flags:
+
+```
+$ pnpm tsx scripts/migrate-from-nocodb.ts --dry-run [--port-slug X]
+  Pulls everything, transforms, runs dedup, writes CSV report to .migration/<timestamp>/. No DB writes.
+
+$ pnpm tsx scripts/migrate-from-nocodb.ts --apply --report .migration/<timestamp>/
+  Reads the report, performs the writes the dry-run promised. Refuses if the source data has changed since the report was generated (hash mismatch).
+
+$ pnpm tsx scripts/migrate-from-nocodb.ts --rollback --apply-id <id>
+  Reads the apply log, undoes the writes (only valid within the undo window).
+```
+
+Reuses the `client-portal/server/utils/nocodb.ts` adapter for the NocoDB API client (no need to rebuild). Writes to the new system via Drizzle (re-using the existing services like `createClient`, `createInterest`, etc., so all the same validation runs).
+
+### 9.1 Dry-run report format
+
+`.migration/<timestamp>/report.csv`:
+
+```csv
+op,reason,nocodb_row_id,target_table,target_value,confidence,manual_review_required
+create_client,new,624,clients.fullName,Deepak Ramchandani,N/A,false
+create_contact,new,624,clientContacts.email,dannyrams8888@gmail.com,N/A,false
+create_contact,new,624,clientContacts.phone,+17215868888,N/A,false
+create_interest,new,624,interests.berthId,a1b2c3...,N/A,false
+auto_link,score=98 (email+phone),625,clients.id,<existing client UUID from row 624>,high,false
+flag_for_review,score=72 (same name diff country),188,client.id,<existing client UUID from row 717>,medium,true
+country_unresolved,fallback to AI (port country),198,clientAddresses.countryIso,AI,low,true
+phone_unparseable,placeholder all-zeros,641,clientContacts.phone,<skipped>,N/A,true
+```
+
+Plus `.migration/<timestamp>/summary.md`:
+
+```
+# Migration Dry-Run — 2026-05-03 14:23 UTC
+
+NocoDB:    252 Interests + 35 Residences + 64 Website Submissions
+Outcome:   198 clients, 287 interests (incl. residences), 91 yachts, 412 contacts
+
+Auto-linked (high confidence, no human action needed):
+  - Nicolas Ruiz: rows 681,682,683 → 1 client + 3 interests
+  - John Lynch:   rows 716,725 → 1 client + 2 interests
+  - Deepak Ramchandani: rows 624,625 → 1 client + 2 interests
+  - [12 more]
+
+Flagged for manual review (medium confidence):
+  - Etiennette Clamouze (rows 188,717): same name, different country phone + email
+  - Bruno Joyerot #18 + Bruce Hearn #19: shared household contact
+  - [4 more]
+
+Country resolution failed for 7 rows. All defaulted to port country (AI). Review:
+  - Row 239: "Sag Harbor Y" → AI (likely US)
+  - [6 more]
+
+Phone parsing failed for 3 rows. All flagged, no contact created:
+  - Row 178: empty
+  - Row 641: placeholder "+447000000000"
+  - Row 175: empty
+
+Run `--apply` to commit these changes.
+```
+
+### 9.2 Apply phase
+
+`--apply` reads the report, re-fetches the source rows (via NocoDB MCP / API), recomputes the hash, fails fast if NocoDB changed since dry-run. Then performs the writes within a single PostgreSQL transaction per port (commit at end). On any error mid-transaction, full rollback.
+
+After successful apply, an `apply_id` is generated and an audit-log row written. The `apply_id` is the handle used for `--rollback`.
+
+### 9.3 Idempotency
+
+The script tracks NocoDB row IDs in a `migration_source_links` table:
+
+```ts
+export const migrationSourceLinks = pgTable('migration_source_links', {
+  id: text('id').primaryKey()...,
+  sourceSystem: text('source_system').notNull(), // 'nocodb_interests' | 'nocodb_residences' | …
+  sourceId: text('source_id').notNull(),         // NocoDB row id as string
+  targetEntityType: text('target_entity_type').notNull(), // client | interest | yacht | …
+  targetEntityId: text('target_entity_id').notNull(),
+  appliedAt: timestamp('applied_at')...,
+  appliedBy: text('applied_by'),
+}, (table) => [
+  uniqueIndex('idx_msl_source').on(table.sourceSystem, table.sourceId, table.targetEntityType),
+]);
+```
+
+Re-running `--apply` against the same report skips rows already in this table. Useful for partial-failure resumption.
+
+---
+
+## 10. Test plan
+
+### 10.1 Library-level (vitest unit)
+
+- `tests/unit/dedup/normalize.test.ts` — every dirty-data pattern from §1.3 has a fixture asserting the expected normalized output.
+- `tests/unit/dedup/find-matches.test.ts` — every duplicate cluster from §1.2 has a fixture asserting score + confidence tier. Hard cases (Pattern F) assert "medium" not "high" — false-positive guard.
+
+### 10.2 Service-level (vitest integration)
+
+- `tests/integration/dedup/client-merge.test.ts` — merge service exercised: full reattach, clientMergeLog written, undo within window restores, undo after window returns 410, concurrent merge of same loser fails the second.
+- `tests/integration/dedup/at-create-suggestion.test.ts` — `findClientMatches` against a seeded pool returns expected matches + reasons.
+
+### 10.3 Migration script (vitest integration with NocoDB mock)
+
+- `tests/integration/dedup/migration-dry-run.test.ts` — feed the script a fixture NocoDB dump (the 252 rows, frozen as a JSON snapshot in fixtures), assert the resulting CSV matches a golden file. Catch any future regression in the transform pipeline.
+- `tests/integration/dedup/migration-apply.test.ts` — apply the dry-run output to a clean test DB, assert all expected rows exist, assert idempotency (re-apply is a no-op).
+
+### 10.4 E2E (Playwright)
+
+- `tests/e2e/smoke/30-dedup-create.spec.ts` — type into ClientForm with an email matching seeded client; assert suggestion card appears; click "Use this client"; assert form switches to interest-create mode.
+- `tests/e2e/smoke/31-admin-duplicates.spec.ts` — admin views review queue, opens a candidate, side-by-side merge UI works, merge succeeds, undo within window works.
+
+---
+
+## 11. Rollback plan
+
+Three layers of safety, ordered by reversibility:
+
+1. **Per-merge undo** — admin clicks Undo on a wrongly-merged pair, system rolls back from `clientMergeLog` snapshot. 7-day window. No engineering needed.
+2. **Migration `--rollback` flag** — entire migration apply is reversed via the `apply_id` and `migration_source_links` table. Useful in the first 24h after `--apply`. Engineering-supervised.
+3. **DB restore from backup** — the existing `docs/ops/backup-runbook.md` covers this. Last resort if both above are blocked.
+
+Pre-migration, take a hot backup of the new DB (`pg_dump`). Pre-merge in production (before any human-facing surface ships), the `dedup_auto_merge_threshold` defaults to `null` so no automatic merges happen — every merge is human-confirmed.
+
+---
+
+## 12. Open items
+
+- **Soundex vs metaphone** — Soundex is simpler but English-leaning. Metaphone handles non-English surnames better (the dataset has French, German, Italian, Slavic names). Default to metaphone via the `natural` package; revisit if it adds significant install size.
+- **Cross-port dedup** — not in scope. Each port's clients are deduped within that port. A future "shared address book" feature would need its own design.
+- **Profile photo / face match** — out of scope.
+- **AI-assisted match resolution** — out of scope. The Layer-3 review queue is human-only.
+
+---
+
+## Implementation sequence
+
+P1 (this design's library) → P2 (runtime surfaces) → P3 (migration). Each is a separate plan / PR.
+
+**P1 deliverables**: `src/lib/dedup/{normalize,find-matches}.ts` + tests. No UI changes. No DB changes (except indexed lookups added to existing `clientContacts`). ~1.5 days.
+
+**P2 deliverables**: at-create suggestion in `ClientForm` + interest-level guard in `createInterest` service + admin settings UI for thresholds + `clientMergeCandidates` table + nightly job + admin review queue page + merge service + side-by-side merge UI. ~5–7 days.
+
+**P3 deliverables**: `scripts/migrate-from-nocodb.ts` + `migration_source_links` table + dry-run + apply + rollback. CSV report format frozen against fixture. ~3 days, including fixture creation from the live NocoDB snapshot.
+
+Total: ~10–12 engineering days from approval. Can be split across three PRs landing independently — each is testable in isolation and the runtime surfaces (P2) work even without P3 being run.

package.json

@@ -87,6 +87,7 @@
     "tailwind-merge": "^2.6.0",
     "tailwindcss-animate": "^1.0.7",
     "tesseract.js": "^7.0.0",
+    "vaul": "^1.1.2",
     "zod": "^3.24.0",
     "zustand": "^5.0.0"
   },
@@ -112,6 +113,7 @@
     "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",

playwright.config.ts

@@ -75,6 +75,24 @@ export default defineConfig({
         viewport: { width: 1440, height: 900 },
       },
     },
+    {
+      // Mobile / tablet audit — visits every page in headed Chromium at iPhone
+      // viewports (portrait), screenshots full-page to .audit/mobile/<viewport>/,
+      // and writes an index.md. Depends on `setup` for seeded admin + port-role.
+      name: 'mobile-audit',
+      testMatch: /audit\/mobile\.spec\.ts/,
+      dependencies: ['setup'],
+      // Single test walks 4 viewports × ~45 routes sequentially with slowMo;
+      // 30 min headroom keeps us well under the wall-clock cost.
+      timeout: 1_800_000,
+      use: {
+        headless: false,
+        launchOptions: { slowMo: 200 },
+        screenshot: 'off',
+        video: 'off',
+        trace: 'off',
+      },
+    },
   ],
 
   // Don't start the dev server — we expect it to already be running

pnpm-lock.yaml

@@ -206,6 +206,9 @@ importers:
       tesseract.js:
         specifier: ^7.0.0
         version: 7.0.0
+      vaul:
+        specifier: ^1.1.2
+        version: 1.1.2(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       zod:
         specifier: ^3.24.0
         version: 3.25.76
@@ -276,6 +279,9 @@ importers:
       prettier:
         specifier: ^3.4.0
         version: 3.8.1
+      react-grab:
+        specifier: ^0.1.32
+        version: 0.1.32(react@19.2.4)
       tailwindcss:
         specifier: ^3.4.0
         version: 3.4.19(tsx@4.21.0)(yaml@2.8.2)
@@ -339,6 +345,10 @@ packages:
     peerDependencies:
       react: '>=16.9.0'
 
+  '@antfu/ni@0.23.2':
+    resolution: {integrity: sha512-FSEVWXvwroExDXUu8qV6Wqp2X3D1nJ0Li4LFymCyvCVrm7I3lNfG0zZWSWvGU1RE7891eTnFTyh31L3igOwNKQ==}
+    hasBin: true
+
   '@babel/helper-string-parser@7.27.1':
     resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
     engines: {node: '>=6.9.0'}
@@ -2077,6 +2087,10 @@ packages:
       react: '>=16.9.0'
       react-dom: '>=16.9.0'
 
+  '@react-grab/cli@0.1.32':
+    resolution: {integrity: sha512-TI4SHATLH2yM1DMRXgH3dt/8b3Rj51BplDOqOQiHQKAMOuKVAR9WE2WGWJRT3LwFpl8BXR9ytAM9vrGDrB7QGw==}
+    hasBin: true
+
   '@reduxjs/toolkit@2.11.2':
     resolution: {integrity: sha512-Kd6kAHTA6/nUpp8mySPqj3en3dm0tdMIgbttnQ1xFMVpufoj+ADi8pXLBsd4xzTRHQa7t/Jv8W5UnCuW4kuWMQ==}
     peerDependencies:
@@ -2848,6 +2862,11 @@ packages:
     resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==}
     engines: {node: '>=8'}
 
+  bippy@0.5.39:
+    resolution: {integrity: sha512-8hE8rKSl8JWyeaY+JjpnmceWAZPpLEyzOZQpWXM5Rc7861c5WotMJHy2aRZKZrGA8nMpvLNF01t4yQQ+HcZG3w==}
+    peerDependencies:
+      react: '>=17.0.1'
+
   block-stream2@2.1.0:
     resolution: {integrity: sha512-suhjmLI57Ewpmq00qaygS8UgEq2ly2PCItenIyhMqVjo4t4pGzqMvfgJuX8iWTeSDdfSSqS6j38fL4ToNL7Pfg==}
 
@@ -2953,6 +2972,10 @@ packages:
     resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
     engines: {node: '>=18'}
 
+  cli-spinners@2.9.2:
+    resolution: {integrity: sha512-ywqV+5MmyL4E7ybXgKys4DugZbX0FC6LnwrhjuykIjnK9k8OQacQ7axGKnjDXWNhns0xot3bZI5h55H8yo9cJg==}
+    engines: {node: '>=6'}
+
   cli-truncate@4.0.0:
     resolution: {integrity: sha512-nPdaFdQ0h/GEigbPClz11D0v/ZJEwxmeVZGeMo3Z5StPtUTkA9o1lD6QwoirYiSDzbcwn2XcjwmCp68W1IS4TA==}
     engines: {node: '>=18'}
@@ -3008,6 +3031,10 @@ packages:
     resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
     engines: {node: '>=18'}
 
+  commander@14.0.3:
+    resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
+    engines: {node: '>=20'}
+
   commander@4.1.1:
     resolution: {integrity: sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==}
     engines: {node: '>= 6'}
@@ -3982,6 +4009,10 @@ packages:
     resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
     engines: {node: '>=0.10.0'}
 
+  is-interactive@2.0.0:
+    resolution: {integrity: sha512-qP1vozQRI+BMOPcjFzrjXuQvdak2pHNUMZoeG2eRbiSqyvbEf/wQtEOTOX1guk6E3t36RkaqiSt8A/6YElNxLQ==}
+    engines: {node: '>=12'}
+
   is-map@2.0.3:
     resolution: {integrity: sha512-1Qed0/Hr2m+YqxnM09CjA2d/i6YZNfF6R2oRAOj36eUdS6qIV/huPJNSEpKbupewFs+ZsJlxsjjPbc0/afW6Lw==}
     engines: {node: '>= 0.4'}
@@ -4030,6 +4061,14 @@ packages:
     resolution: {integrity: sha512-p3EcsicXjit7SaskXHs1hA91QxgTw46Fv6EFKKGS5DRFLD8yKnohjF3hxoju94b/OcMZoQukzpPpBE9uLVKzgQ==}
     engines: {node: '>= 0.4'}
 
+  is-unicode-supported@1.3.0:
+    resolution: {integrity: sha512-43r2mRvz+8JRIKnWJ+3j8JtjRKZ6GmjzfaE/qiBJnikNnYv/6bagRJ1kUhNk8R5EX/GkobD+r+sfxCPJsiKBLQ==}
+    engines: {node: '>=12'}
+
+  is-unicode-supported@2.1.0:
+    resolution: {integrity: sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==}
+    engines: {node: '>=18'}
+
   is-url@1.2.4:
     resolution: {integrity: sha512-ITvGim8FhRiYe4IQ5uHSkj7pVaPDrCTkNd3yq3cV7iZAcJdHTUMPMEHcqSOy9xZ9qFenQCvi+2wjH9a1nXqHww==}
 
@@ -4121,6 +4160,9 @@ packages:
     resolution: {integrity: sha512-g1MWMLBiz8FKi1e4w0UyVL3w+iJceWAFBAaBnnGKOpNa5f8TLktkbre1+s6oICydWAm+HRUGTmI+//xv2hvXYA==}
     hasBin: true
 
+  jsonc-parser@3.3.1:
+    resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
+
   jsx-ast-utils@3.3.5:
     resolution: {integrity: sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ==}
     engines: {node: '>=4.0'}
@@ -4128,6 +4170,10 @@ packages:
   keyv@4.5.4:
     resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
 
+  kleur@3.0.3:
+    resolution: {integrity: sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w==}
+    engines: {node: '>=6'}
+
   kysely@0.28.11:
     resolution: {integrity: sha512-zpGIFg0HuoC893rIjYX1BETkVWdDnzTzF5e0kWXJFg5lE0k1/LfNWBejrcnOFu8Q2Rfq/hTDTU7XLUM8QOrpzg==}
     engines: {node: '>=20.0.0'}
@@ -4274,6 +4320,10 @@ packages:
   lodash@4.17.23:
     resolution: {integrity: sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==}
 
+  log-symbols@6.0.0:
+    resolution: {integrity: sha512-i24m8rpwhmPIS4zscNzK6MSEhk0DUWa/8iYQWxhffV8jkI4Phvs3F+quL5xvS0gdQR0FyTCMMH33Y78dDTzzIw==}
+    engines: {node: '>=18'}
+
   log-update@6.1.0:
     resolution: {integrity: sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w==}
     engines: {node: '>=18'}
@@ -4582,6 +4632,10 @@ packages:
     resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
     engines: {node: '>= 0.8.0'}
 
+  ora@8.2.0:
+    resolution: {integrity: sha512-weP+BZ8MVNnlCm8c0Qdc1WSWq4Qn7I+9CJGm7Qali6g44e/PUzbjNqJX5NJ9ljlNMosfJvg1fKEGILklK9cwnw==}
+    engines: {node: '>=18'}
+
   own-keys@1.0.1:
     resolution: {integrity: sha512-qFOyK5PjiWZd+QQIh+1jhdb9LpxTF0qs7Pm8o5QHYZ0M3vKqSqzsZaEB6oWlxZ+q2sJBMI/Ktgd2N5ZwQoRHfg==}
     engines: {node: '>= 0.4'}
@@ -4781,6 +4835,10 @@ packages:
     resolution: {integrity: sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==}
     engines: {node: '>= 0.6.0'}
 
+  prompts@2.4.2:
+    resolution: {integrity: sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==}
+    engines: {node: '>= 6'}
+
   prop-types@15.8.1:
     resolution: {integrity: sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==}
 
@@ -5071,6 +5129,15 @@ packages:
   react-fast-compare@3.2.2:
     resolution: {integrity: sha512-nsO+KSNgo1SbJqJEYRE9ERzo7YtYbou/OqjSQKxV7jcKox7+usiUVZOAC+XnDOABXggQTno0Y1CpVnuWEc1boQ==}
 
+  react-grab@0.1.32:
+    resolution: {integrity: sha512-ODZkzu4zjwX/5a1VxTdIkagPD6uPnp8IkSN2v5FDgFMZkH5r/YEMq43hIsdpHV5/R2ymqS9zLxp4H7SNSRx5ng==}
+    hasBin: true
+    peerDependencies:
+      react: '>=17.0.0'
+    peerDependenciesMeta:
+      react:
+        optional: true
+
   react-hook-form@7.71.2:
     resolution: {integrity: sha512-1CHvcDYzuRUNOflt4MOq3ZM46AronNJtQ1S7tnX6YN4y72qhgiUItpacZUAQ0TyWYci3yz1X+rXaSxiuEm86PA==}
     engines: {node: '>=18.0.0'}
@@ -5357,6 +5424,9 @@ packages:
   simple-swizzle@0.2.4:
     resolution: {integrity: sha512-nAu1WFPQSMNr2Zn9PGSZK9AGn4t/y97lEm+MXTtUDwfP0ksAIX4nO+6ruD9Jwut4C49SB1Ws+fbXsm/yScWOHw==}
 
+  sisteransi@1.0.5:
+    resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
+
   slice-ansi@5.0.0:
     resolution: {integrity: sha512-FC+lgizVPfie0kkhqUScwRu1O/lF6NOgJmlCgK+/LYxDCTk8sGelYaHDhFcDN+Sn3Cv+3VSa4Byeo+IMCzpMgQ==}
     engines: {node: '>=12'}
@@ -5369,6 +5439,10 @@ packages:
     resolution: {integrity: sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==}
     engines: {node: '>= 6.0.0', npm: '>= 3.0.0'}
 
+  smol-toml@1.6.1:
+    resolution: {integrity: sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==}
+    engines: {node: '>= 18'}
+
   socket.io-adapter@2.5.6:
     resolution: {integrity: sha512-DkkO/dz7MGln0dHn5bmN3pPy+JmywNICWrJqVWiVOyvXjWQFIv9c2h24JrQLLFJ2aQVQf/Cvl1vblnd4r2apLQ==}
 
@@ -5431,6 +5505,10 @@ packages:
   std-env@4.0.0:
     resolution: {integrity: sha512-zUMPtQ/HBY3/50VbpkupYHbRroTRZJPRLvreamgErJVys0ceuzMkD44J/QjqhHjOzK42GQ3QZIeFG1OYfOtKqQ==}
 
+  stdin-discarder@0.2.2:
+    resolution: {integrity: sha512-UhDfHmA92YAlNnCfhmq0VeNL5bDbiZGg7sZ2IvPsXubGkiNa9EC+tUTsjBRsYUAz87btI6/1wf4XoVvQ3uRnmQ==}
+    engines: {node: '>=18'}
+
   stop-iteration-iterator@1.1.0:
     resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==}
     engines: {node: '>= 0.4'}
@@ -5763,6 +5841,12 @@ packages:
     resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
     engines: {node: '>= 0.8'}
 
+  vaul@1.1.2:
+    resolution: {integrity: sha512-ZFkClGpWyI2WUQjdLJ/BaGuV6AVQiJ3uELGk3OYtP+B6yCO7Cmn9vPFXVJkRaGkOJu3m8bQMgtyzNHixULceQA==}
+    peerDependencies:
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+
   victory-vendor@37.3.6:
     resolution: {integrity: sha512-SbPDPdDBYp+5MJHhBCAyI7wKM3d5ivekigc2Dk2s7pgbZ9wIgIBYGVw4zGHBml/qTFbexrofXW6Gu4noGxrOwQ==}
 
@@ -6065,6 +6149,8 @@ snapshots:
       resize-observer-polyfill: 1.5.1
       throttle-debounce: 5.0.2
 
+  '@antfu/ni@0.23.2': {}
+
   '@babel/helper-string-parser@7.27.1': {}
 
   '@babel/helper-validator-identifier@7.28.5': {}
@@ -7467,6 +7553,17 @@ snapshots:
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
 
+  '@react-grab/cli@0.1.32':
+    dependencies:
+      '@antfu/ni': 0.23.2
+      commander: 14.0.3
+      ignore: 7.0.5
+      jsonc-parser: 3.3.1
+      ora: 8.2.0
+      picocolors: 1.1.1
+      prompts: 2.4.2
+      smol-toml: 1.6.1
+
   '@reduxjs/toolkit@2.11.2(react-redux@9.2.0(@types/react@19.2.14)(react@19.2.4)(redux@5.0.1))(react@19.2.4)':
     dependencies:
       '@standard-schema/spec': 1.1.0
@@ -8233,6 +8330,10 @@ snapshots:
 
   binary-extensions@2.3.0: {}
 
+  bippy@0.5.39(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+
   block-stream2@2.1.0:
     dependencies:
       readable-stream: 3.6.2
@@ -8353,6 +8454,8 @@ snapshots:
     dependencies:
       restore-cursor: 5.1.0
 
+  cli-spinners@2.9.2: {}
+
   cli-truncate@4.0.0:
     dependencies:
       slice-ansi: 5.0.0
@@ -8409,6 +8512,8 @@ snapshots:
 
   commander@13.1.0: {}
 
+  commander@14.0.3: {}
+
   commander@4.1.1: {}
 
   component-classes@1.2.6:
@@ -9561,6 +9666,8 @@ snapshots:
     dependencies:
       is-extglob: 2.1.1
 
+  is-interactive@2.0.0: {}
+
   is-map@2.0.3: {}
 
   is-negative-zero@2.0.3: {}
@@ -9604,6 +9711,10 @@ snapshots:
     dependencies:
       which-typed-array: 1.1.20
 
+  is-unicode-supported@1.3.0: {}
+
+  is-unicode-supported@2.1.0: {}
+
   is-url@1.2.4: {}
 
   is-weakmap@2.0.2: {}
@@ -9685,6 +9796,8 @@ snapshots:
     dependencies:
       minimist: 1.2.8
 
+  jsonc-parser@3.3.1: {}
+
   jsx-ast-utils@3.3.5:
     dependencies:
       array-includes: 3.1.9
@@ -9696,6 +9809,8 @@ snapshots:
     dependencies:
       json-buffer: 3.0.1
 
+  kleur@3.0.3: {}
+
   kysely@0.28.11: {}
 
   language-subtag-registry@0.3.23: {}
@@ -9823,6 +9938,11 @@ snapshots:
 
   lodash@4.17.23: {}
 
+  log-symbols@6.0.0:
+    dependencies:
+      chalk: 5.6.2
+      is-unicode-supported: 1.3.0
+
   log-update@6.1.0:
     dependencies:
       ansi-escapes: 7.3.0
@@ -10121,6 +10241,18 @@ snapshots:
       type-check: 0.4.0
       word-wrap: 1.2.5
 
+  ora@8.2.0:
+    dependencies:
+      chalk: 5.6.2
+      cli-cursor: 5.0.0
+      cli-spinners: 2.9.2
+      is-interactive: 2.0.0
+      is-unicode-supported: 2.1.0
+      log-symbols: 6.0.0
+      stdin-discarder: 0.2.2
+      string-width: 7.2.0
+      strip-ansi: 7.2.0
+
   own-keys@1.0.1:
     dependencies:
       get-intrinsic: 1.3.0
@@ -10313,6 +10445,11 @@ snapshots:
 
   process@0.11.10: {}
 
+  prompts@2.4.2:
+    dependencies:
+      kleur: 3.0.3
+      sisteransi: 1.0.5
+
   prop-types@15.8.1:
     dependencies:
       loose-envify: 1.4.0
@@ -10728,6 +10865,13 @@ snapshots:
 
   react-fast-compare@3.2.2: {}
 
+  react-grab@0.1.32(react@19.2.4):
+    dependencies:
+      '@react-grab/cli': 0.1.32
+      bippy: 0.5.39(react@19.2.4)
+    optionalDependencies:
+      react: 19.2.4
+
   react-hook-form@7.71.2(react@19.2.4):
     dependencies:
       react: 19.2.4
@@ -11075,6 +11219,8 @@ snapshots:
     dependencies:
       is-arrayish: 0.3.4
 
+  sisteransi@1.0.5: {}
+
   slice-ansi@5.0.0:
     dependencies:
       ansi-styles: 6.2.3
@@ -11087,6 +11233,8 @@ snapshots:
 
   smart-buffer@4.2.0: {}
 
+  smol-toml@1.6.1: {}
+
   socket.io-adapter@2.5.6:
     dependencies:
       debug: 4.4.3
@@ -11167,6 +11315,8 @@ snapshots:
 
   std-env@4.0.0: {}
 
+  stdin-discarder@0.2.2: {}
+
   stop-iteration-iterator@1.1.0:
     dependencies:
       es-errors: 1.3.0
@@ -11584,6 +11734,15 @@ snapshots:
 
   vary@1.1.2: {}
 
+  vaul@1.1.2(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+    dependencies:
+      '@radix-ui/react-dialog': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    transitivePeerDependencies:
+      - '@types/react'
+      - '@types/react-dom'
+
   victory-vendor@37.3.6:
     dependencies:
       '@types/d3-array': 3.2.2

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-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/dev-set-password.ts

@@ -0,0 +1,40 @@
+/**
+ * Dev helper: set a user's password directly (bypasses email reset).
+ * Usage: pnpm tsx scripts/dev-set-password.ts <email> <password>
+ */
+import 'dotenv/config';
+import { hashPassword } from 'better-auth/crypto';
+import { eq, and } from 'drizzle-orm';
+import { db } from '@/lib/db';
+import { user, account } from '@/lib/db/schema/users';
+
+async function main() {
+  const [, , email, password] = process.argv;
+  if (!email || !password) {
+    console.error('Usage: pnpm tsx scripts/dev-set-password.ts <email> <password>');
+    process.exit(1);
+  }
+
+  const u = await db.query.user.findFirst({ where: eq(user.email, email) });
+  if (!u) {
+    console.error(`User not found: ${email}`);
+    process.exit(1);
+  }
+
+  const hash = await hashPassword(password);
+  const result = await db
+    .update(account)
+    .set({ password: hash, updatedAt: new Date() })
+    .where(and(eq(account.userId, u.id), eq(account.providerId, 'credential')))
+    .returning({ id: account.id });
+
+  if (result.length === 0) {
+    console.error(`No credential account row for ${email}`);
+    process.exit(1);
+  }
+
+  console.log(`Updated password for ${email} (account id ${result[0]?.id}).`);
+  process.exit(0);
+}
+
+main();

scripts/load-berths-to-port-nimara.ts

@@ -0,0 +1,126 @@
+/**
+ * One-shot: load the 117-berth NocoDB snapshot into the port-nimara
+ * port, skipping any moorings that already exist.
+ *
+ * The original seed only seeded 12 hand-rolled berths into port-nimara
+ * (A-01..D-03), but the migration's interest rows reference moorings
+ * across A-01..E-18. This loads the full set so interest→berth links
+ * resolve cleanly on the next migration run.
+ */
+import 'dotenv/config';
+import { eq, and, sql, inArray } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { berths } from '@/lib/db/schema/berths';
+import berthSnapshot from '@/lib/db/seed-data/berths.json';
+
+interface SnapshotBerth {
+  mooringNumber: string;
+  area: string;
+  status: 'available' | 'under_offer' | 'sold';
+  lengthFt: number | null;
+  widthFt: number | null;
+  draftFt: number | null;
+  lengthM: number | null;
+  widthM: number | null;
+  draftM: number | null;
+  widthIsMinimum: boolean;
+  nominalBoatSize: number | null;
+  nominalBoatSizeM: number | null;
+  waterDepth: number | null;
+  waterDepthM: number | null;
+  waterDepthIsMinimum: boolean;
+  sidePontoon: string | null;
+  powerCapacity: number | null;
+  voltage: number | null;
+  mooringType: string | null;
+  cleatType: string | null;
+  cleatCapacity: string | null;
+  bollardType: string | null;
+  bollardCapacity: string | null;
+  access: string | null;
+  price: number | null;
+  bowFacing: string | null;
+  berthApproved: boolean;
+  statusOverrideMode: string | null;
+}
+
+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 snapshot = berthSnapshot as unknown as SnapshotBerth[];
+
+  // Existing moorings — skip these.
+  const existingRows = await db
+    .select({ mooringNumber: berths.mooringNumber })
+    .from(berths)
+    .where(eq(berths.portId, port.id));
+  const existingMoorings = new Set(existingRows.map((r) => r.mooringNumber));
+
+  const toInsert = snapshot.filter((b) => !existingMoorings.has(b.mooringNumber));
+  console.log(
+    `Snapshot: ${snapshot.length} berths, existing in port-nimara: ${existingRows.length}, to insert: ${toInsert.length}`,
+  );
+
+  if (toInsert.length === 0) {
+    console.log('Nothing to do.');
+    return;
+  }
+
+  const inserted = await db
+    .insert(berths)
+    .values(
+      toInsert.map((b) => ({
+        portId: port.id,
+        mooringNumber: b.mooringNumber,
+        area: b.area,
+        status: b.status,
+        lengthFt: b.lengthFt != null ? String(b.lengthFt) : null,
+        widthFt: b.widthFt != null ? String(b.widthFt) : null,
+        draftFt: b.draftFt != null ? String(b.draftFt) : null,
+        lengthM: b.lengthM != null ? String(b.lengthM) : null,
+        widthM: b.widthM != null ? String(b.widthM) : null,
+        draftM: b.draftM != null ? String(b.draftM) : null,
+        widthIsMinimum: b.widthIsMinimum,
+        nominalBoatSize: b.nominalBoatSize != null ? String(b.nominalBoatSize) : null,
+        nominalBoatSizeM: b.nominalBoatSizeM != null ? String(b.nominalBoatSizeM) : null,
+        waterDepth: b.waterDepth != null ? String(b.waterDepth) : null,
+        waterDepthM: b.waterDepthM != null ? String(b.waterDepthM) : null,
+        waterDepthIsMinimum: b.waterDepthIsMinimum,
+        sidePontoon: b.sidePontoon,
+        powerCapacity: b.powerCapacity != null ? String(b.powerCapacity) : null,
+        voltage: b.voltage != null ? String(b.voltage) : null,
+        mooringType: b.mooringType,
+        cleatType: b.cleatType,
+        cleatCapacity: b.cleatCapacity,
+        bollardType: b.bollardType,
+        bollardCapacity: b.bollardCapacity,
+        access: b.access,
+        price: b.price != null ? String(b.price) : null,
+        priceCurrency: 'USD',
+        bowFacing: b.bowFacing,
+        berthApproved: b.berthApproved,
+        statusOverrideMode: b.statusOverrideMode,
+        tenureType: 'permanent' as const,
+      })),
+    )
+    .returning({ id: berths.id, mooringNumber: berths.mooringNumber });
+
+  console.log(`Inserted ${inserted.length} berths.`);
+
+  // Suppress unused-import warning if eslint is strict.
+  void and;
+  void sql;
+  void inArray;
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

scripts/migrate-from-nocodb.ts

@@ -0,0 +1,251 @@
+/**
+ * One-shot migration: legacy NocoDB Interests → new client/interest split.
+ *
+ * Usage:
+ *
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --dry-run
+ *     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 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 --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 { 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';
+
+interface CliArgs {
+  dryRun: boolean;
+  apply: boolean;
+  portSlug: string | null;
+  reportDir: string | null;
+  unsafeSkipRedirectCheck: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    dryRun: false,
+    apply: false,
+    portSlug: null,
+    reportDir: null,
+    unsafeSkipRedirectCheck: 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] ?? 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);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage:
+  pnpm tsx scripts/migrate-from-nocodb.ts --dry-run [--port-slug <slug>]
+    Pulls NocoDB → transforms → writes report to .migration/<timestamp>/.
+    No database writes.
+
+  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 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));
+
+  if (!args.dryRun && !args.apply) {
+    console.error('Must specify --dry-run or --apply');
+    printHelp();
+    process.exit(1);
+  }
+
+  // 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);
+  }
+
+  // ── Fetch + transform (shared by dry-run and apply) ──────────────────────
+
+  console.log('[migrate] Loading NocoDB config…');
+  const config = loadNocoDbConfig();
+  console.log(`[migrate] Source: ${config.url}`);
+
+  console.log('[migrate] Fetching snapshot from NocoDB…');
+  const start = Date.now();
+  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.`,
+  );
+
+  console.log('[migrate] Running transform + dedup pipeline…');
+  const plan = transformSnapshot(snapshot);
+
+  // 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();
+  const paths = resolveReportPaths(repoRoot);
+
+  console.log(`[migrate] Writing report to ${paths.rootDir}…`);
+  await writeReport(paths, plan, generatedAt);
+
+  // ── Plan summary ─────────────────────────────────────────────────────────
+  const s = plan.stats;
+  console.log('');
+  console.log('=== Migration Plan Summary ===');
+  console.log(
+    `  Input:     ${s.inputInterestRows} interests, ${s.inputResidentialRows} residential interests`,
+  );
+  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(
+    `  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 });
+  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`);
+
+  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`);
+    }
+  }
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error('[migrate] Fatal error:', err);
+  process.exit(1);
+});

scripts/smoke-test-redirect.ts

@@ -0,0 +1,108 @@
+/**
+ * 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;
+  // @ts-expect-error monkey-patch
+  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: [] };
+    },
+  });
+
+  // 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).
+  // @ts-expect-error monkey-patch
+  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);
+});

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

@@ -1,10 +1,9 @@
+import { PageHeader } from '@/components/shared/page-header';
+
 export default function BackupManagementPage() {
   return (
     <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-bold text-foreground">Backup Management</h1>
-        <p className="text-muted-foreground">Manage system backups and restoration</p>
-      </div>
+      <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">

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

@@ -2,6 +2,7 @@ import {
   SettingsFormCard,
   type SettingFieldDef,
 } from '@/components/admin/shared/settings-form-card';
+import { PageHeader } from '@/components/shared/page-header';
 
 const FIELDS: SettingFieldDef[] = [
   {
@@ -47,13 +48,10 @@ const FIELDS: SettingFieldDef[] = [
 export default function BrandingSettingsPage() {
   return (
     <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-semibold">Branding</h1>
-        <p className="text-sm text-muted-foreground">
-          Logo, primary color, app name, and email header/footer HTML used by the branded auth shell
-          and outgoing email templates.
-        </p>
-      </div>
+      <PageHeader
+        title="Branding"
+        description="Logo, primary color, app name, and email header/footer HTML used by the branded auth shell and outgoing email templates."
+      />
       <SettingsFormCard
         title="Identity"
         description="App name, logo, and primary color."

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

@@ -3,6 +3,7 @@ import {
   type SettingFieldDef,
 } from '@/components/admin/shared/settings-form-card';
 import { DocumensoTestButton } from '@/components/admin/documenso/documenso-test-button';
+import { PageHeader } from '@/components/shared/page-header';
 
 const API_FIELDS: SettingFieldDef[] = [
   {
@@ -48,13 +49,10 @@ const EOI_FIELDS: SettingFieldDef[] = [
 export default function DocumensoSettingsPage() {
   return (
     <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-semibold">Documenso & EOI</h1>
-        <p className="text-sm text-muted-foreground">
-          API credentials and default EOI generation pathway. Use the test-connection button to
-          verify a saved configuration before relying on it.
-        </p>
-      </div>
+      <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."
+      />
 
       <SettingsFormCard
         title="Documenso API"

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

@@ -0,0 +1,5 @@
+import { DuplicatesReviewQueue } from '@/components/admin/duplicates/duplicates-review-queue';
+
+export default function DuplicatesAdminPage() {
+  return <DuplicatesReviewQueue />;
+}

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

@@ -2,6 +2,7 @@ import {
   SettingsFormCard,
   type SettingFieldDef,
 } from '@/components/admin/shared/settings-form-card';
+import { PageHeader } from '@/components/shared/page-header';
 
 const FIELDS: SettingFieldDef[] = [
   {
@@ -33,7 +34,7 @@ const FIELDS: SettingFieldDef[] = [
     label: 'Default signature (HTML)',
     description: 'Appended to the bottom of system-generated emails.',
     type: 'html',
-    placeholder: '<p>—<br>The Port Nimara team</p>',
+    placeholder: '<p>-<br>The Port Nimara team</p>',
     defaultValue: '',
   },
   {
@@ -70,7 +71,7 @@ const FIELDS: SettingFieldDef[] = [
   {
     key: 'smtp_pass_override',
     label: 'SMTP password override',
-    description: 'Optional. Stored in plain text — only set when overriding env credentials.',
+    description: 'Optional. Stored in plain text - only set when overriding env credentials.',
     type: 'password',
     defaultValue: '',
   },
@@ -79,13 +80,10 @@ const FIELDS: SettingFieldDef[] = [
 export default function EmailSettingsPage() {
   return (
     <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-semibold">Email Settings</h1>
-        <p className="text-sm text-muted-foreground">
-          Per-port outgoing email configuration. SMTP credentials and the From address default to
-          environment variables when these fields are blank.
-        </p>
-      </div>
+      <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."
+      />
       <SettingsFormCard
         title="From address & signature"
         description="Identity headers and shared HTML used by system-generated emails."

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

@@ -1,10 +1,9 @@
+import { PageHeader } from '@/components/shared/page-header';
+
 export default function DataImportPage() {
   return (
     <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-bold text-foreground">Data Import</h1>
-        <p className="text-muted-foreground">Import data from external sources</p>
-      </div>
+      <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">

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

@@ -1,15 +1,13 @@
 import { InvitationsManager } from '@/components/admin/invitations/invitations-manager';
+import { PageHeader } from '@/components/shared/page-header';
 
 export default function InvitationsPage() {
   return (
     <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-semibold">Invitations</h1>
-        <p className="text-sm text-muted-foreground">
-          Send a single-use invitation to a new CRM user. The recipient sets their own password via
-          the link in the email.
-        </p>
-      </div>
+      <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>
   );

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

@@ -0,0 +1,36 @@
+import { redirect } from 'next/navigation';
+import { headers } from 'next/headers';
+import { eq } from 'drizzle-orm';
+
+import { auth } from '@/lib/auth';
+import { db } from '@/lib/db';
+import { userProfiles } from '@/lib/db/schema/users';
+
+/**
+ * Guard: only super-admins (isSuperAdmin === true in user_profiles) may access
+ * any page under /[portSlug]/admin. Everyone else is redirected to their dashboard.
+ */
+export default async function AdminLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  const session = await auth.api.getSession({ headers: await headers() });
+
+  if (!session?.user) {
+    redirect('/login');
+  }
+
+  const profile = await db.query.userProfiles.findFirst({
+    where: eq(userProfiles.userId, session.user.id),
+  });
+
+  if (!profile?.isSuperAdmin) {
+    redirect(`/${portSlug}/dashboard`);
+  }
+
+  return <>{children}</>;
+}

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

@@ -1,10 +1,9 @@
+import { PageHeader } from '@/components/shared/page-header';
+
 export default function OnboardingPage() {
   return (
     <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-bold text-foreground">Onboarding</h1>
-        <p className="text-muted-foreground">Guided setup for new port configurations</p>
-      </div>
+      <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">

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

@@ -16,10 +16,13 @@ import {
   Tag,
   Upload,
   Users,
+  UsersRound,
   Webhook,
+  Globe,
 } from 'lucide-react';
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { PageHeader } from '@/components/shared/page-header';
 
 interface AdminSection {
   href: string;
@@ -28,7 +31,17 @@ interface AdminSection {
   icon: typeof Settings;
 }
 
-const SECTIONS: AdminSection[] = [
+interface AdminGroup {
+  title: string;
+  description: string;
+  sections: AdminSection[];
+}
+
+const GROUPS: AdminGroup[] = [
+  {
+    title: 'Access',
+    description: 'Who can sign in and what they can do once they do.',
+    sections: [
       {
         href: 'users',
         label: 'Users',
@@ -47,12 +60,12 @@ const SECTIONS: AdminSection[] = [
         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,
+    ],
   },
+  {
+    title: 'Configuration',
+    description: 'Branding, integrations, and per-port settings.',
+    sections: [
       {
         href: 'email',
         label: 'Email Settings',
@@ -89,6 +102,12 @@ const SECTIONS: AdminSection[] = [
         description: 'Outgoing webhook subscriptions, secrets, and delivery log.',
         icon: Webhook,
       },
+    ],
+  },
+  {
+    title: 'Content',
+    description: 'Forms, templates, and labels that users see.',
+    sections: [
       {
         href: 'forms',
         label: 'Forms',
@@ -113,6 +132,36 @@ const SECTIONS: AdminSection[] = [
         description: 'Tenant-defined fields for clients, yachts, and reservations.',
         icon: Key,
       },
+    ],
+  },
+  {
+    title: 'Data Quality',
+    description: 'Cleanup, imports, and the audit trail.',
+    sections: [
+      {
+        href: 'duplicates',
+        label: 'Duplicates',
+        description: 'Review queue of suspected duplicate clients flagged by the dedup engine.',
+        icon: UsersRound,
+      },
+      {
+        href: 'import',
+        label: 'Bulk Import',
+        description: 'CSV-driven imports for clients, yachts, and reservations.',
+        icon: Upload,
+      },
+      {
+        href: 'audit',
+        label: 'Audit Log',
+        description: 'Searchable log of every authenticated mutation in the system.',
+        icon: ScrollText,
+      },
+    ],
+  },
+  {
+    title: 'Operations',
+    description: 'Health checks and disaster recovery.',
+    sections: [
       {
         href: 'reports',
         label: 'Reports',
@@ -125,18 +174,18 @@ const SECTIONS: AdminSection[] = [
         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,
       },
+    ],
+  },
+  {
+    title: 'Tenancy',
+    description: 'Multi-port and multi-install scaffolding.',
+    sections: [
       {
         href: 'ports',
         label: 'Ports',
@@ -149,12 +198,26 @@ const SECTIONS: AdminSection[] = [
         description: 'Initial-setup wizard for fresh ports.',
         icon: LayoutDashboard,
       },
+    ],
+  },
+  {
+    title: 'Integrations',
+    description: 'Third-party providers wired into the app.',
+    sections: [
       {
         href: 'ocr',
         label: 'Receipt OCR',
         description: 'Configure the AI provider used by the mobile receipt scanner.',
         icon: ScrollText,
       },
+      {
+        href: 'website-analytics',
+        label: 'Website analytics (Umami)',
+        description: 'Per-port Umami URL, API token, and Website ID.',
+        icon: Globe,
+      },
+    ],
+  },
 ];
 
 export default async function AdminLandingPage({
@@ -164,16 +227,21 @@ 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."
+      />
+      {GROUPS.map((group) => (
+        <section key={group.title} className="space-y-3">
           <div>
-        <h1 className="text-2xl font-semibold">Administration</h1>
-        <p className="text-sm text-muted-foreground">
-          Per-port configuration and system administration. Each card below opens a dedicated
-          settings page.
-        </p>
+            <h2 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+              {group.title}
+            </h2>
+            <p className="text-xs text-muted-foreground/80">{group.description}</p>
           </div>
           <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
-        {SECTIONS.map((s) => {
+            {group.sections.map((s) => {
               const Icon = s.icon;
               return (
                 <Link
@@ -197,6 +265,8 @@ export default async function AdminLandingPage({
               );
             })}
           </div>
+        </section>
+      ))}
     </div>
   );
 }

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

@@ -2,6 +2,7 @@ import {
   SettingsFormCard,
   type SettingFieldDef,
 } from '@/components/admin/shared/settings-form-card';
+import { PageHeader } from '@/components/shared/page-header';
 
 const DEFAULT_FIELDS: SettingFieldDef[] = [
   {
@@ -53,14 +54,10 @@ const DIGEST_FIELDS: SettingFieldDef[] = [
 export default function ReminderSettingsPage() {
   return (
     <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-semibold">Reminders</h1>
-        <p className="text-sm text-muted-foreground">
-          Default reminder behaviour for new interests and the optional daily-digest delivery
-          window. Individual users can still configure their own digest preferences in Notifications
-          → Preferences.
-        </p>
-      </div>
+      <PageHeader
+        title="Reminders"
+        description="Default reminder behaviour for new interests and the optional daily-digest delivery window. Individual users can still configure their own digest preferences in Notifications → Preferences."
+      />
 
       <SettingsFormCard
         title="Defaults for new interests"

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

@@ -1,10 +1,12 @@
+import { PageHeader } from '@/components/shared/page-header';
+
 export default function ScheduledReportsPage() {
   return (
     <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-bold text-foreground">Scheduled Reports</h1>
-        <p className="text-muted-foreground">Configure and manage automated report delivery</p>
-      </div>
+      <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">

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

@@ -2,6 +2,7 @@
 
 import { useCallback, useEffect, useState } from 'react';
 import { Button } from '@/components/ui/button';
+import { PageHeader } from '@/components/shared/page-header';
 import { Badge } from '@/components/ui/badge';
 import {
   AlertDialog,
@@ -36,7 +37,11 @@ export default function WebhooksPage() {
   const [deleteTarget, setDeleteTarget] = useState<Webhook | null>(null);
   const [expandedId, setExpandedId] = useState<string | null>(null);
   const [regenerating, setRegenerating] = useState<string | null>(null);
-  const [newSecret, setNewSecret] = useState<{ webhookId: string; secret: string; masked: string } | null>(null);
+  const [newSecret, setNewSecret] = useState<{
+    webhookId: string;
+    secret: string;
+    masked: string;
+  } | null>(null);
 
   const loadWebhooks = useCallback(async () => {
     try {
@@ -98,15 +103,20 @@ export default function WebhooksPage() {
 
   return (
     <div className="space-y-6">
-      <div className="flex items-center justify-between">
-        <div>
-          <h1 className="text-2xl font-bold text-foreground">Webhooks</h1>
-          <p className="text-muted-foreground">Configure outgoing webhook integrations</p>
-        </div>
-        <Button onClick={() => { setEditTarget(null); setFormOpen(true); }}>
+      <PageHeader
+        title="Webhooks"
+        description="Configure outgoing webhook integrations"
+        actions={
+          <Button
+            onClick={() => {
+              setEditTarget(null);
+              setFormOpen(true);
+            }}
+          >
             Add Webhook
           </Button>
-      </div>
+        }
+      />
 
       {loading ? (
         <p className="text-sm text-muted-foreground">Loading...</p>
@@ -116,7 +126,13 @@ export default function WebhooksPage() {
           <p className="text-sm text-muted-foreground mt-1">
             Add a webhook to receive real-time notifications of CRM events.
           </p>
-          <Button className="mt-4" onClick={() => { setEditTarget(null); setFormOpen(true); }}>
+          <Button
+            className="mt-4"
+            onClick={() => {
+              setEditTarget(null);
+              setFormOpen(true);
+            }}
+          >
             Add Webhook
           </Button>
         </div>
@@ -141,17 +157,16 @@ export default function WebhooksPage() {
                 </div>
 
                 <div className="flex items-center gap-2 shrink-0">
-                  <Button
-                    variant="ghost"
-                    size="sm"
-                    onClick={() => handleToggleActive(webhook)}
-                  >
+                  <Button variant="ghost" size="sm" onClick={() => handleToggleActive(webhook)}>
                     {webhook.isActive ? 'Disable' : 'Enable'}
                   </Button>
                   <Button
                     variant="ghost"
                     size="sm"
-                    onClick={() => { setEditTarget(webhook); setFormOpen(true); }}
+                    onClick={() => {
+                      setEditTarget(webhook);
+                      setFormOpen(true);
+                    }}
                   >
                     Edit
                   </Button>
@@ -163,11 +178,7 @@ export default function WebhooksPage() {
                   >
                     Delete
                   </Button>
-                  <Button
-                    variant="ghost"
-                    size="sm"
-                    onClick={() => toggleExpand(webhook.id)}
-                  >
+                  <Button variant="ghost" size="sm" onClick={() => toggleExpand(webhook.id)}>
                     {expandedId === webhook.id ? 'Collapse' : 'Details'}
                   </Button>
                 </div>
@@ -228,18 +239,26 @@ export default function WebhooksPage() {
         onSuccess={loadWebhooks}
       />
 
-      <AlertDialog open={!!deleteTarget} onOpenChange={(open) => { if (!open) setDeleteTarget(null); }}>
+      <AlertDialog
+        open={!!deleteTarget}
+        onOpenChange={(open) => {
+          if (!open) setDeleteTarget(null);
+        }}
+      >
         <AlertDialogContent>
           <AlertDialogHeader>
             <AlertDialogTitle>Delete Webhook</AlertDialogTitle>
             <AlertDialogDescription>
-              Delete &quot;{deleteTarget?.name}&quot;? This will also delete all delivery history. This action
-              cannot be undone.
+              Delete &quot;{deleteTarget?.name}&quot;? This will also delete all delivery history.
+              This action cannot be undone.
             </AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
             <AlertDialogCancel>Cancel</AlertDialogCancel>
-            <AlertDialogAction onClick={handleDelete} className="bg-destructive text-destructive-foreground">
+            <AlertDialogAction
+              onClick={handleDelete}
+              className="bg-destructive text-destructive-foreground"
+            >
               Delete
             </AlertDialogAction>
           </AlertDialogFooter>

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

@@ -0,0 +1,74 @@
+import {
+  SettingsFormCard,
+  type SettingFieldDef,
+} from '@/components/admin/shared/settings-form-card';
+import { UmamiTestButton } from '@/components/admin/website-analytics/umami-test-button';
+import { PageHeader } from '@/components/shared/page-header';
+
+/**
+ * Per-port Umami credentials. We deliberately keep all three values
+ * port-scoped (per the operator decision) so different ports can point at
+ * different Umami instances if needed. The /website-analytics dashboard
+ * page reads these settings via the umami.service layer at request time.
+ */
+const FIELDS: SettingFieldDef[] = [
+  {
+    key: 'umami_api_url',
+    label: 'Umami API URL',
+    description:
+      'Base URL of the Umami instance, e.g. https://analytics.portnimara.com (no trailing slash, no /api).',
+    type: 'string',
+    placeholder: 'https://analytics.portnimara.com',
+    defaultValue: '',
+  },
+  {
+    key: 'umami_api_token',
+    label: 'API token',
+    description:
+      'Long-lived API token if your Umami install supports one (Umami Cloud or v2 self-hosted with API keys enabled). Leave blank if you only have username/password - the service falls back to the JWT login flow using the credentials below. Stored in plain text in system_settings.',
+    type: 'password',
+    defaultValue: '',
+  },
+  {
+    key: 'umami_username',
+    label: 'Username',
+    description: 'Self-hosted JWT fallback. Only used if API token is blank.',
+    type: 'string',
+    placeholder: 'admin',
+    defaultValue: '',
+  },
+  {
+    key: 'umami_password',
+    label: 'Password',
+    description: 'Self-hosted JWT fallback. Only used if API token is blank.',
+    type: 'password',
+    defaultValue: '',
+  },
+  {
+    key: 'umami_website_id',
+    label: 'Website ID',
+    description:
+      'UUID of this port’s website inside Umami. Find it in Umami → Settings → Websites → Edit → Website ID.',
+    type: 'string',
+    placeholder: '00000000-0000-0000-0000-000000000000',
+    defaultValue: '',
+  },
+];
+
+export default function WebsiteAnalyticsSettingsPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Website analytics (Umami)"
+        description="Connect this port to its Umami website to display traffic, top pages, referrers, and conversion data on the Website Analytics dashboard."
+      />
+
+      <SettingsFormCard
+        title="Umami connection"
+        description="Per-port credentials. Each port can point at its own Umami instance; or share one instance with different website IDs."
+        fields={FIELDS}
+        extra={<UmamiTestButton />}
+      />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/berth-reservations/page.tsx

@@ -0,0 +1,5 @@
+import { BerthReservationsList } from '@/components/reservations/berth-reservations-list';
+
+export default function BerthReservationsPage() {
+  return <BerthReservationsList />;
+}

src/app/(dashboard)/[portSlug]/clients/[clientId]/loading.tsx

@@ -0,0 +1,41 @@
+import { Skeleton } from '@/components/ui/skeleton';
+import { CardSkeleton } from '@/components/shared/loading-skeleton';
+
+/**
+ * Route-level loading UI for the client detail page. Renders while the
+ * server component resolves the session and the client component bootstraps
+ * its initial query - replaces the previous empty-header flash on direct
+ * URL visits.
+ */
+export default function Loading() {
+  return (
+    <div className="space-y-6">
+      {/* Header strip - title, badges, action buttons */}
+      <div className="rounded-xl border border-border bg-card px-5 py-4 shadow-sm space-y-3">
+        <div className="flex items-center gap-3">
+          <Skeleton className="h-7 w-56" />
+          <Skeleton className="h-5 w-16 rounded-full" />
+        </div>
+        <div className="flex flex-wrap gap-2">
+          <Skeleton className="h-9 w-20 rounded-md" />
+          <Skeleton className="h-9 w-20 rounded-md" />
+          <Skeleton className="h-9 w-24 rounded-md" />
+          <Skeleton className="h-9 w-32 rounded-md" />
+        </div>
+      </div>
+
+      {/* Tab strip */}
+      <div className="flex gap-2 border-b border-border pb-1">
+        {Array.from({ length: 8 }).map((_, i) => (
+          <Skeleton key={i} className="h-8 w-20 rounded-md" />
+        ))}
+      </div>
+
+      {/* Two-column overview */}
+      <div className="grid grid-cols-1 gap-6 md:grid-cols-2">
+        <CardSkeleton />
+        <CardSkeleton />
+      </div>
+    </div>
+  );
+}

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

@@ -20,6 +20,7 @@ import { TableSkeleton } from '@/components/shared/loading-skeleton';
 import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
 import { PermissionGate } from '@/components/shared/permission-gate';
 import { ExpenseFormDialog } from '@/components/expenses/expense-form-dialog';
+import { ExpenseCard } from '@/components/expenses/expense-card';
 import { expenseFilterDefinitions } from '@/components/expenses/expense-filters';
 import { getExpenseColumns, type ExpenseRow } from '@/components/expenses/expense-columns';
 import { usePaginatedQuery } from '@/hooks/use-paginated-query';
@@ -60,8 +61,7 @@ export default function ExpensesPage() {
   });
 
   const archiveMutation = useMutation({
-    mutationFn: (id: string) =>
-      apiFetch(`/api/v1/expenses/${id}`, { method: 'DELETE' }),
+    mutationFn: (id: string) => apiFetch(`/api/v1/expenses/${id}`, { method: 'DELETE' }),
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['expenses'] });
       setArchiveExpense(null);
@@ -151,6 +151,14 @@ export default function ExpensesPage() {
           onSortChange={setSort}
           isLoading={isFetching && !isLoading}
           getRowId={(row) => row.id}
+          cardRender={(row) => (
+            <ExpenseCard
+              expense={row.original}
+              portSlug={portSlug}
+              onEdit={setEditExpense}
+              onArchive={setArchiveExpense}
+            />
+          )}
           emptyState={
             <EmptyState
               title="No expenses found"

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

@@ -1,9 +1,11 @@
 'use client';
 
-import { useState, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { useParams, useRouter } from 'next/navigation';
 import { useMutation } from '@tanstack/react-query';
-import { Upload, Loader2, ScanLine } from 'lucide-react';
+import { Camera, Loader2, ScanLine, Upload } from 'lucide-react';
+
+import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
 
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
@@ -33,9 +35,16 @@ export default function ScanReceiptPage() {
   const router = useRouter();
   const fileInputRef = useRef<HTMLInputElement>(null);
 
+  const cameraInputRef = useRef<HTMLInputElement>(null);
   const [scanResult, setScanResult] = useState<ScanResult | null>(null);
   const [previewUrl, setPreviewUrl] = useState<string | null>(null);
 
+  const { setChrome } = useMobileChrome();
+  useEffect(() => {
+    setChrome({ title: 'Scan Receipt', showBackButton: true });
+    return () => setChrome({ title: null, showBackButton: false });
+  }, [setChrome]);
+
   // Editable fields from scan
   const [establishment, setEstablishment] = useState('');
   const [amount, setAmount] = useState('');
@@ -94,7 +103,7 @@ export default function ScanReceiptPage() {
 
   return (
     <div className="max-w-2xl mx-auto space-y-6">
-      <div>
+      <div className="hidden sm:block">
         <h1 className="text-2xl font-bold">Scan Receipt</h1>
         <p className="text-muted-foreground mt-1">
           Upload a receipt image and we will extract the expense details automatically.
@@ -109,28 +118,44 @@ export default function ScanReceiptPage() {
           </CardTitle>
         </CardHeader>
         <CardContent>
+          {previewUrl ? (
             <div
-            className="border-2 border-dashed rounded-lg p-8 text-center cursor-pointer hover:bg-muted/50 transition-colors"
+              className="border-2 border-dashed rounded-lg p-4 text-center cursor-pointer hover:bg-muted/50 transition-colors"
               onClick={() => fileInputRef.current?.click()}
             >
-            {previewUrl ? (
               <img
                 src={previewUrl}
                 alt="Receipt preview"
                 className="max-h-64 mx-auto rounded object-contain"
               />
+            </div>
           ) : (
-              <div className="space-y-2">
-                <Upload className="h-8 w-8 mx-auto text-muted-foreground" />
-                <p className="text-sm text-muted-foreground">
-                  Click to upload or drag and drop
-                </p>
-                <p className="text-xs text-muted-foreground">
+            <div className="grid gap-2 sm:grid-cols-2">
+              <Button
+                type="button"
+                size="lg"
+                className="w-full h-14 sm:hidden"
+                onClick={() => cameraInputRef.current?.click()}
+              >
+                <Camera className="mr-2 h-5 w-5" />
+                Take photo
+              </Button>
+              <Button
+                type="button"
+                variant="outline"
+                size="lg"
+                className="w-full h-14"
+                onClick={() => fileInputRef.current?.click()}
+              >
+                <Upload className="mr-2 h-5 w-5" />
+                <span className="sm:hidden">Choose from library</span>
+                <span className="hidden sm:inline">Click to upload or drag and drop</span>
+              </Button>
+              <p className="text-xs text-muted-foreground sm:col-span-2 text-center">
                 JPEG, PNG, WebP up to 10MB
               </p>
             </div>
           )}
-          </div>
           <input
             ref={fileInputRef}
             type="file"
@@ -138,6 +163,14 @@ export default function ScanReceiptPage() {
             className="hidden"
             onChange={handleFileChange}
           />
+          <input
+            ref={cameraInputRef}
+            type="file"
+            accept="image/*"
+            capture="environment"
+            className="hidden"
+            onChange={handleFileChange}
+          />
 
           {scanMutation.isPending && (
             <div className="flex items-center justify-center gap-2 mt-4 text-muted-foreground">
@@ -222,25 +255,18 @@ export default function ScanReceiptPage() {
             </div>
 
             {saveMutation.isError && (
-              <p className="text-sm text-destructive">
-                {(saveMutation.error as Error).message}
-              </p>
+              <p className="text-sm text-destructive">{(saveMutation.error as Error).message}</p>
             )}
 
             <div className="flex gap-2 pt-2">
-              <Button
-                variant="outline"
-                onClick={() => router.push(`/${params.portSlug}/expenses`)}
-              >
+              <Button variant="outline" onClick={() => router.push(`/${params.portSlug}/expenses`)}>
                 Cancel
               </Button>
               <Button
                 onClick={() => saveMutation.mutate()}
                 disabled={saveMutation.isPending || !amount}
               >
-                {saveMutation.isPending && (
-                  <Loader2 className="mr-2 h-4 w-4 animate-spin" />
-                )}
+                {saveMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
                 Save as Expense
               </Button>
             </div>

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

@@ -1,11 +1,13 @@
 'use client';
 
-import { useState } from 'react';
-import { useParams, useRouter } from 'next/navigation';
+import { useEffect, useState } from 'react';
+import { useParams, useRouter, useSearchParams } from 'next/navigation';
 import { useForm, FormProvider } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
-import { useMutation } from '@tanstack/react-query';
-import { ChevronLeft, ChevronRight, Check, Loader2 } from 'lucide-react';
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { ChevronLeft, ChevronRight, Check, Loader2, Wallet } from 'lucide-react';
+
+import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
 
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
@@ -43,9 +45,35 @@ export default function NewInvoicePage() {
   const params = useParams<{ portSlug: string }>();
   const portSlug = params?.portSlug ?? '';
   const router = useRouter();
+  const searchParams = useSearchParams();
+  const prefilledInterestId = searchParams.get('interestId') ?? undefined;
+  const prefilledKind =
+    searchParams.get('kind') === 'deposit' ? ('deposit' as const) : ('general' as const);
 
   const [step, setStep] = useState(1);
 
+  const { setChrome } = useMobileChrome();
+  useEffect(() => {
+    setChrome({ title: 'New Invoice', showBackButton: true });
+    return () => setChrome({ title: null, showBackButton: false });
+  }, [setChrome]);
+
+  // When the form is launched from an interest detail with `?interestId=…&kind=deposit`,
+  // fetch enough of the interest to display "Deposit for {client} - Berth {n}" in
+  // the review step. Doubles as the source of truth for the billing entity prefill.
+  const { data: prefilledInterest } = useQuery<{
+    data: {
+      id: string;
+      clientId: string;
+      clientName: string | null;
+      berthMooringNumber: string | null;
+    };
+  }>({
+    queryKey: ['interest-prefill', prefilledInterestId],
+    queryFn: () => apiFetch(`/api/v1/interests/${prefilledInterestId}`),
+    enabled: !!prefilledInterestId,
+  });
+
   const methods = useForm<CreateInvoiceInput>({
     resolver: zodResolver(createInvoiceSchema),
     defaultValues: {
@@ -53,6 +81,8 @@ export default function NewInvoicePage() {
       currency: 'USD',
       lineItems: [],
       expenseIds: [],
+      interestId: prefilledInterestId,
+      kind: prefilledKind,
     },
   });
 
@@ -65,6 +95,43 @@ export default function NewInvoicePage() {
   } = methods;
 
   const watchedValues = watch();
+  const isDepositInvoice = watchedValues.kind === 'deposit';
+
+  // Resolve the selected billing entity to a human name so the review step
+  // shows "Acme Yacht Charters" instead of "company 4f2a1b…".
+  const billingEntityRef = watchedValues.billingEntity ?? null;
+  const { data: billingEntityName } = useQuery<{ name: string }>({
+    queryKey: ['billing-entity-name', billingEntityRef?.type, billingEntityRef?.id],
+    queryFn: async () => {
+      if (!billingEntityRef) return { name: '' };
+      const path =
+        billingEntityRef.type === 'company'
+          ? `/api/v1/companies/${billingEntityRef.id}`
+          : `/api/v1/clients/${billingEntityRef.id}`;
+      const res = await apiFetch<{
+        data: { fullName?: string; name?: string };
+      }>(path);
+      return {
+        name: res?.data?.fullName ?? res?.data?.name ?? '',
+      };
+    },
+    enabled: !!billingEntityRef?.id,
+    staleTime: 60_000,
+  });
+
+  // Pre-fill the billing entity from the linked interest's client on launch.
+  useEffect(() => {
+    if (prefilledInterest?.data && !watchedValues.billingEntity) {
+      setValue(
+        'billingEntity',
+        { type: 'client', id: prefilledInterest.data.clientId },
+        { shouldValidate: true },
+      );
+    }
+    // We only want this to run when the interest data first arrives.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [prefilledInterest?.data?.clientId]);
+
   const lineItems = watchedValues.lineItems ?? [];
   const subtotal = lineItems.reduce(
     (sum, li) => sum + (Number(li.quantity) || 0) * (Number(li.unitPrice) || 0),
@@ -117,8 +184,8 @@ export default function NewInvoicePage() {
 
   return (
     <div className="max-w-2xl mx-auto space-y-6">
-      {/* Header */}
-      <div className="flex items-center gap-3">
+      {/* Header - desktop only; mobile gets the title from the topbar */}
+      <div className="hidden sm:flex items-center gap-3">
         <Button variant="ghost" size="sm" onClick={() => router.push(`/${portSlug}/invoices`)}>
           <ChevronLeft className="h-4 w-4" />
         </Button>
@@ -157,6 +224,23 @@ export default function NewInvoicePage() {
                 <CardTitle className="text-base">Client Information</CardTitle>
               </CardHeader>
               <CardContent className="space-y-4">
+                {isDepositInvoice ? (
+                  <div className="flex items-start gap-3 rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-sm text-amber-900">
+                    <Wallet className="mt-0.5 h-4 w-4 shrink-0" />
+                    <div className="min-w-0">
+                      <p className="font-medium">Deposit invoice</p>
+                      <p className="text-xs text-amber-800">
+                        {prefilledInterest?.data
+                          ? `Linked to ${prefilledInterest.data.clientName ?? 'interest'}${
+                              prefilledInterest.data.berthMooringNumber
+                                ? ` - Berth ${prefilledInterest.data.berthMooringNumber}`
+                                : ''
+                            }. Marking this invoice as paid will advance the interest to "Deposit 10%".`
+                          : 'Marking this invoice as paid will advance the linked interest to "Deposit 10%".'}
+                      </p>
+                    </div>
+                  </div>
+                ) : null}
                 <div className="space-y-2">
                   <Label>
                     Billing entity <span className="text-destructive">*</span>
@@ -294,9 +378,13 @@ export default function NewInvoicePage() {
                     <p className="font-medium mt-0.5">
                       {watchedValues.billingEntity ? (
                         <>
-                          <span className="capitalize">{watchedValues.billingEntity.type}</span>{' '}
-                          <span className="text-xs opacity-60">
-                            {watchedValues.billingEntity.id.slice(0, 12)}
+                          {billingEntityName?.name ? (
+                            <span>{billingEntityName.name}</span>
+                          ) : (
+                            <span className="text-muted-foreground">Loading…</span>
+                          )}{' '}
+                          <span className="text-xs text-muted-foreground capitalize">
+                            ({watchedValues.billingEntity.type})
                           </span>
                         </>
                       ) : (

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

@@ -12,6 +12,7 @@ import { PageHeader } from '@/components/shared/page-header';
 import { EmptyState } from '@/components/shared/empty-state';
 import { TableSkeleton } from '@/components/shared/loading-skeleton';
 import { PermissionGate } from '@/components/shared/permission-gate';
+import { InvoiceCard } from '@/components/invoices/invoice-card';
 import { invoiceFilterDefinitions } from '@/components/invoices/invoice-filters';
 import { getInvoiceColumns, type InvoiceRow } from '@/components/invoices/invoice-columns';
 import { usePaginatedQuery } from '@/hooks/use-paginated-query';
@@ -63,8 +64,7 @@ export default function InvoicesPage() {
   });
 
   const deleteMutation = useMutation({
-    mutationFn: (id: string) =>
-      apiFetch(`/api/v1/invoices/${id}`, { method: 'DELETE' }),
+    mutationFn: (id: string) => apiFetch(`/api/v1/invoices/${id}`, { method: 'DELETE' }),
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['invoices'] });
       setDeleteTarget(null);
@@ -72,8 +72,7 @@ export default function InvoicesPage() {
   });
 
   const sendMutation = useMutation({
-    mutationFn: (id: string) =>
-      apiFetch(`/api/v1/invoices/${id}/send`, { method: 'POST' }),
+    mutationFn: (id: string) => apiFetch(`/api/v1/invoices/${id}/send`, { method: 'POST' }),
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['invoices'] });
     },
@@ -82,8 +81,7 @@ export default function InvoicesPage() {
   const columns = getInvoiceColumns({
     portSlug,
     onSend: (invoice) => sendMutation.mutate(invoice.id),
-    onRecordPayment: (invoice) =>
-      router.push(`/${portSlug}/invoices/${invoice.id}?tab=payment`),
+    onRecordPayment: (invoice) => router.push(`/${portSlug}/invoices/${invoice.id}?tab=payment`),
     onDelete: (invoice) => setDeleteTarget(invoice),
   });
 
@@ -141,6 +139,17 @@ export default function InvoicesPage() {
           onSortChange={setSort}
           isLoading={isFetching && !isLoading}
           getRowId={(row) => row.id}
+          cardRender={(row) => (
+            <InvoiceCard
+              invoice={row.original}
+              portSlug={portSlug}
+              onSend={(invoice) => sendMutation.mutate(invoice.id)}
+              onRecordPayment={(invoice) =>
+                router.push(`/${portSlug}/invoices/${invoice.id}?tab=payment`)
+              }
+              onDelete={setDeleteTarget}
+            />
+          )}
           emptyState={
             <EmptyState
               title="No invoices found"
@@ -161,15 +170,11 @@ export default function InvoicesPage() {
             <h3 className="font-semibold">Delete Invoice?</h3>
             <p className="text-sm text-muted-foreground">
               This will permanently delete invoice{' '}
-              <span className="font-mono font-medium">{deleteTarget.invoiceNumber}</span>.
-              This action cannot be undone.
+              <span className="font-mono font-medium">{deleteTarget.invoiceNumber}</span>. This
+              action cannot be undone.
             </p>
             <div className="flex items-center gap-2 justify-end">
-              <Button
-                variant="outline"
-                size="sm"
-                onClick={() => setDeleteTarget(null)}
-              >
+              <Button variant="outline" size="sm" onClick={() => setDeleteTarget(null)}>
                 Cancel
               </Button>
               <Button

src/app/(dashboard)/[portSlug]/invoices/upload-receipts/page.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from 'next';
+
+import { UploadReceiptsGuide } from '@/components/invoices/upload-receipts-guide';
+
+export const metadata: Metadata = {
+  title: 'How to upload receipts',
+};
+
+export default async function UploadReceiptsPage({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  return <UploadReceiptsGuide portSlug={portSlug} />;
+}

src/app/(dashboard)/[portSlug]/website-analytics/page.tsx

@@ -0,0 +1,11 @@
+import type { Metadata } from 'next';
+
+import { WebsiteAnalyticsShell } from '@/components/website-analytics/website-analytics-shell';
+
+export const metadata: Metadata = {
+  title: 'Website analytics',
+};
+
+export default function WebsiteAnalyticsPage() {
+  return <WebsiteAnalyticsShell />;
+}

src/app/(dashboard)/layout.tsx

@@ -12,6 +12,8 @@ import { PortProvider } from '@/providers/port-provider';
 import { PermissionsProvider } from '@/providers/permissions-provider';
 import { Sidebar } from '@/components/layout/sidebar';
 import { Topbar } from '@/components/layout/topbar';
+import { MobileLayout } from '@/components/layout/mobile/mobile-layout';
+import { RealtimeToasts } from '@/components/shared/realtime-toasts';
 
 export default async function DashboardLayout({ children }: { children: React.ReactNode }) {
   const session = await auth.api.getSession({ headers: await headers() });
@@ -37,7 +39,9 @@ export default async function DashboardLayout({ children }: { children: React.Re
       <PortProvider ports={ports} defaultPortId={ports[0]?.id ?? null}>
         <PermissionsProvider>
           <SocketProvider>
-            <div className="flex h-screen overflow-hidden bg-background">
+            <RealtimeToasts />
+            {/* Desktop shell - hidden by CSS on mobile */}
+            <div data-shell="desktop" className="flex h-screen overflow-hidden bg-background">
               <Sidebar
                 portRoles={portRoles}
                 isSuperAdmin={profile?.isSuperAdmin ?? false}
@@ -45,6 +49,7 @@ export default async function DashboardLayout({ children }: { children: React.Re
                   name: profile?.displayName ?? session.user.name ?? session.user.email,
                   email: session.user.email,
                 }}
+                ports={ports}
               />
               <div className="flex-1 flex flex-col overflow-hidden min-w-0">
                 <Topbar
@@ -54,9 +59,14 @@ export default async function DashboardLayout({ children }: { children: React.Re
                     email: session.user.email,
                   }}
                 />
-                <main className="flex-1 overflow-y-auto bg-background p-6">{children}</main>
+                <main className="flex-1 overflow-y-auto bg-background pt-3 px-6 pb-6">
+                  {children}
+                </main>
               </div>
             </div>
+
+            {/* Mobile shell - hidden by CSS on desktop */}
+            <MobileLayout>{children}</MobileLayout>
           </SocketProvider>
         </PermissionsProvider>
       </PortProvider>

src/app/(portal)/layout.tsx

@@ -12,14 +12,10 @@ export const metadata: Metadata = {
   },
 };
 
-export default async function PortalLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
+export default async function PortalLayout({ children }: { children: React.ReactNode }) {
   // This layout wraps all portal routes including login/verify
   // We can't easily check pathname in a server layout, so we attempt
-  // to get the session and pass it down — login/verify pages handle their own
+  // to get the session and pass it down - login/verify pages handle their own
   // redirect logic independently.
   const session = await getPortalSession().catch(() => null);
 
@@ -42,17 +38,11 @@ export default async function PortalLayout({
     <div className="min-h-screen bg-gray-50">
       {session && (
         <>
-          <PortalHeader
-            portName={portName}
-            portLogoUrl={portLogoUrl}
-            clientName={clientName}
-          />
+          <PortalHeader portName={portName} portLogoUrl={portLogoUrl} clientName={clientName} />
           <PortalNav />
         </>
       )}
-      <main className={session ? 'max-w-5xl mx-auto px-4 sm:px-6 py-8' : ''}>
-        {children}
-      </main>
+      <main className={session ? 'max-w-5xl mx-auto px-4 sm:px-6 py-8' : ''}>{children}</main>
     </div>
   );
 }

src/app/(portal)/portal/activate/page.tsx

@@ -14,7 +14,7 @@ export default function PortalActivatePage() {
       <PasswordSetForm
         endpoint="/api/portal/auth/activate"
         title="Activate your account"
-        description="Welcome — choose a password to finish setting up your client portal account."
+        description="Welcome - choose a password to finish setting up your client portal account."
         successTitle="Account activated"
         successDescription="You can now sign in with your new password."
         submitLabel="Activate account"

src/app/(portal)/portal/forgot-password/page.tsx

@@ -18,7 +18,7 @@ export default function PortalForgotPasswordPage() {
     e.preventDefault();
     setLoading(true);
     try {
-      // Always returns 200 — caller never sees whether email exists.
+      // Always returns 200 - caller never sees whether email exists.
       await fetch('/api/portal/auth/forgot-password', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },

src/app/(portal)/portal/interests/page.tsx

@@ -5,28 +5,19 @@ import type { Metadata } from 'next';
 import { getPortalSession } from '@/lib/portal/auth';
 import { getClientInterests } from '@/lib/services/portal.service';
 import { Badge } from '@/components/ui/badge';
+import { stageLabel, safeStage, type PipelineStage } from '@/lib/constants';
 
 export const metadata: Metadata = { title: 'Interests' };
 
-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'EOI / NDA Signed',
-  deposit_10pct: 'Deposit Received',
-  contract: 'Contract Stage',
-  completed: 'Completed',
-};
-
-const STAGE_COLORS: Record<string, 'default' | 'secondary' | 'destructive' | 'outline'> = {
+const STAGE_VARIANT: Record<PipelineStage, 'default' | 'secondary' | 'destructive' | 'outline'> = {
   open: 'secondary',
   details_sent: 'secondary',
   in_communication: 'default',
-  visited: 'default',
-  signed_eoi_nda: 'default',
+  eoi_sent: 'default',
+  eoi_signed: 'default',
   deposit_10pct: 'default',
-  contract: 'default',
+  contract_sent: 'default',
+  contract_signed: 'default',
   completed: 'outline',
 };
 
@@ -40,9 +31,7 @@ export default async function PortalInterestsPage() {
     <div className="space-y-6">
       <div>
         <h1 className="text-2xl font-semibold text-gray-900">Berth Interests</h1>
-        <p className="text-sm text-gray-500 mt-1">
-          Your berth enquiries and applications
-        </p>
+        <p className="text-sm text-gray-500 mt-1">Your berth enquiries and applications</p>
       </div>
 
       {interests.length === 0 ? (
@@ -56,10 +45,7 @@ export default async function PortalInterestsPage() {
       ) : (
         <div className="space-y-3">
           {interests.map((interest) => (
-            <div
-              key={interest.id}
-              className="bg-white rounded-lg border p-5"
-            >
+            <div key={interest.id} className="bg-white rounded-lg border p-5">
               <div className="flex items-start justify-between gap-4">
                 <div className="flex-1 min-w-0">
                   <div className="flex items-center gap-2 mb-1">
@@ -71,7 +57,7 @@ export default async function PortalInterestsPage() {
                       <span className="font-medium text-gray-900">General Interest</span>
                     )}
                     {interest.berthArea && (
-                      <span className="text-sm text-gray-400">— {interest.berthArea}</span>
+                      <span className="text-sm text-gray-400">- {interest.berthArea}</span>
                     )}
                   </div>
                   {interest.leadCategory && (
@@ -98,8 +84,8 @@ export default async function PortalInterestsPage() {
                     )}
                   </div>
                 </div>
-                <Badge variant={STAGE_COLORS[interest.pipelineStage] ?? 'default'}>
-                  {STAGE_LABELS[interest.pipelineStage] ?? interest.pipelineStage}
+                <Badge variant={STAGE_VARIANT[safeStage(interest.pipelineStage)]}>
+                  {stageLabel(interest.pipelineStage)}
                 </Badge>
               </div>
             </div>

src/app/(portal)/portal/my-reservations/page.tsx

@@ -59,7 +59,7 @@ export default async function PortalMyReservationsPage() {
                   <div className="flex items-center gap-2 mb-1">
                     <span className="font-medium text-gray-900">{r.yachtName ?? 'Yacht'}</span>
                     {r.berthMooringNumber && (
-                      <span className="text-sm text-gray-400">— Berth {r.berthMooringNumber}</span>
+                      <span className="text-sm text-gray-400">- Berth {r.berthMooringNumber}</span>
                     )}
                   </div>
                   <p className="text-sm text-gray-500">

src/app/(scanner)/[portSlug]/scan/layout.tsx

@@ -1,20 +1,51 @@
+import type { Metadata, Viewport } from 'next';
 import { redirect } from 'next/navigation';
 import { headers } from 'next/headers';
+import { eq } from 'drizzle-orm';
 
 import { auth } from '@/lib/auth';
 import { db } from '@/lib/db';
 import { ports as portsTable } from '@/lib/db/schema/ports';
 import { QueryProvider } from '@/providers/query-provider';
 import { PortProvider } from '@/providers/port-provider';
-import { eq } from 'drizzle-orm';
 
 /**
  * Minimal layout for the mobile receipt-scanner PWA. No sidebar, no
- * topbar — the scanner is its own contained surface. Adds the PWA
- * manifest link + theme color so iOS/Android pick up "Add to Home
- * Screen". Auth check matches the dashboard layout so unauthorized
- * users still bounce to /login.
+ * topbar - the scanner is its own contained surface. PWA manifest +
+ * iOS web-app meta tags are emitted via Next.js's metadata/viewport
+ * exports so React doesn't try to render a second `<head>` mid-tree
+ * (which throws hydration errors in the App Router). Auth check
+ * matches the dashboard layout so unauthorized users still bounce.
  */
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}): Promise<Metadata> {
+  const { portSlug } = await params;
+  return {
+    manifest: `/${portSlug}/scan/manifest.webmanifest`,
+    appleWebApp: {
+      capable: true,
+      title: 'PN Scanner',
+      statusBarStyle: 'default',
+    },
+    other: {
+      // Android/Chrome equivalent of the apple-* meta. metadata.appleWebApp
+      // covers iOS only; this preserves the existing PWA hint for Chrome.
+      'mobile-web-app-capable': 'yes',
+    },
+  };
+}
+
+export const viewport: Viewport = {
+  themeColor: '#3a7bc8',
+  width: 'device-width',
+  initialScale: 1,
+  viewportFit: 'cover',
+};
+
 export default async function ScannerLayout({
   children,
   params,
@@ -33,16 +64,7 @@ export default async function ScannerLayout({
 
   return (
     <QueryProvider>
-      <PortProvider ports={port ? [port] : []} defaultPortId={port?.id ?? null}>
-        <head>
-          <link rel="manifest" href={`/${portSlug}/scan/manifest.webmanifest`} />
-          <meta name="theme-color" content="#3a7bc8" />
-          <meta name="mobile-web-app-capable" content="yes" />
-          <meta name="apple-mobile-web-app-capable" content="yes" />
-          <meta name="apple-mobile-web-app-status-bar-style" content="default" />
-          <meta name="apple-mobile-web-app-title" content="PN Scanner" />
-          <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
-        </head>
+      <PortProvider ports={[port]} defaultPortId={port.id}>
         <div className="min-h-[100dvh] bg-background">{children}</div>
       </PortProvider>
     </QueryProvider>

src/app/(scanner)/[portSlug]/scan/manifest.webmanifest/route.ts

@@ -15,7 +15,7 @@ export async function GET(_req: Request, { params }: { params: Promise<{ portSlu
   const portName = port?.name ?? 'Port Nimara';
 
   const manifest = {
-    name: `${portName} — Scanner`,
+    name: `${portName} - Scanner`,
     short_name: 'Scanner',
     description: `Capture and submit expense receipts for ${portName}.`,
     start_url: `/${portSlug}/scan`,

src/app/(scanner)/[portSlug]/scan/page.tsx

@@ -3,7 +3,7 @@ import type { Metadata } from 'next';
 import { ScanShell } from '@/components/scan/scan-shell';
 
 export const metadata: Metadata = {
-  title: 'Scan receipt — Port Nimara',
+  title: 'Scan receipt - Port Nimara',
 };
 
 export default function ScanPage() {

src/app/api/health/route.ts

@@ -1,11 +1,11 @@
 import { NextResponse } from 'next/server';
 
 /**
- * Liveness probe — confirms the Next.js process is responding.
+ * Liveness probe - confirms the Next.js process is responding.
  *
  * Returns 200 unconditionally; if the process is wedged or has crashed
  * the request never lands here at all. Do NOT include database/Redis/MinIO
- * checks in this endpoint — a transient downstream blip should drop the
+ * checks in this endpoint - a transient downstream blip should drop the
  * pod from the load balancer (readiness), not restart the pod (liveness).
  *
  * For deep dependency checks, hit `/api/ready` instead.

src/app/api/public/interests/route.ts

@@ -36,7 +36,7 @@ type PublicInterestData = z.infer<typeof publicInterestSchema>;
 // Keep the helper aligned with that.
 type Tx = typeof db;
 
-// POST /api/public/interests — unauthenticated public interest registration.
+// POST /api/public/interests - unauthenticated public interest registration.
 // Creates the trio (client + yacht + interest) plus an optional company +
 // membership, all inside a single transaction.
 export async function POST(req: NextRequest) {
@@ -70,7 +70,7 @@ export async function POST(req: NextRequest) {
 
     const firstName = data.firstName ?? fullName.split(/\s+/)[0] ?? 'Valued Guest';
 
-    // Resolve berth by mooring number (if provided). Read-only lookup — safe
+    // Resolve berth by mooring number (if provided). Read-only lookup - safe
     // to do outside the transaction.
     let berthId: string | null = null;
     let resolvedMooringNumber: string | null = data.mooringNumber ?? null;

src/app/api/public/residential-inquiries/route.ts

@@ -34,7 +34,7 @@ async function gateRateLimit(ip: string): Promise<void> {
 }
 
 /**
- * POST /api/public/residential-inquiries — unauthenticated entry point for
+ * POST /api/public/residential-inquiries - unauthenticated entry point for
  * the public website's residential interest form. Creates a
  * `residential_clients` row and an opening `residential_interests` row in a
  * single transaction.
@@ -110,7 +110,7 @@ export async function POST(req: NextRequest) {
     emitToRoom(`port:${portId}`, 'residential_client:created', { id: result.clientId });
     emitToRoom(`port:${portId}`, 'residential_interest:created', { id: result.interestId });
 
-    // Send notification emails (non-blocking — failures shouldn't 500 the
+    // Send notification emails (non-blocking - failures shouldn't 500 the
     // public form).
     void sendResidentialNotifications({
       portId,
@@ -147,7 +147,7 @@ async function sendResidentialNotifications(args: {
   });
   await sendEmail(data.email, confirmation.subject, confirmation.html);
 
-  // Sales-team alert — pull recipients from system_settings if configured;
+  // Sales-team alert - pull recipients from system_settings if configured;
   // fall back to the inquiry_contact_email if available.
   const recipientsRow = await db.query.systemSettings.findFirst({
     where: and(

src/app/api/public/website-inquiries/route.ts

@@ -0,0 +1,177 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+import { eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { websiteSubmissions } from '@/lib/db/schema/website-submissions';
+import { env } from '@/lib/env';
+import { logger } from '@/lib/logger';
+import { checkRateLimit, rateLimiters } from '@/lib/rate-limit';
+
+/**
+ * POST /api/public/website-inquiries
+ *
+ * Capture endpoint for the marketing website's dual-write. The website
+ * server (`/server/api/register.ts`, `/server/api/contact.ts`) calls this
+ * AFTER its existing NocoDB write succeeds, sending the same payload as a
+ * server-to-server fire-and-forget POST. The CRM stores the raw payload
+ * in `website_submissions` for later analysis / promotion to entities.
+ *
+ * Auth: shared-secret in `X-Webhook-Secret` header, timing-safe compared
+ *   against `WEBSITE_INTAKE_SECRET`. If the env var is unset on this
+ *   instance, the endpoint refuses every request with 503 - the correct
+ *   posture for dev/staging that hasn't been wired up yet.
+ *
+ * Idempotency: payload carries a `submission_id` UUID. The unique index
+ *   on `website_submissions.submission_id` makes redelivery a no-op; the
+ *   handler returns 200 + the existing record's id instead of erroring.
+ *
+ * No emails / no `interests` rows are created here. The endpoint's job is
+ * pure data capture. A separate "promote" step (future) will turn captured
+ * submissions into proper `clients` + `interests` rows once we trust the
+ * pipeline.
+ */
+
+const SubmissionSchema = z.object({
+  submission_id: z.string().uuid(),
+  kind: z.enum(['berth_inquiry', 'residence_inquiry', 'contact_form']),
+  payload: z.record(z.unknown()),
+  legacy_nocodb_id: z.string().optional(),
+  /** Defaults to port-nimara since that's currently the only port with a
+   *  public marketing site. Future ports can override per-submission. */
+  port_slug: z.string().default('port-nimara'),
+});
+
+function verifySecret(header: string | null): boolean {
+  const expected = env.WEBSITE_INTAKE_SECRET;
+  if (!expected) return false;
+  if (!header) return false;
+  // Timing-safe compare requires equal-length buffers; pad to whichever is
+  // longer so an early-exit on length mismatch can't leak the secret length.
+  const a = Buffer.from(header);
+  const b = Buffer.from(expected);
+  const pad = Buffer.alloc(Math.max(a.length, b.length));
+  const aPad = Buffer.concat([a, pad]).subarray(0, pad.length);
+  const bPad = Buffer.concat([b, pad]).subarray(0, pad.length);
+  return timingSafeEqual(aPad, bPad) && a.length === b.length;
+}
+
+export async function POST(req: NextRequest) {
+  // Refuse outright if the CRM hasn't been wired up - safer than letting
+  // unauthenticated traffic in just because the env var was forgotten.
+  if (!env.WEBSITE_INTAKE_SECRET) {
+    return NextResponse.json(
+      { error: 'Website intake is not configured on this server.' },
+      { status: 503 },
+    );
+  }
+
+  // Auth gate - shared secret in header, timing-safe compare.
+  const secretHeader = req.headers.get('x-webhook-secret');
+  if (!verifySecret(secretHeader)) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  // Rate limit. All website-side traffic shares the website's egress IP,
+  // so we use a dedicated bucket sized to accommodate normal traffic
+  // (500/hr) rather than the 5/hr publicForm bucket meant for individual
+  // human submissions. The shared-secret header is the real abuse
+  // boundary; this limiter is just a backstop if the secret ever leaks.
+  const ip = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? 'unknown';
+  const rl = await checkRateLimit(ip, rateLimiters.websiteIntake);
+  if (!rl.allowed) {
+    const retryAfter = Math.max(1, Math.ceil((rl.resetAt - Date.now()) / 1000));
+    return NextResponse.json(
+      { error: 'Rate limit exceeded' },
+      { status: 429, headers: { 'Retry-After': String(retryAfter) } },
+    );
+  }
+
+  // Parse + validate body. Reject anything that doesn't conform — the
+  // website is a known caller; a malformed payload signals tampering.
+  let parsed;
+  try {
+    const body = await req.json();
+    parsed = SubmissionSchema.parse(body);
+  } catch (err) {
+    return NextResponse.json(
+      { error: 'Invalid payload', details: err instanceof Error ? err.message : 'parse error' },
+      { status: 400 },
+    );
+  }
+
+  // Resolve port. We require the slug to exist; can't capture submissions
+  // for a port the CRM doesn't know about.
+  const [port] = await db
+    .select({ id: ports.id })
+    .from(ports)
+    .where(eq(ports.slug, parsed.port_slug))
+    .limit(1);
+  if (!port) {
+    // Don't echo the input slug back in the error - generic message is
+    // sufficient and avoids the input-reflection pattern that complicates
+    // log-injection / audit reviews. The slug is logged server-side
+    // for debugging.
+    logger.warn(
+      { portSlug: parsed.port_slug, submissionId: parsed.submission_id },
+      'website-inquiry rejected: unknown port',
+    );
+    return NextResponse.json({ error: 'Unknown port' }, { status: 400 });
+  }
+
+  // Idempotent insert. Two parallel requests carrying the same submission_id
+  // could both pass any pre-check, so we don't pre-check at all - the unique
+  // index on submission_id is the source of truth, and `onConflictDoNothing`
+  // keeps the second request's INSERT from raising 23505. When the conflict
+  // hits, `returning()` yields zero rows and we look up the existing row to
+  // return its id, mirroring the first-delivery shape so the website never
+  // sees a difference between fresh and dup.
+  const insertResult = await db
+    .insert(websiteSubmissions)
+    .values({
+      portId: port.id,
+      submissionId: parsed.submission_id,
+      kind: parsed.kind,
+      payload: parsed.payload,
+      legacyNocodbId: parsed.legacy_nocodb_id ?? null,
+      sourceIp: ip,
+      userAgent: req.headers.get('user-agent') ?? null,
+    })
+    .onConflictDoNothing({ target: websiteSubmissions.submissionId })
+    .returning({ id: websiteSubmissions.id });
+
+  if (insertResult[0]) {
+    logger.info(
+      {
+        submissionId: parsed.submission_id,
+        kind: parsed.kind,
+        portSlug: parsed.port_slug,
+        legacyNocodbId: parsed.legacy_nocodb_id,
+      },
+      'website inquiry captured',
+    );
+    return NextResponse.json({ id: insertResult[0].id, deduped: false });
+  }
+
+  // Conflict path: row already exists. Fetch its id so the response shape
+  // stays identical regardless of which request "won" the race.
+  const existing = await db
+    .select({ id: websiteSubmissions.id })
+    .from(websiteSubmissions)
+    .where(eq(websiteSubmissions.submissionId, parsed.submission_id))
+    .limit(1);
+  if (existing[0]) {
+    return NextResponse.json({ id: existing[0].id, deduped: true });
+  }
+
+  // Should be unreachable - the conflict means a row exists, so the lookup
+  // above should always find it. If it doesn't (e.g. simultaneous DELETE),
+  // surface a 500 explicitly rather than silently 200ing a missing id.
+  logger.error(
+    { submissionId: parsed.submission_id },
+    'website-inquiry conflict but row not found on lookup',
+  );
+  return NextResponse.json({ error: 'Insert failed' }, { status: 500 });
+}

src/app/api/ready/route.ts

@@ -21,7 +21,7 @@ interface ReadyResponse {
 }
 
 /**
- * Readiness probe — verifies that every backing service this process
+ * Readiness probe - verifies that every backing service this process
  * needs to serve traffic is reachable. A 503 should drop the pod from the
  * load balancer until the next probe succeeds; it should not trigger a
  * pod restart (that's what `/api/health` is for).

src/app/api/v1/admin/alerts/run-engine/route.ts

@@ -10,7 +10,7 @@ import { runAlertEngineForPorts } from '@/lib/services/alert-engine';
  * exercised by the realapi socket fanout test.
  *
  * Requires super_admin or per-port admin permissions; the engine itself
- * is idempotent — duplicate runs only re-evaluate, never duplicate rows.
+ * is idempotent - duplicate runs only re-evaluate, never duplicate rows.
  */
 export const POST = withAuth(async (_req, ctx) => {
   try {

src/app/api/v1/admin/documenso/health/route.ts

@@ -5,7 +5,7 @@ import { errorResponse } from '@/lib/errors';
 import { checkDocumensoHealth } from '@/lib/services/documenso-client';
 
 /**
- * Admin probe — calls Documenso /api/v1/health using the port's effective
+ * Admin probe - calls Documenso /api/v1/health using the port's effective
  * config. Used by the "Test connection" button on /admin/documenso.
  */
 export const POST = withAuth(

src/app/api/v1/admin/duplicates/[id]/dismiss/route.ts

@@ -0,0 +1,4 @@
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { dismissHandler } from '../../handlers';
+
+export const POST = withAuth(withPermission('clients', 'edit', dismissHandler));

src/app/api/v1/admin/duplicates/[id]/merge/route.ts

@@ -0,0 +1,4 @@
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { confirmMergeHandler } from '../../handlers';
+
+export const POST = withAuth(withPermission('clients', 'edit', confirmMergeHandler));

src/app/api/v1/admin/duplicates/handlers.ts

@@ -0,0 +1,160 @@
+import { NextResponse } from 'next/server';
+import { and, eq, inArray } from 'drizzle-orm';
+
+import type { AuthContext } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { clients, clientMergeCandidates } from '@/lib/db/schema/clients';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+import {
+  listPendingMergeCandidates,
+  mergeClients,
+  type MergeFieldChoices,
+} from '@/lib/services/client-merge.service';
+
+/**
+ * GET /api/v1/admin/duplicates
+ *
+ * Pending merge candidates for the current port, sorted by score.
+ * Each row hydrates its two client summaries so the review-queue UI
+ * can render side-by-side cards without an N+1 fetch.
+ */
+export async function listHandler(_req: Request, ctx: AuthContext): Promise<NextResponse> {
+  try {
+    const pairs = await listPendingMergeCandidates(ctx.portId);
+    if (pairs.length === 0) return NextResponse.json({ data: [] });
+
+    const ids = Array.from(new Set(pairs.flatMap((p) => [p.clientAId, p.clientBId])));
+    const clientRows = await db
+      .select({
+        id: clients.id,
+        fullName: clients.fullName,
+        archivedAt: clients.archivedAt,
+        mergedIntoClientId: clients.mergedIntoClientId,
+        createdAt: clients.createdAt,
+      })
+      .from(clients)
+      .where(inArray(clients.id, ids));
+    const clientById = new Map(clientRows.map((c) => [c.id, c]));
+
+    const data = pairs
+      .map((p) => {
+        const a = clientById.get(p.clientAId);
+        const b = clientById.get(p.clientBId);
+        if (!a || !b) return null; // FK orphan - shouldn't happen, but be defensive
+        // Skip pairs where one side has already been merged or archived.
+        if (a.mergedIntoClientId || b.mergedIntoClientId) return null;
+        return {
+          id: p.id,
+          score: p.score,
+          reasons: p.reasons,
+          createdAt: p.createdAt,
+          clientA: { id: a.id, fullName: a.fullName, createdAt: a.createdAt },
+          clientB: { id: b.id, fullName: b.fullName, createdAt: b.createdAt },
+        };
+      })
+      .filter((row): row is NonNullable<typeof row> => row !== null);
+
+    return NextResponse.json({ data });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}
+
+/**
+ * POST /api/v1/admin/duplicates/[id]/merge
+ *
+ * Body: { winnerId: string, fieldChoices?: MergeFieldChoices }
+ *
+ * Confirms a merge candidate. The winner is the one the user picked
+ * to keep; the other side becomes the loser. Calls into the merge
+ * service which is the only path that touches client_merge_log.
+ */
+export async function confirmMergeHandler(
+  req: Request,
+  ctx: AuthContext,
+  params: { id?: string },
+): Promise<NextResponse> {
+  try {
+    const id = params.id ?? '';
+    const body = (await req.json().catch(() => ({}))) as {
+      winnerId?: string;
+      fieldChoices?: MergeFieldChoices;
+    };
+    if (!body.winnerId) {
+      return NextResponse.json({ error: 'winnerId required' }, { status: 400 });
+    }
+
+    const [candidate] = await db
+      .select()
+      .from(clientMergeCandidates)
+      .where(
+        and(
+          eq(clientMergeCandidates.id, id),
+          eq(clientMergeCandidates.portId, ctx.portId),
+          eq(clientMergeCandidates.status, 'pending'),
+        ),
+      );
+    if (!candidate) throw new NotFoundError('Merge candidate');
+
+    const loserId =
+      body.winnerId === candidate.clientAId
+        ? candidate.clientBId
+        : body.winnerId === candidate.clientBId
+          ? candidate.clientAId
+          : null;
+    if (!loserId) {
+      return NextResponse.json(
+        { error: 'winnerId must match one of the candidate clients' },
+        { status: 400 },
+      );
+    }
+
+    const result = await mergeClients({
+      winnerId: body.winnerId,
+      loserId,
+      mergedBy: ctx.userId,
+      fieldChoices: body.fieldChoices,
+    });
+
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}
+
+/**
+ * POST /api/v1/admin/duplicates/[id]/dismiss
+ *
+ * Mark a merge candidate as dismissed. The background scoring job
+ * skips dismissed pairs on subsequent runs (a future score increase
+ * can re-create them).
+ */
+export async function dismissHandler(
+  _req: Request,
+  ctx: AuthContext,
+  params: { id?: string },
+): Promise<NextResponse> {
+  try {
+    const id = params.id ?? '';
+    const result = await db
+      .update(clientMergeCandidates)
+      .set({
+        status: 'dismissed',
+        resolvedAt: new Date(),
+        resolvedBy: ctx.userId,
+      })
+      .where(
+        and(
+          eq(clientMergeCandidates.id, id),
+          eq(clientMergeCandidates.portId, ctx.portId),
+          eq(clientMergeCandidates.status, 'pending'),
+        ),
+      )
+      .returning({ id: clientMergeCandidates.id });
+
+    if (result.length === 0) throw new NotFoundError('Merge candidate');
+    return NextResponse.json({ data: { id: result[0]!.id, status: 'dismissed' } });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

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

@@ -0,0 +1,4 @@
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { listHandler } from './handlers';
+
+export const GET = withAuth(withPermission('clients', 'view', listHandler));

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

@@ -9,7 +9,7 @@ import { createCrmInvite, listCrmInvites } from '@/lib/services/crm-invite.servi
 export const GET = withAuth(
   withPermission('admin', 'manage_users', async (_req, ctx) => {
     try {
-      // crm_user_invites is a global table (no per-port column) — invites
+      // crm_user_invites is a global table (no per-port column) - invites
       // mint better-auth users that may later be assigned roles in any
       // port. Listing it cross-tenant would let a port-A director
       // enumerate pending invitee emails, names, and isSuperAdmin flags

src/app/api/v1/admin/ocr-settings/test/route.ts

@@ -13,7 +13,7 @@ const schema = z.object({
   apiKey: z.string().min(1),
 });
 
-// `manage_settings`-gated for parity with the parent OCR settings route —
+// `manage_settings`-gated for parity with the parent OCR settings route -
 // triggers outbound AI provider auth requests using a caller-supplied key.
 export const POST = withAuth(
   withPermission('admin', 'manage_settings', async (req) => {

src/app/api/v1/admin/templates/preview/route.ts

@@ -17,12 +17,12 @@ import { previewAdminTemplateSchema } from '@/lib/validators/document-templates'
  * POST /api/v1/admin/templates/preview
  *
  * Generates a preview PDF from a TipTap JSON content block.
- * Returns { data: { pdfBase64: string } } — the client can render this
+ * Returns { data: { pdfBase64: string } } - the client can render this
  * in an <iframe src="data:application/pdf;base64,..."> or open in a new tab.
  *
  * Body:
  *   content: TipTap JSON document
- *   sampleData?: Record<string, string> — variable substitutions
+ *   sampleData?: Record<string, string> - variable substitutions
  */
 export const POST = withAuth(
   withPermission('documents', 'manage', async (req, _ctx) => {
@@ -60,10 +60,7 @@ export const POST = withAuth(
 /**
  * Deeply substitutes {{variable}} tokens in all text nodes of a TipTap doc.
  */
-function substituteInDoc(
-  node: TipTapNode,
-  data: Record<string, string>,
-): TipTapNode {
+function substituteInDoc(node: TipTapNode, data: Record<string, string>): TipTapNode {
   if (node.type === 'text' && node.text) {
     return { ...node, text: substituteVariables(node.text, data) };
   }

src/app/api/v1/admin/umami/test/route.ts

@@ -0,0 +1,24 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { testConnection } from '@/lib/services/umami.service';
+
+/**
+ * POST /api/v1/admin/umami/test - admin-only Umami connection check.
+ *
+ * Returns `{ data: { ok: true, visitors } }` on success or
+ * `{ data: { ok: false, error } }` on failure. Mirrors the shape used by
+ * the Documenso health endpoint so the existing test-button UI pattern
+ * just works.
+ */
+export const POST = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx) => {
+    try {
+      const result = await testConnection(ctx.portId);
+      return NextResponse.json({ data: result });
+    } catch (err) {
+      const error = err instanceof Error ? err.message : 'Unknown error';
+      return NextResponse.json({ data: { ok: false, error } });
+    }
+  }),
+);

src/app/api/v1/analytics/route.ts

@@ -9,6 +9,7 @@ import {
   getRevenueBreakdown,
   type DateRange,
   type MetricBase,
+  type PresetDateRange,
 } from '@/lib/services/analytics.service';
 
 const METRICS: Record<MetricBase, (portId: string, range: DateRange) => Promise<unknown>> = {
@@ -18,18 +19,70 @@ const METRICS: Record<MetricBase, (portId: string, range: DateRange) => Promise<
   lead_source_attribution: getLeadSourceAttribution,
 };
 
+const ISO_DATE_RX = /^\d{4}-\d{2}-\d{2}$/;
+
 export const GET = withAuth(
   withPermission('reports', 'view_analytics', async (req: NextRequest, ctx) => {
     const url = new URL(req.url);
     const metric = url.searchParams.get('metric') as MetricBase | null;
-    const range = (url.searchParams.get('range') ?? '30d') as DateRange;
+    const rawRange = url.searchParams.get('range') ?? '30d';
+    const fromParam = url.searchParams.get('from');
+    const toParam = url.searchParams.get('to');
 
     if (!metric || !(metric in METRICS)) {
       return NextResponse.json({ error: 'Invalid or missing metric' }, { status: 400 });
     }
-    if (!ALL_RANGES.includes(range)) {
+
+    let range: DateRange;
+    if (rawRange === 'custom') {
+      if (!fromParam || !toParam) {
+        return NextResponse.json(
+          { error: 'Custom range requires `from` and `to` (YYYY-MM-DD)' },
+          { status: 400 },
+        );
+      }
+      if (!ISO_DATE_RX.test(fromParam) || !ISO_DATE_RX.test(toParam)) {
+        return NextResponse.json(
+          { error: '`from`/`to` must be ISO date strings (YYYY-MM-DD)' },
+          { status: 400 },
+        );
+      }
+      if (fromParam > toParam) {
+        return NextResponse.json({ error: '`from` must be on or before `to`' }, { status: 400 });
+      }
+      // Round-trip date check: regex passes "9999-13-99" or "2026-02-31"
+      // (rolls over silently when handed to `new Date`). Re-serialize and
+      // confirm it matches the input to catch invalid calendar values.
+      for (const [label, raw] of [
+        ['from', fromParam],
+        ['to', toParam],
+      ] as const) {
+        const d = new Date(`${raw}T00:00:00.000Z`);
+        if (Number.isNaN(d.getTime()) || d.toISOString().slice(0, 10) !== raw) {
+          return NextResponse.json(
+            { error: `\`${label}\` is not a valid calendar date` },
+            { status: 400 },
+          );
+        }
+      }
+      // Backstop against the occupancy-timeline N+1 query loop. Each day
+      // in the range issues its own DB query, so a multi-year custom
+      // range would saturate the connection pool. 365 days is a generous
+      // ceiling for analytical queries; if a longer span is needed, the
+      // service should be restructured to use `generate_series` instead
+      // of a JS loop.
+      const fromMs = new Date(`${fromParam}T00:00:00.000Z`).getTime();
+      const toMs = new Date(`${toParam}T23:59:59.999Z`).getTime();
+      if ((toMs - fromMs) / 86_400_000 > 365) {
+        return NextResponse.json({ error: 'Custom range cannot exceed 365 days' }, { status: 400 });
+      }
+      range = { kind: 'custom', from: fromParam, to: toParam };
+    } else {
+      if (!ALL_RANGES.includes(rawRange as PresetDateRange)) {
         return NextResponse.json({ error: 'Invalid range' }, { status: 400 });
       }
+      range = rawRange as PresetDateRange;
+    }
 
     const data = await METRICS[metric](ctx.portId, range);
     return NextResponse.json({ metric, range, data });

src/app/api/v1/berth-reservations/[id]/handlers.ts

@@ -0,0 +1,107 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { requirePermission } from '@/lib/auth/permissions';
+import { errorResponse } from '@/lib/errors';
+import {
+  activate,
+  cancel,
+  endReservation,
+  getById,
+} from '@/lib/services/berth-reservations.service';
+
+// ─── PATCH body schema (action-based discriminated union) ────────────────────
+
+const patchBodySchema = z.discriminatedUnion('action', [
+  z.object({
+    action: z.literal('activate'),
+    contractFileId: z.string().optional(),
+    effectiveDate: z.coerce.date().optional(),
+  }),
+  z.object({
+    action: z.literal('end'),
+    endDate: z.coerce.date(),
+    notes: z.string().optional(),
+  }),
+  z.object({
+    action: z.literal('cancel'),
+    reason: z.string().optional(),
+  }),
+]);
+
+// ─── Handlers ────────────────────────────────────────────────────────────────
+
+export const getHandler: RouteHandler = async (_req, ctx, params) => {
+  try {
+    const reservation = await getById(params.id!, ctx.portId);
+    return NextResponse.json({ data: reservation });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const patchHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const body = await parseBody(req, patchBodySchema);
+    const meta = {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    };
+
+    if (body.action === 'activate') {
+      requirePermission(ctx, 'reservations', 'activate');
+      const result = await activate(
+        params.id!,
+        ctx.portId,
+        {
+          contractFileId: body.contractFileId,
+          effectiveDate: body.effectiveDate,
+        },
+        meta,
+      );
+      return NextResponse.json({ data: result });
+    }
+
+    if (body.action === 'end') {
+      // `end` is lifecycle progression; same privilege as activate.
+      requirePermission(ctx, 'reservations', 'activate');
+      const result = await endReservation(
+        params.id!,
+        ctx.portId,
+        { endDate: body.endDate, notes: body.notes },
+        meta,
+      );
+      return NextResponse.json({ data: result });
+    }
+
+    // action === 'cancel'
+    requirePermission(ctx, 'reservations', 'cancel');
+    const result = await cancel(params.id!, ctx.portId, { reason: body.reason }, meta);
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const deleteHandler: RouteHandler = async (_req, ctx, params) => {
+  try {
+    await cancel(
+      params.id!,
+      ctx.portId,
+      {},
+      {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      },
+    );
+    return new NextResponse(null, { status: 204 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/berth-reservations/[id]/route.ts

@@ -1,113 +1,9 @@
-import { NextResponse } from 'next/server';
-import { z } from 'zod';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { parseBody } from '@/lib/api/route-helpers';
-import { requirePermission } from '@/lib/auth/permissions';
-import { errorResponse } from '@/lib/errors';
-import {
-  activate,
-  cancel,
-  endReservation,
-  getById,
-} from '@/lib/services/berth-reservations.service';
-
-// ─── PATCH body schema (action-based discriminated union) ────────────────────
-
-const patchBodySchema = z.discriminatedUnion('action', [
-  z.object({
-    action: z.literal('activate'),
-    contractFileId: z.string().optional(),
-    effectiveDate: z.coerce.date().optional(),
-  }),
-  z.object({
-    action: z.literal('end'),
-    endDate: z.coerce.date(),
-    notes: z.string().optional(),
-  }),
-  z.object({
-    action: z.literal('cancel'),
-    reason: z.string().optional(),
-  }),
-]);
-
-// ─── Handlers ────────────────────────────────────────────────────────────────
-
-export const getHandler: RouteHandler = async (_req, ctx, params) => {
-  try {
-    const reservation = await getById(params.id!, ctx.portId);
-    return NextResponse.json({ data: reservation });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const patchHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const body = await parseBody(req, patchBodySchema);
-    const meta = {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    };
-
-    if (body.action === 'activate') {
-      requirePermission(ctx, 'reservations', 'activate');
-      const result = await activate(
-        params.id!,
-        ctx.portId,
-        {
-          contractFileId: body.contractFileId,
-          effectiveDate: body.effectiveDate,
-        },
-        meta,
-      );
-      return NextResponse.json({ data: result });
-    }
-
-    if (body.action === 'end') {
-      // `end` is lifecycle progression; same privilege as activate.
-      requirePermission(ctx, 'reservations', 'activate');
-      const result = await endReservation(
-        params.id!,
-        ctx.portId,
-        { endDate: body.endDate, notes: body.notes },
-        meta,
-      );
-      return NextResponse.json({ data: result });
-    }
-
-    // action === 'cancel'
-    requirePermission(ctx, 'reservations', 'cancel');
-    const result = await cancel(params.id!, ctx.portId, { reason: body.reason }, meta);
-    return NextResponse.json({ data: result });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const deleteHandler: RouteHandler = async (_req, ctx, params) => {
-  try {
-    await cancel(
-      params.id!,
-      ctx.portId,
-      {},
-      {
-        userId: ctx.userId,
-        portId: ctx.portId,
-        ipAddress: ctx.ipAddress,
-        userAgent: ctx.userAgent,
-      },
-    );
-    return new NextResponse(null, { status: 204 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { getHandler, patchHandler, deleteHandler } from './handlers';
 
 export const GET = withAuth(withPermission('reservations', 'view', getHandler));
-// PATCH cannot use `withPermission` wrapper — the required permission depends
+// PATCH cannot use `withPermission` wrapper - the required permission depends
 // on the `action` field in the body. `requirePermission` is called inside the
 // handler after the body is parsed.
 export const PATCH = withAuth(patchHandler);

src/app/api/v1/berth-reservations/handlers.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from 'next/server';
+
+import type { AuthContext } from '@/lib/api/helpers';
+import { parseQuery } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listReservations } from '@/lib/services/berth-reservations.service';
+import { listReservationsSchema } from '@/lib/validators/reservations';
+
+/**
+ * Port-scoped global list of reservations across all berths. Inner handler
+ * lives here so it can be invoked directly from integration tests without
+ * the `withAuth(withPermission(...))` wrappers (matches the convention
+ * used throughout `src/app/api/v1/*`).
+ */
+export async function listHandler(req: Request, ctx: AuthContext): Promise<NextResponse> {
+  try {
+    const query = parseQuery(req as never, listReservationsSchema);
+    const result = await listReservations(ctx.portId, query);
+    const { page, limit } = query;
+    const totalPages = Math.ceil(result.total / limit);
+    return NextResponse.json({
+      data: result.data,
+      pagination: {
+        page,
+        pageSize: limit,
+        total: result.total,
+        totalPages,
+        hasNextPage: page < totalPages,
+        hasPreviousPage: page > 1,
+      },
+    });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

src/app/api/v1/berth-reservations/route.ts

@@ -0,0 +1,4 @@
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { listHandler } from './handlers';
+
+export const GET = withAuth(withPermission('reservations', 'view', listHandler));

src/app/api/v1/berths/[id]/waiting-list/route.ts

@@ -40,7 +40,7 @@ export const PUT = withAuth(
   }),
 );
 
-// PATCH /api/v1/berths/[id]/waiting-list — reorder a single entry
+// PATCH /api/v1/berths/[id]/waiting-list - reorder a single entry
 export const PATCH = withAuth(
   withPermission('berths', 'manage_waiting_list', async (req, ctx, params) => {
     try {

src/app/api/v1/berths/options/route.ts

@@ -4,7 +4,7 @@ import { withAuth, withPermission } from '@/lib/api/helpers';
 import { getBerthOptions } from '@/lib/services/berths.service';
 import { errorResponse } from '@/lib/errors';
 
-// GET /api/v1/berths/options — lightweight list for selects/comboboxes
+// GET /api/v1/berths/options - lightweight list for selects/comboboxes
 export const GET = withAuth(
   withPermission('berths', 'view', async (req, ctx) => {
     try {

src/app/api/v1/clients/[id]/portal-user/route.ts

@@ -19,7 +19,7 @@ const inviteSchema = z.object({
  *
  * Admin creates a portal account for a client and triggers the activation
  * email. Idempotent in spirit: if a portal user already exists for the
- * email, returns 409 — the admin can resend the activation via
+ * email, returns 409 - the admin can resend the activation via
  * ?action=resend.
  */
 export const POST = withAuth(

src/app/api/v1/clients/match-candidates/handlers.ts

@@ -0,0 +1,160 @@
+import { NextResponse } from 'next/server';
+import { and, eq, inArray } from 'drizzle-orm';
+
+import type { AuthContext } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { clients, clientContacts } from '@/lib/db/schema/clients';
+import { interests } from '@/lib/db/schema/interests';
+import { errorResponse } from '@/lib/errors';
+import { findClientMatches, type MatchCandidate } from '@/lib/dedup/find-matches';
+import { normalizeEmail, normalizeName, normalizePhone } from '@/lib/dedup/normalize';
+import type { CountryCode } from '@/lib/i18n/countries';
+
+/**
+ * GET /api/v1/clients/match-candidates
+ *
+ * Query parameters (any combination):
+ *   email      Free-text email; gets normalized server-side.
+ *   phone      Free-text phone; gets normalized to E.164 server-side.
+ *   name       Free-text full name; used for surname-token blocking.
+ *   country    Optional ISO country hint (default: AI for Port Nimara).
+ *
+ * Returns the top candidates that scored above the soft-warn threshold,
+ * each with a small client summary the form's suggestion card can
+ * render. Confidence tiers and rules are applied server-side from the
+ * port's `system_settings` (when wired) or sensible defaults otherwise.
+ *
+ * Used by `useDedupSuggestion` in the new-client form. Debounced on
+ * the client; this endpoint must be cheap (single port pool fetch +
+ * an in-memory dedup pass).
+ */
+export async function getMatchCandidatesHandler(
+  req: Request,
+  ctx: AuthContext,
+): Promise<NextResponse> {
+  try {
+    const url = new URL(req.url);
+    const rawEmail = url.searchParams.get('email');
+    const rawPhone = url.searchParams.get('phone');
+    const rawName = url.searchParams.get('name');
+    const country = (url.searchParams.get('country') ?? 'AI') as CountryCode;
+
+    const email = rawEmail ? normalizeEmail(rawEmail) : null;
+    const phoneResult = rawPhone ? normalizePhone(rawPhone, country) : null;
+    const nameResult = rawName ? normalizeName(rawName) : null;
+
+    // If the caller didn't give us anything useful to match on, return empty
+    // - short-circuit rather than scan every client for nothing.
+    if (!email && !phoneResult?.e164 && !nameResult?.surnameToken) {
+      return NextResponse.json({ data: [] });
+    }
+
+    // Build the input candidate.
+    const input: MatchCandidate = {
+      id: '__incoming__',
+      fullName: nameResult?.display ?? null,
+      surnameToken: nameResult?.surnameToken ?? null,
+      emails: email ? [email] : [],
+      phonesE164: phoneResult?.e164 ? [phoneResult.e164] : [],
+      countryIso: country,
+    };
+
+    // Fetch the live pool for this port. We keep this O(N) over clients
+    // since the dedup library does its own blocking; for ports with
+    // thousands of clients we can later restrict by surname-token /
+    // contact lookups, but for current scale the simple full-pool fetch
+    // is fine.
+    const liveClients = await db
+      .select({
+        id: clients.id,
+        fullName: clients.fullName,
+        nationalityIso: clients.nationalityIso,
+      })
+      .from(clients)
+      .where(and(eq(clients.portId, ctx.portId)));
+
+    if (liveClients.length === 0) {
+      return NextResponse.json({ data: [] });
+    }
+
+    const clientIds = liveClients.map((c) => c.id);
+    const contactRows = await db
+      .select({
+        clientId: clientContacts.clientId,
+        channel: clientContacts.channel,
+        value: clientContacts.value,
+        valueE164: clientContacts.valueE164,
+      })
+      .from(clientContacts)
+      .where(inArray(clientContacts.clientId, clientIds));
+
+    // Group contacts by client for the candidate map.
+    const emailsByClient = new Map<string, string[]>();
+    const phonesByClient = new Map<string, string[]>();
+    for (const c of contactRows) {
+      if (c.channel === 'email') {
+        const arr = emailsByClient.get(c.clientId) ?? [];
+        arr.push(c.value.toLowerCase());
+        emailsByClient.set(c.clientId, arr);
+      } else if (c.channel === 'phone' || c.channel === 'whatsapp') {
+        if (c.valueE164) {
+          const arr = phonesByClient.get(c.clientId) ?? [];
+          arr.push(c.valueE164);
+          phonesByClient.set(c.clientId, arr);
+        }
+      }
+    }
+
+    const pool: MatchCandidate[] = liveClients.map((c) => {
+      const named = normalizeName(c.fullName);
+      return {
+        id: c.id,
+        fullName: c.fullName,
+        surnameToken: named.surnameToken ?? null,
+        emails: emailsByClient.get(c.id) ?? [],
+        phonesE164: phonesByClient.get(c.id) ?? [],
+        countryIso: (c.nationalityIso as CountryCode | null) ?? null,
+      };
+    });
+
+    const matches = findClientMatches(input, pool, {
+      highScore: 90,
+      mediumScore: 50,
+    });
+
+    // Only return medium+ - low-confidence noise isn't useful at the
+    // create-form layer (background scoring queue picks those up).
+    const useful = matches.filter((m) => m.confidence !== 'low');
+    if (useful.length === 0) {
+      return NextResponse.json({ data: [] });
+    }
+
+    // Pull a quick summary for each surfaced candidate so the suggestion
+    // card has enough to render ("Marcus Laurent · 2 interests · last
+    // contact 9d ago").
+    const summarizedIds = useful.map((m) => m.candidate.id);
+    const interestCounts = await db
+      .select({ clientId: interests.clientId })
+      .from(interests)
+      .where(inArray(interests.clientId, summarizedIds));
+    const interestsByClient = new Map<string, number>();
+    for (const r of interestCounts) {
+      interestsByClient.set(r.clientId, (interestsByClient.get(r.clientId) ?? 0) + 1);
+    }
+
+    const data = useful.map((m) => ({
+      clientId: m.candidate.id,
+      fullName: m.candidate.fullName,
+      score: m.score,
+      confidence: m.confidence,
+      reasons: m.reasons,
+      interestCount: interestsByClient.get(m.candidate.id) ?? 0,
+      emails: m.candidate.emails,
+      phonesE164: m.candidate.phonesE164,
+    }));
+
+    return NextResponse.json({ data });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

src/app/api/v1/clients/match-candidates/route.ts

@@ -0,0 +1,4 @@
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { getMatchCandidatesHandler } from './handlers';
+
+export const GET = withAuth(withPermission('clients', 'view', getMatchCandidatesHandler));

src/app/api/v1/companies/[id]/members/[mid]/handlers.ts

@@ -0,0 +1,47 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { endMembership, updateMembership } from '@/lib/services/company-memberships.service';
+import { endMembershipSchema, updateMembershipSchema } from '@/lib/validators/company-memberships';
+
+export const patchHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const body = await parseBody(req, updateMembershipSchema);
+    const updated = await updateMembership(params.mid!, ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: updated });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const deleteHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    let endDate = new Date();
+    const text = await req.text();
+    if (text.length > 0) {
+      const parsed = endMembershipSchema.parse(JSON.parse(text));
+      endDate = parsed.endDate;
+    }
+    await endMembership(
+      params.mid!,
+      ctx.portId,
+      { endDate },
+      {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      },
+    );
+    return new NextResponse(null, { status: 204 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/companies/[id]/members/[mid]/route.ts

@@ -1,50 +1,6 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { parseBody } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { endMembership, updateMembership } from '@/lib/services/company-memberships.service';
-import { endMembershipSchema, updateMembershipSchema } from '@/lib/validators/company-memberships';
-
-export const patchHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const body = await parseBody(req, updateMembershipSchema);
-    const updated = await updateMembership(params.mid!, ctx.portId, body, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return NextResponse.json({ data: updated });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const deleteHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    let endDate = new Date();
-    const text = await req.text();
-    if (text.length > 0) {
-      const parsed = endMembershipSchema.parse(JSON.parse(text));
-      endDate = parsed.endDate;
-    }
-    await endMembership(
-      params.mid!,
-      ctx.portId,
-      { endDate },
-      {
-        userId: ctx.userId,
-        portId: ctx.portId,
-        ipAddress: ctx.ipAddress,
-        userAgent: ctx.userAgent,
-      },
-    );
-    return new NextResponse(null, { status: 204 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { patchHandler, deleteHandler } from './handlers';
 
 export const PATCH = withAuth(withPermission('memberships', 'manage', patchHandler));
 export const DELETE = withAuth(withPermission('memberships', 'manage', deleteHandler));

src/app/api/v1/companies/[id]/members/[mid]/set-primary/handlers.ts

@@ -0,0 +1,19 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { setPrimary } from '@/lib/services/company-memberships.service';
+
+export const setPrimaryHandler: RouteHandler = async (_req, ctx, params) => {
+  try {
+    const membership = await setPrimary(params.mid!, ctx.portId, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: membership });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/companies/[id]/members/[mid]/set-primary/route.ts

@@ -1,21 +1,5 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { errorResponse } from '@/lib/errors';
-import { setPrimary } from '@/lib/services/company-memberships.service';
-
-export const setPrimaryHandler: RouteHandler = async (_req, ctx, params) => {
-  try {
-    const membership = await setPrimary(params.mid!, ctx.portId, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return NextResponse.json({ data: membership });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { setPrimaryHandler } from './handlers';
 
 export const POST = withAuth(withPermission('memberships', 'manage', setPrimaryHandler));

src/app/api/v1/companies/[id]/members/handlers.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseBody, parseQuery } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { addMembership, listByCompany } from '@/lib/services/company-memberships.service';
+import { addMembershipSchema } from '@/lib/validators/company-memberships';
+
+const listQuerySchema = z.object({
+  activeOnly: z
+    .enum(['true', 'false'])
+    .transform((v) => v === 'true')
+    .default('true'),
+});
+
+export const listHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const { activeOnly } = parseQuery(req, listQuerySchema);
+    const memberships = await listByCompany(params.id!, ctx.portId, { activeOnly });
+    return NextResponse.json({ data: memberships });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const createHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const body = await parseBody(req, addMembershipSchema);
+    const membership = await addMembership(params.id!, ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: membership }, { status: 201 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/companies/[id]/members/route.ts

@@ -1,43 +1,6 @@
-import { NextResponse } from 'next/server';
-import { z } from 'zod';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { parseBody, parseQuery } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { addMembership, listByCompany } from '@/lib/services/company-memberships.service';
-import { addMembershipSchema } from '@/lib/validators/company-memberships';
-
-const listQuerySchema = z.object({
-  activeOnly: z
-    .enum(['true', 'false'])
-    .transform((v) => v === 'true')
-    .default('true'),
-});
-
-export const listHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const { activeOnly } = parseQuery(req, listQuerySchema);
-    const memberships = await listByCompany(params.id!, ctx.portId, { activeOnly });
-    return NextResponse.json({ data: memberships });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const createHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const body = await parseBody(req, addMembershipSchema);
-    const membership = await addMembership(params.id!, ctx.portId, body, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return NextResponse.json({ data: membership }, { status: 201 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { listHandler, createHandler } from './handlers';
 
 export const GET = withAuth(withPermission('memberships', 'view', listHandler));
 export const POST = withAuth(withPermission('memberships', 'manage', createHandler));

src/app/api/v1/companies/autocomplete/handlers.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { autocomplete } from '@/lib/services/companies.service';
+
+export const autocompleteHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const q = req.nextUrl.searchParams.get('q');
+    if (!q) {
+      return NextResponse.json({ data: [] });
+    }
+    const companies = await autocomplete(ctx.portId, q);
+    return NextResponse.json({ data: companies });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/companies/autocomplete/route.ts

@@ -1,20 +1,5 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { errorResponse } from '@/lib/errors';
-import { autocomplete } from '@/lib/services/companies.service';
-
-export const autocompleteHandler: RouteHandler = async (req, ctx) => {
-  try {
-    const q = req.nextUrl.searchParams.get('q');
-    if (!q) {
-      return NextResponse.json({ data: [] });
-    }
-    const companies = await autocomplete(ctx.portId, q);
-    return NextResponse.json({ data: companies });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { autocompleteHandler } from './handlers';
 
 export const GET = withAuth(withPermission('companies', 'view', autocompleteHandler));

src/app/api/v1/expenses/[id]/merge/route.ts

@@ -7,7 +7,7 @@ import { errorResponse } from '@/lib/errors';
 import { mergeDuplicate } from '@/lib/services/expense-dedup.service';
 
 const mergeSchema = z.object({
-  /** Surviving expense id — typically the row's existing `duplicateOf` pointer. */
+  /** Surviving expense id - typically the row's existing `duplicateOf` pointer. */
   targetId: z.string().min(1),
 });
 

src/app/api/v1/expenses/scan-receipt/route.ts

@@ -51,7 +51,7 @@ export const POST = withAuth(
           });
         }
 
-        // Per-port budget gate — refuse the call before we spend tokens
+        // Per-port budget gate - refuse the call before we spend tokens
         // when the port has already hit its hard cap, or when the request
         // would push it past the cap. Soft-cap warnings ride along on the
         // success response so the UI can show a banner without blocking.
@@ -99,7 +99,7 @@ export const POST = withAuth(
           });
         } catch (err) {
           logger.error({ err, provider: config.provider }, 'OCR provider call failed');
-          // Provider hiccup — degrade to manual entry rather than 500-ing.
+          // Provider hiccup - degrade to manual entry rather than 500-ing.
           return NextResponse.json({
             data: {
               parsed: EMPTY,

src/app/api/v1/files/folders/route.ts

@@ -16,7 +16,7 @@ export const POST = withAuth(
     try {
       const body = await parseBody(req, createFolderSchema);
 
-      // Sanitize path — no null bytes, no path traversal
+      // Sanitize path - no null bytes, no path traversal
       const safePath = body.path
         .replace(/\x00/g, '')
         .replace(/\.\.\//g, '')

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

@@ -0,0 +1,41 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { clearInterestOutcome, setInterestOutcome } from '@/lib/services/interests.service';
+import { clearOutcomeSchema, setOutcomeSchema } from '@/lib/validators/interests';
+
+export const POST = withAuth(
+  withPermission('interests', 'change_stage', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, setOutcomeSchema);
+      const result = await setInterestOutcome(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: result });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('interests', 'change_stage', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, clearOutcomeSchema);
+      const result = await clearInterestOutcome(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: result });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

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

@@ -20,7 +20,7 @@ export const GET = withAuth(
   }),
 );
 
-// POST /api/v1/interests/[id]/recommendations — add manual recommendation
+// POST /api/v1/interests/[id]/recommendations - add manual recommendation
 export const POST = withAuth(
   withPermission('interests', 'edit', async (req, ctx, params) => {
     try {

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

@@ -7,6 +7,26 @@ import { db } from '@/lib/db';
 import { interests } from '@/lib/db/schema/interests';
 import { auditLogs } from '@/lib/db/schema/system';
 import { documents, documentEvents } from '@/lib/db/schema/documents';
+import { user } from '@/lib/db/schema/users';
+import { stageLabel } from '@/lib/constants';
+
+const OUTCOME_LABELS: Record<string, string> = {
+  won: 'Won',
+  lost_other_marina: 'Lost - went to another marina',
+  lost_unqualified: 'Lost - unqualified',
+  lost_no_response: 'Lost - no response',
+  cancelled: 'Cancelled',
+};
+
+const DOC_EVENT_LABELS: Record<string, string> = {
+  sent: 'sent for signing',
+  completed: 'fully signed',
+  signed: 'signed by recipient',
+  rejected: 'rejected',
+  expired: 'expired',
+  cancelled: 'cancelled',
+  reminder_sent: 'reminder sent',
+};
 
 interface TimelineEvent {
   id: string;
@@ -14,6 +34,10 @@ interface TimelineEvent {
   action: string;
   description: string;
   userId: string | null;
+  /** Resolved display name for `userId`. `'system'` for auto-events; null when
+   *  the user has been deleted or the event has no actor. Falls back to
+   *  email-localpart if the user has no display name. */
+  userName: string | null;
   createdAt: Date;
   metadata: Record<string, unknown>;
 }
@@ -33,12 +57,7 @@ export const GET = withAuth(
       const auditRows = await db
         .select()
         .from(auditLogs)
-        .where(
-          and(
-            eq(auditLogs.entityType, 'interest'),
-            eq(auditLogs.entityId, interestId),
-          ),
-        )
+        .where(and(eq(auditLogs.entityType, 'interest'), eq(auditLogs.entityId, interestId)))
         .orderBy(desc(auditLogs.createdAt))
         .limit(50);
 
@@ -67,28 +86,82 @@ export const GET = withAuth(
 
       const docTitles = Object.fromEntries(interestDocs.map((d) => [d.id, d.title]));
 
+      // Resolve display names for any `userId` that is a real user row (the
+      // sentinel value 'system' is used for auto-events and isn't joined).
+      const realUserIds = Array.from(
+        new Set(auditRows.map((r) => r.userId).filter((u): u is string => !!u && u !== 'system')),
+      );
+      const userRows =
+        realUserIds.length > 0
+          ? await db
+              .select({ id: user.id, name: user.name, email: user.email })
+              .from(user)
+              .where(inArray(user.id, realUserIds))
+          : [];
+      const userNameById = new Map<string, string>(
+        userRows.map((u) => [u.id, u.name?.trim() || u.email.split('@')[0] || 'User']),
+      );
+      const resolveUserName = (userId: string | null): string | null => {
+        if (!userId) return null;
+        if (userId === 'system') return 'system';
+        return userNameById.get(userId) ?? null;
+      };
+
       // Union and sort
       const auditEvents: TimelineEvent[] = auditRows.map((row) => ({
         id: row.id,
         type: 'audit',
         action: row.action,
-        description: buildAuditDescription(row.action, row.newValue as Record<string, unknown> | null),
+        description: buildAuditDescription(
+          row.action,
+          row.newValue as Record<string, unknown> | null,
+          (row.metadata as Record<string, unknown>) ?? {},
+          row.userId,
+        ),
         userId: row.userId,
+        userName: resolveUserName(row.userId),
         createdAt: row.createdAt,
         metadata: (row.metadata as Record<string, unknown>) ?? {},
       }));
 
-      const docEvents: TimelineEvent[] = docEventRows.map((row) => ({
+      const docEvents: TimelineEvent[] = docEventRows.map((row) => {
+        const title = docTitles[row.documentId] ?? row.documentId;
+        const action = DOC_EVENT_LABELS[row.eventType] ?? row.eventType;
+        return {
           id: row.id,
           type: 'document_event',
           action: row.eventType,
-        description: `Document "${docTitles[row.documentId] ?? row.documentId}": ${row.eventType}`,
+          description: `Document "${title}" ${action}`,
           userId: null,
+          userName: null,
           createdAt: row.createdAt,
           metadata: (row.eventData as Record<string, unknown>) ?? {},
-      }));
+        };
+      });
 
       const allEvents = [...auditEvents, ...docEvents];
+
+      // Fallback: when no audit-log entries exist for this interest (typical
+      // for seed/imported data inserted directly into the table without going
+      // through the service), synthesize a "Created at <stage>" event so the
+      // tab isn't empty when the interest is clearly past `open`.
+      const hasCreateAudit = allEvents.some((e) => e.action === 'create');
+      if (!hasCreateAudit) {
+        const stage = stageLabel(interest.pipelineStage);
+        const created = interest.createdAt ?? new Date();
+        allEvents.push({
+          id: `synth-${interest.id}-create`,
+          type: 'audit',
+          action: 'create',
+          description:
+            interest.pipelineStage === 'open' ? 'Interest created' : `Interest created at ${stage}`,
+          userId: null,
+          userName: null,
+          createdAt: created,
+          metadata: { synthetic: true },
+        });
+      }
+
       allEvents.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
 
       return NextResponse.json({ data: allEvents.slice(0, 50) });
@@ -101,12 +174,39 @@ export const GET = withAuth(
 function buildAuditDescription(
   action: string,
   newValue: Record<string, unknown> | null,
+  metadata: Record<string, unknown>,
+  userId: string | null,
 ): string {
   if (action === 'create') return 'Interest created';
   if (action === 'archive') return 'Interest archived';
   if (action === 'restore') return 'Interest restored';
+
+  const type = metadata.type;
+
+  if (type === 'outcome_set') {
+    const outcomeKey = (newValue?.outcome as string | undefined) ?? '';
+    const label = OUTCOME_LABELS[outcomeKey] ?? outcomeKey ?? 'Closed';
+    const reason = (newValue?.reason as string | undefined) ?? '';
+    return reason ? `Marked as ${label} - ${reason}` : `Marked as ${label}`;
+  }
+
+  if (type === 'outcome_cleared') {
+    const stage = (newValue?.pipelineStage as string | undefined) ?? '';
+    return stage ? `Reopened to ${stageLabel(stage)}` : 'Reopened';
+  }
+
+  if (type === 'stage_change' && newValue?.pipelineStage) {
+    const stage = stageLabel(newValue.pipelineStage as string);
+    const reason = (newValue.reason as string | undefined) ?? '';
+    const auto = userId === 'system';
+    if (auto) {
+      return reason ? `${stage} (auto-advanced - ${reason})` : `Stage advanced to ${stage}`;
+    }
+    return reason ? `Stage changed to ${stage} - ${reason}` : `Stage changed to ${stage}`;
+  }
+
   if (action === 'update' && newValue?.pipelineStage) {
-    return `Stage changed to "${newValue.pipelineStage}"`;
+    return `Stage changed to ${stageLabel(newValue.pipelineStage as string)}`;
   }
   if (action === 'update') return 'Interest updated';
   return action;

src/app/api/v1/saved-views/[id]/handlers.ts

@@ -0,0 +1,68 @@
+import { and, eq } from 'drizzle-orm';
+import { NextResponse } from 'next/server';
+
+import type { AuthContext } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { db } from '@/lib/db';
+import { savedViews } from '@/lib/db/schema';
+import { errorResponse } from '@/lib/errors';
+import { savedViewsService } from '@/lib/services/saved-views.service';
+import { updateSavedViewSchema } from '@/lib/validators/saved-views';
+
+/**
+ * Resolves the view and enforces ownership before mutating.
+ *
+ * Returns a 404 when the view does not exist (or lives in a different port)
+ * and a 403 when it belongs to a different user. The 404-before-403 split
+ * matches the rest of the API and avoids leaking the existence of another
+ * user's saved view via timing or status code.
+ */
+async function assertViewOwner(
+  id: string,
+  portId: string,
+  userId: string,
+): Promise<NextResponse | null> {
+  const view = await db.query.savedViews.findFirst({
+    where: and(eq(savedViews.id, id), eq(savedViews.portId, portId)),
+  });
+  if (!view) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  }
+  if (view.userId !== userId) {
+    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+  }
+  return null;
+}
+
+export async function patchHandler(
+  req: Request,
+  ctx: AuthContext,
+  params: { id?: string },
+): Promise<NextResponse> {
+  try {
+    const id = params.id ?? '';
+    const denied = await assertViewOwner(id, ctx.portId, ctx.userId);
+    if (denied) return denied;
+    const body = await parseBody(req as never, updateSavedViewSchema);
+    const view = await savedViewsService.update(ctx.portId, ctx.userId, id, body);
+    return NextResponse.json({ data: view });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}
+
+export async function deleteHandler(
+  _req: Request,
+  ctx: AuthContext,
+  params: { id?: string },
+): Promise<NextResponse> {
+  try {
+    const id = params.id ?? '';
+    const denied = await assertViewOwner(id, ctx.portId, ctx.userId);
+    if (denied) return denied;
+    await savedViewsService.delete(ctx.portId, ctx.userId, id);
+    return NextResponse.json({ data: null }, { status: 200 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+}

src/app/api/v1/saved-views/[id]/route.ts

@@ -1,28 +1,5 @@
-import { NextResponse } from 'next/server';
-
 import { withAuth } from '@/lib/api/helpers';
-import { parseBody } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { savedViewsService } from '@/lib/services/saved-views.service';
-import { updateSavedViewSchema } from '@/lib/validators/saved-views';
+import { patchHandler, deleteHandler } from './handlers';
 
-export const PATCH = withAuth(async (req, ctx, params) => {
-  try {
-    const id = params.id ?? '';
-    const body = await parseBody(req, updateSavedViewSchema);
-    const view = await savedViewsService.update(ctx.portId, ctx.userId, id, body);
-    return NextResponse.json({ data: view });
-  } catch (error) {
-    return errorResponse(error);
-  }
-});
-
-export const DELETE = withAuth(async (_req, ctx, params) => {
-  try {
-    const id = params.id ?? '';
-    await savedViewsService.delete(ctx.portId, ctx.userId, id);
-    return NextResponse.json({ data: null }, { status: 200 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-});
+export const PATCH = withAuth(patchHandler);
+export const DELETE = withAuth(deleteHandler);

src/app/api/v1/search/route.ts

@@ -18,7 +18,7 @@ export const GET = withAuth(async (req: NextRequest, ctx) => {
 
     const results = await search(ctx.portId, q);
 
-    // Fire-and-forget — do not await
+    // Fire-and-forget - do not await
     saveRecentSearch(ctx.userId, ctx.portId, q);
 
     return NextResponse.json(results);

src/app/api/v1/website-analytics/route.ts

@@ -0,0 +1,113 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { ALL_RANGES, type DateRange, type PresetDateRange } from '@/lib/analytics/range';
+import {
+  getActiveVisitors,
+  getMetric,
+  getPageviewsSeries,
+  getStats,
+  type UmamiMetricType,
+} from '@/lib/services/umami.service';
+
+/**
+ * GET /api/v1/website-analytics?metric=...&range=...
+ *
+ * Single endpoint serving every Umami widget on the /website-analytics
+ * page. Mirrors the shape of /api/v1/analytics so the client side can
+ * reuse the same hook pattern.
+ *
+ * Supported metrics:
+ *   - stats              → KPI tiles (pageviews, visitors, visits, etc.)
+ *   - pageviews          → time-series for the trend chart
+ *   - active             → live "right now" count (range ignored)
+ *   - top-{type}         → top pages/referrers/countries/etc.
+ *                          where type ∈ url|referrer|country|browser|
+ *                          os|device|event
+ *
+ * Range param accepts the same presets as /api/v1/analytics, plus
+ * `range=custom&from=YYYY-MM-DD&to=YYYY-MM-DD`.
+ */
+
+const ISO_DATE_RX = /^\d{4}-\d{2}-\d{2}$/;
+const TOP_METRIC_RX = /^top-(url|referrer|country|browser|os|device|event)$/;
+
+function parseRange(req: NextRequest): DateRange | { error: string } {
+  const url = new URL(req.url);
+  const rawRange = url.searchParams.get('range') ?? '30d';
+  const fromParam = url.searchParams.get('from');
+  const toParam = url.searchParams.get('to');
+
+  if (rawRange === 'custom') {
+    if (!fromParam || !toParam) {
+      return { error: 'Custom range requires `from` and `to` (YYYY-MM-DD)' };
+    }
+    if (!ISO_DATE_RX.test(fromParam) || !ISO_DATE_RX.test(toParam)) {
+      return { error: '`from`/`to` must be ISO date strings (YYYY-MM-DD)' };
+    }
+    if (fromParam > toParam) {
+      return { error: '`from` must be on or before `to`' };
+    }
+    // Round-trip date check (catches "2026-02-31" type rollovers).
+    for (const [label, raw] of [
+      ['from', fromParam],
+      ['to', toParam],
+    ] as const) {
+      const d = new Date(`${raw}T00:00:00.000Z`);
+      if (Number.isNaN(d.getTime()) || d.toISOString().slice(0, 10) !== raw) {
+        return { error: `\`${label}\` is not a valid calendar date` };
+      }
+    }
+    return { kind: 'custom', from: fromParam, to: toParam };
+  }
+  if (!ALL_RANGES.includes(rawRange as PresetDateRange)) {
+    return { error: 'Invalid range' };
+  }
+  return rawRange as PresetDateRange;
+}
+
+export const GET = withAuth(
+  withPermission('reports', 'view_analytics', async (req: NextRequest, ctx) => {
+    const url = new URL(req.url);
+    const metric = url.searchParams.get('metric');
+    if (!metric) {
+      return NextResponse.json({ error: 'Missing metric' }, { status: 400 });
+    }
+
+    const rangeOrError = parseRange(req);
+    if (typeof rangeOrError === 'object' && 'error' in rangeOrError) {
+      return NextResponse.json({ error: rangeOrError.error }, { status: 400 });
+    }
+    const range = rangeOrError as DateRange;
+
+    try {
+      let data: unknown;
+
+      if (metric === 'stats') {
+        data = await getStats(ctx.portId, range);
+      } else if (metric === 'pageviews') {
+        data = await getPageviewsSeries(ctx.portId, range);
+      } else if (metric === 'active') {
+        data = await getActiveVisitors(ctx.portId);
+      } else if (TOP_METRIC_RX.test(metric)) {
+        const type = metric.replace(/^top-/, '') as UmamiMetricType;
+        const limit = Number(url.searchParams.get('limit') ?? 10);
+        data = await getMetric(ctx.portId, range, type, limit);
+      } else {
+        return NextResponse.json({ error: `Unknown metric: ${metric}` }, { status: 400 });
+      }
+
+      // `data === null` from the service means Umami isn't configured for
+      // this port - surface that explicitly so the UI can render a
+      // "configure your credentials" empty state instead of a chart.
+      if (data === null) {
+        return NextResponse.json({ error: 'umami_not_configured', metric, range }, { status: 200 });
+      }
+
+      return NextResponse.json({ metric, range, data });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Unknown error';
+      return NextResponse.json({ error: message, metric, range }, { status: 502 });
+    }
+  }),
+);

src/app/api/v1/yachts/[id]/ownership-history/handlers.ts

@@ -0,0 +1,14 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { listOwnershipHistory } from '@/lib/services/yachts.service';
+
+export const historyHandler: RouteHandler = async (_req, ctx, params) => {
+  try {
+    const history = await listOwnershipHistory(params.id!, ctx.portId);
+    return NextResponse.json({ data: history });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/yachts/[id]/ownership-history/route.ts

@@ -1,16 +1,5 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { errorResponse } from '@/lib/errors';
-import { listOwnershipHistory } from '@/lib/services/yachts.service';
-
-export const historyHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const history = await listOwnershipHistory(params.id!, ctx.portId);
-    return NextResponse.json({ data: history });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { historyHandler } from './handlers';
 
 export const GET = withAuth(withPermission('yachts', 'view', historyHandler));

src/app/api/v1/yachts/[id]/transfer/handlers.ts

@@ -0,0 +1,22 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { transferOwnership } from '@/lib/services/yachts.service';
+import { transferOwnershipSchema } from '@/lib/validators/yachts';
+
+export const transferHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const body = await parseBody(req, transferOwnershipSchema);
+    const yacht = await transferOwnership(params.id!, ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: yacht });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/yachts/[id]/transfer/route.ts

@@ -1,24 +1,5 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { parseBody } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { transferOwnership } from '@/lib/services/yachts.service';
-import { transferOwnershipSchema } from '@/lib/validators/yachts';
-
-export const transferHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const body = await parseBody(req, transferOwnershipSchema);
-    const yacht = await transferOwnership(params.id!, ctx.portId, body, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return NextResponse.json({ data: yacht });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { transferHandler } from './handlers';
 
 export const POST = withAuth(withPermission('yachts', 'transfer', transferHandler));

src/app/api/v1/yachts/autocomplete/handlers.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { autocomplete } from '@/lib/services/yachts.service';
+
+export const autocompleteHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const q = req.nextUrl.searchParams.get('q');
+    if (!q) {
+      return NextResponse.json({ data: [] });
+    }
+    const yachts = await autocomplete(ctx.portId, q);
+    return NextResponse.json({ data: yachts });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/yachts/autocomplete/route.ts

@@ -1,20 +1,5 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { errorResponse } from '@/lib/errors';
-import { autocomplete } from '@/lib/services/yachts.service';
-
-export const autocompleteHandler: RouteHandler = async (req, ctx) => {
-  try {
-    const q = req.nextUrl.searchParams.get('q');
-    if (!q) {
-      return NextResponse.json({ data: [] });
-    }
-    const yachts = await autocomplete(ctx.portId, q);
-    return NextResponse.json({ data: yachts });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { autocompleteHandler } from './handlers';
 
 export const GET = withAuth(withPermission('yachts', 'view', autocompleteHandler));