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/port-config.ts

@@ -105,14 +105,103 @@ export const SETTING_KEYS = {
 
   // Berths
   berthsDefaultCurrency: 'berths_default_currency',
+
+  // Pipeline auto-advance — per-trigger mode (auto | suggest | off).
+  // Stored as a single JSON blob keyed by trigger name so the admin UI
+  // edits/saves the full map atomically. Defaults applied in
+  // `getStageAdvanceMode` — aggressive defaults match the conventional
+  // CRM behaviour (EOI signed → reservation auto-advances).
+  stageAdvanceRules: 'stage_advance_rules',
 } as const;
 
+// ─── Stage auto-advance ──────────────────────────────────────────────────────
+
+export type StageAdvanceMode = 'auto' | 'suggest' | 'off';
+
+/**
+ * Stage transitions that callers can gate through the admin's
+ * `stage_advance_rules` setting. Keys are the trigger names already
+ * used by the rules engine (`berth-rules-engine.ts`) — keeping them in
+ * sync lets a single admin toggle drive both side-effects (berth status)
+ * and stage moves.
+ */
+export type StageAdvanceTrigger =
+  | 'eoi_sent'
+  | 'eoi_signed'
+  | 'reservation_signed'
+  | 'deposit_received'
+  | 'contract_signed';
+
+const STAGE_ADVANCE_DEFAULTS: Record<StageAdvanceTrigger, StageAdvanceMode> = {
+  // Sending the EOI is the moment the deal formally enters the document-
+  // signing pursuit phase — auto-advance so the kanban tracks reality
+  // without a rep having to click.
+  eoi_sent: 'auto',
+  // EOI signed = formal commitment to proceed → advance to reservation.
+  eoi_signed: 'auto',
+  // Reservation signed = the deal is now under contract pursuit.
+  reservation_signed: 'auto',
+  // Deposit received = monies in, deal is committed; the next milestone
+  // is contract sign-off.
+  deposit_received: 'auto',
+  contract_signed: 'auto',
+};
+
+/**
+ * Resolve the auto-advance mode for a single trigger on a port.
+ * Reads `stage_advance_rules` (a JSON object keyed by trigger name) and
+ * falls back to the platform default when the port hasn't overridden.
+ */
+export async function getStageAdvanceMode(
+  portId: string,
+  trigger: StageAdvanceTrigger,
+): Promise<StageAdvanceMode> {
+  const raw = await readSetting<Record<string, StageAdvanceMode>>(
+    SETTING_KEYS.stageAdvanceRules,
+    portId,
+  );
+  const mode = raw?.[trigger];
+  if (mode === 'auto' || mode === 'suggest' || mode === 'off') return mode;
+  return STAGE_ADVANCE_DEFAULTS[trigger];
+}
+
+export function getStageAdvanceDefaults(): Record<StageAdvanceTrigger, StageAdvanceMode> {
+  return { ...STAGE_ADVANCE_DEFAULTS };
+}
+
 // ─── Helper ──────────────────────────────────────────────────────────────────
 
