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

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

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

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

.claude/scheduled_tasks.lock

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

.gitignore

@@ -20,10 +20,30 @@ tsconfig.tsbuildinfo
 docker-compose.override.yml
 .remember/
 .DS_Store
-eoi/
+# Root-only ad-hoc EOI scratch dir; routes under src/app/.../eoi/ must NOT match.
+/eoi/
 
 # Brainstorming companion mockup files
 .superpowers/
 
 # Ad-hoc screenshots / scratch artifacts at repo root
 /*.png
+/*.jpg
+
+# Legacy Nuxt portal — kept on disk for reference, not tracked here
+/client-portal/
+
+# Sister marketing site — separate Nuxt project, not part of CRM tracking
+/website/
+
+# Mobile audit screenshots — generated locally, regenerable
+/.audit/
+/.audit-screenshots/
+
+# Migration script output (CSV reports, transcripts)
+.migration/
+
+# Tool caches / runtime state
+/.claude/
+/.serena/
+/ruvector.db

docs/operations/outbound-comms-safety.md

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

docs/runbooks/backup-and-restore.md

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

docs/runbooks/email-deliverability.md

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

docs/runbooks/permission-audit.md

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

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

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

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

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

docs/superpowers/specs/2026-05-03-dedup-and-migration-design.md

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

package.json

@@ -52,6 +52,7 @@
     "@tanstack/react-query": "^5.62.0",
     "@tanstack/react-query-devtools": "^5.62.0",
     "@tanstack/react-table": "^8.21.3",
+    "archiver": "^7.0.1",
     "better-auth": "^1.2.0",
     "bullmq": "^5.25.0",
     "class-variance-authority": "^0.7.0",
@@ -61,7 +62,9 @@
     "drizzle-orm": "^0.38.0",
     "imapflow": "^1.2.13",
     "ioredis": "^5.4.0",
+    "iso-3166-2": "^1.0.0",
     "jose": "^6.2.1",
+    "libphonenumber-js": "^1.12.42",
     "lucide-react": "^0.460.0",
     "mailparser": "^3.9.4",
     "minio": "^8.0.0",
@@ -83,12 +86,16 @@
     "sonner": "^1.7.0",
     "tailwind-merge": "^2.6.0",
     "tailwindcss-animate": "^1.0.7",
+    "tesseract.js": "^7.0.0",
+    "vaul": "^1.1.2",
     "zod": "^3.24.0",
     "zustand": "^5.0.0"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.5",
     "@playwright/test": "^1.58.2",
+    "@types/archiver": "^7.0.0",
+    "@types/iso-3166-2": "^1.0.4",
     "@types/mailparser": "^3.4.6",
     "@types/node": "^22.0.0",
     "@types/nodemailer": "^6.4.0",
@@ -106,6 +113,7 @@
     "lint-staged": "^15.2.0",
     "postcss": "^8.4.0",
     "prettier": "^3.4.0",
+    "react-grab": "^0.1.32",
     "tailwindcss": "^3.4.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",

playwright.config.ts

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

scripts/audit-permissions.ts

@@ -0,0 +1,188 @@
+/**
+ * Permission-matrix audit.
+ *
+ * Walks every src/app/api/v1/** /route.ts file and reports each exported HTTP
+ * handler (GET/POST/PUT/PATCH/DELETE) that is *not* wrapped in withPermission().
+ * Internal v1 routes should be permission-gated; routes that intentionally use
+ * withAuth() alone (e.g. user-self endpoints) can be allow-listed below.
+ *
+ * Run:
+ *   pnpm tsx scripts/audit-permissions.ts
+ *
+ * Exit code:
+ *   0 — every handler is permission-gated or in the allow-list
+ *   1 — at least one handler is missing both a withPermission wrapper and an
+ *       allow-list entry. CI should fail.
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+const ROOT = join(process.cwd(), 'src/app/api/v1');
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const;
+
+/**
+ * Routes intentionally exempt from withPermission. Each entry should explain
+ * why — typically because the route operates on the caller's own resources
+ * (no port-level permission semantics) or is admin-only and gated by
+ * isSuperAdmin inside the handler.
+ */
+const ALLOW_LIST: ReadonlyArray<{ pattern: RegExp; reason: string }> = [
+  // Self / admin / public
+  { pattern: /\/me\/route\.ts$/, reason: 'Self-endpoint — auth is sufficient.' },
+  { pattern: /\/admin\//, reason: 'Admin-only — gated by isSuperAdmin inside handler.' },
+  {
+    pattern: /\/notifications\//,
+    reason: 'User-scoped notifications — caller is the resource owner.',
+  },
+  { pattern: /\/socket\//, reason: 'Socket auth handshake.' },
+  { pattern: /\/health\//, reason: 'Public health check.' },
+  { pattern: /\/users\/me\//, reason: 'User-self preferences — caller is the resource owner.' },
+  { pattern: /\/saved-views\//, reason: 'User-self saved views — caller is the resource owner.' },
+  {
+    pattern: /\/settings\/feature-flag\//,
+    reason: 'Public read of feature-flag bool — no PII; auth is sufficient.',
+  },
+  // Cross-cutting / port-scoped reference data
+  { pattern: /\/tags\//, reason: 'Tags are cross-cutting reference data; port-scoped via auth.' },
+  {
+    pattern: /\/currency\/(convert|rates)\/route\.ts$/,
+    reason: 'Currency reference data; port-scoped, no PII.',
+  },
+  {
+    pattern: /\/currency\/rates\/refresh\//,
+    reason: 'TODO: gate with admin:manage_settings — currently allow-listed.',
+  },
+  {
+    pattern: /\/search\//,
+    reason: 'Port-scoped search — results filtered by auth context (resources have own perms).',
+  },
+  // Alerts surface in topbar/dashboard for every signed-in user; per-port not per-resource.
+  { pattern: /\/alerts\//, reason: 'Alerts are user-scoped; port-filtered via auth context.' },
+  // Internally gated by isSuperAdmin
+  {
+    pattern: /\/expenses\/export\/parent-company\//,
+    reason: 'Internally gated by isSuperAdmin inside the handler.',
+  },
+  // Pending dedicated permissions
+  {
+    pattern: /\/ai\//,
+    reason: 'TODO: needs ai:* permission catalog entry. Currently allow-listed.',
+  },
+  {
+    pattern: /\/custom-fields\/\[entityId\]\//,
+    reason: 'TODO: needs custom_fields:* permission. PUT path internally validated.',
+  },
+  {
+    pattern: /\/berth-reservations\/\[id\]\/route\.ts$/,
+    reason: 'TODO: PATCH should map to reservations:edit (not currently in catalog).',
+  },
+];
+
+interface Finding {
+  file: string;
+  method: string;
+  reason: 'no-withPermission' | 'no-withAuth' | 'allow-listed';
+  allowReason?: string;
+}
+
+async function* walk(dir: string): AsyncGenerator<string> {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walk(path);
+    else if (entry.isFile() && entry.name === 'route.ts') yield path;
+  }
+}
+
+function isAllowListed(file: string): { allowed: boolean; reason?: string } {
+  for (const { pattern, reason } of ALLOW_LIST) {
+    if (pattern.test(file)) return { allowed: true, reason };
+  }
+  return { allowed: false };
+}
+
+async function auditFile(file: string): Promise<Finding[]> {
+  const src = await readFile(file, 'utf-8');
+  const findings: Finding[] = [];
+
+  for (const method of HTTP_METHODS) {
+    // Match: export const GET = withAuth(...
+    const declRe = new RegExp(`export\\s+const\\s+${method}\\s*=\\s*(.+?);`, 's');
+    const m = declRe.exec(src);
+    if (!m) continue;
+    const block = m[1] ?? '';
+
+    const hasAuth = /withAuth\s*\(/.test(block);
+    const hasPerm = /withPermission\s*\(/.test(block);
+    const allow = isAllowListed(file);
+
+    if (!hasAuth) {
+      findings.push({ file, method, reason: 'no-withAuth' });
+      continue;
+    }
+    if (!hasPerm) {
+      if (allow.allowed) {
+        findings.push({ file, method, reason: 'allow-listed', allowReason: allow.reason });
+      } else {
+        findings.push({ file, method, reason: 'no-withPermission' });
+      }
+    }
+  }
+
+  return findings;
+}
+
+async function main() {
+  const files: string[] = [];
+  for await (const f of walk(ROOT)) files.push(f);
+  files.sort();
+
+  const all: Finding[] = [];
+  for (const f of files) all.push(...(await auditFile(f)));
+
+  const violations = all.filter(
+    (f) => f.reason === 'no-withPermission' || f.reason === 'no-withAuth',
+  );
+  const allowListed = all.filter((f) => f.reason === 'allow-listed');
+
+  // Markdown report
+  const lines: string[] = [];
+  lines.push('# Permission Matrix Audit');
+  lines.push('');
+  lines.push(`Scanned ${files.length} route files under \`src/app/api/v1/\`.`);
+  lines.push('');
+
+  if (violations.length === 0) {
+    lines.push('**No violations.** Every internal v1 handler is permission-gated.');
+  } else {
+    lines.push(`**${violations.length} violation(s):**`);
+    lines.push('');
+    lines.push('| File | Method | Issue |');
+    lines.push('| --- | --- | --- |');
+    for (const v of violations) {
+      const rel = relative(process.cwd(), v.file);
+      lines.push(`| \`${rel}\` | ${v.method} | ${v.reason} |`);
+    }
+  }
+  lines.push('');
+  lines.push(
+    `**Allow-listed:** ${allowListed.length} handler(s) intentionally skip \`withPermission\`.`,
+  );
+  if (allowListed.length > 0) {
+    lines.push('');
+    lines.push('| File | Method | Reason |');
+    lines.push('| --- | --- | --- |');
+    for (const a of allowListed) {
+      const rel = relative(process.cwd(), a.file);
+      lines.push(`| \`${rel}\` | ${a.method} | ${a.allowReason} |`);
+    }
+  }
+
+  process.stdout.write(lines.join('\n') + '\n');
+  process.exit(violations.length > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(2);
+});

scripts/backfill-legacy-lead-source.ts

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

scripts/backfill-phone-e164.ts

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

scripts/backup/minio-mirror.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Hourly MinIO mirror for Port Nimara CRM.
+#
+# Mirrors the live `MINIO_BUCKET` to the backup destination. `mc mirror`
+# is incremental — only changed objects transfer — so this is cheap.
+#
+# Versioning on the destination bucket is what protects against object
+# deletes / overwrites; we don't try to roll our own.
+
+set -euo pipefail
+
+: "${MINIO_ENDPOINT:?MINIO_ENDPOINT not set}"
+: "${MINIO_ACCESS_KEY:?MINIO_ACCESS_KEY not set}"
+: "${MINIO_SECRET_KEY:?MINIO_SECRET_KEY not set}"
+: "${MINIO_BUCKET:?MINIO_BUCKET not set}"
+: "${BACKUP_S3_BUCKET:?BACKUP_S3_BUCKET not set}"
+: "${BACKUP_S3_ENDPOINT:?BACKUP_S3_ENDPOINT not set}"
+: "${BACKUP_S3_ACCESS_KEY:?BACKUP_S3_ACCESS_KEY not set}"
+: "${BACKUP_S3_SECRET_KEY:?BACKUP_S3_SECRET_KEY not set}"
+
+# Default scheme: live MinIO is plain HTTP unless MINIO_USE_SSL=true.
+LIVE_URL="${MINIO_ENDPOINT}"
+if [[ "${MINIO_USE_SSL:-false}" == "true" ]]; then
+  LIVE_URL="https://${MINIO_ENDPOINT}:${MINIO_PORT:-443}"
+else
+  LIVE_URL="http://${MINIO_ENDPOINT}:${MINIO_PORT:-9000}"
+fi
+
+LIVE_ALIAS="live-$$"
+BACKUP_ALIAS="bk-$$"
+trap 'mc alias remove "$LIVE_ALIAS" 2>/dev/null || true; mc alias remove "$BACKUP_ALIAS" 2>/dev/null || true' EXIT
+
+mc alias set "$LIVE_ALIAS" "$LIVE_URL" \
+  "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY" --api S3v4 >/dev/null
+mc alias set "$BACKUP_ALIAS" "$BACKUP_S3_ENDPOINT" \
+  "$BACKUP_S3_ACCESS_KEY" "$BACKUP_S3_SECRET_KEY" --api S3v4 >/dev/null
+
+SOURCE="${LIVE_ALIAS}/${MINIO_BUCKET}/"
+DEST="${BACKUP_ALIAS}/${BACKUP_S3_BUCKET}/minio/"
+
+echo "[$(date -u +%FT%TZ)] Mirroring $SOURCE → $DEST"
+
+# `--remove` would delete objects from the destination that no longer
+# exist in source — we DON'T pass it, because that would let an
+# accidental delete on the live bucket cascade into permanent loss on
+# the backup side. Versioning + lifecycle handle stale-object cleanup.
+mc mirror --quiet --overwrite "$SOURCE" "$DEST"
+
+# Print byte / count diff for the operator.
+echo "[$(date -u +%FT%TZ)] Done. Destination summary:"
+mc du "$DEST"

scripts/backup/pg-backup.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Hourly PostgreSQL backup for Port Nimara CRM.
+#
+# Reads DATABASE_URL and BACKUP_S3_* from the environment. Dumps to a
+# tmpfile, gzips, optionally GPG-encrypts to BACKUP_GPG_RECIPIENT, and
+# uploads to s3://${BACKUP_S3_BUCKET}/pg/<hostname>/<UTC-date>/<hour>.dump.gz[.gpg].
+#
+# Designed to fail loud: any non-zero exit halts the script and propagates
+# to the cron / CI runner so the operator sees the failure.
+
+set -euo pipefail
+
+: "${DATABASE_URL:?DATABASE_URL not set}"
+: "${BACKUP_S3_BUCKET:?BACKUP_S3_BUCKET not set}"
+: "${BACKUP_S3_ENDPOINT:?BACKUP_S3_ENDPOINT not set}"
+: "${BACKUP_S3_ACCESS_KEY:?BACKUP_S3_ACCESS_KEY not set}"
+: "${BACKUP_S3_SECRET_KEY:?BACKUP_S3_SECRET_KEY not set}"
+
+HOST="${BACKUP_HOST_OVERRIDE:-$(hostname -s)}"
+DATE_UTC="$(date -u +%Y-%m-%d)"
+HOUR_UTC="$(date -u +%H)"
+WORKDIR="$(mktemp -d)"
+trap 'rm -rf "$WORKDIR"' EXIT
+
+DUMP_FILE="$WORKDIR/${HOUR_UTC}.dump"
+ARCHIVE_NAME="${HOUR_UTC}.dump.gz"
+
+echo "[$(date -u +%FT%TZ)] Dumping $DATABASE_URL → $DUMP_FILE"
+pg_dump --format=custom --compress=9 --no-owner --no-privileges \
+  --file="$DUMP_FILE" "$DATABASE_URL"
+
+# pg_dump's `custom` format is already compressed, but we wrap in gzip so
+# the file looks the same regardless of the dump format on disk.
+gzip -n "$DUMP_FILE"
+GZ_FILE="${DUMP_FILE}.gz"
+
+# Optional GPG layer. Only encrypt if the recipient is configured.
+if [[ -n "${BACKUP_GPG_RECIPIENT:-}" ]]; then
+  echo "[$(date -u +%FT%TZ)] Encrypting for $BACKUP_GPG_RECIPIENT"
+  gpg --batch --yes --trust-model always \
+    --recipient "$BACKUP_GPG_RECIPIENT" \
+    --encrypt --output "${GZ_FILE}.gpg" "$GZ_FILE"
+  rm "$GZ_FILE"
+  GZ_FILE="${GZ_FILE}.gpg"
+  ARCHIVE_NAME="${ARCHIVE_NAME}.gpg"
+fi
+
+# Configure mc client for the backup destination.
+MC_ALIAS="bk-$$"
+mc alias set "$MC_ALIAS" "$BACKUP_S3_ENDPOINT" \
+  "$BACKUP_S3_ACCESS_KEY" "$BACKUP_S3_SECRET_KEY" \
+  --api S3v4 >/dev/null
+
+REMOTE_PATH="${MC_ALIAS}/${BACKUP_S3_BUCKET}/pg/${HOST}/${DATE_UTC}/${ARCHIVE_NAME}"
+echo "[$(date -u +%FT%TZ)] Uploading → $REMOTE_PATH"
+mc cp --quiet "$GZ_FILE" "$REMOTE_PATH"
+
+# Tag with retention metadata so lifecycle rules can decide what to expire.
+mc tag set "$REMOTE_PATH" "kind=hourly&host=${HOST}&date=${DATE_UTC}" >/dev/null
+
+mc alias remove "$MC_ALIAS" >/dev/null
+
+echo "[$(date -u +%FT%TZ)] OK ${ARCHIVE_NAME} ($(du -h "$GZ_FILE" | cut -f1))"

scripts/backup/restore.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Cold-restore script for Port Nimara CRM.
+#
+# Two modes:
+#   --drill         Restore to a sandbox DB ($DRILL_DATABASE_URL) + a tagged
+#                   sandbox path on the live MinIO bucket. Used by the weekly
+#                   cron drill so the runbook stays accurate.
+#   (no --drill)    Interactive production restore. Prompts before each
+#                   destructive step; refuses to run if the live DB has
+#                   non-empty tables (caller is expected to drop first).
+#
+# Common args:
+#   --snapshot YYYY-MM-DD/HH    Specific dump to restore. Defaults to "latest".
+
+set -euo pipefail
+
+DRILL=0
+SNAPSHOT="latest"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --drill) DRILL=1; shift ;;
+    --snapshot) SNAPSHOT="$2"; shift 2 ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+: "${BACKUP_S3_BUCKET:?BACKUP_S3_BUCKET not set}"
+: "${BACKUP_S3_ENDPOINT:?BACKUP_S3_ENDPOINT not set}"
+: "${BACKUP_S3_ACCESS_KEY:?BACKUP_S3_ACCESS_KEY not set}"
+: "${BACKUP_S3_SECRET_KEY:?BACKUP_S3_SECRET_KEY not set}"
+
+if [[ "$DRILL" -eq 1 ]]; then
+  : "${DRILL_DATABASE_URL:?DRILL_DATABASE_URL not set}"
+  TARGET_DB="$DRILL_DATABASE_URL"
+  echo "[drill] target DB = $TARGET_DB"
+else
+  : "${DATABASE_URL:?DATABASE_URL not set}"
+  TARGET_DB="$DATABASE_URL"
+  read -rp "About to overwrite $TARGET_DB. Type 'restore' to continue: " confirm
+  [[ "$confirm" == "restore" ]] || { echo "aborted"; exit 1; }
+fi
+
+HOST="${BACKUP_HOST_OVERRIDE:-$(hostname -s)}"
+WORKDIR="$(mktemp -d)"
+trap 'rm -rf "$WORKDIR"' EXIT
+
+MC_ALIAS="bk-$$"
+mc alias set "$MC_ALIAS" "$BACKUP_S3_ENDPOINT" \
+  "$BACKUP_S3_ACCESS_KEY" "$BACKUP_S3_SECRET_KEY" --api S3v4 >/dev/null
+trap 'rm -rf "$WORKDIR"; mc alias remove "$MC_ALIAS" 2>/dev/null || true' EXIT
+
+# Resolve the snapshot path.
+if [[ "$SNAPSHOT" == "latest" ]]; then
+  REMOTE=$(mc ls --recursive "${MC_ALIAS}/${BACKUP_S3_BUCKET}/pg/${HOST}/" \
+    | awk '{print $NF}' | sort | tail -1)
+  if [[ -z "$REMOTE" ]]; then
+    echo "no snapshots found under ${BACKUP_S3_BUCKET}/pg/${HOST}/" >&2
+    exit 1
+  fi
+  REMOTE="${MC_ALIAS}/${BACKUP_S3_BUCKET}/pg/${HOST}/${REMOTE}"
+else
+  REMOTE="${MC_ALIAS}/${BACKUP_S3_BUCKET}/pg/${HOST}/${SNAPSHOT}.dump.gz"
+  # If GPG was used, the file lives at .dump.gz.gpg. Try both.
+  if ! mc stat "$REMOTE" >/dev/null 2>&1; then
+    REMOTE="${REMOTE}.gpg"
+  fi
+fi
+
+echo "[$(date -u +%FT%TZ)] Pulling $REMOTE"
+LOCAL="$WORKDIR/$(basename "$REMOTE")"
+mc cp --quiet "$REMOTE" "$LOCAL"
+
+# Decrypt if needed.
+if [[ "$LOCAL" == *.gpg ]]; then
+  echo "[$(date -u +%FT%TZ)] Decrypting"
+  gpg --batch --yes --decrypt --output "${LOCAL%.gpg}" "$LOCAL"
+  rm "$LOCAL"
+  LOCAL="${LOCAL%.gpg}"
+fi
+
+# Decompress.
+gunzip "$LOCAL"
+LOCAL="${LOCAL%.gz}"
+
+echo "[$(date -u +%FT%TZ)] Restoring into $TARGET_DB"
+
+# Drop & recreate to guarantee no half-state from a prior run.
+DB_NAME=$(echo "$TARGET_DB" | sed -E 's|.*/([^?]+).*|\1|')
+ADMIN_URL=$(echo "$TARGET_DB" | sed -E "s|/${DB_NAME}|/postgres|")
+
+psql "$ADMIN_URL" -v ON_ERROR_STOP=1 <<SQL
+SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+  WHERE datname = '${DB_NAME}' AND pid <> pg_backend_pid();
+DROP DATABASE IF EXISTS "${DB_NAME}";
+CREATE DATABASE "${DB_NAME}";
+SQL
+
+pg_restore --no-owner --no-privileges --dbname "$TARGET_DB" "$LOCAL"
+
+# Drill mode: compare row counts vs the live producer for parity.
+if [[ "$DRILL" -eq 1 ]]; then
+  echo "[$(date -u +%FT%TZ)] Drill row-count diff (live vs restored):"
+  TABLES=$(psql -At "$TARGET_DB" -c \
+    "SELECT tablename FROM pg_tables WHERE schemaname='public' ORDER BY tablename;")
+  diff_count=0
+  while IFS= read -r tbl; do
+    [[ -z "$tbl" ]] && continue
+    live=$(psql -At "${LIVE_DATABASE_URL:-$DATABASE_URL}" -c "SELECT count(*) FROM \"$tbl\";")
+    restored=$(psql -At "$TARGET_DB" -c "SELECT count(*) FROM \"$tbl\";")
+    delta=$((live - restored))
+    if [[ "$delta" -ne 0 ]]; then
+      echo "  ⚠ $tbl: live=$live restored=$restored delta=$delta"
+      diff_count=$((diff_count + 1))
+    fi
+  done <<< "$TABLES"
+  if [[ "$diff_count" -eq 0 ]]; then
+    echo "  ✓ row counts match across all tables"
+  fi
+fi
+
+echo "[$(date -u +%FT%TZ)] Restore complete."

scripts/dev-set-password.ts

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

scripts/dev-trigger-crm-invite.ts

@@ -20,7 +20,15 @@ async function main() {
   const isSuperAdmin = args.includes('--super');
   const name = args.find((a, i) => i > 0 && !a.startsWith('--'));
 
-  const { inviteId, link } = await createCrmInvite({ email, name, isSuperAdmin });
+  // Dev script runs out-of-band (no HTTP request, no session). The service's
+  // super-admin gate requires `invitedBy.isSuperAdmin === true` for super
+  // invites; the script bypasses that with a synthetic caller identity.
+  const { inviteId, link } = await createCrmInvite({
+    email,
+    name,
+    isSuperAdmin,
+    invitedBy: { userId: 'cli-script', isSuperAdmin: true },
+  });
   console.log(`✓ Invite created (id=${inviteId})`);
   console.log(`  email: ${email}`);
   console.log(`  super_admin: ${isSuperAdmin}`);

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

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

scripts/migrate-from-nocodb.ts

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

scripts/smoke-test-redirect.ts

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

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

@@ -1,10 +1,9 @@
+import { PageHeader } from '@/components/shared/page-header';
+
 export default function BackupManagementPage() {
   return (
     <div className="space-y-6">
-      <div>
+      <PageHeader title="Backup Management" description="Manage system backups and restoration" />
-        <h1 className="text-2xl font-bold text-foreground">Backup Management</h1>
-        <p className="text-muted-foreground">Manage system backups and restoration</p>
-      </div>
       <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-12">
         <p className="text-lg font-medium text-muted-foreground">Coming in Layer 4</p>
         <p className="text-sm text-muted-foreground">

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

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

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

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

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

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

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

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

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

@@ -1,10 +1,9 @@
+import { PageHeader } from '@/components/shared/page-header';
+
 export default function DataImportPage() {
   return (
     <div className="space-y-6">
-      <div>
+      <PageHeader title="Data Import" description="Import data from external sources" />
-        <h1 className="text-2xl font-bold text-foreground">Data Import</h1>
-        <p className="text-muted-foreground">Import data from external sources</p>
-      </div>
       <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-12">
         <p className="text-lg font-medium text-muted-foreground">Coming in Layer 4</p>
         <p className="text-sm text-muted-foreground">

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

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

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

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

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

@@ -0,0 +1,5 @@
+import { OcrSettingsForm } from '@/components/admin/ocr-settings-form';
+
+export default function OcrSettingsPage() {
+  return <OcrSettingsForm />;
+}

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

@@ -1,10 +1,9 @@
+import { PageHeader } from '@/components/shared/page-header';
+
 export default function OnboardingPage() {
   return (
     <div className="space-y-6">
-      <div>
+      <PageHeader title="Onboarding" description="Guided setup for new port configurations" />
-        <h1 className="text-2xl font-bold text-foreground">Onboarding</h1>
-        <p className="text-muted-foreground">Guided setup for new port configurations</p>
-      </div>
       <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-12">
         <p className="text-lg font-medium text-muted-foreground">Coming in Layer 4</p>
         <p className="text-sm text-muted-foreground">

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

@@ -16,10 +16,13 @@ import {
   Tag,
   Upload,
   Users,
+  UsersRound,
   Webhook,
+  Globe,
 } from 'lucide-react';
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { PageHeader } from '@/components/shared/page-header';
 
 interface AdminSection {
   href: string;
@@ -28,126 +31,192 @@ interface AdminSection {
   icon: typeof Settings;
 }
 
-const SECTIONS: AdminSection[] = [
+interface AdminGroup {
+  title: string;
+  description: string;
+  sections: AdminSection[];
+}
+
+const GROUPS: AdminGroup[] = [
   {
-    href: 'users',
+    title: 'Access',
-    label: 'Users',
+    description: 'Who can sign in and what they can do once they do.',
-    description: 'CRM accounts, role assignments, and per-user residential access toggles.',
+    sections: [
-    icon: Users,
+      {
+        href: 'users',
+        label: 'Users',
+        description: 'CRM accounts, role assignments, and per-user residential access toggles.',
+        icon: Users,
+      },
+      {
+        href: 'invitations',
+        label: 'Invitations',
+        description: 'Send invitations, track pending invites, and resend or revoke them.',
+        icon: Mail,
+      },
+      {
+        href: 'roles',
+        label: 'Roles & Permissions',
+        description: 'Default permission sets and per-port role overrides.',
+        icon: Shield,
+      },
+    ],
   },
   {
-    href: 'invitations',
+    title: 'Configuration',
-    label: 'Invitations',
+    description: 'Branding, integrations, and per-port settings.',
-    description: 'Send invitations, track pending invites, and resend or revoke them.',
+    sections: [
-    icon: Mail,
+      {
+        href: 'email',
+        label: 'Email Settings',
+        description: 'From address, signatures, and per-port SMTP overrides.',
+        icon: Mail,
+      },
+      {
+        href: 'documenso',
+        label: 'Documenso & EOI',
+        description: 'API credentials, EOI template, and default in-app vs Documenso pathway.',
+        icon: FileText,
+      },
+      {
+        href: 'reminders',
+        label: 'Reminders',
+        description: 'Default reminder behaviour and the daily-digest delivery window.',
+        icon: Bell,
+      },
+      {
+        href: 'branding',
+        label: 'Branding',
+        description: 'App name, logo, primary color, and email header/footer HTML.',
+        icon: Palette,
+      },
+      {
+        href: 'settings',
+        label: 'System Settings',
+        description: 'Generic key/value configuration store for advanced flags.',
+        icon: Settings,
+      },
+      {
+        href: 'webhooks',
+        label: 'Webhooks',
+        description: 'Outgoing webhook subscriptions, secrets, and delivery log.',
+        icon: Webhook,
+      },
+    ],
   },
   {
-    href: 'roles',
+    title: 'Content',
-    label: 'Roles & Permissions',
+    description: 'Forms, templates, and labels that users see.',
-    description: 'Default permission sets and per-port role overrides.',
+    sections: [
-    icon: Shield,
+      {
+        href: 'forms',
+        label: 'Forms',
+        description: 'Form templates used by client-facing inquiry and intake flows.',
+        icon: Sliders,
+      },
+      {
+        href: 'templates',
+        label: 'Document Templates',
+        description: 'PDF + email templates with merge-field placeholders.',
+        icon: FileText,
+      },
+      {
+        href: 'tags',
+        label: 'Tags',
+        description: 'Color-coded tags applied to clients, yachts, companies, and interests.',
+        icon: Tag,
+      },
+      {
+        href: 'custom-fields',
+        label: 'Custom Fields',
+        description: 'Tenant-defined fields for clients, yachts, and reservations.',
+        icon: Key,
+      },
+    ],
   },
   {
-    href: 'audit',
+    title: 'Data Quality',
-    label: 'Audit Log',
+    description: 'Cleanup, imports, and the audit trail.',
-    description: 'Searchable log of every authenticated mutation in the system.',
+    sections: [
-    icon: ScrollText,
+      {
+        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,
+      },
+    ],
   },
   {
-    href: 'email',
+    title: 'Operations',
-    label: 'Email Settings',
+    description: 'Health checks and disaster recovery.',
-    description: 'From address, signatures, and per-port SMTP overrides.',
+    sections: [
-    icon: Mail,
+      {
+        href: 'reports',
+        label: 'Reports',
+        description: 'Saved analytics views and ad-hoc query results.',
+        icon: LayoutDashboard,
+      },
+      {
+        href: 'monitoring',
+        label: 'Queue Monitoring',
+        description: 'BullMQ queue health, throughput, and retry diagnostics.',
+        icon: Database,
+      },
+      {
+        href: 'backup',
+        label: 'Backup & Restore',
+        description: 'Database snapshots and on-demand exports.',
+        icon: HardDrive,
+      },
+    ],
   },
   {
-    href: 'documenso',
+    title: 'Tenancy',
-    label: 'Documenso & EOI',
+    description: 'Multi-port and multi-install scaffolding.',
-    description: 'API credentials, EOI template, and default in-app vs Documenso pathway.',
+    sections: [
-    icon: FileText,
+      {
+        href: 'ports',
+        label: 'Ports',
+        description: 'Manage the marinas/ports this installation serves.',
+        icon: Briefcase,
+      },
+      {
+        href: 'onboarding',
+        label: 'Onboarding',
+        description: 'Initial-setup wizard for fresh ports.',
+        icon: LayoutDashboard,
+      },
+    ],
   },
   {
-    href: 'reminders',
+    title: 'Integrations',
-    label: 'Reminders',
+    description: 'Third-party providers wired into the app.',
-    description: 'Default reminder behaviour and the daily-digest delivery window.',
+    sections: [
-    icon: Bell,
+      {
-  },
+        href: 'ocr',
-  {
+        label: 'Receipt OCR',
-    href: 'branding',
+        description: 'Configure the AI provider used by the mobile receipt scanner.',
-    label: 'Branding',
+        icon: ScrollText,
-    description: 'App name, logo, primary color, and email header/footer HTML.',
+      },
-    icon: Palette,
+      {
-  },
+        href: 'website-analytics',
-  {
+        label: 'Website analytics (Umami)',
-    href: 'settings',
+        description: 'Per-port Umami URL, API token, and Website ID.',
-    label: 'System Settings',
+        icon: Globe,
-    description: 'Generic key/value configuration store for advanced flags.',
+      },
-    icon: Settings,
+    ],
-  },
-  {
-    href: 'webhooks',
-    label: 'Webhooks',
-    description: 'Outgoing webhook subscriptions, secrets, and delivery log.',
-    icon: Webhook,
-  },
-  {
-    href: 'forms',
-    label: 'Forms',
-    description: 'Form templates used by client-facing inquiry and intake flows.',
-    icon: Sliders,
-  },
-  {
-    href: 'templates',
-    label: 'Document Templates',
-    description: 'PDF + email templates with merge-field placeholders.',
-    icon: FileText,
-  },
-  {
-    href: 'tags',
-    label: 'Tags',
-    description: 'Color-coded tags applied to clients, yachts, companies, and interests.',
-    icon: Tag,
-  },
-  {
-    href: 'custom-fields',
-    label: 'Custom Fields',
-    description: 'Tenant-defined fields for clients, yachts, and reservations.',
-    icon: Key,
-  },
-  {
-    href: 'reports',
-    label: 'Reports',
-    description: 'Saved analytics views and ad-hoc query results.',
-    icon: LayoutDashboard,
-  },
-  {
-    href: 'monitoring',
-    label: 'Queue Monitoring',
-    description: 'BullMQ queue health, throughput, and retry diagnostics.',
-    icon: Database,
-  },
-  {
-    href: 'import',
-    label: 'Bulk Import',
-    description: 'CSV-driven imports for clients, yachts, and reservations.',
-    icon: Upload,
-  },
-  {
-    href: 'backup',
-    label: 'Backup & Restore',
-    description: 'Database snapshots and on-demand exports.',
-    icon: HardDrive,
-  },
-  {
-    href: 'ports',
-    label: 'Ports',
-    description: 'Manage the marinas/ports this installation serves.',
-    icon: Briefcase,
-  },
-  {
-    href: 'onboarding',
-    label: 'Onboarding',
-    description: 'Initial-setup wizard for fresh ports.',
-    icon: LayoutDashboard,
   },
 ];
 
@@ -158,39 +227,46 @@ export default async function AdminLandingPage({
 }) {
   const { portSlug } = await params;
   return (
-    <div className="space-y-6">
+    <div className="space-y-8">
-      <div>
+      <PageHeader
-        <h1 className="text-2xl font-semibold">Administration</h1>
+        title="Administration"
-        <p className="text-sm text-muted-foreground">
+        description="Per-port configuration and system administration. Each card below opens a dedicated settings page."
-          Per-port configuration and system administration. Each card below opens a dedicated
+      />
-          settings page.
+      {GROUPS.map((group) => (
-        </p>
+        <section key={group.title} className="space-y-3">
-      </div>
+          <div>
-      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+            <h2 className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
-        {SECTIONS.map((s) => {
+              {group.title}
-          const Icon = s.icon;
+            </h2>
-          return (
+            <p className="text-xs text-muted-foreground/80">{group.description}</p>
-            <Link
+          </div>
-              key={s.href}
+          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
-              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            {group.sections.map((s) => {
-              href={`/${portSlug}/admin/${s.href}` as any}
+              const Icon = s.icon;
-              className="block group"
+              return (
-            >
+                <Link
-              <Card className="h-full transition-colors group-hover:border-primary/50 group-hover:bg-muted/30">
+                  key={s.href}
-                <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
+                  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                  <Icon className="h-5 w-5 mt-0.5 text-muted-foreground group-hover:text-primary" />
+                  href={`/${portSlug}/admin/${s.href}` as any}
-                  <div className="flex-1">
+                  className="block group"
-                    <CardTitle className="text-base">{s.label}</CardTitle>
+                >
-                  </div>
+                  <Card className="h-full transition-colors group-hover:border-primary/50 group-hover:bg-muted/30">
-                </CardHeader>
+                    <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
-                <CardContent>
+                      <Icon className="h-5 w-5 mt-0.5 text-muted-foreground group-hover:text-primary" />
-                  <CardDescription>{s.description}</CardDescription>
+                      <div className="flex-1">
-                </CardContent>
+                        <CardTitle className="text-base">{s.label}</CardTitle>
-              </Card>
+                      </div>
-            </Link>
+                    </CardHeader>
-          );
+                    <CardContent>
-        })}
+                      <CardDescription>{s.description}</CardDescription>
-      </div>
+                    </CardContent>
+                  </Card>
+                </Link>
+              );
+            })}
+          </div>
+        </section>
+      ))}
     </div>
   );
 }

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

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

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

@@ -1,10 +1,12 @@
+import { PageHeader } from '@/components/shared/page-header';
+
 export default function ScheduledReportsPage() {
   return (
     <div className="space-y-6">
-      <div>
+      <PageHeader
-        <h1 className="text-2xl font-bold text-foreground">Scheduled Reports</h1>
+        title="Scheduled Reports"
-        <p className="text-muted-foreground">Configure and manage automated report delivery</p>
+        description="Configure and manage automated report delivery"
-      </div>
+      />
       <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-12">
         <p className="text-lg font-medium text-muted-foreground">Coming in Layer 3</p>
         <p className="text-sm text-muted-foreground">

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

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

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

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

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

@@ -0,0 +1,5 @@
+import { AlertsPageShell } from '@/components/alerts/alerts-page-shell';
+
+export default function AlertsPage() {
+  return <AlertsPageShell />;
+}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

src/app/(dashboard)/layout.tsx

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

src/app/(portal)/layout.tsx

@@ -12,14 +12,10 @@ export const metadata: Metadata = {
   },
 };
 
-export default async function PortalLayout({
+export default async function PortalLayout({ children }: { children: React.ReactNode }) {
-  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
+          <PortalHeader portName={portName} portLogoUrl={portLogoUrl} clientName={clientName} />
-            portName={portName}
-            portLogoUrl={portLogoUrl}
-            clientName={clientName}
-          />
           <PortalNav />
         </>
       )}
-      <main className={session ? 'max-w-5xl mx-auto px-4 sm:px-6 py-8' : ''}>
+      <main className={session ? 'max-w-5xl mx-auto px-4 sm:px-6 py-8' : ''}>{children}</main>
-        {children}
-      </main>
     </div>
   );
 }

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,72 @@
+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';
+
+/**
+ * Minimal layout for the mobile receipt-scanner PWA. No sidebar, no
+ * 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,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ portSlug: string }>;
+}) {
+  const session = await auth.api.getSession({ headers: await headers() });
+  if (!session?.user) redirect('/login');
+
+  const { portSlug } = await params;
+  const port = await db.query.ports.findFirst({
+    where: eq(portsTable.slug, portSlug),
+  });
+  if (!port) redirect('/login');
+
+  return (
+    <QueryProvider>
+      <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

@@ -0,0 +1,45 @@
+import { NextResponse } from 'next/server';
+import { eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+
+/**
+ * Per-port PWA manifest. Scoped to `/<portSlug>/scan` so the install
+ * only covers the scanner page, not the rest of the CRM. Each port
+ * gets its own homescreen icon labeled with its name.
+ */
+export async function GET(_req: Request, { params }: { params: Promise<{ portSlug: string }> }) {
+  const { portSlug } = await params;
+  const port = await db.query.ports.findFirst({ where: eq(ports.slug, portSlug) });
+  const portName = port?.name ?? 'Port Nimara';
+
+  const manifest = {
+    name: `${portName} - Scanner`,
+    short_name: 'Scanner',
+    description: `Capture and submit expense receipts for ${portName}.`,
+    start_url: `/${portSlug}/scan`,
+    scope: `/${portSlug}/scan`,
+    display: 'standalone',
+    orientation: 'portrait',
+    background_color: '#ffffff',
+    theme_color: '#3a7bc8',
+    icons: [
+      { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+      { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+      {
+        src: '/icon-512-maskable.png',
+        sizes: '512x512',
+        type: 'image/png',
+        purpose: 'maskable',
+      },
+    ],
+  };
+
+  return NextResponse.json(manifest, {
+    headers: {
+      'Content-Type': 'application/manifest+json',
+      'Cache-Control': 'public, max-age=300, must-revalidate',
+    },
+  });
+}

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

@@ -0,0 +1,11 @@
+import type { Metadata } from 'next';
+
+import { ScanShell } from '@/components/scan/scan-shell';
+
+export const metadata: Metadata = {
+  title: 'Scan receipt - Port Nimara',
+};
+
+export default function ScanPage() {
+  return <ScanShell />;
+}

src/app/api/health/route.ts

@@ -1,68 +1,15 @@
 import { NextResponse } from 'next/server';
-import { db } from '@/lib/db';
-import { redis } from '@/lib/redis';
-import { minioClient } from '@/lib/minio';
-import { env } from '@/lib/env';
-import { sql } from 'drizzle-orm';
 
-type CheckStatus = 'ok' | 'error';
+/**
-
+ * Liveness probe - confirms the Next.js process is responding.
-interface HealthChecks {
+ *
-  postgres: CheckStatus;
+ * Returns 200 unconditionally; if the process is wedged or has crashed
-  redis: CheckStatus;
+ * the request never lands here at all. Do NOT include database/Redis/MinIO
-  minio: CheckStatus;
+ * checks in this endpoint - a transient downstream blip should drop the
-}
+ * pod from the load balancer (readiness), not restart the pod (liveness).
-
+ *
-interface HealthResponse {
+ * For deep dependency checks, hit `/api/ready` instead.
-  status: 'healthy' | 'degraded';
+ */
-  checks: HealthChecks;
+export async function GET() {
-  timestamp: string;
+  return NextResponse.json({ status: 'ok', timestamp: new Date().toISOString() });
-}
-
-export async function GET(): Promise<NextResponse<HealthResponse>> {
-  const checks: HealthChecks = {
-    postgres: 'error',
-    redis: 'error',
-    minio: 'error',
-  };
-
-  await Promise.allSettled([
-    db
-      .execute(sql`SELECT 1`)
-      .then(() => {
-        checks.postgres = 'ok';
-      })
-      .catch(() => {
-        checks.postgres = 'error';
-      }),
-
-    redis
-      .ping()
-      .then(() => {
-        checks.redis = 'ok';
-      })
-      .catch(() => {
-        checks.redis = 'error';
-      }),
-
-    minioClient
-      .bucketExists(env.MINIO_BUCKET)
-      .then(() => {
-        checks.minio = 'ok';
-      })
-      .catch(() => {
-        checks.minio = 'error';
-      }),
-  ]);
-
-  const allHealthy = Object.values(checks).every((s) => s === 'ok');
-  const status: HealthResponse['status'] = allHealthy ? 'healthy' : 'degraded';
-
-  const body: HealthResponse = {
-    status,
-    checks,
-    timestamp: new Date().toISOString(),
-  };
-
-  return NextResponse.json(body, { status: allHealthy ? 200 : 503 });
 }

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

@@ -12,31 +12,23 @@ import { yachts, yachtOwnershipHistory } from '@/lib/db/schema/yachts';
 import { companies, companyMemberships } from '@/lib/db/schema/companies';
 import { createAuditLog } from '@/lib/audit';
 import { errorResponse, RateLimitError } from '@/lib/errors';
+import { checkRateLimit, rateLimiters } from '@/lib/rate-limit';
 import { publicInterestSchema } from '@/lib/validators/interests';
 import { sendInquiryNotifications } from '@/lib/services/inquiry-notifications.service';
+import { parsePhone } from '@/lib/i18n/phone';
+import type { CountryCode } from '@/lib/i18n/countries';
 
-// ─── Simple in-memory rate limiter ───────────────────────────────────────────
+/**
-// Max 5 requests per hour per IP
+ * Throws RateLimitError if the IP has exceeded the public-form quota.
-
+ * Backed by the Redis sliding-window limiter so the cap survives restarts
-const ipHits = new Map<string, { count: number; resetAt: number }>();
+ * and is shared across worker processes.
-const WINDOW_MS = 60 * 60 * 1000; // 1 hour
+ */
-const MAX_HITS = 5;
+async function gateRateLimit(ip: string): Promise<void> {
-
+  const result = await checkRateLimit(ip, rateLimiters.publicForm);
-function checkRateLimit(ip: string): void {
+  if (!result.allowed) {
-  const now = Date.now();
+    const retryAfter = Math.max(1, Math.ceil((result.resetAt - Date.now()) / 1000));
-  const entry = ipHits.get(ip);
-
-  if (!entry || now > entry.resetAt) {
-    ipHits.set(ip, { count: 1, resetAt: now + WINDOW_MS });
-    return;
-  }
-
-  if (entry.count >= MAX_HITS) {
-    const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
     throw new RateLimitError(retryAfter);
   }
-
-  entry.count += 1;
 }
 
 type PublicInterestData = z.infer<typeof publicInterestSchema>;
@@ -44,13 +36,13 @@ 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) {
   try {
     const ip = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? 'unknown';
-    checkRateLimit(ip);
+    await gateRateLimit(ip);
 
     const body = await req.json();
     const data = publicInterestSchema.parse(body);
@@ -61,6 +53,16 @@ export async function POST(req: NextRequest) {
       return NextResponse.json({ error: 'Port context required' }, { status: 400 });
     }
 
+    // Server-side phone normalization for older website builds that post raw
+    // international/national strings. Newer builds may pre-fill phoneE164/Country.
+    let phoneE164 = data.phoneE164 ?? null;
+    let phoneCountry: CountryCode | null = (data.phoneCountry as CountryCode | null) ?? null;
+    if (!phoneE164) {
+      const parsed = parsePhone(data.phone, phoneCountry ?? undefined);
+      phoneE164 = parsed.e164;
+      phoneCountry = parsed.country ?? phoneCountry;
+    }
+
     const fullName =
       data.firstName && data.lastName
         ? `${data.firstName} ${data.lastName}`
@@ -68,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;
@@ -96,17 +98,21 @@ export async function POST(req: NextRequest) {
         });
         if (existingClient && existingClient.portId === portId) {
           clientId = existingClient.id;
+          const updates: Partial<typeof clients.$inferInsert> = {};
           if (data.preferredContactMethod) {
-            await tx
+            updates.preferredContactMethod = data.preferredContactMethod;
-              .update(clients)
+          }
-              .set({ preferredContactMethod: data.preferredContactMethod })
+          if (data.nationalityIso && !existingClient.nationalityIso) {
-              .where(eq(clients.id, clientId));
+            updates.nationalityIso = data.nationalityIso;
+          }
+          if (Object.keys(updates).length > 0) {
+            await tx.update(clients).set(updates).where(eq(clients.id, clientId));
           }
         } else {
-          clientId = await createClientInTx(tx, portId, fullName, data);
+          clientId = await createClientInTx(tx, portId, fullName, data, phoneE164, phoneCountry);
         }
       } else {
-        clientId = await createClientInTx(tx, portId, fullName, data);
+        clientId = await createClientInTx(tx, portId, fullName, data, phoneE164, phoneCountry);
       }
 
       // 2. Optional: upsert company + add membership
@@ -128,7 +134,8 @@ export async function POST(req: NextRequest) {
               name: data.company.name,
               legalName: data.company.legalName ?? null,
               taxId: data.company.taxId ?? null,
-              incorporationCountry: data.company.incorporationCountry ?? null,
+              incorporationCountryIso: data.company.incorporationCountryIso ?? null,
+              incorporationSubdivisionIso: data.company.incorporationSubdivisionIso ?? null,
               status: 'active',
             })
             .returning();
@@ -198,9 +205,9 @@ export async function POST(req: NextRequest) {
             label: 'Primary',
             streetAddress: data.address.street ?? null,
             city: data.address.city ?? null,
-            stateProvince: data.address.stateProvince ?? null,
+            subdivisionIso: data.address.subdivisionIso ?? null,
             postalCode: data.address.postalCode ?? null,
-            country: data.address.country ?? null,
+            countryIso: data.address.countryIso ?? null,
             isPrimary: true,
           });
         }
@@ -279,7 +286,9 @@ async function createClientInTx(
   tx: Tx,
   portId: string,
   fullName: string,
-  data: Pick<PublicInterestData, 'email' | 'phone' | 'preferredContactMethod'>,
+  data: Pick<PublicInterestData, 'email' | 'phone' | 'preferredContactMethod' | 'nationalityIso'>,
+  phoneE164: string | null,
+  phoneCountry: CountryCode | null,
 ): Promise<string> {
   const [newClient] = await tx
     .insert(clients)
@@ -287,6 +296,7 @@ async function createClientInTx(
       portId,
       fullName,
       preferredContactMethod: data.preferredContactMethod,
+      nationalityIso: data.nationalityIso ?? null,
       source: 'website',
     })
     .returning();
@@ -303,6 +313,8 @@ async function createClientInTx(
     clientId,
     channel: 'phone',
     value: data.phone,
+    valueE164: phoneE164,
+    valueCountry: phoneCountry,
     isPrimary: false,
   });
 

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

@@ -14,30 +14,27 @@ import {
 import { env } from '@/lib/env';
 import { errorResponse, RateLimitError, ValidationError } from '@/lib/errors';
 import { logger } from '@/lib/logger';
+import { checkRateLimit, rateLimiters } from '@/lib/rate-limit';
 import { publicResidentialInquirySchema } from '@/lib/validators/residential';
 import { emitToRoom } from '@/lib/socket/server';
+import { parsePhone } from '@/lib/i18n/phone';
+import type { CountryCode } from '@/lib/i18n/countries';
 
-// ─── Rate limiter (5 per hour per IP) ────────────────────────────────────────
+/**
-
+ * Throws RateLimitError if the IP has exceeded the public-form quota.
-const ipHits = new Map<string, { count: number; resetAt: number }>();
+ * Backed by the Redis sliding-window limiter so the cap survives restarts
-const WINDOW_MS = 60 * 60 * 1000;
+ * and is shared across worker processes.
-const MAX_HITS = 5;
+ */
-
+async function gateRateLimit(ip: string): Promise<void> {
-function checkRateLimit(ip: string): void {
+  const result = await checkRateLimit(ip, rateLimiters.publicForm);
-  const now = Date.now();
+  if (!result.allowed) {
-  const entry = ipHits.get(ip);
+    const retryAfter = Math.max(1, Math.ceil((result.resetAt - Date.now()) / 1000));
-  if (!entry || now > entry.resetAt) {
+    throw new RateLimitError(retryAfter);
-    ipHits.set(ip, { count: 1, resetAt: now + WINDOW_MS });
-    return;
   }
-  if (entry.count >= MAX_HITS) {
-    throw new RateLimitError(Math.ceil((entry.resetAt - now) / 1000));
-  }
-  entry.count += 1;
 }
 
 /**
- * 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.
@@ -47,7 +44,7 @@ function checkRateLimit(ip: string): void {
 export async function POST(req: NextRequest) {
   try {
     const ip = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? 'unknown';
-    checkRateLimit(ip);
+    await gateRateLimit(ip);
 
     const body = await req.json();
     const data = publicResidentialInquirySchema.parse(body);
@@ -61,6 +58,16 @@ export async function POST(req: NextRequest) {
       throw new ValidationError('Unknown port');
     }
 
+    // If the website didn't pre-normalize, parse server-side. International
+    // strings parse without a hint; national-format submissions need a country.
+    let phoneE164 = data.phoneE164 ?? null;
+    let phoneCountry: CountryCode | null = (data.phoneCountry as CountryCode | null) ?? null;
+    if (!phoneE164) {
+      const parsed = parsePhone(data.phone, phoneCountry ?? undefined);
+      phoneE164 = parsed.e164;
+      phoneCountry = parsed.country ?? phoneCountry;
+    }
+
     const result = await withTransaction(async (tx) => {
       const [client] = await tx
         .insert(residentialClients)
@@ -69,7 +76,13 @@ export async function POST(req: NextRequest) {
           fullName: `${data.firstName.trim()} ${data.lastName.trim()}`.trim(),
           email: data.email,
           phone: data.phone,
+          phoneE164,
+          phoneCountry,
+          nationalityIso: data.nationalityIso ?? null,
+          timezone: data.timezone ?? null,
           placeOfResidence: data.placeOfResidence,
+          placeOfResidenceCountryIso: data.placeOfResidenceCountryIso ?? null,
+          subdivisionIso: data.subdivisionIso ?? null,
           preferredContactMethod: data.preferredContactMethod,
           source: 'website',
           status: 'prospect',
@@ -97,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,
@@ -134,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

@@ -0,0 +1,82 @@
+import { NextResponse } from 'next/server';
+import { sql } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { redis } from '@/lib/redis';
+import { minioClient } from '@/lib/minio';
+import { env } from '@/lib/env';
+
+type CheckStatus = 'ok' | 'error';
+
+interface ReadyChecks {
+  postgres: CheckStatus;
+  redis: CheckStatus;
+  minio: CheckStatus;
+}
+
+interface ReadyResponse {
+  status: 'ready' | 'degraded';
+  checks: ReadyChecks;
+  timestamp: string;
+}
+
+/**
+ * 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).
+ *
+ * Checks:
+ *   - postgres: `SELECT 1` against the primary
+ *   - redis:    `PING`
+ *   - minio:    `bucketExists(<configured-bucket>)`
+ *
+ * Documenso + SMTP are intentionally not probed here: they're optional
+ * integrations, and each tenant configures its own credentials. A
+ * tenant-misconfigured Documenso instance shouldn't deadline the entire
+ * shared CRM.
+ */
+export async function GET(): Promise<NextResponse<ReadyResponse>> {
+  const checks: ReadyChecks = {
+    postgres: 'error',
+    redis: 'error',
+    minio: 'error',
+  };
+
+  await Promise.allSettled([
+    db
+      .execute(sql`SELECT 1`)
+      .then(() => {
+        checks.postgres = 'ok';
+      })
+      .catch(() => {
+        checks.postgres = 'error';
+      }),
+
+    redis
+      .ping()
+      .then(() => {
+        checks.redis = 'ok';
+      })
+      .catch(() => {
+        checks.redis = 'error';
+      }),
+
+    minioClient
+      .bucketExists(env.MINIO_BUCKET)
+      .then(() => {
+        checks.minio = 'ok';
+      })
+      .catch(() => {
+        checks.minio = 'error';
+      }),
+  ]);
+
+  const allReady = Object.values(checks).every((s) => s === 'ok');
+  const status: ReadyResponse['status'] = allReady ? 'ready' : 'degraded';
+
+  return NextResponse.json(
+    { status, checks, timestamp: new Date().toISOString() },
+    { status: allReady ? 200 : 503 },
+  );
+}

src/app/api/v1/admin/ai-budget/route.ts

@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  getAiBudget,
+  setAiBudget,
+  currentPeriodTokens,
+  periodBreakdown,
+} from '@/lib/services/ai-budget.service';
+
+const saveSchema = z.object({
+  enabled: z.boolean().optional(),
+  softCapTokens: z.number().int().nonnegative().max(100_000_000).optional(),
+  hardCapTokens: z.number().int().nonnegative().max(100_000_000).optional(),
+  period: z.enum(['day', 'week', 'month']).optional(),
+});
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const [budget, used, breakdown] = await Promise.all([
+        getAiBudget(ctx.portId),
+        currentPeriodTokens(ctx.portId),
+        periodBreakdown(ctx.portId),
+      ]);
+      return NextResponse.json({ data: { budget, used, breakdown } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PUT = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, saveSchema);
+      const next = await setAiBudget(ctx.portId, body, ctx.userId);
+      return NextResponse.json({ data: next });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

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

@@ -0,0 +1,25 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { runAlertEngineForPorts } from '@/lib/services/alert-engine';
+
+/**
+ * Admin trigger for an immediate alert engine sweep over the caller's port.
+ * Useful for manual ops ("re-evaluate now after I fixed a rule") and
+ * 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.
+ */
+export const POST = withAuth(async (_req, ctx) => {
+  try {
+    if (!ctx.isSuperAdmin) {
+      return NextResponse.json({ error: 'Super admin only' }, { status: 403 });
+    }
+    const summary = await runAlertEngineForPorts([ctx.portId]);
+    return NextResponse.json({ data: summary });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

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

@@ -1,29 +1,76 @@
 import { NextResponse } from 'next/server';
 import { z } from 'zod';
+import { inArray } from 'drizzle-orm';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseQuery } from '@/lib/api/route-helpers';
-import { listAuditLogs } from '@/lib/services/audit.service';
+import { searchAuditLogs } from '@/lib/services/audit-search.service';
+import { db } from '@/lib/db';
+import { user } from '@/lib/db/schema/users';
 import { errorResponse } from '@/lib/errors';
 
 const auditQuerySchema = z.object({
-  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(200).default(50),
-  limit: z.coerce.number().int().min(1).max(100).default(50),
   entityType: z.string().optional(),
   action: z.string().optional(),
   userId: z.string().optional(),
   entityId: z.string().optional(),
   dateFrom: z.string().optional(),
   dateTo: z.string().optional(),
+  /** Free-text query against the tsvector `search_text` column. */
   search: z.string().optional(),
+  /** Cursor pair from the previous page's response. */
+  cursorAt: z.string().optional(),
+  cursorId: z.string().optional(),
 });
 
 export const GET = withAuth(
   withPermission('admin', 'view_audit_log', async (req, ctx) => {
     try {
       const query = parseQuery(req, auditQuerySchema);
-      const result = await listAuditLogs(ctx.portId, query);
+      const cursor =
-      return NextResponse.json(result);
+        query.cursorAt && query.cursorId
+          ? { createdAt: new Date(query.cursorAt), id: query.cursorId }
+          : undefined;
+      const { rows, nextCursor } = await searchAuditLogs({
+        portId: ctx.portId,
+        q: query.search,
+        userId: query.userId,
+        action: query.action,
+        entityType: query.entityType,
+        entityId: query.entityId,
+        from: query.dateFrom ? new Date(query.dateFrom) : undefined,
+        to: query.dateTo ? new Date(query.dateTo) : undefined,
+        cursor,
+        limit: query.limit,
+      });
+
+      // Resolve actor emails in one batched query so the table can show
+      // who did what without N+1 round trips.
+      const userIds = Array.from(
+        new Set(rows.map((r) => r.userId).filter((id): id is string => Boolean(id))),
+      );
+      const userRows = userIds.length
+        ? await db
+            .select({ id: user.id, email: user.email, name: user.name })
+            .from(user)
+            .where(inArray(user.id, userIds))
+        : [];
+      const userMap = new Map(userRows.map((u) => [u.id, u]));
+
+      const data = rows.map((r) => ({
+        ...r,
+        actor: r.userId ? (userMap.get(r.userId) ?? null) : null,
+      }));
+
+      return NextResponse.json({
+        data,
+        pagination: {
+          nextCursor: nextCursor
+            ? { createdAt: nextCursor.createdAt.toISOString(), id: nextCursor.id }
+            : null,
+        },
+      });
     } catch (error) {
       return errorResponse(error);
     }

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/[id]/resend/route.ts

@@ -1,12 +1,18 @@
 import { NextResponse } from 'next/server';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
-import { errorResponse } from '@/lib/errors';
+import { errorResponse, ForbiddenError } from '@/lib/errors';
 import { resendCrmInvite } from '@/lib/services/crm-invite.service';
 
+// Resend mints a fresh token + new email on a global invite row;
+// restrict to super-admins to match revoke/list and avoid cross-tenant
+// re-issuance of foreign-port invitations.
 export const POST = withAuth(
   withPermission('admin', 'manage_users', async (_req, ctx, params) => {
     try {
+      if (!ctx.isSuperAdmin) {
+        throw new ForbiddenError('Resending CRM invites requires super-admin');
+      }
       const id = params.id ?? '';
       const result = await resendCrmInvite(id, {
         userId: ctx.userId,

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

@@ -1,12 +1,18 @@
 import { NextResponse } from 'next/server';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
-import { errorResponse } from '@/lib/errors';
+import { errorResponse, ForbiddenError } from '@/lib/errors';
 import { revokeCrmInvite } from '@/lib/services/crm-invite.service';
 
+// Invites are a global resource (no portId column). Revoking a foreign
+// tenant's pending invite by id would be cross-tenant tampering;
+// restrict to super-admins to match the listing endpoint.
 export const DELETE = withAuth(
   withPermission('admin', 'manage_users', async (_req, ctx, params) => {
     try {
+      if (!ctx.isSuperAdmin) {
+        throw new ForbiddenError('Revoking CRM invites requires super-admin');
+      }
       const id = params.id ?? '';
       await revokeCrmInvite(id, {
         userId: ctx.userId,

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

@@ -3,12 +3,20 @@ import { z } from 'zod';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
+import { errorResponse, ForbiddenError } from '@/lib/errors';
 import { createCrmInvite, listCrmInvites } from '@/lib/services/crm-invite.service';
 
 export const GET = withAuth(
-  withPermission('admin', 'manage_users', async (_req, _ctx) => {
+  withPermission('admin', 'manage_users', async (_req, ctx) => {
     try {
+      // 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
+      // for every other tenant. Restrict the listing to super-admins.
+      if (!ctx.isSuperAdmin) {
+        throw new ForbiddenError('Listing CRM invites requires super-admin');
+      }
       const data = await listCrmInvites();
       return NextResponse.json({ data });
     } catch (error) {
@@ -24,10 +32,17 @@ const createInviteSchema = z.object({
 });
 
 export const POST = withAuth(
-  withPermission('admin', 'manage_users', async (req, _ctx) => {
+  withPermission('admin', 'manage_users', async (req, ctx) => {
     try {
       const body = await parseBody(req, createInviteSchema);
-      const result = await createCrmInvite(body);
+      // Only existing super-admins can mint super-admin invitations. The
+      // manage_users permission is granted to port-scoped director roles,
+      // which must not be able to elevate themselves cross-tenant by
+      // inviting a fresh super_admin.
+      if (body.isSuperAdmin && !ctx.isSuperAdmin) {
+        throw new ForbiddenError('Only super admins can mint super-admin invitations');
+      }
+      const result = await createCrmInvite({ ...body, invitedBy: ctx });
       return NextResponse.json({ data: result }, { status: 201 });
     } catch (error) {
       return errorResponse(error);

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

@@ -0,0 +1,72 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { getPublicOcrConfig, saveOcrConfig, OCR_MODELS } from '@/lib/services/ocr-config.service';
+
+const saveSchema = z.object({
+  /** When 'global', requires super_admin and stores at port_id=null. */
+  scope: z.enum(['port', 'global']),
+  provider: z.enum(['openai', 'claude']),
+  model: z.string().min(1),
+  apiKey: z.string().optional(),
+  clearApiKey: z.boolean().optional(),
+  useGlobal: z.boolean().optional(),
+  aiEnabled: z.boolean().optional(),
+});
+
+// Only role tiers that hold `admin.manage_settings` (director / super_admin)
+// may read or write the OCR config: the apiKey is stored encrypted but is
+// passed straight into the receipt-scan handler, so a swapped key would
+// exfiltrate every subsequent receipt image to whatever endpoint that key
+// authenticates with.
+export const GET = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const url = new URL(req.url);
+      const scope = url.searchParams.get('scope') ?? 'port';
+      if (scope === 'global' && !ctx.isSuperAdmin) {
+        return NextResponse.json({ error: 'Super admin only' }, { status: 403 });
+      }
+      const config = await getPublicOcrConfig(scope === 'global' ? null : ctx.portId);
+      return NextResponse.json({ data: config, models: OCR_MODELS });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PUT = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, saveSchema);
+      if (body.scope === 'global' && !ctx.isSuperAdmin) {
+        return NextResponse.json({ error: 'Super admin only' }, { status: 403 });
+      }
+      const validModels = OCR_MODELS[body.provider];
+      if (!validModels.includes(body.model)) {
+        return NextResponse.json(
+          { error: `Invalid model for provider ${body.provider}` },
+          { status: 400 },
+        );
+      }
+      await saveOcrConfig(
+        body.scope === 'global' ? null : ctx.portId,
+        {
+          provider: body.provider,
+          model: body.model,
+          apiKey: body.apiKey,
+          clearApiKey: body.clearApiKey,
+          useGlobal: body.useGlobal,
+          aiEnabled: body.aiEnabled,
+        },
+        ctx.userId,
+      );
+      return NextResponse.json({ ok: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

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

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { OCR_MODELS } from '@/lib/services/ocr-config.service';
+import { testProvider } from '@/lib/services/ocr-providers';
+
+const schema = z.object({
+  provider: z.enum(['openai', 'claude']),
+  model: z.string().min(1),
+  apiKey: z.string().min(1),
+});
+
+// `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) => {
+    try {
+      const body = await parseBody(req, schema);
+      if (!OCR_MODELS[body.provider].includes(body.model)) {
+        return NextResponse.json({ error: 'Invalid model' }, { status: 400 });
+      }
+      const result = await testProvider(body.provider, body.apiKey, body.model);
+      return NextResponse.json(result);
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

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

@@ -4,11 +4,25 @@ import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
 import { getPort, updatePort } from '@/lib/services/ports.service';
 import { updatePortSchema } from '@/lib/validators/ports';
-import { errorResponse } from '@/lib/errors';
+import { errorResponse, ForbiddenError } from '@/lib/errors';
+
+/**
+ * Non-super-admin callers (e.g. port directors holding admin.manage_settings)
+ * may only read/mutate THEIR OWN port row. The path id is therefore
+ * compared against ctx.portId and a foreign target is rejected before the
+ * service is touched. Super-admins retain unrestricted access.
+ */
+function assertPortInScope(targetPortId: string, ctx: { portId: string; isSuperAdmin: boolean }) {
+  if (ctx.isSuperAdmin) return;
+  if (targetPortId !== ctx.portId) {
+    throw new ForbiddenError('Cross-tenant port access denied');
+  }
+}
 
 export const GET = withAuth(
-  withPermission('admin', 'manage_settings', async (_req, _ctx, params) => {
+  withPermission('admin', 'manage_settings', async (_req, ctx, params) => {
     try {
+      assertPortInScope(params.id!, ctx);
       const data = await getPort(params.id!);
       return NextResponse.json({ data });
     } catch (error) {
@@ -20,6 +34,7 @@ export const GET = withAuth(
 export const PATCH = withAuth(
   withPermission('admin', 'manage_settings', async (req, ctx, params) => {
     try {
+      assertPortInScope(params.id!, ctx);
       const body = await parseBody(req, updatePortSchema);
       const data = await updatePort(params.id!, body, {
         userId: ctx.userId,

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

@@ -4,11 +4,18 @@ import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
 import { listPorts, createPort } from '@/lib/services/ports.service';
 import { createPortSchema } from '@/lib/validators/ports';
-import { errorResponse } from '@/lib/errors';
+import { errorResponse, ForbiddenError } from '@/lib/errors';
 
+// Listing every tenant and creating new tenants are super-admin operations:
+// a port director must not be able to enumerate other ports (target
+// discovery for cross-tenant attacks) or spin up new tenants whose admin
+// they implicitly become.
 export const GET = withAuth(
-  withPermission('admin', 'manage_settings', async () => {
+  withPermission('admin', 'manage_settings', async (_req, ctx) => {
     try {
+      if (!ctx.isSuperAdmin) {
+        throw new ForbiddenError('Listing all ports requires super-admin');
+      }
       const data = await listPorts();
       return NextResponse.json({ data });
     } catch (error) {
@@ -20,6 +27,9 @@ export const GET = withAuth(
 export const POST = withAuth(
   withPermission('admin', 'manage_settings', async (req, ctx) => {
     try {
+      if (!ctx.isSuperAdmin) {
+        throw new ForbiddenError('Creating ports requires super-admin');
+      }
       const body = await parseBody(req, createPortSchema);
       const data = await createPort(body, {
         userId: ctx.userId,

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(
+function substituteInDoc(node: TipTapNode, data: Record<string, string>): TipTapNode {
-  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/ai/email-draft/[jobId]/route.ts

@@ -4,14 +4,17 @@ import { withAuth } from '@/lib/api/helpers';
 import { getEmailDraftResult } from '@/lib/services/email-draft.service';
 import { errorResponse } from '@/lib/errors';
 
-export const GET = withAuth(async (_req, _ctx, params) => {
+export const GET = withAuth(async (_req, ctx, params) => {
   try {
     const { jobId } = params;
     if (!jobId) {
       return NextResponse.json({ error: 'jobId is required' }, { status: 400 });
     }
 
-    const result = await getEmailDraftResult(jobId);
+    const result = await getEmailDraftResult(jobId, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+    });
 
     if (result === null) {
       return NextResponse.json({ status: 'processing' });

src/app/api/v1/alerts/[id]/acknowledge/route.ts

@@ -0,0 +1,11 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { acknowledgeAlert } from '@/lib/services/alerts.service';
+
+export const POST = withAuth(async (_req, ctx, params) => {
+  const id = params.id;
+  if (!id) return NextResponse.json({ error: 'Missing id' }, { status: 400 });
+  await acknowledgeAlert(id, ctx.portId, ctx.userId);
+  return NextResponse.json({ ok: true });
+});

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

@@ -0,0 +1,11 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { dismissAlert } from '@/lib/services/alerts.service';
+
+export const POST = withAuth(async (_req, ctx, params) => {
+  const id = params.id;
+  if (!id) return NextResponse.json({ error: 'Missing id' }, { status: 400 });
+  await dismissAlert(id, ctx.portId, ctx.userId);
+  return NextResponse.json({ ok: true });
+});

src/app/api/v1/alerts/count/route.ts

@@ -0,0 +1,24 @@
+import { NextResponse } from 'next/server';
+import { and, eq, isNull, sql } from 'drizzle-orm';
+
+import { withAuth } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { alerts } from '@/lib/db/schema/insights';
+
+export const GET = withAuth(async (_req, ctx) => {
+  const rows = await db
+    .select({ severity: alerts.severity, count: sql<number>`count(*)::int` })
+    .from(alerts)
+    .where(
+      and(eq(alerts.portId, ctx.portId), isNull(alerts.resolvedAt), isNull(alerts.dismissedAt)),
+    )
+    .groupBy(alerts.severity);
+
+  const bySeverity = { info: 0, warning: 0, critical: 0 } as Record<string, number>;
+  let total = 0;
+  for (const r of rows) {
+    bySeverity[r.severity] = r.count;
+    total += r.count;
+  }
+  return NextResponse.json({ total, bySeverity });
+});

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

@@ -0,0 +1,26 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { listAlertsForPort } from '@/lib/services/alerts.service';
+
+type AlertStatus = 'open' | 'dismissed' | 'resolved';
+
+export const GET = withAuth(async (req: NextRequest, ctx) => {
+  const url = new URL(req.url);
+  const status = (url.searchParams.get('status') ?? 'open') as AlertStatus;
+
+  const rows = await listAlertsForPort(ctx.portId, {
+    includeDismissed: status !== 'open',
+    includeResolved: status !== 'open',
+  });
+
+  // Filter to the requested status bucket so callers don't see overlap.
+  const filtered = rows.filter((a) => {
+    if (status === 'open') return !a.dismissedAt && !a.resolvedAt;
+    if (status === 'dismissed') return Boolean(a.dismissedAt) && !a.resolvedAt;
+    if (status === 'resolved') return Boolean(a.resolvedAt);
+    return true;
+  });
+
+  return NextResponse.json({ data: filtered });
+});

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

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

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

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

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

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

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

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

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

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

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

@@ -8,7 +8,7 @@ import { reorderWaitingListSchema } from '@/lib/validators/interests';
 import { getWaitingList, updateWaitingList } from '@/lib/services/berths.service';
 import { errorResponse, NotFoundError } from '@/lib/errors';
 import { db } from '@/lib/db';
-import { berthWaitingList } from '@/lib/db/schema/berths';
+import { berths, berthWaitingList } from '@/lib/db/schema/berths';
 
 // GET /api/v1/berths/[id]/waiting-list
 export const GET = withAuth(
@@ -40,18 +40,24 @@ 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 {
       const body = await parseBody(req, reorderWaitingListSchema);
       const berthId = params.id!;
 
+      // Tenant scope: refuse to reorder a foreign-port berth's waiting
+      // list. The route's URL id and the entry id are otherwise enough
+      // for any user with manage_waiting_list to mutate any tenant's
+      // queue ordering.
+      const berthRow = await db.query.berths.findFirst({
+        where: and(eq(berths.id, berthId), eq(berths.portId, ctx.portId)),
+      });
+      if (!berthRow) throw new NotFoundError('Berth');
+
       const entry = await db.query.berthWaitingList.findFirst({
-        where: and(
+        where: and(eq(berthWaitingList.id, body.entryId), eq(berthWaitingList.berthId, berthId)),
-          eq(berthWaitingList.id, body.entryId),
-          eq(berthWaitingList.berthId, berthId),
-        ),
       });
       if (!entry) throw new NotFoundError('Waiting list entry');
 

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

@@ -1,15 +1,17 @@
 import { NextResponse } from 'next/server';
 
-import { withAuth } from '@/lib/api/helpers';
+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(async (req, ctx) => {
+export const GET = withAuth(
-  try {
+  withPermission('berths', 'view', async (req, ctx) => {
-    const options = await getBerthOptions(ctx.portId);
+    try {
-    return NextResponse.json({ data: options });
+      const options = await getBerthOptions(ctx.portId);
-  } catch (error) {
+      return NextResponse.json({ data: options });
-    return errorResponse(error);
+    } catch (error) {
-  }
+      return errorResponse(error);
-});
+    }
+  }),
+);

src/app/api/v1/clients/[id]/addresses/[addressId]/route.ts

@@ -0,0 +1,51 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { updateClientAddress, removeClientAddress } from '@/lib/services/clients.service';
+import { optionalCountryIsoSchema, optionalSubdivisionIsoSchema } from '@/lib/validators/i18n';
+
+const updateAddressSchema = z.object({
+  label: z.string().min(1).max(80).optional(),
+  streetAddress: z.string().max(500).optional().nullable(),
+  city: z.string().max(120).optional().nullable(),
+  subdivisionIso: optionalSubdivisionIsoSchema.optional(),
+  postalCode: z.string().max(40).optional().nullable(),
+  countryIso: optionalCountryIsoSchema.optional(),
+  isPrimary: z.boolean().optional(),
+});
+
+export const PATCH = withAuth(
+  withPermission('clients', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateAddressSchema);
+      const row = await updateClientAddress(params.addressId!, params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('clients', 'edit', async (req, ctx, params) => {
+    try {
+      await removeClientAddress(params.addressId!, params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

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

@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listClientAddresses, addClientAddress } from '@/lib/services/clients.service';
+import { optionalCountryIsoSchema, optionalSubdivisionIsoSchema } from '@/lib/validators/i18n';
+
+const addAddressSchema = z.object({
+  label: z.string().min(1).max(80).optional(),
+  streetAddress: z.string().max(500).optional().nullable(),
+  city: z.string().max(120).optional().nullable(),
+  subdivisionIso: optionalSubdivisionIsoSchema.optional(),
+  postalCode: z.string().max(40).optional().nullable(),
+  countryIso: optionalCountryIsoSchema.optional(),
+  isPrimary: z.boolean().optional(),
+});
+
+export const GET = withAuth(
+  withPermission('clients', 'view', async (req, ctx, params) => {
+    try {
+      const rows = await listClientAddresses(params.id!, ctx.portId);
+      return NextResponse.json({ data: rows });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('clients', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, addAddressSchema);
+      const row = await addClientAddress(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/clients/[id]/contacts/[contactId]/route.ts

@@ -5,10 +5,13 @@ import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
 import { errorResponse } from '@/lib/errors';
 import { updateContact, removeContact } from '@/lib/services/clients.service';
+import { optionalCountryIsoSchema, optionalPhoneE164Schema } from '@/lib/validators/i18n';
 
 const updateContactSchema = z.object({
   channel: z.enum(['email', 'phone', 'whatsapp', 'other']).optional(),
   value: z.string().min(1).optional(),
+  valueE164: optionalPhoneE164Schema.optional(),
+  valueCountry: optionalCountryIsoSchema.optional(),
   label: z.string().optional(),
   isPrimary: z.boolean().optional(),
   notes: z.string().optional(),
@@ -18,18 +21,12 @@ export const PATCH = withAuth(
   withPermission('clients', 'edit', async (req, ctx, params) => {
     try {
       const body = await parseBody(req, updateContactSchema);
-      const contact = await updateContact(
+      const contact = await updateContact(params.contactId!, params.id!, ctx.portId, body, {
-        params.contactId!,
+        userId: ctx.userId,
-        params.id!,
+        portId: ctx.portId,
-        ctx.portId,
+        ipAddress: ctx.ipAddress,
-        body,
+        userAgent: ctx.userAgent,
-        {
+      });
-          userId: ctx.userId,
-          portId: ctx.portId,
-          ipAddress: ctx.ipAddress,
-          userAgent: ctx.userAgent,
-        },
-      );
       return NextResponse.json({ data: contact });
     } catch (error) {
       return errorResponse(error);

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

@@ -5,10 +5,13 @@ import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
 import { errorResponse } from '@/lib/errors';
 import { listContacts, addContact } from '@/lib/services/clients.service';
+import { optionalCountryIsoSchema, optionalPhoneE164Schema } from '@/lib/validators/i18n';
 
 const addContactSchema = z.object({
   channel: z.enum(['email', 'phone', 'whatsapp', 'other']),
   value: z.string().min(1),
+  valueE164: optionalPhoneE164Schema.optional(),
+  valueCountry: optionalCountryIsoSchema.optional(),
   label: z.string().optional(),
   isPrimary: z.boolean().optional().default(false),
   notes: z.string().optional(),