feat(eoi): align prerequisites with EOI document structure

Match the gate to the actual EOI's structure (Section 2 vs Section 3) so
the rep can generate the document the moment they have what they need —
and not before.

  Required (Section 2 — top paragraph):
    - Client name
    - Client primary email
    - Client primary address

  Optional (Section 3 — left blank when absent):
    - Linked yacht (name, dimensions)
    - Linked berth (mooring number)

Previously the dialog blocked generation unless yacht AND berth were both
linked, which was overzealous — early-stage EOIs are routinely sent before
a specific berth is pinned down.

  - eoi-context.ts: yacht and berth are now nullable in the returned
    context. The hard ValidationError is now driven by the EOI's Section
    2 fields (name/email/address) rather than yacht/berth presence. The
    owner block falls back to the interest's client when no yacht is
    linked, so signing parties remain resolvable.

  - documenso-payload.ts + fill-eoi-form.ts: Section 3 form values
    render as empty strings when yacht or berth are absent, so the
    rendered PDF leaves those template inputs blank.

  - document-templates.ts: yacht.* and berth.* tokens fall back to
    empty strings; the legacy-fallback catch handler also recognises
    the new "missing required client details" error.

  - interests.service.ts: getInterestById now also returns
    `clientPrimaryEmail` and `clientHasAddress` so the Documents tab
    can compute the EOI prerequisites checklist client-side without an
    extra fetch.

  - eoi-generate-dialog.tsx: prereqs split into two groups visually —
    Required (with red ✗ when missing) and Optional (with grey – when
    absent). The Generate button only requires the Required block to
    pass. A small amber banner surfaces when Required is incomplete so
    the rep knows where to add the missing data.

Tests: 835/835 pass. Replaces the obsolete "throws on missing yacht/
berth" tests with parity coverage for the new behaviour ("builds a
valid context when yacht/berth missing", "throws when client email/
address missing"). Adds a payload test for the empty-Section-3 case.

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

src/lib/pdf/fill-eoi-form.ts

