fix(residential): mobile card list alongside the desktop table

Both the residential-clients and residential-interests pages rendered
plain HTML <table>s with 5–6 columns directly. At 390px viewport the
header columns clipped at the right edge — "Sour..." for the clients
page, no header for the interests page either.

Adds a parallel mobile card list:
  - <table> stays inside `hidden lg:block` (unchanged at lg+)
  - new card list inside `lg:hidden` mirrors the row data:
    - Clients: name + status pill on top, then email · phone ·
      residence · source as a wrap-friendly meta row.
    - Interests: stage label as headline, updated-at on the right,
      preferences (line-clamp-2) and notes (line-clamp-1) below,
      source small at the bottom.
  - Each card is a Link to the detail page (matching the row click
    target on desktop).
  - Empty + loading states render as a centered card on mobile.

This is the same `hidden lg:block` / `lg:hidden` pattern used for the
main /clients and /interests pages. Doesn't refactor to the full
DataView primitive (would mean rebuilding the residential data layer
on TanStack Table) — keeps the change tightly scoped to the visible
output.

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-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/migrate-from-nocodb.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 harbor-royale
+ *     Same, but tags the planned writes with the named port (matters for
+ *     the apply phase — every client/interest belongs to one port).
+ *
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --apply --report .migration/<dir>/
+ *     [Not yet implemented — apply phase comes in a follow-up PR.]
+ *
+ * Design reference: docs/superpowers/specs/2026-05-03-dedup-and-migration-design.md §9.
+ */
+
+import 'dotenv/config';
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+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;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    dryRun: false,
+    apply: false,
+    portSlug: null,
+    reportDir: null,
+  };
+  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 === '-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 --report .migration/<dir>/
+    Apply phase. (Not yet implemented.)
+
+Flags:
+  --dry-run               Read NocoDB, write report only.
+  --apply                 Actually write to the new DB. (Not yet supported.)
+  --port-slug <slug>      Port slug to attach to all imported entities.
+                          Defaults to the first available port if omitted.
+  --report <dir>          Path to a previously-generated report dir
+                          (only used by --apply).
+  -h, --help              Show this help.
+`);
+}
+
+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);
+  }
+
+  if (args.apply) {
+    console.error('--apply is not yet implemented in this version. P3 ships dry-run first.');
+    console.error('See docs/superpowers/specs/2026-05-03-dedup-and-migration-design.md §9.2.');
+    process.exit(2);
+  }
+
+  // ── Dry-run path ───────────────────────────────────────────────────────────
+
+  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 (the script itself
+  // lives in scripts/; we want the .migration dir at the repo 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);
+
+  // ── Console 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(
+    `  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}`);
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error('[migrate] Fatal error:', 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[] = [
   {
@@ -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,12 @@ import {
   Tag,
   Upload,
   Users,
+  UsersRound,
   Webhook,
 } from 'lucide-react';
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { PageHeader } from '@/components/shared/page-header';
 
 interface AdminSection {
   href: string;
@@ -28,7 +30,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 +59,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 +101,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 +131,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 +173,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 +197,20 @@ 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,
       },
+    ],
+  },
 ];
 
 export default async function AdminLandingPage({
@@ -164,16 +220,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 +258,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]/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)/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}
@@ -57,6 +61,9 @@ export default async function DashboardLayout({ children }: { children: React.Re
                 <main className="flex-1 overflow-y-auto bg-background p-6">{children}</main>
               </div>
             </div>
+
+            {/* Mobile shell — hidden by CSS on desktop */}
+            <MobileLayout>{children}</MobileLayout>
           </SocketProvider>
         </PermissionsProvider>
       </PortProvider>

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">
@@ -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/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/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,110 +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 } 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

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/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/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]/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/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));

src/app/api/webhooks/documenso/route.ts

@@ -6,6 +6,7 @@ import { verifyDocumensoSecret } from '@/lib/services/documenso-webhook';
 import {
   handleRecipientSigned,
   handleDocumentCompleted,
+  handleDocumentExpired,
   handleDocumentOpened,
   handleDocumentRejected,
   handleDocumentCancelled,
@@ -139,6 +140,10 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
         await handleDocumentCancelled({ documentId: documensoId, signatureHash });
         break;
 
+      case 'DOCUMENT_EXPIRED':
+        await handleDocumentExpired({ documentId: documensoId });
+        break;
+
       default:
         logger.info({ event }, 'Unhandled Documenso webhook event type');
     }

src/app/globals.css

@@ -127,3 +127,45 @@
     @apply bg-muted-foreground/30;
   }
 }
+
+/* ─── Form-factor shell visibility ──────────────────────────────────────────
+ * Two shells (desktop + mobile) render to the DOM on every page; CSS hides
+ * the inactive one. The data-form-factor body attribute is set server-side
+ * from User-Agent (see src/lib/form-factor.ts). The media-query fallback
+ * handles desktop browsers resized below lg (1024px), or stripped UAs.
+ *
+ * IMPORTANT: only `display: none` rules are emitted — we never set a positive
+ * display, because the desktop shell uses Tailwind's `flex` class which would
+ * be overridden by `display: block` (same specificity, later cascade).
+ */
+[data-shell='mobile'] {
+  display: none;
+}
+
+@media (max-width: 1023.98px) {
+  [data-shell='desktop'] {
+    display: none;
+  }
+  [data-shell='mobile'] {
+    display: block;
+  }
+}
+
+body[data-form-factor='mobile'] [data-shell='desktop'] {
+  display: none;
+}
+body[data-form-factor='mobile'] [data-shell='mobile'] {
+  display: block;
+}
+
+/*
+ * React Query Devtools floating button collides with the bottom tab bar's
+ * "More" tab on mobile. The devtools panel itself remains accessible from
+ * desktop where the toggle is positioned out of the way of any UI.
+ */
+@media (max-width: 1023.98px) {
+  .tsqd-open-btn-container,
+  .tsqd-parent-container {
+    display: none !important;
+  }
+}

src/app/layout.tsx

@@ -1,6 +1,10 @@
-import type { Metadata } from 'next';
+import type { Metadata, Viewport } from 'next';
+import Script from 'next/script';
+import { headers } from 'next/headers';
 import { Inter, JetBrains_Mono } from 'next/font/google';
 import { Toaster } from 'sonner';
+import { classifyFormFactor } from '@/lib/form-factor';
+import { ReactGrabViewportSync } from '@/components/dev/react-grab-viewport-sync';
 import './globals.css';
 
 const inter = Inter({
@@ -15,20 +19,55 @@ const jetbrainsMono = JetBrains_Mono({
   display: 'swap',
 });
 
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  viewportFit: 'cover',
+  themeColor: '#1e2844',
+};
+
 export const metadata: Metadata = {
   title: {
     default: 'Port Nimara CRM',
     template: '%s | Port Nimara CRM',
   },
   description: 'Marina management system for Port Nimara',
+  appleWebApp: {
+    capable: true,
+    statusBarStyle: 'black-translucent',
+    title: 'Port Nimara',
+  },
+  icons: {
+    icon: [
+      { url: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+      { url: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+    ],
+    apple: '/apple-touch-icon.png',
+  },
 };
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const headerList = await headers();
+  const formFactor = classifyFormFactor(headerList.get('user-agent'));
+
   return (
     <html lang="en" suppressHydrationWarning>
-      <body className={`${inter.variable} ${jetbrainsMono.variable} font-sans antialiased`}>
+      <head>
+        {process.env.NODE_ENV === 'development' && (
+          <Script
+            src="//unpkg.com/react-grab/dist/index.global.js"
+            crossOrigin="anonymous"
+            strategy="beforeInteractive"
+          />
+        )}
+      </head>
+      <body
+        data-form-factor={formFactor}
+        className={`${inter.variable} ${jetbrainsMono.variable} font-sans antialiased`}
+      >
         {children}
         <Toaster richColors position="top-right" />
+        {process.env.NODE_ENV === 'development' && <ReactGrabViewportSync />}
       </body>
     </html>
   );

src/components/admin/audit/audit-log-card.tsx

@@ -0,0 +1,151 @@
+'use client';
+
+import { Activity, Clock, Eye, Pencil, Plus, Trash2, User } from 'lucide-react';
+import { formatDistanceToNow } from 'date-fns';
+
+import { ListCard, ListCardAvatar, ListCardMeta } from '@/components/shared/list-card';
+import { cn } from '@/lib/utils';
+
+interface AuditEntry {
+  id: string;
+  userId: string | null;
+  action: string;
+  entityType: string;
+  entityId: string | null;
+  fieldChanged: string | null;
+  oldValue: Record<string, unknown> | null;
+  newValue: Record<string, unknown> | null;
+  metadata: Record<string, unknown> | null;
+  ipAddress: string | null;
+  createdAt: string;
+  actor: { id: string; email: string; name: string } | null;
+}
+
+const ACTION_ACCENT: Record<string, string> = {
+  create: 'bg-emerald-400',
+  update: 'bg-blue-400',
+  delete: 'bg-rose-400',
+  viewed: 'bg-slate-300',
+};
+
+const ACTION_BADGE_COLORS: Record<string, string> = {
+  create: 'bg-green-600',
+  update: 'bg-blue-500',
+  delete: 'bg-red-600',
+  archive: 'bg-orange-500',
+  restore: 'bg-teal-500',
+  login: 'bg-gray-500',
+  permission_denied: 'bg-red-800',
+  merge: 'bg-purple-500',
+  revert: 'bg-amber-500',
+};
+
+function ActionIcon({ action }: { action: string }) {
+  if (action === 'create') return <Plus className="h-5 w-5" />;
+  if (action === 'update') return <Pencil className="h-5 w-5" />;
+  if (action === 'delete') return <Trash2 className="h-5 w-5" />;
+  if (action === 'viewed') return <Eye className="h-5 w-5" />;
+  return <Activity className="h-5 w-5" />;
+}
+
+function actionVerb(action: string): string {
+  const map: Record<string, string> = {
+    create: 'Created',
+    update: 'Updated',
+    delete: 'Deleted',
+    archive: 'Archived',
+    restore: 'Restored',
+    login: 'Logged in',
+    permission_denied: 'Permission denied',
+    merge: 'Merged',
+    revert: 'Reverted',
+    viewed: 'Viewed',
+  };
+  return map[action] ?? action.charAt(0).toUpperCase() + action.slice(1);
+}
+
+interface AuditLogCardProps {
+  entry: AuditEntry;
+}
+
+export function AuditLogCard({ entry }: AuditLogCardProps) {
+  const accentClass = ACTION_ACCENT[entry.action] ?? 'bg-slate-300';
+  const badgeColor = ACTION_BADGE_COLORS[entry.action] ?? 'bg-gray-500';
+
+  const entityTitle = `${entry.entityType.charAt(0).toUpperCase()}${entry.entityType.slice(1)}${
+    entry.entityId ? ` ${entry.entityId.slice(0, 8)}…` : ''
+  }`;
+
+  const actorName = entry.actor?.name ?? (entry.userId ? `${entry.userId.slice(0, 8)}…` : 'system');
+
+  // Changed-fields chip line: prefer fieldChanged (single field), then newValue keys
+  let changedFields: string[] = [];
+  if (entry.fieldChanged) {
+    changedFields = [entry.fieldChanged];
+  } else if (entry.newValue) {
+    changedFields = Object.keys(entry.newValue);
+  }
+  const visibleFields = changedFields.slice(0, 3);
+  const overflowCount = changedFields.length - visibleFields.length;
+
+  return (
+    <ListCard
+      href="#"
+      ariaLabel={`Audit: ${actionVerb(entry.action)} ${entityTitle}`}
+      accentClassName={accentClass}
+    >
+      <div className="flex items-start gap-3">
+        <ListCardAvatar icon={<ActionIcon action={entry.action} />} />
+        <div className="min-w-0 flex-1">
+          {/* Title: entity type + short ID */}
+          <h3 className="truncate text-base font-semibold tracking-tight text-foreground">
+            {entityTitle}
+          </h3>
+
+          {/* Subtitle: action verb + actor */}
+          <p className="mt-0.5 inline-flex items-center gap-1 truncate text-sm text-muted-foreground">
+            <User className="h-3.5 w-3.5 shrink-0 text-muted-foreground/70" aria-hidden />
+            <span className="truncate">
+              {actionVerb(entry.action)} by {actorName}
+            </span>
+          </p>
+
+          {/* Timestamp meta line */}
+          <div className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-0.5 text-xs text-muted-foreground">
+            <ListCardMeta icon={<Clock className="h-3 w-3" />}>
+              {formatDistanceToNow(new Date(entry.createdAt), { addSuffix: true })}
+            </ListCardMeta>
+          </div>
+
+          {/* Action badge + changed-fields chips */}
+          <div className="mt-1.5 flex flex-wrap items-center gap-x-2 gap-y-1">
+            <span
+              className={cn(
+                'inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium text-white',
+                badgeColor,
+              )}
+            >
+              {entry.action}
+            </span>
+
+            {visibleFields.length > 0 ? (
+              <>
+                {visibleFields.map((field) => (
+                  <span
+                    key={field}
+                    className="inline-flex items-center rounded-full bg-secondary px-2 py-0.5 text-xs text-secondary-foreground"
+                  >
+                    {field}
+                  </span>
+                ))}
+                {overflowCount > 0 ? (
+                  <span className="text-xs text-muted-foreground">+{overflowCount}</span>
+                ) : null}
+              </>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </ListCard>
+  );
+}

src/components/admin/audit/audit-log-list.tsx

@@ -19,6 +19,7 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { apiFetch } from '@/lib/api/client';
+import { AuditLogCard } from './audit-log-card';
 
 interface AuditEntry {
   id: string;
@@ -357,6 +358,7 @@ export function AuditLogList() {
           data={entries}
           isLoading={loading}
           getRowId={(row) => row.id}
+          cardRender={(row) => <AuditLogCard entry={row.original} />}
           emptyState={
             <div className="text-center py-8">
               <p className="text-muted-foreground">No audit log entries found.</p>

src/components/admin/duplicates/duplicates-review-queue.tsx

@@ -0,0 +1,215 @@
+'use client';
+
+import { useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { ArrowRight, GitMerge, X } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { PageHeader } from '@/components/shared/page-header';
+import { EmptyState } from '@/components/shared/empty-state';
+import { Skeleton } from '@/components/ui/skeleton';
+import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';
+
+interface CandidatePair {
+  id: string;
+  score: number;
+  reasons: string[];
+  createdAt: string;
+  clientA: { id: string; fullName: string; createdAt: string };
+  clientB: { id: string; fullName: string; createdAt: string };
+}
+
+/**
+ * Admin review queue for the dedup background scoring job.
+ *
+ * Lists every pending merge candidate (pairs where score >=
+ * `dedup_review_queue_threshold`). For each pair the admin can:
+ *   - Pick a winner via the side-by-side card → confirms a merge
+ *   - Dismiss → removes from the queue (a future score increase
+ *     re-creates the pair on the next scoring run)
+ *
+ * Only minimal merge UI here: the user picks which side is the winner
+ * (no per-field choice), and the loser archives. A richer side-by-side
+ * field-merge dialog is a future enhancement.
+ */
+export function DuplicatesReviewQueue() {
+  const queryClient = useQueryClient();
+
+  const { data, isLoading } = useQuery<{ data: CandidatePair[] }>({
+    queryKey: ['admin', 'duplicates'],
+    queryFn: () => apiFetch<{ data: CandidatePair[] }>('/api/v1/admin/duplicates'),
+  });
+
+  const pairs = data?.data ?? [];
+
+  return (
+    <div className="space-y-4">
+      <PageHeader
+        title="Duplicate clients"
+        description={
+          pairs.length === 0
+            ? 'No pending pairs to review.'
+            : `${pairs.length} pair${pairs.length === 1 ? '' : 's'} flagged for review.`
+        }
+      />
+
+      {isLoading ? (
+        <div className="space-y-3">
+          {[0, 1, 2].map((i) => (
+            <Skeleton key={i} className="h-32 w-full" />
+          ))}
+        </div>
+      ) : pairs.length === 0 ? (
+        <EmptyState
+          title="All clear"
+          description="The background scoring job hasn't surfaced any potential duplicates yet."
+        />
+      ) : (
+        <ul className="space-y-3">
+          {pairs.map((pair) => (
+            <li key={pair.id}>
+              <CandidateRow pair={pair} queryClient={queryClient} />
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+function CandidateRow({
+  pair,
+  queryClient,
+}: {
+  pair: CandidatePair;
+  queryClient: ReturnType<typeof useQueryClient>;
+}) {
+  const [busy, setBusy] = useState<'merge' | 'dismiss' | null>(null);
+  const [winnerId, setWinnerId] = useState<string>(pair.clientA.id);
+
+  const mergeMutation = useMutation({
+    mutationFn: () =>
+      apiFetch(`/api/v1/admin/duplicates/${pair.id}/merge`, {
+        method: 'POST',
+        body: { winnerId },
+      }),
+    onSuccess: () => {
+      const loserName =
+        winnerId === pair.clientA.id ? pair.clientB.fullName : pair.clientA.fullName;
+      const winnerName =
+        winnerId === pair.clientA.id ? pair.clientA.fullName : pair.clientB.fullName;
+      toast.success(`Merged "${loserName}" into "${winnerName}"`);
+      queryClient.invalidateQueries({ queryKey: ['admin', 'duplicates'] });
+      queryClient.invalidateQueries({ queryKey: ['clients'] });
+    },
+    onError: (err) => toast.error(err instanceof Error ? err.message : 'Merge failed'),
+    onSettled: () => setBusy(null),
+  });
+
+  const dismissMutation = useMutation({
+    mutationFn: () => apiFetch(`/api/v1/admin/duplicates/${pair.id}/dismiss`, { method: 'POST' }),
+    onSuccess: () => {
+      toast.message('Dismissed');
+      queryClient.invalidateQueries({ queryKey: ['admin', 'duplicates'] });
+    },
+    onError: (err) => toast.error(err instanceof Error ? err.message : 'Dismiss failed'),
+    onSettled: () => setBusy(null),
+  });
+
+  return (
+    <div className="rounded-lg border bg-card p-4">
+      <div className="mb-3 flex items-baseline justify-between gap-3">
+        <div>
+          <span className="rounded-full bg-muted px-2 py-0.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
+            score {pair.score}
+          </span>{' '}
+          <span className="text-xs text-muted-foreground">{pair.reasons.join(' · ')}</span>
+        </div>
+        <span className="text-xs text-muted-foreground">
+          flagged {new Date(pair.createdAt).toLocaleDateString()}
+        </span>
+      </div>
+
+      <div className="grid gap-3 sm:grid-cols-[1fr_auto_1fr]">
+        <ClientCard
+          client={pair.clientA}
+          isSelected={winnerId === pair.clientA.id}
+          onSelect={() => setWinnerId(pair.clientA.id)}
+        />
+        <div className="flex items-center justify-center text-muted-foreground">
+          <ArrowRight className="size-4" aria-hidden />
+        </div>
+        <ClientCard
+          client={pair.clientB}
+          isSelected={winnerId === pair.clientB.id}
+          onSelect={() => setWinnerId(pair.clientB.id)}
+        />
+      </div>
+
+      <div className="mt-3 flex flex-wrap items-center gap-2">
+        <Button
+          size="sm"
+          onClick={() => {
+            setBusy('merge');
+            mergeMutation.mutate();
+          }}
+          disabled={busy !== null}
+        >
+          <GitMerge className="mr-1 size-3.5" aria-hidden />
+          Merge into selected
+        </Button>
+        <Button
+          size="sm"
+          variant="ghost"
+          onClick={() => {
+            setBusy('dismiss');
+            dismissMutation.mutate();
+          }}
+          disabled={busy !== null}
+        >
+          <X className="mr-1 size-3.5" aria-hidden />
+          Dismiss
+        </Button>
+        <p className="text-xs text-muted-foreground">
+          The unselected card becomes the loser; its interests + contacts move to the selected
+          client and the original is archived.
+        </p>
+      </div>
+    </div>
+  );
+}
+
+function ClientCard({
+  client,
+  isSelected,
+  onSelect,
+}: {
+  client: CandidatePair['clientA'];
+  isSelected: boolean;
+  onSelect: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onSelect}
+      className={cn(
+        'rounded-md border p-3 text-left transition-colors',
+        isSelected
+          ? 'border-primary bg-primary/5 ring-1 ring-primary/30'
+          : 'border-border hover:bg-muted/40',
+      )}
+    >
+      <p className="text-sm font-medium">{client.fullName}</p>
+      <p className="mt-0.5 text-[11px] text-muted-foreground">
+        Created {new Date(client.createdAt).toLocaleDateString()}
+      </p>
+      {isSelected ? (
+        <span className="mt-1 inline-block rounded-full bg-primary/10 px-1.5 py-0.5 text-[10px] font-semibold text-primary">
+          KEEP
+        </span>
+      ) : null}
+    </button>
+  );
+}

src/components/admin/settings/settings-manager.tsx

@@ -68,9 +68,11 @@ const KNOWN_SETTINGS: Array<{
       open: 0.05,
       details_sent: 0.1,
       in_communication: 0.2,
-      signed_eoi_nda: 0.4,
-      deposit_10pct: 0.6,
-      contract: 0.8,
+      eoi_sent: 0.4,
+      eoi_signed: 0.6,
+      deposit_10pct: 0.75,
+      contract_sent: 0.85,
+      contract_signed: 0.95,
       completed: 1.0,
     },
   },
@@ -105,6 +107,17 @@ const KNOWN_SETTINGS: Array<{
     type: 'json',
     defaultValue: [],
   },
+  {
+    key: 'eoi_signers',
+    label: 'EOI Signers',
+    description:
+      'Internal staff who countersign every EOI. JSON object with `developer` (signs after the client) and `approver` (final approval). Both fields take `{ name, email }`.',
+    type: 'json',
+    defaultValue: {
+      developer: { name: 'David Mizrahi', email: 'dm@portnimara.com' },
+      approver: { name: 'Abbie May', email: 'sales@portnimara.com' },
+    },
+  },
 ];
 
 export function SettingsManager() {
@@ -228,7 +241,14 @@ export function SettingsManager() {
             </CardHeader>
             <CardContent className="space-y-4">
               {KNOWN_SETTINGS.filter((s) => s.type === 'string').map((setting) => (
-                <div key={setting.key} className="flex items-center justify-between gap-4">
+                <div
+                  key={setting.key}
+                  // Stack label/description above the input on phone widths.
+                  // The previous flex row crushed the label column into a
+                  // narrow vertical stripe ("Inquiry / Contact / Email" wrapping
+                  // one word per line) while the input took the rest.
+                  className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between sm:gap-4"
+                >
                   <div className="flex-1">
                     <Label>{setting.label}</Label>
                     <p className="text-xs text-muted-foreground">{setting.description}</p>
@@ -236,7 +256,7 @@ export function SettingsManager() {
                   <div className="flex items-center gap-2">
                     <Input
                       type="text"
-                      className="w-64"
+                      className="w-full sm:w-64"
                       value={String(getEffectiveValue(setting.key, setting.defaultValue) ?? '')}
                       onChange={(e) =>
                         setValues((prev) => ({
@@ -270,7 +290,10 @@ export function SettingsManager() {
           </CardHeader>
           <CardContent className="space-y-4">
             {KNOWN_SETTINGS.filter((s) => s.type === 'number').map((setting) => (
-              <div key={setting.key} className="flex items-center justify-between gap-4">
+              <div
+                key={setting.key}
+                className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between sm:gap-4"
+              >
                 <div className="flex-1">
                   <Label>{setting.label}</Label>
                   <p className="text-xs text-muted-foreground">{setting.description}</p>
@@ -278,7 +301,7 @@ export function SettingsManager() {
                 <div className="flex items-center gap-2">
                   <Input
                     type="number"
-                    className="w-24"
+                    className="w-full sm:w-24"
                     value={String(getEffectiveValue(setting.key, setting.defaultValue) ?? '')}
                     onChange={(e) =>
                       setValues((prev) => ({

src/components/admin/system-monitoring-dashboard.tsx

@@ -7,6 +7,7 @@ import { apiFetch } from '@/lib/api/client';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { ServiceHealthCard } from './service-health-card';
 import { QueueOverview } from './queue-overview';
+import { PageHeader } from '@/components/shared/page-header';
 import type {
   HealthStatus,
   QueueStatus,
@@ -17,16 +18,14 @@ import type {
 export function SystemMonitoringDashboard() {
   const { data: healthData } = useQuery({
     queryKey: ['system', 'health'],
-    queryFn: () =>
-      apiFetch<{ data: HealthStatus }>('/api/v1/admin/health').then((r) => r.data),
+    queryFn: () => apiFetch<{ data: HealthStatus }>('/api/v1/admin/health').then((r) => r.data),
     staleTime: 30_000,
     refetchInterval: 30_000,
   });
 
   const { data: queuesData } = useQuery({
     queryKey: ['system', 'queues'],
-    queryFn: () =>
-      apiFetch<{ data: QueueStatus[] }>('/api/v1/admin/queues').then((r) => r.data),
+    queryFn: () => apiFetch<{ data: QueueStatus[] }>('/api/v1/admin/queues').then((r) => r.data),
     staleTime: 10_000,
     refetchInterval: 10_000,
   });
@@ -47,11 +46,10 @@ export function SystemMonitoringDashboard() {
 
   return (
     <div className="space-y-8">
-      {/* Page header */}
-      <div>
-        <h1 className="text-2xl font-bold text-foreground">System Monitoring</h1>
-        <p className="text-muted-foreground">Real-time health, queue status and connection tracking</p>
-      </div>
+      <PageHeader
+        title="System Monitoring"
+        description="Real-time health, queue status and connection tracking"
+      />
 
       {/* Service health */}
       <section className="space-y-3">
@@ -79,10 +77,7 @@ export function SystemMonitoringDashboard() {
         ) : (
           <div className="flex gap-3">
             {[1, 2, 3, 4].map((i) => (
-              <div
-                key={i}
-                className="h-[88px] w-[160px] rounded-xl border bg-card animate-pulse"
-              />
+              <div key={i} className="h-[88px] w-[160px] rounded-xl border bg-card animate-pulse" />
             ))}
           </div>
         )}
@@ -124,9 +119,7 @@ export function SystemMonitoringDashboard() {
             </CardTitle>
           </CardHeader>
           <CardContent>
-            <p className="text-3xl font-bold">
-              {queues.reduce((sum, q) => sum + q.active, 0)}
-            </p>
+            <p className="text-3xl font-bold">{queues.reduce((sum, q) => sum + q.active, 0)}</p>
           </CardContent>
         </Card>
       </section>
@@ -141,10 +134,7 @@ export function SystemMonitoringDashboard() {
         ) : (
           <div className="grid grid-cols-5 gap-3">
             {[1, 2, 3, 4, 5].map((i) => (
-              <div
-                key={i}
-                className="h-[110px] rounded-xl border bg-card animate-pulse"
-              />
+              <div key={i} className="h-[110px] rounded-xl border bg-card animate-pulse" />
             ))}
           </div>
         )}
@@ -159,8 +149,7 @@ export function SystemMonitoringDashboard() {
 function RecentErrorsPanel() {
   const { data: errorsData } = useQuery({
     queryKey: ['system', 'errors'],
-    queryFn: () =>
-      apiFetch<{ data: RecentError[] }>('/api/v1/admin/errors').then((r) => r.data),
+    queryFn: () => apiFetch<{ data: RecentError[] }>('/api/v1/admin/errors').then((r) => r.data),
     staleTime: 30_000,
     refetchInterval: 30_000,
   });

src/components/admin/users/user-card.tsx

@@ -0,0 +1,149 @@
+'use client';
+
+import { Clock, Mail, MoreHorizontal, Pencil, Shield, Trash2 } from 'lucide-react';
+import { formatDistanceToNow } from 'date-fns';
+
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
+import {
+  ListCard,
+  ListCardAvatar,
+  ListCardMeta,
+  deriveInitials,
+} from '@/components/shared/list-card';
+import { cn } from '@/lib/utils';
+
+interface UserRow {
+  userId: string;
+  displayName: string;
+  email: string;
+  phone: string | null;
+  isActive: boolean;
+  isSuperAdmin: boolean;
+  lastLoginAt: string | null;
+  role: { id: string; name: string };
+  assignedAt: string;
+}
+
+interface UserCardProps {
+  user: UserRow;
+  onEdit: (user: UserRow) => void;
+  onRemove: (userId: string) => void;
+  isRemoving: boolean;
+}
+
+export function UserCard({ user, onEdit, onRemove, isRemoving }: UserCardProps) {
+  const initials = deriveInitials(user.displayName || user.email);
+
+  const accentClass = user.isSuperAdmin
+    ? 'bg-violet-400'
+    : !user.isActive
+      ? 'bg-slate-400'
+      : undefined;
+
+  return (
+    <ListCard
+      href="#"
+      ariaLabel={`User: ${user.displayName}`}
+      accentClassName={accentClass}
+      actions={
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-9 w-9"
+              onClick={(e) => e.stopPropagation()}
+              aria-label={`Actions for ${user.displayName}`}
+            >
+              <MoreHorizontal className="h-4 w-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem
+              onClick={(e) => {
+                e.preventDefault();
+                onEdit(user);
+              }}
+            >
+              <Pencil className="mr-2 h-3.5 w-3.5" />
+              Edit
+            </DropdownMenuItem>
+            <ConfirmationDialog
+              trigger={
+                <DropdownMenuItem className="text-destructive" onSelect={(e) => e.preventDefault()}>
+                  <Trash2 className="mr-2 h-3.5 w-3.5" />
+                  Remove
+                </DropdownMenuItem>
+              }
+              title="Remove User"
+              description={`Remove "${user.displayName}" from this port? They will lose access but their account remains.`}
+              confirmLabel="Remove"
+              onConfirm={() => onRemove(user.userId)}
+              loading={isRemoving}
+            />
+          </DropdownMenuContent>
+        </DropdownMenu>
+      }
+    >
+      <div className="flex items-start gap-3">
+        <ListCardAvatar initials={initials} className={cn(!user.isActive && 'opacity-50')} />
+        <div className="min-w-0 flex-1">
+          {/* Title row + spacer for actions button */}
+          <div className="flex items-start justify-between gap-2">
+            <h3
+              className={cn(
+                'truncate text-base font-semibold tracking-tight',
+                user.isActive ? 'text-foreground' : 'text-muted-foreground',
+              )}
+            >
+              {user.displayName || user.email}
+            </h3>
+            <span aria-hidden className="block h-9 w-9 shrink-0" />
+          </div>
+
+          {/* Email subtitle — only when display name is shown as title */}
+          {user.displayName && user.displayName !== user.email ? (
+            <p className="mt-0.5 inline-flex items-center gap-1 truncate text-sm text-muted-foreground">
+              <Mail className="h-3.5 w-3.5 shrink-0 text-muted-foreground/70" aria-hidden />
+              <span className="truncate">{user.email}</span>
+            </p>
+          ) : null}
+
+          {/* Role + last login meta */}
+          <div className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-0.5 text-xs text-muted-foreground">
+            <ListCardMeta icon={<Shield className="h-3 w-3" />}>{user.role.name}</ListCardMeta>
+
+            {user.lastLoginAt ? (
+              <ListCardMeta icon={<Clock className="h-3 w-3" />}>
+                {formatDistanceToNow(new Date(user.lastLoginAt), { addSuffix: true })}
+              </ListCardMeta>
+            ) : (
+              <ListCardMeta icon={<Clock className="h-3 w-3" />}>Never logged in</ListCardMeta>
+            )}
+          </div>
+
+          {/* Status + super-admin pills */}
+          <div className="mt-1.5 flex flex-wrap items-center gap-x-2 gap-y-1">
+            {!user.isActive ? (
+              <span className="inline-flex items-center rounded-full bg-slate-200 px-2 py-0.5 text-xs font-medium text-slate-700">
+                Inactive
+              </span>
+            ) : null}
+            {user.isSuperAdmin ? (
+              <span className="inline-flex items-center rounded-full bg-violet-100 px-2 py-0.5 text-xs font-medium text-violet-700">
+                Super Admin
+              </span>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </ListCard>
+  );
+}

src/components/admin/users/user-list.tsx

@@ -10,6 +10,7 @@ import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { apiFetch } from '@/lib/api/client';
+import { UserCard } from './user-card';
 import { UserForm } from './user-form';
 
 interface UserRow {
@@ -152,6 +153,14 @@ export function UserList() {
         data={users}
         isLoading={loading}
         getRowId={(row) => row.userId}
+        cardRender={(row) => (
+          <UserCard
+            user={row.original}
+            onEdit={handleEditUser}
+            onRemove={handleRemoveUser}
+            isRemoving={deletingId === row.original.userId}
+          />
+        )}
         emptyState={
           <div className="text-center py-8">
             <p className="text-muted-foreground">No users assigned to this port.</p>

src/components/alerts/alert-rail.tsx

@@ -22,7 +22,11 @@ export function AlertRail() {
     <section
       data-testid="alert-rail"
       aria-label="Active alerts"
-      className="flex h-full flex-col gap-3"
+      // `h-full` is intentional only at xl: where the parent dashboard grid
+      // gives this rail a sibling column whose height it should match. On
+      // mobile (single-column stack) there's no fixed-height context, so
+      // forcing 100% height makes the section overflow / look stretched.
+      className="flex flex-col gap-3 xl:h-full"
     >
       <div className="flex items-baseline justify-between">
         <h2 className="text-sm font-semibold tracking-tight">Alerts</h2>

src/components/berths/berth-card.tsx

@@ -0,0 +1,177 @@
+'use client';
+
+import { Activity, Anchor, MapPin, MoreHorizontal, Pencil } from 'lucide-react';
+import { useRouter, useParams } from 'next/navigation';
+
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { TagBadge } from '@/components/shared/tag-badge';
+import { ListCard, ListCardAvatar, ListCardMeta } from '@/components/shared/list-card';
+import { cn } from '@/lib/utils';
+import type { BerthRow } from './berth-columns';
+
+const STATUS_VARIANTS: Record<string, string> = {
+  available: 'bg-green-100 text-green-800 border-green-200',
+  under_offer: 'bg-yellow-100 text-yellow-800 border-yellow-200',
+  sold: 'bg-red-100 text-red-800 border-red-200',
+};
+
+const STATUS_LABELS: Record<string, string> = {
+  available: 'Available',
+  under_offer: 'Under Offer',
+  sold: 'Sold',
+};
+
+const ACCENT_CLASS: Record<string, string> = {
+  available: 'bg-emerald-400',
+  under_offer: 'bg-amber-400',
+  sold: 'bg-slate-400',
+};
+
+function formatPrice(price: string, currency: string): string {
+  try {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: currency || 'USD',
+      maximumFractionDigits: 0,
+    }).format(Number(price));
+  } catch {
+    return `${currency} ${price}`;
+  }
+}
+
+interface BerthCardProps {
+  berth: BerthRow;
+}
+
+export function BerthCard({ berth }: BerthCardProps) {
+  const router = useRouter();
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+
+  const statusLabel = STATUS_LABELS[berth.status] ?? berth.status;
+  const statusColor =
+    STATUS_VARIANTS[berth.status] ?? 'bg-muted text-muted-foreground border-muted';
+  const accentClass = ACCENT_CLASS[berth.status] ?? 'bg-slate-300';
+
+  // Dimensions string
+  let dimText: string | null = null;
+  if (berth.lengthM || berth.widthM) {
+    const l = berth.lengthM ?? '?';
+    const w = berth.widthM ?? '?';
+    dimText = `${l}m × ${w}m`;
+  }
+
+  const metaParts: string[] = [];
+  if (dimText) metaParts.push(dimText);
+  if (berth.price) metaParts.push(formatPrice(berth.price, berth.priceCurrency));
+
+  const tags = berth.tags ?? [];
+
+  return (
+    <ListCard
+      href={`/${portSlug}/berths/${berth.id}`}
+      ariaLabel={`Berth ${berth.mooringNumber}`}
+      accentClassName={accentClass}
+      actions={
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-9 w-9"
+              onClick={(e) => e.stopPropagation()}
+              aria-label={`Actions for berth ${berth.mooringNumber}`}
+            >
+              <MoreHorizontal className="h-4 w-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem
+              onClick={(e) => {
+                e.stopPropagation();
+                router.push(`/${portSlug}/berths/${berth.id}`);
+              }}
+            >
+              <Activity className="mr-2 h-3.5 w-3.5" />
+              View details
+            </DropdownMenuItem>
+            <DropdownMenuItem
+              onClick={(e) => {
+                e.stopPropagation();
+                router.push(`/${portSlug}/berths/${berth.id}?edit=true`);
+              }}
+            >
+              <Pencil className="mr-2 h-3.5 w-3.5" />
+              Edit
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      }
+    >
+      <div className="flex items-start gap-3">
+        <ListCardAvatar icon={<Anchor className="h-5 w-5" />} />
+        <div className="min-w-0 flex-1">
+          {/* Title row + spacer for actions button */}
+          <div className="flex items-start justify-between gap-2">
+            <h3 className="truncate text-base font-semibold tracking-tight text-foreground">
+              {berth.mooringNumber}
+            </h3>
+            <span aria-hidden className="block h-9 w-9 shrink-0" />
+          </div>
+
+          {/* Area subtitle */}
+          {berth.area ? (
+            <p className="mt-0.5 inline-flex items-center gap-1 truncate text-sm text-muted-foreground">
+              <MapPin className="h-3.5 w-3.5 shrink-0 text-muted-foreground/70" aria-hidden />
+              <span className="truncate">{berth.area}</span>
+            </p>
+          ) : null}
+
+          {/* Dimensions · Price meta line */}
+          {metaParts.length > 0 ? (
+            <div className="mt-0.5 flex flex-wrap items-center gap-x-1.5 text-xs text-muted-foreground">
+              {metaParts.map((part, i) => (
+                <span key={part} className="inline-flex items-center gap-1">
+                  {i > 0 ? <span aria-hidden>·</span> : null}
+                  <ListCardMeta>{part}</ListCardMeta>
+                </span>
+              ))}
+            </div>
+          ) : null}
+
+          {/* Status pill */}
+          <div className="mt-1.5">
+            <span
+              className={cn(
+                'inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-medium',
+                statusColor,
+              )}
+            >
+              {statusLabel}
+            </span>
+          </div>
+
+          {/* Tags */}
+          {tags.length > 0 ? (
+            <div className="mt-2 flex flex-wrap gap-1">
+              {tags.slice(0, 2).map((tag) => (
+                <TagBadge key={tag.id} name={tag.name} color={tag.color} />
+              ))}
+              {tags.length > 2 ? (
+                <span className="inline-flex items-center rounded-full bg-secondary px-2 py-0.5 text-xs text-secondary-foreground">
+                  +{tags.length - 2}
+                </span>
+              ) : null}
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </ListCard>
+  );
+}

src/components/berths/berth-detail-header.tsx

@@ -44,6 +44,17 @@ type BerthDetailData = {
   draftFt: string | null;
   draftM: string | null;
   widthIsMinimum: boolean | null;
+  nominalBoatSize: string | null;
+  nominalBoatSizeM: string | null;
+  waterDepth: string | null;
+  waterDepthM: string | null;
+  waterDepthIsMinimum: boolean | null;
+  sidePontoon: string | null;
+  cleatType: string | null;
+  cleatCapacity: string | null;
+  bollardType: string | null;
+  bollardCapacity: string | null;
+  bowFacing: string | null;
   price: string | null;
   priceCurrency: string;
   tenureType: string;
@@ -167,10 +178,15 @@ export function BerthDetailHeader({ berth }: BerthDetailHeaderProps) {
   return (
     <>
       <DetailHeaderStrip>
-        <div className="flex items-start gap-4">
+        {/* Stacks vertically on phone widths so the action buttons don't
+            squeeze the area subtitle into a two-line wrap. From sm up the
+            title/area block sits side-by-side with the action buttons. */}
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:gap-4">
           <div className="flex-1 min-w-0">
             <div className="flex items-center gap-3 flex-wrap">
-              <h1 className="text-2xl font-bold text-foreground">Berth {berth.mooringNumber}</h1>
+              <h1 className="hidden sm:block text-2xl font-bold text-foreground">
+                Berth {berth.mooringNumber}
+              </h1>
               <span
                 className={`inline-flex items-center rounded-full border px-3 py-1 text-sm font-medium ${STATUS_COLORS[berth.status] ?? 'bg-muted text-muted-foreground border-muted'}`}
               >
@@ -180,7 +196,7 @@ export function BerthDetailHeader({ berth }: BerthDetailHeaderProps) {
             {berth.area && <p className="text-muted-foreground mt-1">{berth.area}</p>}
           </div>
 
-          <div className="flex items-center gap-2 shrink-0">
+          <div className="flex flex-wrap items-center gap-2 sm:shrink-0">
             <PermissionGate resource="berths" action="edit">
               <Button variant="outline" size="sm" onClick={() => setStatusOpen(true)}>
                 <RefreshCw className="mr-1.5 h-4 w-4" />

src/components/berths/berth-detail.tsx

@@ -1,11 +1,15 @@
 'use client';
 
+import { useEffect, useState } from 'react';
+import { useSearchParams, useRouter } from 'next/navigation';
 import { useQuery } from '@tanstack/react-query';
 
 import { DetailLayout } from '@/components/shared/detail-layout';
+import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
 import { apiFetch } from '@/lib/api/client';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { BerthDetailHeader } from './berth-detail-header';
+import { BerthForm } from './berth-form';
 import { buildBerthTabs } from './berth-tabs';
 
 interface BerthDetailProps {
@@ -26,15 +30,45 @@ export function BerthDetail({ berthId }: BerthDetailProps) {
     'berth:statusChanged': [['berth', berthId]],
   });
 
+  const { setChrome } = useMobileChrome();
+  const titleForChrome: string | null = data?.mooringNumber ?? null;
+  useEffect(() => {
+    setChrome({ title: titleForChrome, showBackButton: true });
+    return () => setChrome({ title: null, showBackButton: false });
+  }, [titleForChrome, setChrome]);
+
+  // Auto-open edit sheet when ?edit=true is present in the URL
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const [editOpen, setEditOpen] = useState(false);
+
+  useEffect(() => {
+    if (searchParams.get('edit') === 'true') {
+      setEditOpen(true);
+      // Strip the param without adding a history entry
+      const params = new URLSearchParams(searchParams.toString());
+      params.delete('edit');
+      const newUrl = params.toString() ? `?${params.toString()}` : window.location.pathname;
+      // typedRoutes can't statically validate this dynamic path; cast is safe
+      // because we're always replacing within the same route segment.
+      router.replace(newUrl as never);
+    }
+    // Only run once on mount / when searchParams changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [searchParams]);
+
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const berth = data as any;
 
   return (
+    <>
       <DetailLayout
         isLoading={isLoading}
         header={berth ? <BerthDetailHeader berth={berth} /> : null}
         tabs={berth ? buildBerthTabs(berth) : []}
         defaultTab="overview"
       />
+      {berth ? <BerthForm berth={berth} open={editOpen} onOpenChange={setEditOpen} /> : null}
+    </>
   );
 }

src/components/berths/berth-form.tsx

@@ -16,18 +16,22 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
-import {
-  Sheet,
-  SheetContent,
-  SheetHeader,
-  SheetTitle,
-  SheetFooter,
-} from '@/components/ui/sheet';
+import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter } from '@/components/ui/sheet';
 import { Separator } from '@/components/ui/separator';
 import { Switch } from '@/components/ui/switch';
 import { TagPicker } from '@/components/shared/tag-picker';
 import { apiFetch } from '@/lib/api/client';
 import { updateBerthSchema, type UpdateBerthInput } from '@/lib/validators/berths';
+import {
+  BERTH_AREAS,
+  BERTH_SIDE_PONTOON_OPTIONS,
+  BERTH_MOORING_TYPES,
+  BERTH_CLEAT_TYPES,
+  BERTH_CLEAT_CAPACITIES,
+  BERTH_BOLLARD_TYPES,
+  BERTH_BOLLARD_CAPACITIES,
+  BERTH_ACCESS_OPTIONS,
+} from '@/lib/constants';
 
 interface BerthFormProps {
   berth: {
@@ -42,16 +46,27 @@ interface BerthFormProps {
     draftFt: string | null;
     draftM: string | null;
     widthIsMinimum: boolean | null;
+    nominalBoatSize: string | null;
+    nominalBoatSizeM: string | null;
+    waterDepth: string | null;
+    waterDepthM: string | null;
+    waterDepthIsMinimum: boolean | null;
+    sidePontoon: string | null;
+    powerCapacity: string | null;
+    voltage: string | null;
+    mooringType: string | null;
+    cleatType: string | null;
+    cleatCapacity: string | null;
+    bollardType: string | null;
+    bollardCapacity: string | null;
+    access: string | null;
+    bowFacing: string | null;
     price: string | null;
     priceCurrency: string;
     tenureType: string;
     tenureYears: number | null;
     tenureStartDate: string | null;
     tenureEndDate: string | null;
-    powerCapacity: string | null;
-    voltage: string | null;
-    mooringType: string | null;
-    access: string | null;
     berthApproved: boolean | null;
     tags: Array<{ id: string; name: string; color: string }>;
   };
@@ -59,10 +74,42 @@ interface BerthFormProps {
   onOpenChange: (open: boolean) => void;
 }
 
+/** Optional select that allows clearing back to "no value". */
+function SelectOrEmpty({
+  value,
+  onChange,
+  options,
+  placeholder = 'Select…',
+}: {
+  value: string | undefined;
+  onChange: (next: string | undefined) => void;
+  options: readonly string[];
+  placeholder?: string;
+}) {
+  const NONE = '__none';
+  return (
+    <Select value={value ?? NONE} onValueChange={(v) => onChange(v === NONE ? undefined : v)}>
+      <SelectTrigger>
+        <SelectValue placeholder={placeholder} />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value={NONE}>—</SelectItem>
+        {options.map((opt) => (
+          <SelectItem key={opt} value={opt}>
+            {opt}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
+
 export function BerthForm({ berth, open, onOpenChange }: BerthFormProps) {
   const queryClient = useQueryClient();
   const [tagIds, setTagIds] = useState<string[]>(berth.tags.map((t) => t.id));
 
+  const numOrUndef = (v: string | null) => (v != null && v !== '' ? Number(v) : undefined);
+
   const {
     register,
     handleSubmit,
@@ -73,23 +120,34 @@ export function BerthForm({ berth, open, onOpenChange }: BerthFormProps) {
     resolver: zodResolver(updateBerthSchema),
     defaultValues: {
       area: berth.area ?? undefined,
-      lengthFt: berth.lengthFt ? Number(berth.lengthFt) : undefined,
-      lengthM: berth.lengthM ? Number(berth.lengthM) : undefined,
-      widthFt: berth.widthFt ? Number(berth.widthFt) : undefined,
-      widthM: berth.widthM ? Number(berth.widthM) : undefined,
-      draftFt: berth.draftFt ? Number(berth.draftFt) : undefined,
-      draftM: berth.draftM ? Number(berth.draftM) : undefined,
+      lengthFt: numOrUndef(berth.lengthFt),
+      lengthM: numOrUndef(berth.lengthM),
+      widthFt: numOrUndef(berth.widthFt),
+      widthM: numOrUndef(berth.widthM),
+      draftFt: numOrUndef(berth.draftFt),
+      draftM: numOrUndef(berth.draftM),
       widthIsMinimum: berth.widthIsMinimum ?? false,
-      price: berth.price ? Number(berth.price) : undefined,
+      nominalBoatSize: numOrUndef(berth.nominalBoatSize),
+      nominalBoatSizeM: numOrUndef(berth.nominalBoatSizeM),
+      waterDepth: numOrUndef(berth.waterDepth),
+      waterDepthM: numOrUndef(berth.waterDepthM),
+      waterDepthIsMinimum: berth.waterDepthIsMinimum ?? false,
+      sidePontoon: berth.sidePontoon ?? undefined,
+      powerCapacity: numOrUndef(berth.powerCapacity),
+      voltage: numOrUndef(berth.voltage),
+      mooringType: berth.mooringType ?? undefined,
+      cleatType: berth.cleatType ?? undefined,
+      cleatCapacity: berth.cleatCapacity ?? undefined,
+      bollardType: berth.bollardType ?? undefined,
+      bollardCapacity: berth.bollardCapacity ?? undefined,
+      access: berth.access ?? undefined,
+      bowFacing: berth.bowFacing ?? undefined,
+      price: numOrUndef(berth.price),
       priceCurrency: berth.priceCurrency,
       tenureType: berth.tenureType as 'permanent' | 'fixed_term',
       tenureYears: berth.tenureYears ?? undefined,
       tenureStartDate: berth.tenureStartDate ?? undefined,
       tenureEndDate: berth.tenureEndDate ?? undefined,
-      powerCapacity: berth.powerCapacity ?? undefined,
-      voltage: berth.voltage ?? undefined,
-      mooringType: berth.mooringType ?? undefined,
-      access: berth.access ?? undefined,
       berthApproved: berth.berthApproved ?? false,
     },
   });
@@ -120,6 +178,14 @@ export function BerthForm({ berth, open, onOpenChange }: BerthFormProps) {
   }
 
   const tenureType = watch('tenureType');
+  const area = watch('area');
+  const sidePontoon = watch('sidePontoon');
+  const mooringType = watch('mooringType');
+  const cleatType = watch('cleatType');
+  const cleatCapacity = watch('cleatCapacity');
+  const bollardType = watch('bollardType');
+  const bollardCapacity = watch('bollardCapacity');
+  const access = watch('access');
 
   return (
     <Sheet open={open} onOpenChange={onOpenChange}>
@@ -136,18 +202,18 @@ export function BerthForm({ berth, open, onOpenChange }: BerthFormProps) {
             </h3>
             <div className="grid grid-cols-2 gap-4">
               <div className="space-y-2">
-                <Label htmlFor="area">Area</Label>
-                <Input id="area" {...register('area')} placeholder="e.g. Marina A" />
+                <Label>Area</Label>
+                <SelectOrEmpty
+                  value={area}
+                  onChange={(v) => setValue('area', v)}
+                  options={BERTH_AREAS}
+                />
               </div>
               <div className="space-y-2">
-                <Label htmlFor="mooringType">Mooring Type</Label>
-                <Input id="mooringType" {...register('mooringType')} />
+                <Label htmlFor="bowFacing">Bow Facing</Label>
+                <Input id="bowFacing" {...register('bowFacing')} placeholder="e.g. East" />
               </div>
             </div>
-            <div className="space-y-2">
-              <Label htmlFor="access">Access</Label>
-              <Input id="access" {...register('access')} />
-            </div>
             <div className="flex items-center gap-2">
               <Switch
                 id="berthApproved"
@@ -168,29 +234,46 @@ export function BerthForm({ berth, open, onOpenChange }: BerthFormProps) {
             <div className="grid grid-cols-2 gap-4">
               <div className="space-y-2">
                 <Label>Length (ft)</Label>
-                <Input type="number" step="0.1" {...register('lengthFt')} />
+                <Input type="number" step="0.01" {...register('lengthFt')} />
               </div>
               <div className="space-y-2">
                 <Label>Length (m)</Label>
-                <Input type="number" step="0.1" {...register('lengthM')} />
+                <Input type="number" step="0.01" {...register('lengthM')} />
               </div>
               <div className="space-y-2">
                 <Label>Width (ft)</Label>
-                <Input type="number" step="0.1" {...register('widthFt')} />
+                <Input type="number" step="0.01" {...register('widthFt')} />
               </div>
               <div className="space-y-2">
                 <Label>Width (m)</Label>
-                <Input type="number" step="0.1" {...register('widthM')} />
+                <Input type="number" step="0.01" {...register('widthM')} />
               </div>
               <div className="space-y-2">
                 <Label>Draft (ft)</Label>
-                <Input type="number" step="0.1" {...register('draftFt')} />
+                <Input type="number" step="0.01" {...register('draftFt')} />
               </div>
               <div className="space-y-2">
                 <Label>Draft (m)</Label>
-                <Input type="number" step="0.1" {...register('draftM')} />
+                <Input type="number" step="0.01" {...register('draftM')} />
+              </div>
+              <div className="space-y-2">
+                <Label>Nominal Boat Size (ft)</Label>
+                <Input type="number" step="1" {...register('nominalBoatSize')} />
+              </div>
+              <div className="space-y-2">
+                <Label>Nominal Boat Size (m)</Label>
+                <Input type="number" step="0.01" {...register('nominalBoatSizeM')} />
+              </div>
+              <div className="space-y-2">
+                <Label>Water Depth (ft)</Label>
+                <Input type="number" step="0.01" {...register('waterDepth')} />
+              </div>
+              <div className="space-y-2">
+                <Label>Water Depth (m)</Label>
+                <Input type="number" step="0.01" {...register('waterDepthM')} />
               </div>
             </div>
+            <div className="flex flex-wrap items-center gap-x-6 gap-y-2">
               <div className="flex items-center gap-2">
                 <Switch
                   id="widthIsMinimum"
@@ -199,6 +282,107 @@ export function BerthForm({ berth, open, onOpenChange }: BerthFormProps) {
                 />
                 <Label htmlFor="widthIsMinimum">Width is minimum</Label>
               </div>
+              <div className="flex items-center gap-2">
+                <Switch
+                  id="waterDepthIsMinimum"
+                  checked={watch('waterDepthIsMinimum') ?? false}
+                  onCheckedChange={(v) => setValue('waterDepthIsMinimum', v)}
+                />
+                <Label htmlFor="waterDepthIsMinimum">Water depth is minimum</Label>
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Mooring & Hardware */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wider">
+              Mooring &amp; Hardware
+            </h3>
+            <div className="space-y-2">
+              <Label>Side Pontoon</Label>
+              <SelectOrEmpty
+                value={sidePontoon}
+                onChange={(v) => setValue('sidePontoon', v)}
+                options={BERTH_SIDE_PONTOON_OPTIONS}
+              />
+            </div>
+            <div className="space-y-2">
+              <Label>Mooring Type</Label>
+              <SelectOrEmpty
+                value={mooringType}
+                onChange={(v) => setValue('mooringType', v)}
+                options={BERTH_MOORING_TYPES}
+              />
+            </div>
+            <div className="grid grid-cols-2 gap-4">
+              <div className="space-y-2">
+                <Label>Cleat Type</Label>
+                <SelectOrEmpty
+                  value={cleatType}
+                  onChange={(v) => setValue('cleatType', v)}
+                  options={BERTH_CLEAT_TYPES}
+                />
+              </div>
+              <div className="space-y-2">
+                <Label>Cleat Capacity</Label>
+                <SelectOrEmpty
+                  value={cleatCapacity}
+                  onChange={(v) => setValue('cleatCapacity', v)}
+                  options={BERTH_CLEAT_CAPACITIES}
+                />
+              </div>
+              <div className="space-y-2">
+                <Label>Bollard Type</Label>
+                <SelectOrEmpty
+                  value={bollardType}
+                  onChange={(v) => setValue('bollardType', v)}
+                  options={BERTH_BOLLARD_TYPES}
+                />
+              </div>
+              <div className="space-y-2">
+                <Label>Bollard Capacity</Label>
+                <SelectOrEmpty
+                  value={bollardCapacity}
+                  onChange={(v) => setValue('bollardCapacity', v)}
+                  options={BERTH_BOLLARD_CAPACITIES}
+                />
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Power */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wider">
+              Power
+            </h3>
+            <div className="grid grid-cols-2 gap-4">
+              <div className="space-y-2">
+                <Label>Power Capacity (kW)</Label>
+                <Input type="number" step="1" {...register('powerCapacity')} />
+              </div>
+              <div className="space-y-2">
+                <Label>Voltage (V at 60Hz)</Label>
+                <Input type="number" step="1" {...register('voltage')} />
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Access */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wider">
+              Access
+            </h3>
+            <SelectOrEmpty
+              value={access}
+              onChange={(v) => setValue('access', v)}
+              options={BERTH_ACCESS_OPTIONS}
+            />
           </div>
 
           <Separator />
@@ -262,25 +446,6 @@ export function BerthForm({ berth, open, onOpenChange }: BerthFormProps) {
 
           <Separator />
 
-          {/* Infrastructure */}
-          <div className="space-y-4">
-            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wider">
-              Infrastructure
-            </h3>
-            <div className="grid grid-cols-2 gap-4">
-              <div className="space-y-2">
-                <Label>Power Capacity</Label>
-                <Input {...register('powerCapacity')} />
-              </div>
-              <div className="space-y-2">
-                <Label>Voltage</Label>
-                <Input {...register('voltage')} />
-              </div>
-            </div>
-          </div>
-
-          <Separator />
-
           {/* Tags */}
           <div className="space-y-4">
             <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wider">

src/components/berths/berth-interest-pulse.tsx

@@ -0,0 +1,166 @@
+'use client';
+
+import Link from 'next/link';
+import { useParams } from 'next/navigation';
+import { useQuery } from '@tanstack/react-query';
+import { ChevronRight, Users } from 'lucide-react';
+import { formatDistanceToNowStrict } from 'date-fns';
+
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { apiFetch } from '@/lib/api/client';
+import { stageBadgeClass, stageLabel } from '@/lib/constants';
+import { computeUrgencyBadges } from '@/components/interests/urgency';
+import type { InterestRow } from '@/components/interests/interest-columns';
+import { cn } from '@/lib/utils';
+
+interface InterestsResponse {
+  data: InterestRow[];
+}
+
+const PREVIEW_LIMIT = 5;
+
+/**
+ * Top-of-overview pulse for the berth detail page. Lists the active
+ * interested parties with their stage + last activity, so the rep can do
+ * berth-level triage ("who's on this slip and how warm are they?")
+ * without clicking into the Interests tab.
+ *
+ * Borrows from the old Nuxt CRM's BerthDetailsModal "Interested Parties"
+ * pattern but uses the new at-a-glance signals (urgency badges, last
+ * activity).
+ */
+export function BerthInterestPulse({ berthId }: { berthId: string }) {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+
+  const { data, isLoading } = useQuery<InterestsResponse>({
+    queryKey: ['interests', { berthId, sort: 'dateLastContact', order: 'desc' }],
+    queryFn: () =>
+      apiFetch<InterestsResponse>(
+        `/api/v1/interests?berthId=${berthId}&limit=10&sort=dateLastContact&order=desc`,
+      ),
+    staleTime: 30_000,
+  });
+
+  const all = data?.data ?? [];
+  const active = all.filter((i) => !i.archivedAt && !i.outcome);
+  const preview = active.slice(0, PREVIEW_LIMIT);
+  const more = active.length - preview.length;
+
+  if (isLoading) {
+    return (
+      <Card>
+        <CardHeader className="pb-3">
+          <CardTitle className="text-sm font-medium">Interested parties</CardTitle>
+        </CardHeader>
+        <CardContent className="pt-0">
+          <div className="space-y-2">
+            {[0, 1, 2].map((i) => (
+              <div key={i} className="h-10 animate-pulse rounded-md bg-muted/40" />
+            ))}
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  if (active.length === 0) {
+    return (
+      <Card>
+        <CardHeader className="pb-3">
+          <CardTitle className="flex items-center gap-1.5 text-sm font-medium">
+            <Users className="size-3.5" />
+            Interested parties
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="pt-0">
+          <p className="text-sm text-muted-foreground">No active interests on this berth.</p>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <Card>
+      <CardHeader className="flex flex-row items-center justify-between pb-3 space-y-0">
+        <CardTitle className="flex items-center gap-1.5 text-sm font-medium">
+          <Users className="size-3.5" />
+          Interested parties
+          <span className="ml-1 rounded-full bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
+            {active.length}
+          </span>
+        </CardTitle>
+      </CardHeader>
+      <CardContent className="pt-0">
+        <ul className="divide-y divide-border">
+          {preview.map((i) => {
+            const lastIso = i.dateLastContact ?? i.updatedAt ?? null;
+            const lastActivity = lastIso
+              ? formatDistanceToNowStrict(new Date(lastIso), { addSuffix: true })
+              : null;
+            const urgency = computeUrgencyBadges(i);
+            const initials = (i.clientName ?? '?')
+              .split(/\s+/)
+              .filter(Boolean)
+              .slice(0, 2)
+              .map((p) => p[0]!.toUpperCase())
+              .join('');
+            return (
+              <li key={i.id}>
+                <Link
+                  href={`/${portSlug}/interests/${i.id}`}
+                  className="group flex items-center gap-3 px-1 py-2.5 transition-colors hover:bg-foreground/5 rounded-md -mx-1"
+                >
+                  <span className="flex size-8 shrink-0 items-center justify-center rounded-full bg-brand-100 text-xs font-semibold text-brand-700">
+                    {initials || '?'}
+                  </span>
+                  <div className="min-w-0 flex-1 space-y-0.5">
+                    <div className="flex items-center gap-2 flex-wrap">
+                      <span className="truncate text-sm font-medium text-foreground">
+                        {i.clientName ?? 'Unknown'}
+                      </span>
+                      <span
+                        className={cn(
+                          'inline-flex items-center rounded-full px-2 py-0.5 text-[10px] font-medium',
+                          stageBadgeClass(i.pipelineStage),
+                        )}
+                      >
+                        {stageLabel(i.pipelineStage)}
+                      </span>
+                      {urgency.map((b) => (
+                        <span
+                          key={b.id}
+                          title={b.detail}
+                          className={cn(
+                            'inline-flex items-center rounded-full px-1.5 py-0.5 text-[10px] font-medium',
+                            b.className,
+                          )}
+                        >
+                          {b.label}
+                        </span>
+                      ))}
+                    </div>
+                    {lastActivity ? (
+                      <p className="text-[11px] tabular-nums text-muted-foreground">
+                        Last activity {lastActivity}
+                      </p>
+                    ) : null}
+                  </div>
+                  <ChevronRight className="size-4 shrink-0 text-muted-foreground/60 transition-transform group-hover:translate-x-0.5" />
+                </Link>
+              </li>
+            );
+          })}
+        </ul>
+        {more > 0 ? (
+          <Link
+            href={`/${portSlug}/berths/${berthId}?tab=interests`}
+            className="mt-2 inline-flex text-xs font-medium text-primary hover:underline"
+          >
+            View all {active.length} interests →
+          </Link>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}

src/components/berths/berth-interests-tab.tsx

@@ -19,6 +19,7 @@ import {
 import { TableSkeleton } from '@/components/shared/loading-skeleton';
 import { EmptyState } from '@/components/shared/empty-state';
 import { Bookmark } from 'lucide-react';
+import { PIPELINE_STAGES, stageLabel } from '@/lib/constants';
 import type { InterestRow } from '@/components/interests/interest-columns';
 
 interface BerthInterestsTabProps {
@@ -28,27 +29,10 @@ interface BerthInterestsTabProps {
 type StageFilter = 'all' | 'active' | 'lost';
 type SortMode = 'newest' | 'stage' | 'category';
 
-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
-
-const STAGE_ORDER: Record<string, number> = {
-  open: 0,
-  details_sent: 1,
-  in_communication: 2,
-  visited: 3,
-  signed_eoi_nda: 4,
-  deposit_10pct: 5,
-  contract: 6,
-  completed: 7,
-};
+function stageRank(stage: string): number {
+  const idx = PIPELINE_STAGES.indexOf(stage as (typeof PIPELINE_STAGES)[number]);
+  return idx === -1 ? 99 : idx;
+}
 
 const CATEGORY_RANK: Record<string, number> = {
   hot_lead: 0,
@@ -104,8 +88,8 @@ export function BerthInterestsTab({ berthId }: BerthInterestsTabProps) {
     });
     const sorted = [...filtered].sort((a, b) => {
       if (sortMode === 'stage') {
-        const sa = STAGE_ORDER[a.pipelineStage] ?? 99;
-        const sb = STAGE_ORDER[b.pipelineStage] ?? 99;
+        const sa = stageRank(a.pipelineStage);
+        const sb = stageRank(b.pipelineStage);
         if (sa !== sb) return sb - sa; // furthest along first
       }
       if (sortMode === 'category') {
@@ -189,7 +173,7 @@ export function BerthInterestsTab({ berthId }: BerthInterestsTabProps) {
                 </td>
                 <td className="px-3 py-2">
                   <Badge variant="secondary" className="font-normal">
-                    {STAGE_LABELS[i.pipelineStage] ?? i.pipelineStage}
+                    {stageLabel(i.pipelineStage)}
                   </Badge>
                 </td>
                 <td className="px-3 py-2 text-muted-foreground">

src/components/berths/berth-list.tsx

@@ -9,6 +9,7 @@ import { SavedViewsDropdown } from '@/components/shared/saved-views-dropdown';
 import { EmptyState } from '@/components/shared/empty-state';
 import { usePaginatedQuery } from '@/hooks/use-paginated-query';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { BerthCard } from './berth-card';
 import { berthColumns, type BerthRow } from './berth-columns';
 import { berthFilterDefinitions } from './berth-filters';
 import { Anchor } from 'lucide-react';
@@ -73,6 +74,7 @@ export function BerthList() {
         onSortChange={setSort}
         getRowId={(row) => row.id}
         onRowClick={(row) => router.push(`/${params.portSlug}/berths/${row.id}`)}
+        cardRender={(row) => <BerthCard berth={row.original} />}
         emptyState={
           <EmptyState
             icon={Anchor}

src/components/berths/berth-tabs.tsx

@@ -5,6 +5,7 @@ import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { TagBadge } from '@/components/shared/tag-badge';
 import { BerthReservationsTab } from './berth-reservations-tab';
 import { BerthInterestsTab } from './berth-interests-tab';
+import { BerthInterestPulse } from './berth-interest-pulse';
 
 type BerthData = {
   id: string;
@@ -47,22 +48,57 @@ type BerthData = {
 
 function SpecRow({ label, value }: { label: string; value: React.ReactNode }) {
   if (!value && value !== 0 && value !== false) return null;
+  // Mobile-first: stack vertically with label on top so long values
+  // (e.g. "206.69 ft / 62.99 m") never clip at the right edge.
+  // From `sm` (>=640px) up: switch to the original two-column layout.
   return (
-    <div className="flex justify-between py-2 text-sm">
+    <div className="flex flex-col gap-0.5 py-2 text-sm sm:flex-row sm:items-baseline sm:justify-between sm:gap-3">
       <span className="text-muted-foreground">{label}</span>
-      <span className="font-medium text-right max-w-[60%]">{value}</span>
+      <span className="font-medium sm:max-w-[60%] sm:text-right">{value}</span>
     </div>
   );
 }
 
 function OverviewTab({ berth }: { berth: BerthData }) {
+  // Round to at most 2 decimals; trim trailing zeros so "5.00" -> "5".
+  const fmt = (v: string | null, fractionDigits = 2): string | null => {
+    if (v == null || v === '') return null;
+    const n = Number(v);
+    if (Number.isNaN(n)) return v;
+    return n.toLocaleString('en-US', {
+      minimumFractionDigits: 0,
+      maximumFractionDigits: fractionDigits,
+    });
+  };
+
   const formatDim = (ft: string | null, m: string | null) => {
     const parts = [];
-    if (ft) parts.push(`${ft} ft`);
-    if (m) parts.push(`${m} m`);
+    const ftFmt = fmt(ft);
+    const mFmt = fmt(m);
+    if (ftFmt) parts.push(`${ftFmt} ft`);
+    if (mFmt) parts.push(`${mFmt} m`);
     return parts.length > 0 ? parts.join(' / ') : null;
   };
 
+  const formatNominalBoatSize = (ft: string | null, m: string | null): string | null => {
+    const ftFmt = fmt(ft, 0);
+    const mFmt = fmt(m);
+    const parts: string[] = [];
+    if (ftFmt) parts.push(`${ftFmt} ft`);
+    if (mFmt) parts.push(`${mFmt} m`);
+    return parts.length > 0 ? parts.join(' / ') : null;
+  };
+
+  const formatPower = (kw: string | null) => {
+    const v = fmt(kw, 0);
+    return v ? `${v} kW` : null;
+  };
+
+  const formatVoltage = (v: string | null) => {
+    const fv = fmt(v, 0);
+    return fv ? `${fv} V` : null;
+  };
+
   const price = berth.price
     ? new Intl.NumberFormat('en-US', {
         style: 'currency',
@@ -72,6 +108,11 @@ function OverviewTab({ berth }: { berth: BerthData }) {
     : null;
 
   return (
+    <div className="space-y-6">
+      {/* Sales pulse — top-of-page so reps doing berth-level triage can see
+          who's interested + how warm without clicking into the Interests tab. */}
+      <BerthInterestPulse berthId={berth.id} />
+
       <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
         {/* Specifications */}
         <Card>
@@ -91,7 +132,7 @@ function OverviewTab({ berth }: { berth: BerthData }) {
             <SpecRow label="Draft" value={formatDim(berth.draftFt, berth.draftM)} />
             <SpecRow
               label="Nominal Boat Size"
-            value={berth.nominalBoatSize || berth.nominalBoatSizeM}
+              value={formatNominalBoatSize(berth.nominalBoatSize, berth.nominalBoatSizeM)}
             />
             <SpecRow
               label="Water Depth"
@@ -116,8 +157,8 @@ function OverviewTab({ berth }: { berth: BerthData }) {
               <CardTitle className="text-sm font-medium">Infrastructure</CardTitle>
             </CardHeader>
             <CardContent className="pt-0 divide-y">
-            <SpecRow label="Power Capacity" value={berth.powerCapacity} />
-            <SpecRow label="Voltage" value={berth.voltage} />
+              <SpecRow label="Power Capacity" value={formatPower(berth.powerCapacity)} />
+              <SpecRow label="Voltage" value={formatVoltage(berth.voltage)} />
               <SpecRow label="Cleat Type" value={berth.cleatType} />
               <SpecRow label="Cleat Capacity" value={berth.cleatCapacity} />
               <SpecRow label="Bollard Type" value={berth.bollardType} />
@@ -161,6 +202,7 @@ function OverviewTab({ berth }: { berth: BerthData }) {
           )}
         </div>
       </div>
+    </div>
   );
 }
 

src/components/clients/client-card.tsx

@@ -0,0 +1,142 @@
+'use client';
+
+import { Archive, MoreHorizontal, Pencil } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { TagBadge } from '@/components/shared/tag-badge';
+import {
+  ListCard,
+  ListCardAvatar,
+  ListCardMeta,
+  deriveInitials,
+} from '@/components/shared/list-card';
+import { getCountryName } from '@/lib/i18n/countries';
+import { stageBadgeClass, stageLabel } from '@/lib/constants';
+import type { ClientRow } from './client-columns';
+
+const SOURCE_LABELS: Record<string, string> = {
+  website: 'Website',
+  manual: 'Manual',
+  referral: 'Referral',
+  broker: 'Broker',
+};
+
+interface ClientCardProps {
+  client: ClientRow;
+  portSlug: string;
+  onEdit: (client: ClientRow) => void;
+  onArchive: (client: ClientRow) => void;
+}
+
+export function ClientCard({ client, portSlug, onEdit, onArchive }: ClientCardProps) {
+  const primary = client.contacts?.find((c) => c.isPrimary);
+  const nationality = client.nationalityIso ? getCountryName(client.nationalityIso, 'en') : null;
+  const sourceLabel = client.source ? (SOURCE_LABELS[client.source] ?? client.source) : null;
+  const tags = client.tags ?? [];
+
+  const meta = [nationality, sourceLabel].filter(Boolean) as string[];
+
+  const interest = client.latestInterest ?? null;
+  const interestCount = client.interestCount ?? 0;
+  const interestBerthLabel = interest
+    ? interest.mooringNumber
+      ? `Berth ${interest.mooringNumber}`
+      : 'General interest'
+    : null;
+  const interestStageLabel = interest ? stageLabel(interest.stage) : null;
+  const interestStageBadge = interest ? stageBadgeClass(interest.stage) : null;
+  const extraInterests = interestCount > 1 ? interestCount - 1 : 0;
+
+  return (
+    <ListCard
+      href={`/${portSlug}/clients/${client.id}`}
+      ariaLabel={`Client ${client.fullName}`}
+      actions={
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-9 w-9"
+              onClick={(e) => e.stopPropagation()}
+              aria-label={`Actions for ${client.fullName}`}
+            >
+              <MoreHorizontal className="h-4 w-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem onClick={() => onEdit(client)}>
+              <Pencil className="mr-2 h-3.5 w-3.5" />
+              Edit
+            </DropdownMenuItem>
+            <DropdownMenuItem className="text-destructive" onClick={() => onArchive(client)}>
+              <Archive className="mr-2 h-3.5 w-3.5" />
+              Archive
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      }
+    >
+      <div className="flex items-start gap-3">
+        <ListCardAvatar initials={deriveInitials(client.fullName)} />
+        <div className="min-w-0 flex-1">
+          <div className="flex items-start justify-between gap-2">
+            <h3 className="truncate text-base font-semibold tracking-tight text-foreground">
+              {client.fullName}
+            </h3>
+            <span aria-hidden className="block h-9 w-9 shrink-0" />
+          </div>
+
+          {primary ? (
+            <p className="truncate text-sm text-muted-foreground">{primary.value}</p>
+          ) : null}
+
+          {meta.length > 0 ? (
+            <div className="mt-0.5 flex flex-wrap items-center gap-x-1.5 text-xs text-muted-foreground">
+              {meta.map((m, i) => (
+                <span key={m} className="inline-flex items-center gap-1">
+                  {i > 0 ? <span aria-hidden>·</span> : null}
+                  <ListCardMeta>{m}</ListCardMeta>
+                </span>
+              ))}
+            </div>
+          ) : null}
+
+          {interest ? (
+            <div className="mt-1 flex items-center gap-1.5 text-xs text-muted-foreground">
+              <span className="truncate">{interestBerthLabel}</span>
+              <span aria-hidden>·</span>
+              <span
+                className={`shrink-0 rounded-full px-1.5 py-0.5 text-[10px] font-medium ${interestStageBadge}`}
+              >
+                {interestStageLabel}
+              </span>
+              {extraInterests > 0 ? (
+                <span className="shrink-0 text-muted-foreground/80">+{extraInterests}</span>
+              ) : null}
+            </div>
+          ) : null}
+
+          {tags.length > 0 ? (
+            <div className="mt-2 flex flex-wrap gap-1">
+              {tags.slice(0, 2).map((tag) => (
+                <TagBadge key={tag.id} name={tag.name} color={tag.color} />
+              ))}
+              {tags.length > 2 ? (
+                <span className="inline-flex items-center rounded-full bg-secondary px-2 py-0.5 text-xs text-secondary-foreground">
+                  +{tags.length - 2}
+                </span>
+              ) : null}
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </ListCard>
+  );
+}

src/components/clients/client-columns.tsx

@@ -25,6 +25,8 @@ export interface ClientRow {
   createdAt: string;
   yachtCount?: number;
   companyCount?: number;
+  interestCount?: number;
+  latestInterest?: { stage: string; mooringNumber: string | null } | null;
   contacts?: Array<{ channel: string; value: string; isPrimary: boolean }>;
   tags?: Array<{ id: string; name: string; color: string }>;
 }

src/components/clients/client-detail-header.tsx

@@ -2,7 +2,8 @@
 
 import { useState } from 'react';
 import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { Archive, RotateCcw, Mail, Phone } from 'lucide-react';
+import { Archive, Mail, MessageCircle, Phone, RotateCcw } from 'lucide-react';
+import { format } from 'date-fns';
 
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
@@ -12,31 +13,28 @@ import { DetailHeaderStrip } from '@/components/shared/detail-header-strip';
 import { PortalInviteButton } from '@/components/clients/portal-invite-button';
 import { GdprExportButton } from '@/components/clients/gdpr-export-button';
 import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';
+import { getCountryName } from '@/lib/i18n/countries';
 
 interface ClientDetailHeaderProps {
   client: {
     id: string;
     fullName: string;
-    nationality?: string | null;
-    preferredContactMethod?: string | null;
-    preferredLanguage?: string | null;
-    timezone?: string | null;
-    source?: string | null;
-    sourceDetails?: string | null;
+    nationalityIso?: string | null;
     archivedAt?: string | null;
-    contacts?: Array<{ channel: string; value: string; isPrimary: boolean; label?: string | null }>;
+    createdAt?: string;
+    contacts?: Array<{
+      channel: string;
+      value: string;
+      valueE164?: string | null;
+      isPrimary: boolean;
+      label?: string | null;
+    }>;
     tags?: Array<{ id: string; name: string; color: string }>;
     clientPortalEnabled?: boolean;
   };
 }
 
-const SOURCE_LABELS: Record<string, string> = {
-  website: 'Website',
-  manual: 'Manual',
-  referral: 'Referral',
-  broker: 'Broker',
-};
-
 export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
   const queryClient = useQueryClient();
   const [archiveOpen, setArchiveOpen] = useState(false);
@@ -62,19 +60,36 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
   });
 
   const primaryEmail =
-    client.contacts?.find((c) => c.channel === 'email' && c.isPrimary) ??
-    client.contacts?.find((c) => c.channel === 'email');
-  const primaryPhone =
+    client.contacts?.find((c) => c.channel === 'email' && c.isPrimary)?.value ??
+    client.contacts?.find((c) => c.channel === 'email')?.value;
+  const primaryPhoneContact =
     client.contacts?.find((c) => c.channel === 'phone' && c.isPrimary) ??
     client.contacts?.find((c) => c.channel === 'phone');
+  const primaryPhone = primaryPhoneContact?.value;
+  // wa.me requires the E.164 number without the leading "+". Strip from the
+  // canonical E.164 form when available; otherwise strip non-digits from the
+  // display value as a best-effort fallback.
+  const whatsappNumber = primaryPhoneContact?.valueE164
+    ? primaryPhoneContact.valueE164.replace(/^\+/, '')
+    : primaryPhoneContact?.value
+      ? primaryPhoneContact.value.replace(/[^\d]/g, '')
+      : null;
+
+  const country = client.nationalityIso ? getCountryName(client.nationalityIso, 'en') : null;
+  const addedLabel = client.createdAt
+    ? `Added ${format(new Date(client.createdAt), 'MMM d, yyyy')}`
+    : null;
+  const meta = [country, addedLabel].filter(Boolean) as string[];
 
   return (
     <>
       <DetailHeaderStrip>
-        <div className="flex items-start gap-3 flex-wrap">
-          <div className="flex-1 min-w-0">
+        <div className="flex items-start gap-3">
+          <div className="min-w-0 flex-1 space-y-2">
             <div className="flex items-center gap-2 flex-wrap">
-              <h1 className="text-2xl font-bold text-foreground truncate">{client.fullName}</h1>
+              <h1 className="truncate text-lg font-bold text-foreground sm:text-2xl">
+                {client.fullName}
+              </h1>
               {isArchived && (
                 <Badge variant="secondary" className="text-xs">
                   Archived
@@ -82,31 +97,71 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
               )}
             </div>
 
-            <div className="flex items-center gap-4 mt-2 flex-wrap text-sm text-muted-foreground">
-              {client.source && (
-                <span>
-                  Source:{' '}
-                  <span className="text-foreground">
-                    {SOURCE_LABELS[client.source] ?? client.source}
-                  </span>
-                </span>
-              )}
-              {primaryEmail && (
-                <span className="flex items-center gap-1">
-                  <Mail className="h-3.5 w-3.5" />
-                  {primaryEmail.value}
-                </span>
-              )}
-              {primaryPhone && (
-                <span className="flex items-center gap-1">
-                  <Phone className="h-3.5 w-3.5" />
-                  {primaryPhone.value}
-                </span>
-              )}
+            {meta.length > 0 ? (
+              <p className="text-xs text-muted-foreground sm:text-sm">{meta.join(' · ')}</p>
+            ) : null}
+
+            <div className="flex flex-wrap items-center gap-1.5 pt-1">
+              {primaryEmail ? (
+                <Button
+                  asChild
+                  variant="outline"
+                  size="sm"
+                  className="h-8 gap-1.5 px-2.5 [&_svg]:size-3.5"
+                >
+                  <a href={`mailto:${primaryEmail}`} aria-label={`Email ${primaryEmail}`}>
+                    <Mail />
+                    Email
+                  </a>
+                </Button>
+              ) : null}
+              {primaryPhone ? (
+                <Button
+                  asChild
+                  variant="outline"
+                  size="sm"
+                  className="h-8 gap-1.5 px-2.5 [&_svg]:size-3.5"
+                >
+                  <a href={`tel:${primaryPhone}`} aria-label={`Call ${primaryPhone}`}>
+                    <Phone />
+                    Call
+                  </a>
+                </Button>
+              ) : null}
+              {whatsappNumber ? (
+                <Button
+                  asChild
+                  variant="outline"
+                  size="sm"
+                  className="h-8 gap-1.5 px-2.5 [&_svg]:size-3.5"
+                >
+                  <a
+                    href={`https://wa.me/${whatsappNumber}`}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    aria-label={`Message ${primaryPhone} on WhatsApp`}
+                  >
+                    <MessageCircle />
+                    WhatsApp
+                  </a>
+                </Button>
+              ) : null}
+              {!isArchived && client.clientPortalEnabled !== false ? (
+                <div className="hidden sm:inline-flex">
+                  <PortalInviteButton
+                    clientId={client.id}
+                    clientName={client.fullName}
+                    defaultEmail={primaryEmail}
+                  />
+                </div>
+              ) : null}
+              <div className="hidden sm:inline-flex">
+                <GdprExportButton clientId={client.id} />
+              </div>
             </div>
 
             {client.tags && client.tags.length > 0 && (
-              <div className="flex flex-wrap gap-1 mt-2">
+              <div className="flex flex-wrap gap-1">
                 {client.tags.map((tag) => (
                   <TagBadge key={tag.id} name={tag.name} color={tag.color} />
                 ))}
@@ -114,34 +169,21 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
             )}
           </div>
 
