fix(audit): comprehensive 2026-05-15 audit fix wave + Documenso v2 polish

Bundles the prior session's 50-task fix sweep (Documenso v2 + EOI/signing-
progress redesign + env-to-admin migration + dev-mode banner) with the
2026-05-18 audit fix wave (3 CRITICAL, 14 HIGH, 28 MEDIUM, 6 LOW).

CRITICAL (3):
 - C-01 interest-berths INNER JOIN -> LEFT JOIN so hard-deleted berths
   no longer silently drop interest links
 - C-02 /setup added to PUBLIC_PATHS; fresh-deploy bootstrap loop fixed
 - C-03 generic PATCH /interests/[id] no longer accepts pipelineStage —
   callers must go through /stage with the override-guard chain

HIGH (14/15):
 - H-01 explicit ON DELETE on previously-implicit NO ACTION FKs across
   interests/documents/reservations/reminders/invoices (migration 0070)
 - H-02 login page reads ?redirect= param with same-origin guard
 - H-03 CRM invite token moves to URL fragment so it never lands in
   nginx access logs / Referer headers
 - H-04 Retry-After header on sign-in-by-identifier 429 (RFC 6585 §4)
 - H-05 toggleAccount writes an audit row
 - H-06 upsertSetting masks any value whose key ends with _encrypted
 - H-07 archiveClient cascade fires per-interest audit rows
 - H-08 createSalesTransporter applies SMTP_TIMEOUTS
 - H-09 AppShell stable children — viewport flip across breakpoint no
   longer destroys in-progress form drafts
 - H-10 portal documents page swaps Unicode glyph status icons for
   Lucide CheckCircle2/XCircle/Circle + aria-labels
 - H-12 list components swap alert(...) for toast.warning(...)
 - H-13 5 icon-only buttons gain aria-label
 - H-14 parseBody treats empty bodies as {}
 - H-15 admin layout renders a 403 panel instead of silent bounce
 - H-11 not applicable — mobile-search-overlay IS a mobile bottom-sheet

MEDIUM (28+):
 - M-MT01-05 defense-in-depth port_id/parent-id filters on UPDATE/DELETE
   WHEREs across custom-fields, notes (all 6 entity types x update +
   delete), client-contacts, yacht ownerClient lookup, webhook reads
 - M-D01 documents-hub realtime event-name typo (file:created -> uploaded)
 - M-EM01 portal-auth emails thread through portId
 - M-EM02 sendEmail accepts cc/bcc params
 - M-EM04 notification_digest catalog key
 - M-IN01 portal presigned download URLs use 4h TTL
 - M-IN02 OpenAI client lazy-instantiated
 - M-IN04 stale pdfme refs updated to pdf-lib AcroForm
 - M-IN05 umami.testConnection returns tagged union
 - M-L01 reservations tenure_type unified with berths
 - M-L02 report-generators canonicalize stage values
 - M-AU01 audit log placeholder copy fixed
 - M-AU04 outcome_set / outcome_cleared distinct audit verbs
 - M-NEW-2 activity feed entity name+type separator
 - M-R01 portal allowlist narrowed + portal_session backstop in proxy
 - M-SC02 companies archived partial index
 - M-SC04 audit_logs.searchText documented as DB-managed
 - M-S01 storage_s3_access_key_encrypted admin field
 - M-U01 audit log empty state uses <EmptyState>
 - M-U09 invoice delete dialog -> <AlertDialog>
 - M-U10 toast.success on ClientForm + InterestForm create/edit
 - M-U11 settings-form-card logo preview alt text
 - M-U14 mobile topbar title on clients/yachts/interests/berths
 - M-U15 Invoices in mobile More-sheet

LOW (6/8):
 - L-AU01 severity defaults for security-relevant verbs
 - L-AU02 +13 missing actions in admin audit filter
 - L-AU03 +7 missing entity types in admin audit filter
 - L-AU04 dead listAuditLogs stubbed
 - L-D02 CLAUDE.md Owner-wins chain tightened