@@ -80,11 +80,13 @@ export async function fillEoiFormFields(
   setText(form, 'Name', context.client.fullName);
   setText(form, 'Email', context.client.primaryEmail ?? '');
   setText(form, 'Address', formatAddress(context.client.address));
-  setText(form, 'Yacht Name', context.yacht.name);
-  setText(form, 'Length', context.yacht.lengthFt ?? '');
-  setText(form, 'Width', context.yacht.widthFt ?? '');
-  setText(form, 'Draft', context.yacht.draftFt ?? '');
-  setText(form, 'Berth Number', context.berth.mooringNumber);
+  // Yacht + berth (EOI Section 3) are optional — leave the AcroForm fields
+  // blank when the interest hasn't been linked to either.
+  setText(form, 'Yacht Name', context.yacht?.name ?? '');
+  setText(form, 'Length', context.yacht?.lengthFt ?? '');
+  setText(form, 'Width', context.yacht?.widthFt ?? '');
+  setText(form, 'Draft', context.yacht?.draftFt ?? '');
+  setText(form, 'Berth Number', context.berth?.mooringNumber ?? '');
 
   setCheckbox(form, 'Purchase', true);
   setCheckbox(form, 'Lease_10', false);

src/lib/services/documenso-payload.ts

@@ -128,11 +128,13 @@ export function buildDocumensoPayload(
       Name: context.client.fullName,
       Email: context.client.primaryEmail ?? '',
       Address: formatAddress(context.client.address),
-      'Yacht Name': context.yacht.name,
-      Length: context.yacht.lengthFt ?? '',
-      Width: context.yacht.widthFt ?? '',
-      Draft: context.yacht.draftFt ?? '',
-      'Berth Number': context.berth.mooringNumber,
+      // Yacht + berth are optional EOI fields; when not linked, render as
+      // empty strings so the corresponding template inputs stay blank.
+      'Yacht Name': context.yacht?.name ?? '',
+      Length: context.yacht?.lengthFt ?? '',
+      Width: context.yacht?.widthFt ?? '',
+      Draft: context.yacht?.draftFt ?? '',
+      'Berth Number': context.berth?.mooringNumber ?? '',
       Lease_10: false,
       Purchase: true,
     },

src/lib/services/document-templates.ts

@@ -237,18 +237,20 @@ export async function resolveTemplate(
       tokenMap['{{client.phone}}'] = eoi.client.primaryPhone ?? '';
       tokenMap['{{client.nationality}}'] = eoi.client.nationality ?? '';
 
-      // Yacht tokens
-      tokenMap['{{yacht.name}}'] = eoi.yacht.name;
-      tokenMap['{{yacht.hullNumber}}'] = eoi.yacht.hullNumber ?? '';
-      tokenMap['{{yacht.flag}}'] = eoi.yacht.flag ?? '';
+      // Yacht tokens — `eoi.yacht` is null when no yacht is linked
+      // (Section 3 of the EOI is optional). Tokens render as empty strings
+      // in that case so the template still produces output.
+      tokenMap['{{yacht.name}}'] = eoi.yacht?.name ?? '';
+      tokenMap['{{yacht.hullNumber}}'] = eoi.yacht?.hullNumber ?? '';
+      tokenMap['{{yacht.flag}}'] = eoi.yacht?.flag ?? '';
       tokenMap['{{yacht.yearBuilt}}'] =
-        eoi.yacht.yearBuilt != null ? String(eoi.yacht.yearBuilt) : '';
-      tokenMap['{{yacht.lengthFt}}'] = eoi.yacht.lengthFt ?? '';
-      tokenMap['{{yacht.widthFt}}'] = eoi.yacht.widthFt ?? '';
-      tokenMap['{{yacht.draftFt}}'] = eoi.yacht.draftFt ?? '';
-      tokenMap['{{yacht.lengthM}}'] = eoi.yacht.lengthM ?? '';
-      tokenMap['{{yacht.widthM}}'] = eoi.yacht.widthM ?? '';
-      tokenMap['{{yacht.draftM}}'] = eoi.yacht.draftM ?? '';
+        eoi.yacht?.yearBuilt != null ? String(eoi.yacht.yearBuilt) : '';
+      tokenMap['{{yacht.lengthFt}}'] = eoi.yacht?.lengthFt ?? '';
+      tokenMap['{{yacht.widthFt}}'] = eoi.yacht?.widthFt ?? '';
+      tokenMap['{{yacht.draftFt}}'] = eoi.yacht?.draftFt ?? '';
+      tokenMap['{{yacht.lengthM}}'] = eoi.yacht?.lengthM ?? '';
+      tokenMap['{{yacht.widthM}}'] = eoi.yacht?.widthM ?? '';
+      tokenMap['{{yacht.draftM}}'] = eoi.yacht?.draftM ?? '';
 
       // EoiContext doesn't expose the yacht.registration column — look it up
       // separately (cheap, indexed fetch) so the token resolves when present.
@@ -281,29 +283,31 @@ export async function resolveTemplate(
       tokenMap['{{owner.name}}'] = eoi.owner.name;
       tokenMap['{{owner.legalName}}'] = eoi.owner.legalName ?? '';
 
-      // Berth tokens (from EoiContext)
-      tokenMap['{{berth.mooringNumber}}'] = eoi.berth.mooringNumber;
-      tokenMap['{{berth.area}}'] = eoi.berth.area ?? '';
-      tokenMap['{{berth.lengthFt}}'] = eoi.berth.lengthFt ?? '';
-      tokenMap['{{berth.price}}'] = eoi.berth.price ?? '';
-      tokenMap['{{berth.priceCurrency}}'] = eoi.berth.priceCurrency;
-      tokenMap['{{berth.tenureType}}'] = eoi.berth.tenureType;
+      // Berth tokens — also optional. Render empty when no berth is linked.
+      tokenMap['{{berth.mooringNumber}}'] = eoi.berth?.mooringNumber ?? '';
+      tokenMap['{{berth.area}}'] = eoi.berth?.area ?? '';
+      tokenMap['{{berth.lengthFt}}'] = eoi.berth?.lengthFt ?? '';
+      tokenMap['{{berth.price}}'] = eoi.berth?.price ?? '';
+      tokenMap['{{berth.priceCurrency}}'] = eoi.berth?.priceCurrency ?? '';
+      tokenMap['{{berth.tenureType}}'] = eoi.berth?.tenureType ?? '';
 
       // Interest tokens
       tokenMap['{{interest.stage}}'] = eoi.interest.stage;
       tokenMap['{{interest.leadCategory}}'] = eoi.interest.leadCategory ?? '';
-      tokenMap['{{interest.berthNumber}}'] = eoi.berth.mooringNumber;
+      tokenMap['{{interest.berthNumber}}'] = eoi.berth?.mooringNumber ?? '';
       tokenMap['{{interest.dateFirstContact}}'] = eoi.interest.dateFirstContact
         ? eoi.interest.dateFirstContact.toLocaleDateString('en-GB')
         : '';
       tokenMap['{{interest.notes}}'] = eoi.interest.notes ?? '';
     } catch (err) {
-      // buildEoiContext throws ValidationError when the interest has no yacht
-      // or berth; non-EOI templates don't need those. Fall through to the
-      // legacy resolution path below. Re-throw anything else.
+      // buildEoiContext throws ValidationError when the EOI's required client
+      // fields (name/email/address — Section 2) are missing. For non-EOI
+      // templates (correspondence, welcome letters, etc.) those gates don't
+      // apply — fall through to the legacy resolution path below. Re-throw
+      // anything else.
       if (
         !(err instanceof ValidationError) ||
-        !/interest has no (yacht|berth)/i.test(err.message)
+        !/missing required client details|interest has no (yacht|berth)/i.test(err.message)
       ) {
         throw err;
       }

src/lib/services/eoi-context.ts

@@ -20,6 +20,7 @@ export type EoiContext = {
     primaryPhone: string | null;
     address: { street: string; city: string; country: string } | null;
   };
+  /** Optional. The EOI's Section 3 yacht block is left blank when null. */
   yacht: {
     name: string;
     lengthFt: string | null;
@@ -31,18 +32,22 @@ export type EoiContext = {
     hullNumber: string | null;
     flag: string | null;
     yearBuilt: number | null;
-  };
+  } | null;
   company: {
     name: string;
     legalName: string | null;
     taxId: string | null;
     billingAddress: string | null;
   } | null;
+  /** Inferred from the yacht's polymorphic owner. Falls back to the interest's
+   *  client when no yacht is linked (so the EOI's signing party is still
+   *  resolvable). */
   owner: {
     type: 'client' | 'company';
     name: string;
     legalName?: string;
   };
+  /** Optional. The EOI's Section 3 berth-number is left blank when null. */
   berth: {
     mooringNumber: string;
     area: string | null;
@@ -50,7 +55,7 @@ export type EoiContext = {
     price: string | null;
     priceCurrency: string;
     tenureType: string;
-  };
+  } | null;
   interest: {
     stage: string;
     leadCategory: string | null;
@@ -77,8 +82,10 @@ export type EoiContext = {
  * Pure read-only: no audit logs, no socket emits, no mutations.
  *
  * Tenant-scoped: every fetch is gated by `portId`, and missing rows surface
- * as NotFoundError. Missing yacht/berth references on the interest surface as
- * ValidationError, because EOI flows cannot proceed without them.
+ * as NotFoundError. The hard gate matches the EOI document's top paragraph
+ * (Section 2 — name, address, email): without those the EOI is unsignable
+ * and we throw. Yacht and berth (Section 3) are optional — the rendered PDF
+ * leaves those fields blank when not set.
  */
 export async function buildEoiContext(interestId: string, portId: string): Promise<EoiContext> {
   // 1. Interest (tenant-scoped)
@@ -89,24 +96,19 @@ export async function buildEoiContext(interestId: string, portId: string): Promi
     throw new NotFoundError('Interest');
   }
 
-  // 2. Yacht reference must exist on the interest
-  if (!interest.yachtId) {
-    throw new ValidationError('interest has no yacht');
-  }
-
-  // 3. Berth reference must exist on the interest
-  if (!interest.berthId) {
-    throw new ValidationError('interest has no berth');
-  }
-
-  // 2 + 3 + 4 + 9: parallelise independent reads.
+  // Parallelise independent reads. Yacht and berth are both nullable —
+  // the EOI's Section 3 stays blank when they're absent.
   const [yacht, berth, client, port] = await Promise.all([
-    db.query.yachts.findFirst({
-      where: and(eq(yachts.id, interest.yachtId), eq(yachts.portId, portId)),
-    }),
-    db.query.berths.findFirst({
-      where: and(eq(berths.id, interest.berthId), eq(berths.portId, portId)),
-    }),
+    interest.yachtId
+      ? db.query.yachts.findFirst({
+          where: and(eq(yachts.id, interest.yachtId), eq(yachts.portId, portId)),
+        })
+      : Promise.resolve(undefined),
+    interest.berthId
+      ? db.query.berths.findFirst({
+          where: and(eq(berths.id, interest.berthId), eq(berths.portId, portId)),
+        })
+      : Promise.resolve(undefined),
     db.query.clients.findFirst({
       where: and(eq(clients.id, interest.clientId), eq(clients.portId, portId)),
     }),
@@ -115,8 +117,6 @@ export async function buildEoiContext(interestId: string, portId: string): Promi
     }),
   ]);
 
-  if (!yacht) throw new NotFoundError('Yacht');
-  if (!berth) throw new NotFoundError('Berth');
   if (!client) throw new NotFoundError('Client');
   if (!port) throw new NotFoundError('Port');
 
@@ -157,11 +157,28 @@ export async function buildEoiContext(interestId: string, portId: string): Promi
       }
     : null;
 
-  // 7 + 8. Yacht owner (polymorphic) + optional company billing address.
+  // EOI hard gate: the document's top paragraph (Section 2) requires Name,
+  // Address, and Email. Without these the rendered EOI is unsignable. Yacht
+  // and berth (Section 3) are intentionally optional and may be left blank.
+  const missing: string[] = [];
+  if (!client.fullName?.trim()) missing.push('client name');
+  if (!firstEmail?.value?.trim()) missing.push('client email');
+  if (!clientAddress || !clientAddress.street.trim()) missing.push('client address');
+  if (missing.length > 0) {
+    throw new ValidationError(
+      `Cannot generate EOI — missing required client details: ${missing.join(', ')}.`,
+    );
+  }
+
+  // Owner block. When a yacht is linked, derive from the yacht's polymorphic
+  // owner. When no yacht is linked, fall back to the interest's client so the
+  // EOI's signing party is still resolvable.
   let ownerBlock: EoiContext['owner'];
   let companyBlock: EoiContext['company'] = null;
 
-  if (yacht.currentOwnerType === 'client') {
+  if (!yacht) {
+    ownerBlock = { type: 'client', name: client.fullName };
+  } else if (yacht.currentOwnerType === 'client') {
     // The yacht-owning client may or may not be the same as the interest's client.
     const ownerClient =
       yacht.currentOwnerId === client.id
@@ -228,28 +245,32 @@ export async function buildEoiContext(interestId: string, portId: string): Promi
       primaryPhone: firstPhone?.value ?? null,
       address: clientAddress,
     },
-    yacht: {
-      name: yacht.name,
-      lengthFt: yacht.lengthFt,
-      widthFt: yacht.widthFt,
-      draftFt: yacht.draftFt,
-      lengthM: yacht.lengthM,
-      widthM: yacht.widthM,
-      draftM: yacht.draftM,
-      hullNumber: yacht.hullNumber,
-      flag: yacht.flag,
-      yearBuilt: yacht.yearBuilt,
-    },
+    yacht: yacht
+      ? {
+          name: yacht.name,
+          lengthFt: yacht.lengthFt,
+          widthFt: yacht.widthFt,
+          draftFt: yacht.draftFt,
+          lengthM: yacht.lengthM,
+          widthM: yacht.widthM,
+          draftM: yacht.draftM,
+          hullNumber: yacht.hullNumber,
+          flag: yacht.flag,
+          yearBuilt: yacht.yearBuilt,
+        }
+      : null,
     company: companyBlock,
     owner: ownerBlock,
-    berth: {
-      mooringNumber: berth.mooringNumber,
-      area: berth.area,
-      lengthFt: berth.lengthFt,
-      price: berth.price,
-      priceCurrency: berth.priceCurrency,
-      tenureType: berth.tenureType,
-    },
+    berth: berth
+      ? {
+          mooringNumber: berth.mooringNumber,
+          area: berth.area,
+          lengthFt: berth.lengthFt,
+          price: berth.price,
+          priceCurrency: berth.priceCurrency,
+          tenureType: berth.tenureType,
+        }
+      : null,
     interest: {
       stage: interest.pipelineStage,
       leadCategory: interest.leadCategory,

src/lib/services/interests.service.ts

@@ -1,8 +1,8 @@
-import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
+import { and, desc, eq, inArray, isNull, sql } from 'drizzle-orm';
 
 import { db } from '@/lib/db';
 import { interests, interestTags } from '@/lib/db/schema/interests';
-import { clients } from '@/lib/db/schema/clients';
+import { clients, clientAddresses, clientContacts } from '@/lib/db/schema/clients';
 import { berths } from '@/lib/db/schema/berths';
 import { yachts } from '@/lib/db/schema/yachts';
 import { companyMemberships } from '@/lib/db/schema/companies';
@@ -282,6 +282,24 @@ export async function getInterestById(id: string, portId: string) {
     .from(clients)
     .where(eq(clients.id, interest.clientId));
 
+  // EOI prerequisites: surface enough of the linked client's primary contact
+  // and address so the Documents tab can show the readiness checklist
+  // (Required: name, email, address — Section 2 of the EOI document).
+  const [emailContact] = await db
+    .select({ value: clientContacts.value })
+    .from(clientContacts)
+    .where(and(eq(clientContacts.clientId, interest.clientId), eq(clientContacts.channel, 'email')))
+    .orderBy(desc(clientContacts.isPrimary), desc(clientContacts.updatedAt))
+    .limit(1);
+
+  const [addressRow] = await db
+    .select({ id: clientAddresses.id })
+    .from(clientAddresses)
+    .where(
+      and(eq(clientAddresses.clientId, interest.clientId), eq(clientAddresses.isPrimary, true)),
+    )
+    .limit(1);
+
   let berthMooringNumber: string | null = null;
   if (interest.berthId) {
     const [berthRow] = await db
@@ -300,6 +318,8 @@ export async function getInterestById(id: string, portId: string) {
   return {
     ...interest,
     clientName: clientRow?.fullName ?? null,
+    clientPrimaryEmail: emailContact?.value ?? null,
+    clientHasAddress: !!addressRow,
     berthMooringNumber,
     tags: tagRows,
   };