test(visual): regression baselines for stable list/landing pages

New `visual` project covers six low-volatility screens — portal login,
dashboard, and the four core lists (clients/yachts/berths/invoices) —
with full-page screenshots that diff to a 2% pixel-ratio tolerance.
Animations and the cursor caret are disabled inline so transient
rendering doesn't trigger flaky diffs.

Detail screens (yacht detail, EOI dialog, invoice form steps) are
intentionally deferred until we have stable per-id fixtures so
snapshots don't drift with seed data.

Regenerate with: pnpm exec playwright test --project=visual --update-snapshots

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

.claude/scheduled_tasks.lock

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

.gitattributes

@@ -0,0 +1,30 @@
+# Normalize line endings on commit; check out LF on every OS.
+* text=auto eol=lf
+
+# Binary files — never touch line endings.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.webp binary
+*.pdf binary
+*.zip binary
+*.gz binary
+*.tar binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.otf binary
+*.eot binary
+*.mp4 binary
+*.mov binary
+*.wasm binary
+
+# Shell scripts must stay LF regardless.
+*.sh text eol=lf
+
+# Windows batch / PowerShell must stay CRLF.
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf

.gitignore

@@ -17,3 +17,7 @@ playwright-report/
 nginx/certs/
 tsconfig.tsbuildinfo
 .playwright-mcp/
+docker-compose.override.yml
+.remember/
+.DS_Store
+eoi/

07-DATABASE-SCHEMA.md

@@ -20,16 +20,42 @@
 
 ### Client Domain
 
-- `clients` — Anchor records for people/entities
+- `clients` — Anchor records for people/entities. Yacht and company details
+  are no longer stored here — see the Yacht and Company domains.
 - `client_contacts` — Multi-channel contact entries per client
+- `client_addresses` — Physical addresses per client (primary + others)
 - `client_relationships` — Relationships between clients (referrals, broker, family)
 - `client_notes` — Timestamped notes on clients
 - `client_tags` — Tags assigned to clients
 - `client_merge_log` — Audit trail of client merges
 
+### Yacht Domain
+
+- `yachts` — First-class yacht records. Polymorphic ownership via
+  `current_owner_type` (`'client' | 'company'`) + `current_owner_id`.
+- `yacht_ownership_history` — Append-only log of every transfer; partial
+  unique index `idx_yoh_active` enforces a single active owner per yacht.
+- `yacht_notes`, `yacht_tags` — Notes / tags on yachts.
+
+### Company Domain
+
+- `companies` — Legal entities that may own yachts or be billed.
+- `company_addresses` — Addresses per company.
+- `company_memberships` — Active client ↔ company links with role
+  (director / shareholder / beneficial_owner / authorised_signatory),
+  start/end dates.
+
+### Reservation Domain
+
+- `berth_reservations` — Concrete client + yacht + berth holds with
+  start/end dates and status. Partial unique index `idx_br_active`
+  enforces one active reservation per berth.
+
 ### Interest Domain
 
-- `interests` — Per-berth pipeline records, each belonging to a client (milestone dates are inline columns)
+- `interests` — Per-berth pipeline records. Each row references a
+  `client_id`, `yacht_id` (the yacht in scope for the inquiry), and
+  optional `berth_id`. Milestone dates are inline columns.
 - `interest_notes` — Timestamped notes on interests
 - `interest_tags` — Tags assigned to interests
 

CLAUDE.md

@@ -70,10 +70,13 @@ src/
 - **Formatting:** Prettier - single quotes, semicolons, trailing commas, 2-space indent, 100 char line width.
 - **Lint:** ESLint flat config extending `next/core-web-vitals`, `next/typescript`, `prettier`. Unused vars prefixed with `_` are allowed.
 - **Imports:** Use `@/*` path alias (maps to `src/*`).
-- **Components:** shadcn/ui pattern - base components in `src/components/ui/`, domain components in `src/components/[domain]/`.
+- **Components:** shadcn/ui pattern - base components in `src/components/ui/`, domain components in `src/components/[domain]/`. Yacht / company / reservation domains live in `components/yachts`, `components/companies`, `components/reservations` respectively.
-- **DB schema:** One file per domain in `src/lib/db/schema/`, re-exported from `index.ts`. Relations in `relations.ts`.
+- **DB schema:** One file per domain in `src/lib/db/schema/`, re-exported from `index.ts`. Relations in `relations.ts`. Domain files include `clients.ts`, `yachts.ts`, `companies.ts`, `reservations.ts`, `interests.ts`, `berths.ts`, `documents.ts`, `invoices.ts`, etc.
+- **Polymorphic ownership:** Yachts and invoice billing-entities use `<entity>_type` + `<entity>_id` column pairs (`'client' | 'company'`). Resolve owner identity through `src/lib/services/yachts.service.ts` / `eoi-context.ts` rather than reading the columns ad hoc — those services apply the type discriminator.
+- **EOI generation:** Two pathways share the same `EoiContext` (`src/lib/services/eoi-context.ts`). Documenso pathway calls the template-generate endpoint via `documenso-payload.ts`; in-app pathway fills the same source PDF (`assets/eoi-template.pdf`) via `src/lib/pdf/fill-eoi-form.ts` (pdf-lib AcroForm). Routed through `generateAndSign(...)` in `src/lib/services/document-templates.ts` with a `pathway` parameter.
+- **Merge fields:** Token catalog lives in `src/lib/templates/merge-fields.ts`; the `createTemplateSchema` validator uses `VALID_MERGE_TOKENS` as an allow-list, so unknown tokens are rejected at template creation time.
 - **Routes:** Multi-tenant via `[portSlug]` dynamic segment. Typed routes enabled.
-- **Pre-commit:** Husky + lint-staged runs ESLint fix + Prettier on staged `.ts`/`.tsx` files.
+- **Pre-commit:** Husky + lint-staged runs ESLint fix + Prettier on staged `.ts`/`.tsx` files. The hook also blocks `.env*` files (including `.env.example`) from being committed; pass them via a separate workflow if needed.
 
 ## Environment
 
@@ -89,3 +92,11 @@ Copy `.env.example` to `.env` for local dev. See `src/lib/env.ts` for the full s
 ## Architecture docs
 
 Numbered spec files in repo root (`01-CONSOLIDATED-SYSTEM-SPEC.md` through `15-DESIGN-TOKENS.md`) contain detailed architecture decisions, feature specs, DB schema docs, API catalog, and implementation sequence.
+
+Domain-specific references:
+
+- `docs/eoi-documenso-field-mapping.md` — canonical mapping from `EoiContext`
+  paths to the Documenso template's `formValues` keys, with the matching
+  AcroForm field names used by the in-app pathway.
+- `assets/README.md` — what the in-app EOI source PDF must contain and how
+  to override its path in dev/test.

PROGRESS.md

@@ -1,12 +1,22 @@
 # Port Nimara CRM - Project Progress
 
-**Last updated:** 2026-03-26
+**Last updated:** 2026-04-22
 **Repo:** https://code.letsbe.solutions/letsbe/pn-new-crm
 **Domain:** pn.letsbe.solutions
 **Stack:** Next.js 15 + TypeScript + Tailwind + Drizzle ORM + PostgreSQL + Redis + BullMQ + MinIO + Socket.io
 
 ---
 
+## Since 2026-03-26
+
+- **Admin surface expanded** — full admin users + roles management, admin ports + system settings management, user settings, expanded audit log, and berth CRUD completions.
+- **Reminders system** — promoted from "pages only" to full CRUD with background processors.
+- **Multi-address clients** — new `client_addresses` table with a partial unique index enforcing one primary address per client.
+- **Inquiry notifications feature (end-to-end)** — public interest form now fires: (a) confirmation email to the inquiring client, (b) in-app notifications to CRM users with `interests.view`, (c) optional email to configured sales recipients. Public schema expanded with first/last name split, address block, and berth mooring lookup. `sendEmail` gained a plain-text fallback. Admin settings UI exposes `inquiry_contact_email` and `inquiry_notification_recipients`. Plan: `docs/superpowers/plans/2026-04-14-inquiry-notifications.md`.
+- **Build/infra cleanup** — Next.js 15 static-prerender bugs fixed (Suspense boundaries around `useSearchParams` on `/portal/verify` and `/set-password`), `.gitattributes` added to enforce LF in the index across Windows/macOS checkouts, Docker production build fixes, CI trimmed to build+push (deploy job removed).
+
+---
+
 ## What's Been Built (Layers 0-4 Complete)
 
 ### Layer 0: Foundation (DONE)
@@ -80,8 +90,10 @@
   - API: `/api/v1/notifications/...` (CRUD, preferences, read-all, unread-count)
   - Service: `notifications.service.ts`
   - Components: `src/components/notifications/`
-- [x] **Reminders** - Reminder pages
+- [x] **Reminders** - Full CRUD with background processors (dispatcher, reminder workers)
   - Pages: `/reminders`
+  - API: `/api/v1/reminders/...` (CRUD, my, overdue, upcoming, complete, dismiss, snooze)
+  - Service: `reminders.service.ts`
 - [x] **Search** - Global search (inline in topbar), saved views
   - API: `/api/v1/search/...`, `/api/v1/saved-views/...`
   - Service: `search.service.ts`, `saved-views.service.ts`
@@ -178,11 +190,12 @@
 
 ### Priority 1: Deployment & Go-Live
 
-- [ ] Push to Gitea and verify CI/CD pipeline builds
+- [x] Push to Gitea (origin/main at `9d815c4` as of 2026-04-22)
+- [ ] Verify CI/CD pipeline builds the latest image and pushes to the Gitea container registry
 - [ ] Set up server: install Docker, nginx, configure DNS for `pn.letsbe.solutions`
 - [ ] Run `certbot --nginx -d pn.letsbe.solutions` for SSL
 - [ ] Configure production `.env` on server
-- [ ] Run database migrations (`pnpm db:push`)
+- [ ] Run database migrations (`drizzle-kit migrate` against prod DB — `0000` + `0001` need to apply)
 - [ ] Run seed data (`pnpm db:seed`)
 - [ ] Verify all services start and health check passes
 

assets/README.md

@@ -0,0 +1,48 @@
+# `assets/`
+
+Server-side runtime assets bundled by Next.js (via `outputFileTracingIncludes`
+in `next.config.ts`). These files are read with `fs.readFile` from
+`process.cwd()` at runtime, so they are NOT served as public URLs — use
+`public/` for that.
+
+## `eoi-template.pdf`
+
+The source PDF used by the in-app EOI generation pathway
+(`src/lib/pdf/fill-eoi-form.ts`). It must be the **same** PDF that the
+Documenso EOI template uploads, so both pathways produce equivalent
+documents.
+
+The PDF must contain AcroForm fields with these exact names (mirroring the
+Documenso template's `formValues` keys — see
+`docs/eoi-documenso-field-mapping.md`):
+
+| Field name     | Type     | Filled with                                           |
+| -------------- | -------- | ----------------------------------------------------- |
+| `Name`         | Text     | `EoiContext.client.fullName`                          |
+| `Email`        | Text     | `EoiContext.client.primaryEmail`                      |
+| `Address`      | Text     | `street, city, country`                               |
+| `Yacht Name`   | Text     | `EoiContext.yacht.name`                               |
+| `Length`       | Text     | `EoiContext.yacht.lengthFt`                           |
+| `Width`        | Text     | `EoiContext.yacht.widthFt`                            |
+| `Draft`        | Text     | `EoiContext.yacht.draftFt`                            |
+| `Berth Number` | Text     | `EoiContext.berth.mooringNumber`                      |
+| `Lease_10`     | Checkbox | always `false` (legacy default — Purchase, not Lease) |
+| `Purchase`     | Checkbox | always `true`                                         |
+
+Form fields stay interactive after generation (not flattened), so the
+recipient can still tweak values before signing if the in-app pathway is
+followed by a Documenso send.
+
+### Override path
+
+In dev/test, set `EOI_TEMPLATE_PDF_PATH=/abs/path/to/your/template.pdf` to
+point at a different file (e.g. a fixture).
+
+### How to extract this PDF
+
+The legacy flow uploads this PDF to Documenso template ID 8. To get the
+exact bytes:
+
+1. In Documenso, open the EOI template.
+2. Download the source PDF.
+3. Drop it here as `eoi-template.pdf`.

docs/eoi-documenso-field-mapping.md

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

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

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

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

@@ -1,564 +0,0 @@
-# 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.

next.config.ts

@@ -18,6 +18,12 @@ const nextConfig: NextConfig = {
   experimental: {
     typedRoutes: true,
   },
+  outputFileTracingIncludes: {
+    // Bundle the EOI source PDF so the in-app EOI pathway can read it at
+    // runtime in the standalone build. Reading via fs.readFile from
+    // process.cwd() requires the file to be traced explicitly.
+    '/api/v1/document-templates/**': ['./assets/eoi-template.pdf'],
+  },
 };
 
 export default nextConfig;

package.json

@@ -14,6 +14,10 @@
     "db:push": "drizzle-kit push",
     "db:studio": "drizzle-kit studio",
     "db:seed": "tsx src/lib/db/seed.ts",