-          {/* Actions */}
-          <div className="flex items-center gap-2">
-            {!isArchived && client.clientPortalEnabled !== false && (
-              <PortalInviteButton
-                clientId={client.id}
-                clientName={client.fullName}
-                defaultEmail={primaryEmail?.value}
-              />
-            )}
-            <GdprExportButton clientId={client.id} />
-            <Button
-              variant={isArchived ? 'outline' : 'outline'}
-              size="sm"
+          {/* Top-right: archive/restore as a small icon button — destructive
+              action sits out of the primary action flow. */}
+          <button
+            type="button"
             onClick={() => setArchiveOpen(true)}
-            >
-              {isArchived ? (
-                <>
-                  <RotateCcw className="mr-1.5 h-3.5 w-3.5" />
-                  Restore
-                </>
-              ) : (
-                <>
-                  <Archive className="mr-1.5 h-3.5 w-3.5" />
-                  Archive
-                </>
+            aria-label={isArchived ? 'Restore client' : 'Archive client'}
+            title={isArchived ? 'Restore client' : 'Archive client'}
+            className={cn(
+              'shrink-0 rounded-md p-1.5 text-muted-foreground/70 transition-colors',
+              'hover:bg-foreground/5 hover:text-foreground',
+              isArchived ? 'hover:text-foreground' : 'hover:text-destructive',
             )}
-            </Button>
-          </div>
+          >
+            {isArchived ? <RotateCcw className="size-4" /> : <Archive className="size-4" />}
+          </button>
         </div>
       </DetailHeaderStrip>
 

src/components/clients/client-detail.tsx

@@ -1,8 +1,10 @@
 'use client';
 
+import { useEffect } from 'react';
 import { useQuery } from '@tanstack/react-query';
 
 import { DetailLayout } from '@/components/shared/detail-layout';
+import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
 import { ClientDetailHeader } from '@/components/clients/client-detail-header';
 import { getClientTabs } from '@/components/clients/client-tabs';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
@@ -27,6 +29,8 @@ interface ClientData {
     id: string;
     channel: string;
     value: string;
+    valueE164: string | null;
+    valueCountry: string | null;
     label: string | null;
     isPrimary: boolean;
     notes: string | null;
@@ -80,6 +84,13 @@ export function ClientDetail({ clientId, currentUserId }: ClientDetailProps) {
       apiFetch<{ data: ClientData }>(`/api/v1/clients/${clientId}`).then((r) => r.data),
   });
 
+  const { setChrome } = useMobileChrome();
+  const titleForChrome: string | null = data?.fullName ?? null;
+  useEffect(() => {
+    setChrome({ title: titleForChrome, showBackButton: true });
+    return () => setChrome({ title: null, showBackButton: false });
+  }, [titleForChrome, setChrome]);
+
   useRealtimeInvalidation({
     'client:updated': [['clients', clientId]],
     'client:archived': [['clients', clientId]],

src/components/clients/client-form.tsx

@@ -23,6 +23,7 @@ import { TagPicker } from '@/components/shared/tag-picker';
 import { CountryCombobox } from '@/components/shared/country-combobox';
 import { TimezoneCombobox } from '@/components/shared/timezone-combobox';
 import { PhoneInput } from '@/components/shared/phone-input';
+import { DedupSuggestionPanel } from '@/components/clients/dedup-suggestion-panel';
 import { apiFetch } from '@/lib/api/client';
 import { createClientSchema, type CreateClientInput } from '@/lib/validators/clients';
 import type { CountryCode } from '@/lib/i18n/countries';
@@ -30,6 +31,12 @@ import type { CountryCode } from '@/lib/i18n/countries';
 interface ClientFormProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
+  /** Optional callback fired when the dedup suggestion panel reports
+   *  the user picked an existing client. The form closes; parent is
+   *  responsible for navigating to the existing client's detail page
+   *  or opening the create-interest dialog pre-filled with that
+   *  clientId. Skipped in edit mode. */
+  onUseExistingClient?: (clientId: string) => void;
   /** If provided, form is in edit mode */
   client?: {
     id: string;
@@ -53,7 +60,7 @@ interface ClientFormProps {
   };
 }
 
-export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
+export function ClientForm({ open, onOpenChange, client, onUseExistingClient }: ClientFormProps) {
   const queryClient = useQueryClient();
   const isEdit = !!client;
 
@@ -143,6 +150,26 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
         </SheetHeader>
 
         <form onSubmit={handleSubmit((data) => mutation.mutate(data))} className="space-y-6 py-6">
+          {/* Dedup suggestion — only on the create path. Watches the
+              live form values for email / phone / name and surfaces
+              an existing client when one matches. The user can
+              attach the new interest to that client instead of
+              creating a duplicate. */}
+          {!isEdit ? (
+            <DedupSuggestionPanel
+              email={watch('contacts')?.find((c) => c?.channel === 'email')?.value ?? null}
+              phone={
+                watch('contacts')?.find((c) => c?.channel === 'phone' || c?.channel === 'whatsapp')
+                  ?.valueE164 ?? null
+              }
+              name={watch('fullName') ?? null}
+              onUseExisting={(match) => {
+                onUseExistingClient?.(match.clientId);
+                onOpenChange(false);
+              }}
+            />
+          ) : null}
+
           {/* Basic Info */}
           <div className="space-y-4">
             <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
@@ -339,10 +366,6 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
                   </SelectContent>
                 </Select>
               </div>
-              <div className="space-y-1">
-                <Label>Preferred Language</Label>
-                <Input {...register('preferredLanguage')} placeholder="English" />
-              </div>
               <div className="space-y-1">
                 <Label>Timezone</Label>
                 <TimezoneCombobox

src/components/clients/client-interests-tab.tsx

@@ -0,0 +1,460 @@
+'use client';
+
+import { useState } from 'react';
+import Link from 'next/link';
+import { useParams } from 'next/navigation';
+import type { Route } from 'next';
+import { useQuery } from '@tanstack/react-query';
+import { format, formatDistanceToNowStrict } from 'date-fns';
+import { ArrowRight, CheckCircle2, ChevronRight, Circle, Plus } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { EmptyState } from '@/components/shared/empty-state';
+import { Skeleton } from '@/components/ui/skeleton';
+import { Drawer, DrawerContent, DrawerHeader, DrawerTitle } from '@/components/shared/drawer';
+import { apiFetch } from '@/lib/api/client';
+import { PIPELINE_STAGES, type PipelineStage } from '@/lib/constants';
+import { cn } from '@/lib/utils';
+
+import { STAGE_BADGE, STAGE_LABELS, safeStage } from '@/components/clients/pipeline-constants';
+import {
+  StageStepper,
+  useClientInterests,
+  type ClientInterestRow,
+} from '@/components/clients/client-pipeline-summary';
+import { InterestForm } from '@/components/interests/interest-form';
+
+const LEAD_CATEGORY_LABELS: Record<string, string> = {
+  general_interest: 'General interest',
+  specific_qualified: 'Specific qualified',
+  hot_lead: 'Hot lead',
+};
+
+function InterestRowItem({
+  interest,
+  onOpen,
+}: {
+  interest: ClientInterestRow;
+  onOpen: (i: ClientInterestRow) => void;
+}) {
+  const stage = safeStage(interest.pipelineStage);
+
+  const berthLabel = interest.berthMooringNumber
+    ? `Berth ${interest.berthMooringNumber}`
+    : 'General interest';
+
+  const yachtLabel = interest.yachtName ?? null;
+
+  return (
+    // Tap opens a bottom-sheet preview drawer rather than navigating to the
+    // full interest page. The drawer covers ~80% of mobile interactions
+    // ("what stage is this at, when did we last touch it"). For deeper
+    // edits the drawer has an "Open full page" CTA.
+    <button
+      type="button"
+      onClick={() => onOpen(interest)}
+      className={cn(
+        'group block w-full rounded-xl border border-border bg-card p-4 text-left shadow-sm transition-all',
+        'hover:border-border/70 hover:shadow-md',
+      )}
+    >
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2 flex-wrap">
+            <h3 className="truncate text-base font-semibold tracking-tight text-foreground">
+              {berthLabel}
+            </h3>
+            <span
+              className={cn(
+                'shrink-0 rounded-full px-2 py-0.5 text-[11px] font-medium',
+                STAGE_BADGE[stage],
+              )}
+            >
+              {STAGE_LABELS[stage]}
+            </span>
+          </div>
+          {yachtLabel ? (
+            <p className="mt-0.5 truncate text-xs text-muted-foreground">{yachtLabel}</p>
+          ) : null}
+        </div>
+        <ChevronRight className="size-4 shrink-0 text-muted-foreground transition-transform group-hover:translate-x-0.5" />
+      </div>
+
+      <div className="mt-3">
+        <StageStepper current={stage} />
+      </div>
+    </button>
+  );
+}
+
+function lastActivityFor(interest: ClientInterestRow): string | null {
+  const candidates = [interest.dateLastContact, interest.updatedAt]
+    .filter((v): v is string => Boolean(v))
+    .map((v) => new Date(v).getTime())
+    .filter((t) => !Number.isNaN(t));
+  if (candidates.length === 0) return null;
+  return `${formatDistanceToNowStrict(new Date(Math.max(...candidates)))} ago`;
+}
+
+/** Full interest record returned by `/api/v1/interests/[id]`. Only the fields
+ *  the drawer actually reads are typed here; the API returns more. */
+interface InterestDetail {
+  id: string;
+  pipelineStage: string;
+  leadCategory: string | null;
+  source: string | null;
+  notes: string | null;
+  dateLastContact: string | null;
+  dateEoiSent: string | null;
+  dateEoiSigned: string | null;
+  dateDepositReceived: string | null;
+  dateContractSent: string | null;
+  dateContractSigned: string | null;
+}
+
+function useInterestDetail(id: string | null) {
+  return useQuery<{ data: InterestDetail }>({
+    queryKey: ['interest-detail-drawer', id],
+    queryFn: () => apiFetch<{ data: InterestDetail }>(`/api/v1/interests/${id}`),
+    enabled: id !== null,
+    // Detail rarely changes during a single drawer-open session; stale-time
+    // keeps re-opens snappy without preventing background refetch.
+    staleTime: 30_000,
+  });
+}
+
+/** Format a date-only or ISO timestamp as e.g. "Apr 8, 2026". Returns null for
+ *  empty input so callers can render an "empty" state. */
+function formatDate(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return null;
+  return format(d, 'MMM d, yyyy');
+}
+
+/** A single milestone row inside the drawer's milestone summary. Filled
+ *  circle when the step is done, hollow when pending. Trailing meta line
+ *  shows the date stamp or a "pending" hint. */
+function MilestoneRow({
+  label,
+  done,
+  date,
+  hint = 'pending',
+}: {
+  label: string;
+  done: boolean;
+  date: string | null;
+  hint?: string;
+}) {
+  return (
+    <li className="flex items-center gap-2 py-1">
+      {done ? (
+        <CheckCircle2 className="size-4 shrink-0 text-emerald-600" aria-hidden />
+      ) : (
+        <Circle className="size-4 shrink-0 text-muted-foreground/40" aria-hidden />
+      )}
+      <span className={cn('flex-1 text-sm', done ? 'text-foreground' : 'text-muted-foreground')}>
+        {label}
+      </span>
+      <span className="text-xs text-muted-foreground tabular-nums">{date ?? hint}</span>
+    </li>
+  );
+}
+
+/**
+ * Bottom-sheet preview of a single interest. Designed for the mobile
+ * "tap an interest → see what's happening without leaving the client
+ * page" flow. Shows the pipeline progress, a compact milestone summary
+ * (EOI / Deposit / Contract), lead context, last contact, and a notes
+ * teaser. Tap-out / drag-down dismisses; the full edit page is one tap
+ * away via "Open full page →".
+ */
+function InterestPreviewDrawer({
+  interest,
+  portSlug,
+  onClose,
+}: {
+  interest: ClientInterestRow | null;
+  portSlug: string;
+  onClose: () => void;
+}) {
+  // Pin the most recently selected interest so the drawer stays populated
+  // during the close-animation tail (Vaul keeps the content mounted ~250ms
+  // after `open=false`). Conditional setState is safe here — the guard
+  // ensures it only fires when the prop actually changes to a new row.
+  const [pinned, setPinned] = useState<ClientInterestRow | null>(interest);
+  if (interest && interest !== pinned) setPinned(interest);
+  const showing = pinned;
+
+  const detail = useInterestDetail(showing?.id ?? null);
+  const fullDetail = detail.data?.data ?? null;
+
+  const open = interest !== null;
+  const stage = showing ? safeStage(showing.pipelineStage) : null;
+  const stageIdx = stage ? PIPELINE_STAGES.indexOf(stage) : -1;
+  const reached = (target: PipelineStage) =>
+    stageIdx !== -1 && PIPELINE_STAGES.indexOf(target) <= stageIdx;
+
+  const berthLabel = showing
+    ? showing.berthMooringNumber
+      ? `Berth ${showing.berthMooringNumber}`
+      : 'General interest'
+    : '';
+  const yachtLabel = showing?.yachtName ?? null;
+  const activity = showing ? lastActivityFor(showing) : null;
+  const fullHref = showing ? (`/${portSlug}/interests/${showing.id}` as Route) : ('/' as Route);
+
+  const leadLabel = fullDetail?.leadCategory
+    ? (LEAD_CATEGORY_LABELS[fullDetail.leadCategory] ?? fullDetail.leadCategory)
+    : null;
+  const sourceLabel = fullDetail?.source
+    ? fullDetail.source.replace(/\b\w/g, (m) => m.toUpperCase())
+    : null;
+  const lastContactDate = formatDate(fullDetail?.dateLastContact);
+  const notesPreview = fullDetail?.notes?.trim() || null;
+
+  return (
+    <Drawer
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) onClose();
+      }}
+    >
+      <DrawerContent className="max-h-[85vh]">
+        <DrawerHeader>
+          <div className="flex items-start justify-between gap-3">
+            <div className="min-w-0 flex-1">
+              <DrawerTitle className="truncate">{berthLabel}</DrawerTitle>
+              {yachtLabel ? (
+                <p className="mt-0.5 truncate text-sm text-muted-foreground">{yachtLabel}</p>
+              ) : null}
+            </div>
+            {stage ? (
+              <span
+                className={cn(
+                  'shrink-0 rounded-full px-2.5 py-1 text-xs font-medium',
+                  STAGE_BADGE[stage],
+                )}
+              >
+                {STAGE_LABELS[stage]}
+              </span>
+            ) : null}
+          </div>
+        </DrawerHeader>
+
+        <div className="space-y-5 overflow-y-auto px-4 pb-4">
+          {/* Pipeline-stepper segmented bar — the same primitive used on the
+              row card, so the at-a-glance progress hint is consistent
+              across surfaces. */}
+          {stage ? (
+            <div>
+              <p className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                Pipeline progress
+              </p>
+              <StageStepper current={stage} />
+            </div>
+          ) : null}
+
+          {/* Milestones — three sections matching the full interest detail
+              page (EOI / Deposit / Contract). Done-state is derived from
+              the pipeline stage so seed data without per-step dates still
+              renders correctly. The full milestone columns + per-step
+              actions live behind "Open full page". */}
+          <section>
+            <p className="mb-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+              Milestones
+            </p>
+            <div className="space-y-3">
+              <div className="rounded-lg border border-border bg-card/50 p-3">
+                <p className="mb-1 text-sm font-semibold">EOI</p>
+                <ul>
+                  <MilestoneRow
+                    label="EOI sent"
+                    done={reached('eoi_sent') || !!fullDetail?.dateEoiSent}
+                    date={formatDate(fullDetail?.dateEoiSent)}
+                  />
+                  <MilestoneRow
+                    label="EOI signed"
+                    done={reached('eoi_signed') || !!fullDetail?.dateEoiSigned}
+                    date={formatDate(fullDetail?.dateEoiSigned)}
+                  />
+                </ul>
+              </div>
+              <div className="rounded-lg border border-border bg-card/50 p-3">
+                <p className="mb-1 text-sm font-semibold">Deposit</p>
+                <ul>
+                  <MilestoneRow
+                    label="Deposit received"
+                    done={reached('deposit_10pct') || !!fullDetail?.dateDepositReceived}
+                    date={formatDate(fullDetail?.dateDepositReceived)}
+                  />
+                </ul>
+              </div>
+              <div className="rounded-lg border border-border bg-card/50 p-3">
+                <p className="mb-1 text-sm font-semibold">Contract</p>
+                <ul>
+                  <MilestoneRow
+                    label="Contract sent"
+                    done={reached('contract_sent') || !!fullDetail?.dateContractSent}
+                    date={formatDate(fullDetail?.dateContractSent)}
+                  />
+                  <MilestoneRow
+                    label="Contract signed"
+                    done={reached('contract_signed') || !!fullDetail?.dateContractSigned}
+                    date={formatDate(fullDetail?.dateContractSigned)}
+                  />
+                </ul>
+              </div>
+            </div>
+          </section>
+
+          {/* Compact key/value pairs — lead category, source, last contact,
+              activity. Each row collapses cleanly when its value is
+              missing so the drawer scales from sparse seed data to full
+              records without empty placeholders. */}
+          <dl className="grid grid-cols-[max-content_1fr] gap-x-4 gap-y-1.5 text-sm">
+            {leadLabel ? (
+              <>
+                <dt className="text-muted-foreground">Lead</dt>
+                <dd className="text-right font-medium">{leadLabel}</dd>
+              </>
+            ) : null}
+            {sourceLabel ? (
+              <>
+                <dt className="text-muted-foreground">Source</dt>
+                <dd className="text-right font-medium">{sourceLabel}</dd>
+              </>
+            ) : null}
+            {lastContactDate ? (
+              <>
+                <dt className="text-muted-foreground">Last contact</dt>
+                <dd className="text-right font-medium">{lastContactDate}</dd>
+              </>
+            ) : null}
+            {activity ? (
+              <>
+                <dt className="text-muted-foreground">Last activity</dt>
+                <dd className="text-right font-medium">{activity}</dd>
+              </>
+            ) : null}
+          </dl>
+
+          {notesPreview ? (
+            <section>
+              <p className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                Notes
+              </p>
+              <p className="line-clamp-3 text-sm text-foreground/90 whitespace-pre-wrap">
+                {notesPreview}
+              </p>
+            </section>
+          ) : null}
+
+          <Button asChild className="w-full" size="lg">
+            <Link href={fullHref}>
+              Open full page
+              <ArrowRight className="ml-1.5 size-4" aria-hidden />
+            </Link>
+          </Button>
+        </div>
+      </DrawerContent>
+    </Drawer>
+  );
+}
+
+function InterestSkeleton() {
+  return (
+    <div className="rounded-xl border border-border bg-card p-4 shadow-sm">
+      <Skeleton className="h-4 w-32" />
+      <Skeleton className="mt-2 h-3 w-24" />
+      <Skeleton className="mt-3 h-2 w-48" />
+    </div>
+  );
+}
+
+interface ClientInterestsTabProps {
+  clientId: string;
+}
+
+export function ClientInterestsTab({ clientId }: ClientInterestsTabProps) {
+  const routeParams = useParams<{ portSlug: string }>();
+  const portSlug = routeParams?.portSlug ?? '';
+  const [createOpen, setCreateOpen] = useState(false);
+  const [previewInterest, setPreviewInterest] = useState<ClientInterestRow | null>(null);
+
+  const { data, isLoading, isError } = useClientInterests(clientId);
+
+  if (isLoading) {
+    return (
+      <div className="space-y-3">
+        <InterestSkeleton />
+        <InterestSkeleton />
+      </div>
+    );
+  }
+
+  if (isError) {
+    return <p className="text-sm text-destructive">Could not load interests for this client.</p>;
+  }
+
+  const interests = data?.data ?? [];
+
+  if (interests.length === 0) {
+    return (
+      <>
+        <EmptyState
+          title="No interests yet"
+          description="When this client expresses interest in a berth, the sales process will appear here."
+          action={{
+            label: 'Add interest',
+            onClick: () => setCreateOpen(true),
+          }}
+        />
+        <InterestForm open={createOpen} onOpenChange={setCreateOpen} defaultClientId={clientId} />
+      </>
+    );
+  }
+
+  const active = interests.filter((i) => !i.archivedAt);
+  const archived = interests.filter((i) => i.archivedAt);
+
+  return (
+    <div className="space-y-6">
+      <div className="flex justify-end">
+        <Button size="sm" onClick={() => setCreateOpen(true)}>
+          <Plus className="mr-1.5 size-3.5" />
+          Add interest
+        </Button>
+      </div>
+
+      {active.length > 0 ? (
+        <div className="space-y-3">
+          {active.map((i) => (
+            <InterestRowItem key={i.id} interest={i} onOpen={setPreviewInterest} />
+          ))}
+        </div>
+      ) : null}
+
+      {archived.length > 0 ? (
+        <div className="space-y-3">
+          <h4 className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Archived
+          </h4>
+          <div className="space-y-3 opacity-60">
+            {archived.map((i) => (
+              <InterestRowItem key={i.id} interest={i} onOpen={setPreviewInterest} />
+            ))}
+          </div>
+        </div>
+      ) : null}
+
+      <InterestPreviewDrawer
+        interest={previewInterest}
+        portSlug={portSlug}
+        onClose={() => setPreviewInterest(null)}
+      />
+
+      <InterestForm open={createOpen} onOpenChange={setCreateOpen} defaultClientId={clientId} />
+    </div>
+  );
+}

src/components/clients/client-list.tsx

@@ -16,6 +16,7 @@ import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog
 import { PermissionGate } from '@/components/shared/permission-gate';
 import { ClientForm } from '@/components/clients/client-form';
 import { clientFilterDefinitions } from '@/components/clients/client-filters';
+import { ClientCard } from '@/components/clients/client-card';
 import { getClientColumns, type ClientRow } from '@/components/clients/client-columns';
 import { usePaginatedQuery } from '@/hooks/use-paginated-query';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
@@ -118,6 +119,14 @@ export function ClientList() {
           onSortChange={setSort}
           isLoading={isFetching && !isLoading}
           getRowId={(row) => row.id}
+          cardRender={(row) => (
+            <ClientCard
+              client={row.original}
+              portSlug={portSlug}
+              onEdit={setEditClient}
+              onArchive={setArchiveClient}
+            />
+          )}
           emptyState={
             <EmptyState
               title="No clients found"

src/components/clients/client-pipeline-summary.tsx

@@ -0,0 +1,311 @@
+'use client';
+
+import Link from 'next/link';
+import { useParams, usePathname } from 'next/navigation';
+import type { Route } from 'next';
+import { useQuery } from '@tanstack/react-query';
+import { ArrowRight, ChevronRight } from 'lucide-react';
+import { formatDistanceToNowStrict } from 'date-fns';
+
+import { apiFetch } from '@/lib/api/client';
+import { Skeleton } from '@/components/ui/skeleton';
+import { cn } from '@/lib/utils';
+import {
+  PIPELINE_STAGES,
+  STAGE_BADGE,
+  STAGE_DOT,
+  STAGE_LABELS,
+  safeStage,
+  type PipelineStage,
+} from '@/components/clients/pipeline-constants';
+
+export interface ClientInterestRow {
+  id: string;
+  pipelineStage: string;
+  archivedAt: string | null;
+  updatedAt: string;
+  dateLastContact: string | null;
+  berthMooringNumber?: string | null;
+  yachtName?: string | null;
+}
+
+interface InterestsResponse {
+  data: ClientInterestRow[];
+}
+
+export function useClientInterests(clientId: string) {
+  return useQuery<InterestsResponse>({
+    queryKey: ['interests', { clientId }],
+    queryFn: () => apiFetch<InterestsResponse>(`/api/v1/interests?clientId=${clientId}&limit=50`),
+  });
+}
+
+export function StageStepper({
+  current,
+  size = 'sm',
+}: {
+  current: PipelineStage;
+  size?: 'xs' | 'sm';
+}) {
+  const idx = PIPELINE_STAGES.indexOf(current);
+  // Segmented progress bar: each stage is a slice of equal width that
+  // lights up once the interest has reached it. Reads at-a-glance, scales
+  // to any container width, and works with 9 stages without becoming
+  // micro-dots that vanish under cramped layouts.
+  const height = size === 'xs' ? 'h-1' : 'h-1.5';
+  return (
+    <div
+      className={cn('flex w-full overflow-hidden rounded-full bg-muted', height)}
+      role="progressbar"
+      aria-label="Pipeline progress"
+      aria-valuenow={idx + 1}
+      aria-valuemin={1}
+      aria-valuemax={PIPELINE_STAGES.length}
+    >
+      {PIPELINE_STAGES.map((stage, i) => {
+        const isReached = i <= idx;
+        const isCurrent = i === idx;
+        return (
+          <div
+            key={stage}
+            title={`${STAGE_LABELS[stage]}${isCurrent ? ' (current)' : ''}`}
+            className={cn(
+              'flex-1 transition-colors',
+              isReached ? STAGE_DOT[stage] : 'bg-transparent',
+              i > 0 ? 'border-l border-card' : '',
+            )}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+function pickHighest(interests: ClientInterestRow[]): ClientInterestRow | null {
+  const active = interests.filter((i) => !i.archivedAt);
+  if (active.length === 0) return null;
+  return [...active].sort((a, b) => {
+    const ai = PIPELINE_STAGES.indexOf(safeStage(a.pipelineStage));
+    const bi = PIPELINE_STAGES.indexOf(safeStage(b.pipelineStage));
+    if (ai !== bi) return bi - ai;
+    return new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
+  })[0]!;
+}
+
+function lastActivityLabel(interests: ClientInterestRow[]): string | null {
+  const candidates = interests
+    .flatMap((i) => [i.dateLastContact, i.updatedAt])
+    .filter((v): v is string => Boolean(v))
+    .map((v) => new Date(v).getTime())
+    .filter((t) => !Number.isNaN(t));
+  if (candidates.length === 0) return null;
+  const latest = new Date(Math.max(...candidates));
+  return `${formatDistanceToNowStrict(latest)} ago`;
+}
+
+interface PipelineSummaryProps {
+  clientId: string;
+  /**
+   * `hero` — single-line pulse for the detail header (highest active stage only).
+   * `panel` — compact list of every active interest, for the Overview tab.
+   */
+  variant?: 'hero' | 'panel';
+}
+
+function HeroVariant({ clientId, portSlug }: { clientId: string; portSlug: string }) {
+  const pathname = usePathname();
+  const { data, isLoading } = useClientInterests(clientId);
+  const interests = data?.data ?? [];
+  const top = pickHighest(interests);
+  const activeCount = interests.filter((i) => !i.archivedAt).length;
+  const activity = lastActivityLabel(interests);
+  const interestsTabHref = `${pathname}?tab=interests` as Route;
+
+  if (isLoading) {
+    return (
+      <div className="space-y-2">
+        <Skeleton className="h-4 w-40" />
+        <Skeleton className="h-2 w-48" />
+      </div>
+    );
+  }
+
+  if (!top) {
+    return (
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div>
+          <p className="text-sm font-medium text-foreground">No active interests</p>
+          <p className="text-xs text-muted-foreground">
+            Start one to begin tracking the sales process.
+          </p>
+        </div>
+        <Link
+          href={`/${portSlug}/interests/new` as Route}
+          className="inline-flex items-center gap-1 text-xs font-medium text-primary hover:underline"
+        >
+          Start interest <ArrowRight className="size-3" />
+        </Link>
+      </div>
+    );
+  }
+
+  const stage = safeStage(top.pipelineStage);
+  const berthLabel = top.berthMooringNumber
+    ? `Berth ${top.berthMooringNumber}`
+    : 'General interest';
+  const detailsHref = `/${portSlug}/interests/${top.id}` as Route;
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center gap-2 flex-wrap">
+        <span className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
+          Sales pipeline
+        </span>
+        {activeCount > 1 ? (
+          <span className="text-[10px] font-medium text-muted-foreground">
+            · {activeCount} active
+          </span>
+        ) : null}
+      </div>
+
+      <Link
+        href={detailsHref}
+        className="group -m-1 block rounded-lg p-1 transition-colors hover:bg-foreground/5"
+      >
+        <div className="flex items-center gap-2 flex-wrap">
+          <span className="truncate text-sm font-semibold text-foreground">{berthLabel}</span>
+          <span
+            className={cn(
+              'shrink-0 rounded-full px-2 py-0.5 text-[11px] font-medium',
+              STAGE_BADGE[stage],
+            )}
+          >
+            {STAGE_LABELS[stage]}
+          </span>
+          <ChevronRight className="size-3.5 shrink-0 text-muted-foreground transition-transform group-hover:translate-x-0.5" />
+        </div>
+        <div className="mt-1.5">
+          <StageStepper current={stage} size="xs" />
+        </div>
+      </Link>
+
+      <div className="flex items-center justify-between gap-2 text-xs text-muted-foreground">
+        <span>{activity ? `Last activity ${activity}` : 'No activity recorded'}</span>
+        {activeCount > 1 ? (
+          <Link
+            href={interestsTabHref}
+            className="font-medium text-primary hover:underline"
+            scroll={false}
+          >
+            View all {activeCount}
+          </Link>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function PanelVariant({ clientId, portSlug }: { clientId: string; portSlug: string }) {
+  const pathname = usePathname();
+  const { data, isLoading } = useClientInterests(clientId);
+  const interests = (data?.data ?? []).filter((i) => !i.archivedAt);
+  const interestsTabHref = `${pathname}?tab=interests` as Route;
+
+  if (isLoading) {
+    return (
+      <div className="space-y-2">
+        <Skeleton className="h-4 w-40" />
+        <Skeleton className="h-2 w-48" />
+      </div>
+    );
+  }
+
+  if (interests.length === 0) {
+    return (
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div>
+          <p className="text-sm font-medium text-foreground">No active interests</p>
+          <p className="text-xs text-muted-foreground">
+            Start one to begin tracking the sales process.
+          </p>
+        </div>
+        <Link
+          href={`/${portSlug}/interests/new` as Route}
+          className="inline-flex items-center gap-1 text-xs font-medium text-primary hover:underline"
+        >
+          Start interest <ArrowRight className="size-3" />
+        </Link>
+      </div>
+    );
+  }
+
+  const sorted = [...interests].sort(
+    (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(),
+  );
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center justify-between gap-2">
+        <span className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
+          Sales pipeline · {interests.length} active
+        </span>
+        <Link
+          href={interestsTabHref}
+          className="text-xs font-medium text-primary hover:underline"
+          scroll={false}
+        >
+          Manage
+        </Link>
+      </div>
+
+      <ul className="space-y-2">
+        {sorted.map((i) => {
+          const stage = safeStage(i.pipelineStage);
+          const berthLabel = i.berthMooringNumber
+            ? `Berth ${i.berthMooringNumber}`
+            : 'General interest';
+          const href = `/${portSlug}/interests/${i.id}` as Route;
+          return (
+            <li key={i.id}>
+              <Link
+                href={href}
+                className="group flex items-center gap-3 rounded-lg p-2 -m-2 transition-colors hover:bg-foreground/5"
+              >
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-center gap-2 flex-wrap">
+                    <span className="truncate text-sm font-medium text-foreground">
+                      {berthLabel}
+                    </span>
+                    <span
+                      className={cn(
+                        'shrink-0 rounded-full px-2 py-0.5 text-[10px] font-medium',
+                        STAGE_BADGE[stage],
+                      )}
+                    >
+                      {STAGE_LABELS[stage]}
+                    </span>
+                  </div>
+                  <div className="mt-1">
+                    <StageStepper current={stage} size="xs" />
+                  </div>
+                </div>
+                <ChevronRight className="size-3.5 shrink-0 text-muted-foreground transition-transform group-hover:translate-x-0.5" />
+              </Link>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+
+export function ClientPipelineSummary({ clientId, variant = 'panel' }: PipelineSummaryProps) {
+  const routeParams = useParams<{ portSlug: string }>();
+  const portSlug = routeParams?.portSlug ?? '';
+
+  return variant === 'hero' ? (
+    <HeroVariant clientId={clientId} portSlug={portSlug} />
+  ) : (
+    <PanelVariant clientId={clientId} portSlug={portSlug} />
+  );
+}

src/components/clients/client-tabs.tsx

@@ -9,6 +9,8 @@ import { InlineTimezoneField } from '@/components/shared/inline-timezone-field';
 import { InlineTagEditor } from '@/components/shared/inline-tag-editor';
 import { NotesList } from '@/components/shared/notes-list';
 import type { CountryCode } from '@/lib/i18n/countries';
+import { ClientInterestsTab } from '@/components/clients/client-interests-tab';
+import { ClientPipelineSummary } from '@/components/clients/client-pipeline-summary';
 import { ClientYachtsTab } from '@/components/clients/client-yachts-tab';
 import { ClientCompaniesTab } from '@/components/clients/client-companies-tab';
 import { ClientReservationsTab } from '@/components/clients/client-reservations-tab';
@@ -114,6 +116,8 @@ interface ClientTabsOptions {
       tenureType: string;
       status: string;
     }>;
+    interestCount?: number;
+    noteCount?: number;
     tags?: Array<{ id: string; name: string; color: string }>;
   };
 }
@@ -131,6 +135,11 @@ function OverviewTab({
   };
 
   return (
+    <div className="space-y-6">
+      <div className="rounded-xl border border-border bg-card p-4 shadow-sm">
+        <ClientPipelineSummary clientId={clientId} variant="panel" />
+      </div>
+
       <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
         {/* Personal Info */}
         <div className="space-y-1">
@@ -148,12 +157,6 @@ function OverviewTab({
                 data-testid="client-nationality-inline"
               />
             </EditableRow>
-          <EditableRow label="Preferred Language">
-            <InlineEditableField
-              value={client.preferredLanguage}
-              onSave={save('preferredLanguage')}
-            />
-          </EditableRow>
             <EditableRow label="Timezone">
               <InlineTimezoneField
                 value={client.timezone}
@@ -209,6 +212,7 @@ function OverviewTab({
           />
         </div>
       </div>
+    </div>
   );
 }
 
@@ -219,6 +223,12 @@ export function getClientTabs({ clientId, currentUserId, client }: ClientTabsOpt
       label: 'Overview',
       content: <OverviewTab clientId={clientId} client={client} />,
     },
+    {
+      id: 'interests',
+      label: 'Interests',
+      badge: client.interestCount,
+      content: <ClientInterestsTab clientId={clientId} />,
+    },
     {
       id: 'yachts',
       label: 'Yachts',
@@ -251,18 +261,10 @@ export function getClientTabs({ clientId, currentUserId, client }: ClientTabsOpt
         />
       ),
     },
-    {
-      id: 'interests',
-      label: 'Interests',
-      content: (
-        <div className="text-center py-12 text-muted-foreground">
-          <p>Interests will appear here once created.</p>
-        </div>
-      ),
-    },
     {
       id: 'notes',
       label: 'Notes',
+      badge: client.noteCount,
       content: <NotesList entityType="clients" entityId={clientId} currentUserId={currentUserId} />,
     },
     {

src/components/clients/contacts-editor.tsx

@@ -155,6 +155,7 @@ function ContactRow({
   onRemove: () => void;
 }) {
   const Icon = CHANNEL_ICONS[contact.channel] ?? MoreHorizontal;
+  const [phoneEditing, setPhoneEditing] = useState(false);
 
   async function togglePrimary() {
     try {
@@ -174,17 +175,31 @@ function ContactRow({
   }
 
   return (
-    <div className="group flex items-center gap-2 p-2 rounded-lg border bg-muted/30 text-sm">
-      {/* Left: channel + value */}
-      <div className="flex items-center gap-2 flex-1 min-w-0">
+    <div
+      data-editing={phoneEditing ? 'true' : undefined}
+      className={cn(
+        'group rounded-lg border text-sm transition-all duration-150',
+        // Active-edit dilation: lift the row out of the muted baseline with a
+        // soft primary ring + slightly brighter surface. Single visual signal
+        // replaces the need for any "now editing" label.
+        phoneEditing
+          ? 'bg-card border-primary/30 ring-2 ring-primary/15 shadow-sm p-3 gap-3'
+          : 'bg-muted/30 p-2 gap-2',
+        // Stack value editor / action cluster on mobile; single row on sm+.
+        'flex flex-col sm:flex-row sm:items-center',
+      )}
+    >
+      {/* Top / left: channel + value */}
+      <div className="flex min-w-0 flex-1 items-center gap-2">
         <ChannelPicker value={contact.channel} onChange={changeChannel}>
           <Icon className="h-3.5 w-3.5 text-muted-foreground" />
         </ChannelPicker>
-        <div className="min-w-0">
+        <div className="min-w-0 flex-1">
           {contact.channel === 'phone' || contact.channel === 'whatsapp' ? (
             <InlinePhoneField
               e164={contact.valueE164 ?? null}
               country={contact.valueCountry ?? null}
+              onEditingChange={setPhoneEditing}
               onSave={async ({ e164, country }) => {
                 if (!e164) {
                   toast.error('Phone number is required');
@@ -208,12 +223,27 @@ function ContactRow({
         </div>
       </div>
 
-      {/* Right: tag + actions */}
-      <div className="flex items-center gap-2 shrink-0">
-        <div className="w-28 text-xs text-muted-foreground text-right">
+      {/* Bottom / right: tag + actions.
+          Two layers of hiding compose here:
+            (a) phoneEditing — when the phone editor is open, hide the entire
+                action cluster (tag + star + trash) so the user can focus on
+                the form without chips fighting for space.
+            (b) contact.value — when the value is empty (stale import row,
+                aborted edit), hide just the tag + Make-primary star;
+                neither makes sense without a value. The trash icon stays
+                so the user can clean up the empty entry.
+          On touch (no hover), trash is always rendered; on desktop it
+          fades in on hover only (sm:opacity-0 + sm:group-hover:opacity-100). */}
+      {!phoneEditing ? (
+        <div className="flex shrink-0 items-center justify-end gap-2">
+          {contact.value ? (
+            <>
+              <div className="w-28 text-right text-xs text-muted-foreground">
                 <InlineEditableField
                   value={
-              contact.label && contact.label.toLowerCase() !== 'primary' ? contact.label : null
+                    contact.label && contact.label.toLowerCase() !== 'primary'
+                      ? contact.label
+                      : null
                   }
                   emptyText="Add tag"
                   placeholder="work, home…"
@@ -228,22 +258,25 @@ function ContactRow({
                 onClick={togglePrimary}
                 title={contact.isPrimary ? 'Primary' : 'Make primary'}
                 className={cn(
-            'p-1 rounded hover:bg-background/60 transition-colors',
+                  'rounded p-1 transition-colors hover:bg-background/60',
                   contact.isPrimary ? 'text-primary' : 'text-muted-foreground/50',
                 )}
               >
                 <Star className={cn('h-3.5 w-3.5', contact.isPrimary && 'fill-current')} />
               </button>
+            </>
+          ) : null}
 
           <button
             type="button"
             onClick={onRemove}
             title="Remove"
-          className="p-1 rounded text-muted-foreground/50 hover:text-destructive hover:bg-background/60 opacity-0 group-hover:opacity-100 transition-all"
+            className="rounded p-1 text-muted-foreground/50 transition-all hover:bg-background/60 hover:text-destructive sm:opacity-0 sm:group-hover:opacity-100"
           >
             <Trash2 className="h-3.5 w-3.5" />
           </button>
         </div>
+      ) : null}
     </div>
   );
 }
@@ -330,7 +363,9 @@ function NewContactForm({
   const submitDisabled = saving || (isPhoneChannel ? !phoneValue?.e164 : !value.trim());
 
   return (
-    <div className="flex items-center gap-2 p-2 rounded-lg border bg-muted/30 text-sm">
+    // Single row on sm+; wraps onto multiple lines below 640px so the channel
+    // picker, value field, label, and buttons each get their own usable width.
+    <div className="flex flex-wrap items-center gap-2 rounded-lg border bg-muted/30 p-2 text-sm">
       <Select
         value={channel}
         onValueChange={(next) => {
@@ -353,7 +388,7 @@ function NewContactForm({
       </Select>
 
       {isPhoneChannel ? (
-        <div className="flex-1 min-w-0">
+        <div className="min-w-0 flex-1 basis-full sm:basis-auto">
           <PhoneInput
             value={phoneValue}
             onChange={(v) => setPhoneValue(v)}
@@ -365,7 +400,7 @@ function NewContactForm({
           value={value}
           onChange={(e) => setValue(e.target.value)}
           placeholder={channel === 'email' ? 'name@example.com' : 'value'}
-          className="h-7 text-sm flex-1 min-w-0"
+          className="h-7 min-w-0 flex-1 basis-full text-sm sm:basis-auto"
           autoFocus
           disabled={saving}
           onKeyDown={(e) => {
@@ -382,7 +417,7 @@ function NewContactForm({
         value={label}
         onChange={(e) => setLabel(e.target.value)}
         placeholder="tag (optional)"
-        className="h-7 text-xs w-28"
+        className="h-7 w-28 text-xs"
         disabled={saving}
         onKeyDown={(e) => {
           if (e.key === 'Enter') {
@@ -393,6 +428,7 @@ function NewContactForm({
         }}
       />
 
+      <div className="ml-auto flex gap-2">
         <Button type="button" size="sm" onClick={submit} disabled={submitDisabled}>
           {saving ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : 'Save'}
         </Button>
@@ -400,5 +436,6 @@ function NewContactForm({
           Cancel
         </Button>
       </div>
+    </div>
   );
 }

src/components/clients/dedup-suggestion-panel.tsx

@@ -0,0 +1,183 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { AlertCircle, ArrowRight, Briefcase, X } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';
+
+interface MatchData {
+  clientId: string;
+  fullName: string;
+  score: number;
+  confidence: 'high' | 'medium' | 'low';
+  reasons: string[];
+  interestCount: number;
+  emails: string[];
+  phonesE164: string[];
+}
+
+interface DedupSuggestionPanelProps {
+  /** Free-text inputs from the in-flight new-client form. The panel
+   *  debounces them and queries /api/v1/clients/match-candidates. */
+  email?: string | null;
+  phone?: string | null;
+  name?: string | null;
+  /** Caller wants to attach the new interest to an existing client
+   *  rather than creating a new one. The form switches to
+   *  interest-only mode and pre-fills the client. */
+  onUseExisting: (match: MatchData) => void;
+  /** User explicitly said "create new anyway." Hide the panel until
+   *  they change input again. */
+  onDismiss?: () => void;
+}
+
+/**
+ * Surfaces existing clients that match the form's in-flight inputs.
+ *
+ * Renders nothing while inputs are short / no useful match found.
+ * On a high-confidence match, the panel interrupts visually with a
+ * solid border and a primary "Use this client" button.
+ *
+ * Wired into the new-client form. Skipped in edit mode.
+ */
+export function DedupSuggestionPanel({
+  email,
+  phone,
+  name,
+  onUseExisting,
+  onDismiss,
+}: DedupSuggestionPanelProps) {
+  const [dismissed, setDismissed] = useState(false);
+
+  // Debounce inputs by 300ms so we don't fire on every keystroke. Keep
+  // the latest debounced values in component state.
+  const [debounced, setDebounced] = useState({
+    email: email ?? '',
+    phone: phone ?? '',
+    name: name ?? '',
+  });
+
+  useEffect(() => {
+    const t = setTimeout(() => {
+      setDebounced({ email: email ?? '', phone: phone ?? '', name: name ?? '' });
+      // Clear the dismissed flag when inputs change — the user typed
+      // something new, so the prior dismissal no longer applies.
+      setDismissed(false);
+    }, 300);
+    return () => clearTimeout(t);
+  }, [email, phone, name]);
+
+  const hasSomething =
+    debounced.email.length > 3 || debounced.phone.length > 3 || debounced.name.length > 2;
+
+  const { data, isFetching } = useQuery<{ data: MatchData[] }>({
+    queryKey: ['dedup-match-candidates', debounced],
+    queryFn: () => {
+      const params = new URLSearchParams();
+      if (debounced.email) params.set('email', debounced.email);
+      if (debounced.phone) params.set('phone', debounced.phone);
+      if (debounced.name) params.set('name', debounced.name);
+      return apiFetch<{ data: MatchData[] }>(`/api/v1/clients/match-candidates?${params}`);
+    },
+    enabled: hasSomething && !dismissed,
+    // Same query is fine to cache for a minute — moves are slow at this layer.
+    staleTime: 60_000,
+  });
+
+  if (dismissed) return null;
+  if (!hasSomething) return null;
+  if (isFetching && !data) return null;
+  const matches = data?.data ?? [];
+  if (matches.length === 0) return null;
+
+  const top = matches[0]!;
+  const isHigh = top.confidence === 'high';
+
+  return (
+    <div
+      className={cn(
+        'rounded-lg border p-3 mb-3 transition-colors',
+        isHigh
+          ? 'border-amber-300 bg-amber-50/60 dark:bg-amber-950/30'
+          : 'border-border bg-muted/40',
+      )}
+      data-testid="dedup-suggestion"
+    >
+      <div className="flex items-start gap-3">
+        <div className="mt-0.5">
+          <AlertCircle
+            className={cn(
+              'size-5',
+              isHigh ? 'text-amber-700 dark:text-amber-400' : 'text-muted-foreground',
+            )}
+            aria-hidden
+          />
+        </div>
+        <div className="min-w-0 flex-1">
+          <p className="text-sm font-semibold leading-tight">
+            {isHigh
+              ? 'This looks like an existing client'
+              : 'Possible match — check before creating'}
+          </p>
+          <div className="mt-2 rounded-md border bg-background/80 p-2.5">
+            <div className="flex items-center gap-2">
+              <p className="truncate text-sm font-medium">{top.fullName}</p>
+              <span
+                className={cn(
+                  'shrink-0 rounded-full px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wide',
+                  isHigh
+                    ? 'bg-amber-200 text-amber-900 dark:bg-amber-800 dark:text-amber-100'
+                    : 'bg-muted text-muted-foreground',
+                )}
+              >
+                {top.confidence}
+              </span>
+            </div>
+            <div className="mt-0.5 flex flex-wrap items-center gap-x-3 gap-y-0.5 text-xs text-muted-foreground">
+              {top.emails[0] ? <span className="truncate">{top.emails[0]}</span> : null}
+              {top.phonesE164[0] ? <span>{top.phonesE164[0]}</span> : null}
+              <span className="inline-flex items-center gap-1">
+                <Briefcase className="size-3" aria-hidden />
+                {top.interestCount} {top.interestCount === 1 ? 'interest' : 'interests'}
+              </span>
+            </div>
+            <p className="mt-1.5 text-[11px] text-muted-foreground">{top.reasons.join(' · ')}</p>
+          </div>
+          <div className="mt-3 flex flex-wrap items-center gap-2">
+            <Button
+              type="button"
+              size="sm"
+              onClick={() => onUseExisting(top)}
+              data-testid="dedup-use-existing"
+            >
+              Use this client
+              <ArrowRight className="ml-1 size-3.5" aria-hidden />
+            </Button>
+            <Button
+              type="button"
+              size="sm"
+              variant="ghost"
+              onClick={() => {
+                setDismissed(true);
+                onDismiss?.();
+              }}
+              data-testid="dedup-dismiss"
+            >
+              <X className="mr-1 size-3.5" aria-hidden />
+              Create new anyway
+            </Button>
+            {matches.length > 1 ? (
+              <span className="text-xs text-muted-foreground">
+                +{matches.length - 1} other possible{' '}
+                {matches.length - 1 === 1 ? 'match' : 'matches'}
+              </span>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/clients/pipeline-constants.ts

@@ -0,0 +1,14 @@
+// Re-export from the canonical source so legacy imports keep working.
+export {
+  PIPELINE_STAGES,
+  STAGE_LABELS,
+  STAGE_BADGE,
+  STAGE_DOT,
+  STAGE_WEIGHTS,
+  STAGE_TRANSITIONS,
+  safeStage,
+  stageLabel,
+  stageBadgeClass,
+  stageDotClass,
+  type PipelineStage,
+} from '@/lib/constants';

src/components/companies/company-card.tsx

@@ -0,0 +1,141 @@
+'use client';
+
+import { Archive, Building2, Eye, Hash, MapPin, MoreHorizontal, Pencil } from 'lucide-react';
+import Link from 'next/link';
+
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { ListCard, ListCardAvatar, ListCardMeta } from '@/components/shared/list-card';
+import { cn } from '@/lib/utils';
+import { getCountryName } from '@/lib/i18n/countries';
+import type { CompanyRow } from './company-columns';
+
+const STATUS_COLORS: Record<string, string> = {
+  active: 'bg-green-100 text-green-800 border-green-300',
+  dissolved: 'bg-red-100 text-red-800 border-red-300',
+};
+
+const STATUS_LABELS: Record<string, string> = {
+  active: 'Active',
+  dissolved: 'Dissolved',
+};
+
+interface CompanyCardProps {
+  company: CompanyRow;
+  portSlug: string;
+  onEdit: (company: CompanyRow) => void;
+  onArchive: (company: CompanyRow) => void;
+}
+
+export function CompanyCard({ company, portSlug, onEdit, onArchive }: CompanyCardProps) {
+  const statusLabel = STATUS_LABELS[company.status] ?? company.status;
+  const statusColor =
+    STATUS_COLORS[company.status] ?? 'bg-muted text-muted-foreground border-muted';
+
+  const country = company.incorporationCountryIso
+    ? getCountryName(company.incorporationCountryIso, 'en')
+    : null;
+
+  const memberCount = company.memberCount ?? 0;
+  const yachtCount = company.yachtCount ?? 0;
+  const countParts: string[] = [];
+  if (memberCount > 0)
+    countParts.push(`${memberCount} ${memberCount === 1 ? 'member' : 'members'}`);
+  if (yachtCount > 0) countParts.push(`${yachtCount} ${yachtCount === 1 ? 'yacht' : 'yachts'}`);
+
+  // Skip legalName if it is identical to name or absent
+  const showLegalName =
+    company.legalName && company.legalName.toLowerCase() !== company.name.toLowerCase();
+
+  return (
+    <ListCard
+      href={`/${portSlug}/companies/${company.id}`}
+      ariaLabel={`Company ${company.name}`}
+      actions={
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-9 w-9"
+              onClick={(e) => e.stopPropagation()}
+              aria-label={`Actions for ${company.name}`}
+            >
+              <MoreHorizontal className="h-4 w-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem asChild>
+              <Link href={`/${portSlug}/companies/${company.id}`}>
+                <Eye className="mr-2 h-3.5 w-3.5" />
+                View
+              </Link>
+            </DropdownMenuItem>
+            <DropdownMenuItem onClick={() => onEdit(company)}>
+              <Pencil className="mr-2 h-3.5 w-3.5" />
+              Edit
+            </DropdownMenuItem>
+            <DropdownMenuItem className="text-destructive" onClick={() => onArchive(company)}>
+              <Archive className="mr-2 h-3.5 w-3.5" />
+              Archive
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      }
+    >
+      <div className="flex items-start gap-3">
+        <ListCardAvatar icon={<Building2 className="h-5 w-5" />} />
+        <div className="min-w-0 flex-1">
+          {/* Title row + spacer for actions button */}
+          <div className="flex items-start justify-between gap-2">
+            <h3 className="truncate text-base font-semibold tracking-tight text-foreground">
+              {company.name}
+            </h3>
+            <span aria-hidden className="block h-9 w-9 shrink-0" />
+          </div>
+
+          {/* Legal name subtitle */}
+          {showLegalName ? (
+            <p className="mt-0.5 truncate text-sm text-muted-foreground">{company.legalName}</p>
+          ) : null}
+
+          {/* Country + Tax ID meta line */}
+          {country || company.taxId ? (
+            <div className="mt-0.5 flex flex-wrap items-center gap-x-2 gap-y-0.5 text-xs text-muted-foreground">
+              {country ? (
+                <ListCardMeta icon={<MapPin className="h-3 w-3" />}>{country}</ListCardMeta>
+              ) : null}
+              {company.taxId ? (
+                <ListCardMeta icon={<Hash className="h-3 w-3" />}>{company.taxId}</ListCardMeta>
+              ) : null}
+            </div>
+          ) : null}
+
+          {/* Member / yacht counts */}
+          {countParts.length > 0 ? (
+            <p className="mt-0.5 text-xs text-muted-foreground">{countParts.join(' · ')}</p>
+          ) : null}
+
+          {/* Status pill */}
+          {company.status ? (
+            <div className="mt-1.5">
+              <span
+                className={cn(
+                  'inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-medium',
+                  statusColor,
+                )}
+              >
+                {statusLabel}
+              </span>
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </ListCard>
+  );
+}

src/components/companies/company-detail-header.tsx

@@ -77,10 +77,14 @@ export function CompanyDetailHeader({ company }: CompanyDetailHeaderProps) {
   return (
     <>
       <DetailHeaderStrip>
-        <div className="flex items-start gap-3 flex-wrap">
+        {/* Stack actions below the title block on phone widths; horizontal
+            beside it from sm up. */}
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:flex-wrap sm:gap-3">
           <div className="flex-1 min-w-0">
             <div className="flex items-center gap-2 flex-wrap">
-              <h1 className="text-2xl font-bold text-foreground truncate">{company.name}</h1>
+              <h1 className="hidden sm:block text-2xl font-bold text-foreground truncate">
+                {company.name}
+              </h1>
               <span
                 className={`inline-flex items-center rounded-full border px-3 py-1 text-xs font-medium ${statusColor}`}
               >
@@ -100,7 +104,7 @@ export function CompanyDetailHeader({ company }: CompanyDetailHeaderProps) {
           </div>
 
           {/* Actions */}
-          <div className="flex items-center gap-2">
+          <div className="flex flex-wrap items-center gap-2">
             <PermissionGate resource="companies" action="edit">
               <Button variant="outline" size="sm" onClick={() => setEditOpen(true)}>
                 <Pencil className="mr-1.5 h-3.5 w-3.5" />

src/components/companies/company-detail.tsx

@@ -1,9 +1,11 @@
 'use client';
 
+import { useEffect } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import { useParams } from 'next/navigation';
 
 import { DetailLayout } from '@/components/shared/detail-layout';
+import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
 import { CompanyDetailHeader } from '@/components/companies/company-detail-header';
 import { getCompanyTabs } from '@/components/companies/company-tabs';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
@@ -45,6 +47,13 @@ export function CompanyDetail({ companyId, currentUserId }: CompanyDetailProps)
       apiFetch<{ data: CompanyData }>(`/api/v1/companies/${companyId}`).then((r) => r.data),
   });
 
+  const { setChrome } = useMobileChrome();
+  const titleForChrome: string | null = data?.name ?? null;
+  useEffect(() => {
+    setChrome({ title: titleForChrome, showBackButton: true });
+    return () => setChrome({ title: null, showBackButton: false });
+  }, [titleForChrome, setChrome]);
+
   useRealtimeInvalidation({
     'company:updated': [['companies', companyId]],
     'company:archived': [['companies', companyId]],