-async function readSetting<T>(key: string, portId: string): Promise<T | null> {
+/**
+ * Resolves a port-scoped setting through the registry-aware resolver, which
+ * applies the port → global → env → registry-default chain and decrypts
+ * encrypted entries transparently. The legacy `{ value: <T> }` wrapper from
+ * `settings.service.upsertSetting` is unwrapped inside the resolver, so this
+ * helper still returns the bare `T | null` shape its callers expect.
+ *
+ * If the key isn't registered yet (legacy bespoke settings not in the
+ * registry), we fall back to the older `settings.service.getSetting()` path
+ * for backward compatibility.
+ */
+export async function readSetting<T>(key: string, portId: string): Promise<T | null> {
+  const { registryFor } = await import('@/lib/settings/registry');
+  if (registryFor(key)) {
+    const { getSetting: getSettingFromRegistry } = await import('@/lib/settings/resolver');
+    return (await getSettingFromRegistry<T>(key, portId)) ?? null;
+  }
   const setting = await getSetting(key, portId);
   if (!setting) return null;
-  return setting.value as T;
+  // Legacy upsertSetting wrote the value as the JSONB column directly (not
+  // wrapped). Newer paths wrap it as `{ value }`. Tolerate both.
+  const raw = setting.value as unknown;
+  if (
+    raw &&
+    typeof raw === 'object' &&
+    'value' in (raw as Record<string, unknown>) &&
+    Object.keys(raw as object).length === 1
+  ) {
+    return (raw as { value: T }).value;
+  }
+  return raw as T;
 }
 
 // ─── Email ──────────────────────────────────────────────────────────────────
@@ -171,8 +260,8 @@ export async function getPortEmailConfig(portId: string): Promise<PortEmailConfi
     fromName: fromName ?? envFromName,
     fromAddress: fromAddress ?? envFromAddress,
     replyTo: replyTo ?? null,
-    smtpHost: smtpHost ?? env.SMTP_HOST,
-    smtpPort: smtpPort ?? env.SMTP_PORT,
+    smtpHost: smtpHost ?? env.SMTP_HOST ?? '',
+    smtpPort: smtpPort ?? env.SMTP_PORT ?? 587,
     smtpUser: smtpUser ?? env.SMTP_USER ?? null,
     smtpPass: smtpPass ?? env.SMTP_PASS ?? null,
     allowPersonalAccountSends: allowPersonalAccountSends ?? false,
@@ -302,13 +391,18 @@ export async function getPortDocumensoConfig(portId: string): Promise<PortDocume
   ]);
 
   return {
-    apiUrl: apiUrl ?? env.DOCUMENSO_API_URL,
-    apiKey: apiKey ?? env.DOCUMENSO_API_KEY,
+    // Env values are now optional (admin is canonical). Empty / zero
+    // defaults let consumers proceed and fail at the actual API call with
+    // a clearer "not configured" error rather than crashing at type-check.
+    apiUrl: apiUrl ?? env.DOCUMENSO_API_URL ?? '',
+    apiKey: apiKey ?? env.DOCUMENSO_API_KEY ?? '',
     apiVersion: apiVersion ?? env.DOCUMENSO_API_VERSION,
-    eoiTemplateId: toIntOrNull(eoiTemplateId) ?? env.DOCUMENSO_TEMPLATE_ID_EOI,
-    clientRecipientId: toIntOrNull(clientRecipientId) ?? env.DOCUMENSO_CLIENT_RECIPIENT_ID,
-    developerRecipientId: toIntOrNull(developerRecipientId) ?? env.DOCUMENSO_DEVELOPER_RECIPIENT_ID,
-    approvalRecipientId: toIntOrNull(approvalRecipientId) ?? env.DOCUMENSO_APPROVAL_RECIPIENT_ID,
+    eoiTemplateId: toIntOrNull(eoiTemplateId) ?? env.DOCUMENSO_TEMPLATE_ID_EOI ?? 0,
+    clientRecipientId: toIntOrNull(clientRecipientId) ?? env.DOCUMENSO_CLIENT_RECIPIENT_ID ?? 0,
+    developerRecipientId:
+      toIntOrNull(developerRecipientId) ?? env.DOCUMENSO_DEVELOPER_RECIPIENT_ID ?? 0,
+    approvalRecipientId:
+      toIntOrNull(approvalRecipientId) ?? env.DOCUMENSO_APPROVAL_RECIPIENT_ID ?? 0,
     defaultPathway: defaultPathway ?? 'documenso-template',
     developerName: developerName ?? '',
     developerEmail: developerEmail ?? '',
@@ -344,17 +438,40 @@ export interface DocumensoSecretEntry {
 export async function listDocumensoWebhookSecrets(): Promise<DocumensoSecretEntry[]> {
   const { db } = await import('@/lib/db');
   const { systemSettings } = await import('@/lib/db/schema/system');
-  const { eq, isNotNull } = await import('drizzle-orm');
+  const { decrypt } = await import('@/lib/utils/encryption');
+  const { eq } = await import('drizzle-orm');
   const rows = await db
     .select({ portId: systemSettings.portId, value: systemSettings.value })
     .from(systemSettings)
     .where(eq(systemSettings.key, SETTING_KEYS.documensoWebhookSecret));
-  void isNotNull; // imported for future filters
+
   const out: DocumensoSecretEntry[] = [];
   for (const row of rows) {
-    if (typeof row.value !== 'string' || !row.value || !row.portId) continue;
-    out.push({ portId: row.portId, secret: row.value });
+    if (!row.portId) continue;
+    let secret: string | null = null;
+    if (typeof row.value === 'string') {
+      // Legacy plaintext rows.
+      secret = row.value;
+    } else if (
+      typeof row.value === 'object' &&
+      row.value !== null &&
+      'iv' in row.value &&
+      'tag' in row.value &&
+      'data' in row.value
+    ) {
+      // Encrypted envelope written by the registry-aware resolver.
+      try {
+        secret = decrypt(JSON.stringify(row.value));
+      } catch {
+        // Decryption failure (corrupt envelope, key mismatch) — skip the
+        // entry so a stale row doesn't crash the entire receiver loop.
+        secret = null;
+      }
+    }
+    if (!secret) continue;
+    out.push({ portId: row.portId, secret });
   }
+
   // Append the global env secret as a fallback ONLY when it's a real,
   // non-empty value. An empty env secret would otherwise match an empty
   // X-Documenso-Secret header (verifyDocumensoSecret guards this too,