+    "test:e2e": "playwright test",
+    "test:e2e:smoke": "playwright test --project=smoke",
+    "test:e2e:exhaustive": "playwright test --project=exhaustive",
+    "test:e2e:destructive": "playwright test --project=destructive",
     "prepare": "husky"
   },
   "dependencies": {
@@ -65,6 +69,7 @@
     "next-themes": "^0.4.0",
     "nodemailer": "^6.9.0",
     "openai": "^6.27.0",
+    "pdf-lib": "^1.17.1",
     "pino": "^9.5.0",
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
@@ -91,9 +96,9 @@
     "@types/react-dom": "^19.0.0",
     "@vitest/coverage-v8": "^4.1.0",
     "autoprefixer": "^10.4.27",
-    "esbuild": "^0.25.0",
     "dotenv": "^17.3.1",
     "drizzle-kit": "^0.30.0",
+    "esbuild": "^0.25.0",
     "eslint": "^9.0.0",
     "eslint-config-next": "15.1.0",
     "eslint-config-prettier": "^9.1.0",

playwright.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig, devices } from '@playwright/test';
 
 export default defineConfig({
-  testDir: './tests/e2e/smoke',
+  testDir: './tests/e2e',
   fullyParallel: false,
   forbidOnly: !!process.env.CI,
   retries: 0,
@@ -22,11 +22,53 @@ export default defineConfig({
   projects: [
     {
       name: 'setup',
-      testMatch: /global-setup\.ts/,
+      testMatch: /smoke\/global-setup\.ts/,
     },
     {
       name: 'smoke',
-      testMatch: /\d{2}-.*\.spec\.ts/,
+      testMatch: /smoke\/\d{2}-.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        ...devices['Desktop Chrome'],
+        viewport: { width: 1440, height: 900 },
+      },
+    },
+    {
+      name: 'exhaustive',
+      testMatch: /exhaustive\/.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        ...devices['Desktop Chrome'],
+        viewport: { width: 1440, height: 900 },
+      },
+    },
+    {
+      name: 'destructive',
+      testMatch: /destructive\/.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        ...devices['Desktop Chrome'],
+        viewport: { width: 1440, height: 900 },
+      },
+    },
+    {
+      // Real-API tests hit live external services (Documenso, IMAP, etc.).
+      // Opt-in only: pnpm exec playwright test --project=realapi
+      name: 'realapi',
+      testMatch: /realapi\/.*\.spec\.ts/,
+      dependencies: ['setup'],
+      timeout: 120_000,
+      use: {
+        ...devices['Desktop Chrome'],
+        viewport: { width: 1440, height: 900 },
+      },
+    },
+    {
+      // Visual regression baselines. Regenerate with --update-snapshots after
+      // intentional UI changes; otherwise pnpm exec playwright test --project=visual
+      // diffs against the committed PNGs.
+      name: 'visual',
+      testMatch: /visual\/.*\.spec\.ts/,
       dependencies: ['setup'],
       use: {
         ...devices['Desktop Chrome'],

pnpm-lock.yaml

@@ -152,6 +152,9 @@ importers:
       openai:
         specifier: ^6.27.0
         version: 6.27.0(ws@8.18.3)(zod@3.25.76)
+      pdf-lib:
+        specifier: ^1.17.1
+        version: 1.17.1
       pino:
         specifier: ^9.5.0
         version: 9.14.0
@@ -4417,6 +4420,9 @@ packages:
   pathe@2.0.3:
     resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
 
+  pdf-lib@1.17.1:
+    resolution: {integrity: sha512-V/mpyJAoTsN4cnP31vc0wfNA1+p20evqqnap0KLoRUN0Yk/p3wN52DOEsL4oBFcLdb76hlpKPtzJIgo67j/XLw==}
+
   peberminta@0.9.0:
     resolution: {integrity: sha512-XIxfHpEuSJbITd1H3EeQwpcZbTLHc+VVr8ANI9t5sit565tsI4/xK3KWTUFE2e6QiangUkh3B0jihzmGnNrRsQ==}
 
@@ -5375,6 +5381,9 @@ packages:
   tsconfig-paths@3.15.0:
     resolution: {integrity: sha512-2Ac2RgzDe/cn48GvOe3M+o82pEFewD3UPbyoUHHdKasHwJKjds4fLXWf/Ux5kATBKN20oaFGu+jbElp1pos0mg==}
 
+  tslib@1.14.1:
+    resolution: {integrity: sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==}
+
   tslib@2.8.1:
     resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
 
@@ -9668,6 +9677,13 @@ snapshots:
 
   pathe@2.0.3: {}
 
+  pdf-lib@1.17.1:
+    dependencies:
+      '@pdf-lib/standard-fonts': 1.0.0
+      '@pdf-lib/upng': 1.0.1
+      pako: 1.0.11
+      tslib: 1.14.1
+
   peberminta@0.9.0: {}
 
   performance-now@2.1.0: {}
@@ -10843,6 +10859,8 @@ snapshots:
       minimist: 1.2.8
       strip-bom: 3.0.0
 
+  tslib@1.14.1: {}
+
   tslib@2.8.1: {}
 
   tsx@4.21.0:

scripts/dev-imap-probe.ts

@@ -0,0 +1,66 @@
+/**
+ * Dev diagnostic: connect to IMAP and print the most recent ~10 messages,
+ * showing TO/FROM/subject/date so we can see what the dev mailbox is
+ * actually receiving.
+ *
+ * Run: pnpm tsx scripts/dev-imap-probe.ts
+ */
+
+import 'dotenv/config';
+import { ImapFlow } from 'imapflow';
+import { simpleParser } from 'mailparser';
+
+async function main(): Promise<void> {
+  const host = process.env.IMAP_HOST!;
+  const port = Number(process.env.IMAP_PORT ?? 993);
+  const user = process.env.IMAP_USER!;
+  const pass = process.env.IMAP_PASS!;
+
+  if (!host || !user || !pass) {
+    throw new Error('IMAP_HOST / IMAP_USER / IMAP_PASS not set');
+  }
+
+  console.log(`Connecting to ${user}@${host}:${port}…`);
+  const client = new ImapFlow({
+    host,
+    port,
+    secure: port === 993,
+    auth: { user, pass },
+    logger: false,
+  });
+
+  await client.connect();
+  console.log('Connected. Inbox status:');
+  const lock = await client.getMailboxLock('INBOX');
+  try {
+    const status = await client.status('INBOX', { messages: true, recent: true });
+    console.log('  total:', status.messages, '| recent:', status.recent);
+
+    // Pull the last 10 by UID
+    const since = new Date(Date.now() - 30 * 60 * 1000); // last 30 min
+    const result = await client.search({ since });
+    const uids = Array.isArray(result) ? result.slice(-10).reverse() : [];
+    console.log(`Found ${uids.length} messages in last 30min:`);
+    for (const uid of uids) {
+      const msg = await client.fetchOne(String(uid), { source: true, envelope: true });
+      if (!msg || !msg.source) continue;
+      const parsed = await simpleParser(msg.source);
+      const tos = (Array.isArray(parsed.to) ? parsed.to : parsed.to ? [parsed.to] : [])
+        .flatMap((a) => a.value.map((v) => v.address ?? ''))
+        .join(', ');
+      console.log(
+        `  uid=${uid}  date=${parsed.date?.toISOString()}  from=${parsed.from?.text}  to=${tos}  subject=${parsed.subject}`,
+      );
+    }
+  } finally {
+    lock.release();
+  }
+  await client.logout();
+  console.log('Done.');
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Probe failed:', err);
+  process.exit(1);
+});

scripts/dev-trigger-portal-invite.ts

@@ -0,0 +1,59 @@
+/**
+ * Dev-only helper: pick an existing client and trigger a portal-invite email.
+ * The activation email gets routed to EMAIL_REDIRECT_TO (set in .env) regardless
+ * of the per-portal-user `email` field — so we can use any throwaway address
+ * here without conflicting with seed data.
+ *
+ * Run: pnpm tsx scripts/dev-trigger-portal-invite.ts
+ */
+
+import 'dotenv/config';
+
+import { db } from '@/lib/db';
+import { clients } from '@/lib/db/schema/clients';
+import { portalUsers } from '@/lib/db/schema/portal';
+import { createPortalUser } from '@/lib/services/portal-auth.service';
+import { env } from '@/lib/env';
+import { eq } from 'drizzle-orm';
+
+async function main(): Promise<void> {
+  if (!env.EMAIL_REDIRECT_TO) {
+    throw new Error(
+      'EMAIL_REDIRECT_TO is not set — refusing to send a real activation email to a real client.',
+    );
+  }
+  console.log(`EMAIL_REDIRECT_TO is set: ${env.EMAIL_REDIRECT_TO}`);
+
+  const client = await db.query.clients.findFirst({
+    where: eq(clients.portId, '294c8240-49a7-403e-92e8-fc3a524c00b4'),
+  });
+  if (!client) throw new Error('No client found in port-nimara');
+
+  // Use the redirect target as the portal user's actual email, so the
+  // tester can sign in with the same address that received the activation mail.
+  const portalEmail = env.EMAIL_REDIRECT_TO;
+  console.log(
+    `Creating portal user for client ${client.fullName} (${client.id}) with email ${portalEmail}…`,
+  );
+
+  // Clear any prior dev-script seed so uniqueness checks don't trip.
+  await db.delete(portalUsers).where(eq(portalUsers.clientId, client.id));
+  await db.delete(portalUsers).where(eq(portalUsers.email, portalEmail));
+
+  const result = await createPortalUser({
+    clientId: client.id,
+    portId: client.portId,
+    email: portalEmail,
+    name: client.fullName,
+    createdBy: 'dev-script',
+  });
+
+  console.log('Portal user created:', result);
+  console.log(`Activation email enqueued — should arrive at ${portalEmail}.`);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Script failed:', err);
+  process.exit(1);
+});

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { useState } from 'react';
+import { Suspense, useState } from 'react';
 import { useRouter, useSearchParams } from 'next/navigation';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
@@ -44,7 +44,7 @@ const requirements: Requirement[] = [
   { label: 'Special character', test: (v) => /[^A-Za-z0-9]/.test(v) },
 ];
 
-export default function SetPasswordPage() {
+function SetPasswordInner() {
   const router = useRouter();
   const searchParams = useSearchParams();
   const token = searchParams.get('token');
@@ -154,8 +154,7 @@ export default function SetPasswordPage() {
                   autoComplete="new-password"
                   disabled={isLoading}
                   className={cn(
-                    errors.confirmPassword &&
+                    errors.confirmPassword && 'border-destructive focus-visible:ring-destructive',
-                      'border-destructive focus-visible:ring-destructive',
                   )}
                   {...register('confirmPassword')}
                 />
@@ -174,3 +173,18 @@ export default function SetPasswordPage() {
     </div>
   );
 }
+
+export default function SetPasswordPage() {
+  return (
+    <Suspense
+      fallback={
+        <div
+          className="min-h-screen flex items-center justify-center px-4"
+          style={{ backgroundColor: '#1e2844' }}
+        />
+      }
+    >
+      <SetPasswordInner />
+    </Suspense>
+  );
+}

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

@@ -0,0 +1,16 @@
+import { CompanyDetail } from '@/components/companies/company-detail';
+import { auth } from '@/lib/auth';
+import { headers } from 'next/headers';
+
+interface CompanyDetailPageProps {
+  params: Promise<{ companyId: string }>;
+}
+
+export default async function CompanyDetailPage({ params }: CompanyDetailPageProps) {
+  const { companyId } = await params;
+
+  const session = await auth.api.getSession({ headers: await headers() });
+  const currentUserId = session?.user?.id;
+
+  return <CompanyDetail companyId={companyId} currentUserId={currentUserId} />;
+}

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

@@ -0,0 +1,5 @@
+import { CompanyList } from '@/components/companies/company-list';
+
+export default function CompaniesPage() {
+  return <CompanyList />;
+}

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

@@ -19,6 +19,7 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { OwnerPicker } from '@/components/shared/owner-picker';
 import { InvoiceLineItems } from '@/components/invoices/invoice-line-items';
 import { apiFetch } from '@/lib/api/client';
 import { createInvoiceSchema, type CreateInvoiceInput } from '@/lib/validators/invoices';
@@ -55,7 +56,13 @@ export default function NewInvoicePage() {
     },
   });
 
-  const { register, handleSubmit, watch, setValue, formState: { errors } } = methods;
+  const {
+    register,
+    handleSubmit,
+    watch,
+    setValue,
+    formState: { errors },
+  } = methods;
 
   const watchedValues = watch();
   const lineItems = watchedValues.lineItems ?? [];
@@ -87,7 +94,7 @@ export default function NewInvoicePage() {
   async function goNext() {
     if (step === 1) {
       const valid = await methods.trigger([
-        'clientName',
+        'billingEntity',
         'billingEmail',
         'billingAddress',
         'dueDate',
@@ -112,11 +119,7 @@ export default function NewInvoicePage() {
     <div className="max-w-2xl mx-auto space-y-6">
       {/* Header */}
       <div className="flex items-center gap-3">
-        <Button
+        <Button variant="ghost" size="sm" onClick={() => router.push(`/${portSlug}/invoices`)}>
-          variant="ghost"
-          size="sm"
-          onClick={() => router.push(`/${portSlug}/invoices`)}
-        >
           <ChevronLeft className="h-4 w-4" />
         </Button>
         <h1 className="text-xl font-semibold">New Invoice</h1>
@@ -131,22 +134,16 @@ export default function NewInvoicePage() {
                 step > s.id
                   ? 'bg-primary text-primary-foreground'
                   : step === s.id
-                  ? 'bg-primary text-primary-foreground'
+                    ? 'bg-primary text-primary-foreground'
-                  : 'bg-muted text-muted-foreground'
+                    : 'bg-muted text-muted-foreground'
               }`}
             >
               {step > s.id ? <Check className="h-3.5 w-3.5" /> : s.id}
             </div>
-            <span
+            <span className={`text-sm ${step === s.id ? 'font-medium' : 'text-muted-foreground'}`}>
-              className={`text-sm ${
-                step === s.id ? 'font-medium' : 'text-muted-foreground'
-              }`}
-            >
               {s.label}
             </span>
-            {idx < STEPS.length - 1 && (
+            {idx < STEPS.length - 1 && <div className="w-8 h-px bg-border mx-1" />}
-              <div className="w-8 h-px bg-border mx-1" />
-            )}
           </div>
         ))}
       </div>
@@ -160,18 +157,29 @@ export default function NewInvoicePage() {
                 <CardTitle className="text-base">Client Information</CardTitle>
               </CardHeader>
               <CardContent className="space-y-4">
-                <div className="space-y-1">
+                <div className="space-y-2">
-                  <Label htmlFor="clientName">
+                  <Label>
-                    Client Name <span className="text-destructive">*</span>
+                    Billing entity <span className="text-destructive">*</span>
                   </Label>
-                  <Input
+                  <OwnerPicker
-                    id="clientName"
+                    value={watchedValues.billingEntity ?? null}
-                    {...register('clientName')}
+                    onChange={(ref) => {
-                    placeholder="Client or company name"
+                      if (ref) {
+                        setValue('billingEntity', ref, { shouldValidate: true });
+                      }
+                    }}
                   />
-                  {errors.clientName && (
+                  {errors.billingEntity && (
-                    <p className="text-xs text-destructive">{errors.clientName.message}</p>
+                    <p className="text-xs text-destructive">
+                      {errors.billingEntity.message ??
+                        errors.billingEntity.id?.message ??
+                        errors.billingEntity.type?.message}
+                    </p>
                   )}
+                  <p className="text-xs text-muted-foreground">
+                    Select the client or company to invoice. Their name will be snapshotted into the
+                    invoice.
+                  </p>
                 </div>
 
                 <div className="space-y-1">
@@ -202,11 +210,7 @@ export default function NewInvoicePage() {
                     <Label htmlFor="dueDate">
                       Due Date <span className="text-destructive">*</span>
                     </Label>
-                    <Input
+                    <Input id="dueDate" type="date" {...register('dueDate')} />
-                      id="dueDate"
-                      type="date"
-                      {...register('dueDate')}
-                    />
                     {errors.dueDate && (
                       <p className="text-xs text-destructive">{errors.dueDate.message}</p>
                     )}
@@ -216,7 +220,9 @@ export default function NewInvoicePage() {
                     <Label>Payment Terms</Label>
                     <Select
                       defaultValue="net30"
-                      onValueChange={(v) => setValue('paymentTerms', v as CreateInvoiceInput['paymentTerms'])}
+                      onValueChange={(v) =>
+                        setValue('paymentTerms', v as CreateInvoiceInput['paymentTerms'])
+                      }
                     >
                       <SelectTrigger>
                         <SelectValue placeholder="Select terms" />
@@ -284,8 +290,19 @@ export default function NewInvoicePage() {
               <CardContent className="space-y-4">
                 <div className="grid grid-cols-2 gap-4 text-sm">
                   <div>
-                    <span className="text-muted-foreground">Client</span>
+                    <span className="text-muted-foreground">Billing Entity</span>
-                    <p className="font-medium mt-0.5">{watchedValues.clientName}</p>
+                    <p className="font-medium mt-0.5">
+                      {watchedValues.billingEntity ? (
+                        <>
+                          <span className="capitalize">{watchedValues.billingEntity.type}</span>{' '}
+                          <span className="text-xs opacity-60">
+                            {watchedValues.billingEntity.id.slice(0, 12)}
+                          </span>
+                        </>
+                      ) : (
+                        <span className="text-muted-foreground italic">Not selected</span>
+                      )}
+                    </p>
                   </div>
                   <div>
                     <span className="text-muted-foreground">Due Date</span>
@@ -293,9 +310,7 @@ export default function NewInvoicePage() {
                   </div>
                   <div>
                     <span className="text-muted-foreground">Payment Terms</span>
-                    <p className="font-medium mt-0.5 capitalize">
+                    <p className="font-medium mt-0.5 capitalize">{watchedValues.paymentTerms}</p>
-                      {watchedValues.paymentTerms}
-                    </p>
                   </div>
                   <div>
                     <span className="text-muted-foreground">Currency</span>
@@ -354,12 +369,7 @@ export default function NewInvoicePage() {
 
           {/* Navigation */}
           <div className="flex items-center justify-between">
-            <Button
+            <Button type="button" variant="outline" onClick={goBack} disabled={step === 1}>
-              type="button"
-              variant="outline"
-              onClick={goBack}
-              disabled={step === 1}
-            >
               <ChevronLeft className="mr-1.5 h-4 w-4" />
               Back
             </Button>

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

@@ -0,0 +1,16 @@
+import { YachtDetail } from '@/components/yachts/yacht-detail';
+import { auth } from '@/lib/auth';
+import { headers } from 'next/headers';
+
+interface YachtDetailPageProps {
+  params: Promise<{ yachtId: string }>;
+}
+
+export default async function YachtDetailPage({ params }: YachtDetailPageProps) {
+  const { yachtId } = await params;
+
+  const session = await auth.api.getSession({ headers: await headers() });
+  const currentUserId = session?.user?.id;
+
+  return <YachtDetail yachtId={yachtId} currentUserId={currentUserId} />;
+}

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

@@ -0,0 +1,5 @@
+import { YachtList } from '@/components/yachts/yacht-list';
+
+export default function YachtsPage() {
+  return <YachtList />;
+}

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

@@ -0,0 +1,24 @@
+import { Suspense } from 'react';
+
+import { PasswordSetForm } from '@/components/portal/password-set-form';
+
+export default function PortalActivatePage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="min-h-screen flex items-center justify-center bg-gray-50 text-sm text-gray-500">
+          Loading…
+        </div>
+      }
+    >
+      <PasswordSetForm
+        endpoint="/api/portal/auth/activate"
+        title="Activate your 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"
+      />
+    </Suspense>
+  );
+}

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

@@ -1,5 +1,5 @@
 import { redirect } from 'next/navigation';
-import { Anchor, FileText, Receipt } from 'lucide-react';
+import { Anchor, FileText, Receipt, Sailboat, Building2, CalendarCheck } from 'lucide-react';
 import type { Metadata } from 'next';
 
 import { getPortalSession } from '@/lib/portal/auth';
@@ -21,15 +21,12 @@ export default async function PortalDashboardPage() {
         <h1 className="text-2xl font-semibold text-gray-900">
           Welcome back, {dashboard.client.fullName.split(' ')[0]}
         </h1>
-        {dashboard.client.companyName && (
+        {dashboard.client.nationality && (
-          <p className="text-gray-500 mt-0.5">{dashboard.client.companyName}</p>
+          <p className="text-sm text-gray-400 mt-0.5">{dashboard.client.nationality}</p>
-        )}
-        {dashboard.client.yachtName && (
-          <p className="text-sm text-gray-400 mt-0.5">Vessel: {dashboard.client.yachtName}</p>
         )}
       </div>
 
-      <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
+      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
         <PortalCard
           title="Berth Interests"
           value={dashboard.counts.interests}
@@ -51,13 +48,33 @@ export default async function PortalDashboardPage() {
           icon={Receipt}
           href="/portal/invoices"
         />
+        <PortalCard
+          title="My Yachts"
+          value={dashboard.counts.yachts}
+          description="Vessels you own directly or through a company"
+          icon={Sailboat}
+          href="/portal/my-yachts"
+        />
+        <PortalCard
+          title="My Memberships"
+          value={dashboard.counts.memberships}
+          description="Companies where you hold an active role"
+          icon={Building2}
+        />
+        <PortalCard
+          title="My Active Reservations"
+          value={dashboard.counts.activeReservations}
+          description="Current and pending berth reservations"
+          icon={CalendarCheck}
+          href="/portal/my-reservations"
+        />
       </div>
 
       <div className="bg-white rounded-lg border p-6">
         <h2 className="text-sm font-medium text-gray-700 mb-1">Need assistance?</h2>
         <p className="text-sm text-gray-500">
-          Contact the {dashboard.port.name} team directly. This portal provides a read-only view
+          Contact the {dashboard.port.name} team directly. This portal provides a read-only view of
-          of your account. All changes must be made through your port contact.
+          your account. All changes must be made through your port contact.
         </p>
       </div>
     </div>

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

@@ -0,0 +1,107 @@
+'use client';
+
+import Link from 'next/link';
+import { useState } from 'react';
+import { Loader2, Mail } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+
+export default function PortalForgotPasswordPage() {
+  const [email, setEmail] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setLoading(true);
+    try {
+      // Always returns 200 — caller never sees whether email exists.
+      await fetch('/api/portal/auth/forgot-password', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email }),
+      });
+    } finally {
+      setSubmitted(true);
+      setLoading(false);
+    }
+  }
+
+  if (submitted) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
+        <div className="w-full max-w-md text-center">
+          <div className="inline-flex items-center justify-center w-14 h-14 rounded-full bg-green-50 mb-4">
+            <Mail className="h-7 w-7 text-green-600" />
+          </div>
+          <h1 className="text-xl font-semibold text-gray-900 mb-2">Check your email</h1>
+          <p className="text-gray-500 text-sm leading-relaxed">
+            If <strong>{email}</strong> matches a portal account, we&apos;ve sent a reset link. The
+            link expires in 30 minutes.
+          </p>
+          <Link
+            href="/portal/login"
+            className="mt-6 inline-block text-sm text-[#1e2844] hover:underline"
+          >
+            Back to sign in
+          </Link>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
+      <div className="w-full max-w-sm">
+        <div className="bg-white rounded-lg border p-8 shadow-sm">
+          <div className="text-center mb-6">
+            <h1 className="text-xl font-semibold text-gray-900">Reset your password</h1>
+            <p className="text-sm text-gray-500 mt-1">
+              Enter your email and we&apos;ll send you a reset link.
+            </p>
+          </div>
+
+          <form onSubmit={handleSubmit} className="space-y-4">
+            <div className="space-y-1.5">
+              <Label htmlFor="email">Email address</Label>
+              <Input
+                id="email"
+                type="email"
+                placeholder="you@example.com"
+                value={email}
+                onChange={(e) => setEmail(e.target.value)}
+                required
+                autoFocus
+                disabled={loading}
+              />
+            </div>
+
+            <Button
+              type="submit"
+              className="w-full bg-[#1e2844] hover:bg-[#1e2844]/90 text-white"
+              disabled={loading || !email}
+            >
+              {loading ? (
+                <>
+                  <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+                  Sending…
+                </>
+              ) : (
+                'Send reset link'
+              )}
+            </Button>
+          </form>
+
+          <Link
+            href="/portal/login"
+            className="block mt-4 text-center text-xs text-gray-500 hover:underline"
+          >
+            Back to sign in
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -1,15 +1,23 @@
 'use client';
 
+import Link from 'next/link';
+import { useRouter, useSearchParams } from 'next/navigation';
 import { useState } from 'react';
-import { Mail, Loader2 } from 'lucide-react';
+import { Loader2 } from 'lucide-react';
+
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
+import { PortalAuthShell } from '@/components/portal/portal-auth-shell';
 
 export default function PortalLoginPage() {
+  const router = useRouter();
+  const search = useSearchParams();
+  const next = search.get('next') ?? '/portal/dashboard';
+
   const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
   const [loading, setLoading] = useState(false);
-  const [submitted, setSubmitted] = useState(false);
   const [error, setError] = useState('');
 
   async function handleSubmit(e: React.FormEvent) {
@@ -18,101 +26,90 @@ export default function PortalLoginPage() {
     setLoading(true);
 
     try {
-      const res = await fetch('/api/portal/auth/request', {
+      const res = await fetch('/api/portal/auth/sign-in', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ email }),
+        body: JSON.stringify({ email, password }),
       });
 
       if (!res.ok) {
         const data = await res.json().catch(() => ({}));
-        setError((data as { error?: string }).error ?? 'Something went wrong. Please try again.');
+        setError((data as { error?: string }).error ?? 'Invalid email or password');
         return;
       }
 
-      setSubmitted(true);
+      // typedRoutes: `next` is a runtime string we can't statically check.
+      router.replace(next as never);
+      router.refresh();
     } catch {
-      setError('Unable to connect. Please check your connection and try again.');
+      setError('Unable to connect. Please try again.');
     } finally {
       setLoading(false);
     }
   }
 
-  if (submitted) {
-    return (
-      <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
-        <div className="w-full max-w-md text-center">
-          <div className="inline-flex items-center justify-center w-14 h-14 rounded-full bg-green-50 mb-4">
-            <Mail className="h-7 w-7 text-green-600" />
-          </div>
-          <h1 className="text-xl font-semibold text-gray-900 mb-2">Check your email</h1>
-          <p className="text-gray-500 text-sm leading-relaxed">
-            If <strong>{email}</strong> is associated with a client account, you will receive a
-            sign-in link shortly. The link expires in 24 hours.
-          </p>
-          <button
-            type="button"
-            onClick={() => { setSubmitted(false); setEmail(''); }}
-            className="mt-6 text-sm text-[#1e2844] hover:underline"
-          >
-            Try a different email
-          </button>
-        </div>
-      </div>
-    );
-  }
-
   return (
-    <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
+    <PortalAuthShell>
-      <div className="w-full max-w-sm">
+      <div className="text-center mb-6">
-        <div className="bg-white rounded-lg border p-8 shadow-sm">
+        <h1 className="text-xl font-semibold text-gray-900">Client Portal</h1>
-          <div className="text-center mb-6">
+        <p className="text-sm text-gray-500 mt-1">Sign in to your account</p>
-            <h1 className="text-xl font-semibold text-gray-900">Client Portal</h1>
+      </div>
-            <p className="text-sm text-gray-500 mt-1">
-              Enter your email to receive a sign-in link
-            </p>
-          </div>
 
-          <form onSubmit={handleSubmit} className="space-y-4">
+      <form onSubmit={handleSubmit} className="space-y-4">
-            <div className="space-y-1.5">
+        <div className="space-y-1.5">
-              <Label htmlFor="email">Email address</Label>
+          <Label htmlFor="email">Email address</Label>
-              <Input
+          <Input
-                id="email"
+            id="email"
-                type="email"
+            type="email"
-                placeholder="you@example.com"
+            placeholder="you@example.com"
-                value={email}
+            value={email}
-                onChange={(e) => setEmail(e.target.value)}
+            onChange={(e) => setEmail(e.target.value)}
-                required
+            required
-                autoFocus
+            autoFocus
-                disabled={loading}
+            autoComplete="email"
-              />
+            disabled={loading}
-            </div>
+          />
-
-            {error && (
-              <p className="text-sm text-red-600">{error}</p>
-            )}
-
-            <Button
-              type="submit"
-              className="w-full bg-[#1e2844] hover:bg-[#1e2844]/90 text-white"
-              disabled={loading || !email}
-            >
-              {loading ? (
-                <>
-                  <Loader2 className="h-4 w-4 mr-2 animate-spin" />
-                  Sending link...
-                </>
-              ) : (
-                'Send sign-in link'
-              )}
-            </Button>
-          </form>
         </div>
 
-        <p className="text-center text-xs text-gray-400 mt-4">
+        <div className="space-y-1.5">
-          This portal is for existing clients only.
+          <div className="flex items-center justify-between">
-        </p>
+            <Label htmlFor="password">Password</Label>
-      </div>
+            <Link href="/portal/forgot-password" className="text-xs text-[#007bff] hover:underline">
-    </div>
+              Forgot password?
+            </Link>
+          </div>
+          <Input
+            id="password"
+            type="password"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            required
+            autoComplete="current-password"
+            disabled={loading}
+          />
+        </div>
+
+        {error && <p className="text-sm text-red-600">{error}</p>}
+
+        <Button
+          type="submit"
+          className="w-full bg-[#007bff] hover:bg-[#0069d9] text-white"
+          disabled={loading || !email || !password}
+        >
+          {loading ? (
+            <>
+              <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+              Signing in…
+            </>
+          ) : (
+            'Sign in'
+          )}
+        </Button>
+      </form>
+
+      <p className="text-center text-xs text-gray-400 mt-6">
+        This portal is for existing clients only.
+      </p>
+    </PortalAuthShell>
   );
 }

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

@@ -0,0 +1,83 @@
+import { redirect } from 'next/navigation';
+import { CalendarCheck } from 'lucide-react';
+import type { Metadata } from 'next';
+
+import { getPortalSession } from '@/lib/portal/auth';
+import { getPortalUserReservations } from '@/lib/services/portal.service';
+import { Badge } from '@/components/ui/badge';
+
+export const metadata: Metadata = { title: 'My Reservations' };
+
+const STATUS_COLORS: Record<string, 'default' | 'secondary' | 'destructive' | 'outline'> = {
+  pending: 'secondary',
+  active: 'default',
+  ended: 'outline',
+  cancelled: 'destructive',
+};
+
+const TENURE_LABELS: Record<string, string> = {
+  permanent: 'Permanent',
+  fixed_term: 'Fixed term',
+  seasonal: 'Seasonal',
+};
+
+function formatDate(d: Date | string): string {
+  return new Date(d).toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  });
+}
+
+export default async function PortalMyReservationsPage() {
+  const session = await getPortalSession();
+  if (!session) redirect('/portal/login');
+
+  const reservations = await getPortalUserReservations(session.clientId, session.portId);
+
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold text-gray-900">My Reservations</h1>
+        <p className="text-sm text-gray-500 mt-1">Your current and pending berth reservations</p>
+      </div>
+
+      {reservations.length === 0 ? (
+        <div className="bg-white rounded-lg border p-12 text-center">
+          <CalendarCheck className="h-10 w-10 text-gray-300 mx-auto mb-3" />
+          <p className="text-gray-500 font-medium">No active reservations</p>
+          <p className="text-sm text-gray-400 mt-1">
+            Contact your port representative to discuss reservations.
+          </p>
+        </div>
+      ) : (
+        <div className="space-y-3">
+          {reservations.map((r) => (
+            <div key={r.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">
+                    <span className="font-medium text-gray-900">{r.yachtName ?? 'Yacht'}</span>
+                    {r.berthMooringNumber && (
+                      <span className="text-sm text-gray-400">— Berth {r.berthMooringNumber}</span>
+                    )}
+                  </div>
+                  <p className="text-sm text-gray-500">
+                    {TENURE_LABELS[r.tenureType] ?? r.tenureType}
+                  </p>
+                  <div className="flex flex-wrap gap-3 mt-2 text-xs text-gray-400">
+                    <span>
+                      From {formatDate(r.startDate)}
+                      {r.endDate ? ` to ${formatDate(r.endDate)}` : ' · ongoing'}
+                    </span>
+                  </div>
+                </div>
+                <Badge variant={STATUS_COLORS[r.status] ?? 'default'}>{r.status}</Badge>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,77 @@
+import { redirect } from 'next/navigation';
+import { Sailboat } from 'lucide-react';
+import type { Metadata } from 'next';
+
+import { getPortalSession } from '@/lib/portal/auth';
+import { getPortalUserYachts } from '@/lib/services/portal.service';
+import { Badge } from '@/components/ui/badge';
+
+export const metadata: Metadata = { title: 'My Yachts' };
+
+const STATUS_COLORS: Record<string, 'default' | 'secondary' | 'destructive' | 'outline'> = {
+  active: 'default',
+  retired: 'secondary',
+  sold_away: 'outline',
+};
+
+export default async function PortalMyYachtsPage() {
+  const session = await getPortalSession();
+  if (!session) redirect('/portal/login');
+
+  const yachts = await getPortalUserYachts(session.clientId, session.portId);
+
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold text-gray-900">My Yachts</h1>
+        <p className="text-sm text-gray-500 mt-1">Vessels you own directly or through a company</p>
+      </div>
+
+      {yachts.length === 0 ? (
+        <div className="bg-white rounded-lg border p-12 text-center">
+          <Sailboat className="h-10 w-10 text-gray-300 mx-auto mb-3" />
+          <p className="text-gray-500 font-medium">No yachts on file</p>
+          <p className="text-sm text-gray-400 mt-1">
+            Yachts owned by you or a company you are a member of will appear here.
+          </p>
+        </div>
+      ) : (
+        <div className="space-y-3">
+          {yachts.map((y) => (
+            <div key={y.id} className="bg-white rounded-lg border p-5">
+              <div className="flex items-start gap-4">
+                <Sailboat className="h-5 w-5 text-gray-400 mt-0.5 flex-shrink-0" />
+                <div className="flex-1 min-w-0">
+                  <div className="flex items-start justify-between gap-4 flex-wrap">
+                    <div className="flex-1 min-w-0">
+                      <p className="font-medium text-gray-900 truncate">{y.name}</p>
+                      <p className="text-sm text-gray-500 mt-0.5">
+                        {y.hullNumber ? `Hull ${y.hullNumber}` : 'No hull number'}
+                        {y.flag ? ` · ${y.flag}` : ''}
+                        {y.yearBuilt ? ` · ${y.yearBuilt}` : ''}
+                      </p>
+                      {y.ownerContext === 'company' && y.ownerCompanyName && (
+                        <p className="text-xs text-[#1e2844] mt-2">Owned by {y.ownerCompanyName}</p>
+                      )}
+                    </div>
+                    <Badge variant={STATUS_COLORS[y.status] ?? 'default'}>
+                      {y.status.replace(/_/g, ' ')}
+                    </Badge>
+                  </div>
+
+                  {(y.lengthFt || y.widthFt || y.registration) && (
+                    <div className="flex flex-wrap gap-3 mt-3 text-xs text-gray-400">
+                      {y.registration && <span>Reg: {y.registration}</span>}
+                      {y.lengthFt && <span>Length: {y.lengthFt}ft</span>}
+                      {y.widthFt && <span>Beam: {y.widthFt}ft</span>}
+                    </div>
+                  )}
+                </div>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,24 @@
+import { Suspense } from 'react';
+
+import { PasswordSetForm } from '@/components/portal/password-set-form';
+
+export default function PortalResetPasswordPage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="min-h-screen flex items-center justify-center bg-gray-50 text-sm text-gray-500">
+          Loading…
+        </div>
+      }
+    >
+      <PasswordSetForm
+        endpoint="/api/portal/auth/reset-password"
+        title="Choose a new password"
+        description="Enter a new password to regain access to your client portal."
+        successTitle="Password updated"
+        successDescription="You can now sign in with your new password."
+        submitLabel="Update password"
+      />
+    </Suspense>
+  );
+}

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

@@ -1,35 +0,0 @@
-'use client';
-
-import { useEffect, useRef } from 'react';
-import { useRouter, useSearchParams } from 'next/navigation';
-import { Loader2 } from 'lucide-react';
-
-export default function PortalVerifyPage() {
-  const router = useRouter();
-  const searchParams = useSearchParams();
-  const calledRef = useRef(false);
-
-  useEffect(() => {
-    if (calledRef.current) return;
-    calledRef.current = true;
-
-    const token = searchParams.get('token');
-
-    if (!token) {
-      router.replace('/portal/login?error=missing_token');
-      return;
-    }
-
-    // Redirect to the verify API route which will set the cookie and redirect
-    window.location.href = `/api/portal/auth/verify?token=${encodeURIComponent(token)}`;
-  }, [searchParams, router]);
-
-  return (
-    <div className="min-h-screen flex items-center justify-center bg-gray-50">
-      <div className="text-center">
-        <Loader2 className="h-8 w-8 animate-spin text-[#1e2844] mx-auto mb-3" />
-        <p className="text-sm text-gray-500">Verifying your access...</p>
-      </div>
-    </div>
-  );
-}

src/app/api/portal/auth/activate/route.ts

@@ -0,0 +1,34 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { errorResponse } from '@/lib/errors';
+import { activateAccount } from '@/lib/services/portal-auth.service';
+
+const bodySchema = z.object({
+  token: z.string().min(1),
+  password: z.string().min(9),
+});
+
+export async function POST(req: NextRequest): Promise<NextResponse> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: parsed.error.errors[0]?.message ?? 'Invalid input' },
+      { status: 400 },
+    );
+  }
+
+  try {
+    await activateAccount(parsed.data.token, parsed.data.password);
+    return NextResponse.json({ success: true });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

src/app/api/portal/auth/forgot-password/route.ts

@@ -0,0 +1,30 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { logger } from '@/lib/logger';
+import { requestPasswordReset } from '@/lib/services/portal-auth.service';
+
+const bodySchema = z.object({ email: z.string().email() });
+
+export async function POST(req: NextRequest): Promise<NextResponse> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid email address' }, { status: 400 });
+  }
+
+  // Always return 200 to prevent account-enumeration. Errors are logged
+  // server-side, never surfaced to the client.
+  try {
+    await requestPasswordReset(parsed.data.email);
+  } catch (err) {
+    logger.error({ err }, 'Portal forgot-password failed (swallowed)');
+  }
+  return NextResponse.json({ success: true });
+}

src/app/api/portal/auth/request/route.ts

@@ -1,28 +0,0 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { z } from 'zod';
-
-import { requestMagicLink } from '@/lib/services/portal.service';
-import { logger } from '@/lib/logger';
-
-const bodySchema = z.object({
-  email: z.string().email(),
-});
-
-export async function POST(req: NextRequest): Promise<NextResponse> {
-  try {
-    const body = await req.json();
-    const parsed = bodySchema.safeParse(body);
-
-    if (!parsed.success) {
-      return NextResponse.json({ error: 'Invalid email address' }, { status: 400 });
-    }
-
-    await requestMagicLink(parsed.data.email);
-
-    // Always return success to prevent email enumeration
-    return NextResponse.json({ success: true });
-  } catch (error) {
-    logger.error({ error }, 'Portal magic link request failed');
-    return NextResponse.json({ error: 'Failed to process request' }, { status: 500 });
-  }
-}

src/app/api/portal/auth/reset-password/route.ts

@@ -0,0 +1,34 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { errorResponse } from '@/lib/errors';
+import { resetPassword } from '@/lib/services/portal-auth.service';
+
+const bodySchema = z.object({
+  token: z.string().min(1),
+  password: z.string().min(9),
+});
+
+export async function POST(req: NextRequest): Promise<NextResponse> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: parsed.error.errors[0]?.message ?? 'Invalid input' },
+      { status: 400 },
+    );
+  }
+
+  try {
+    await resetPassword(parsed.data.token, parsed.data.password);
+    return NextResponse.json({ success: true });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

src/app/api/portal/auth/sign-in/route.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { errorResponse } from '@/lib/errors';
+import { PORTAL_COOKIE } from '@/lib/portal/auth';
+import { signIn } from '@/lib/services/portal-auth.service';
+
+const bodySchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1),
+});
+
+const SESSION_MAX_AGE_SECONDS = 60 * 60 * 24; // 24h, matches createPortalToken
+
+export async function POST(req: NextRequest): Promise<NextResponse> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid email or password' }, { status: 400 });
+  }
+
+  try {
+    const result = await signIn(parsed.data);
+    const res = NextResponse.json({ success: true });
+    res.cookies.set(PORTAL_COOKIE, result.token, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      path: '/',
+      maxAge: SESSION_MAX_AGE_SECONDS,
+    });
+    return res;
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

src/app/api/portal/auth/verify/route.ts

@@ -1,38 +0,0 @@
-import { NextRequest, NextResponse } from 'next/server';
-
-import { verifyPortalToken, PORTAL_COOKIE } from '@/lib/portal/auth';
-import { env } from '@/lib/env';
-import { logger } from '@/lib/logger';
-
-export async function GET(req: NextRequest): Promise<NextResponse> {
-  try {
-    const token = req.nextUrl.searchParams.get('token');
-
-    if (!token) {
-      return NextResponse.redirect(new URL('/portal/login?error=missing_token', env.APP_URL));
-    }
-
-    const session = await verifyPortalToken(token);
-
-    if (!session) {
-      return NextResponse.redirect(new URL('/portal/login?error=invalid_token', env.APP_URL));
-    }
-
-    const response = NextResponse.redirect(new URL('/portal/dashboard', env.APP_URL));
-
-    response.cookies.set(PORTAL_COOKIE, token, {
-      httpOnly: true,
-      secure: process.env.NODE_ENV === 'production',
-      sameSite: 'lax',
-      path: '/',
-      maxAge: 60 * 60 * 24, // 24 hours
-    });
-
-    logger.info({ clientId: session.clientId }, 'Portal session created');
-
-    return response;
-  } catch (error) {
-    logger.error({ error }, 'Portal token verification failed');
-    return NextResponse.redirect(new URL('/portal/login?error=server_error', env.APP_URL));
-  }
-}

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

@@ -1,11 +1,15 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { and, eq } from 'drizzle-orm';
+import { and, eq, isNull, sql } from 'drizzle-orm';
+import type { z } from 'zod';
 
 import { db } from '@/lib/db';
+import { withTransaction } from '@/lib/db/utils';
 import { interests } from '@/lib/db/schema/interests';
 import { clients, clientContacts, clientAddresses } from '@/lib/db/schema/clients';
 import { berths } from '@/lib/db/schema/berths';
 import { ports } from '@/lib/db/schema/ports';
+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 { publicInterestSchema } from '@/lib/validators/interests';
@@ -35,7 +39,14 @@ function checkRateLimit(ip: string): void {
   entry.count += 1;
 }
 
-// POST /api/public/interests — unauthenticated public interest registration
+type PublicInterestData = z.infer<typeof publicInterestSchema>;
+// `withTransaction` exposes its tx argument as `typeof db` (see lib/db/utils.ts).
+// Keep the helper aligned with that.
+type Tx = typeof db;
+
+// 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';
@@ -50,7 +61,6 @@ export async function POST(req: NextRequest) {
       return NextResponse.json({ error: 'Port context required' }, { status: 400 });
     }
 
-    // Resolve the full name
     const fullName =
       data.firstName && data.lastName
         ? `${data.firstName} ${data.lastName}`
@@ -58,10 +68,10 @@ export async function POST(req: NextRequest) {
 
     const firstName = data.firstName ?? fullName.split(/\s+/)[0] ?? 'Valued Guest';
 
-    // Resolve berth by mooring number (if provided)
+    // 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;
-
     if (data.mooringNumber) {
       const berth = await db.query.berths.findFirst({
         where: and(eq(berths.mooringNumber, data.mooringNumber), eq(berths.portId, portId)),
@@ -72,74 +82,172 @@ export async function POST(req: NextRequest) {
       }
     }
 
-    // Find or create client by email
+    // ─── Transactional trio creation ────────────────────────────────────────
-    let clientId: string;
+    const result = await withTransaction(async (tx) => {
-
+      // 1. Find or create client by email (case-sensitive contact match, same
-    const existingContact = await db.query.clientContacts.findFirst({
+      //    behavior as before the refactor).
-      where: and(eq(clientContacts.channel, 'email'), eq(clientContacts.value, data.email)),
+      let clientId: string;
-    });
+      const existingContact = await tx.query.clientContacts.findFirst({
-
+        where: and(eq(clientContacts.channel, 'email'), eq(clientContacts.value, data.email)),
-    if (existingContact) {
-      const existingClient = await db.query.clients.findFirst({
-        where: eq(clients.id, existingContact.clientId),
       });
-      if (existingClient && existingClient.portId === portId) {
+      if (existingContact) {
-        clientId = existingClient.id;
+        const existingClient = await tx.query.clients.findFirst({
-        // Update preferred contact method if provided
+          where: eq(clients.id, existingContact.clientId),
-        if (data.preferredContactMethod) {
+        });
-          await db
+        if (existingClient && existingClient.portId === portId) {
-            .update(clients)
+          clientId = existingClient.id;
-            .set({ preferredContactMethod: data.preferredContactMethod })
+          if (data.preferredContactMethod) {
-            .where(eq(clients.id, clientId));
+            await tx
+              .update(clients)
+              .set({ preferredContactMethod: data.preferredContactMethod })
+              .where(eq(clients.id, clientId));
+          }
+        } else {
+          clientId = await createClientInTx(tx, portId, fullName, data);
         }
       } else {
-        clientId = await createNewClient(portId, fullName, data);
+        clientId = await createClientInTx(tx, portId, fullName, data);
       }
-    } else {
-      clientId = await createNewClient(portId, fullName, data);
-    }
 
-    // Store address if provided
+      // 2. Optional: upsert company + add membership
-    if (data.address && Object.values(data.address).some(Boolean)) {
+      let companyId: string | null = null;
-      await db.insert(clientAddresses).values({
+      if (data.company) {
-        clientId,
+        const existingCompany = await tx.query.companies.findFirst({
-        portId,
+          where: and(
-        label: 'Primary',
+            eq(companies.portId, portId),
-        streetAddress: data.address.street ?? null,
+            sql`lower(${companies.name}) = lower(${data.company.name})`,
-        city: data.address.city ?? null,
+          ),
-        stateProvince: data.address.stateProvince ?? null,
+        });
-        postalCode: data.address.postalCode ?? null,
+        if (existingCompany) {
-        country: data.address.country ?? null,
+          companyId = existingCompany.id;
-        isPrimary: true,
+        } else {
+          const [newCompany] = await tx
+            .insert(companies)
+            .values({
+              portId,
+              name: data.company.name,
+              legalName: data.company.legalName ?? null,
+              taxId: data.company.taxId ?? null,
+              incorporationCountry: data.company.incorporationCountry ?? null,
+              status: 'active',
+            })
+            .returning();
+          companyId = newCompany!.id;
+        }
+
+        // Add active membership only if one doesn't already exist (open row).
+        const existingMembership = await tx.query.companyMemberships.findFirst({
+          where: and(
+            eq(companyMemberships.companyId, companyId),
+            eq(companyMemberships.clientId, clientId),
+            isNull(companyMemberships.endDate),
+          ),
+        });
+        if (!existingMembership) {
+          await tx.insert(companyMemberships).values({
+            companyId,
+            clientId,
+            role: data.company.role ?? 'representative',
+            startDate: new Date(),
+            isPrimary: false,
+          });
+        }
+      }
+
+      // 3. Create yacht. Owner is the company when provided, else the client.
+      const ownerType: 'client' | 'company' = companyId ? 'company' : 'client';
+      const ownerId = companyId ?? clientId;
+      const [newYacht] = await tx
+        .insert(yachts)
+        .values({
+          portId,
+          name: data.yacht.name,
+          hullNumber: data.yacht.hullNumber ?? null,
+          registration: data.yacht.registration ?? null,
+          flag: data.yacht.flag ?? null,
+          yearBuilt: data.yacht.yearBuilt ?? null,
+          lengthFt: data.yacht.lengthFt != null ? String(data.yacht.lengthFt) : null,
+          widthFt: data.yacht.widthFt != null ? String(data.yacht.widthFt) : null,
+          draftFt: data.yacht.draftFt != null ? String(data.yacht.draftFt) : null,
+          currentOwnerType: ownerType,
+          currentOwnerId: ownerId,
+          status: 'active',
+        })
+        .returning();
+      const yachtId = newYacht!.id;
+
+      // 3a. Open ownership_history row for the new yacht.
+      await tx.insert(yachtOwnershipHistory).values({
+        yachtId,
+        ownerType,
+        ownerId,
+        startDate: new Date(),
+        endDate: null,
+        createdBy: 'public-submission',
       });
-    }
 
-    // Create the interest
+      // 4. Store address if provided AND no primary address exists yet.
-    const [interest] = await db
+      if (data.address && Object.values(data.address).some(Boolean)) {
-      .insert(interests)
+        const existingAddr = await tx.query.clientAddresses.findFirst({
-      .values({
+          where: and(eq(clientAddresses.clientId, clientId), eq(clientAddresses.isPrimary, true)),
-        portId,
+        });
+        if (!existingAddr) {
+          await tx.insert(clientAddresses).values({
+            clientId,
+            portId,
+            label: 'Primary',
+            streetAddress: data.address.street ?? null,
+            city: data.address.city ?? null,
+            stateProvince: data.address.stateProvince ?? null,
+            postalCode: data.address.postalCode ?? null,
+            country: data.address.country ?? null,
+            isPrimary: true,
+          });
+        }
+      }
+
+      // 5. Create interest with yachtId wired up.
+      const [newInterest] = await tx
+        .insert(interests)
+        .values({
+          portId,
+          clientId,
+          berthId,
+          yachtId,
+          source: 'website',
+          pipelineStage: 'open',
+          notes: data.notes,
+        })
+        .returning();
+
+      return {
+        interestId: newInterest!.id,
         clientId,
-        berthId,
+        yachtId,
-        source: 'website',
+        companyId,
-        pipelineStage: 'open',
+      };
-        notes: data.notes,
+    });
-      })
-      .returning();
 
+    // ─── Post-commit side-effects (fire-and-forget) ─────────────────────────
     void createAuditLog({
       userId: null as unknown as string,
       portId,
       action: 'create',
       entityType: 'interest',
-      entityId: interest!.id,
+      entityId: result.interestId,
-      newValue: { clientId, source: 'website', pipelineStage: 'open', berthId },
+      newValue: {
+        clientId: result.clientId,
+        yachtId: result.yachtId,
+        companyId: result.companyId,
+        source: 'website',
+        pipelineStage: 'open',
+        berthId,
+      },
       metadata: { type: 'public_registration', ip },
       ipAddress: ip,
       userAgent: req.headers.get('user-agent') ?? 'unknown',
     });
 
-    // Fire notifications asynchronously (non-blocking)
     const port = await db.query.ports.findFirst({
       where: eq(ports.id, portId),
       columns: { slug: true },
@@ -148,7 +256,7 @@ export async function POST(req: NextRequest) {
     void sendInquiryNotifications({
       portId,
       portSlug: port?.slug ?? portId,
-      interestId: interest!.id,
+      interestId: result.interestId,
       clientFullName: fullName,
       clientEmail: data.email,
       clientPhone: data.phone,
@@ -157,7 +265,7 @@ export async function POST(req: NextRequest) {
     });
 
     return NextResponse.json(
-      { data: { id: interest!.id, message: 'Interest registered successfully' } },
+      { data: { id: result.interestId, message: 'Interest registered successfully' } },
       { status: 201 },
     );
   } catch (error) {
@@ -165,46 +273,33 @@ export async function POST(req: NextRequest) {
   }
 }
 
-async function createNewClient(
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+async function createClientInTx(
+  tx: Tx,
   portId: string,
   fullName: string,
-  data: {
+  data: Pick<PublicInterestData, 'email' | 'phone' | 'preferredContactMethod'>,
-    email: string;
-    phone: string;
-    companyName?: string;
-    yachtName?: string;
-    yachtLengthFt?: number;
-    yachtWidthFt?: number;
-    yachtDraftFt?: number;
-    preferredBerthSize?: string;
-    preferredContactMethod?: string;
-  },
 ): Promise<string> {
-  const [newClient] = await db
+  const [newClient] = await tx
     .insert(clients)
     .values({
       portId,
       fullName,
-      companyName: data.companyName,
-      yachtName: data.yachtName,
-      yachtLengthFt: data.yachtLengthFt != null ? String(data.yachtLengthFt) : undefined,
-      yachtWidthFt: data.yachtWidthFt != null ? String(data.yachtWidthFt) : undefined,
-      yachtDraftFt: data.yachtDraftFt != null ? String(data.yachtDraftFt) : undefined,
-      berthSizeDesired: data.preferredBerthSize,
       preferredContactMethod: data.preferredContactMethod,
       source: 'website',
     })
     .returning();
   const clientId = newClient!.id;
 
-  await db.insert(clientContacts).values({
+  await tx.insert(clientContacts).values({
     clientId,
     channel: 'email',
     value: data.email,
     isPrimary: true,
   });
 
-  await db.insert(clientContacts).values({
+  await tx.insert(clientContacts).values({
     clientId,
     channel: 'phone',
     value: data.phone,

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

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

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

@@ -0,0 +1,72 @@
+import { and, eq } from 'drizzle-orm';
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
+import { parseBody, parseQuery } from '@/lib/api/route-helpers';
+import { db } from '@/lib/db';
+import { berths } from '@/lib/db/schema/berths';
+import { NotFoundError, errorResponse } from '@/lib/errors';
+import { createPending, listReservations } from '@/lib/services/berth-reservations.service';
+import { createPendingSchema, listReservationsSchema } from '@/lib/validators/reservations';
+
+// URL berthId is authoritative; make body berthId optional (ignored anyway).
+const createPendingBodySchema = createPendingSchema
+  .omit({ berthId: true })
+  .extend({ berthId: createPendingSchema.shape.berthId.optional() });
+
+async function assertBerthInPort(berthId: string, portId: string): Promise<void> {
+  const berth = await db.query.berths.findFirst({
+    where: and(eq(berths.id, berthId), eq(berths.portId, portId)),
+  });
+  if (!berth) throw new NotFoundError('Berth');
+}
+
+export const listHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    await assertBerthInPort(params.id!, ctx.portId);
+
+    const query = parseQuery(req, listReservationsSchema);
+    // URL berthId is authoritative; override any client-supplied value.
+    const result = await listReservations(ctx.portId, { ...query, berthId: params.id! });
+    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);
+  }
+};
+
+export const createHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    await assertBerthInPort(params.id!, ctx.portId);
+
+    const body = await parseBody(req, createPendingBodySchema);
+    // URL berthId is authoritative; any body-supplied berthId is ignored.
+    const reservation = await createPending(
+      ctx.portId,
+      { ...body, berthId: params.id! },
+      {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      },
+    );
+    return NextResponse.json({ data: reservation }, { status: 201 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const GET = withAuth(withPermission('reservations', 'view', listHandler));
+export const POST = withAuth(withPermission('reservations', 'create', createHandler));

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

@@ -0,0 +1,59 @@
+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 { createPortalUser, resendActivation } from '@/lib/services/portal-auth.service';
+import { db } from '@/lib/db';
+import { eq } from 'drizzle-orm';
+import { portalUsers } from '@/lib/db/schema/portal';
+
+const inviteSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(200).optional(),
+});
+
+/**
+ * POST /api/v1/clients/:id/portal-user
+ *
+ * Admin creates a portal account for a client and triggers the activation
+ * email. Idempotent in spirit: if a portal user already exists for the
+ * email, returns 409 — the admin can resend the activation via
+ * ?action=resend.
+ */
+export const POST = withAuth(
+  withPermission('clients', 'edit', async (req, ctx, params) => {
+    try {
+      const url = new URL(req.url);
+      const action = url.searchParams.get('action');
+
+      if (action === 'resend') {
+        // Body is optional in resend mode; the portal user id is the path id
+        // in this case (not the client id). Looking up by client+email so
+        // admins don't have to track portal-user ids.
+        const body = await parseBody(req, inviteSchema);
+        const existing = await db.query.portalUsers.findFirst({
+          where: eq(portalUsers.email, body.email.toLowerCase().trim()),
+        });
+        if (!existing) {
+          return NextResponse.json({ error: 'Portal user not found' }, { status: 404 });
+        }
+        await resendActivation(existing.id, ctx.portId);
+        return NextResponse.json({ success: true });
+      }
+
+      const body = await parseBody(req, inviteSchema);
+      const result = await createPortalUser({
+        clientId: params.id!,
+        portId: ctx.portId,
+        email: body.email,
+        name: body.name,
+        createdBy: ctx.userId,
+      });
+      return NextResponse.json({ data: result }, { status: 201 });
+    } catch (err) {
+      return errorResponse(err);
+    }
+  }),
+);

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

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

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

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

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

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

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

@@ -0,0 +1,49 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { getCompanyById, updateCompany, archiveCompany } from '@/lib/services/companies.service';
+import { updateCompanySchema } from '@/lib/validators/companies';
+
+export const getHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const company = await getCompanyById(params.id!, ctx.portId);
+    return NextResponse.json({ data: company });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const patchHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const body = await parseBody(req, updateCompanySchema);
+    const updated = await updateCompany(params.id!, ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: updated });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const deleteHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    await archiveCompany(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('companies', 'view', getHandler));
+export const PATCH = withAuth(withPermission('companies', 'edit', patchHandler));
+export const DELETE = withAuth(withPermission('companies', 'delete', deleteHandler));

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

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

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

@@ -0,0 +1,47 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
+import { parseQuery, parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listCompanies, createCompany } from '@/lib/services/companies.service';
+import { listCompaniesSchema, createCompanySchema } from '@/lib/validators/companies';
+
+export const listHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const query = parseQuery(req, listCompaniesSchema);
+    const result = await listCompanies(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);
+  }
+};
+
+export const createHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const body = await parseBody(req, createCompanySchema);
+    const company = await createCompany(ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: company }, { status: 201 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const GET = withAuth(withPermission('companies', 'view', listHandler));
+export const POST = withAuth(withPermission('companies', 'create', createHandler));

src/app/api/v1/document-templates/[id]/generate-and-sign/route.ts

@@ -11,7 +11,7 @@ export const POST = withAuth(
     try {
       const body = await parseBody(req, generateAndSignSchema);
       const result = await generateAndSign(
-        params.id!,
+        params.id === 'documenso-template' ? null : params.id!,
         ctx.portId,
         {
           clientId: body.clientId,
@@ -19,6 +19,7 @@ export const POST = withAuth(
           berthId: body.berthId,
         },
         body.signers,
+        body.pathway,
         {
           userId: ctx.userId,
           portId: ctx.portId,

src/app/api/v1/documents/generate-eoi/route.ts

@@ -1,24 +0,0 @@
-import { NextResponse } from 'next/server';
-
-import { withAuth, withPermission } from '@/lib/api/helpers';
-import { parseBody } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { generateEoi } from '@/lib/services/documents.service';
-import { generateEoiSchema } from '@/lib/validators/documents';
-
-export const POST = withAuth(
-  withPermission('documents', 'create', async (req, ctx) => {
-    try {
-      const body = await parseBody(req, generateEoiSchema);
-      const doc = await generateEoi(body.interestId, ctx.portId, {
-        userId: ctx.userId,
-        portId: ctx.portId,
-        ipAddress: ctx.ipAddress,
-        userAgent: ctx.userAgent,
-      });
-      return NextResponse.json({ data: doc }, { status: 201 });
-    } catch (error) {
-      return errorResponse(error);
-    }
-  }),
-);

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

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

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

@@ -0,0 +1,49 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { getYachtById, updateYacht, archiveYacht } from '@/lib/services/yachts.service';
+import { updateYachtSchema } from '@/lib/validators/yachts';
+
+export const getHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const yacht = await getYachtById(params.id!, ctx.portId);
+    return NextResponse.json({ data: yacht });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const patchHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const body = await parseBody(req, updateYachtSchema);
+    const updated = await updateYacht(params.id!, ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: updated });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const deleteHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    await archiveYacht(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('yachts', 'view', getHandler));
+export const PATCH = withAuth(withPermission('yachts', 'edit', patchHandler));
+export const DELETE = withAuth(withPermission('yachts', 'delete', deleteHandler));

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

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

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

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

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

@@ -0,0 +1,47 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
+import { parseQuery, parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listYachts, createYacht } from '@/lib/services/yachts.service';
+import { listYachtsSchema, createYachtSchema } from '@/lib/validators/yachts';
+
+export const listHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const query = parseQuery(req, listYachtsSchema);
+    const result = await listYachts(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);
+  }
+};
+
+export const createHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const body = await parseBody(req, createYachtSchema);
+    const yacht = await createYacht(ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: yacht }, { status: 201 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const GET = withAuth(withPermission('yachts', 'view', listHandler));
+export const POST = withAuth(withPermission('yachts', 'create', createHandler));

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

@@ -2,11 +2,13 @@ import { NextRequest, NextResponse } from 'next/server';
 import { createHash } from 'crypto';
 
 import { db } from '@/lib/db';
-import { verifyDocumensoSignature } from '@/lib/services/documenso-webhook';
+import { verifyDocumensoSecret } from '@/lib/services/documenso-webhook';
 import {
   handleRecipientSigned,
   handleDocumentCompleted,
-  handleDocumentExpired,
+  handleDocumentOpened,
+  handleDocumentRejected,
+  handleDocumentCancelled,
 } from '@/lib/services/documents.service';
 import { env } from '@/lib/env';
 import { logger } from '@/lib/logger';
@@ -14,39 +16,58 @@ import { logger } from '@/lib/logger';
 // BR-024: Dedup via signatureHash unique index on documentEvents
 // Always return 200 from webhook (webhook best practice)
 
+// Documenso emits Prisma enum names on the wire (e.g. "DOCUMENT_SIGNED").
+// The UI displays them as lowercase-dotted ("document.signed") but the JSON
+// body uses the enum value as-is. Normalize both forms in case 2.x ever flips.
+function canonicalizeEvent(event: string): string {
+  return event.toUpperCase().replace(/\./g, '_');
+}
+
+type DocumensoRecipient = {
+  email: string;
+  signingStatus?: string;
+  readStatus?: string;
+  signedAt?: string | null;
+};
+
+type DocumensoWebhookBody = {
+  event: string;
+  payload: {
+    id: number | string;
+    recipients?: DocumensoRecipient[];
+  };
+};
+
 export async function POST(req: NextRequest): Promise<NextResponse> {
-  let payload: string;
+  let rawBody: string;
 
   try {
-    payload = await req.text();
+    rawBody = await req.text();
   } catch {
     return NextResponse.json({ ok: false }, { status: 200 });
   }
 
-  // Verify HMAC signature
+  // Documenso v1.13 + 2.x send the secret in plaintext via X-Documenso-Secret.
-  const signature = req.headers.get('x-documenso-signature') ?? '';
+  const providedSecret = req.headers.get('x-documenso-secret') ?? '';
 
-  if (!verifyDocumensoSignature(payload, signature, env.DOCUMENSO_WEBHOOK_SECRET)) {
+  if (!verifyDocumensoSecret(providedSecret, env.DOCUMENSO_WEBHOOK_SECRET)) {
-    logger.warn({ signature }, 'Invalid Documenso webhook signature');
+    logger.warn({ providedLen: providedSecret.length }, 'Invalid Documenso webhook secret');
-    return NextResponse.json({ ok: false, error: 'Invalid signature' }, { status: 200 });
+    return NextResponse.json({ ok: false, error: 'Invalid secret' }, { status: 200 });
   }
 
   // Compute deduplication hash
-  const signatureHash = createHash('sha256').update(payload).digest('hex');
+  const signatureHash = createHash('sha256').update(rawBody).digest('hex');
 
-  let parsed: { type: string; payload: Record<string, unknown> };
+  let parsed: DocumensoWebhookBody;
 
   try {
-    parsed = JSON.parse(payload) as typeof parsed;
+    parsed = JSON.parse(rawBody) as DocumensoWebhookBody;
   } catch {
     logger.warn('Failed to parse Documenso webhook payload');
     return NextResponse.json({ ok: false }, { status: 200 });
   }
 
-  // Dedup: try to insert a sentinel documentEvent with signatureHash
+  // Replay guard: if any event with this hash already exists, skip.
-  // We need a documentId — if dedup fails at this stage we can't easily check.
-  // Instead, store the hash lookup on the first real documentEvent insert in handlers.
-  // Here we just check if this hash was already seen in any event.
   try {
     const existing = await db.query.documentEvents.findFirst({
       where: (de, { eq }) => eq(de.signatureHash, signatureHash),
@@ -60,33 +81,69 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
     logger.error({ err }, 'Failed to check duplicate webhook');
   }
 
+  const event = canonicalizeEvent(parsed.event);
+  const documensoId = String(parsed.payload?.id ?? '');
+  const recipients = parsed.payload?.recipients ?? [];
+
+  if (!documensoId) {
+    logger.warn({ event }, 'Documenso webhook missing payload.id');
+    return NextResponse.json({ ok: true }, { status: 200 });
+  }
+
   try {
-    switch (parsed.type) {
+    switch (event) {
-      case 'RECIPIENT_SIGNED':
+      case 'DOCUMENT_SIGNED':
-        await handleRecipientSigned({
+      case 'DOCUMENT_RECIPIENT_COMPLETED': {
-          documentId: parsed.payload.documentId as string,
+        // v1.13 fires DOCUMENT_SIGNED per recipient sign;
-          recipientEmail: parsed.payload.recipientEmail as string,
+        // 2.x fires DOCUMENT_RECIPIENT_COMPLETED for the same semantics.
+        const signedRecipients = recipients.filter(
+          (r) => r.signingStatus === 'SIGNED' || Boolean(r.signedAt),
+        );
+        for (const r of signedRecipients) {
+          await handleRecipientSigned({
+            documentId: documensoId,
+            recipientEmail: r.email,
+            signatureHash: `${signatureHash}:signed:${r.email}`,
+          });
+        }
+        break;
+      }
+
+      case 'DOCUMENT_OPENED': {
+        const openedRecipients = recipients.filter((r) => r.readStatus === 'OPENED');
+        for (const r of openedRecipients) {
+          await handleDocumentOpened({
+            documentId: documensoId,
+            recipientEmail: r.email,
+            signatureHash: `${signatureHash}:opened:${r.email}`,
+          });
+        }
+        break;
+      }
+
+      case 'DOCUMENT_COMPLETED':
+        await handleDocumentCompleted({ documentId: documensoId });
+        break;
+
+      case 'DOCUMENT_REJECTED': {
+        const rejecting = recipients.find((r) => r.signingStatus === 'REJECTED');
+        await handleDocumentRejected({
+          documentId: documensoId,
+          recipientEmail: rejecting?.email,
           signatureHash,
         });
         break;
+      }
 
-      case 'DOCUMENT_COMPLETED':
+      case 'DOCUMENT_CANCELLED':
-        await handleDocumentCompleted({
+        await handleDocumentCancelled({ documentId: documensoId, signatureHash });
-          documentId: parsed.payload.documentId as string,
-        });
-        break;
-
-      case 'DOCUMENT_EXPIRED':
-        await handleDocumentExpired({
-          documentId: parsed.payload.documentId as string,
-        });
         break;
 
       default:
-        logger.info({ type: parsed.type }, 'Unhandled Documenso webhook event type');
+        logger.info({ event }, 'Unhandled Documenso webhook event type');
     }
   } catch (err) {
-    logger.error({ err, type: parsed.type }, 'Error processing Documenso webhook');
+    logger.error({ err, event }, 'Error processing Documenso webhook');
   }
 
   return NextResponse.json({ ok: true }, { status: 200 });

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

@@ -0,0 +1,90 @@
+'use client';
+
+import { useState } from 'react';
+import { useParams } from 'next/navigation';
+import { useQuery } from '@tanstack/react-query';
+import { Plus } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { PermissionGate } from '@/components/shared/permission-gate';
+import { EmptyState } from '@/components/shared/empty-state';
+import { ReservationList, type ReservationRow } from '@/components/reservations/reservation-list';
+import { BerthReserveDialog } from '@/components/reservations/berth-reserve-dialog';
+import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { apiFetch } from '@/lib/api/client';
+
+interface BerthReservationsTabProps {
+  berthId: string;
+}
+
+export function BerthReservationsTab({ berthId }: BerthReservationsTabProps) {
+  const routeParams = useParams<{ portSlug: string }>();
+  const portSlug = routeParams?.portSlug ?? '';
+  const [reserveOpen, setReserveOpen] = useState(false);
+
+  const { data, isLoading } = useQuery<{ data: ReservationRow[]; pagination?: unknown }>({
+    queryKey: ['berths', berthId, 'reservations'],
+    queryFn: () =>
+      apiFetch(
+        `/api/v1/berths/${berthId}/reservations?page=1&limit=50&order=desc&includeArchived=false`,
+      ),
+  });
+
+  useRealtimeInvalidation({
+    'berth_reservation:created': [['berths', berthId, 'reservations']],
+    'berth_reservation:activated': [['berths', berthId, 'reservations']],
+    'berth_reservation:ended': [['berths', berthId, 'reservations']],
+    'berth_reservation:cancelled': [['berths', berthId, 'reservations']],
+  });
+
+  const reservations = data?.data ?? [];
+  const active = reservations.find((r) => r.status === 'active');
+  const history = reservations.filter((r) => r.status !== 'active');
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center justify-between">
+        <h3 className="text-lg font-semibold">Reservations</h3>
+        <PermissionGate resource="reservations" action="create">
+          <Button size="sm" onClick={() => setReserveOpen(true)}>
+            <Plus className="mr-1.5 h-4 w-4" />
+            Reserve this berth
+          </Button>
+        </PermissionGate>
+      </div>
+
+      {/* Active reservation card */}
+      <Card>
+        <CardHeader className="pb-3">
+          <CardTitle className="text-sm font-medium">Active reservation</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {active ? (
+            <ReservationList reservations={[active]} portSlug={portSlug} />
+          ) : (
+            <p className="text-sm text-muted-foreground">No active reservation.</p>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* History */}
+      <Card>
+        <CardHeader className="pb-3">
+          <CardTitle className="text-sm font-medium">History</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {isLoading ? (
+            <p className="text-sm text-muted-foreground">Loading…</p>
+          ) : history.length === 0 ? (
+            <EmptyState title="No past reservations" description="Nothing here yet." />
+          ) : (
+            <ReservationList reservations={history} portSlug={portSlug} />
+          )}
+        </CardContent>
+      </Card>
+
+      <BerthReserveDialog open={reserveOpen} onOpenChange={setReserveOpen} berthId={berthId} />
+    </div>
+  );
+}

src/components/berths/berth-tabs.tsx

@@ -3,6 +3,7 @@
 import { type DetailTab } from '@/components/shared/detail-layout';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { TagBadge } from '@/components/shared/tag-badge';
+import { BerthReservationsTab } from './berth-reservations-tab';
 
 type BerthData = {
   id: string;
@@ -87,7 +88,10 @@ function OverviewTab({ berth }: { berth: BerthData }) {
             }
           />
           <SpecRow label="Draft" value={formatDim(berth.draftFt, berth.draftM)} />
-          <SpecRow label="Nominal Boat Size" value={berth.nominalBoatSize || berth.nominalBoatSizeM} />
+          <SpecRow
+            label="Nominal Boat Size"
+            value={berth.nominalBoatSize || berth.nominalBoatSizeM}
+          />
           <SpecRow
             label="Water Depth"
             value={
@@ -179,6 +183,11 @@ export function buildBerthTabs(berth: BerthData): DetailTab[] {
       label: 'Interests',
       content: <StubTab label="Interests" />,
     },
+    {
+      id: 'reservations',
+      label: 'Reservations',
+      content: <BerthReservationsTab berthId={berth.id} />,
+    },
     {
       id: 'waiting-list',
       label: 'Waiting List',

src/components/clients/client-columns.tsx

@@ -18,7 +18,7 @@ import { TagBadge } from '@/components/shared/tag-badge';
 export interface ClientRow {
   id: string;
   fullName: string;
-  companyName: string | null;
+  nationality: string | null;
   source: string | null;
   archivedAt: string | null;
   createdAt: string;
@@ -39,6 +39,10 @@ interface GetColumnsOptions {
   onArchive: (client: ClientRow) => void;
 }
 
+// TODO: Add "Yachts" (count) and "Primary company" columns once the
+// GET /api/v1/clients list endpoint joins owned-yachts and primary-company
+// data into the row shape. Until then, the columns are omitted rather than
+// shown as empty placeholders.
 export function getClientColumns({
   portSlug,
   onEdit,
@@ -59,14 +63,6 @@ export function getClientColumns({
         </Link>
       ),
     },
-    {
-      id: 'companyName',
-      accessorKey: 'companyName',
-      header: 'Company',
-      cell: ({ getValue }) => (
-        <span className="text-muted-foreground">{(getValue() as string | null) ?? '—'}</span>
-      ),
-    },
     {
       id: 'primaryContact',
       header: 'Primary Contact',
@@ -82,6 +78,14 @@ export function getClientColumns({
         );
       },
     },
+    {
+      id: 'nationality',
+      accessorKey: 'nationality',
+      header: 'Nationality',
+      cell: ({ getValue }) => (
+        <span className="text-muted-foreground">{(getValue() as string | null) ?? '—'}</span>
+      ),
+    },
     {
       id: 'source',
       accessorKey: 'source',
@@ -149,10 +153,7 @@ export function getClientColumns({
               <Pencil className="mr-2 h-3.5 w-3.5" />
               Edit
             </DropdownMenuItem>
-            <DropdownMenuItem
+            <DropdownMenuItem className="text-destructive" onClick={() => onArchive(row.original)}>
-              className="text-destructive"
-              onClick={() => onArchive(row.original)}
-            >
               <Archive className="mr-2 h-3.5 w-3.5" />
               Archive
             </DropdownMenuItem>

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

@@ -0,0 +1,103 @@
+'use client';
+
+import Link from 'next/link';
+import { useParams } from 'next/navigation';
+import { format } from 'date-fns';
+
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableRow,
+} from '@/components/ui/table';
+import { Badge } from '@/components/ui/badge';
+import { EmptyState } from '@/components/shared/empty-state';
+
+interface ClientCompaniesTabProps {
+  clientId: string;
+  companies: Array<{
+    membershipId: string;
+    role: string;
+    isPrimary: boolean;
+    startDate: string | Date;
+    company: {
+      id: string;
+      name: string;
+      legalName: string | null;
+      status: string;
+    };
+  }>;
+}
+
+function formatSince(startDate: string | Date): string {
+  const d = typeof startDate === 'string' ? new Date(startDate) : startDate;
+  if (Number.isNaN(d.getTime())) return '—';
+  return format(d, 'MMM d, yyyy');
+}
+
+export function ClientCompaniesTab({ clientId: _clientId, companies }: ClientCompaniesTabProps) {
+  const routeParams = useParams<{ portSlug: string }>();
+  const portSlug = routeParams?.portSlug ?? '';
+
+  if (companies.length === 0) {
+    return (
+      <EmptyState
+        title="No company memberships"
+        description="This client is not affiliated with any companies yet. Add a membership from a company's detail page."
+      />
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <h3 className="text-sm font-medium">Company affiliations</h3>
+      <div className="rounded-md border">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Company</TableHead>
+              <TableHead>Role</TableHead>
+              <TableHead>Primary</TableHead>
+              <TableHead>Since</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {companies.map((m) => (
+              <TableRow key={m.membershipId}>
+                <TableCell>
+                  <Link
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    href={`/${portSlug}/companies/${m.company.id}` as any}
+                    className="text-primary hover:underline"
+                  >
+                    {m.company.name}
+                  </Link>
+                  {m.company.legalName && (
+                    <span className="ml-2 text-xs text-muted-foreground">
+                      ({m.company.legalName})
+                    </span>
+                  )}
+                </TableCell>
+                <TableCell className="capitalize">{m.role.replace('_', ' ')}</TableCell>
+                <TableCell>
+                  {m.isPrimary ? (
+                    <Badge variant="secondary" className="text-xs">
+                      Primary
+                    </Badge>
+                  ) : (
+                    <span className="text-muted-foreground">—</span>
+                  )}
+                </TableCell>
+                <TableCell className="text-muted-foreground text-sm">
+                  {formatSince(m.startDate)}
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+    </div>
+  );
+}

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

@@ -9,19 +9,14 @@ import { Badge } from '@/components/ui/badge';
 import { TagBadge } from '@/components/shared/tag-badge';
 import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
 import { ClientForm } from '@/components/clients/client-form';
+import { PortalInviteButton } from '@/components/clients/portal-invite-button';
 import { apiFetch } from '@/lib/api/client';
 
 interface ClientDetailHeaderProps {
   client: {
     id: string;
     fullName: string;
-    companyName?: string | null;
     nationality?: string | null;
-    isProxy?: boolean;
-    proxyType?: string | null;
-    actualOwnerName?: string | null;
-    yachtName?: string | null;
-    berthSizeDesired?: string | null;
     preferredContactMethod?: string | null;
     preferredLanguage?: string | null;
     timezone?: string | null;
@@ -36,13 +31,7 @@ interface ClientDetailHeaderProps {
 type ClientFormClient = {
   id: string;
   fullName: string;
-  companyName?: string | null;
   nationality?: string | null;
-  isProxy?: boolean;
-  proxyType?: string | null;
-  actualOwnerName?: string | null;
-  yachtName?: string | null;
-  berthSizeDesired?: string | null;
   preferredContactMethod?: string | null;
   preferredLanguage?: string | null;
   timezone?: string | null;
@@ -67,8 +56,7 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
   const isArchived = !!client.archivedAt;
 
   const archiveMutation = useMutation({
-    mutationFn: () =>
+    mutationFn: () => apiFetch(`/api/v1/clients/${client.id}`, { method: 'DELETE' }),
-      apiFetch(`/api/v1/clients/${client.id}`, { method: 'DELETE' }),
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['clients', client.id] });
       queryClient.invalidateQueries({ queryKey: ['clients'] });
@@ -77,8 +65,7 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
   });
 
   const restoreMutation = useMutation({
-    mutationFn: () =>
+    mutationFn: () => apiFetch(`/api/v1/clients/${client.id}/restore`, { method: 'POST' }),
-      apiFetch(`/api/v1/clients/${client.id}/restore`, { method: 'POST' }),
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['clients', client.id] });
       queryClient.invalidateQueries({ queryKey: ['clients'] });
@@ -86,10 +73,12 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
     },
   });
 
-  const primaryEmail = client.contacts?.find((c) => c.channel === 'email' && c.isPrimary)
+  const primaryEmail =
-    ?? client.contacts?.find((c) => c.channel === 'email');
+    client.contacts?.find((c) => c.channel === 'email' && c.isPrimary) ??
-  const primaryPhone = client.contacts?.find((c) => c.channel === 'phone' && c.isPrimary)
+    client.contacts?.find((c) => c.channel === 'email');
-    ?? client.contacts?.find((c) => c.channel === 'phone');
+  const primaryPhone =
+    client.contacts?.find((c) => c.channel === 'phone' && c.isPrimary) ??
+    client.contacts?.find((c) => c.channel === 'phone');
 
   return (
     <>
@@ -97,23 +86,14 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
         <div className="flex items-start gap-3 flex-wrap">
           <div className="flex-1 min-w-0">
             <div className="flex items-center gap-2 flex-wrap">
-              <h1 className="text-2xl font-bold text-foreground truncate">
+              <h1 className="text-2xl font-bold text-foreground truncate">{client.fullName}</h1>
-                {client.fullName}
-              </h1>
               {isArchived && (
-                <Badge variant="secondary" className="text-xs">Archived</Badge>
+                <Badge variant="secondary" className="text-xs">
-              )}
+                  Archived
-              {client.isProxy && (
-                <Badge variant="outline" className="text-xs capitalize">
-                  Proxy {client.proxyType ? `(${client.proxyType.replace('_', ' ')})` : ''}
                 </Badge>
               )}
             </div>
 
-            {client.companyName && (
-              <p className="text-muted-foreground mt-0.5">{client.companyName}</p>
-            )}
-
             <div className="flex items-center gap-4 mt-2 flex-wrap text-sm text-muted-foreground">
               {client.source && (
                 <span>
@@ -148,11 +128,14 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
 
           {/* Actions */}
           <div className="flex items-center gap-2">
-            <Button
+            {!isArchived && (
-              variant="outline"
+              <PortalInviteButton
-              size="sm"
+                clientId={client.id}
-              onClick={() => setEditOpen(true)}
+                clientName={client.fullName}
-            >
+                defaultEmail={primaryEmail?.value}
+              />
+            )}
+            <Button variant="outline" size="sm" onClick={() => setEditOpen(true)}>
               <Pencil className="mr-1.5 h-3.5 w-3.5" />
               Edit
             </Button>

src/components/clients/client-detail.tsx

@@ -12,19 +12,7 @@ interface ClientData {
   id: string;
   portId: string;
   fullName: string;
-  companyName: string | null;
   nationality: string | null;
-  isProxy: boolean;
-  proxyType: string | null;
-  actualOwnerName: string | null;
-  yachtName: string | null;
-  yachtLengthFt: string | null;
-  yachtWidthFt: string | null;
-  yachtDraftFt: string | null;
-  yachtLengthM: string | null;
-  yachtWidthM: string | null;
-  yachtDraftM: string | null;
-  berthSizeDesired: string | null;
   preferredContactMethod: string | null;
   preferredLanguage: string | null;
   timezone: string | null;
@@ -46,6 +34,35 @@ interface ClientData {
     name: string;
     color: string;
   }>;
+  yachts: Array<{
+    id: string;
+    name: string;
+    hullNumber: string | null;
+    registration: string | null;
+    lengthFt: string | null;
+    widthFt: string | null;
+    status: string;
+  }>;
+  companies: Array<{
+    membershipId: string;
+    role: string;
+    isPrimary: boolean;
+    startDate: string | Date;
+    company: {
+      id: string;
+      name: string;
+      legalName: string | null;
+      status: string;
+    };
+  }>;
+  activeReservations: Array<{
+    id: string;
+    berthId: string;
+    yachtId: string;
+    startDate: string | Date;
+    tenureType: string;
+    status: string;
+  }>;
 }
 
 interface ClientDetailProps {
@@ -64,11 +81,15 @@ export function ClientDetail({ clientId, currentUserId }: ClientDetailProps) {
     'client:updated': [['clients', clientId]],
     'client:archived': [['clients', clientId]],
     'client:restored': [['clients', clientId]],
+    'yacht:ownership_transferred': [['clients', clientId]],
+    'company_membership:added': [['clients', clientId]],
+    'company_membership:ended': [['clients', clientId]],
+    'berth_reservation:activated': [['clients', clientId]],
+    'berth_reservation:ended': [['clients', clientId]],
+    'berth_reservation:cancelled': [['clients', clientId]],
   });
 
-  const tabs = data
+  const tabs = data ? getClientTabs({ clientId, currentUserId, client: data }) : [];
-    ? getClientTabs({ clientId, currentUserId, client: data })
-    : [];
 
   return (
     <DetailLayout

src/components/clients/client-filters.tsx

@@ -24,11 +24,6 @@ export const clientFilterDefinitions: FilterDefinition[] = [
     type: 'text',
     placeholder: 'Filter by nationality...',
   },
-  {
-    key: 'isProxy',
-    label: 'Proxy Client',
-    type: 'boolean',
-  },
   {
     key: 'includeArchived',
     label: 'Include Archived',

src/components/clients/client-form.tsx

@@ -16,13 +16,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
-import {
+import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter } from '@/components/ui/sheet';
-  Sheet,
-  SheetContent,
-  SheetHeader,
-  SheetTitle,
-  SheetFooter,
-} from '@/components/ui/sheet';
 import { Checkbox } from '@/components/ui/checkbox';
 import { Separator } from '@/components/ui/separator';
 import { TagPicker } from '@/components/shared/tag-picker';
@@ -36,13 +30,7 @@ interface ClientFormProps {
   client?: {
     id: string;
     fullName: string;
-    companyName?: string | null;
     nationality?: string | null;
-    isProxy?: boolean;
-    proxyType?: string | null;
-    actualOwnerName?: string | null;
-    yachtName?: string | null;
-    berthSizeDesired?: string | null;
     preferredContactMethod?: string | null;
     preferredLanguage?: string | null;
     timezone?: string | null;
@@ -53,6 +41,7 @@ interface ClientFormProps {
       value: string;
       label?: string | null;
       isPrimary?: boolean;
+      notes?: string | null;
     }>;
     tags?: Array<{ id: string }>;
   };
@@ -75,13 +64,11 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
     defaultValues: {
       fullName: '',
       contacts: [{ channel: 'email', value: '', isPrimary: true }],
-      isProxy: false,
       tagIds: [],
     },
   });
 
   const { fields, append, remove } = useFieldArray({ control, name: 'contacts' });
-  const isProxy = watch('isProxy');
   const tagIds = watch('tagIds') ?? [];
 
   // Populate form when editing
@@ -89,14 +76,10 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
     if (client && open) {
       reset({
         fullName: client.fullName,
-        companyName: client.companyName ?? undefined,
         nationality: client.nationality ?? undefined,
-        isProxy: client.isProxy ?? false,
+        preferredContactMethod:
-        proxyType: client.proxyType ?? undefined,
+          (client.preferredContactMethod as CreateClientInput['preferredContactMethod']) ??
-        actualOwnerName: client.actualOwnerName ?? undefined,
+          undefined,
-        yachtName: client.yachtName ?? undefined,
-        berthSizeDesired: client.berthSizeDesired ?? undefined,
-        preferredContactMethod: (client.preferredContactMethod as CreateClientInput['preferredContactMethod']) ?? undefined,
         preferredLanguage: client.preferredLanguage ?? undefined,
         timezone: client.timezone ?? undefined,
         source: (client.source as CreateClientInput['source']) ?? undefined,
@@ -108,6 +91,7 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
                 value: c.value,
                 label: c.label ?? undefined,
                 isPrimary: c.isPrimary ?? false,
+                notes: c.notes ?? undefined,
               }))
             : [{ channel: 'email', value: '', isPrimary: true }],
         tagIds: client.tags?.map((t) => t.id) ?? [],
@@ -116,7 +100,6 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
       reset({
         fullName: '',
         contacts: [{ channel: 'email', value: '', isPrimary: true }],
-        isProxy: false,
         tagIds: [],
       });
     }
@@ -151,10 +134,7 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
           <SheetTitle>{isEdit ? 'Edit Client' : 'New Client'}</SheetTitle>
         </SheetHeader>
 
-        <form
+        <form onSubmit={handleSubmit((data) => mutation.mutate(data))} className="space-y-6 py-6">
-          onSubmit={handleSubmit((data) => mutation.mutate(data))}
-          className="space-y-6 py-6"
-        >
           {/* Basic Info */}
           <div className="space-y-4">
             <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
@@ -170,11 +150,6 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
                 )}
               </div>
 
-              <div className="space-y-1">
-                <Label>Company Name</Label>
-                <Input {...register('companyName')} placeholder="Acme Corp" />
-              </div>
-
               <div className="space-y-1">
                 <Label>Nationality</Label>
                 <Input {...register('nationality')} placeholder="British" />
@@ -194,9 +169,7 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
                 type="button"
                 variant="outline"
                 size="sm"
-                onClick={() =>
+                onClick={() => append({ channel: 'email', value: '', isPrimary: false })}
-                  append({ channel: 'email', value: '', isPrimary: false })
-                }
               >
                 <Plus className="mr-1 h-3.5 w-3.5" />
                 Add Contact
@@ -218,7 +191,10 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
                     <Select
                       value={watch(`contacts.${index}.channel`)}
                       onValueChange={(v) =>
-                        setValue(`contacts.${index}.channel`, v as 'email' | 'phone' | 'whatsapp' | 'other')
+                        setValue(
+                          `contacts.${index}.channel`,
+                          v as 'email' | 'phone' | 'whatsapp' | 'other',
+                        )
                       }
                     >
                       <SelectTrigger className="h-8">
@@ -254,9 +230,7 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
                   <div className="col-span-1 flex items-center gap-1 pb-1">
                     <Checkbox
                       checked={watch(`contacts.${index}.isPrimary`)}
-                      onCheckedChange={(v) =>
+                      onCheckedChange={(v) => setValue(`contacts.${index}.isPrimary`, !!v)}
-                        setValue(`contacts.${index}.isPrimary`, !!v)
-                      }
                     />
                     <Label className="text-xs">Primary</Label>
                   </div>
@@ -281,72 +255,6 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
 
           <Separator />
 
-          {/* Proxy */}
-          <div className="space-y-4">
-            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
-              Proxy Information
-            </h3>
-            <div className="flex items-center gap-2">
-              <Checkbox
-                id="isProxy"
-                checked={watch('isProxy')}
-                onCheckedChange={(v) => setValue('isProxy', !!v)}
-              />
-              <Label htmlFor="isProxy">This is a proxy client</Label>
-            </div>
-
-            {isProxy && (
-              <div className="grid grid-cols-2 gap-4">
-                <div className="space-y-1">
-                  <Label>Proxy Type</Label>
-                  <Select
-                    value={watch('proxyType') ?? ''}
-                    onValueChange={(v) => setValue('proxyType', v)}
-                  >
-                    <SelectTrigger>
-                      <SelectValue placeholder="Select type" />
-                    </SelectTrigger>
-                    <SelectContent>
-                      <SelectItem value="broker">Broker</SelectItem>
-                      <SelectItem value="representative">Representative</SelectItem>
-                      <SelectItem value="family_member">Family Member</SelectItem>
-                      <SelectItem value="legal_counsel">Legal Counsel</SelectItem>
-                      <SelectItem value="other">Other</SelectItem>
-                    </SelectContent>
-                  </Select>
-                </div>
-                <div className="space-y-1">
-                  <Label>Actual Owner Name</Label>
-                  <Input
-                    {...register('actualOwnerName')}
-                    placeholder="Actual owner"
-                  />
-                </div>
-              </div>
-            )}
-          </div>
-
-          <Separator />
-
-          {/* Yacht Details */}
-          <div className="space-y-4">
-            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
-              Yacht Details
-            </h3>
-            <div className="grid grid-cols-2 gap-4">
-              <div className="col-span-2 space-y-1">
-                <Label>Yacht Name</Label>
-                <Input {...register('yachtName')} placeholder="My Yacht" />
-              </div>
-              <div className="space-y-1">
-                <Label>Berth Size Desired</Label>
-                <Input {...register('berthSizeDesired')} placeholder="e.g. 30m" />
-              </div>
-            </div>
-          </div>
-
-          <Separator />
-
           {/* Source & Preferences */}
           <div className="space-y-4">
             <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
@@ -357,7 +265,9 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
                 <Label>Source</Label>
                 <Select
                   value={watch('source') ?? ''}
-                  onValueChange={(v) => setValue('source', v as 'website' | 'manual' | 'referral' | 'broker')}
+                  onValueChange={(v) =>
+                    setValue('source', v as 'website' | 'manual' | 'referral' | 'broker')
+                  }
                 >
                   <SelectTrigger>
                     <SelectValue placeholder="Select source" />
@@ -374,7 +284,9 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
                 <Label>Preferred Contact Method</Label>
                 <Select
                   value={watch('preferredContactMethod') ?? ''}
-                  onValueChange={(v) => setValue('preferredContactMethod', v as 'email' | 'phone' | 'whatsapp')}
+                  onValueChange={(v) =>
+                    setValue('preferredContactMethod', v as 'email' | 'phone' | 'whatsapp')
+                  }
                 >
                   <SelectTrigger>
                     <SelectValue placeholder="Select method" />
@@ -396,10 +308,7 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
               </div>
               <div className="col-span-2 space-y-1">
                 <Label>Source Details</Label>
-                <Input
+                <Input {...register('sourceDetails')} placeholder="Referred by John Doe" />
-                  {...register('sourceDetails')}
-                  placeholder="Referred by John Doe"
-                />
               </div>
             </div>
           </div>
@@ -409,18 +318,11 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
           {/* Tags */}
           <div className="space-y-2">
             <Label>Tags</Label>
-            <TagPicker
+            <TagPicker selectedIds={tagIds} onChange={(ids) => setValue('tagIds', ids)} />
-              selectedIds={tagIds}
-              onChange={(ids) => setValue('tagIds', ids)}
-            />
           </div>
 
           <SheetFooter>
-            <Button
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
-              type="button"
-              variant="outline"
-              onClick={() => onOpenChange(false)}
-            >
               Cancel
             </Button>
             <Button type="submit" disabled={isSubmitting || mutation.isPending}>

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

@@ -0,0 +1,51 @@
+'use client';
+
+import { ReservationList, type ReservationRow } from '@/components/reservations/reservation-list';
+
+interface ClientReservationsTabProps {
+  clientId: string;
+  activeReservations: Array<{
+    id: string;
+    berthId: string;
+    yachtId: string;
+    startDate: string | Date;
+    tenureType: string;
+    status: string;
+  }>;
+}
+
+export function ClientReservationsTab({
+  clientId,
+  activeReservations,
+}: ClientReservationsTabProps) {
+  const rows: ReservationRow[] = activeReservations.map((r) => ({
+    id: r.id,
+    berthId: r.berthId,
+    portId: '', // not rendered by ReservationList
+    clientId,
+    yachtId: r.yachtId,
+    status: r.status as ReservationRow['status'],
+    startDate: typeof r.startDate === 'string' ? r.startDate : r.startDate.toISOString(),
+    endDate: null,
+    tenureType: r.tenureType,
+    contractFileId: null,
+    notes: null,
+    createdAt: '',
+  }));
+
+  return (
+    <div className="space-y-4">
+      <div>
+        <h3 className="text-sm font-medium">Active reservations</h3>
+        <p className="text-xs text-muted-foreground mt-0.5">
+          Showing currently active reservations. History is coming soon.
+        </p>
+      </div>
+      <ReservationList
+        reservations={rows}
+        showBerth
+        emptyMessage="This client has no active reservations."
+      />
+    </div>
+  );
+}

src/components/clients/client-tabs.tsx

@@ -2,22 +2,16 @@
 
 import type { DetailTab } from '@/components/shared/detail-layout';
 import { NotesList } from '@/components/shared/notes-list';
+import { ClientYachtsTab } from '@/components/clients/client-yachts-tab';
+import { ClientCompaniesTab } from '@/components/clients/client-companies-tab';
+import { ClientReservationsTab } from '@/components/clients/client-reservations-tab';
 
 interface ClientTabsOptions {
   clientId: string;
   currentUserId?: string;
   client: {
     fullName: string;
-    companyName?: string | null;
     nationality?: string | null;
-    isProxy?: boolean;
-    proxyType?: string | null;
-    actualOwnerName?: string | null;
-    yachtName?: string | null;
-    yachtLengthFt?: string | null;
-    yachtWidthFt?: string | null;
-    yachtDraftFt?: string | null;
-    berthSizeDesired?: string | null;
     preferredContactMethod?: string | null;
     preferredLanguage?: string | null;
     timezone?: string | null;
@@ -30,6 +24,36 @@ interface ClientTabsOptions {
       label?: string | null;
       isPrimary: boolean;
     }>;
+    yachts: Array<{
+      id: string;
+      name: string;
+      hullNumber: string | null;
+      registration: string | null;
+      lengthFt: string | null;
+      widthFt: string | null;
+      status: string;
+    }>;
+    companies: Array<{
+      membershipId: string;
+      role: string;
+      isPrimary: boolean;
+      startDate: string | Date;
+      company: {
+        id: string;
+        name: string;
+        legalName: string | null;
+        status: string;
+      };
+    }>;
+    activeReservations: Array<{
+      id: string;
+      berthId: string;
+      yachtId: string;
+      startDate: string | Date;
+      tenureType: string;
+      status: string;
+    }>;
+    tags?: Array<{ id: string; name: string; color: string }>;
   };
 }
 
@@ -51,14 +75,10 @@ function OverviewTab({ client }: { client: ClientTabsOptions['client'] }) {
         <h3 className="text-sm font-medium mb-2">Personal Information</h3>
         <dl>
           <InfoRow label="Full Name" value={client.fullName} />
-          <InfoRow label="Company" value={client.companyName} />
           <InfoRow label="Nationality" value={client.nationality} />
           <InfoRow label="Preferred Language" value={client.preferredLanguage} />
           <InfoRow label="Timezone" value={client.timezone} />
-          <InfoRow
+          <InfoRow label="Preferred Contact" value={client.preferredContactMethod} />
-            label="Preferred Contact"
-            value={client.preferredContactMethod}
-          />
         </dl>
       </div>
 
@@ -72,18 +92,12 @@ function OverviewTab({ client }: { client: ClientTabsOptions['client'] }) {
                 key={c.id}
                 className="flex items-center gap-2 p-2 rounded-lg border bg-muted/30 text-sm"
               >
-                <span className="capitalize text-muted-foreground w-20 shrink-0">
+                <span className="capitalize text-muted-foreground w-20 shrink-0">{c.channel}</span>
-                  {c.channel}
-                </span>
                 <span className="flex-1">{c.value}</span>
                 {c.label && (
-                  <span className="text-xs text-muted-foreground capitalize">
+                  <span className="text-xs text-muted-foreground capitalize">{c.label}</span>
-                    {c.label}
-                  </span>
-                )}
-                {c.isPrimary && (
-                  <span className="text-xs font-medium text-primary">Primary</span>
                 )}
+                {c.isPrimary && <span className="text-xs font-medium text-primary">Primary</span>}
               </div>
             ))}
           </div>
@@ -92,41 +106,6 @@ function OverviewTab({ client }: { client: ClientTabsOptions['client'] }) {
         )}
       </div>
 
-      {/* Yacht Details */}
-      {(client.yachtName ||
-        client.yachtLengthFt ||
-        client.berthSizeDesired) && (
-        <div className="space-y-1">
-          <h3 className="text-sm font-medium mb-2">Yacht Details</h3>
-          <dl>
-            <InfoRow label="Yacht Name" value={client.yachtName} />
-            <InfoRow
-              label="Length"
-              value={
-                client.yachtLengthFt
-                  ? `${client.yachtLengthFt} ft`
-                  : undefined
-              }
-            />
-            <InfoRow
-              label="Width"
-              value={
-                client.yachtWidthFt ? `${client.yachtWidthFt} ft` : undefined
-              }
-            />
-            <InfoRow
-              label="Draft"
-              value={
-                client.yachtDraftFt
-                  ? `${client.yachtDraftFt} ft`
-                  : undefined
-              }
-            />
-            <InfoRow label="Berth Size Desired" value={client.berthSizeDesired} />
-          </dl>
-        </div>
-      )}
-
       {/* Source */}
       {(client.source || client.sourceDetails) && (
         <div className="space-y-1">
@@ -138,34 +117,54 @@ function OverviewTab({ client }: { client: ClientTabsOptions['client'] }) {
         </div>
       )}
 
-      {/* Proxy Info */}
+      {/* Tags */}
-      {client.isProxy && (
+      {client.tags && client.tags.length > 0 && (
         <div className="space-y-1">
-          <h3 className="text-sm font-medium mb-2">Proxy Information</h3>
+          <h3 className="text-sm font-medium mb-2">Tags</h3>
-          <dl>
+          <div className="flex flex-wrap gap-1">
-            <InfoRow
+            {client.tags.map((tag) => (
-              label="Proxy Type"
+              <span
-              value={client.proxyType?.replace('_', ' ')}
+                key={tag.id}
-            />
+                className="inline-block rounded-full px-2 py-0.5 text-xs font-medium"
-            <InfoRow label="Actual Owner" value={client.actualOwnerName} />
+                style={{ backgroundColor: `${tag.color}20`, color: tag.color }}
-          </dl>
+              >
+                {tag.name}
+              </span>
+            ))}
+          </div>
         </div>
       )}
     </div>
   );
 }
 
-export function getClientTabs({
+export function getClientTabs({ clientId, currentUserId, client }: ClientTabsOptions): DetailTab[] {
-  clientId,
-  currentUserId,
-  client,
-}: ClientTabsOptions): DetailTab[] {
   return [
     {
       id: 'overview',
       label: 'Overview',
       content: <OverviewTab client={client} />,
     },
+    {
+      id: 'yachts',
+      label: 'Yachts',
+      badge: client.yachts.length,
+      content: <ClientYachtsTab clientId={clientId} yachts={client.yachts} />,
+    },
+    {
+      id: 'companies',
+      label: 'Companies',
+      badge: client.companies.length,
+      content: <ClientCompaniesTab clientId={clientId} companies={client.companies} />,
+    },
+    {
+      id: 'reservations',
+      label: 'Reservations',
+      badge: client.activeReservations.length,
+      content: (
+        <ClientReservationsTab clientId={clientId} activeReservations={client.activeReservations} />
+      ),
+    },
     {
       id: 'interests',
       label: 'Interests',
@@ -178,13 +177,7 @@ export function getClientTabs({
     {
       id: 'notes',
       label: 'Notes',
-      content: (
+      content: <NotesList entityType="clients" entityId={clientId} currentUserId={currentUserId} />,
-        <NotesList
-          entityType="clients"
-          entityId={clientId}
-          currentUserId={currentUserId}
-        />
-      ),
     },
     {
       id: 'files',

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

@@ -0,0 +1,97 @@
+'use client';
+
+import { useState } from 'react';
+import Link from 'next/link';
+import { useParams } from 'next/navigation';
+import { Plus } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableRow,
+} from '@/components/ui/table';
+import { EmptyState } from '@/components/shared/empty-state';
+import { PermissionGate } from '@/components/shared/permission-gate';
+import { YachtForm } from '@/components/yachts/yacht-form';
+
+interface ClientYachtsTabProps {
+  clientId: string;
+  yachts: Array<{
+    id: string;
+    name: string;
+    hullNumber: string | null;
+    registration: string | null;
+    lengthFt: string | null;
+    widthFt: string | null;
+    status: string;
+  }>;
+}
+
+export function ClientYachtsTab({ clientId: _clientId, yachts }: ClientYachtsTabProps) {
+  const routeParams = useParams<{ portSlug: string }>();
+  const portSlug = routeParams?.portSlug ?? '';
+  const [createOpen, setCreateOpen] = useState(false);
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between">
+        <h3 className="text-sm font-medium">Client-owned yachts</h3>
+        <PermissionGate resource="yachts" action="create">
+          <Button size="sm" onClick={() => setCreateOpen(true)}>
+            <Plus className="mr-1.5 h-4 w-4" />
+            Add yacht
+          </Button>
+        </PermissionGate>
+      </div>
+
+      {yachts.length === 0 ? (
+        <EmptyState title="No yachts" description="No yachts owned by this client yet." />
+      ) : (
+        <div className="rounded-md border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>Name</TableHead>
+                <TableHead>Dimensions</TableHead>
+                <TableHead>Hull Number</TableHead>
+                <TableHead>Status</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {yachts.map((y) => (
+                <TableRow key={y.id}>
+                  <TableCell>
+                    <Link
+                      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                      href={`/${portSlug}/yachts/${y.id}` as any}
+                      className="text-primary hover:underline"
+                    >
+                      {y.name}
+                    </Link>
+                  </TableCell>
+                  <TableCell>
+                    {y.lengthFt && y.widthFt ? `${y.lengthFt} × ${y.widthFt} ft` : '—'}
+                  </TableCell>
+                  <TableCell>{y.hullNumber ?? '—'}</TableCell>
+                  <TableCell className="capitalize">{y.status.replace('_', ' ')}</TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </div>
+      )}
+
+      {/*
+        TODO: YachtForm (Task 5.2) does not yet accept a preset owner prop.
+        When opened here, the user must manually pick this client in the owner
+        picker. Wire an `initialOwner` prop into YachtForm in a follow-up so
+        we can pre-select `{ type: 'client', id: clientId }`.
+      */}
+      {createOpen && <YachtForm open={createOpen} onOpenChange={setCreateOpen} />}
+    </div>
+  );
+}

src/components/clients/portal-invite-button.tsx

@@ -0,0 +1,154 @@
+'use client';
+
+import { useState } from 'react';
+import { UserPlus, Loader2, Check } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { apiFetch } from '@/lib/api/client';
+
+interface PortalInviteButtonProps {
+  clientId: string;
+  clientName: string;
+  defaultEmail?: string;
+}
+
+/**
+ * Admin button on the client detail header that creates a portal user for
+ * the client and sends them an activation email. Uses the client's primary
+ * email as the default but lets the admin override.
+ */
+export function PortalInviteButton({
+  clientId,
+  clientName,
+  defaultEmail,
+}: PortalInviteButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [email, setEmail] = useState(defaultEmail ?? '');
+  const [name, setName] = useState(clientName);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [success, setSuccess] = useState(false);
+
+  function reset() {
+    setEmail(defaultEmail ?? '');
+    setName(clientName);
+    setError('');
+    setSuccess(false);
+    setLoading(false);
+  }
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    try {
+      await apiFetch(`/api/v1/clients/${clientId}/portal-user`, {
+        method: 'POST',
+        body: { email, name },
+      });
+      setSuccess(true);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to send invitation');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => {
+          reset();
+          setOpen(true);
+        }}
+      >
+        <UserPlus className="mr-1.5 h-3.5 w-3.5" />
+        Invite to portal
+      </Button>
+
+      <Dialog
+        open={open}
+        onOpenChange={(o) => {
+          if (!o) reset();
+          setOpen(o);
+        }}
+      >
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Invite to client portal</DialogTitle>
+            <DialogDescription>
+              We&apos;ll email an activation link. The client picks their own password from there.
+            </DialogDescription>
+          </DialogHeader>
+
+          {success ? (
+            <div className="py-4 flex items-center gap-3 text-sm text-green-700">
+              <Check className="h-5 w-5" />
+              Activation email sent to <strong>{email}</strong>.
+            </div>
+          ) : (
+            <form onSubmit={submit} className="space-y-4 py-2">
+              <div className="space-y-1.5">
+                <Label htmlFor="invite-email">Email address</Label>
+                <Input
+                  id="invite-email"
+                  type="email"
+                  required
+                  autoFocus
+                  value={email}
+                  onChange={(e) => setEmail(e.target.value)}
+                  disabled={loading}
+                  placeholder="client@example.com"
+                />
+              </div>
+              <div className="space-y-1.5">
+                <Label htmlFor="invite-name">Display name (optional)</Label>
+                <Input
+                  id="invite-name"
+                  value={name}
+                  onChange={(e) => setName(e.target.value)}
+                  disabled={loading}
+                />
+              </div>
+              {error && <p className="text-sm text-destructive">{error}</p>}
+            </form>
+          )}
+
+          <DialogFooter>
+            {success ? (
+              <Button onClick={() => setOpen(false)}>Done</Button>
+            ) : (
+              <>
+                <Button type="button" variant="outline" onClick={() => setOpen(false)}>
+                  Cancel
+                </Button>
+                <Button onClick={submit} disabled={loading || !email}>
+                  {loading ? (
+                    <>
+                      <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+                      Sending…
+                    </>
+                  ) : (
+                    'Send invitation'
+                  )}
+                </Button>
+              </>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

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

@@ -0,0 +1,220 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useForm } from 'react-hook-form';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Loader2 } from 'lucide-react';
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
+import { Checkbox } from '@/components/ui/checkbox';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Textarea } from '@/components/ui/textarea';
+import { ClientPicker } from '@/components/shared/client-picker';
+import { apiFetch } from '@/lib/api/client';
+import { ROLES } from '@/lib/validators/company-memberships';
+
+type RoleEnum = (typeof ROLES)[number];
+
+type FormValues = {
+  clientId: string | null;
+  role: RoleEnum;
+  roleDetail?: string;
+  startDate: string; // YYYY-MM-DD
+  isPrimary: boolean;
+  notes?: string;
+};
+
+interface AddMembershipDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  companyId: string;
+}
+
+const todayIso = (): string => new Date().toISOString().slice(0, 10);
+
+const ROLE_LABEL: Record<RoleEnum, string> = {
+  director: 'Director',
+  officer: 'Officer',
+  broker: 'Broker',
+  representative: 'Representative',
+  legal_counsel: 'Legal counsel',
+  employee: 'Employee',
+  shareholder: 'Shareholder',
+  other: 'Other',
+};
+
+export function AddMembershipDialog({ open, onOpenChange, companyId }: AddMembershipDialogProps) {
+  const queryClient = useQueryClient();
+  const [formError, setFormError] = useState<string | null>(null);
+
+  const {
+    register,
+    handleSubmit,
+    watch,
+    setValue,
+    reset,
+    formState: { errors, isSubmitting },
+  } = useForm<FormValues>({
+    defaultValues: {
+      clientId: null,
+      role: 'director',
+      roleDetail: '',
+      startDate: todayIso(),
+      isPrimary: false,
+      notes: '',
+    },
+  });
+
+  useEffect(() => {
+    if (open) {
+      setFormError(null);
+      reset({
+        clientId: null,
+        role: 'director',
+        roleDetail: '',
+        startDate: todayIso(),
+        isPrimary: false,
+        notes: '',
+      });
+    }
+  }, [open, reset]);
+
+  const clientId = watch('clientId');
+  const role = watch('role');
+  const isPrimary = watch('isPrimary');
+
+  const mutation = useMutation({
+    mutationFn: async (data: FormValues) => {
+      if (!data.clientId) {
+        throw new Error('Please select a client');
+      }
+      await apiFetch(`/api/v1/companies/${companyId}/members`, {
+        method: 'POST',
+        body: {
+          clientId: data.clientId,
+          role: data.role,
+          roleDetail: data.roleDetail?.trim() || undefined,
+          startDate: data.startDate,
+          isPrimary: data.isPrimary,
+          notes: data.notes?.trim() || undefined,
+        },
+      });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['companies', companyId, 'members'] });
+      onOpenChange(false);
+    },
+    onError: (err: unknown) => {
+      let msg = err instanceof Error ? err.message : 'Failed to add membership';
+      // Detect 409 — service returns a "membership already exists" message
+      if (/already exists/i.test(msg)) {
+        msg = 'This membership already exists (same client + role + start date).';
+      }
+      setFormError(msg);
+    },
+  });
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-md">
+        <DialogHeader>
+          <DialogTitle>Add member</DialogTitle>
+          <DialogDescription>
+            Associate a client with this company in a specific role.
+          </DialogDescription>
+        </DialogHeader>
+
+        <form
+          onSubmit={handleSubmit((data) => {
+            setFormError(null);
+            mutation.mutate(data);
+          })}
+          className="space-y-4"
+        >
+          <div className="space-y-2">
+            <Label>Client</Label>
+            <ClientPicker value={clientId} onChange={(id) => setValue('clientId', id)} />
+            {!clientId && errors.clientId && <p className="text-xs text-destructive">Required</p>}
+          </div>
+
+          <div className="space-y-2">
+            <Label>Role</Label>
+            <Select value={role} onValueChange={(v) => setValue('role', v as RoleEnum)}>
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {ROLES.map((r) => (
+                  <SelectItem key={r} value={r}>
+                    {ROLE_LABEL[r]}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="roleDetail">Role detail (optional)</Label>
+            <Input
+              id="roleDetail"
+              {...register('roleDetail')}
+              placeholder="e.g. Chief Investment Officer"
+            />
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="startDate">Start date</Label>
+            <Input id="startDate" type="date" {...register('startDate', { required: true })} />
+            {errors.startDate && <p className="text-xs text-destructive">Required</p>}
+          </div>
+
+          <div className="flex items-center gap-2">
+            <Checkbox
+              id="isPrimary"
+              checked={isPrimary}
+              onCheckedChange={(v) => setValue('isPrimary', v === true)}
+            />
+            <Label htmlFor="isPrimary" className="cursor-pointer">
+              Set as primary contact
+            </Label>
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="notes">Notes (optional)</Label>
+            <Textarea id="notes" rows={2} {...register('notes')} />
+          </div>
+
+          {formError && <p className="text-sm text-destructive">{formError}</p>}
+
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+              Cancel
+            </Button>
+            <Button type="submit" disabled={isSubmitting || mutation.isPending}>
+              {(isSubmitting || mutation.isPending) && (
+                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+              )}
+              Add member
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

src/components/companies/company-columns.tsx

@@ -0,0 +1,148 @@
+'use client';
+
+import Link from 'next/link';
+import { MoreHorizontal, Pencil, Archive, Eye } from 'lucide-react';
+import type { ColumnDef } from '@tanstack/react-table';
+
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+
+// TODO: add member/yacht counts once the list endpoint returns them via a join.
+export interface CompanyRow {
+  id: string;
+  name: string;
+  legalName: string | null;
+  taxId: string | null;
+  registrationNumber: string | null;
+  incorporationCountry: string | null;
+  incorporationDate: string | null;
+  status: string;
+  billingEmail: string | null;
+  notes: string | null;
+  archivedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  active: 'bg-green-100 text-green-800 border-green-300',
+  dissolved: 'bg-red-100 text-red-800 border-red-300',
+};
+
+const STATUS_LABELS: Record<string, string> = {
+  active: 'Active',
+  dissolved: 'Dissolved',
+};
+
+interface GetCompanyColumnsOptions {
+  portSlug: string;
+  onEdit: (company: CompanyRow) => void;
+  onArchive: (company: CompanyRow) => void;
+}
+
+export function getCompanyColumns({
+  portSlug,
+  onEdit,
+  onArchive,
+}: GetCompanyColumnsOptions): ColumnDef<CompanyRow, unknown>[] {
+  return [
+    {
+      id: 'name',
+      accessorKey: 'name',
+      header: 'Name',
+      cell: ({ row }) => (
+        <Link
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          href={`/${portSlug}/companies/${row.original.id}` as any}
+          className="font-medium text-primary hover:underline"
+          onClick={(e) => e.stopPropagation()}
+        >
+          {row.original.name}
+        </Link>
+      ),
+    },
+    {
+      id: 'legalName',
+      accessorKey: 'legalName',
+      header: 'Legal Name',
+      enableSorting: false,
+      cell: ({ getValue }) => {
+        const value = getValue() as string | null;
+        if (!value) return <span className="text-muted-foreground">—</span>;
+        return <span className="text-sm">{value}</span>;
+      },
+    },
+    {
+      id: 'taxId',
+      accessorKey: 'taxId',
+      header: 'Tax ID',
+      enableSorting: false,
+      cell: ({ getValue }) => {
+        const value = getValue() as string | null;
+        if (!value) return <span className="text-muted-foreground">—</span>;
+        return <span className="text-sm">{value}</span>;
+      },
+    },
+    {
+      id: 'status',
+      accessorKey: 'status',
+      header: 'Status',
+      cell: ({ row }) => {
+        const status = row.original.status;
+        const label = STATUS_LABELS[status] ?? status;
+        const color = STATUS_COLORS[status] ?? 'bg-muted text-muted-foreground border-muted';
+        return (
+          <span
+            className={`inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-medium ${color}`}
+          >
+            {label}
+          </span>
+        );
+      },
+    },
+    {
+      id: 'actions',
+      header: '',
+      enableSorting: false,
+      size: 48,
+      cell: ({ row }) => (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-7 w-7"
+              onClick={(e) => e.stopPropagation()}
+            >
+              <MoreHorizontal className="h-4 w-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem asChild>
+              <Link
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                href={`/${portSlug}/companies/${row.original.id}` as any}
+              >
+                <Eye className="mr-2 h-3.5 w-3.5" />
+                View
+              </Link>
+            </DropdownMenuItem>
+            <DropdownMenuItem onClick={() => onEdit(row.original)}>
+              <Pencil className="mr-2 h-3.5 w-3.5" />
+              Edit
+            </DropdownMenuItem>
+            <DropdownMenuItem className="text-destructive" onClick={() => onArchive(row.original)}>
+              <Archive className="mr-2 h-3.5 w-3.5" />
+              Archive
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ),
+    },
+  ];
+}

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

@@ -0,0 +1,153 @@
+'use client';
+
+import { useState } from 'react';
+import { useParams, useRouter } from 'next/navigation';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Pencil, Archive } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { Badge } from '@/components/ui/badge';
+import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
+import { PermissionGate } from '@/components/shared/permission-gate';
+import { CompanyForm } from '@/components/companies/company-form';
+import { apiFetch } from '@/lib/api/client';
+
+interface CompanyDetailHeaderCompany {
+  id: string;
+  name: string;
+  legalName: string | null;
+  taxId: string | null;
+  registrationNumber: string | null;
+  incorporationCountry: string | null;
+  incorporationDate: string | null;
+  status: string;
+  billingEmail: string | null;
+  notes: string | null;
+  archivedAt: string | null;
+}
+
+interface CompanyDetailHeaderProps {
+  company: CompanyDetailHeaderCompany;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  active: 'bg-green-100 text-green-800 border-green-300',
+  dissolved: 'bg-red-100 text-red-800 border-red-300',
+};
+
+const STATUS_LABELS: Record<string, string> = {
+  active: 'Active',
+  dissolved: 'Dissolved',
+};
+
+export function CompanyDetailHeader({ company }: CompanyDetailHeaderProps) {
+  const queryClient = useQueryClient();
+  const router = useRouter();
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+
+  const [editOpen, setEditOpen] = useState(false);
+  const [archiveOpen, setArchiveOpen] = useState(false);
+
+  const isArchived = !!company.archivedAt;
+  const showLegalName = company.legalName && company.legalName !== company.name;
+
+  const archiveMutation = useMutation({
+    mutationFn: () => apiFetch(`/api/v1/companies/${company.id}`, { method: 'DELETE' }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['companies', company.id] });
+      queryClient.invalidateQueries({ queryKey: ['companies'] });
+      toast.success('Company archived');
+      setArchiveOpen(false);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      router.push(`/${portSlug}/companies` as any);
+    },
+    onError: (err: Error) => {
+      toast.error(err.message || 'Failed to archive company');
+    },
+  });
+
+  const statusLabel = STATUS_LABELS[company.status] ?? company.status;
+  const statusColor =
+    STATUS_COLORS[company.status] ?? 'bg-muted text-muted-foreground border-muted';
+
+  return (
+    <>
+      <div className="space-y-3">
+        <div className="flex items-start gap-3 flex-wrap">
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center gap-2 flex-wrap">
+              <h1 className="text-2xl font-bold text-foreground truncate">{company.name}</h1>
+              <span
+                className={`inline-flex items-center rounded-full border px-3 py-1 text-xs font-medium ${statusColor}`}
+              >
+                {statusLabel}
+              </span>
+              {isArchived && (
+                <Badge variant="secondary" className="text-xs">
+                  Archived
+                </Badge>
+              )}
+            </div>
+
+            <div className="mt-1 space-y-0.5 text-sm text-muted-foreground">
+              {showLegalName && <p>{company.legalName}</p>}
+              {company.taxId && <p>Tax ID: {company.taxId}</p>}
+            </div>
+          </div>
+
+          {/* Actions */}
+          <div className="flex items-center gap-2">
+            <PermissionGate resource="companies" action="edit">
+              <Button variant="outline" size="sm" onClick={() => setEditOpen(true)}>
+                <Pencil className="mr-1.5 h-3.5 w-3.5" />
+                Edit
+              </Button>
+            </PermissionGate>
+            <PermissionGate resource="companies" action="delete">
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => setArchiveOpen(true)}
+                disabled={isArchived}
+              >
+                <Archive className="mr-1.5 h-3.5 w-3.5" />
+                Archive
+              </Button>
+            </PermissionGate>
+          </div>
+        </div>
+      </div>
+
+      <CompanyForm
+        open={editOpen}
+        onOpenChange={setEditOpen}
+        company={{
+          id: company.id,
+          name: company.name,
+          legalName: company.legalName,
+          taxId: company.taxId,
+          registrationNumber: company.registrationNumber,
+          incorporationCountry: company.incorporationCountry,
+          incorporationDate: company.incorporationDate,
+          status: company.status,
+          billingEmail: company.billingEmail,
+          notes: company.notes,
+        }}
+      />
+
+      <ArchiveConfirmDialog
+        open={archiveOpen}
+        onOpenChange={setArchiveOpen}
+        entityName={company.name}
+        entityType="Company"
+        isArchived={isArchived}
+        onConfirm={() => {
+          archiveMutation.mutate();
+        }}
+        isLoading={archiveMutation.isPending}
+      />
+    </>
+  );
+}

src/components/companies/company-detail.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import { useParams } from 'next/navigation';
+
+import { DetailLayout } from '@/components/shared/detail-layout';
+import { CompanyDetailHeader } from '@/components/companies/company-detail-header';
+import { getCompanyTabs } from '@/components/companies/company-tabs';
+import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { apiFetch } from '@/lib/api/client';
+
+export interface CompanyData {
+  id: string;
+  portId: string;
+  name: string;
+  legalName: string | null;
+  taxId: string | null;
+  registrationNumber: string | null;
+  incorporationCountry: string | null;
+  incorporationDate: string | null;
+  status: string;
+  billingEmail: string | null;
+  notes: string | null;
+  archivedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface CompanyDetailProps {
+  companyId: string;
+  currentUserId?: string;
+}
+
+export function CompanyDetail({ companyId, currentUserId }: CompanyDetailProps) {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+
+  const { data, isLoading } = useQuery<CompanyData>({
+    queryKey: ['companies', companyId],
+    queryFn: () =>
+      apiFetch<{ data: CompanyData }>(`/api/v1/companies/${companyId}`).then((r) => r.data),
+  });
+
+  useRealtimeInvalidation({
+    'company:updated': [['companies', companyId]],
+    'company:archived': [['companies', companyId]],
+    'company_membership:added': [['companies', companyId, 'members']],
+    'company_membership:updated': [['companies', companyId, 'members']],
+    'company_membership:ended': [['companies', companyId, 'members']],
+  });
+
+  const tabs = data ? getCompanyTabs({ companyId, portSlug, currentUserId, company: data }) : [];
+
+  return (
+    <DetailLayout
+      header={data ? <CompanyDetailHeader company={data} /> : null}
+      tabs={tabs}
+      defaultTab="overview"
+      isLoading={isLoading}
+    />
+  );
+}

src/components/companies/company-filters.tsx

@@ -0,0 +1,24 @@
+import type { FilterDefinition } from '@/components/shared/filter-bar';
+
+export const companyFilterDefinitions: FilterDefinition[] = [
+  {
+    key: 'search',
+    label: 'Search',
+    type: 'text',
+    placeholder: 'Search by name, legal name, tax ID...',
+  },
+  {
+    key: 'status',
+    label: 'Status',
+    type: 'select',
+    options: [
+      { label: 'Active', value: 'active' },
+      { label: 'Dissolved', value: 'dissolved' },
+    ],
+  },
+  {
+    key: 'includeArchived',
+    label: 'Include Archived',
+    type: 'boolean',
+  },
+];

src/components/companies/company-form.tsx

@@ -0,0 +1,262 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Loader2 } from 'lucide-react';
+import { z } from 'zod';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Textarea } from '@/components/ui/textarea';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
+import { Separator } from '@/components/ui/separator';
+import { TagPicker } from '@/components/shared/tag-picker';
+import { apiFetch } from '@/lib/api/client';
+import { createCompanySchema, type CreateCompanyInput } from '@/lib/validators/companies';
+
+type CompanyStatus = 'active' | 'dissolved';
+
+type CompanyFormValues = z.input<typeof createCompanySchema>;
+
+interface CompanyFormProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** If provided, form is in edit mode */
+  company?: {
+    id: string;
+    name: string;
+    legalName: string | null;
+    taxId: string | null;
+    registrationNumber: string | null;
+    incorporationCountry: string | null;
+    incorporationDate: string | null;
+    status: string;
+    billingEmail: string | null;
+    notes: string | null;
+  };
+}
+
+export function CompanyForm({ open, onOpenChange, company }: CompanyFormProps) {
+  const queryClient = useQueryClient();
+  const isEdit = !!company;
+  const [formError, setFormError] = useState<string | null>(null);
+
+  const {
+    register,
+    handleSubmit,
+    watch,
+    setValue,
+    reset,
+    formState: { errors, isSubmitting },
+  } = useForm<CompanyFormValues>({
+    resolver: zodResolver(createCompanySchema),
+    defaultValues: {
+      name: '',
+      status: 'active',
+      tagIds: [],
+    },
+  });
+
+  const tagIds = watch('tagIds') ?? [];
+  const status = watch('status') ?? 'active';
+
+  // Populate form when editing, or reset to defaults in create mode.
+  useEffect(() => {
+    if (company && open) {
+      reset({
+        name: company.name,
+        legalName: company.legalName ?? undefined,
+        taxId: company.taxId ?? undefined,
+        registrationNumber: company.registrationNumber ?? undefined,
+        incorporationCountry: company.incorporationCountry ?? undefined,
+        incorporationDate: company.incorporationDate
+          ? new Date(company.incorporationDate)
+          : undefined,
+        status: (company.status as CompanyStatus) ?? 'active',
+        billingEmail: company.billingEmail ?? undefined,
+        notes: company.notes ?? undefined,
+        tagIds: [],
+      });
+    } else if (!company && open) {
+      reset({ name: '', status: 'active', tagIds: [] });
+    }
+    setFormError(null);
+  }, [company, open, reset]);
+
+  const mutation = useMutation({
+    mutationFn: async (data: CreateCompanyInput) => {
+      if (isEdit) {
+        // updateCompanySchema omits tagIds — strip them from PATCH body.
+        const { tagIds: _tIds, ...rest } = data;
+        void _tIds;
+        await apiFetch(`/api/v1/companies/${company!.id}`, {
+          method: 'PATCH',
+          body: rest,
+        });
+      } else {
+        await apiFetch('/api/v1/companies', { method: 'POST', body: data });
+      }
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['companies'] });
+      onOpenChange(false);
+    },
+    onError: (err: unknown) => {
+      const msg = err instanceof Error ? err.message : 'Failed to save company';
+      setFormError(msg);
+    },
+  });
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent className="w-full sm:max-w-2xl overflow-y-auto">
+        <SheetHeader>
+          <SheetTitle>{isEdit ? 'Edit Company' : 'New Company'}</SheetTitle>
+        </SheetHeader>
+
+        <form
+          onSubmit={handleSubmit((data) => {
+            setFormError(null);
+            mutation.mutate(data as CreateCompanyInput);
+          })}
+          className="space-y-6 py-6"
+        >
+          {/* Basics */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
+              Basics
+            </h3>
+
+            <div className="grid grid-cols-2 gap-4">
+              <div className="col-span-2 space-y-1">
+                <Label>Name *</Label>
+                <Input {...register('name')} placeholder="Acme Holdings Ltd" />
+                {errors.name && <p className="text-xs text-destructive">{errors.name.message}</p>}
+              </div>
+
+              <div className="col-span-2 space-y-1">
+                <Label>Legal Name</Label>
+                <Input {...register('legalName')} placeholder="Acme Holdings Limited" />
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Registration */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
+              Registration
+            </h3>
+            <div className="grid grid-cols-2 gap-4">
+              <div className="space-y-1">
+                <Label>Tax ID</Label>
+                <Input {...register('taxId')} placeholder="VAT / EIN" />
+              </div>
+              <div className="space-y-1">
+                <Label>Registration Number</Label>
+                <Input {...register('registrationNumber')} placeholder="Company #" />
+              </div>
+              <div className="space-y-1">
+                <Label>Incorporation Country</Label>
+                <Input {...register('incorporationCountry')} placeholder="e.g. MT" />
+              </div>
+              <div className="space-y-1">
+                <Label>Incorporation Date</Label>
+                <Input type="date" {...register('incorporationDate')} />
+                {errors.incorporationDate && (
+                  <p className="text-xs text-destructive">{errors.incorporationDate.message}</p>
+                )}
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Contact & Status */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
+              Contact & Status
+            </h3>
+            <div className="grid grid-cols-2 gap-4">
+              <div className="space-y-1">
+                <Label>Billing Email</Label>
+                <Input
+                  type="email"
+                  {...register('billingEmail')}
+                  placeholder="billing@example.com"
+                />
+                {errors.billingEmail && (
+                  <p className="text-xs text-destructive">{errors.billingEmail.message}</p>
+                )}
+              </div>
+              <div className="space-y-1">
+                <Label>Status</Label>
+                <Select
+                  value={status}
+                  onValueChange={(v) => setValue('status', v as CompanyStatus)}
+                >
+                  <SelectTrigger>
+                    <SelectValue placeholder="Select status" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="active">Active</SelectItem>
+                    <SelectItem value="dissolved">Dissolved</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Notes */}
+          <div className="space-y-2">
+            <Label>Notes</Label>
+            <Textarea
+              {...register('notes')}
+              placeholder="Internal notes about this company"
+              rows={4}
+            />
+          </div>
+
+          <Separator />
+
+          {/* Tags */}
+          <div className="space-y-2">
+            <Label>Tags</Label>
+            <TagPicker selectedIds={tagIds} onChange={(ids) => setValue('tagIds', ids)} />
+          </div>
+
+          {formError && (
+            <p className="text-sm text-destructive" role="alert">
+              {formError}
+            </p>
+          )}
+
+          <SheetFooter>
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+              Cancel
+            </Button>
+            <Button type="submit" disabled={isSubmitting || mutation.isPending}>
+              {(isSubmitting || mutation.isPending) && (
+                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+              )}
+              {isEdit ? 'Save Changes' : 'Create Company'}
+            </Button>
+          </SheetFooter>
+        </form>
+      </SheetContent>
+    </Sheet>
+  );
+}

src/components/companies/company-list.tsx

@@ -0,0 +1,167 @@
+'use client';
+
+import { useState } from 'react';
+import { useParams } from 'next/navigation';
+import { Plus } from 'lucide-react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+import { Button } from '@/components/ui/button';
+import { DataTable } from '@/components/shared/data-table';
+import { FilterBar } from '@/components/shared/filter-bar';
+import { SavedViewsDropdown } from '@/components/shared/saved-views-dropdown';
+import { PageHeader } from '@/components/shared/page-header';
+import { EmptyState } from '@/components/shared/empty-state';
+import { TableSkeleton } from '@/components/shared/loading-skeleton';
+import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
+import { PermissionGate } from '@/components/shared/permission-gate';
+import { CompanyForm } from '@/components/companies/company-form';
+import { companyFilterDefinitions } from '@/components/companies/company-filters';
+import { getCompanyColumns, type CompanyRow } from '@/components/companies/company-columns';
+import { usePaginatedQuery } from '@/hooks/use-paginated-query';
+import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { apiFetch } from '@/lib/api/client';
+
+export function CompanyList() {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+  const queryClient = useQueryClient();
+
+  const [createOpen, setCreateOpen] = useState(false);
+  const [editCompany, setEditCompany] = useState<CompanyRow | null>(null);
+  const [archiveCompany, setArchiveCompany] = useState<CompanyRow | null>(null);
+
+  const {
+    data,
+    pagination,
+    isLoading,
+    isFetching,
+    sort,
+    setSort,
+    setPage,
+    setPageSize,
+    filters,
+    setFilter,
+    clearFilters,
+  } = usePaginatedQuery<CompanyRow>({
+    queryKey: ['companies'],
+    endpoint: '/api/v1/companies',
+    filterDefinitions: companyFilterDefinitions,
+  });
+
+  useRealtimeInvalidation({
+    'company:created': [['companies']],
+    'company:updated': [['companies']],
+    'company:archived': [['companies']],
+  });
+
+  const archiveMutation = useMutation({
+    mutationFn: (id: string) => apiFetch(`/api/v1/companies/${id}`, { method: 'DELETE' }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['companies'] });
+      setArchiveCompany(null);
+    },
+  });
+
+  const columns = getCompanyColumns({
+    portSlug,
+    onEdit: (company) => setEditCompany(company),
+    onArchive: (company) => setArchiveCompany(company),
+  });
+
+  return (
+    <div className="space-y-4">
+      <PageHeader
+        title="Companies"
+        description="Manage company records"
+        actions={
+          <PermissionGate resource="companies" action="create">
+            <Button size="sm" onClick={() => setCreateOpen(true)}>
+              <Plus className="mr-1.5 h-4 w-4" />
+              New Company
+            </Button>
+          </PermissionGate>
+        }
+      />
+
+      <div className="flex items-center gap-2">
+        <FilterBar
+          filters={companyFilterDefinitions}
+          values={filters}
+          onChange={setFilter}
+          onClear={clearFilters}
+        />
+        <SavedViewsDropdown
+          entityType="companies"
+          currentFilters={filters}
+          currentSort={sort}
+          onApplyView={(savedFilters, _savedSort) => {
+            clearFilters();
+            Object.entries(savedFilters).forEach(([key, val]) => setFilter(key, val));
+          }}
+        />
+      </div>
+
+      {isLoading ? (
+        <TableSkeleton />
+      ) : !data.length ? (
+        <EmptyState
+          title="No companies yet"
+          description="Create your first company to get started."
+          action={{ label: 'New Company', onClick: () => setCreateOpen(true) }}
+        />
+      ) : (
+        <DataTable
+          columns={columns}
+          data={data}
+          pagination={pagination}
+          onPaginationChange={(p, ps) => {
+            setPage(p);
+            setPageSize(ps);
+          }}
+          sort={sort}
+          onSortChange={setSort}
+          isLoading={isFetching && !isLoading}
+          getRowId={(row) => row.id}
+          emptyState={
+            <EmptyState
+              title="No companies yet"
+              description="Create your first company to get started."
+              action={{ label: 'New Company', onClick: () => setCreateOpen(true) }}
+            />
+          }
+        />
+      )}
+
+      <CompanyForm open={createOpen} onOpenChange={setCreateOpen} />
+
+      {editCompany && (
+        <CompanyForm
+          open={!!editCompany}
+          onOpenChange={(open) => !open && setEditCompany(null)}
+          company={{
+            id: editCompany.id,
+            name: editCompany.name,
+            legalName: editCompany.legalName,
+            taxId: editCompany.taxId,
+            registrationNumber: editCompany.registrationNumber,
+            incorporationCountry: editCompany.incorporationCountry,
+            incorporationDate: editCompany.incorporationDate,
+            status: editCompany.status,
+            billingEmail: editCompany.billingEmail,
+            notes: editCompany.notes,
+          }}
+        />
+      )}
+
+      <ArchiveConfirmDialog
+        open={!!archiveCompany}
+        onOpenChange={(open) => !open && setArchiveCompany(null)}
+        entityName={archiveCompany?.name ?? ''}
+        entityType="Company"
+        isArchived={false}
+        onConfirm={() => archiveCompany && archiveMutation.mutate(archiveCompany.id)}
+        isLoading={archiveMutation.isPending}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,266 @@
+'use client';
+
+import { useState } from 'react';
+import Link from 'next/link';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Loader2, MoreHorizontal, Plus, Star, XCircle } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { Badge } from '@/components/ui/badge';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { EmptyState } from '@/components/shared/empty-state';
+import { PermissionGate } from '@/components/shared/permission-gate';
+import { apiFetch } from '@/lib/api/client';
+import { AddMembershipDialog } from './add-membership-dialog';
+
+interface MembershipRow {
+  id: string;
+  companyId: string;
+  clientId: string;
+  role: string;
+  roleDetail: string | null;
+  startDate: string;
+  endDate: string | null;
+  isPrimary: boolean;
+  notes: string | null;
+}
+
+interface CompanyMembersTabProps {
+  companyId: string;
+  portSlug: string;
+}
+
+const ROLE_LABELS: Record<string, string> = {
+  director: 'Director',
+  officer: 'Officer',
+  broker: 'Broker',
+  representative: 'Representative',
+  legal_counsel: 'Legal counsel',
+  employee: 'Employee',
+  shareholder: 'Shareholder',
+  other: 'Other',
+};
+
+function formatDate(value: string | null): string {
+  if (!value) return '—';
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleDateString();
+}
+
+/**
+ * Renders a client's name as a link by fetching the client record.
+ * Memoization is handled via the TanStack Query cache, so repeat renders
+ * for the same clientId are free.
+ */
+function ClientName({ clientId, portSlug }: { clientId: string; portSlug: string }) {
+  const { data } = useQuery<{ fullName: string | null }>({
+    queryKey: ['clients', clientId, 'name-only'],
+    queryFn: () =>
+      apiFetch<{ data: { fullName: string | null } }>(`/api/v1/clients/${clientId}`).then(
+        (r) => r.data,
+      ),
+  });
+
+  return (
+    <Link
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      href={`/${portSlug}/clients/${clientId}` as any}
+      className="text-primary hover:underline"
+    >
+      {data?.fullName ?? `Client ${clientId.slice(0, 8)}`}
+    </Link>
+  );
+}
+
+export function CompanyMembersTab({ companyId, portSlug }: CompanyMembersTabProps) {
+  const queryClient = useQueryClient();
+  const [activeOnly, setActiveOnly] = useState(true);
+  const [addOpen, setAddOpen] = useState(false);
+
+  const membersKey = ['companies', companyId, 'members', { activeOnly }];
+
+  const { data, isLoading } = useQuery<MembershipRow[]>({
+    queryKey: membersKey,
+    queryFn: () =>
+      apiFetch<{ data: MembershipRow[] }>(
+        `/api/v1/companies/${companyId}/members?activeOnly=${activeOnly ? 'true' : 'false'}`,
+      ).then((r) => r.data),
+  });
+
+  const endMutation = useMutation({
+    mutationFn: (membershipId: string) =>
+      apiFetch(`/api/v1/companies/${companyId}/members/${membershipId}`, {
+        method: 'DELETE',
+      }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['companies', companyId, 'members'] });
+      toast.success('Membership ended');
+    },
+    onError: (err: Error) => {
+      toast.error(err.message || 'Failed to end membership');
+    },
+  });
+
+  const setPrimaryMutation = useMutation({
+    mutationFn: (membershipId: string) =>
+      apiFetch(`/api/v1/companies/${companyId}/members/${membershipId}/set-primary`, {
+        method: 'POST',
+      }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['companies', companyId, 'members'] });
+      toast.success('Primary contact updated');
+    },
+    onError: (err: Error) => {
+      toast.error(err.message || 'Failed to set primary');
+    },
+  });
+
+  const members = data ?? [];
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between gap-3 flex-wrap">
+        <div className="inline-flex rounded-md border p-0.5 text-xs">
+          <button
+            type="button"
+            onClick={() => setActiveOnly(true)}
+            className={`px-3 py-1 rounded-sm transition-colors ${
+              activeOnly ? 'bg-primary text-primary-foreground' : 'text-muted-foreground'
+            }`}
+          >
+            Active
+          </button>
+          <button
+            type="button"
+            onClick={() => setActiveOnly(false)}
+            className={`px-3 py-1 rounded-sm transition-colors ${
+              !activeOnly ? 'bg-primary text-primary-foreground' : 'text-muted-foreground'
+            }`}
+          >
+            All
+          </button>
+        </div>
+
+        <PermissionGate resource="memberships" action="manage">
+          <Button size="sm" onClick={() => setAddOpen(true)}>
+            <Plus className="mr-1.5 h-4 w-4" />
+            Add Member
+          </Button>
+        </PermissionGate>
+      </div>
+
+      {isLoading ? (
+        <div className="flex items-center justify-center py-12">
+          <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+        </div>
+      ) : members.length === 0 ? (
+        <EmptyState
+          title={activeOnly ? 'No active members' : 'No members yet'}
+          description={
+            activeOnly
+              ? 'This company has no active memberships. Switch to "All" to see past members.'
+              : 'Add the first member to this company to get started.'
+          }
+        />
+      ) : (
+        <div className="rounded-md border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>Client</TableHead>
+                <TableHead>Role</TableHead>
+                <TableHead>Role Detail</TableHead>
+                <TableHead>Start Date</TableHead>
+                <TableHead>End Date</TableHead>
+                <TableHead>Primary</TableHead>
+                <TableHead className="w-[48px]"></TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {members.map((m) => {
+                const isActive = !m.endDate;
+                return (
+                  <TableRow key={m.id}>
+                    <TableCell>
+                      <ClientName clientId={m.clientId} portSlug={portSlug} />
+                    </TableCell>
+                    <TableCell>{ROLE_LABELS[m.role] ?? m.role}</TableCell>
+                    <TableCell className="text-sm text-muted-foreground max-w-[240px] truncate">
+                      {m.roleDetail ?? '—'}
+                    </TableCell>
+                    <TableCell>{formatDate(m.startDate)}</TableCell>
+                    <TableCell>
+                      {m.endDate ? (
+                        formatDate(m.endDate)
+                      ) : (
+                        <span className="text-muted-foreground">—</span>
+                      )}
+                    </TableCell>
+                    <TableCell>
+                      {m.isPrimary ? (
+                        <Badge variant="secondary" className="text-xs">
+                          Primary
+                        </Badge>
+                      ) : (
+                        <span className="text-muted-foreground">—</span>
+                      )}
+                    </TableCell>
+                    <TableCell>
+                      <PermissionGate resource="memberships" action="manage">
+                        <DropdownMenu>
+                          <DropdownMenuTrigger asChild>
+                            <Button variant="ghost" size="icon" className="h-7 w-7">
+                              <MoreHorizontal className="h-4 w-4" />
+                            </Button>
+                          </DropdownMenuTrigger>
+                          <DropdownMenuContent align="end">
+                            {isActive && !m.isPrimary && (
+                              <DropdownMenuItem
+                                onClick={() => setPrimaryMutation.mutate(m.id)}
+                                disabled={setPrimaryMutation.isPending}
+                              >
+                                <Star className="mr-2 h-3.5 w-3.5" />
+                                Set Primary
+                              </DropdownMenuItem>
+                            )}
+                            {isActive && (
+                              <DropdownMenuItem
+                                className="text-destructive"
+                                onClick={() => endMutation.mutate(m.id)}
+                                disabled={endMutation.isPending}
+                              >
+                                <XCircle className="mr-2 h-3.5 w-3.5" />
+                                End Membership
+                              </DropdownMenuItem>
+                            )}
+                          </DropdownMenuContent>
+                        </DropdownMenu>
+                      </PermissionGate>
+                    </TableCell>
+                  </TableRow>
+                );
+              })}
+            </TableBody>
+          </Table>
+        </div>
+      )}
+
+      <AddMembershipDialog open={addOpen} onOpenChange={setAddOpen} companyId={companyId} />
+    </div>
+  );
+}

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

@@ -0,0 +1,156 @@
+'use client';
+
+import Link from 'next/link';
+import { useQuery } from '@tanstack/react-query';
+import { Loader2 } from 'lucide-react';
+
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { EmptyState } from '@/components/shared/empty-state';
+import { apiFetch } from '@/lib/api/client';
+
+interface OwnedYachtRow {
+  id: string;
+  name: string;
+  hullNumber: string | null;
+  lengthFt: string | null;
+  widthFt: string | null;
+  lengthM: string | null;
+  widthM: string | null;
+  status: string;
+}
+
+interface YachtListResponse {
+  data: OwnedYachtRow[];
+}
+
+interface CompanyOwnedYachtsTabProps {
+  companyId: string;
+  portSlug: string;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  active: 'bg-green-100 text-green-800 border-green-300',
+  retired: 'bg-gray-100 text-gray-800 border-gray-300',
+  sold_away: 'bg-amber-100 text-amber-800 border-amber-300',
+};
+
+const STATUS_LABELS: Record<string, string> = {
+  active: 'Active',
+  retired: 'Retired',
+  sold_away: 'Sold Away',
+};
+
+function formatDimensions(y: OwnedYachtRow): string | null {
+  if (y.lengthFt || y.widthFt) {
+    const length = y.lengthFt ?? '—';
+    const width = y.widthFt ?? '—';
+    return `${length} × ${width} ft`;
+  }
+  if (y.lengthM || y.widthM) {
+    const length = y.lengthM ?? '—';
+    const width = y.widthM ?? '—';
+    return `${length} × ${width} m`;
+  }
+  return null;
+}
+
+export function CompanyOwnedYachtsTab({ companyId, portSlug }: CompanyOwnedYachtsTabProps) {
+  const { data, isLoading } = useQuery<OwnedYachtRow[]>({
+    queryKey: ['companies', companyId, 'owned-yachts'],
+    queryFn: async () => {
+      const params = new URLSearchParams({
+        ownerType: 'company',
+        ownerId: companyId,
+        page: '1',
+        limit: '50',
+        includeArchived: 'false',
+        order: 'desc',
+      });
+      const res = await apiFetch<YachtListResponse>(`/api/v1/yachts?${params.toString()}`);
+      return res.data;
+    },
+  });
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+      </div>
+    );
+  }
+
+  const yachts = data ?? [];
+
+  if (yachts.length === 0) {
+    return (
+      <EmptyState
+        title="No yachts owned"
+        description="Yachts owned by this company will appear here."
+      />
+    );
+  }
+
+  return (
+    <div className="rounded-md border">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Name</TableHead>
+            <TableHead>Dimensions</TableHead>
+            <TableHead>Hull Number</TableHead>
+            <TableHead>Status</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {yachts.map((y) => {
+            const dims = formatDimensions(y);
+            const statusLabel = STATUS_LABELS[y.status] ?? y.status;
+            const statusColor =
+              STATUS_COLORS[y.status] ?? 'bg-muted text-muted-foreground border-muted';
+            return (
+              <TableRow key={y.id}>
+                <TableCell>
+                  <Link
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    href={`/${portSlug}/yachts/${y.id}` as any}
+                    className="font-medium text-primary hover:underline"
+                  >
+                    {y.name}
+                  </Link>
+                </TableCell>
+                <TableCell>
+                  {dims ? (
+                    <span className="text-sm">{dims}</span>
+                  ) : (
+                    <span className="text-muted-foreground">—</span>
+                  )}
+                </TableCell>
+                <TableCell>
+                  {y.hullNumber ? (
+                    <span className="text-sm">{y.hullNumber}</span>
+                  ) : (
+                    <span className="text-muted-foreground">—</span>
+                  )}
+                </TableCell>
+                <TableCell>
+                  <span
+                    className={`inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-medium ${statusColor}`}
+                  >
+                    {statusLabel}
+                  </span>
+                </TableCell>
+              </TableRow>
+            );
+          })}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

src/components/companies/company-picker.tsx

@@ -0,0 +1,103 @@
+'use client';
+
+import { useState } from 'react';
+import { Check, ChevronsUpDown } from 'lucide-react';
+import { useQuery } from '@tanstack/react-query';
+
+import { Button } from '@/components/ui/button';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { useDebounce } from '@/hooks/use-debounce';
+import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';
+
+interface CompanyOption {
+  id: string;
+  name: string;
+  legalName?: string | null;
+}
+
+interface CompanyPickerProps {
+  value: string | null;
+  onChange: (companyId: string | null) => void;
+  placeholder?: string;
+  disabled?: boolean;
+}
+
+export function CompanyPicker({
+  value,
+  onChange,
+  placeholder = 'Select company...',
+  disabled,
+}: CompanyPickerProps) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState('');
+  const debounced = useDebounce(search, 300);
+
+  const { data } = useQuery<{ data: CompanyOption[] }>({
+    queryKey: ['company-picker', debounced],
+    queryFn: () => apiFetch(`/api/v1/companies/autocomplete?q=${encodeURIComponent(debounced)}`),
+    enabled: open,
+  });
+
+  const options = data?.data ?? [];
+
+  const selectedLabel = (() => {
+    if (!value) return placeholder;
+    const match = options.find((o) => o.id === value);
+    return match?.name ?? `Company ${value.slice(0, 8)}`;
+  })();
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          role="combobox"
+          disabled={disabled}
+          className={cn('w-full justify-between', !value && 'text-muted-foreground')}
+        >
+          <span className="truncate">{selectedLabel}</span>
+          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-[320px] p-0" align="start">
+        <Command shouldFilter={false}>
+          <CommandInput placeholder="Search companies…" value={search} onValueChange={setSearch} />
+          <CommandList>
+            <CommandEmpty>No companies found.</CommandEmpty>
+            <CommandGroup>
+              {options.map((c) => (
+                <CommandItem
+                  key={c.id}
+                  value={c.id}
+                  onSelect={() => {
+                    onChange(c.id);
+                    setOpen(false);
+                  }}
+                >
+                  <Check
+                    className={cn('mr-2 h-4 w-4', value === c.id ? 'opacity-100' : 'opacity-0')}
+                  />
+                  <span>
+                    {c.name}
+                    {c.legalName ? (
+                      <span className="ml-2 text-xs opacity-60">{c.legalName}</span>
+                    ) : null}
+                  </span>
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}

src/components/companies/company-tabs.tsx

@@ -0,0 +1,167 @@
+'use client';
+
+import type { DetailTab } from '@/components/shared/detail-layout';
+import { EmptyState } from '@/components/shared/empty-state';
+import { CompanyMembersTab } from '@/components/companies/company-members-tab';
+import { CompanyOwnedYachtsTab } from '@/components/companies/company-owned-yachts-tab';
+
+interface CompanyTabsCompany {
+  id: string;
+  name: string;
+  legalName: string | null;
+  taxId: string | null;
+  registrationNumber: string | null;
+  incorporationCountry: string | null;
+  incorporationDate: string | null;
+  status: string;
+  billingEmail: string | null;
+  notes: string | null;
+}
+
+interface CompanyTabsOptions {
+  companyId: string;
+  portSlug: string;
+  currentUserId?: string;
+  company: CompanyTabsCompany;
+}
+
+const STATUS_LABELS: Record<string, string> = {
+  active: 'Active',
+  dissolved: 'Dissolved',
+};
+
+function InfoRow({ label, value }: { label: string; value?: string | number | null }) {
+  if (value === null || value === undefined || value === '') return null;
+  return (
+    <div className="flex gap-2 py-1.5 border-b last:border-0">
+      <dt className="w-40 shrink-0 text-sm text-muted-foreground">{label}</dt>
+      <dd className="text-sm">{value}</dd>
+    </div>
+  );
+}
+
+function formatDate(value: string | null): string | null {
+  if (!value) return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleDateString();
+}
+
+function OverviewTab({ company }: { company: CompanyTabsCompany }) {
+  const incorporationDate = formatDate(company.incorporationDate);
+
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+      {/* Identity */}
+      <div className="space-y-1">
+        <h3 className="text-sm font-medium mb-2">Identity</h3>
+        <dl>
+          <InfoRow label="Name" value={company.name} />
+          <InfoRow label="Legal Name" value={company.legalName} />
+          <InfoRow label="Status" value={STATUS_LABELS[company.status] ?? company.status} />
+        </dl>
+      </div>
+
+      {/* Registration */}
+      {(company.taxId ||
+        company.registrationNumber ||
+        company.incorporationCountry ||
+        incorporationDate) && (
+        <div className="space-y-1">
+          <h3 className="text-sm font-medium mb-2">Registration</h3>
+          <dl>
+            <InfoRow label="Tax ID" value={company.taxId} />
+            <InfoRow label="Registration Number" value={company.registrationNumber} />
+            <InfoRow label="Incorporation Country" value={company.incorporationCountry} />
+            <InfoRow label="Incorporation Date" value={incorporationDate} />
+          </dl>
+        </div>
+      )}
+
+      {/* Contact */}
+      {company.billingEmail && (
+        <div className="space-y-1">
+          <h3 className="text-sm font-medium mb-2">Contact</h3>
+          <dl>
+            <InfoRow label="Billing Email" value={company.billingEmail} />
+          </dl>
+        </div>
+      )}
+
+      {/* Notes */}
+      {company.notes && (
+        <div className="space-y-1 md:col-span-2">
+          <h3 className="text-sm font-medium mb-2">Notes</h3>
+          <p className="text-sm whitespace-pre-wrap rounded-md border bg-muted/30 p-3">
+            {company.notes}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function getCompanyTabs({
+  companyId,
+  portSlug,
+  // currentUserId reserved for when NotesList supports entityType='companies'.
+  currentUserId: _currentUserId,
+  company,
+}: CompanyTabsOptions): DetailTab[] {
+  void _currentUserId;
+
+  return [
+    {
+      id: 'overview',
+      label: 'Overview',
+      content: <OverviewTab company={company} />,
+    },
+    {
+      id: 'members',
+      label: 'Members',
+      content: <CompanyMembersTab companyId={companyId} portSlug={portSlug} />,
+    },
+    {
+      id: 'owned-yachts',
+      label: 'Owned Yachts',
+      content: <CompanyOwnedYachtsTab companyId={companyId} portSlug={portSlug} />,
+    },
+    {
+      id: 'addresses',
+      label: 'Addresses',
+      // TODO: wire to future company-addresses endpoint (see company-addresses schema).
+      content: (
+        <EmptyState
+          title="Addresses"
+          description="Company addresses coming soon — the addresses endpoint is pending wiring."
+        />
+      ),
+    },
+    {
+      id: 'documents',
+      label: 'Documents',
+      content: <EmptyState title="Documents" description="Coming soon" />,
+    },
+    {
+      id: 'notes',
+      label: 'Notes',
+      // TODO: NotesList currently supports entityType 'clients' | 'interests'.
+      // Extend NotesList (or swap to a company-notes endpoint) in a follow-up.
+      content: (
+        <EmptyState
+          title="Notes"
+          description="Company notes coming soon — the notes endpoint is pending wiring."
+        />
+      ),
+    },
+    {
+      id: 'tags',
+      label: 'Tags',
+      // TODO: replace with an inline tag editor once one exists; company tags
+      // can be edited via the Edit form in the meantime.
+      content: (
+        <EmptyState title="Tags" description="Manage tags from the Edit company form for now." />
+      ),
+    },
+  ];
+}

src/components/documents/eoi-generate-dialog.tsx

@@ -1,7 +1,7 @@
 'use client';
 
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
-import { useQueryClient } from '@tanstack/react-query';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
 
 import {
   Dialog,
@@ -12,12 +12,19 @@ import {
   DialogTitle,
 } from '@/components/ui/dialog';
 import { Button } from '@/components/ui/button';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Label } from '@/components/ui/label';
 import { apiFetch } from '@/lib/api/client';
 
 interface EoiPrerequisites {
   hasName: boolean;
-  hasEmail: boolean;
+  hasYacht: boolean;
-  hasYachtDims: boolean;
   hasBerth: boolean;
 }
 
@@ -30,11 +37,23 @@ interface EoiGenerateDialogProps {
 
 const PREREQUISITE_LABELS: { key: keyof EoiPrerequisites; label: string }[] = [
   { key: 'hasName', label: 'Client has full name' },
-  { key: 'hasEmail', label: 'Client has email address' },
+  { key: 'hasYacht', label: 'Yacht linked to interest' },
-  { key: 'hasYachtDims', label: 'Yacht dimensions set' },
   { key: 'hasBerth', label: 'Berth linked to interest' },
 ];
 
+const DOCUMENSO_TEMPLATE_VALUE = 'documenso-template';
+
+interface InAppTemplate {
+  id: string;
+  name: string;
+  description?: string | null;
+  templateType: string;
+}
+
+interface ListResponse {
+  data: InAppTemplate[];
+}
+
 export function EoiGenerateDialog({
   interestId,
   open,
@@ -44,9 +63,21 @@ export function EoiGenerateDialog({
   const queryClient = useQueryClient();
   const [isGenerating, setIsGenerating] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [selectedTemplate, setSelectedTemplate] = useState<string>(DOCUMENSO_TEMPLATE_VALUE);
 
   const allMet = Object.values(prerequisites).every(Boolean);
 
+  // Load in-app EOI templates so the operator can pick one as an alternative
+  // to the Documenso external-signing flow.
+  const { data: templatesRes } = useQuery<ListResponse>({
+    queryKey: ['document-templates', { templateType: 'eoi', isActive: true }],
+    queryFn: () =>
+      apiFetch<ListResponse>('/api/v1/document-templates?templateType=eoi&isActive=true'),
+    enabled: open,
+  });
+
+  const inAppTemplates = useMemo(() => templatesRes?.data ?? [], [templatesRes]);
+
   const handleGenerate = async () => {
     if (!allMet) return;
 
@@ -54,9 +85,17 @@ export function EoiGenerateDialog({
     setError(null);
 
     try {
-      await apiFetch('/api/v1/documents/generate-eoi', {
+      const isDocumensoPath = selectedTemplate === DOCUMENSO_TEMPLATE_VALUE;
+      const url = `/api/v1/document-templates/${encodeURIComponent(selectedTemplate)}/generate-and-sign`;
+      await apiFetch(url, {
         method: 'POST',
-        body: { interestId },
+        body: {
+          interestId,
+          pathway: isDocumensoPath ? 'documenso-template' : 'inapp',
+          // Signers are derived server-side from EOI context for both pathways
+          // when the template type is EOI, so the dialog doesn't collect them.
+          signers: [],
+        },
       });
 
       queryClient.invalidateQueries({ queryKey: ['documents', { interestId }] });
@@ -74,39 +113,58 @@ export function EoiGenerateDialog({
         <DialogHeader>
           <DialogTitle>Generate Expression of Interest</DialogTitle>
           <DialogDescription>
-            The following prerequisites must be met before generating the EOI document.
+            Pick how to render the EOI. Documenso is the primary path; in-app templates use the same
+            source PDF but render and store the PDF locally before sending for signing.
           </DialogDescription>
         </DialogHeader>
 
-        <div className="space-y-2 py-2">
+        <div className="space-y-4 py-2">
-          {PREREQUISITE_LABELS.map(({ key, label }) => (
+          <div className="space-y-2">
-            <div key={key} className="flex items-center gap-3">
+            <Label htmlFor="eoi-template">Template</Label>
-              <span
+            <Select value={selectedTemplate} onValueChange={setSelectedTemplate}>
-                className={`flex h-5 w-5 items-center justify-center rounded-full text-xs font-bold ${
+              <SelectTrigger id="eoi-template">
-                  prerequisites[key]
+                <SelectValue />
-                    ? 'bg-green-100 text-green-700'
+              </SelectTrigger>
-                    : 'bg-red-100 text-red-700'
+              <SelectContent>
-                }`}
+                <SelectItem value={DOCUMENSO_TEMPLATE_VALUE}>
-              >
+                  Documenso Standard EOI (recommended)
-                {prerequisites[key] ? '✓' : '✗'}
+                </SelectItem>
-              </span>
+                {inAppTemplates.map((t) => (
-              <span className={prerequisites[key] ? 'text-foreground' : 'text-muted-foreground'}>
+                  <SelectItem key={t.id} value={t.id}>
-                {label}
+                    {t.name}
-              </span>
+                  </SelectItem>
-            </div>
+                ))}
-          ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div className="space-y-2">
+            <p className="text-xs font-medium text-muted-foreground">Prerequisites</p>
+            {PREREQUISITE_LABELS.map(({ key, label }) => (
+              <div key={key} className="flex items-center gap-3">
+                <span
+                  className={`flex h-5 w-5 items-center justify-center rounded-full text-xs font-bold ${
+                    prerequisites[key] ? 'bg-green-100 text-green-700' : 'bg-red-100 text-red-700'
+                  }`}
+                >
+                  {prerequisites[key] ? '✓' : '✗'}
+                </span>
+                <span className={prerequisites[key] ? 'text-foreground' : 'text-muted-foreground'}>
+                  {label}
+                </span>
+              </div>
+            ))}
+          </div>
         </div>
 
-        {error && (
+        {error && <p className="text-sm text-destructive">{error}</p>}
-          <p className="text-sm text-destructive">{error}</p>
-        )}
 
         <DialogFooter>
           <Button variant="outline" onClick={() => onOpenChange(false)}>
             Cancel
           </Button>
           <Button onClick={handleGenerate} disabled={!allMet || isGenerating}>
-            {isGenerating ? 'Generating...' : 'Generate EOI'}
+            {isGenerating ? 'Generating…' : 'Generate EOI'}
           </Button>
         </DialogFooter>
       </DialogContent>

src/components/interests/interest-documents-tab.tsx

@@ -14,13 +14,9 @@ interface InterestDocumentsTabProps {
 
 interface InterestData {
   id: string;
+  yachtId?: string | null;
   berthId?: string | null;
-  client?: {
+  clientName?: string | null;
-    fullName?: string | null;
-    yachtLengthFt?: string | null;
-    yachtLengthM?: string | null;
-    contacts?: Array<{ channel: string; value: string }>;
-  };
 }
 
 export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps) {
@@ -28,20 +24,14 @@ export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps)
 
   const { data: interestRes } = useQuery({
     queryKey: ['interests', interestId],
-    queryFn: () =>
+    queryFn: () => apiFetch<{ data: InterestData }>(`/api/v1/interests/${interestId}`),
-      apiFetch<{ data: InterestData }>(`/api/v1/interests/${interestId}`),
   });
 
   const interest = interestRes?.data;
 
   const prerequisites = {
-    hasName: Boolean(interest?.client?.fullName),
+    hasName: Boolean(interest?.clientName),
-    hasEmail: Boolean(
+    hasYacht: Boolean(interest?.yachtId),
-      interest?.client?.contacts?.some((c) => c.channel === 'email' && c.value),
-    ),
-    hasYachtDims: Boolean(
-      interest?.client?.yachtLengthFt || interest?.client?.yachtLengthM,
-    ),
     hasBerth: Boolean(interest?.berthId),
   };
 

src/components/interests/interest-form.tsx

@@ -18,18 +18,8 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
-import {
+import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter } from '@/components/ui/sheet';
-  Sheet,
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
-  SheetContent,
-  SheetHeader,
-  SheetTitle,
-  SheetFooter,
-} from '@/components/ui/sheet';
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from '@/components/ui/popover';
 import {
   Command,
   CommandEmpty,
@@ -41,6 +31,7 @@ import {
 import { Checkbox } from '@/components/ui/checkbox';
 import { Separator } from '@/components/ui/separator';
 import { TagPicker } from '@/components/shared/tag-picker';
+import { YachtPicker } from '@/components/yachts/yacht-picker';
 import { apiFetch } from '@/lib/api/client';
 import { useEntityOptions } from '@/hooks/use-entity-options';
 import { createInterestSchema, type CreateInterestInput } from '@/lib/validators/interests';
@@ -71,6 +62,7 @@ interface InterestFormProps {
     id: string;
     clientId: string;
     clientName?: string | null;
+    yachtId?: string | null;
     berthId?: string | null;
     berthMooringNumber?: string | null;
     pipelineStage: string;
@@ -101,6 +93,7 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
     resolver: zodResolver(createInterestSchema),
     defaultValues: {
       clientId: '',
+      yachtId: undefined,
       pipelineStage: 'open',
       reminderEnabled: false,
       tagIds: [],
@@ -111,26 +104,34 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
   const reminderEnabled = watch('reminderEnabled');
   const selectedClientId = watch('clientId');
   const selectedBerthId = watch('berthId');
+  const selectedYachtId = watch('yachtId');
 
-  const { options: clientOptions, isLoading: clientsLoading, setSearch: setClientSearch } =
+  const {
-    useEntityOptions({
+    options: clientOptions,
-      endpoint: '/api/v1/clients/options',
+    isLoading: clientsLoading,
-      labelKey: 'fullName',
+    setSearch: setClientSearch,
-    });
+  } = useEntityOptions({
+    endpoint: '/api/v1/clients/options',
+    labelKey: 'fullName',
+  });
 
-  const { options: berthOptions, isLoading: berthsLoading, setSearch: setBerthSearch } =
+  const {
-    useEntityOptions({
+    options: berthOptions,
-      endpoint: '/api/v1/berths/options',
+    isLoading: berthsLoading,
-      labelKey: 'mooringNumber',
+    setSearch: setBerthSearch,
-    });
+  } = useEntityOptions({
+    endpoint: '/api/v1/berths/options',
+    labelKey: 'mooringNumber',
+  });
 
   useEffect(() => {
     if (interest && open) {
       reset({
         clientId: interest.clientId,
+        yachtId: interest.yachtId ?? undefined,
         berthId: interest.berthId ?? undefined,
-        pipelineStage: interest.pipelineStage as typeof PIPELINE_STAGES[number],
+        pipelineStage: interest.pipelineStage as (typeof PIPELINE_STAGES)[number],
-        leadCategory: interest.leadCategory as typeof LEAD_CATEGORIES[number] | undefined,
+        leadCategory: interest.leadCategory as (typeof LEAD_CATEGORIES)[number] | undefined,
         source: interest.source ?? undefined,
         notes: interest.notes ?? undefined,
         reminderEnabled: interest.reminderEnabled ?? false,
@@ -140,6 +141,7 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
     } else if (!interest && open) {
       reset({
         clientId: '',
+        yachtId: undefined,
         pipelineStage: 'open',
         reminderEnabled: false,
         tagIds: [],
@@ -178,10 +180,7 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
           <SheetTitle>{isEdit ? 'Edit Interest' : 'New Interest'}</SheetTitle>
         </SheetHeader>
 
-        <form
+        <form onSubmit={handleSubmit((data) => mutation.mutate(data))} className="space-y-6 py-6">
-          onSubmit={handleSubmit((data) => mutation.mutate(data))}
-          className="space-y-6 py-6"
-        >
           {/* Client */}
           <div className="space-y-4">
             <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
@@ -202,16 +201,13 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
                     )}
                     disabled={isEdit}
                   >
-                    {selectedClient?.label ?? (interest?.clientName ?? 'Select client...')}
+                    {selectedClient?.label ?? interest?.clientName ?? 'Select client...'}
                     <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
                   </Button>
                 </PopoverTrigger>
                 <PopoverContent className="w-[400px] p-0">
                   <Command>
-                    <CommandInput
+                    <CommandInput placeholder="Search clients..." onValueChange={setClientSearch} />
-                      placeholder="Search clients..."
-                      onValueChange={setClientSearch}
-                    />
                     <CommandList>
                       <CommandEmpty>
                         {clientsLoading ? 'Loading...' : 'No clients found.'}
@@ -258,16 +254,13 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
                       !selectedBerthId && 'text-muted-foreground',
                     )}
                   >
-                    {selectedBerth?.label ?? (interest?.berthMooringNumber ?? 'Select berth...')}
+                    {selectedBerth?.label ?? interest?.berthMooringNumber ?? 'Select berth...'}
                     <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
                   </Button>
                 </PopoverTrigger>
                 <PopoverContent className="w-[400px] p-0">
                   <Command>
-                    <CommandInput
+                    <CommandInput placeholder="Search berths..." onValueChange={setBerthSearch} />
-                      placeholder="Search berths..."
-                      onValueChange={setBerthSearch}
-                    />
                     <CommandList>
                       <CommandEmpty>
                         {berthsLoading ? 'Loading...' : 'No berths found.'}
@@ -312,6 +305,24 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
                 </PopoverContent>
               </Popover>
             </div>
+
+            <div className="space-y-2">
+              <Label>Yacht</Label>
+              <YachtPicker
+                value={selectedYachtId ?? null}
+                onChange={(id) => setValue('yachtId', id ?? undefined)}
+                ownerFilter={
+                  selectedClientId ? { type: 'client', id: selectedClientId } : undefined
+                }
+                disabled={!selectedClientId}
+                placeholder={selectedClientId ? 'Select yacht...' : 'Select a client first'}
+              />
+              <p className="text-xs text-muted-foreground">
+                Required before the interest can leave the &quot;Open&quot; stage.
+              </p>
+              {/* TODO: also include company-owned yachts where client is a member — requires autocomplete owner=any|company filter */}
+              {/* TODO: add "Add new yacht" inline shortcut (requires YachtForm integration) */}
+            </div>
           </div>
 
           <Separator />
@@ -326,7 +337,9 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
                 <Label>Stage</Label>
                 <Select
                   value={watch('pipelineStage') ?? 'open'}
-                  onValueChange={(v) => setValue('pipelineStage', v as typeof PIPELINE_STAGES[number])}
+                  onValueChange={(v) =>
+                    setValue('pipelineStage', v as (typeof PIPELINE_STAGES)[number])
+                  }
                 >
                   <SelectTrigger>
                     <SelectValue placeholder="Select stage" />
@@ -346,7 +359,10 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
                 <Select
                   value={watch('leadCategory') ?? ''}
                   onValueChange={(v) =>
-                    setValue('leadCategory', v ? v as typeof LEAD_CATEGORIES[number] : undefined)
+                    setValue(
+                      'leadCategory',
+                      v ? (v as (typeof LEAD_CATEGORIES)[number]) : undefined,
+                    )
                   }
                 >
                   <SelectTrigger>
@@ -427,18 +443,11 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
           {/* Tags */}
           <div className="space-y-2">
             <Label>Tags</Label>
-            <TagPicker
+            <TagPicker selectedIds={tagIds} onChange={(ids) => setValue('tagIds', ids)} />
-              selectedIds={tagIds}
-              onChange={(ids) => setValue('tagIds', ids)}
-            />
           </div>
 
           <SheetFooter>
-            <Button
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
-              type="button"
-              variant="outline"
-              onClick={() => onOpenChange(false)}
-            >
               Cancel
             </Button>
             <Button type="submit" disabled={isSubmitting || mutation.isPending}>

src/components/layout/sidebar.tsx

@@ -8,6 +8,8 @@ import {
   Users,
   Bookmark,
   Anchor,
+  Ship,
+  Building2,
   Receipt,
   FileText,
   FolderOpen,
@@ -30,12 +32,7 @@ import { Badge } from '@/components/ui/badge';
 import { Separator } from '@/components/ui/separator';
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { Sheet, SheetContent, SheetTrigger } from '@/components/ui/sheet';
-import {
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
-  Tooltip,
-  TooltipContent,
-  TooltipProvider,
-  TooltipTrigger,
-} from '@/components/ui/tooltip';
 import type { UserPortRole } from '@/lib/db/schema/users';
 import type { Role } from '@/lib/db/schema/users';
 
@@ -65,6 +62,8 @@ function buildNavSections(portSlug: string | undefined): NavSection[] {
       items: [
         { href: `${base}/dashboard`, label: 'Dashboard', icon: LayoutDashboard },
         { href: `${base}/clients`, label: 'Clients', icon: Users },
+        { href: `${base}/yachts`, label: 'Yachts', icon: Ship },
+        { href: `${base}/companies`, label: 'Companies', icon: Building2 },
         { href: `${base}/interests`, label: 'Interests', icon: Bookmark },
         { href: `${base}/berths`, label: 'Berths', icon: Anchor },
       ],
@@ -280,7 +279,8 @@ export function Sidebar({ portRoles }: SidebarProps) {
 
   // Check for admin access based on role permissions
   const hasAdminAccess = portRoles.some(
-    (pr) => pr.role?.permissions?.admin?.manage_users || pr.role?.permissions?.admin?.manage_settings,
+    (pr) =>
+      pr.role?.permissions?.admin?.manage_users || pr.role?.permissions?.admin?.manage_settings,
   );
 
   return (

src/components/portal/password-set-form.tsx

@@ -0,0 +1,178 @@
+'use client';
+
+import Link from 'next/link';
+import { useSearchParams } from 'next/navigation';
+import { useState } from 'react';
+import { CheckCircle2, Loader2 } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { PortalAuthShell } from '@/components/portal/portal-auth-shell';
+
+interface PasswordSetFormProps {
+  /** API endpoint that accepts `{ token, password }` and sets / resets the password. */
+  endpoint: string;
+  title: string;
+  description: string;
+  successTitle: string;
+  successDescription: string;
+  submitLabel: string;
+}
+
+const MIN_LENGTH = 9;
+
+/**
+ * Shared form used by both the activation and password-reset flows. The
+ * activation token is read from the `?token=` query string. Empty / missing
+ * tokens land the user in an explicit error state instead of submitting a
+ * doomed request.
+ */
+export function PasswordSetForm({
+  endpoint,
+  title,
+  description,
+  successTitle,
+  successDescription,
+  submitLabel,
+}: PasswordSetFormProps) {
+  const search = useSearchParams();
+  const token = search.get('token') ?? '';
+
+  const [password, setPassword] = useState('');
+  const [confirm, setConfirm] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [done, setDone] = useState(false);
+
+  const tooShort = password.length > 0 && password.length < MIN_LENGTH;
+  const mismatch = confirm.length > 0 && password !== confirm;
+  const canSubmit = !!token && password.length >= MIN_LENGTH && password === confirm && !loading;
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    if (!canSubmit) return;
+    setLoading(true);
+    setError('');
+    try {
+      const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token, password }),
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        setError((data as { error?: string }).error ?? 'Something went wrong. Please try again.');
+        return;
+      }
+      setDone(true);
+    } catch {
+      setError('Unable to connect. Please try again.');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (!token) {
+    return (
+      <PortalAuthShell>
+        <div className="text-center space-y-3">
+          <h1 className="text-xl font-semibold text-gray-900">Link is missing or invalid</h1>
+          <p className="text-sm text-gray-500">
+            Please use the link from the email we sent you. If the link is broken, request a new
+            one.
+          </p>
+          <Link
+            href="/portal/forgot-password"
+            className="inline-block text-sm text-[#007bff] hover:underline"
+          >
+            Request a new link
+          </Link>
+        </div>
+      </PortalAuthShell>
+    );
+  }
+
+  if (done) {
+    return (
+      <PortalAuthShell>
+        <div className="text-center">
+          <div className="inline-flex items-center justify-center w-14 h-14 rounded-full bg-green-50 mb-4">
+            <CheckCircle2 className="h-7 w-7 text-green-600" />
+          </div>
+          <h1 className="text-xl font-semibold text-gray-900 mb-2">{successTitle}</h1>
+          <p className="text-gray-500 text-sm">{successDescription}</p>
+          <Link
+            href="/portal/login"
+            className="mt-6 inline-block text-sm text-[#007bff] hover:underline"
+          >
+            Sign in
+          </Link>
+        </div>
+      </PortalAuthShell>
+    );
+  }
+
+  return (
+    <PortalAuthShell>
+      <div className="mb-6">
+        <h1 className="text-xl font-semibold text-gray-900">{title}</h1>
+        <p className="text-sm text-gray-500 mt-1">{description}</p>
+      </div>
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div className="space-y-1.5">
+          <Label htmlFor="password">New password</Label>
+          <Input
+            id="password"
+            type="password"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            required
+            autoFocus
+            autoComplete="new-password"
+            minLength={MIN_LENGTH}
+            disabled={loading}
+          />
+          <p className="text-xs text-gray-500">At least {MIN_LENGTH} characters.</p>
+          {tooShort && (
+            <p className="text-xs text-red-600">
+              Password must be at least {MIN_LENGTH} characters.
+            </p>
+          )}
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="confirm">Confirm password</Label>
+          <Input
+            id="confirm"
+            type="password"
+            value={confirm}
+            onChange={(e) => setConfirm(e.target.value)}
+            required
+            autoComplete="new-password"
+            disabled={loading}
+          />
+          {mismatch && <p className="text-xs text-red-600">Passwords don&apos;t match.</p>}
+        </div>
+
+        {error && <p className="text-sm text-red-600">{error}</p>}
+
+        <Button
+          type="submit"
+          className="w-full bg-[#007bff] hover:bg-[#0069d9] text-white"
+          disabled={!canSubmit}
+        >
+          {loading ? (
+            <>
+              <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+              Saving…
+            </>
+          ) : (
+            submitLabel
+          )}
+        </Button>
+      </form>
+    </PortalAuthShell>
+  );
+}

src/components/portal/portal-auth-shell.tsx

@@ -0,0 +1,27 @@
+const BG_URL = 'https://s3.portnimara.com/images/Overhead_1_blur.png';
+const LOGO_URL =
+  'https://s3.portnimara.com/images/Port%20Nimara%20New%20Logo-Circular%20Frame_250px.png';
+
+export function PortalAuthShell({ children }: { children: React.ReactNode }) {
+  return (
+    <div
+      className="min-h-screen flex items-center justify-center px-4 py-8"
+      style={{
+        backgroundImage: `url('${BG_URL}')`,
+        backgroundSize: 'cover',
+        backgroundPosition: 'center',
+        backgroundColor: '#f2f2f2',
+      }}
+    >
+      <div className="w-full max-w-md">
+        <div className="bg-white rounded-lg shadow-lg p-8">
+          <div className="flex justify-center mb-6">
+            {/* eslint-disable-next-line @next/next/no-img-element */}
+            <img src={LOGO_URL} alt="Port Nimara" className="w-24 h-auto" />
+          </div>
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/portal/portal-nav.tsx

@@ -2,12 +2,14 @@
 
 import Link from 'next/link';
 import { usePathname } from 'next/navigation';
-import { LayoutDashboard, Anchor, FileText, Receipt } from 'lucide-react';
+import { LayoutDashboard, Anchor, FileText, Receipt, Sailboat, CalendarCheck } from 'lucide-react';
 import { cn } from '@/lib/utils';
 
 const navItems = [
   { label: 'Dashboard', href: '/portal/dashboard', icon: LayoutDashboard },
   { label: 'Interests', href: '/portal/interests', icon: Anchor },
+  { label: 'My Yachts', href: '/portal/my-yachts', icon: Sailboat },
+  { label: 'Reservations', href: '/portal/my-reservations', icon: CalendarCheck },
   { label: 'Documents', href: '/portal/documents', icon: FileText },
   { label: 'Invoices', href: '/portal/invoices', icon: Receipt },
 ];

src/components/reservations/berth-reserve-dialog.tsx

@@ -0,0 +1,251 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useForm } from 'react-hook-form';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Loader2 } from 'lucide-react';
+import { toast } from 'sonner';
+
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogFooter,
+  DialogDescription,
+} from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import { Input } from '@/components/ui/input';
+import { Textarea } from '@/components/ui/textarea';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { ClientPicker } from '@/components/shared/client-picker';
+import { YachtPicker } from '@/components/yachts/yacht-picker';
+import { apiFetch } from '@/lib/api/client';
+
+type TenureType = 'permanent' | 'fixed_term' | 'seasonal';
+
+type FormValues = {
+  clientId: string | null;
+  yachtId: string | null;
+  startDate: string; // YYYY-MM-DD
+  tenureType: TenureType;
+  notes?: string;
+};
+
+interface BerthReserveDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  berthId: string;
+}
+
+export function BerthReserveDialog({ open, onOpenChange, berthId }: BerthReserveDialogProps) {
+  const queryClient = useQueryClient();
+  const [formError, setFormError] = useState<string | null>(null);
+
+  const {
+    register,
+    handleSubmit,
+    watch,
+    setValue,
+    reset,
+    formState: { errors, isSubmitting },
+  } = useForm<FormValues>({
+    defaultValues: {
+      clientId: null,
+      yachtId: null,
+      startDate: new Date().toISOString().slice(0, 10),
+      tenureType: 'permanent',
+      notes: '',
+    },
+  });
+
+  useEffect(() => {
+    if (open) {
+      setFormError(null);
+      reset({
+        clientId: null,
+        yachtId: null,
+        startDate: new Date().toISOString().slice(0, 10),
+        tenureType: 'permanent',
+        notes: '',
+      });
+    }
+  }, [open, reset]);
+
+  const clientId = watch('clientId');
+  const yachtId = watch('yachtId');
+  const tenureType = watch('tenureType');
+
+  // When client changes, clear yacht (since yacht-picker is filtered to owner=client)
+  useEffect(() => {
+    setValue('yachtId', null);
+  }, [clientId, setValue]);
+
+  function validate(data: FormValues): string | null {
+    if (!data.clientId) return 'Please select a client';
+    if (!data.yachtId) return 'Please select a yacht';
+    return null;
+  }
+
+  async function createPending(data: FormValues): Promise<{ id: string }> {
+    const res = await apiFetch<{ data: { id: string } }>(`/api/v1/berths/${berthId}/reservations`, {
+      method: 'POST',
+      body: {
+        clientId: data.clientId!,
+        yachtId: data.yachtId!,
+        startDate: data.startDate,
+        tenureType: data.tenureType,
+        notes: data.notes?.trim() || undefined,
+      },
+    });
+    return res.data;
+  }
+
+  const createMutation = useMutation({
+    mutationFn: async (data: FormValues) => {
+      const err = validate(data);
+      if (err) throw new Error(err);
+      await createPending(data);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['berths', berthId, 'reservations'] });
+      queryClient.invalidateQueries({ queryKey: ['berth-reservations'] });
+      toast.success('Reservation created');
+      onOpenChange(false);
+    },
+    onError: (err: unknown) => {
+      const msg = err instanceof Error ? err.message : 'Failed to create reservation';
+      setFormError(msg);
+    },
+  });
+
+  const createAndActivateMutation = useMutation({
+    mutationFn: async (data: FormValues) => {
+      const err = validate(data);
+      if (err) throw new Error(err);
+      const pending = await createPending(data);
+      // Immediately activate
+      await apiFetch(`/api/v1/berth-reservations/${pending.id}`, {
+        method: 'PATCH',
+        body: { action: 'activate' },
+      });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['berths', berthId, 'reservations'] });
+      queryClient.invalidateQueries({ queryKey: ['berth-reservations'] });
+      toast.success('Reservation created and activated');
+      onOpenChange(false);
+    },
+    onError: (err: unknown) => {
+      const msg = err instanceof Error ? err.message : 'Failed to activate';
+      if (/active reservation|conflict|409/i.test(msg)) {
+        setFormError(
+          'This berth already has an active reservation. The pending record was created — activate it manually once the other reservation ends.',
+        );
+      } else {
+        setFormError(msg);
+      }
+    },
+  });
+
+  const isPending = isSubmitting || createMutation.isPending || createAndActivateMutation.isPending;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-md">
+        <DialogHeader>
+          <DialogTitle>Reserve this berth</DialogTitle>
+          <DialogDescription>
+            Create a pending reservation or activate it immediately.
+          </DialogDescription>
+        </DialogHeader>
+
+        <form className="space-y-4">
+          <div className="space-y-2">
+            <Label>Client</Label>
+            <ClientPicker value={clientId} onChange={(id) => setValue('clientId', id)} />
+          </div>
+
+          <div className="space-y-2">
+            <Label>Yacht</Label>
+            <YachtPicker
+              value={yachtId}
+              onChange={(id) => setValue('yachtId', id)}
+              ownerFilter={clientId ? { type: 'client', id: clientId } : undefined}
+              disabled={!clientId}
+              placeholder={clientId ? 'Select yacht...' : 'Select a client first'}
+            />
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="startDate">Start date</Label>
+            <Input id="startDate" type="date" {...register('startDate', { required: true })} />
+            {errors.startDate && <p className="text-xs text-destructive">Required</p>}
+          </div>
+
+          <div className="space-y-2">
+            <Label>Tenure</Label>
+            <Select
+              value={tenureType}
+              onValueChange={(v) => setValue('tenureType', v as TenureType)}
+            >
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="permanent">Permanent</SelectItem>
+                <SelectItem value="fixed_term">Fixed term</SelectItem>
+                <SelectItem value="seasonal">Seasonal</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div className="space-y-2">
+            <Label htmlFor="notes">Notes (optional)</Label>
+            <Textarea id="notes" rows={2} {...register('notes')} />
+          </div>
+
+          {formError && <p className="text-sm text-destructive">{formError}</p>}
+
+          <DialogFooter className="flex-col-reverse sm:flex-row gap-2">
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+              Cancel
+            </Button>
+            <Button
+              type="button"
+              variant="outline"
+              disabled={isPending}
+              onClick={handleSubmit((data) => {
+                setFormError(null);
+                createMutation.mutate(data);
+              })}
+            >
+              {createMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+              Create reservation
+            </Button>
+            <Button
+              type="button"
+              disabled={isPending}
+              onClick={handleSubmit((data) => {
+                setFormError(null);
+                createAndActivateMutation.mutate(data);
+              })}
+            >
+              {createAndActivateMutation.isPending && (
+                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+              )}
+              Create and activate
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

src/components/reservations/reservation-list.tsx

@@ -0,0 +1,215 @@
+'use client';
+
+import { useParams } from 'next/navigation';
+import Link from 'next/link';
+import { useQuery } from '@tanstack/react-query';
+
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { EmptyState } from '@/components/shared/empty-state';
+import { apiFetch } from '@/lib/api/client';
+
+export interface ReservationRow {
+  id: string;
+  berthId: string;
+  portId: string;
+  clientId: string;
+  yachtId: string;
+  status: 'pending' | 'active' | 'ended' | 'cancelled';
+  startDate: string;
+  endDate: string | null;
+  tenureType: string;
+  contractFileId: string | null;
+  notes: string | null;
+  createdAt: string;
+}
+
+export interface ReservationListProps {
+  reservations: ReservationRow[];
+  showBerth?: boolean;
+  portSlug?: string;
+  emptyMessage?: string;
+}
+
+/**
+ * Renders a client's name as a link by fetching the client record.
+ * Uses TanStack Query cache for memoization of repeated clientId queries.
+ */
+function ClientLink({ clientId, portSlug }: { clientId: string; portSlug: string }) {
+  const { data } = useQuery<{ fullName: string }>({
+    queryKey: ['clients', clientId, 'name-only'],
+    queryFn: () =>
+      apiFetch<{ data: { fullName: string } }>(`/api/v1/clients/${clientId}`).then((r) => r.data),
+  });
+
+  return (
+    <Link
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      href={`/${portSlug}/clients/${clientId}` as any}
+      className="text-primary hover:underline"
+    >
+      {data?.fullName ?? `Client ${clientId.slice(0, 8)}`}
+    </Link>
+  );
+}
+
+/**
+ * Renders a yacht's name as a link by fetching the yacht record.
+ */
+function YachtLink({ yachtId, portSlug }: { yachtId: string; portSlug: string }) {
+  const { data } = useQuery<{ name: string }>({
+    queryKey: ['yachts', yachtId, 'name-only'],
+    queryFn: () =>
+      apiFetch<{ data: { name: string } }>(`/api/v1/yachts/${yachtId}`).then((r) => r.data),
+  });
+
+  return (
+    <Link
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      href={`/${portSlug}/yachts/${yachtId}` as any}
+      className="text-primary hover:underline"
+    >
+      {data?.name ?? `Yacht ${yachtId.slice(0, 8)}`}
+    </Link>
+  );
+}
+
+/**
+ * Renders a berth's mooring number as a link by fetching the berth record.
+ */
+function BerthLink({ berthId, portSlug }: { berthId: string; portSlug: string }) {
+  const { data } = useQuery<{ mooringNumber: string }>({
+    queryKey: ['berths', berthId, 'name-only'],
+    queryFn: () =>
+      apiFetch<{ data: { mooringNumber: string } }>(`/api/v1/berths/${berthId}`).then(
+        (r) => r.data,
+      ),
+  });
+
+  return (
+    <Link
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      href={`/${portSlug}/berths/${berthId}` as any}
+      className="text-primary hover:underline"
+    >
+      {data?.mooringNumber ?? `Berth ${berthId.slice(0, 8)}`}
+    </Link>
+  );
+}
+
+/**
+ * Renders a status badge with appropriate color coding.
+ */
+function StatusBadge({ status }: { status: ReservationRow['status'] }) {
+  const colorMap: Record<ReservationRow['status'], string> = {
+    pending: 'bg-gray-100 text-gray-800',
+    active: 'bg-green-100 text-green-800',
+    ended: 'bg-blue-100 text-blue-800',
+    cancelled: 'bg-red-100 text-red-800',
+  };
+
+  const color = colorMap[status];
+  const label = status.charAt(0).toUpperCase() + status.slice(1);
+
+  return (
+    <span className={`inline-block rounded-full px-2 py-0.5 text-xs font-medium ${color}`}>
+      {label}
+    </span>
+  );
+}
+
+/**
+ * Pretty-prints tenure type for display.
+ */
+function prettyTenure(tenureType: string): string {
+  const tenureMap: Record<string, string> = {
+    permanent: 'Permanent',
+    fixed_term: 'Fixed term',
+    seasonal: 'Seasonal',
+  };
+  return tenureMap[tenureType] ?? tenureType;
+}
+
+/**
+ * Formats a date range as "{startDate} → {endDate or 'ongoing'}".
+ */
+function formatDateRange(startDate: string, endDate: string | null): string {
+  const start = new Date(startDate).toLocaleDateString();
+  const end = endDate ? new Date(endDate).toLocaleDateString() : 'ongoing';
+  return `${start} → ${end}`;
+}
+
+export function ReservationList({
+  reservations,
+  showBerth = false,
+  portSlug: portSlugProp,
+  emptyMessage,
+}: ReservationListProps) {
+  const routeParams = useParams<{ portSlug: string }>();
+  const portSlug = portSlugProp ?? routeParams?.portSlug ?? '';
+
+  if (reservations.length === 0) {
+    return (
+      <EmptyState title="No reservations" description={emptyMessage ?? 'No reservations yet.'} />
+    );
+  }
+
+  return (
+    <div className="rounded-md border">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            {showBerth && <TableHead>Berth</TableHead>}
+            <TableHead>Client</TableHead>
+            <TableHead>Yacht</TableHead>
+            <TableHead>Dates</TableHead>
+            <TableHead>Tenure</TableHead>
+            <TableHead>Status</TableHead>
+            <TableHead>Contract</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {reservations.map((r) => (
+            <TableRow key={r.id}>
+              {showBerth && (
+                <TableCell>
+                  <BerthLink berthId={r.berthId} portSlug={portSlug} />
+                </TableCell>
+              )}
+              <TableCell>
+                <ClientLink clientId={r.clientId} portSlug={portSlug} />
+              </TableCell>
+              <TableCell>
+                <YachtLink yachtId={r.yachtId} portSlug={portSlug} />
+              </TableCell>
+              <TableCell>{formatDateRange(r.startDate, r.endDate)}</TableCell>
+              <TableCell>{prettyTenure(r.tenureType)}</TableCell>
+              <TableCell>
+                <StatusBadge status={r.status} />
+              </TableCell>
+              <TableCell>
+                {r.contractFileId ? (
+                  // TODO: Confirm final file-download endpoint URL when available
+                  <a
+                    href={`/api/v1/files/${r.contractFileId}/download`}
+                    className="text-primary hover:underline"
+                  >
+                    View contract
+                  </a>
+                ) : (
+                  '—'
+                )}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

src/components/search/command-search.tsx

@@ -2,7 +2,7 @@
 
 import { useEffect, useRef, useState, useCallback } from 'react';
 import { useRouter } from 'next/navigation';
-import { Search, Clock, User, TrendingUp, Anchor } from 'lucide-react';
+import { Search, Clock, User, TrendingUp, Anchor, Ship, Building2 } from 'lucide-react';
 
 import { cn } from '@/lib/utils';
 import { useSearch } from '@/hooks/use-search';
@@ -22,7 +22,11 @@ export function CommandSearch() {
   const hasQuery = query.length >= 2;
   const hasResults =
     results &&
-    (results.clients.length > 0 || results.interests.length > 0 || results.berths.length > 0);
+    (results.clients.length > 0 ||
+      results.interests.length > 0 ||
+      results.berths.length > 0 ||
+      results.yachts.length > 0 ||
+      results.companies.length > 0);
 
   // Cmd/Ctrl+K focuses the input
   useEffect(() => {
@@ -67,7 +71,13 @@ export function CommandSearch() {
     }
   }
 
-  const iconMap = { client: User, interest: TrendingUp, berth: Anchor } as const;
+  const iconMap = {
+    client: User,
+    interest: TrendingUp,
+    berth: Anchor,
+    yacht: Ship,
+    company: Building2,
+  } as const;
 
   return (
     <div ref={wrapperRef} className="relative">
@@ -142,12 +152,38 @@ export function CommandSearch() {
                       id: c.id,
                       icon: 'client',
                       label: c.fullName,
-                      sub: c.companyName,
+                      sub: null,
                     }))}
                     iconMap={iconMap}
                     onSelect={(id) => navigate(`/${portSlug}/clients/${id}`)}
                   />
                 )}
+                {results.yachts.length > 0 && (
+                  <ResultGroup
+                    heading="Yachts"
+                    items={results.yachts.map((y) => ({
+                      id: y.id,
+                      icon: 'yacht',
+                      label: y.name,
+                      sub: [y.hullNumber, y.registration].filter(Boolean).join(' · ') || null,
+                    }))}
+                    iconMap={iconMap}
+                    onSelect={(id) => navigate(`/${portSlug}/yachts/${id}`)}
+                  />
+                )}
+                {results.companies.length > 0 && (
+                  <ResultGroup
+                    heading="Companies"
+                    items={results.companies.map((c) => ({
+                      id: c.id,
+                      icon: 'company',
+                      label: c.name,
+                      sub: [c.legalName, c.taxId].filter(Boolean).join(' · ') || null,
+                    }))}
+                    iconMap={iconMap}
+                    onSelect={(id) => navigate(`/${portSlug}/companies/${id}`)}
+                  />
+                )}
                 {results.interests.length > 0 && (
                   <ResultGroup
                     heading="Interests"
@@ -190,7 +226,12 @@ function ResultGroup({
   onSelect,
 }: {
   heading: string;
-  items: Array<{ id: string; icon: 'client' | 'interest' | 'berth'; label: string; sub?: string | null }>;
+  items: Array<{
+    id: string;
+    icon: 'client' | 'interest' | 'berth' | 'yacht' | 'company';
+    label: string;
+    sub?: string | null;
+  }>;
   iconMap: Record<string, React.ElementType | undefined>;
   onSelect: (id: string) => void;
 }) {

src/components/search/search-result-item.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { User, Anchor, TrendingUp } from 'lucide-react';
+import { User, Anchor, TrendingUp, Ship, Building2 } from 'lucide-react';
 
 import { CommandItem } from '@/components/ui/command';
 
@@ -9,7 +9,6 @@ import { CommandItem } from '@/components/ui/command';
 interface ClientItem {
   id: string;
   fullName: string;
-  companyName: string | null;
 }
 
 interface InterestItem {
@@ -26,10 +25,26 @@ interface BerthItem {
   status: string;
 }
 
+interface YachtItem {
+  id: string;
+  name: string;
+  hullNumber: string | null;
+  registration: string | null;
+}
+
+interface CompanyItem {
+  id: string;
+  name: string;
+  legalName: string | null;
+  taxId: string | null;
+}
+
 type SearchResultItemProps =
   | { type: 'client'; item: ClientItem; onSelect: () => void }
   | { type: 'interest'; item: InterestItem; onSelect: () => void }
-  | { type: 'berth'; item: BerthItem; onSelect: () => void };
+  | { type: 'berth'; item: BerthItem; onSelect: () => void }
+  | { type: 'yacht'; item: YachtItem; onSelect: () => void }
+  | { type: 'company'; item: CompanyItem; onSelect: () => void };
 
 // ─── Component ────────────────────────────────────────────────────────────────
 
@@ -38,12 +53,7 @@ export function SearchResultItem({ type, item, onSelect }: SearchResultItemProps
     return (
       <CommandItem value={item.id} onSelect={onSelect} className="flex items-center gap-2">
         <User className="h-4 w-4 shrink-0 text-muted-foreground" />
-        <div className="flex flex-col">
+        <span className="text-sm font-medium">{item.fullName}</span>
-          <span className="text-sm font-medium">{item.fullName}</span>
-          {item.companyName && (
-            <span className="text-xs text-muted-foreground">{item.companyName}</span>
-          )}
-        </div>
       </CommandItem>
     );
   }
@@ -63,6 +73,38 @@ export function SearchResultItem({ type, item, onSelect }: SearchResultItemProps
     );
   }
 
+  if (type === 'yacht') {
+    return (
+      <CommandItem value={item.id} onSelect={onSelect} className="flex items-center gap-2">
+        <Ship className="h-4 w-4 shrink-0 text-muted-foreground" />
+        <div className="flex flex-col">
+          <span className="text-sm font-medium">{item.name}</span>
+          {(item.hullNumber || item.registration) && (
+            <span className="text-xs text-muted-foreground">
+              {[item.hullNumber, item.registration].filter(Boolean).join(' · ')}
+            </span>
+          )}
+        </div>
+      </CommandItem>
+    );
+  }
+
+  if (type === 'company') {
+    return (
+      <CommandItem value={item.id} onSelect={onSelect} className="flex items-center gap-2">
+        <Building2 className="h-4 w-4 shrink-0 text-muted-foreground" />
+        <div className="flex flex-col">
+          <span className="text-sm font-medium">{item.name}</span>
+          {(item.legalName || item.taxId) && (
+            <span className="text-xs text-muted-foreground">
+              {[item.legalName, item.taxId].filter(Boolean).join(' · ')}
+            </span>
+          )}
+        </div>
+      </CommandItem>
+    );
+  }
+
   // berth
   return (
     <CommandItem value={item.id} onSelect={onSelect} className="flex items-center gap-2">

src/components/shared/client-picker.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import { useState } from 'react';
+import { Check, ChevronsUpDown } from 'lucide-react';
+import { useQuery } from '@tanstack/react-query';
+
+import { Button } from '@/components/ui/button';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { useDebounce } from '@/hooks/use-debounce';
+import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';
+
+interface ClientOption {
+  id: string;
+  fullName: string;
+}
+
+interface ClientPickerProps {
+  value: string | null;
+  onChange: (clientId: string | null) => void;
+  placeholder?: string;
+  disabled?: boolean;
+}
+
+export function ClientPicker({
+  value,
+  onChange,
+  placeholder = 'Select client...',
+  disabled,
+}: ClientPickerProps) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState('');
+  const debounced = useDebounce(search, 300);
+
+  const { data } = useQuery<{ data: ClientOption[] }>({
+    queryKey: ['client-picker', debounced],
+    queryFn: () =>
+      apiFetch(
+        `/api/v1/clients?search=${encodeURIComponent(debounced)}&page=1&limit=10&order=desc&includeArchived=false`,
+      ),
+    enabled: open,
+  });
+
+  const options = data?.data ?? [];
+
+  const selectedLabel = (() => {
+    if (!value) return placeholder;
+    const match = options.find((o) => o.id === value);
+    return match?.fullName ?? `Client ${value.slice(0, 8)}`;
+  })();
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          role="combobox"
+          disabled={disabled}
+          className={cn('w-full justify-between', !value && 'text-muted-foreground')}
+        >
+          <span className="truncate">{selectedLabel}</span>
+          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-[320px] p-0" align="start">
+        <Command shouldFilter={false}>
+          <CommandInput placeholder="Search clients…" value={search} onValueChange={setSearch} />
+          <CommandList>
+            <CommandEmpty>No clients found.</CommandEmpty>
+            <CommandGroup>
+              {options.map((c) => (
+                <CommandItem
+                  key={c.id}
+                  value={c.id}
+                  onSelect={() => {
+                    onChange(c.id);
+                    setOpen(false);
+                  }}
+                >
+                  <Check
+                    className={cn('mr-2 h-4 w-4', value === c.id ? 'opacity-100' : 'opacity-0')}
+                  />
+                  <span>{c.fullName}</span>
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}

src/components/shared/owner-picker.tsx

@@ -0,0 +1,164 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { Check, ChevronsUpDown } from 'lucide-react';
+import { useQuery } from '@tanstack/react-query';
+
+import { Button } from '@/components/ui/button';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { useDebounce } from '@/hooks/use-debounce';
+import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';
+
+export type OwnerRef = { type: 'client' | 'company'; id: string };
+
+interface OwnerOption {
+  id: string;
+  name?: string | null;
+  fullName?: string | null;
+}
+
+interface OwnerPickerProps {
+  value: OwnerRef | null;
+  onChange: (value: OwnerRef | null) => void;
+  /** Optional placeholder when empty */
+  placeholder?: string;
+  /** Disable the component */
+  disabled?: boolean;
+}
+
+export function OwnerPicker({
+  value,
+  onChange,
+  placeholder = 'Select owner...',
+  disabled,
+}: OwnerPickerProps) {
+  const [open, setOpen] = useState(false);
+  const [type, setType] = useState<'client' | 'company'>(value?.type ?? 'client');
+  const [search, setSearch] = useState('');
+  const debounced = useDebounce(search, 300);
+
+  // Keep local `type` in sync if value.type changes externally.
+  useEffect(() => {
+    if (value?.type) setType(value.type);
+  }, [value?.type]);
+
+  const endpoint =
+    type === 'client'
+      ? `/api/v1/clients/options?search=${encodeURIComponent(debounced)}`
+      : `/api/v1/companies/autocomplete?q=${encodeURIComponent(debounced)}`;
+
+  const { data } = useQuery<{ data: OwnerOption[] }>({
+    queryKey: ['owner-picker', type, debounced],
+    queryFn: () => apiFetch(endpoint),
+    enabled: open,
+  });
+
+  const options = data?.data ?? [];
+
+  // Selected display label — show entity's name from current options if
+  // available, otherwise a truncated id fallback.
+  const selectedLabel = (() => {
+    if (!value) return placeholder;
+    const match = options.find((o) => o.id === value.id);
+    if (match) {
+      return type === 'client'
+        ? (match.fullName ?? '(unnamed client)')
+        : (match.name ?? '(unnamed company)');
+    }
+    return value.type === 'client'
+      ? `Client ${value.id.slice(0, 8)}`
+      : `Company ${value.id.slice(0, 8)}`;
+  })();
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          role="combobox"
+          disabled={disabled}
+          className={cn('w-full justify-between', !value && 'text-muted-foreground')}
+        >
+          <span className="truncate">
+            {value && (
+              <span className="mr-2 text-xs opacity-60">
+                {value.type === 'client' ? 'Client:' : 'Company:'}
+              </span>
+            )}
+            {selectedLabel}
+          </span>
+          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-[320px] p-0" align="start">
+        {/* Type toggle */}
+        <div className="flex border-b">
+          <button
+            type="button"
+            onClick={() => {
+              setType('client');
+              setSearch('');
+            }}
+            className={cn(
+              'flex-1 px-3 py-2 text-xs',
+              type === 'client' ? 'bg-accent font-medium' : 'hover:bg-accent/50',
+            )}
+          >
+            Client
+          </button>
+          <button
+            type="button"
+            onClick={() => {
+              setType('company');
+              setSearch('');
+            }}
+            className={cn(
+              'flex-1 px-3 py-2 text-xs',
+              type === 'company' ? 'bg-accent font-medium' : 'hover:bg-accent/50',
+            )}
+          >
+            Company
+          </button>
+        </div>
+
+        <Command shouldFilter={false}>
+          <CommandInput placeholder={`Search ${type}s…`} value={search} onValueChange={setSearch} />
+          <CommandList>
+            <CommandEmpty>No results.</CommandEmpty>
+            <CommandGroup>
+              {options.map((opt) => {
+                const label =
+                  type === 'client' ? (opt.fullName ?? '(unnamed)') : (opt.name ?? '(unnamed)');
+                const isSelected = value?.id === opt.id && value?.type === type;
+                return (
+                  <CommandItem
+                    key={opt.id}
+                    value={opt.id}
+                    onSelect={() => {
+                      onChange({ type, id: opt.id });
+                      setOpen(false);
+                    }}
+                  >
+                    <Check
+                      className={cn('mr-2 h-4 w-4', isSelected ? 'opacity-100' : 'opacity-0')}
+                    />
+                    {label}
+                  </CommandItem>
+                );
+              })}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}

src/components/yachts/yacht-columns.tsx

@@ -0,0 +1,176 @@
+'use client';
+
+import Link from 'next/link';
+import { MoreHorizontal, Pencil, Archive, Eye } from 'lucide-react';
+import type { ColumnDef } from '@tanstack/react-table';
+
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { OwnerLink } from '@/components/yachts/yacht-detail-header';
+
+export interface YachtRow {
+  id: string;
+  name: string;
+  hullNumber: string | null;
+  registration: string | null;
+  currentOwnerType: 'client' | 'company';
+  currentOwnerId: string;
+  lengthFt: string | null;
+  widthFt: string | null;
+  draftFt: string | null;
+  lengthM: string | null;
+  widthM: string | null;
+  status: string;
+  archivedAt: string | null;
+  updatedAt: string;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  active: 'bg-green-100 text-green-800 border-green-300',
+  retired: 'bg-gray-100 text-gray-800 border-gray-300',
+  sold_away: 'bg-amber-100 text-amber-800 border-amber-300',
+};
+
+const STATUS_LABELS: Record<string, string> = {
+  active: 'Active',
+  retired: 'Retired',
+  sold_away: 'Sold Away',
+};
+
+function formatDimensions(yacht: YachtRow): string | null {
+  if (yacht.lengthFt || yacht.widthFt) {
+    const length = yacht.lengthFt ?? '—';
+    const width = yacht.widthFt ?? '—';
+    return `${length} × ${width} ft`;
+  }
+  if (yacht.lengthM || yacht.widthM) {
+    const length = yacht.lengthM ?? '—';
+    const width = yacht.widthM ?? '—';
+    return `${length} × ${width} m`;
+  }
+  return null;
+}
+
+interface GetYachtColumnsOptions {
+  portSlug: string;
+  onEdit: (yacht: YachtRow) => void;
+  onArchive: (yacht: YachtRow) => void;
+}
+
+export function getYachtColumns({
+  portSlug,
+  onEdit,
+  onArchive,
+}: GetYachtColumnsOptions): ColumnDef<YachtRow, unknown>[] {
+  return [
+    {
+      id: 'name',
+      accessorKey: 'name',
+      header: 'Name',
+      cell: ({ row }) => (
+        <Link
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          href={`/${portSlug}/yachts/${row.original.id}` as any}
+          className="font-medium text-primary hover:underline"
+          onClick={(e) => e.stopPropagation()}
+        >
+          {row.original.name}
+        </Link>
+      ),
+    },
+    {
+      id: 'currentOwner',
+      header: 'Current Owner',
+      enableSorting: false,
+      cell: ({ row }) => (
+        <OwnerLink
+          portSlug={portSlug}
+          type={row.original.currentOwnerType}
+          id={row.original.currentOwnerId}
+        />
+      ),
+    },
+    {
+      id: 'dimensions',
+      header: 'Dimensions',
+      enableSorting: false,
+      cell: ({ row }) => {
+        const dims = formatDimensions(row.original);
+        if (!dims) return <span className="text-muted-foreground">—</span>;
+        return <span className="text-sm">{dims}</span>;
+      },
+    },
+    {
+      id: 'hullNumber',
+      accessorKey: 'hullNumber',
+      header: 'Hull Number',
+      enableSorting: false,
+      cell: ({ getValue }) => {
+        const value = getValue() as string | null;
+        if (!value) return <span className="text-muted-foreground">—</span>;
+        return <span className="text-sm">{value}</span>;
+      },
+    },
+    {
+      id: 'status',
+      accessorKey: 'status',
+      header: 'Status',
+      cell: ({ row }) => {
+        const status = row.original.status;
+        const label = STATUS_LABELS[status] ?? status;
+        const color = STATUS_COLORS[status] ?? 'bg-muted text-muted-foreground border-muted';
+        return (
+          <span
+            className={`inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-medium ${color}`}
+          >
+            {label}
+          </span>
+        );
+      },
+    },
+    {
+      id: 'actions',
+      header: '',
+      enableSorting: false,
+      size: 48,
+      cell: ({ row }) => (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-7 w-7"
+              onClick={(e) => e.stopPropagation()}
+            >
+              <MoreHorizontal className="h-4 w-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem asChild>
+              <Link
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                href={`/${portSlug}/yachts/${row.original.id}` as any}
+              >
+                <Eye className="mr-2 h-3.5 w-3.5" />
+                View
+              </Link>
+            </DropdownMenuItem>
+            <DropdownMenuItem onClick={() => onEdit(row.original)}>
+              <Pencil className="mr-2 h-3.5 w-3.5" />
+              Edit
+            </DropdownMenuItem>
+            <DropdownMenuItem className="text-destructive" onClick={() => onArchive(row.original)}>
+              <Archive className="mr-2 h-3.5 w-3.5" />
+              Archive
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ),
+    },
+  ];
+}

src/components/yachts/yacht-detail-header.tsx

@@ -0,0 +1,241 @@
+'use client';
+
+import { useState } from 'react';
+import Link from 'next/link';
+import { useParams, useRouter } from 'next/navigation';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Pencil, Archive, ArrowRightLeft } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { Badge } from '@/components/ui/badge';
+import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
+import { PermissionGate } from '@/components/shared/permission-gate';
+import { YachtForm } from '@/components/yachts/yacht-form';
+import { YachtTransferDialog } from '@/components/yachts/yacht-transfer-dialog';
+import { apiFetch } from '@/lib/api/client';
+
+interface YachtDetailHeaderYacht {
+  id: string;
+  name: string;
+  hullNumber: string | null;
+  registration: string | null;
+  flag: string | null;
+  yearBuilt: number | null;
+  builder: string | null;
+  model: string | null;
+  hullMaterial: string | null;
+  lengthFt: string | null;
+  widthFt: string | null;
+  draftFt: string | null;
+  lengthM: string | null;
+  widthM: string | null;
+  draftM: string | null;
+  currentOwnerType: 'client' | 'company';
+  currentOwnerId: string;
+  status: string;
+  notes: string | null;
+  archivedAt: string | null;
+}
+
+interface YachtDetailHeaderProps {
+  yacht: YachtDetailHeaderYacht;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  active: 'bg-green-100 text-green-800 border-green-300',
+  retired: 'bg-gray-100 text-gray-800 border-gray-300',
+  sold_away: 'bg-amber-100 text-amber-800 border-amber-300',
+};
+
+const STATUS_LABELS: Record<string, string> = {
+  active: 'Active',
+  retired: 'Retired',
+  sold_away: 'Sold Away',
+};
+
+export function OwnerLink({
+  portSlug,
+  type,
+  id,
+}: {
+  portSlug: string;
+  type: 'client' | 'company';
+  id: string;
+}) {
+  const { data } = useQuery<{ fullName?: string; name?: string }>({
+    queryKey: [type === 'client' ? 'clients' : 'companies', id, 'name-only'],
+    queryFn: () =>
+      apiFetch<{ data: { fullName?: string; name?: string } }>(
+        type === 'client' ? `/api/v1/clients/${id}` : `/api/v1/companies/${id}`,
+      ).then((r) => r.data),
+  });
+
+  const label = type === 'client' ? data?.fullName : data?.name;
+  const href = type === 'client' ? `/${portSlug}/clients/${id}` : `/${portSlug}/companies/${id}`;
+
+  return (
+    <Link
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      href={href as any}
+      className="text-primary hover:underline"
+    >
+      {label ?? `${type === 'client' ? 'Client' : 'Company'} ${id.slice(0, 8)}`}
+    </Link>
+  );
+}
+
+function formatDimensions(yacht: YachtDetailHeaderYacht): string | null {
+  const parts: string[] = [];
+  if (yacht.lengthFt) parts.push(`${yacht.lengthFt} ft`);
+  if (yacht.widthFt) parts.push(`${yacht.widthFt} ft`);
+
+  let summary: string | null = null;
+  if (parts.length > 0) {
+    summary = parts.join(' × ');
+  }
+  if (yacht.draftFt) {
+    summary = summary ? `${summary} (draft ${yacht.draftFt} ft)` : `draft ${yacht.draftFt} ft`;
+  }
+  return summary;
+}
+
+export function YachtDetailHeader({ yacht }: YachtDetailHeaderProps) {
+  const queryClient = useQueryClient();
+  const router = useRouter();
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+
+  const [editOpen, setEditOpen] = useState(false);
+  const [archiveOpen, setArchiveOpen] = useState(false);
+  const [transferOpen, setTransferOpen] = useState(false);
+
+  const isArchived = !!yacht.archivedAt;
+
+  const archiveMutation = useMutation({
+    mutationFn: () => apiFetch(`/api/v1/yachts/${yacht.id}`, { method: 'DELETE' }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['yachts', yacht.id] });
+      queryClient.invalidateQueries({ queryKey: ['yachts'] });
+      toast.success('Yacht archived');
+      setArchiveOpen(false);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      router.push(`/${portSlug}/yachts` as any);
+    },
+    onError: (err: Error) => {
+      toast.error(err.message || 'Failed to archive yacht');
+    },
+  });
+
+  const dimensions = formatDimensions(yacht);
+  const statusLabel = STATUS_LABELS[yacht.status] ?? yacht.status;
+  const statusColor = STATUS_COLORS[yacht.status] ?? 'bg-muted text-muted-foreground border-muted';
+
+  return (
+    <>
+      <div className="space-y-3">
+        <div className="flex items-start gap-3 flex-wrap">
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center gap-2 flex-wrap">
+              <h1 className="text-2xl font-bold text-foreground truncate">{yacht.name}</h1>
+              <span
+                className={`inline-flex items-center rounded-full border px-3 py-1 text-xs font-medium ${statusColor}`}
+              >
+                {statusLabel}
+              </span>
+              {isArchived && (
+                <Badge variant="secondary" className="text-xs">
+                  Archived
+                </Badge>
+              )}
+            </div>
+
+            {dimensions && <p className="text-muted-foreground mt-0.5 text-sm">{dimensions}</p>}
+
+            <div className="flex items-center gap-2 mt-2 text-sm text-muted-foreground">
+              <span>Owner:</span>
+              <OwnerLink
+                portSlug={portSlug}
+                type={yacht.currentOwnerType}
+                id={yacht.currentOwnerId}
+              />
+            </div>
+          </div>
+
+          {/* Actions */}
+          <div className="flex items-center gap-2">
+            <Button variant="outline" size="sm" onClick={() => setEditOpen(true)}>
+              <Pencil className="mr-1.5 h-3.5 w-3.5" />
+              Edit
+            </Button>
+            <PermissionGate resource="yachts" action="transfer">
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => setTransferOpen(true)}
+                disabled={isArchived}
+              >
+                <ArrowRightLeft className="mr-1.5 h-3.5 w-3.5" />
+                Transfer
+              </Button>
+            </PermissionGate>
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => setArchiveOpen(true)}
+              disabled={isArchived}
+            >
+              <Archive className="mr-1.5 h-3.5 w-3.5" />
+              Archive
+            </Button>
+          </div>
+        </div>
+      </div>
+
+      <YachtForm
+        open={editOpen}
+        onOpenChange={setEditOpen}
+        yacht={{
+          id: yacht.id,
+          name: yacht.name,
+          hullNumber: yacht.hullNumber,
+          registration: yacht.registration,
+          flag: yacht.flag,
+          yearBuilt: yacht.yearBuilt,
+          builder: yacht.builder,
+          model: yacht.model,
+          hullMaterial: yacht.hullMaterial,
+          lengthFt: yacht.lengthFt,
+          widthFt: yacht.widthFt,
+          draftFt: yacht.draftFt,
+          lengthM: yacht.lengthM,
+          widthM: yacht.widthM,
+          draftM: yacht.draftM,
+          currentOwnerType: yacht.currentOwnerType,
+          currentOwnerId: yacht.currentOwnerId,
+          status: yacht.status,
+          notes: yacht.notes,
+        }}
+      />
+
+      <ArchiveConfirmDialog
+        open={archiveOpen}
+        onOpenChange={setArchiveOpen}
+        entityName={yacht.name}
+        entityType="Yacht"
+        isArchived={isArchived}
+        onConfirm={() => {
+          archiveMutation.mutate();
+        }}
+        isLoading={archiveMutation.isPending}
+      />
+
+      <YachtTransferDialog
+        open={transferOpen}
+        onOpenChange={setTransferOpen}
+        yachtId={yacht.id}
+        currentOwner={{ type: yacht.currentOwnerType, id: yacht.currentOwnerId }}
+      />
+    </>
+  );
+}

src/components/yachts/yacht-detail.tsx

@@ -0,0 +1,67 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+
+import { DetailLayout } from '@/components/shared/detail-layout';
+import { YachtDetailHeader } from '@/components/yachts/yacht-detail-header';
+import { getYachtTabs } from '@/components/yachts/yacht-tabs';
+import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { apiFetch } from '@/lib/api/client';
+
+export interface YachtData {
+  id: string;
+  portId: string;
+  name: string;
+  hullNumber: string | null;
+  registration: string | null;
+  flag: string | null;
+  yearBuilt: number | null;
+  builder: string | null;
+  model: string | null;
+  hullMaterial: string | null;
+  lengthFt: string | null;
+  widthFt: string | null;
+  draftFt: string | null;
+  lengthM: string | null;
+  widthM: string | null;
+  draftM: string | null;
+  currentOwnerType: 'client' | 'company';
+  currentOwnerId: string;
+  status: string;
+  notes: string | null;
+  archivedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface YachtDetailProps {
+  yachtId: string;
+  currentUserId?: string;
+}
+
+export function YachtDetail({ yachtId, currentUserId }: YachtDetailProps) {
+  const { data, isLoading } = useQuery<YachtData>({
+    queryKey: ['yachts', yachtId],
+    queryFn: () => apiFetch<{ data: YachtData }>(`/api/v1/yachts/${yachtId}`).then((r) => r.data),
+  });
+
+  useRealtimeInvalidation({
+    'yacht:updated': [['yachts', yachtId]],
+    'yacht:archived': [['yachts', yachtId]],
+    'yacht:ownership_transferred': [
+      ['yachts', yachtId],
+      ['yachts', yachtId, 'ownership-history'],
+    ],
+  });
+
+  const tabs = data ? getYachtTabs({ yachtId, currentUserId, yacht: data }) : [];
+
+  return (
+    <DetailLayout
+      header={data ? <YachtDetailHeader yacht={data} /> : null}
+      tabs={tabs}
+      defaultTab="overview"
+      isLoading={isLoading}
+    />
+  );
+}

src/components/yachts/yacht-filters.tsx

@@ -0,0 +1,34 @@
+import type { FilterDefinition } from '@/components/shared/filter-bar';
+
+export const yachtFilterDefinitions: FilterDefinition[] = [
+  {
+    key: 'search',
+    label: 'Search',
+    type: 'text',
+    placeholder: 'Search by name, hull, registration...',
+  },
+  {
+    key: 'status',
+    label: 'Status',
+    type: 'select',
+    options: [
+      { label: 'Active', value: 'active' },
+      { label: 'Retired', value: 'retired' },
+      { label: 'Sold Away', value: 'sold_away' },
+    ],
+  },
+  {
+    key: 'ownerType',
+    label: 'Owner Type',
+    type: 'select',
+    options: [
+      { label: 'Client', value: 'client' },
+      { label: 'Company', value: 'company' },
+    ],
+  },
+  {
+    key: 'includeArchived',
+    label: 'Include Archived',
+    type: 'boolean',
+  },
+];

src/components/yachts/yacht-form.tsx

@@ -0,0 +1,356 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Loader2 } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Textarea } from '@/components/ui/textarea';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter } from '@/components/ui/sheet';
+import { Separator } from '@/components/ui/separator';
+import { OwnerPicker, type OwnerRef } from '@/components/shared/owner-picker';
+import { TagPicker } from '@/components/shared/tag-picker';
+import { apiFetch } from '@/lib/api/client';
+import { createYachtSchema, type CreateYachtInput } from '@/lib/validators/yachts';
+
+interface YachtFormProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** If provided, form is in edit mode */
+  yacht?: {
+    id: string;
+    name: string;
+    hullNumber?: string | null;
+    registration?: string | null;
+    flag?: string | null;
+    yearBuilt?: number | null;
+    builder?: string | null;
+    model?: string | null;
+    hullMaterial?: string | null;
+    lengthFt?: string | null;
+    widthFt?: string | null;
+    draftFt?: string | null;
+    lengthM?: string | null;
+    widthM?: string | null;
+    draftM?: string | null;
+    currentOwnerType: 'client' | 'company';
+    currentOwnerId: string;
+    status?: string | null;
+    notes?: string | null;
+  };
+}
+
+type YachtStatus = 'active' | 'retired' | 'sold_away';
+
+export function YachtForm({ open, onOpenChange, yacht }: YachtFormProps) {
+  const queryClient = useQueryClient();
+  const isEdit = !!yacht;
+  const [formError, setFormError] = useState<string | null>(null);
+
+  const {
+    register,
+    handleSubmit,
+    watch,
+    setValue,
+    reset,
+    formState: { errors, isSubmitting },
+  } = useForm<CreateYachtInput>({
+    resolver: zodResolver(createYachtSchema),
+    defaultValues: {
+      name: '',
+      status: 'active',
+      tagIds: [],
+    },
+  });
+
+  const tagIds = watch('tagIds') ?? [];
+  const owner = watch('owner') as OwnerRef | undefined;
+  const status = watch('status') ?? 'active';
+
+  // Populate form when editing, or reset to defaults in create mode.
+  useEffect(() => {
+    if (yacht && open) {
+      reset({
+        name: yacht.name,
+        hullNumber: yacht.hullNumber ?? undefined,
+        registration: yacht.registration ?? undefined,
+        flag: yacht.flag ?? undefined,
+        yearBuilt: yacht.yearBuilt ?? undefined,
+        builder: yacht.builder ?? undefined,
+        model: yacht.model ?? undefined,
+        hullMaterial: yacht.hullMaterial ?? undefined,
+        lengthFt: yacht.lengthFt ?? undefined,
+        widthFt: yacht.widthFt ?? undefined,
+        draftFt: yacht.draftFt ?? undefined,
+        lengthM: yacht.lengthM ?? undefined,
+        widthM: yacht.widthM ?? undefined,
+        draftM: yacht.draftM ?? undefined,
+        // Owner is required by the schema in create mode. In edit mode we
+        // strip it before PATCH, but we still satisfy the resolver by
+        // supplying the current owner.
+        owner: { type: yacht.currentOwnerType, id: yacht.currentOwnerId },
+        status: (yacht.status as YachtStatus | null) ?? 'active',
+        notes: yacht.notes ?? undefined,
+        tagIds: [],
+      });
+    } else if (!yacht && open) {
+      reset({
+        name: '',
+        status: 'active',
+        tagIds: [],
+      });
+    }
+    setFormError(null);
+  }, [yacht, open, reset]);
+
+  const mutation = useMutation({
+    mutationFn: async (data: CreateYachtInput) => {
+      if (isEdit) {
+        // updateYachtSchema omits owner + tagIds — strip them from PATCH body.
+        const { owner: _owner, tagIds: _tIds, ...rest } = data;
+        void _owner;
+        void _tIds;
+        await apiFetch(`/api/v1/yachts/${yacht!.id}`, {
+          method: 'PATCH',
+          body: rest,
+        });
+      } else {
+        await apiFetch('/api/v1/yachts', { method: 'POST', body: data });
+      }
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['yachts'] });
+      onOpenChange(false);
+    },
+    onError: (err: Error) => {
+      setFormError(err.message || 'Failed to save yacht');
+    },
+  });
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent className="w-full sm:max-w-2xl overflow-y-auto">
+        <SheetHeader>
+          <SheetTitle>{isEdit ? 'Edit Yacht' : 'New Yacht'}</SheetTitle>
+        </SheetHeader>
+
+        <form
+          onSubmit={handleSubmit((data) => {
+            setFormError(null);
+            mutation.mutate(data);
+          })}
+          className="space-y-6 py-6"
+        >
+          {/* Basic */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
+              Basic
+            </h3>
+
+            <div className="grid grid-cols-2 gap-4">
+              <div className="col-span-2 space-y-1">
+                <Label>Name *</Label>
+                <Input {...register('name')} placeholder="Sea Breeze" />
+                {errors.name && <p className="text-xs text-destructive">{errors.name.message}</p>}
+              </div>
+
+              <div className="space-y-1">
+                <Label>Hull Number</Label>
+                <Input {...register('hullNumber')} placeholder="HIN" />
+              </div>
+
+              <div className="space-y-1">
+                <Label>Registration</Label>
+                <Input {...register('registration')} placeholder="Registration #" />
+              </div>
+
+              <div className="space-y-1">
+                <Label>Flag</Label>
+                <Input {...register('flag')} placeholder="e.g. MT" />
+              </div>
+
+              <div className="space-y-1">
+                <Label>Year Built</Label>
+                <Input
+                  type="number"
+                  {...register('yearBuilt', { valueAsNumber: true })}
+                  placeholder="2015"
+                />
+                {errors.yearBuilt && (
+                  <p className="text-xs text-destructive">{errors.yearBuilt.message}</p>
+                )}
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Build */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
+              Build
+            </h3>
+            <div className="grid grid-cols-2 gap-4">
+              <div className="space-y-1">
+                <Label>Builder</Label>
+                <Input {...register('builder')} placeholder="Benetti" />
+              </div>
+              <div className="space-y-1">
+                <Label>Model</Label>
+                <Input {...register('model')} placeholder="Classic 120" />
+              </div>
+              <div className="col-span-2 space-y-1">
+                <Label>Hull Material</Label>
+                <Input {...register('hullMaterial')} placeholder="Aluminium" />
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Dimensions (ft) */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
+              Dimensions (ft)
+            </h3>
+            <div className="grid grid-cols-3 gap-4">
+              <div className="space-y-1">
+                <Label>Length (ft)</Label>
+                <Input {...register('lengthFt')} placeholder="120" />
+              </div>
+              <div className="space-y-1">
+                <Label>Width (ft)</Label>
+                <Input {...register('widthFt')} placeholder="25" />
+              </div>
+              <div className="space-y-1">
+                <Label>Draft (ft)</Label>
+                <Input {...register('draftFt')} placeholder="8" />
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Dimensions (m) */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
+              Dimensions (m)
+            </h3>
+            <div className="grid grid-cols-3 gap-4">
+              <div className="space-y-1">
+                <Label>Length (m)</Label>
+                <Input {...register('lengthM')} placeholder="36.5" />
+              </div>
+              <div className="space-y-1">
+                <Label>Width (m)</Label>
+                <Input {...register('widthM')} placeholder="7.6" />
+              </div>
+              <div className="space-y-1">
+                <Label>Draft (m)</Label>
+                <Input {...register('draftM')} placeholder="2.4" />
+              </div>
+            </div>
+          </div>
+
+          <Separator />
+
+          {/* Ownership */}
+          <div className="space-y-4">
+            <h3 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
+              Ownership
+            </h3>
+
+            {isEdit ? (
+              <p className="rounded-md border bg-muted/30 px-3 py-2 text-xs text-muted-foreground">
+                Ownership changes use the Transfer button.
+              </p>
+            ) : (
+              <div className="space-y-1">
+                <Label>Owner *</Label>
+                <OwnerPicker
+                  value={owner ?? null}
+                  onChange={(v) => {
+                    if (v) {
+                      setValue('owner', v, { shouldValidate: true });
+                    }
+                  }}
+                />
+                {errors.owner && (
+                  <p className="text-xs text-destructive">
+                    {errors.owner.message ?? 'Owner is required'}
+                  </p>
+                )}
+              </div>
+            )}
+          </div>
+
+          <Separator />
+
+          {/* Status */}
+          <div className="space-y-2">
+            <Label>Status</Label>
+            <Select value={status} onValueChange={(v) => setValue('status', v as YachtStatus)}>
+              <SelectTrigger>
+                <SelectValue placeholder="Select status" />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="active">Active</SelectItem>
+                <SelectItem value="retired">Retired</SelectItem>
+                <SelectItem value="sold_away">Sold away</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+
+          <Separator />
+
+          {/* Notes */}
+          <div className="space-y-2">
+            <Label>Notes</Label>
+            <Textarea
+              {...register('notes')}
+              placeholder="Internal notes about this yacht"
+              rows={4}
+            />
+          </div>
+
+          <Separator />
+
+          {/* Tags */}
+          <div className="space-y-2">
+            <Label>Tags</Label>
+            <TagPicker selectedIds={tagIds} onChange={(ids) => setValue('tagIds', ids)} />
+          </div>
+
+          {formError && (
+            <p className="text-sm text-destructive" role="alert">
+              {formError}
+            </p>
+          )}
+
+          <SheetFooter>
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+              Cancel
+            </Button>
+            <Button type="submit" disabled={isSubmitting || mutation.isPending}>
+              {(isSubmitting || mutation.isPending) && (
+                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+              )}
+              {isEdit ? 'Save Changes' : 'Create Yacht'}
+            </Button>
+          </SheetFooter>
+        </form>
+      </SheetContent>
+    </Sheet>
+  );
+}

src/components/yachts/yacht-list.tsx

@@ -0,0 +1,170 @@
+'use client';
+
+import { useState } from 'react';
+import { useParams } from 'next/navigation';
+import { Plus } from 'lucide-react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+import { Button } from '@/components/ui/button';
+import { DataTable } from '@/components/shared/data-table';
+import { FilterBar } from '@/components/shared/filter-bar';
+import { SavedViewsDropdown } from '@/components/shared/saved-views-dropdown';
+import { PageHeader } from '@/components/shared/page-header';
+import { EmptyState } from '@/components/shared/empty-state';
+import { TableSkeleton } from '@/components/shared/loading-skeleton';
+import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
+import { PermissionGate } from '@/components/shared/permission-gate';
+import { YachtForm } from '@/components/yachts/yacht-form';
+import { yachtFilterDefinitions } from '@/components/yachts/yacht-filters';
+import { getYachtColumns, type YachtRow } from '@/components/yachts/yacht-columns';
+import { usePaginatedQuery } from '@/hooks/use-paginated-query';
+import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { apiFetch } from '@/lib/api/client';
+
+export function YachtList() {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+  const queryClient = useQueryClient();
+
+  const [createOpen, setCreateOpen] = useState(false);
+  const [editYacht, setEditYacht] = useState<YachtRow | null>(null);
+  const [archiveYacht, setArchiveYacht] = useState<YachtRow | null>(null);
+
+  const {
+    data,
+    pagination,
+    isLoading,
+    isFetching,
+    sort,
+    setSort,
+    setPage,
+    setPageSize,
+    filters,
+    setFilter,
+    clearFilters,
+  } = usePaginatedQuery<YachtRow>({
+    queryKey: ['yachts'],
+    endpoint: '/api/v1/yachts',
+    filterDefinitions: yachtFilterDefinitions,
+  });
+
+  useRealtimeInvalidation({
+    'yacht:created': [['yachts']],
+    'yacht:updated': [['yachts']],
+    'yacht:archived': [['yachts']],
+    'yacht:ownership_transferred': [['yachts']],
+  });
+
+  const archiveMutation = useMutation({
+    mutationFn: (id: string) => apiFetch(`/api/v1/yachts/${id}`, { method: 'DELETE' }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['yachts'] });
+      setArchiveYacht(null);
+    },
+  });
+
+  const columns = getYachtColumns({
+    portSlug,
+    onEdit: (yacht) => setEditYacht(yacht),
+    onArchive: (yacht) => setArchiveYacht(yacht),
+  });
+
+  return (
+    <div className="space-y-4">
+      <PageHeader
+        title="Yachts"
+        description="Manage yacht records"
+        actions={
+          <PermissionGate resource="yachts" action="create">
+            <Button size="sm" onClick={() => setCreateOpen(true)}>
+              <Plus className="mr-1.5 h-4 w-4" />
+              New Yacht
+            </Button>
+          </PermissionGate>
+        }
+      />
+
+      <div className="flex items-center gap-2">
+        <FilterBar
+          filters={yachtFilterDefinitions}
+          values={filters}
+          onChange={setFilter}
+          onClear={clearFilters}
+        />
+        <SavedViewsDropdown
+          entityType="yachts"
+          currentFilters={filters}
+          currentSort={sort}
+          onApplyView={(savedFilters, _savedSort) => {
+            clearFilters();
+            Object.entries(savedFilters).forEach(([key, val]) => setFilter(key, val));
+          }}
+        />
+      </div>
+
+      {isLoading ? (
+        <TableSkeleton />
+      ) : !data.length ? (
+        <EmptyState
+          title="No yachts found"
+          description="Get started by adding your first yacht."
+          action={{ label: 'New Yacht', onClick: () => setCreateOpen(true) }}
+        />
+      ) : (
+        <DataTable
+          columns={columns}
+          data={data}
+          pagination={pagination}
+          onPaginationChange={(p, ps) => {
+            setPage(p);
+            setPageSize(ps);
+          }}
+          sort={sort}
+          onSortChange={setSort}
+          isLoading={isFetching && !isLoading}
+          getRowId={(row) => row.id}
+          emptyState={
+            <EmptyState
+              title="No yachts found"
+              description="Get started by adding your first yacht."
+              action={{ label: 'New Yacht', onClick: () => setCreateOpen(true) }}
+            />
+          }
+        />
+      )}
+
+      <YachtForm open={createOpen} onOpenChange={setCreateOpen} />
+
+      {editYacht && (
+        <YachtForm
+          open={!!editYacht}
+          onOpenChange={(open) => !open && setEditYacht(null)}
+          yacht={{
+            id: editYacht.id,
+            name: editYacht.name,
+            hullNumber: editYacht.hullNumber,
+            registration: editYacht.registration,
+            lengthFt: editYacht.lengthFt,
+            widthFt: editYacht.widthFt,
+            draftFt: editYacht.draftFt,
+            lengthM: editYacht.lengthM,
+            widthM: editYacht.widthM,
+            currentOwnerType: editYacht.currentOwnerType,
+            currentOwnerId: editYacht.currentOwnerId,
+            status: editYacht.status,
+          }}
+        />
+      )}
+
+      <ArchiveConfirmDialog
+        open={!!archiveYacht}
+        onOpenChange={(open) => !open && setArchiveYacht(null)}
+        entityName={archiveYacht?.name ?? ''}
+        entityType="Yacht"
+        isArchived={false}
+        onConfirm={() => archiveYacht && archiveMutation.mutate(archiveYacht.id)}
+        isLoading={archiveMutation.isPending}
+      />
+    </div>
+  );
+}

src/components/yachts/yacht-ownership-history.tsx

@@ -0,0 +1,123 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import { useParams } from 'next/navigation';
+import { Loader2 } from 'lucide-react';
+
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { Badge } from '@/components/ui/badge';
+import { EmptyState } from '@/components/shared/empty-state';
+import { OwnerLink } from '@/components/yachts/yacht-detail-header';
+import { apiFetch } from '@/lib/api/client';
+
+interface OwnershipHistoryRow {
+  id: string;
+  yachtId: string;
+  ownerType: 'client' | 'company';
+  ownerId: string;
+  startDate: string;
+  endDate: string | null;
+  transferReason: string | null;
+  transferNotes: string | null;
+  createdBy: string;
+  createdAt: string;
+}
+
+interface YachtOwnershipHistoryProps {
+  yachtId: string;
+}
+
+const REASON_LABELS: Record<string, string> = {
+  sale: 'Sale',
+  inheritance: 'Inheritance',
+  gift: 'Gift',
+  company_restructure: 'Company restructure',
+  other: 'Other',
+};
+
+function formatDate(value: string | null): string {
+  if (!value) return '—';
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleDateString();
+}
+
+export function YachtOwnershipHistory({ yachtId }: YachtOwnershipHistoryProps) {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+
+  const { data, isLoading } = useQuery<OwnershipHistoryRow[]>({
+    queryKey: ['yachts', yachtId, 'ownership-history'],
+    queryFn: () =>
+      apiFetch<{ data: OwnershipHistoryRow[] }>(`/api/v1/yachts/${yachtId}/ownership-history`).then(
+        (r) => r.data,
+      ),
+  });
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+      </div>
+    );
+  }
+
+  if (!data || data.length === 0) {
+    return (
+      <EmptyState
+        title="No ownership history"
+        description="This yacht's ownership transfers will appear here."
+      />
+    );
+  }
+
+  return (
+    <div className="rounded-md border">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Start Date</TableHead>
+            <TableHead>End Date</TableHead>
+            <TableHead>Owner</TableHead>
+            <TableHead>Reason</TableHead>
+            <TableHead>Notes</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {data.map((row) => (
+            <TableRow key={row.id}>
+              <TableCell>{formatDate(row.startDate)}</TableCell>
+              <TableCell>
+                {row.endDate ? (
+                  formatDate(row.endDate)
+                ) : (
+                  <Badge variant="secondary" className="text-xs">
+                    Current
+                  </Badge>
+                )}
+              </TableCell>
+              <TableCell>
+                <OwnerLink portSlug={portSlug} type={row.ownerType} id={row.ownerId} />
+              </TableCell>
+              <TableCell className="text-sm text-muted-foreground">
+                {row.transferReason
+                  ? (REASON_LABELS[row.transferReason] ?? row.transferReason)
+                  : '—'}
+              </TableCell>
+              <TableCell className="text-sm text-muted-foreground max-w-[320px] truncate">
+                {row.transferNotes ?? '—'}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}