feat(post-audit): batch A+B quick-wins + audit-side residuals

Bundles the user-prioritised follow-ups from the post-audit punch-list.

Batch A — pipeline + EOI safety:
 - §1.1 timeline buildAuditDescription renders diff fields ("leadCategory → hot_lead").
 - §4.13 EOI rejection cascade: notification to assigned rep + audit row + rose banner.
 - §4.10b finish doc-detail: SigningProgress reuse, linked-entity names (server-resolved),
   per-event icons + tooltips + show-more in activity panel.
 - §7.2 stage guidance card replaces empty Payments slot pre-reservation.
 - §4.15 deal-pulse trigger audit (docs/deal-pulse-trigger-audit.md).

Batch B — UX consistency + docs:
 - §1.4 quick log-contact button on interest header.
 - §2.1 contact-log compose: Dialog → Sheet.
 - §7.1 docs/deal-pulse explainer page; /docs/ in PUBLIC_PATHS.
 - DocumentStatus now includes 'rejected' + 'declined' across constants, labels, tone maps.

Audit-side residuals:
 - M-NEW-1 /me/ports skips port-context requirement.
 - M-AU03 audit log CSV export endpoint + UI button.
 - M-IN03 dead receipt-scanner.ts deleted; live path already per-port.
 - M-P01 pg_trgm GIN indexes (migration 0071).
 - §10.1 webhook tests verified passing (was stale).

Deferred per user direction:
 - §11.3 email copy refactor (needs old-CRM reference).
 - M-EM03 IMAP bounce-to-interest linking.

Tests: 1374/1374. tsc + lint clean.

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

src/components/interests/interest-contact-log-tab.tsx

@@ -23,14 +23,19 @@ import { toast } from 'sonner';
 
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
+// §2.1: contact-log compose surface migrated from Dialog to Sheet so it
+// matches the side-panel doctrine used by every other compose surface in
+// the app (ClientForm, InterestForm, YachtForm, EOI Generate). The
+// dialog name `ComposeDialog` is kept for git-blame continuity but the
+// component now renders <Sheet side="right">.
 import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogFooter,
-  DialogHeader,
-  DialogTitle,
-} from '@/components/ui/dialog';
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from '@/components/ui/sheet';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -298,9 +303,13 @@ function EmptyState({ onAdd }: { onAdd: () => void }) {
   );
 }
 
-// ─── Compose / edit dialog ───────────────────────────────────────────────────
+// ─── Compose / edit sheet ───────────────────────────────────────────────────
 
