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

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

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

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

.gitignore

@@ -40,6 +40,9 @@ docker-compose.override.yml
 /.audit/
 /.audit-screenshots/
 
+# Migration script output (CSV reports, transcripts)
+.migration/
+
 # Tool caches / runtime state
 /.claude/
 /.serena/

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-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.

scripts/backfill-legacy-lead-source.ts

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

scripts/backfill-phone-e164.ts

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

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

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

scripts/migrate-from-nocodb.ts

@@ -0,0 +1,251 @@
+/**
+ * One-shot migration: legacy NocoDB Interests → new client/interest split.
+ *
+ * Usage:
+ *
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --dry-run
+ *     Pulls the live NocoDB base, runs the transform + dedup pipeline,
+ *     writes a report to .migration/<timestamp>/. NO database writes.
+ *
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --dry-run --port-slug port-nimara
+ *     Same, but tags the planned writes with the named port (matters for
+ *     the apply phase — every client/interest belongs to one port).
+ *
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --apply --port-slug port-nimara
+ *     Re-fetches NocoDB, re-transforms, then writes the planned rows
+ *     into the target port via the idempotent `migration_source_links`
+ *     ledger. Re-runs are safe — already-imported source IDs are skipped.
+ *     REQUIRES `EMAIL_REDIRECT_TO` to be set in env (safety net) unless
+ *     `--unsafe-skip-redirect-check` is also passed.
+ *
+ * Design reference: docs/superpowers/specs/2026-05-03-dedup-and-migration-design.md §9.
+ */
+
+import 'dotenv/config';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { applyPlan } from '@/lib/dedup/migration-apply';
+import { fetchSnapshot, loadNocoDbConfig } from '@/lib/dedup/nocodb-source';
+import { transformSnapshot } from '@/lib/dedup/migration-transform';
+import { resolveReportPaths, writeReport } from '@/lib/dedup/migration-report';
+
+interface CliArgs {
+  dryRun: boolean;
+  apply: boolean;
+  portSlug: string | null;
+  reportDir: string | null;
+  unsafeSkipRedirectCheck: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    dryRun: false,
+    apply: false,
+    portSlug: null,
+    reportDir: null,
+    unsafeSkipRedirectCheck: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--apply') args.apply = true;
+    else if (a === '--port-slug') args.portSlug = argv[++i] ?? null;
+    else if (a === '--report') args.reportDir = argv[++i] ?? null;
+    else if (a === '--unsafe-skip-redirect-check') args.unsafeSkipRedirectCheck = true;
+    else if (a === '-h' || a === '--help') {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage:
+  pnpm tsx scripts/migrate-from-nocodb.ts --dry-run [--port-slug <slug>]
+    Pulls NocoDB → transforms → writes report to .migration/<timestamp>/.
+    No database writes.
+
+  pnpm tsx scripts/migrate-from-nocodb.ts --apply --port-slug <slug>
+    Re-fetches NocoDB, re-transforms, writes via migration_source_links
+    ledger. Idempotent — safe to re-run. Requires EMAIL_REDIRECT_TO set
+    (unless --unsafe-skip-redirect-check is also passed).
+
+Flags:
+  --dry-run                       Read NocoDB, write report only.
+  --apply                         Actually write rows to the DB.
+  --port-slug <slug>              Port slug to attach to all imported
+                                  entities. Defaults to the first
+                                  available port if omitted.
+  --report <dir>                  Path to a previously-generated report
+                                  dir (only used by --apply).
+  --unsafe-skip-redirect-check    Skip the EMAIL_REDIRECT_TO precondition
+                                  check. Only use in production cutover.
+  -h, --help                      Show this help.
+`);
+}
+
+/**
+ * Resolve the target port: use the slug if provided, otherwise the first
+ * port found. Errors out cleanly if the slug doesn't match any port.
+ */
+async function resolvePort(slug: string | null): Promise<{ id: string; slug: string }> {
+  if (slug) {
+    const [p] = await db
+      .select({ id: ports.id, slug: ports.slug })
+      .from(ports)
+      .where(eq(ports.slug, slug))
+      .limit(1);
+    if (!p) {
+      console.error(`No port found with slug "${slug}".`);
+      process.exit(1);
+    }
+    return { id: p.id, slug: p.slug };
+  }
+  const [first] = await db.select({ id: ports.id, slug: ports.slug }).from(ports).limit(1);
+  if (!first) {
+    console.error('No ports exist in the target DB. Seed at least one port before applying.');
+    process.exit(1);
+  }
+  return { id: first.id, slug: first.slug };
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.dryRun && !args.apply) {
+    console.error('Must specify --dry-run or --apply');
+    printHelp();
+    process.exit(1);
+  }
+
+  // Safety gate: --apply must run with EMAIL_REDIRECT_TO set, unless the
+  // operator explicitly opts out (production cutover).
+  if (args.apply && !process.env.EMAIL_REDIRECT_TO && !args.unsafeSkipRedirectCheck) {
+    console.error(
+      '--apply requires EMAIL_REDIRECT_TO to be set in the environment as a safety net.',
+    );
+    console.error('See docs/operations/outbound-comms-safety.md for the rationale.');
+    console.error(
+      'If you are running the production cutover and have read that doc, add ' +
+        '--unsafe-skip-redirect-check to override.',
+    );
+    process.exit(2);
+  }
+
+  // ── Fetch + transform (shared by dry-run and apply) ──────────────────────
+
+  console.log('[migrate] Loading NocoDB config…');
+  const config = loadNocoDbConfig();
+  console.log(`[migrate] Source: ${config.url}`);
+
+  console.log('[migrate] Fetching snapshot from NocoDB…');
+  const start = Date.now();
+  const snapshot = await fetchSnapshot(config);
+  const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+  console.log(
+    `[migrate] Snapshot fetched in ${elapsed}s — ${snapshot.interests.length} interests, ${snapshot.residentialInterests.length} residential, ${snapshot.berths.length} berths.`,
+  );
+
+  console.log('[migrate] Running transform + dedup pipeline…');
+  const plan = transformSnapshot(snapshot);
+
+  // Resolve output paths relative to the worktree root.
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const repoRoot = path.resolve(scriptDir, '..');
+  const generatedAt = new Date().toISOString();
+  const paths = resolveReportPaths(repoRoot);
+
+  console.log(`[migrate] Writing report to ${paths.rootDir}…`);
+  await writeReport(paths, plan, generatedAt);
+
+  // ── Plan summary ─────────────────────────────────────────────────────────
+  const s = plan.stats;
+  console.log('');
+  console.log('=== Migration Plan Summary ===');
+  console.log(
+    `  Input:     ${s.inputInterestRows} interests, ${s.inputResidentialRows} residential interests`,
+  );
+  console.log(`  Output:    ${s.outputClients} clients, ${s.outputInterests} interests`);
+  console.log(`             ${s.outputContacts} contacts, ${s.outputAddresses} addresses`);
+  console.log(
+    `             ${s.outputDocuments} EOI documents, ${s.outputDocumentSigners} signers`,
+  );
+  console.log(
+    `             ${s.outputResidentialClients} residential clients (with default-stage interests)`,
+  );
+  console.log(
+    `  Dedup:     ${s.autoLinkedClusters} auto-linked clusters, ${s.needsReviewPairs} pairs flagged for review`,
+  );
+  console.log(`  Quality:   ${s.flaggedRows} rows flagged (see report.csv)`);
+  console.log('');
+  console.log(`  Full report: ${paths.summaryPath}`);
+
+  if (args.dryRun) {
+    console.log('');
+    console.log('Dry-run complete. Re-run with --apply to write rows.');
+    return;
+  }
+
+  // ── Apply path ───────────────────────────────────────────────────────────
+
+  const port = await resolvePort(args.portSlug);
+  const applyId = randomUUID();
+
+  console.log('');
+  console.log(`[migrate] Applying to port "${port.slug}" (id=${port.id})`);
+  console.log(`[migrate] Apply id: ${applyId}`);
+  console.log('[migrate] Inserting…');
+
+  const applyStart = Date.now();
+  const result = await applyPlan(plan, { port, applyId });
+  const applyElapsed = ((Date.now() - applyStart) / 1000).toFixed(1);
+
+  console.log('');
+  console.log('=== Apply Result ===');
+  console.log(`  Time:      ${applyElapsed}s`);
+  console.log(
+    `  Clients:   ${result.clientsInserted} inserted, ${result.clientsSkipped} already linked`,
+  );
+  console.log(`  Contacts:  ${result.contactsInserted} inserted`);
+  console.log(`  Addresses: ${result.addressesInserted} inserted`);
+  console.log(`  Yachts:    ${result.yachtsInserted} inserted`);
+  console.log(
+    `  Interests: ${result.interestsInserted} inserted, ${result.interestsSkipped} already linked`,
+  );
+  console.log(
+    `  Documents: ${result.documentsInserted} inserted, ${result.documentsSkipped} already linked`,
+  );
+  console.log(`  Signers:   ${result.documentSignersInserted} inserted`);
+  console.log(
+    `  Res-Clt:   ${result.residentialClientsInserted} inserted, ${result.residentialClientsSkipped} already linked`,
+  );
+  console.log(`  Res-Int:   ${result.residentialInterestsInserted} inserted`);
+
+  if (result.warnings.length > 0) {
+    console.log('');
+    console.log('Warnings:');
+    for (const w of result.warnings.slice(0, 20)) {
+      console.log(`  - ${w}`);
+    }
+    if (result.warnings.length > 20) {
+      console.log(`  … ${result.warnings.length - 20} more`);
+    }
+  }
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error('[migrate] Fatal error:', err);
+  process.exit(1);
+});

scripts/smoke-test-redirect.ts

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

src/app/(dashboard)/[portSlug]/admin/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

@@ -34,7 +34,7 @@ const FIELDS: SettingFieldDef[] = [
     label: 'Default signature (HTML)',
     description: 'Appended to the bottom of system-generated emails.',
     type: 'html',
-    placeholder: '<p>—<br>The Port Nimara team</p>',
+    placeholder: '<p>-<br>The Port Nimara team</p>',
     defaultValue: '',
   },
   {
@@ -71,7 +71,7 @@ const FIELDS: SettingFieldDef[] = [
   {
     key: 'smtp_pass_override',
     label: 'SMTP password override',
-    description: 'Optional. Stored in plain text — only set when overriding env credentials.',
+    description: 'Optional. Stored in plain text - only set when overriding env credentials.',
     type: 'password',
     defaultValue: '',
   },

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

@@ -16,7 +16,9 @@ import {
   Tag,
   Upload,
   Users,
+  UsersRound,
   Webhook,
+  Globe,
 } from 'lucide-react';
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
@@ -29,7 +31,17 @@ interface AdminSection {
   icon: typeof Settings;
 }
 
-const SECTIONS: AdminSection[] = [
+interface AdminGroup {
+  title: string;
+  description: string;
+  sections: AdminSection[];
+}
+
+const GROUPS: AdminGroup[] = [
+  {
+    title: 'Access',
+    description: 'Who can sign in and what they can do once they do.',
+    sections: [
       {
         href: 'users',
         label: 'Users',
@@ -48,12 +60,12 @@ const SECTIONS: AdminSection[] = [
         description: 'Default permission sets and per-port role overrides.',
         icon: Shield,
       },
-  {
-    href: 'audit',
-    label: 'Audit Log',
-    description: 'Searchable log of every authenticated mutation in the system.',
-    icon: ScrollText,
+    ],
   },
+  {
+    title: 'Configuration',
+    description: 'Branding, integrations, and per-port settings.',
+    sections: [
       {
         href: 'email',
         label: 'Email Settings',
@@ -90,6 +102,12 @@ const SECTIONS: AdminSection[] = [
         description: 'Outgoing webhook subscriptions, secrets, and delivery log.',
         icon: Webhook,
       },
+    ],
+  },
+  {
+    title: 'Content',
+    description: 'Forms, templates, and labels that users see.',
+    sections: [
       {
         href: 'forms',
         label: 'Forms',
@@ -114,6 +132,36 @@ const SECTIONS: AdminSection[] = [
         description: 'Tenant-defined fields for clients, yachts, and reservations.',
         icon: Key,
       },
+    ],
+  },
+  {
+    title: 'Data Quality',
+    description: 'Cleanup, imports, and the audit trail.',
+    sections: [
+      {
+        href: 'duplicates',
+        label: 'Duplicates',
+        description: 'Review queue of suspected duplicate clients flagged by the dedup engine.',
+        icon: UsersRound,
+      },
+      {
+        href: 'import',
+        label: 'Bulk Import',
+        description: 'CSV-driven imports for clients, yachts, and reservations.',
+        icon: Upload,
+      },
+      {
+        href: 'audit',
+        label: 'Audit Log',
+        description: 'Searchable log of every authenticated mutation in the system.',
+        icon: ScrollText,
+      },
+    ],
+  },
+  {
+    title: 'Operations',
+    description: 'Health checks and disaster recovery.',
+    sections: [
       {
         href: 'reports',
         label: 'Reports',
@@ -126,18 +174,18 @@ const SECTIONS: AdminSection[] = [
         description: 'BullMQ queue health, throughput, and retry diagnostics.',
         icon: Database,
       },
-  {
-    href: 'import',
-    label: 'Bulk Import',
-    description: 'CSV-driven imports for clients, yachts, and reservations.',
-    icon: Upload,
-  },
       {
         href: 'backup',
         label: 'Backup & Restore',
         description: 'Database snapshots and on-demand exports.',
         icon: HardDrive,
       },
+    ],
+  },
+  {
+    title: 'Tenancy',
+    description: 'Multi-port and multi-install scaffolding.',
+    sections: [
       {
         href: 'ports',
         label: 'Ports',
@@ -150,12 +198,26 @@ const SECTIONS: AdminSection[] = [
         description: 'Initial-setup wizard for fresh ports.',
         icon: LayoutDashboard,
       },
+    ],
+  },
+  {
+    title: 'Integrations',
+    description: 'Third-party providers wired into the app.',
+    sections: [
       {
         href: 'ocr',
         label: 'Receipt OCR',
         description: 'Configure the AI provider used by the mobile receipt scanner.',
         icon: ScrollText,
       },
+      {
+        href: 'website-analytics',
+        label: 'Website analytics (Umami)',
+        description: 'Per-port Umami URL, API token, and Website ID.',
+        icon: Globe,
+      },
+    ],
+  },
 ];
 
 export default async function AdminLandingPage({
@@ -165,13 +227,21 @@ export default async function AdminLandingPage({
 }) {
   const { portSlug } = await params;
   return (
-    <div className="space-y-6">
+    <div className="space-y-8">
       <PageHeader
         title="Administration"
         description="Per-port configuration and system administration. Each card below opens a dedicated settings page."
       />
+      {GROUPS.map((group) => (
+        <section key={group.title} className="space-y-3">
+          <div>
+            <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
@@ -195,6 +265,8 @@ export default async function AdminLandingPage({
               );
             })}
           </div>
+        </section>
+      ))}
     </div>
   );
 }

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

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

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

@@ -4,13 +4,13 @@ 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
+ * 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 */}
+      {/* 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" />

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

@@ -59,7 +59,7 @@ export default function NewInvoicePage() {
   }, [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
+  // 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: {
@@ -184,7 +184,7 @@ export default function NewInvoicePage() {
 
   return (
     <div className="max-w-2xl mx-auto space-y-6">
-      {/* Header — desktop only; mobile gets the title from the topbar */}
+      {/* 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" />
@@ -233,7 +233,7 @@ export default function NewInvoicePage() {
                         {prefilledInterest?.data
                           ? `Linked to ${prefilledInterest.data.clientName ?? 'interest'}${
                               prefilledInterest.data.berthMooringNumber
-                                ? ` — Berth ${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%".'}

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

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

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

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

src/app/(dashboard)/layout.tsx

@@ -40,7 +40,7 @@ export default async function DashboardLayout({ children }: { children: React.Re
         <PermissionsProvider>
           <SocketProvider>
             <RealtimeToasts />
-            {/* Desktop shell — hidden by CSS on mobile */}
+            {/* Desktop shell - hidden by CSS on mobile */}
             <div data-shell="desktop" className="flex h-screen overflow-hidden bg-background">
               <Sidebar
                 portRoles={portRoles}
@@ -49,6 +49,7 @@ export default async function DashboardLayout({ children }: { children: React.Re
                   name: profile?.displayName ?? session.user.name ?? session.user.email,
                   email: session.user.email,
                 }}
+                ports={ports}
               />
               <div className="flex-1 flex flex-col overflow-hidden min-w-0">
                 <Topbar
@@ -58,11 +59,13 @@ export default async function DashboardLayout({ children }: { children: React.Re
                     email: session.user.email,
                   }}
                 />
-                <main className="flex-1 overflow-y-auto bg-background p-6">{children}</main>
+                <main className="flex-1 overflow-y-auto bg-background pt-3 px-6 pb-6">
+                  {children}
+                </main>
               </div>
             </div>
 
-            {/* Mobile shell — hidden by CSS on desktop */}
+            {/* Mobile shell - hidden by CSS on desktop */}
             <MobileLayout>{children}</MobileLayout>
           </SocketProvider>
         </PermissionsProvider>

src/app/(portal)/layout.tsx

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

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

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

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

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

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

@@ -57,7 +57,7 @@ export default async function PortalInterestsPage() {
                       <span className="font-medium text-gray-900">General Interest</span>
                     )}
                     {interest.berthArea && (
-                      <span className="text-sm text-gray-400">— {interest.berthArea}</span>
+                      <span className="text-sm text-gray-400">- {interest.berthArea}</span>
                     )}
                   </div>
                   {interest.leadCategory && (

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

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

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

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

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

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

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

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

src/app/api/health/route.ts

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

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

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

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

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

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

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

src/app/api/ready/route.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -3,7 +3,7 @@ import { withAuth, withPermission } from '@/lib/api/helpers';
 import { getHandler, patchHandler, deleteHandler } from './handlers';
 
 export const GET = withAuth(withPermission('reservations', 'view', getHandler));
-// PATCH cannot use `withPermission` wrapper — the required permission depends
+// PATCH cannot use `withPermission` wrapper - the required permission depends
 // on the `action` field in the body. `requirePermission` is called inside the
 // handler after the body is parsed.
 export const PATCH = withAuth(patchHandler);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -12,9 +12,9 @@ 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',
+  lost_other_marina: 'Lost - went to another marina',
+  lost_unqualified: 'Lost - unqualified',
+  lost_no_response: 'Lost - no response',
   cancelled: 'Cancelled',
 };
 
@@ -187,7 +187,7 @@ function buildAuditDescription(
     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}`;
+    return reason ? `Marked as ${label} - ${reason}` : `Marked as ${label}`;
   }
 
   if (type === 'outcome_cleared') {
@@ -200,9 +200,9 @@ function buildAuditDescription(
     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} (auto-advanced - ${reason})` : `Stage advanced to ${stage}`;
     }
-    return reason ? `Stage changed to ${stage} — ${reason}` : `Stage changed to ${stage}`;
+    return reason ? `Stage changed to ${stage} - ${reason}` : `Stage changed to ${stage}`;
   }
 
   if (action === 'update' && newValue?.pipelineStage) {

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

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

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

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

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

@@ -75,7 +75,7 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
     });
 
     if (existing) {
-      logger.info({ signatureHash }, 'Duplicate Documenso webhook — skipping');
+      logger.info({ signatureHash }, 'Duplicate Documenso webhook - skipping');
       return NextResponse.json({ ok: true }, { status: 200 });
     }
   } catch (err) {

src/app/globals.css

@@ -93,7 +93,7 @@
     @apply bg-background text-foreground font-sans antialiased;
   }
 
-  /* Wave watermark — subtle background texture for auth pages */
+  /* Wave watermark - subtle background texture for auth pages */
   .wave-watermark {
     background-image: repeating-linear-gradient(
       135deg,
@@ -134,7 +134,7 @@
  * 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
+ * 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).
  */
@@ -169,3 +169,33 @@ body[data-form-factor='mobile'] [data-shell='mobile'] {
     display: none !important;
   }
 }
+
+/*
+ * Recharts focus-ring suppression.
+ *
+ * Recharts SVG surfaces become keyboard-focusable when a user clicks into
+ * them (the library adds tabindex on chart sectors / paths). The global
+ * `*:focus-visible` rule above paints a 4px brand-blue box-shadow ring,
+ * which on a chart surface reads as a stray rectangle around the plot
+ * area. Hover/tooltip already handles chart interactivity, so suppress
+ * the ring entirely here.
+ *
+ * Lives OUTSIDE `@layer base` so Tailwind's PostCSS pipeline can't drop
+ * it during purge (an earlier copy inside `@layer base` was being
+ * silently removed at build time, leaving the ring intact).
+ */
+div.recharts-wrapper:focus,
+div.recharts-wrapper:focus-visible,
+svg.recharts-surface:focus,
+svg.recharts-surface:focus-visible,
+div.recharts-responsive-container:focus,
+div.recharts-responsive-container:focus-visible,
+.recharts-wrapper *:focus,
+.recharts-wrapper *:focus-visible {
+  outline: none !important;
+  box-shadow: none !important;
+  --tw-ring-shadow: 0 0 #0000 !important;
+  --tw-ring-offset-shadow: 0 0 #0000 !important;
+  --tw-ring-color: transparent !important;
+  --tw-ring-offset-color: transparent !important;
+}

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

@@ -87,7 +87,7 @@ export function AuditLogList() {
   const [loading, setLoading] = useState(true);
   const [loadingMore, setLoadingMore] = useState(false);
 
-  // Filter state — debounce text inputs.
+  // Filter state - debounce text inputs.
   const [search, setSearch] = useState('');
   const [entityType, setEntityType] = useState<string>('all');
   const [action, setAction] = useState<string>('all');
@@ -215,7 +215,7 @@ export function AuditLogList() {
             </span>
           );
         }
-        return <span className="text-xs text-muted-foreground">—</span>;
+        return <span className="text-xs text-muted-foreground">-</span>;
       },
     },
     {
@@ -245,7 +245,7 @@ export function AuditLogList() {
       <PageHeader
         title="Audit Log"
         eyebrow="Admin"
-        description="Every state change in this port — fully searchable."
+        description="Every state change in this port - fully searchable."
         variant="gradient"
       />
 

src/components/admin/custom-fields/custom-field-form.tsx

@@ -59,12 +59,7 @@ const FIELD_TYPE_LABELS: Record<string, string> = {
 
 // ─── Component ────────────────────────────────────────────────────────────────
 
-export function CustomFieldForm({
-  open,
-  onOpenChange,
-  field,
-  onSuccess,
-}: CustomFieldFormProps) {
+export function CustomFieldForm({ open, onOpenChange, field, onSuccess }: CustomFieldFormProps) {
   const isEdit = !!field;
 
   // Form state
@@ -72,9 +67,7 @@ export function CustomFieldForm({
   const [fieldName, setFieldName] = useState(field?.fieldName ?? '');
   const [fieldLabel, setFieldLabel] = useState(field?.fieldLabel ?? '');
   const [fieldType, setFieldType] = useState(field?.fieldType ?? 'text');
-  const [selectOptions, setSelectOptions] = useState<string[]>(
-    field?.selectOptions ?? [],
-  );
+  const [selectOptions, setSelectOptions] = useState<string[]>(field?.selectOptions ?? []);
   const [newOption, setNewOption] = useState('');
   const [isRequired, setIsRequired] = useState(field?.isRequired ?? false);
   const [sortOrder, setSortOrder] = useState(field?.sortOrder ?? 0);
@@ -169,13 +162,11 @@ export function CustomFieldForm({
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent className="max-w-lg">
         <DialogHeader>
-          <DialogTitle>
-            {isEdit ? 'Edit Custom Field' : 'New Custom Field'}
-          </DialogTitle>
+          <DialogTitle>{isEdit ? 'Edit Custom Field' : 'New Custom Field'}</DialogTitle>
         </DialogHeader>
 
         <form onSubmit={handleSubmit} className="space-y-5 py-2">
-          {/* Entity Type — create only */}
+          {/* Entity Type - create only */}
           <div className="space-y-1.5">
             <Label htmlFor="cf-entity-type">Entity Type</Label>
             {isEdit ? (
@@ -198,7 +189,7 @@ export function CustomFieldForm({
             )}
           </div>
 
-          {/* Field Name — create only */}
+          {/* Field Name - create only */}
           <div className="space-y-1.5">
             <Label htmlFor="cf-field-name">
               Field Name
@@ -232,7 +223,7 @@ export function CustomFieldForm({
             />
           </div>
 
-          {/* Field Type — create only */}
+          {/* Field Type - create only */}
           <div className="space-y-1.5">
             <Label htmlFor="cf-field-type">Field Type</Label>
             {isEdit ? (
@@ -260,7 +251,7 @@ export function CustomFieldForm({
             )}
           </div>
 
-          {/* Select Options — visible when fieldType = 'select' */}
+          {/* Select Options - visible when fieldType = 'select' */}
           {fieldType === 'select' && (
             <div className="space-y-2">
               <Label>Options</Label>
@@ -302,11 +293,7 @@ export function CustomFieldForm({
           {/* Is Required */}
           <div className="flex items-center justify-between">
             <Label htmlFor="cf-is-required">Required field</Label>
-            <Switch
-              id="cf-is-required"
-              checked={isRequired}
-              onCheckedChange={setIsRequired}
-            />
+            <Switch id="cf-is-required" checked={isRequired} onCheckedChange={setIsRequired} />
           </div>
 
           {/* Sort Order */}

src/components/admin/document-templates/template-form.tsx

@@ -11,13 +11,7 @@ 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 { apiFetch } from '@/lib/api/client';
 import { TEMPLATE_VARIABLES } from '@/lib/pdf/tiptap-to-pdfme';
 
@@ -61,20 +55,13 @@ interface TemplateFormProps {
   onSuccess: () => void;
 }
 
-export function TemplateForm({
-  open,
-  onOpenChange,
-  template,
-  onSuccess,
-}: TemplateFormProps) {
+export function TemplateForm({ open, onOpenChange, template, onSuccess }: TemplateFormProps) {
   const isEdit = !!template;
 
   const [name, setName] = useState(template?.name ?? '');
   const [type, setType] = useState(template?.templateType ?? 'other');
   const [contentJson, setContentJson] = useState(
-    template?.content
-      ? JSON.stringify(template.content, null, 2)
-      : EMPTY_DOC,
+    template?.content ? JSON.stringify(template.content, null, 2) : EMPTY_DOC,
   );
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -86,7 +73,7 @@ export function TemplateForm({
       setJsonError(null);
       return true;
     } catch {
-      setJsonError('Invalid JSON — check syntax.');
+      setJsonError('Invalid JSON - check syntax.');
       return false;
     }
   }
@@ -115,8 +102,7 @@ export function TemplateForm({
       onSuccess();
       onOpenChange(false);
     } catch (err: unknown) {
-      const message =
-        err instanceof Error ? err.message : 'Something went wrong';
+      const message = err instanceof Error ? err.message : 'Something went wrong';
       setError(message);
     } finally {
       setLoading(false);
@@ -127,9 +113,7 @@ export function TemplateForm({
     <Sheet open={open} onOpenChange={onOpenChange}>
       <SheetContent className="w-full max-w-2xl overflow-y-auto sm:max-w-2xl">
         <SheetHeader>
-          <SheetTitle>
-            {isEdit ? 'Edit Template' : 'New Document Template'}
-          </SheetTitle>
+          <SheetTitle>{isEdit ? 'Edit Template' : 'New Document Template'}</SheetTitle>
         </SheetHeader>
 
         <form onSubmit={handleSubmit} className="mt-6 space-y-6">
@@ -145,7 +129,7 @@ export function TemplateForm({
             />
           </div>
 
-          {/* Type — only on create */}
+          {/* Type - only on create */}
           {!isEdit && (
             <div className="space-y-2">
               <Label htmlFor="template-type">Document Type</Label>
@@ -166,15 +150,11 @@ export function TemplateForm({
 
           {/* TipTap JSON Content */}
           <div className="space-y-2">
-            <Label htmlFor="template-content">
-              Document Content (TipTap JSON)
-            </Label>
+            <Label htmlFor="template-content">Document Content (TipTap JSON)</Label>
             <p className="text-xs text-muted-foreground">
               Paste or edit TipTap JSON. Use{' '}
-              <code className="rounded bg-muted px-1 text-xs">
-                {'{{variable.key}}'}
-              </code>{' '}
-              tokens for dynamic content.
+              <code className="rounded bg-muted px-1 text-xs">{'{{variable.key}}'}</code> tokens for
+              dynamic content.
             </p>
             <textarea
               id="template-content"
@@ -187,9 +167,7 @@ export function TemplateForm({
               className="w-full rounded-md border border-input bg-background px-3 py-2 font-mono text-xs shadow-sm focus:outline-none focus:ring-2 focus:ring-ring"
               spellCheck={false}
             />
-            {jsonError && (
-              <p className="text-xs text-destructive">{jsonError}</p>
-            )}
+            {jsonError && <p className="text-xs text-destructive">{jsonError}</p>}
           </div>
 
           {/* Available Variables Reference */}
@@ -200,19 +178,15 @@ export function TemplateForm({
             <div className="mt-3 grid grid-cols-1 gap-1 sm:grid-cols-2">
               {TEMPLATE_VARIABLES.map((v) => (
                 <div key={v.key} className="text-xs">
-                  <code className="rounded bg-muted px-1">
-                    {`{{${v.key}}}`}
-                  </code>{' '}
-                  <span className="text-muted-foreground">— {v.label}</span>
+                  <code className="rounded bg-muted px-1">{`{{${v.key}}}`}</code>{' '}
+                  <span className="text-muted-foreground">- {v.label}</span>
                 </div>
               ))}
             </div>
           </details>
 
           {error && (
-            <p className="rounded bg-destructive/10 px-3 py-2 text-sm text-destructive">
-              {error}
-            </p>
+            <p className="rounded bg-destructive/10 px-3 py-2 text-sm text-destructive">{error}</p>
           )}
 
           <SheetFooter>
@@ -225,11 +199,7 @@ export function TemplateForm({
               Cancel
             </Button>
             <Button type="submit" disabled={loading || !!jsonError}>
-              {loading
-                ? 'Saving…'
-                : isEdit
-                  ? 'Save Changes'
-                  : 'Create Template'}
+              {loading ? 'Saving…' : isEdit ? 'Save Changes' : 'Create Template'}
             </Button>
           </SheetFooter>
         </form>

src/components/admin/document-templates/template-list.tsx

@@ -9,12 +9,7 @@ import { PageHeader } from '@/components/shared/page-header';
 import { ConfirmationDialog } from '@/components/shared/confirmation-dialog';
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
-import {
-  Sheet,
-  SheetContent,
-  SheetHeader,
-  SheetTitle,
-} from '@/components/ui/sheet';
+import { Sheet, SheetContent, SheetHeader, SheetTitle } from '@/components/ui/sheet';
 import { apiFetch } from '@/lib/api/client';
 import { TemplateForm } from './template-form';
 import { TemplateVersionHistory } from './template-version-history';
@@ -57,9 +52,7 @@ export function TemplateList() {
   const fetchTemplates = useCallback(async () => {
     setLoading(true);
     try {
-      const res = await apiFetch<{ data: AdminTemplate[] }>(
-        '/api/v1/admin/templates',
-      );
+      const res = await apiFetch<{ data: AdminTemplate[] }>('/api/v1/admin/templates');
       setTemplates(res.data);
     } finally {
       setLoading(false);
@@ -122,9 +115,7 @@ export function TemplateList() {
       accessorKey: 'version',
       header: 'Version',
       cell: ({ row }) => (
-        <span className="text-sm text-muted-foreground">
-          v{row.original.version}
-        </span>
+        <span className="text-sm text-muted-foreground">v{row.original.version}</span>
       ),
     },
     {
@@ -151,10 +142,7 @@ export function TemplateList() {
       header: '',
       cell: ({ row }) => (
         <div className="flex items-center justify-end gap-1">
-          <TemplatePreview
-            content={row.original.content}
-            templateName={row.original.name}
-          />
+          <TemplatePreview content={row.original.content} templateName={row.original.name} />
           <Button
             variant="ghost"
             size="icon"
@@ -177,9 +165,7 @@ export function TemplateList() {
             title={row.original.isActive ? 'Deactivate' : 'Activate'}
             onClick={() => handleToggleActive(row.original)}
           >
-            <span className="text-xs">
-              {row.original.isActive ? 'Off' : 'On'}
-            </span>
+            <span className="text-xs">{row.original.isActive ? 'Off' : 'On'}</span>
           </Button>
           <ConfirmationDialog
             trigger={
@@ -233,9 +219,7 @@ export function TemplateList() {
       <Sheet open={historyOpen} onOpenChange={setHistoryOpen}>
         <SheetContent className="w-full max-w-xl sm:max-w-xl overflow-y-auto">
           <SheetHeader>
-            <SheetTitle>
-              Version History — {historyTemplate?.name}
-            </SheetTitle>
+            <SheetTitle>Version History - {historyTemplate?.name}</SheetTitle>
           </SheetHeader>
           <div className="mt-6">
             {historyTemplate && (

src/components/admin/document-templates/template-preview.tsx

@@ -3,12 +3,7 @@
 import { useState } from 'react';
 import { Eye, ExternalLink } from 'lucide-react';
 import { Button } from '@/components/ui/button';
-import {
-  Dialog,
-  DialogContent,
-  DialogHeader,
-  DialogTitle,
-} from '@/components/ui/dialog';
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog';
 import { apiFetch } from '@/lib/api/client';
 import { TEMPLATE_VARIABLES } from '@/lib/pdf/tiptap-to-pdfme';
 
@@ -24,9 +19,7 @@ export function TemplatePreview({ content, templateName }: TemplatePreviewProps)
   const [error, setError] = useState<string | null>(null);
 
   // Build sample data from TEMPLATE_VARIABLES examples
-  const sampleData = Object.fromEntries(
-    TEMPLATE_VARIABLES.map((v) => [v.key, v.example]),
-  );
+  const sampleData = Object.fromEntries(TEMPLATE_VARIABLES.map((v) => [v.key, v.example]));
 
   async function handlePreview() {
     if (!content) {
@@ -74,14 +67,9 @@ export function TemplatePreview({ content, templateName }: TemplatePreviewProps)
         <DialogContent className="max-w-4xl">
           <DialogHeader>
             <div className="flex items-center justify-between">
-              <DialogTitle>Preview — {templateName}</DialogTitle>
+              <DialogTitle>Preview - {templateName}</DialogTitle>
               {pdfBase64 && (
-                <Button
-                  variant="ghost"
-                  size="sm"
-                  onClick={handleOpenInNewTab}
-                  className="mr-6"
-                >
+                <Button variant="ghost" size="sm" onClick={handleOpenInNewTab} className="mr-6">
                   <ExternalLink className="mr-1.5 h-3.5 w-3.5" />
                   Open in new tab
                 </Button>
@@ -100,9 +88,7 @@ export function TemplatePreview({ content, templateName }: TemplatePreviewProps)
             )}
 
             {error && !loading && (
-              <div className="rounded bg-destructive/10 p-4 text-sm text-destructive">
-                {error}
-              </div>
+              <div className="rounded bg-destructive/10 p-4 text-sm text-destructive">{error}</div>
             )}
 
             {pdfBase64 && !loading && (

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/invitations/invitations-manager.tsx

@@ -117,7 +117,7 @@ export function InvitationsManager() {
               {invites.map((i) => (
                 <tr key={i.id} className="border-t">
                   <td className="px-3 py-2 font-medium">{i.email}</td>
-                  <td className="px-3 py-2 text-muted-foreground">{i.name ?? '—'}</td>
+                  <td className="px-3 py-2 text-muted-foreground">{i.name ?? '-'}</td>
                   <td className="px-3 py-2 text-muted-foreground">
                     {i.isSuperAdmin ? 'Super admin' : 'Standard user'}
                   </td>
@@ -163,7 +163,7 @@ export function InvitationsManager() {
                         )}
                       </div>
                     ) : (
-                      <span className="text-xs text-muted-foreground">—</span>
+                      <span className="text-xs text-muted-foreground">-</span>
                     )}
                   </td>
                 </tr>

src/components/admin/ocr-settings-form.tsx

@@ -160,7 +160,7 @@ function SettingsBlock({ scope, title, description, showUseGlobal }: SettingsBlo
                 Enable AI receipt parsing for this port
               </Label>
               <p className="text-xs text-muted-foreground">
-                Off by default. Receipts are read on-device using Tesseract.js — accurate enough for
+                Off by default. Receipts are read on-device using Tesseract.js - accurate enough for
                 most receipts and incurs no AI cost. Turning this on lets the configured provider
                 re-parse receipts server-side for higher accuracy on hard-to-read images.
               </p>
@@ -214,7 +214,7 @@ function SettingsBlock({ scope, title, description, showUseGlobal }: SettingsBlo
               id={`apiKey-${scope}`}
               type={showKey ? 'text' : 'password'}
               autoComplete="off"
-              placeholder={hasKey ? '•••••• (saved — leave blank to keep)' : 'sk-…'}
+              placeholder={hasKey ? '•••••• (saved - leave blank to keep)' : 'sk-…'}
               value={apiKey}
               onChange={(e) => {
                 setApiKey(e.target.value);

src/components/admin/queue-detail-table.tsx

@@ -33,7 +33,7 @@ const statusVariant: Record<JobStatus, 'default' | 'secondary' | 'destructive' |
 };
 
 function formatDate(ts: number | undefined): string {
-  if (!ts) return '—';
+  if (!ts) return '-';
   return new Date(ts).toLocaleString();
 }
 
@@ -42,7 +42,7 @@ function truncateId(id: string): string {
 }
 
 function truncateReason(reason: string | undefined): string {
-  if (!reason) return '—';
+  if (!reason) return '-';
   return reason.length > 80 ? `${reason.slice(0, 80)}…` : reason;
 }
 
@@ -184,7 +184,7 @@ export function QueueDetailTable({ queueName }: QueueDetailTableProps) {
       {totalPages > 1 && (
         <div className="flex items-center justify-between text-sm text-muted-foreground">
           <span>
-            {total} total jobs — page {page} of {totalPages}
+            {total} total jobs - page {page} of {totalPages}
           </span>
           <div className="flex gap-2">
             <Button

src/components/admin/roles/role-list.tsx

@@ -95,7 +95,7 @@ export function RoleList() {
       accessorKey: 'description',
       header: 'Description',
       cell: ({ row }) => (
-        <span className="text-muted-foreground text-sm">{row.original.description ?? '—'}</span>
+        <span className="text-muted-foreground text-sm">{row.original.description ?? '-'}</span>
       ),
     },
     {

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

@@ -241,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>
@@ -249,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) => ({
@@ -283,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>
@@ -291,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) => ({
@@ -353,7 +363,7 @@ export function SettingsManager() {
                         );
                         void saveSetting(setting.key, parsed);
                       } catch {
-                        // invalid JSON — do nothing
+                        // invalid JSON - do nothing
                       }
                     }}
                   >

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

@@ -108,7 +108,7 @@ export function UserCard({ user, onEdit, onRemove, isRemoving }: UserCardProps)
             <span aria-hidden className="block h-9 w-9 shrink-0" />
           </div>
 
-          {/* Email subtitle — only when display name is shown as title */}
+          {/* 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 />

src/components/admin/webhooks/webhook-delivery-log.tsx

@@ -87,13 +87,9 @@ export function WebhookDeliveryLog({ webhookId }: Props) {
             <TableRow key={d.id}>
               <TableCell className="font-mono text-xs">{d.eventType}</TableCell>
               <TableCell>
-                <Badge variant={STATUS_VARIANTS[d.status] ?? 'outline'}>
-                  {d.status}
-                </Badge>
-              </TableCell>
-              <TableCell className="text-sm">
-                {d.responseStatus ?? '—'}
+                <Badge variant={STATUS_VARIANTS[d.status] ?? 'outline'}>{d.status}</Badge>
               </TableCell>
+              <TableCell className="text-sm">{d.responseStatus ?? '-'}</TableCell>
               <TableCell className="text-sm">{d.attempt}</TableCell>
               <TableCell className="text-xs text-muted-foreground">
                 {d.deliveredAt

src/components/admin/website-analytics/umami-test-button.tsx

@@ -0,0 +1,67 @@
+'use client';
+
+import { useState } from 'react';
+import { Loader2, CheckCircle2, XCircle } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { apiFetch } from '@/lib/api/client';
+
+interface TestResponse {
+  ok: boolean;
+  visitors?: number;
+  error?: string;
+}
+
+/**
+ * Hits POST /api/v1/admin/umami/test which calls Umami's `/api/websites/:id/
+ * active` to verify auth + websiteId in one request. On success, shows the
+ * live visitor count as proof we got real data back.
+ */
+export function UmamiTestButton() {
+  const [pending, setPending] = useState(false);
+  const [result, setResult] = useState<TestResponse | null>(null);
+
+  async function runTest() {
+    setPending(true);
+    setResult(null);
+    try {
+      const res = await apiFetch<{ data: TestResponse }>('/api/v1/admin/umami/test', {
+        method: 'POST',
+      });
+      setResult(res.data);
+      if (res.data.ok) {
+        toast.success(`Umami reachable - ${res.data.visitors ?? 0} active visitor(s) right now`);
+      } else {
+        toast.error(res.data.error ?? 'Umami test failed');
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Test failed';
+      setResult({ ok: false, error: message });
+      toast.error(message);
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <div className="flex items-center gap-3">
+      {result &&
+        (result.ok ? (
+          <span className="flex items-center text-xs text-green-600">
+            <CheckCircle2 className="mr-1 h-3.5 w-3.5" />
+            Connected ({result.visitors ?? 0} active)
+          </span>
+        ) : (
+          <span className="flex items-center text-xs text-destructive">
+            <XCircle className="mr-1 h-3.5 w-3.5" />
+            {result.error ?? 'Failed'}
+          </span>
+        ))}
+      <Button type="button" size="sm" variant="outline" onClick={runTest} disabled={pending}>
+        {pending ? <Loader2 className="mr-2 h-3.5 w-3.5 animate-spin" /> : null}
+        Test connection
+      </Button>
+    </div>
+  );
+}

src/components/alerts/alert-bell.tsx

@@ -16,8 +16,8 @@ import { useAlertCount, useAlertList, useAlertRealtime } from './use-alerts';
 export function AlertBell() {
   const portSlug = useUIStore((s) => s.currentPortSlug);
   const [open, setOpen] = useState(false);
-  // Count is cheap (one aggregate query) — fire on every page so the badge stays live.
-  // List is heavier — only fetch when the popover is actually open.
+  // Count is cheap (one aggregate query) - fire on every page so the badge stays live.
+  // List is heavier - only fetch when the popover is actually open.
   const { data: count } = useAlertCount();
   const { data: list, isLoading } = useAlertList('open', open);
   useAlertRealtime();

src/components/alerts/alert-rail.tsx

@@ -22,11 +22,10 @@ export function AlertRail() {
     <section
       data-testid="alert-rail"
       aria-label="Active alerts"
-      // `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"
+      // Natural height - the parent aside no longer forces 100% of the
+      // dashboard grid row, so the rail can sit compactly under Reminders
+      // without bleeding down into the Recent Activity panel below.
+      className="flex flex-col gap-3"
     >
       <div className="flex items-baseline justify-between">
         <h2 className="text-sm font-semibold tracking-tight">Alerts</h2>
@@ -57,7 +56,7 @@ export function AlertRail() {
               href={portSlug ? (`/${portSlug}/alerts` as never) : ('/alerts' as never)}
               className="block rounded-lg border border-dashed border-border px-3 py-2 text-center text-xs text-muted-foreground transition-colors hover:bg-accent"
             >
-              +{overflow} more — view all
+              +{overflow} more - view all
             </Link>
           ) : null}
         </div>

src/components/berths/berth-columns.tsx

@@ -56,7 +56,12 @@ function ActionsCell({ row }: { row: { original: BerthRow } }) {
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
-        <Button variant="ghost" size="icon" className="h-8 w-8" onClick={(e) => e.stopPropagation()}>
+        <Button
+          variant="ghost"
+          size="icon"
+          className="h-8 w-8"
+          onClick={(e) => e.stopPropagation()}
+        >
           <MoreHorizontal className="h-4 w-4" />
           <span className="sr-only">Open menu</span>
         </Button>
@@ -89,14 +94,12 @@ export const berthColumns: ColumnDef<BerthRow, unknown>[] = [
   {
     accessorKey: 'mooringNumber',
     header: 'Mooring #',
-    cell: ({ row }) => (
-      <span className="font-medium">{row.original.mooringNumber}</span>
-    ),
+    cell: ({ row }) => <span className="font-medium">{row.original.mooringNumber}</span>,
   },
   {
     accessorKey: 'area',
     header: 'Area',
-    cell: ({ row }) => row.original.area ?? '—',
+    cell: ({ row }) => row.original.area ?? '-',
   },
   {
     accessorKey: 'status',
@@ -109,7 +112,7 @@ export const berthColumns: ColumnDef<BerthRow, unknown>[] = [
     enableSorting: false,
     cell: ({ row }) => {
       const { lengthM, widthM } = row.original;
-      if (!lengthM && !widthM) return '—';
+      if (!lengthM && !widthM) return '-';
       return `${lengthM ?? '?'}m × ${widthM ?? '?'}m`;
     },
   },
@@ -118,7 +121,7 @@ export const berthColumns: ColumnDef<BerthRow, unknown>[] = [
     header: 'Price',
     cell: ({ row }) => {
       const { price, priceCurrency } = row.original;
-      if (!price) return '—';
+      if (!price) return '-';
       return new Intl.NumberFormat('en-US', {
         style: 'currency',
         currency: priceCurrency || 'USD',
@@ -129,8 +132,7 @@ export const berthColumns: ColumnDef<BerthRow, unknown>[] = [
   {
     accessorKey: 'tenureType',
     header: 'Tenure',
-    cell: ({ row }) =>
-      row.original.tenureType === 'permanent' ? 'Permanent' : 'Fixed Term',
+    cell: ({ row }) => (row.original.tenureType === 'permanent' ? 'Permanent' : 'Fixed Term'),
   },
   {
     id: 'tags',

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,7 +178,10 @@ 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="hidden sm:block text-2xl font-bold text-foreground">
@@ -182,7 +196,7 @@ export function BerthDetailHeader({ berth }: BerthDetailHeaderProps) {
             {berth.area && <p className="text-muted-foreground mt-1">{berth.area}</p>}
           </div>
 
-          <div className="flex flex-wrap 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-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-interests-tab.tsx

@@ -168,7 +168,7 @@ export function BerthInterestsTab({ berthId }: BerthInterestsTabProps) {
                     href={`/${portSlug}/interests/${i.id}` as never}
                     className="hover:text-brand"
                   >
-                    {i.clientName ?? '—'}
+                    {i.clientName ?? '-'}
                   </Link>
                 </td>
                 <td className="px-3 py-2">
@@ -177,10 +177,10 @@ export function BerthInterestsTab({ berthId }: BerthInterestsTabProps) {
                   </Badge>
                 </td>
                 <td className="px-3 py-2 text-muted-foreground">
-                  {i.leadCategory ? (CATEGORY_LABELS[i.leadCategory] ?? i.leadCategory) : '—'}
+                  {i.leadCategory ? (CATEGORY_LABELS[i.leadCategory] ?? i.leadCategory) : '-'}
                 </td>
                 <td className="px-3 py-2 text-muted-foreground">
-                  {i.source ? (SOURCE_LABELS[i.source] ?? i.source) : '—'}
+                  {i.source ? (SOURCE_LABELS[i.source] ?? i.source) : '-'}
                 </td>
                 <td className="px-3 py-2 text-xs text-muted-foreground">
                   {new Date(i.createdAt).toLocaleDateString()}

src/components/berths/berth-list.tsx

@@ -36,7 +36,7 @@ export function BerthList() {
         title="Berths"
         description="View and manage berth allocations"
         variant="gradient"
-        // No "New" button — berths are import-only
+        // No "New" button - berths are import-only
       />
 
       <div className="flex items-center gap-2 flex-wrap">

src/components/berths/berth-tabs.tsx

@@ -48,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',
@@ -74,7 +109,7 @@ function OverviewTab({ berth }: { berth: BerthData }) {
 
   return (
     <div className="space-y-6">
-      {/* Sales pulse — top-of-page so reps doing berth-level triage can see
+      {/* 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} />
 
@@ -97,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"
@@ -122,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} />

src/components/clients/client-columns.tsx

@@ -70,7 +70,7 @@ export function getClientColumns({
       enableSorting: false,
       cell: ({ row }) => {
         const primary = row.original.contacts?.find((c) => c.isPrimary);
-        if (!primary) return <span className="text-muted-foreground">—</span>;
+        if (!primary) return <span className="text-muted-foreground">-</span>;
         return (
           <span className="text-sm">
             <span className="text-muted-foreground capitalize">{primary.channel}: </span>
@@ -86,7 +86,7 @@ export function getClientColumns({
       cell: ({ getValue }) => {
         const iso = getValue() as string | null;
         return (
-          <span className="text-muted-foreground">{iso ? getCountryName(iso, 'en') : '—'}</span>
+          <span className="text-muted-foreground">{iso ? getCountryName(iso, 'en') : '-'}</span>
         );
       },
     },
@@ -96,7 +96,7 @@ export function getClientColumns({
       header: 'Source',
       cell: ({ getValue }) => {
         const source = getValue() as string | null;
-        if (!source) return <span className="text-muted-foreground">—</span>;
+        if (!source) return <span className="text-muted-foreground">-</span>;
         return (
           <Badge variant="outline" className="capitalize text-xs">
             {SOURCE_LABELS[source] ?? source}
@@ -111,7 +111,7 @@ export function getClientColumns({
       cell: ({ row }) => {
         const c = row.original.yachtCount ?? 0;
         return c === 0 ? (
-          <span className="text-muted-foreground">—</span>
+          <span className="text-muted-foreground">-</span>
         ) : (
           <Badge variant="secondary" className="text-xs">
             {c}
@@ -126,7 +126,7 @@ export function getClientColumns({
       cell: ({ row }) => {
         const c = row.original.companyCount ?? 0;
         return c === 0 ? (
-          <span className="text-muted-foreground">—</span>
+          <span className="text-muted-foreground">-</span>
         ) : (
           <Badge variant="secondary" className="text-xs">
             {c}
@@ -140,7 +140,7 @@ export function getClientColumns({
       enableSorting: false,
       cell: ({ row }) => {
         const clientTags = row.original.tags ?? [];
-        if (clientTags.length === 0) return <span className="text-muted-foreground">—</span>;
+        if (clientTags.length === 0) return <span className="text-muted-foreground">-</span>;
         return (
           <div className="flex flex-wrap gap-1">
             {clientTags.slice(0, 3).map((tag) => (

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

@@ -33,7 +33,7 @@ interface ClientCompaniesTabProps {
 
 function formatSince(startDate: string | Date): string {
   const d = typeof startDate === 'string' ? new Date(startDate) : startDate;
-  if (Number.isNaN(d.getTime())) return '—';
+  if (Number.isNaN(d.getTime())) return '-';
   return format(d, 'MMM d, yyyy');
 }
 
@@ -87,7 +87,7 @@ export function ClientCompaniesTab({ clientId: _clientId, companies }: ClientCom
                       Primary
                     </Badge>
                   ) : (
-                    <span className="text-muted-foreground">—</span>
+                    <span className="text-muted-foreground">-</span>
                   )}
                 </TableCell>
                 <TableCell className="text-muted-foreground text-sm">

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

@@ -169,7 +169,7 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
             )}
           </div>
 
-          {/* Top-right: archive/restore as a small icon button — destructive
+          {/* Top-right: archive/restore as a small icon button - destructive
               action sits out of the primary action flow. */}
           <button
             type="button"

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">

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

@@ -180,7 +180,7 @@ function InterestPreviewDrawer({
 }) {
   // 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
+  // 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);
@@ -243,7 +243,7 @@ function InterestPreviewDrawer({
         </DrawerHeader>
 
         <div className="space-y-5 overflow-y-auto px-4 pb-4">
-          {/* Pipeline-stepper segmented bar — the same primitive used on the
+          {/* Pipeline-stepper segmented bar - the same primitive used on the
               row card, so the at-a-glance progress hint is consistent
               across surfaces. */}
           {stage ? (
@@ -255,7 +255,7 @@ function InterestPreviewDrawer({
             </div>
           ) : null}
 
-          {/* Milestones — three sections matching the full interest detail
+          {/* 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
@@ -308,7 +308,7 @@ function InterestPreviewDrawer({
             </div>
           </section>
 
-          {/* Compact key/value pairs — lead category, source, last contact,
+          {/* 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. */}

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

@@ -106,8 +106,8 @@ function lastActivityLabel(interests: ClientInterestRow[]): string | null {
 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.
+   * `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';
 }

src/components/clients/client-tabs.tsx

@@ -116,6 +116,8 @@ interface ClientTabsOptions {
       tenureType: string;
       status: string;
     }>;
+    interestCount?: number;
+    noteCount?: number;
     tags?: Array<{ id: string; name: string; color: string }>;
   };
 }
@@ -224,6 +226,7 @@ export function getClientTabs({ clientId, currentUserId, client }: ClientTabsOpt
     {
       id: 'interests',
       label: 'Interests',
+      badge: client.interestCount,
       content: <ClientInterestsTab clientId={clientId} />,
     },
     {
@@ -261,6 +264,7 @@ export function getClientTabs({ clientId, currentUserId, client }: ClientTabsOpt
     {
       id: 'notes',
       label: 'Notes',
+      badge: client.noteCount,
       content: <NotesList entityType="clients" entityId={clientId} currentUserId={currentUserId} />,
     },
     {

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

@@ -74,9 +74,9 @@ export function ClientYachtsTab({ clientId: _clientId, yachts }: ClientYachtsTab
                     </Link>
                   </TableCell>
                   <TableCell>
-                    {y.lengthFt && y.widthFt ? `${y.lengthFt} × ${y.widthFt} ft` : '—'}
+                    {y.lengthFt && y.widthFt ? `${y.lengthFt} × ${y.widthFt} ft` : '-'}
                   </TableCell>
-                  <TableCell>{y.hullNumber ?? '—'}</TableCell>
+                  <TableCell>{y.hullNumber ?? '-'}</TableCell>
                   <TableCell className="capitalize">{y.status.replace('_', ' ')}</TableCell>
                 </TableRow>
               ))}

src/components/clients/contacts-editor.tsx

@@ -223,14 +223,27 @@ function ContactRow({
         </div>
       </div>
 
-      {/* Bottom / right: tag + actions. Hidden while the phone editor is active
-          to keep focus on the form — no chips fighting for space, no noise. */}
+      {/* 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…"
@@ -251,12 +264,13 @@ function ContactRow({
               >
                 <Star className={cn('h-3.5 w-3.5', contact.isPrimary && 'fill-current')} />
               </button>
+            </>
+          ) : null}
 
           <button
             type="button"
             onClick={onRemove}
             title="Remove"
-            // Trash is opacity-0 on desktop hover-only; on touch, always show.
             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" />

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/gdpr-export-button.tsx

@@ -74,7 +74,7 @@ export function GdprExportButton({ clientId }: { clientId: string }) {
         },
       }),
     onSuccess: () => {
-      toast.success('Export queued — refresh in ~30 seconds');
+      toast.success('Export queued - refresh in ~30 seconds');
       qc.invalidateQueries({ queryKey });
       setEmailOverride('');
     },
@@ -128,7 +128,7 @@ export function GdprExportButton({ clientId }: { clientId: string }) {
                 Email the bundle when ready
               </Label>
               <p className="text-xs text-muted-foreground">
-                Sends a 7-day signed download link to the client&apos;s primary email — or to the
+                Sends a 7-day signed download link to the client&apos;s primary email - or to the
                 override below.
               </p>
               {emailToClient ? (

src/components/companies/add-membership-dialog.tsx

@@ -122,7 +122,7 @@ export function AddMembershipDialog({ open, onOpenChange, companyId }: AddMember
     },
     onError: (err: unknown) => {
       let msg = err instanceof Error ? err.message : 'Failed to add membership';
-      // Detect 409 — service returns a "membership already exists" message
+      // Detect 409 - service returns a "membership already exists" message
       if (/already exists/i.test(msg)) {
         msg = 'This membership already exists (same client + role + start date).';
       }

src/components/companies/company-columns.tsx

@@ -76,7 +76,7 @@ export function getCompanyColumns({
       enableSorting: false,
       cell: ({ getValue }) => {
         const value = getValue() as string | null;
-        if (!value) return <span className="text-muted-foreground">—</span>;
+        if (!value) return <span className="text-muted-foreground">-</span>;
         return <span className="text-sm">{value}</span>;
       },
     },
@@ -87,7 +87,7 @@ export function getCompanyColumns({
       enableSorting: false,
       cell: ({ getValue }) => {
         const value = getValue() as string | null;
-        if (!value) return <span className="text-muted-foreground">—</span>;
+        if (!value) return <span className="text-muted-foreground">-</span>;
         return <span className="text-sm">{value}</span>;
       },
     },
@@ -98,7 +98,7 @@ export function getCompanyColumns({
       size: 88,
       cell: ({ row }) => {
         const n = row.original.memberCount ?? 0;
-        if (n === 0) return <span className="text-muted-foreground">—</span>;
+        if (n === 0) return <span className="text-muted-foreground">-</span>;
         return <Badge variant="secondary">{n}</Badge>;
       },
     },
@@ -109,7 +109,7 @@ export function getCompanyColumns({
       size: 88,
       cell: ({ row }) => {
         const n = row.original.yachtCount ?? 0;
-        if (n === 0) return <span className="text-muted-foreground">—</span>;
+        if (n === 0) return <span className="text-muted-foreground">-</span>;
         return <Badge variant="secondary">{n}</Badge>;
       },
     },

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

@@ -77,7 +77,9 @@ 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="hidden sm:block text-2xl font-bold text-foreground truncate">

src/components/companies/company-form.tsx

@@ -101,7 +101,7 @@ export function CompanyForm({ open, onOpenChange, company }: CompanyFormProps) {
   const mutation = useMutation({
     mutationFn: async (data: CreateCompanyInput) => {
       if (isEdit) {
-        // updateCompanySchema omits tagIds — strip them from PATCH body.
+        // updateCompanySchema omits tagIds - strip them from PATCH body.
         const { tagIds: _tIds, ...rest } = data;
         void _tIds;
         await apiFetch(`/api/v1/companies/${company!.id}`, {
@@ -178,7 +178,7 @@ export function CompanyForm({ open, onOpenChange, company }: CompanyFormProps) {
                   value={watch('incorporationCountryIso')}
                   onChange={(iso) => {
                     setValue('incorporationCountryIso', iso ?? undefined);
-                    // Wipe subdivision when country flips — codes are country-scoped.
+                    // Wipe subdivision when country flips - codes are country-scoped.
                     setValue('incorporationSubdivisionIso', undefined);
                   }}
                   data-testid="company-incorp-country"

src/components/companies/company-members-tab.tsx

@@ -56,7 +56,7 @@ const ROLE_LABELS: Record<string, string> = {
 };
 
 function formatDate(value: string | null): string {
-  if (!value) return '—';
+  if (!value) return '-';
   const date = new Date(value);
   if (Number.isNaN(date.getTime())) return value;
   return date.toLocaleDateString();
@@ -201,14 +201,14 @@ export function CompanyMembersTab({ companyId, portSlug }: CompanyMembersTabProp
                     </TableCell>
                     <TableCell>{ROLE_LABELS[m.role] ?? m.role}</TableCell>
                     <TableCell className="text-sm text-muted-foreground max-w-[240px] truncate">
-                      {m.roleDetail ?? '—'}
+                      {m.roleDetail ?? '-'}
                     </TableCell>
                     <TableCell>{formatDate(m.startDate)}</TableCell>
                     <TableCell>
                       {m.endDate ? (
                         formatDate(m.endDate)
                       ) : (
-                        <span className="text-muted-foreground">—</span>
+                        <span className="text-muted-foreground">-</span>
                       )}
                     </TableCell>
                     <TableCell>
@@ -217,7 +217,7 @@ export function CompanyMembersTab({ companyId, portSlug }: CompanyMembersTabProp
                           Primary
                         </Badge>
                       ) : (
-                        <span className="text-muted-foreground">—</span>
+                        <span className="text-muted-foreground">-</span>
                       )}
                     </TableCell>
                     <TableCell>

src/components/companies/company-owned-yachts-tab.tsx

@@ -49,13 +49,13 @@ const STATUS_LABELS: Record<string, string> = {
 
 function formatDimensions(y: OwnedYachtRow): string | null {
   if (y.lengthFt || y.widthFt) {
-    const length = y.lengthFt ?? '—';
-    const width = y.widthFt ?? '—';
+    const length = y.lengthFt ?? '-';
+    const width = y.widthFt ?? '-';
     return `${length} × ${width} ft`;
   }
   if (y.lengthM || y.widthM) {
-    const length = y.lengthM ?? '—';
-    const width = y.widthM ?? '—';
+    const length = y.lengthM ?? '-';
+    const width = y.widthM ?? '-';
     return `${length} × ${width} m`;
   }
   return null;
@@ -129,14 +129,14 @@ export function CompanyOwnedYachtsTab({ companyId, portSlug }: CompanyOwnedYacht
                   {dims ? (
                     <span className="text-sm">{dims}</span>
                   ) : (
-                    <span className="text-muted-foreground">—</span>
+                    <span className="text-muted-foreground">-</span>
                   )}
                 </TableCell>
                 <TableCell>
                   {y.hullNumber ? (
                     <span className="text-sm">{y.hullNumber}</span>
                   ) : (
-                    <span className="text-muted-foreground">—</span>
+                    <span className="text-muted-foreground">-</span>
                   )}
                 </TableCell>
                 <TableCell>

src/components/companies/company-tabs.tsx

@@ -125,7 +125,7 @@ function OverviewTab({ companyId, company }: { companyId: string; company: Compa
             <InlineCountryField
               value={company.incorporationCountryIso}
               onSave={async (iso) => {
-                // Wipe subdivision when country flips — codes are country-scoped.
+                // Wipe subdivision when country flips - codes are country-scoped.
                 await mutation.mutateAsync({
                   incorporationCountryIso: iso,
                   incorporationSubdivisionIso: null,
@@ -146,7 +146,11 @@ function OverviewTab({ companyId, company }: { companyId: string; company: Compa
           </EditableRow>
           <EditableRow label="Incorporation Date">
             <InlineEditableField
-              value={company.incorporationDate}
+              // The API returns this as an ISO timestamp ("2019-03-14T00:00:00.000Z")
+              // because Postgres `date` columns are serialized through JSON. Strip
+              // the time portion so the read-only state shows just YYYY-MM-DD,
+              // which is also the format the user types when editing.
+              value={company.incorporationDate ? company.incorporationDate.slice(0, 10) : null}
               placeholder="YYYY-MM-DD"
               onSave={save('incorporationDate')}
             />
@@ -171,7 +175,7 @@ function OverviewTab({ companyId, company }: { companyId: string; company: Compa
           variant="textarea"
           value={company.notes}
           onSave={save('notes')}
-          emptyText="No notes — click to add"
+          emptyText="No notes - click to add"
         />
       </div>
 

src/components/dashboard/activity-feed.tsx

@@ -58,7 +58,7 @@ function ActivityFeedInner() {
       <CardContent>
         {items.length === 0 ? (
           <p className="text-sm text-muted-foreground">
-            No recent activity yet — your team&apos;s actions (interests created, stages changed,
+            No recent activity yet - your team&apos;s actions (interests created, stages changed,
             invoices sent) will appear here.
           </p>
         ) : (

src/components/dashboard/dashboard-shell.tsx

@@ -3,6 +3,7 @@
 import { useState } from 'react';
 
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { usePortContext } from '@/providers/port-provider';
 import { PageHeader } from '@/components/shared/page-header';
 import { KpiCardsWithBoundary } from './kpi-cards';
 import { ActivityFeed } from './activity-feed';
@@ -12,29 +13,53 @@ import { OccupancyTimelineChart } from './occupancy-timeline-chart';
 import { RevenueBreakdownChart } from './revenue-breakdown-chart';
 import { LeadSourceChart } from './lead-source-chart';
 import { MyRemindersRail } from './my-reminders-rail';
+import { WebsiteGlanceTile } from './website-glance-tile';
 import { WidgetErrorBoundary } from './widget-error-boundary';
 import { AlertRail } from '@/components/alerts/alert-rail';
-import type { DateRange } from '@/lib/services/analytics.service';
+import { isCustomRange, type DateRange } from '@/lib/analytics/range';
 
-const RANGE_LABELS: Record<DateRange, string> = {
+const PRESET_LABELS: Record<'today' | '7d' | '30d' | '90d', string> = {
   today: 'Today',
   '7d': 'Last 7 days',
   '30d': 'Last 30 days',
   '90d': 'Last 90 days',
 };
 
+function rangeLabel(range: DateRange): string {
+  if (isCustomRange(range)) {
+    const fmt: Intl.DateTimeFormatOptions = {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric',
+      timeZone: 'UTC',
+    };
+    const from = new Date(`${range.from}T00:00:00.000Z`).toLocaleDateString('en-US', fmt);
+    const to = new Date(`${range.to}T00:00:00.000Z`).toLocaleDateString('en-US', fmt);
+    return `${from} – ${to}`;
+  }
+  return PRESET_LABELS[range];
+}
+
 export function DashboardShell() {
   const [range, setRange] = useState<DateRange>('30d');
+  const { currentPort } = usePortContext();
+  const portName = currentPort?.name ?? 'this port';
 
+  // Use a partial query-key prefix (no range segment) for invalidations.
+  // Reading: "any cached analytics result, regardless of range, please
+  // refetch on this event." This avoids any chance that a custom-range
+  // object literal hashes differently than the one stored in the cache,
+  // and keeps the invalidation surface broad enough to refresh whichever
+  // range the user is currently looking at.
   useRealtimeInvalidation({
     'interest:stageChanged': [
-      ['analytics', 'pipeline_funnel', range],
-      ['analytics', 'lead_source_attribution', range],
+      ['analytics', 'pipeline_funnel'],
+      ['analytics', 'lead_source_attribution'],
       ['dashboard', 'kpis'],
     ],
     'client:created': [['dashboard', 'kpis']],
     'berth:statusChanged': [
-      ['analytics', 'occupancy_timeline', range],
+      ['analytics', 'occupancy_timeline'],
       ['dashboard', 'kpis'],
     ],
   });
@@ -44,8 +69,8 @@ export function DashboardShell() {
       <PageHeader
         title="Dashboard"
         eyebrow="Overview"
-        description="Live snapshot of your marina activity"
-        kpiLine={<span>{RANGE_LABELS[range]}</span>}
+        description={`Live snapshot of ${portName} activity`}
+        kpiLine={<span>{rangeLabel(range)}</span>}
         variant="gradient"
         actions={<DateRangePicker value={range} onChange={setRange} />}
       />
@@ -54,7 +79,12 @@ export function DashboardShell() {
         <KpiCardsWithBoundary />
       </div>
 
-      <div className="grid gap-4 grid-cols-1 xl:grid-cols-[minmax(0,1fr)_320px]">
+      {/* `items-start` is critical: without it, the right-column aside is
+          stretched to match the chart column's row height, which forces
+          MyRemindersRail (or any other child with `h-full`) to push later
+          children out of the aside's box and into the rows below where
+          ActivityFeed renders. */}
+      <div className="grid gap-4 grid-cols-1 items-start xl:grid-cols-[minmax(0,1fr)_320px]">
         <div className="grid gap-4 grid-cols-1 lg:grid-cols-2">
           <WidgetErrorBoundary>
             <PipelineFunnelChart range={range} />
@@ -70,6 +100,11 @@ export function DashboardShell() {
           </WidgetErrorBoundary>
         </div>
         <aside className="min-w-0 space-y-4">
+          {/* Soft-fail tile linking to /website-analytics. Hidden if Umami
+              isn't configured for this port. */}
+          <WidgetErrorBoundary>
+            <WebsiteGlanceTile />
+          </WidgetErrorBoundary>
           <WidgetErrorBoundary>
             <MyRemindersRail />
           </WidgetErrorBoundary>

src/components/dashboard/date-range-picker.tsx

@@ -1,8 +1,12 @@
 'use client';
 
+import { useState } from 'react';
+import { Calendar } from 'lucide-react';
+
 import { Button } from '@/components/ui/button';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
 import { cn } from '@/lib/utils';
-import type { DateRange } from '@/lib/services/analytics.service';
+import { isCustomRange, type DateRange } from '@/lib/analytics/range';
 
 interface DateRangePickerProps {
   value: DateRange;
@@ -10,14 +14,64 @@ interface DateRangePickerProps {
   className?: string;
 }
 
-const OPTIONS: Array<{ value: DateRange; label: string }> = [
+const PRESETS: Array<{ value: 'today' | '7d' | '30d' | '90d'; label: string }> = [
   { value: 'today', label: 'Today' },
   { value: '7d', label: '7d' },
   { value: '30d', label: '30d' },
   { value: '90d', label: '90d' },
 ];
 
+/**
+ * Format a custom range as a compact button label, e.g. "Apr 14 – May 4".
+ * Same year omits the year on both sides; different years includes both.
+ */
+function formatCustom(range: { from: string; to: string }): string {
+  const from = new Date(`${range.from}T00:00:00.000Z`);
+  const to = new Date(`${range.to}T00:00:00.000Z`);
+  const sameYear = from.getUTCFullYear() === to.getUTCFullYear();
+  const fmt: Intl.DateTimeFormatOptions = sameYear
+    ? { month: 'short', day: 'numeric', timeZone: 'UTC' }
+    : { month: 'short', day: 'numeric', year: 'numeric', timeZone: 'UTC' };
+  return `${from.toLocaleDateString('en-US', fmt)} – ${to.toLocaleDateString('en-US', fmt)}`;
+}
+
+/**
+ * Today's date as a YYYY-MM-DD string in UTC. Used as the default for the
+ * "to" picker so users can't accidentally pick a future date by leaving the
+ * field empty.
+ */
+function todayIso(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
 export function DateRangePicker({ value, onChange, className }: DateRangePickerProps) {
+  const [open, setOpen] = useState(false);
+  const isCustom = isCustomRange(value);
+
+  // Local state for the popover form. Seeded from the current value if it's
+  // already custom, otherwise defaults to a 14-day window ending today.
+  const [draftFrom, setDraftFrom] = useState<string>(() => {
+    if (isCustom) return value.from;
+    const d = new Date();
+    d.setUTCDate(d.getUTCDate() - 14);
+    return d.toISOString().slice(0, 10);
+  });
+  const [draftTo, setDraftTo] = useState<string>(() => (isCustom ? value.to : todayIso()));
+
+  const today = todayIso();
+  const draftValid =
+    draftFrom !== '' &&
+    draftTo !== '' &&
+    draftFrom <= draftTo &&
+    draftFrom <= today &&
+    draftTo <= today;
+
+  function applyCustom() {
+    if (!draftValid) return;
+    onChange({ kind: 'custom', from: draftFrom, to: draftTo });
+    setOpen(false);
+  }
+
   return (
     <div
       role="tablist"
@@ -27,8 +81,8 @@ export function DateRangePicker({ value, onChange, className }: DateRangePickerP
         className,
       )}
     >
-      {OPTIONS.map((opt) => {
-        const active = opt.value === value;
+      {PRESETS.map((opt) => {
+        const active = !isCustom && opt.value === value;
         return (
           <Button
             key={opt.value}
@@ -50,6 +104,68 @@ export function DateRangePicker({ value, onChange, className }: DateRangePickerP
           </Button>
         );
       })}
+
+      {/* Custom range - popover with two date inputs and an Apply button */}
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button
+            type="button"
+            role="tab"
+            aria-selected={isCustom}
+            variant="ghost"
+            size="sm"
+            className={cn(
+              'h-7 px-3 text-xs font-medium transition-all duration-base ease-spring inline-flex items-center gap-1',
+              isCustom
+                ? 'bg-background text-foreground shadow-sm'
+                : 'text-muted-foreground hover:text-foreground',
+            )}
+            data-testid="range-custom"
+          >
+            <Calendar className="h-3 w-3" aria-hidden />
+            {isCustom ? formatCustom(value) : 'Custom'}
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent align="end" className="w-[260px] p-3">
+          <div className="space-y-3">
+            <div className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+              Custom range
+            </div>
+            <label className="block text-xs">
+              <span className="block text-muted-foreground mb-1">From</span>
+              <input
+                type="date"
+                value={draftFrom}
+                /* `max` capped at min(draftTo, today). Without the today
+                   cap, users could pick a future From, end up with an
+                   empty result, and not understand why. */
+                max={draftTo && draftTo < today ? draftTo : today}
+                onChange={(e) => setDraftFrom(e.target.value)}
+                className="w-full rounded-md border border-input bg-background px-2 py-1.5 text-sm outline-none focus:border-brand/60 focus:ring-2 focus:ring-brand/15"
+              />
+            </label>
+            <label className="block text-xs">
+              <span className="block text-muted-foreground mb-1">To</span>
+              <input
+                type="date"
+                value={draftTo}
+                min={draftFrom || undefined}
+                max={today}
+                onChange={(e) => setDraftTo(e.target.value)}
+                className="w-full rounded-md border border-input bg-background px-2 py-1.5 text-sm outline-none focus:border-brand/60 focus:ring-2 focus:ring-brand/15"
+              />
+            </label>
+            <div className="flex items-center justify-end gap-2 pt-1">
+              <Button variant="ghost" size="sm" onClick={() => setOpen(false)}>
+                Cancel
+              </Button>
+              <Button size="sm" onClick={applyCustom} disabled={!draftValid}>
+                Apply
+              </Button>
+            </div>
+          </div>
+        </PopoverContent>
+      </Popover>
     </div>
   );
 }

src/components/dashboard/kpi-cards.tsx

@@ -3,6 +3,7 @@
 import { useQuery } from '@tanstack/react-query';
 
 import { apiFetch } from '@/lib/api/client';
+import { useUIStore } from '@/stores/ui-store';
 import { KPITile } from '@/components/ui/kpi-tile';
 import { Skeleton } from '@/components/ui/skeleton';
 import { WidgetErrorBoundary } from './widget-error-boundary';
@@ -37,11 +38,19 @@ function KpiTileSkeleton() {
 }
 
 export function KpiCards() {
+  // Keying on currentPortId ensures React Query treats a port-resolved fetch
+  // as a different query than the one that fires on first paint when the
+  // store hasn't yet hydrated. Without this, an early null-port fetch could
+  // cache an error and display "-" indefinitely until the staleTime expires.
+  const portId = useUIStore((s) => s.currentPortId);
   const { data, isLoading, isError } = useQuery<KpiData>({
-    queryKey: ['dashboard', 'kpis'],
+    queryKey: ['dashboard', 'kpis', portId],
     queryFn: () => apiFetch<KpiData>('/api/v1/dashboard/kpis'),
     staleTime: 60_000,
     retry: 2,
+    // Avoid running until we have a port id - gates against the early
+    // unauth/no-port window where the API would return zeroes/errors.
+    enabled: !!portId,
   });
 
   if (isLoading) {
@@ -62,22 +71,22 @@ export function KpiCards() {
   }> = [
     {
       label: 'Total Clients',
-      value: isError ? '—' : String(data?.totalClients ?? 0),
+      value: isError ? '-' : String(data?.totalClients ?? 0),
       accent: 'brand',
     },
     {
       label: 'Active Interests',
-      value: isError ? '—' : String(data?.activeInterests ?? 0),
+      value: isError ? '-' : String(data?.activeInterests ?? 0),
       accent: 'teal',
     },
     {
       label: 'Pipeline Value',
-      value: isError ? '—' : formatCurrency(data?.pipelineValueUsd ?? 0),
+      value: isError ? '-' : formatCurrency(data?.pipelineValueUsd ?? 0),
       accent: 'success',
     },
     {
       label: 'Occupancy Rate',
-      value: isError ? '—' : formatPercent(data?.occupancyRate ?? 0),
+      value: isError ? '-' : formatPercent(data?.occupancyRate ?? 0),
       accent: 'purple',
     },
   ];