Bonus — Document detail polish (#67 partial, 3/6 deliverables):
 - state-aware action button per signer
 - watcher Add UI with display-name resolution
 - cleanSignerName cleanup

Prior session work bundled in:
 - Documenso v2 webhook + envelope-ID normalization + sequential signing
 - SigningProgress UI redesign (avatars, per-signer state, timestamps)
 - env->admin settings registry + RegistryDrivenForm + encrypted creds
 - Embedded-signing card + Test connection + setup help
 - Dev-mode EMAIL_REDIRECT_TO banner
 - Pipeline rules admin page
 - Sales email config card
 - Audit log details Sheet
 - EOI tab: Finalising badge, absolute timestamps, sequential indicator
 - Notes pipeline_stage_at_creation (migration 0069)
 - Documenso numeric ID dual-key webhook (migration 0068)
 - Dimensions criterion copy (migration 0067)

Tests: 1374/1374 vitest pass. tsc clean. lint clean.

See docs/AUDIT-FIX-WAVE-2026-05-18.md for the full progress report and
the user-input items still pending.

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

src/lib/services/interests.service.ts

@@ -479,14 +479,18 @@ export async function getInterestById(id: string, portId: string) {
   // wa.me) so the header can render Email / Call / WhatsApp buttons without
   // a second fetch, and the Documents tab can show the EOI prereq checklist.
   const [emailContact] = await db
-    .select({ value: clientContacts.value })
+    .select({ id: clientContacts.id, 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 [phoneContact] = await db
-    .select({ value: clientContacts.value, valueE164: clientContacts.valueE164 })
+    .select({
+      id: clientContacts.id,
+      value: clientContacts.value,
+      valueE164: clientContacts.valueE164,
+    })
     .from(clientContacts)
     .where(
       and(
@@ -528,14 +532,18 @@ export async function getInterestById(id: string, portId: string) {
   // Most-recent note preview for the Overview tab (the "do you have anything
   // outstanding on this lead?" peek). Returns the latest note's truncated
   // content + author/timestamp so the UI can render a one-line teaser.
+  // Left-joins userProfiles so the teaser can show the author's display name
+  // instead of leaking the raw user-id UUID.
   const [recentNote] = await db
     .select({
       id: interestNotes.id,
       content: interestNotes.content,
       authorId: interestNotes.authorId,
+      authorName: userProfiles.displayName,
       createdAt: interestNotes.createdAt,
     })
     .from(interestNotes)
+    .leftJoin(userProfiles, eq(userProfiles.userId, interestNotes.authorId))
     .where(eq(interestNotes.interestId, id))
     .orderBy(desc(interestNotes.createdAt))
     .limit(1);
@@ -580,7 +588,11 @@ export async function getInterestById(id: string, portId: string) {
     ...interest,
     clientName: clientRow?.fullName ?? null,
     clientPrimaryEmail: emailContact?.value ?? null,
+    /** Contact-row id for the primary email — surfaces so the interest UI
+     *  can inline-edit through PATCH /api/v1/clients/[id]/contacts/[contactId]. */
+    clientPrimaryEmailContactId: emailContact?.id ?? null,
     clientPrimaryPhone: phoneContact?.value ?? null,
+    clientPrimaryPhoneContactId: phoneContact?.id ?? null,
     clientPrimaryPhoneE164: phoneContact?.valueE164 ?? null,
     clientHasAddress: !!addressRow,
     berthId,
@@ -1010,6 +1022,68 @@ export async function advanceStageIfBehind(
   return true;
 }
 
+/**
+ * Gated variant: reads the per-port `stage_advance_rules` setting for the
+ * given trigger and either:
+ *   - 'auto' → calls advanceStageIfBehind (same behaviour as the base helper)
+ *   - 'suggest' → emits an in-CRM notification with an Approve link so the
+ *     rep can advance with one click (no auto-move)
+ *   - 'off' → no-op (audit log of the event still fires upstream)
+ *
+ * Use this from every lifecycle event handler that wants admin-controlled
+ * cadence — the bare `advanceStageIfBehind` stays available for paths
+ * where the move is unconditional (manual rep action, completion of a
+ * doc the admin can't disable).
+ */
+export async function advanceStageIfBehindGated(
+  interestId: string,
+  portId: string,
+  target: PipelineStage,
+  meta: AuditMeta,
+  reason: string | undefined,
+  trigger:
+    | 'eoi_sent'
+    | 'eoi_signed'
+    | 'reservation_signed'
+    | 'deposit_received'
+    | 'contract_signed',
+): Promise<boolean> {
+  const { getStageAdvanceMode } = await import('@/lib/services/port-config');
+  const mode = await getStageAdvanceMode(portId, trigger);
+  if (mode === 'off') return false;
+  if (mode === 'auto') return advanceStageIfBehind(interestId, portId, target, meta, reason);
+  // 'suggest' — notify the rep with an Approve link, no auto-move. The
+  // rep can click the notification to fire the same advance manually.
+  const existing = await db.query.interests.findFirst({
+    where: and(eq(interests.id, interestId), eq(interests.portId, portId)),
+    columns: { pipelineStage: true, assignedTo: true },
+  });
+  if (!existing) return false;
+  const currentIdx = PIPELINE_STAGES.indexOf(existing.pipelineStage as PipelineStage);
+  const targetIdx = PIPELINE_STAGES.indexOf(target);
+  if (currentIdx === -1 || targetIdx === -1 || currentIdx >= targetIdx) return false;
+  if (existing.assignedTo) {
+    void import('@/lib/services/notifications.service').then(({ createNotification }) =>
+      createNotification({
+        portId,
+        userId: existing.assignedTo!,
+        type: 'stage_advance_suggested',
+        title: `Advance to ${target}?`,
+        description:
+          reason ??
+          `${trigger} fired — suggested advance from ${existing.pipelineStage} to ${target}.`,
+        link: `/interests/${interestId}`,
+        entityType: 'interest',
+        entityId: interestId,
+        dedupeKey: `interest:${interestId}:advance-suggest:${trigger}`,
+      }).catch(() => {
+        // Notification failure shouldn't block the parent webhook handler.
+      }),
+    );
+  }
+  return false;
+}
+
 // ─── Set Outcome (Won / Lost) ────────────────────────────────────────────────
 //
 // Records a terminal outcome for the interest. The `outcome` column is the
@@ -1047,12 +1121,13 @@ export async function setInterestOutcome(
   void createAuditLog({
     userId: meta.userId,
     portId,
-    action: 'update',
+    // M-AU04: distinct verb so the audit filter / FTS surface it directly.
+    action: 'outcome_set',
     entityType: 'interest',
     entityId: id,
     oldValue: { outcome: oldOutcome, pipelineStage: stageAtOutcome },
     newValue: { outcome: data.outcome, pipelineStage: stageAtOutcome, reason: data.reason },
-    metadata: { type: 'outcome_set', stageAtOutcome },
+    metadata: { stageAtOutcome },
     ipAddress: meta.ipAddress,
     userAgent: meta.userAgent,
   });
@@ -1115,12 +1190,12 @@ export async function clearInterestOutcome(
   void createAuditLog({
     userId: meta.userId,
     portId,
-    action: 'update',
+    // M-AU04: distinct verb so the audit filter / FTS surface it directly.
+    action: 'outcome_cleared',
     entityType: 'interest',
     entityId: id,
     oldValue: { outcome: existing.outcome, pipelineStage: existing.pipelineStage },
     newValue: { outcome: null, pipelineStage: reopenStage },
-    metadata: { type: 'outcome_cleared' },
     ipAddress: meta.ipAddress,
     userAgent: meta.userAgent,
   });