-function ComposeDialog(props: {
+// Exported for §1.4 — interest-detail-header.tsx mounts this sheet
+// directly via a "Log contact" quick-action button (sibling to the
+// Email / Call / WhatsApp pills) so the rep doesn't have to navigate
+// to the Contact log tab first.
+export function ComposeDialog(props: {
   interestId: string;
   existing?: ContactLogEntry;
   open: boolean;
@@ -416,15 +425,15 @@ function ComposeDialogBody({
   });
 
   return (
-    <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent className="sm:max-w-md">
-        <DialogHeader>
-          <DialogTitle>{isEdit ? 'Edit contact log entry' : 'Log a contact'}</DialogTitle>
-          <DialogDescription>
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent side="right" className="w-3/4 sm:max-w-md overflow-y-auto">
+        <SheetHeader>
+          <SheetTitle>{isEdit ? 'Edit contact log entry' : 'Log a contact'}</SheetTitle>
+          <SheetDescription>
             Record the channel, the direction, and what was discussed. Optionally schedule a
             follow-up — a reminder will be created automatically.
-          </DialogDescription>
-        </DialogHeader>
+          </SheetDescription>
+        </SheetHeader>
 
         <div className="space-y-3 py-1">
           {/* Quick-template buttons. Tap one to seed the channel + direction
@@ -594,7 +603,7 @@ function ComposeDialogBody({
           </div>
         </div>
 
-        <DialogFooter>
+        <SheetFooter>
           <Button
             variant="outline"
             onClick={() => onOpenChange(false)}
@@ -608,9 +617,9 @@ function ComposeDialogBody({
           >
             {mutation.isPending ? 'Saving…' : isEdit ? 'Save changes' : 'Log contact'}
           </Button>
-        </DialogFooter>
-      </DialogContent>
-    </Dialog>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
   );
 }
 

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

@@ -66,6 +66,8 @@ const STATUS_TONES: Record<DocumentStatus, string> = {
   completed: 'bg-emerald-100 text-emerald-700',
   expired: 'bg-rose-100 text-rose-700',
   cancelled: 'bg-slate-200 text-slate-600',
+  rejected: 'bg-rose-100 text-rose-700',
+  declined: 'bg-rose-100 text-rose-700',
 };
 
 const ACTIVE_STATUSES = DOCUMENT_STATUS_ACTIVE;

src/components/interests/interest-detail-header.tsx

@@ -11,10 +11,12 @@ import {
   XCircle,
   RefreshCcw,
   Mail,
+  MessageSquarePlus,
   Phone,
   AlarmClock,
   User,
 } from 'lucide-react';
+import { ComposeDialog as ContactLogComposeSheet } from '@/components/interests/interest-contact-log-tab';
 import { WhatsAppIcon } from '@/components/icons/whatsapp';
 import Link from 'next/link';
 
@@ -125,6 +127,10 @@ export function InterestDetailHeader({ portSlug, interest }: InterestDetailHeade
   const [editOpen, setEditOpen] = useState(false);
   const [archiveOpen, setArchiveOpen] = useState(false);
   const [outcomeDialog, setOutcomeDialog] = useState<null | 'won' | 'lost'>(null);
+  // §1.4: Quick log-contact button next to the Email/Call/WhatsApp pills.
+  // Opens the same Sheet the Contact log tab uses without forcing the rep
+  // to tab-navigate first.
+  const [logContactOpen, setLogContactOpen] = useState(false);
   // (Upload-paper-signed-EOI dialog moved to the EOI tab.)
 
   const isArchived = !!interest.archivedAt;
@@ -389,6 +395,16 @@ export function InterestDetailHeader({ portSlug, interest }: InterestDetailHeade
                     </a>
                   </Button>
                 ) : null}
+                <Button
+                  variant="outline"
+                  size="sm"
+                  className="h-8 gap-1.5 px-2.5 [&_svg]:size-3.5"
+                  onClick={() => setLogContactOpen(true)}
+                  aria-label="Log a contact for this interest"
+                >
+                  <MessageSquarePlus />
+                  Log contact
+                </Button>
               </div>
             ) : null}
           </div>
@@ -524,6 +540,12 @@ export function InterestDetailHeader({ portSlug, interest }: InterestDetailHeade
         }}
         isLoading={archiveMutation.isPending || restoreMutation.isPending}
       />
+
+      <ContactLogComposeSheet
+        interestId={interest.id}
+        open={logContactOpen}
+        onOpenChange={setLogContactOpen}
+      />
     </>
   );
 }

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

@@ -76,6 +76,8 @@ const STATUS_TONES: Record<DocumentStatus, string> = {
   completed: 'bg-emerald-100 text-emerald-700',
   expired: 'bg-rose-100 text-rose-700',
   cancelled: 'bg-slate-200 text-slate-600',
+  rejected: 'bg-rose-100 text-rose-700',
+  declined: 'bg-rose-100 text-rose-700',
 };
 
 const ACTIVE_STATUSES = DOCUMENT_STATUS_ACTIVE;
@@ -247,8 +249,17 @@ function ActiveEoiCard({
     'document:signer:opened': [['documents', doc.id, 'signers']],
     'document:completed': [['documents', doc.id, 'signers'], ['documents']],
     'document:signer:rejected': [['documents', doc.id, 'signers'], ['documents']],
+    'document:rejected': [['documents', doc.id, 'signers'], ['documents']],
   });
 
+  // §4.13: surface the rejection callout in a high-visibility banner —
+  // status pill alone doesn't communicate that the doc is dead and the
+  // rep must take action.
+  const isRejected = doc.status === 'rejected' || doc.status === 'declined';
+  const rejectedSigner = isRejected
+    ? signers.find((s) => s.status === 'declined' || s.status === 'rejected')
+    : null;
+
   const remindAllMutation = useMutation({
     mutationFn: () => apiFetch(`/api/v1/documents/${doc.id}/remind`, { method: 'POST', body: {} }),
     onSuccess: () => {
@@ -259,7 +270,30 @@ function ActiveEoiCard({
   });
 
   return (
-    <section className="rounded-xl border bg-gradient-brand-soft p-5 shadow-xs">
+    <section
+      className={
+        isRejected
+          ? 'rounded-xl border border-rose-300 bg-rose-50 p-5 shadow-xs'
+          : 'rounded-xl border bg-gradient-brand-soft p-5 shadow-xs'
+      }
+    >
+      {isRejected ? (
+        <div className="mb-4 flex items-start gap-3 rounded-md border border-rose-300 bg-white p-3">
+          <AlertTriangle className="size-5 shrink-0 text-rose-600" aria-hidden />
+          <div className="min-w-0 flex-1 text-sm">
+            <p className="font-semibold text-rose-900">
+              EOI declined
+              {rejectedSigner
+                ? ` by ${rejectedSigner.signerName ?? rejectedSigner.signerEmail}`
+                : ''}
+            </p>
+            <p className="mt-0.5 text-rose-800">
+              The document is no longer valid. Cancel and regenerate, or reach out to the signer
+              before re-sending.
+            </p>
+          </div>
+        </div>
+      ) : null}
       <header className="flex items-start justify-between gap-3">
         <div className="min-w-0 flex-1 space-y-1">
           <div className="flex items-center gap-2 flex-wrap">

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

@@ -66,6 +66,8 @@ const STATUS_TONES: Record<DocumentStatus, string> = {
   completed: 'bg-emerald-100 text-emerald-700',
   expired: 'bg-rose-100 text-rose-700',
   cancelled: 'bg-slate-200 text-slate-600',
+  rejected: 'bg-rose-100 text-rose-700',
+  declined: 'bg-rose-100 text-rose-700',
 };
 
 const ACTIVE_STATUSES = DOCUMENT_STATUS_ACTIVE;

src/components/interests/interest-tabs.tsx

@@ -49,6 +49,7 @@ import { InterestEoiTab } from '@/components/interests/interest-eoi-tab';
 import { InterestContactLogTab } from '@/components/interests/interest-contact-log-tab';
 import { QualificationChecklist } from '@/components/interests/qualification-checklist';
 import { PaymentsSection } from '@/components/interests/payments-section';
+import { StageGuidanceCard } from '@/components/interests/stage-guidance-card';
 import { SkipAheadBanner } from '@/components/interests/skip-ahead-banner';
 import { InterestBerthStatusBanner } from '@/components/interests/interest-berth-status-banner';
 import { InterestContractTab } from '@/components/interests/interest-contract-tab';
@@ -836,12 +837,20 @@ function OverviewTab({
           stage: no deposit is expected yet, so the empty card is just
           noise — the next-milestone card carries the actionable copy
           instead. */}
-      {showPaymentsSection && (
+      {showPaymentsSection ? (
         <PaymentsSection
           interestId={interestId}
           depositExpectedAmount={interest.depositExpectedAmount ?? null}
           depositExpectedCurrency={interest.depositExpectedCurrency ?? null}
         />
+      ) : (
+        // §7.2: replace the empty Payments slot with a stage-aware
+        // "next step" card on pre-reservation stages so the rep gets
+        // an actionable prompt instead of dead space.
+        <StageGuidanceCard
+          stage={interest.pipelineStage as PipelineStage}
+          hasLinkedBerth={(interest.linkedBerthCount ?? 0) > 0}
+        />
       )}
 
       {/* Sales-process milestones — phase-aware so the user only sees

src/components/interests/stage-guidance-card.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import { Sparkles, ArrowRight, Anchor, Send, ClipboardCheck, FileSignature } from 'lucide-react';
+
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import type { PipelineStage } from '@/lib/constants';
+
+interface StageGuidanceCardProps {
+  /** Current pipeline stage. Drives the per-stage copy + actions. */
+  stage: PipelineStage;
+  /** Callbacks for each shortcut action. Optional — if absent, the
+   *  corresponding button is hidden. */
+  onScrollToRecommender?: () => void;
+  onOpenEoiGenerate?: () => void;
+  onOpenQualification?: () => void;
+  /** True when berth_interest milestone is satisfied (≥1 linked berth);
+   *  used to hide the "Add a berth" prompt when the rep has already
+   *  done it. */
+  hasLinkedBerth?: boolean;
+}
+
+interface StageCopy {
+  title: string;
+  description: string;
+  next: string;
+  actionLabel?: string;
+  actionIcon?: typeof Anchor;
+  onAction?: 'recommender' | 'eoi' | 'qualification';
+}
+
+/**
+ * §7.2 — Stage-aware "what to do next" prompt that sits on the Overview
+ * tab in the spot the Payments section occupies post-reservation. Each
+ * pre-deposit stage gets a one-card prompt + a shortcut button that
+ * jumps the rep to the right surface.
+ *
+ * Replaces the previously-empty Payments slot on enquiry / qualified /
+ * nurturing / eoi stages with an actionable hint.
+ */
+function copyFor(stage: PipelineStage, ctx: { hasLinkedBerth?: boolean }): StageCopy | null {
+  switch (stage) {
+    case 'enquiry':
+      return {
+        title: 'Next: qualify the interest',
+        description: ctx.hasLinkedBerth
+          ? 'Confirm vessel details, walk the rep through the qualification checklist, then move to Qualified.'
+          : 'Link a berth (or capture desired dimensions) and run the qualification checklist before moving on.',
+        next: 'qualified',
+        actionLabel: ctx.hasLinkedBerth ? 'Open qualification checklist' : 'Recommend a berth',
+        actionIcon: ctx.hasLinkedBerth ? ClipboardCheck : Anchor,
+        onAction: ctx.hasLinkedBerth ? 'qualification' : 'recommender',
+      };
+    case 'qualified':
+      return {
+        title: 'Next: send the EOI',
+        description:
+          'Generate the Expression of Interest with all parties and send for signing. Auto-advances to EOI on send.',
+        next: 'eoi',
+        actionLabel: 'Generate EOI',
+        actionIcon: Send,
+        onAction: 'eoi',
+      };
+    case 'nurturing':
+      return {
+        title: 'Stay in touch',
+        description:
+          'Deal is in nurture — schedule a follow-up reminder or log a contact when the prospect re-engages, then move them back to Qualified.',
+        next: 'qualified',
+      };
+    case 'eoi':
+      return {
+        title: 'Waiting on signatures',
+        description:
+          'All signers will get a notification once each completes; the deal auto-advances to Reservation when everyone signs.',
+        next: 'reservation',
+      };
+    default:
+      // Reservation onwards have their own dedicated sections (Payments,
+      // Documents) so the guidance card doesn't render.
+      return null;
+  }
+}
+
+export function StageGuidanceCard({
+  stage,
+  onScrollToRecommender,
+  onOpenEoiGenerate,
+  onOpenQualification,
+  hasLinkedBerth,
+}: StageGuidanceCardProps) {
+  const copy = copyFor(stage, { hasLinkedBerth });
+  if (!copy) return null;
+
+  const ActionIcon = copy.actionIcon ?? FileSignature;
+  const action =
+    copy.onAction === 'recommender' && onScrollToRecommender
+      ? onScrollToRecommender
+      : copy.onAction === 'eoi' && onOpenEoiGenerate
+        ? onOpenEoiGenerate
+        : copy.onAction === 'qualification' && onOpenQualification
+          ? onOpenQualification
+          : null;
+
+  return (
+    <Card>
+      <CardHeader className="pb-2">
+        <CardTitle className="flex items-center gap-2 text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+          <Sparkles className="h-3.5 w-3.5" aria-hidden />
+          Next step
+        </CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-3">
+        <div>
+          <p className="text-sm font-medium text-foreground">{copy.title}</p>
+          <p className="mt-1 text-xs text-muted-foreground">{copy.description}</p>
+        </div>
+        {copy.actionLabel && action ? (
+          <Button size="sm" onClick={action} className="gap-1.5">
+            <ActionIcon className="h-3.5 w-3.5" aria-hidden />
+            {copy.actionLabel}
+            <ArrowRight className="h-3 w-3" aria-hidden />
+          </Button>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}