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/components/documents/document-detail.tsx

@@ -1,11 +1,11 @@
 'use client';
 
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
 import Link from 'next/link';
 import type { Route } from 'next';
 import { useRouter } from 'next/navigation';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
-import { ArrowLeft, Bell, Download, Mail, Trash2, X } from 'lucide-react';
+import { ArrowLeft, Bell, Download, Mail, Send, Trash2, UserPlus, X } from 'lucide-react';
 import { toast } from 'sonner';
 
 import { Button } from '@/components/ui/button';
@@ -15,6 +15,22 @@ import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { useConfirmation } from '@/hooks/use-confirmation';
 import { apiFetch } from '@/lib/api/client';
 import { toastError } from '@/lib/api/toast-error';
+import { cleanSignerName } from '@/components/documents/signing-progress';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+
+/** Capitalize the first letter; rest stays as-is. Used for normalising
+ *  free-text enum values ('signer'/'approver'/'sent'/'pending') for
+ *  display without resorting to full ALL-CAPS that other surfaces use. */
+function capFirst(s: string | null | undefined): string {
+  if (!s) return '';
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
 
 interface DetailDoc {
   id: string;
@@ -39,6 +55,9 @@ interface DetailSigner {
   signerRole: string;
   signingOrder: number;
   status: string;
+  /** Null = never invited yet → "Send invitation" CTA.
+   *  Set + status pending → "Send reminder" CTA. */
+  invitedAt: string | null;
   signedAt: string | null;
   signingUrl: string | null;
 }
@@ -158,6 +177,22 @@ export function DocumentDetail({ documentId, portSlug }: DocumentDetailProps) {
     }
   };
 
+  // #67: state-aware action button. When a signer has no `invitedAt`
+  // they've never been mailed — fire the initial invitation (the same
+  // route the EOI tab uses; handles v2 distribute-or-self-heal).
+  const handleSendInvitation = async (signerId: string) => {
+    try {
+      await apiFetch(`/api/v1/documents/${documentId}/send-invitation`, {
+        method: 'POST',
+        body: { signerId },
+      });
+      toast.success('Invitation sent');
+      queryClient.invalidateQueries({ queryKey: ['document-detail', documentId] });
+    } catch (err) {
+      toastError(err);
+    }
+  };
+
   const handleCancel = async () => {
     const ok = await confirm({
       title: 'Cancel document',
@@ -213,7 +248,7 @@ export function DocumentDetail({ documentId, portSlug }: DocumentDetailProps) {
         kpiLine={
           <>
             <StatusPill status={STATUS_PILL_MAP[doc.status] ?? 'pending'} withDot>
-              {doc.status.replace(/_/g, ' ')}
+              {capFirst(doc.status.replace(/_/g, ' '))}
             </StatusPill>
             <span>
               {signers.filter((s) => s.status === 'signed').length}/{signers.length} signed
@@ -279,28 +314,42 @@ export function DocumentDetail({ documentId, portSlug }: DocumentDetailProps) {
                     </div>
                     <div className="min-w-0 flex-1">
                       <div className="flex items-center justify-between gap-2">
-                        <div className="font-medium text-foreground">{signer.signerName}</div>
+                        <div className="font-medium text-foreground">
+                          {/* #67 cleanup: strip `(was: …)` / `(placeholder)`
+                              email-redirect leak suffixes that the EOI tab
+                              already scrubs on its own SigningProgress card. */}
+                          {cleanSignerName(signer.signerName) || signer.signerEmail}
+                        </div>
                         <StatusPill status={SIGNER_PILL_MAP[signer.status] ?? 'pending'}>
-                          {signer.status}
+                          {capFirst(signer.status)}
                         </StatusPill>
                       </div>
                       <div className="text-xs text-muted-foreground">
-                        {signer.signerEmail} · {signer.signerRole}
+                        {signer.signerEmail} · {capFirst(signer.signerRole)}
                       </div>
                       <div className="mt-1 text-xs text-muted-foreground">
                         {signer.signedAt
                           ? `Signed ${new Date(signer.signedAt).toLocaleDateString('en-GB')}`
-                          : 'Pending'}
+                          : signer.invitedAt
+                            ? `Invited ${new Date(signer.invitedAt).toLocaleDateString('en-GB')}`
+                            : 'Not yet invited'}
                       </div>
                       {signer.status === 'pending' && doc.documensoId && isInFlight ? (
                         <div className="mt-2 flex items-center gap-2">
-                          <Button
-                            size="sm"
-                            variant="outline"
-                            onClick={() => handleRemind(signer.id)}
-                          >
-                            <Bell className="mr-1.5 h-3 w-3" aria-hidden /> Remind
-                          </Button>
+                          {/* #67 state-aware CTA: invited yet? remind. else: send. */}
+                          {signer.invitedAt ? (
+                            <Button
+                              size="sm"
+                              variant="outline"
+                              onClick={() => handleRemind(signer.id)}
+                            >
+                              <Bell className="mr-1.5 h-3 w-3" aria-hidden /> Send reminder
+                            </Button>
+                          ) : (
+                            <Button size="sm" onClick={() => handleSendInvitation(signer.id)}>
+                              <Send className="mr-1.5 h-3 w-3" aria-hidden /> Send invitation
+                            </Button>
+                          )}
                           {signer.signingUrl ? (
                             <button
                               type="button"
@@ -339,44 +388,7 @@ export function DocumentDetail({ documentId, portSlug }: DocumentDetailProps) {
 
         {/* Right column */}
         <div className="flex flex-col gap-4">
-          <section className="rounded-md border bg-white p-4">
-            <h2 className="mb-2 text-sm font-semibold uppercase tracking-wide text-muted-foreground">
-              Watchers
-            </h2>
-            {watchers.length === 0 ? (
-              <p className="text-xs text-muted-foreground">No one is watching this document yet.</p>
-            ) : (
-              <ul className="space-y-1">
-                {watchers.map((w) => (
-                  <li key={w.userId} className="flex items-center justify-between text-sm">
-                    <span className="truncate font-mono text-xs text-muted-foreground">
-                      {w.userId.slice(0, 8)}…
-                    </span>
-                    <button
-                      type="button"
-                      aria-label="Remove watcher"
-                      onClick={async () => {
-                        try {
-                          await apiFetch(`/api/v1/documents/${documentId}/watchers/${w.userId}`, {
-                            method: 'DELETE',
-                          });
-                          toast.success('Watcher removed');
-                          queryClient.invalidateQueries({
-                            queryKey: ['document-detail', documentId],
-                          });
-                        } catch (err) {
-                          toastError(err);
-                        }
-                      }}
-                      className="text-muted-foreground hover:text-destructive"
-                    >
-                      <Trash2 className="h-3.5 w-3.5" aria-hidden />
-                    </button>
-                  </li>
-                ))}
-              </ul>
-            )}
-          </section>
+          <WatchersCard documentId={documentId} watchers={watchers} />
 
           <section className="rounded-md border bg-white p-4">
             <h2 className="mb-2 text-sm font-semibold uppercase tracking-wide text-muted-foreground">
@@ -405,3 +417,130 @@ export function DocumentDetail({ documentId, portSlug }: DocumentDetailProps) {
     </div>
   );
 }
+
+/**
+ * #67 watcher Add UI. The watchers list previously displayed only
+ * user-id stubs (truncated UUID) with a delete button and no way to
+ * add new watchers. This card resolves user IDs to display names
+ * via the existing `/api/v1/admin/users/picker` endpoint (already
+ * used by the registry-driven settings form), surfaces a "+ Add"
+ * select, and keeps the delete affordance unchanged.
+ */
+interface PickerUser {
+  id: string;
+  email: string;
+  name: string | null;
+}
+
+function WatchersCard({ documentId, watchers }: { documentId: string; watchers: DetailWatcher[] }) {
+  const queryClient = useQueryClient();
+  const [selected, setSelected] = useState('');
+
+  const { data: usersData } = useQuery({
+    queryKey: ['admin', 'users-picker'],
+    queryFn: () => apiFetch<{ data: PickerUser[] }>('/api/v1/admin/users/picker'),
+  });
+  const users = usersData?.data ?? [];
+
+  const userById = useMemo(() => {
+    const map = new Map<string, PickerUser>();
+    for (const u of users) map.set(u.id, u);
+    return map;
+  }, [users]);
+
+  const watcherIds = new Set(watchers.map((w) => w.userId));
+  const candidates = users.filter((u) => !watcherIds.has(u.id));
+
+  async function addWatcher(userId: string) {
+    if (!userId) return;
+    try {
+      await apiFetch(`/api/v1/documents/${documentId}/watchers`, {
+        method: 'POST',
+        body: { userId },
+      });
+      toast.success('Watcher added');
+      setSelected('');
+      queryClient.invalidateQueries({ queryKey: ['document-detail', documentId] });
+    } catch (err) {
+      toastError(err);
+    }
+  }
+
+  async function removeWatcher(userId: string) {
+    try {
+      await apiFetch(`/api/v1/documents/${documentId}/watchers/${userId}`, {
+        method: 'DELETE',
+      });
+      toast.success('Watcher removed');
+      queryClient.invalidateQueries({ queryKey: ['document-detail', documentId] });
+    } catch (err) {
+      toastError(err);
+    }
+  }
+
+  return (
+    <section className="rounded-md border bg-white p-4">
+      <h2 className="mb-1 text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+        Watchers
+      </h2>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Watchers receive an in-app notification on every signing event (opened, signed, declined,
+        completed).
+      </p>
+
+      {watchers.length === 0 ? (
+        <p className="text-xs text-muted-foreground">No one is watching this document yet.</p>
+      ) : (
+        <ul className="mb-3 space-y-1">
+          {watchers.map((w) => {
+            const u = userById.get(w.userId);
+            return (
+              <li key={w.userId} className="flex items-center justify-between text-sm">
+                <span className="truncate">
+                  {u?.name ?? u?.email ?? `User ${w.userId.slice(0, 8)}…`}
+                </span>
+                <button
+                  type="button"
+                  aria-label="Remove watcher"
+                  onClick={() => removeWatcher(w.userId)}
+                  className="text-muted-foreground hover:text-destructive"
+                >
+                  <Trash2 className="h-3.5 w-3.5" aria-hidden />
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+
+      <div className="flex items-center gap-2">
+        <Select value={selected} onValueChange={setSelected}>
+          <SelectTrigger className="h-9 flex-1 text-xs">
+            <SelectValue placeholder="Add a watcher…" />
+          </SelectTrigger>
+          <SelectContent>
+            {candidates.length === 0 ? (
+              <div className="px-2 py-3 text-xs text-muted-foreground">
+                All users in this port are already watching.
+              </div>
+            ) : (
+              candidates.map((u) => (
+                <SelectItem key={u.id} value={u.id}>
+                  {u.name ?? u.email}
+                </SelectItem>
+              ))
+            )}
+          </SelectContent>
+        </Select>
+        <Button
+          size="sm"
+          variant="outline"
+          disabled={!selected}
+          onClick={() => addWatcher(selected)}
+        >
+          <UserPlus className="mr-1.5 h-3 w-3" aria-hidden /> Add
+        </Button>
+      </div>
+    </section>
+  );
+}