refactor(sales): consolidate pipeline stages + wire EOI auto-advance

The 8→9 stage refresh from earlier today only updated constants.ts and the DB — 20 component/service files still hardcoded the old enum, leaving labels blank, filter dropdowns wrong, kanban columns mismatched, and the analytics funnel silently dropping new-stage rows. The platform also never advanced pipelineStage on EOI lifecycle events: documents.service.ts wrote eoiStatus but left the user-visible stage stuck. This commit closes both gaps: 1. Single source of truth in src/lib/constants.ts — adds STAGE_LABELS, STAGE_BADGE, STAGE_DOT, STAGE_WEIGHTS, STAGE_TRANSITIONS plus stageLabel / stageBadgeClass / stageDotClass / safeStage / canTransitionStage helpers. components/clients/pipeline-constants.ts becomes a re-export shim so existing imports keep working. 2. 18 stale-enum surfaces migrated — interest list (table, card, filters, form, stage picker), pipeline board, client card, berth interests tab, portal client interests page, dashboard pipeline / funnel / revenue- forecast charts, settings pipeline_weights default, dashboard.service weights, analytics.service funnel stages, alert-rules stale-interest filter, interest-scoring stage rank. 3. Documents tab wired into interest detail — replaced the placeholder in interest-tabs.tsx with InterestDocumentsTab + InterestFilesTab so the EOI launcher is back where salespeople work. 4. Auto-advance — new advanceStageIfBehind() in interests.service.ts (forward-only, no-op if interest is already past the target). Called from documents.service.ts on send (→ eoi_sent), Documenso completed webhook (→ eoi_signed), and manual signed-EOI upload (→ eoi_signed). 5. Transition guard — canTransitionStage() blocks egregious skips (e.g. completed → open, open → contract_signed). Enforced in changeInterestStage before the DB write. Tests updated to reflect the 9-stage model. tsc clean, vitest 832/832, ESLint clean on every file touched. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-01 23:33:53 +02:00
parent 0d357731ad
commit 886119cbde
26 changed files with 577 additions and 419 deletions
--- a/src/app/(portal)/portal/interests/page.tsx
+++ b/src/app/(portal)/portal/interests/page.tsx
@@ -5,28 +5,19 @@ import type { Metadata } from 'next';
 import { getPortalSession } from '@/lib/portal/auth';
 import { getClientInterests } from '@/lib/services/portal.service';
 import { Badge } from '@/components/ui/badge';
+import { stageLabel, safeStage, type PipelineStage } from '@/lib/constants';

 export const metadata: Metadata = { title: 'Interests' };

-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'EOI / NDA Signed',
-  deposit_10pct: 'Deposit Received',
-  contract: 'Contract Stage',
-  completed: 'Completed',
-};
-
-const STAGE_COLORS: Record<string, 'default' | 'secondary' | 'destructive' | 'outline'> = {
+const STAGE_VARIANT: Record<PipelineStage, 'default' | 'secondary' | 'destructive' | 'outline'> = {
  open: 'secondary',
  details_sent: 'secondary',
  in_communication: 'default',
-  visited: 'default',
-  signed_eoi_nda: 'default',
+  eoi_sent: 'default',
+  eoi_signed: 'default',
  deposit_10pct: 'default',
-  contract: 'default',
+  contract_sent: 'default',
+  contract_signed: 'default',
  completed: 'outline',
 };

@@ -40,9 +31,7 @@ export default async function PortalInterestsPage() {
    <div className="space-y-6">
      <div>
        <h1 className="text-2xl font-semibold text-gray-900">Berth Interests</h1>
-        <p className="text-sm text-gray-500 mt-1">
-          Your berth enquiries and applications
-        </p>
+        <p className="text-sm text-gray-500 mt-1">Your berth enquiries and applications</p>
      </div>

      {interests.length === 0 ? (
@@ -56,10 +45,7 @@ export default async function PortalInterestsPage() {
      ) : (
        <div className="space-y-3">
          {interests.map((interest) => (
-            <div
-              key={interest.id}
-              className="bg-white rounded-lg border p-5"
-            >
+            <div key={interest.id} className="bg-white rounded-lg border p-5">
              <div className="flex items-start justify-between gap-4">
                <div className="flex-1 min-w-0">
                  <div className="flex items-center gap-2 mb-1">
@@ -98,8 +84,8 @@ export default async function PortalInterestsPage() {
                    )}
                  </div>
                </div>
-                <Badge variant={STAGE_COLORS[interest.pipelineStage] ?? 'default'}>
-                  {STAGE_LABELS[interest.pipelineStage] ?? interest.pipelineStage}
+                <Badge variant={STAGE_VARIANT[safeStage(interest.pipelineStage)]}>
+                  {stageLabel(interest.pipelineStage)}
                </Badge>
              </div>
            </div>
--- a/src/components/admin/settings/settings-manager.tsx
+++ b/src/components/admin/settings/settings-manager.tsx
@@ -68,9 +68,11 @@ const KNOWN_SETTINGS: Array<{
      open: 0.05,
      details_sent: 0.1,
      in_communication: 0.2,
-      signed_eoi_nda: 0.4,
-      deposit_10pct: 0.6,
-      contract: 0.8,
+      eoi_sent: 0.4,
+      eoi_signed: 0.6,
+      deposit_10pct: 0.75,
+      contract_sent: 0.85,
+      contract_signed: 0.95,
      completed: 1.0,
    },
  },
--- a/src/components/berths/berth-interests-tab.tsx
+++ b/src/components/berths/berth-interests-tab.tsx
@@ -19,6 +19,7 @@ import {
 import { TableSkeleton } from '@/components/shared/loading-skeleton';
 import { EmptyState } from '@/components/shared/empty-state';
 import { Bookmark } from 'lucide-react';
+import { PIPELINE_STAGES, stageLabel } from '@/lib/constants';
 import type { InterestRow } from '@/components/interests/interest-columns';

 interface BerthInterestsTabProps {
@@ -28,27 +29,10 @@ interface BerthInterestsTabProps {
 type StageFilter = 'all' | 'active' | 'lost';
 type SortMode = 'newest' | 'stage' | 'category';

-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
-
-const STAGE_ORDER: Record<string, number> = {
-  open: 0,
-  details_sent: 1,
-  in_communication: 2,
-  visited: 3,
-  signed_eoi_nda: 4,
-  deposit_10pct: 5,
-  contract: 6,
-  completed: 7,
-};
+function stageRank(stage: string): number {
+  const idx = PIPELINE_STAGES.indexOf(stage as (typeof PIPELINE_STAGES)[number]);
+  return idx === -1 ? 99 : idx;
+}

 const CATEGORY_RANK: Record<string, number> = {
  hot_lead: 0,
@@ -104,8 +88,8 @@ export function BerthInterestsTab({ berthId }: BerthInterestsTabProps) {
    });
    const sorted = [...filtered].sort((a, b) => {
      if (sortMode === 'stage') {
-        const sa = STAGE_ORDER[a.pipelineStage] ?? 99;
-        const sb = STAGE_ORDER[b.pipelineStage] ?? 99;
+        const sa = stageRank(a.pipelineStage);
+        const sb = stageRank(b.pipelineStage);
        if (sa !== sb) return sb - sa; // furthest along first
      }
      if (sortMode === 'category') {
@@ -189,7 +173,7 @@ export function BerthInterestsTab({ berthId }: BerthInterestsTabProps) {
                </td>
                <td className="px-3 py-2">
                  <Badge variant="secondary" className="font-normal">
-                    {STAGE_LABELS[i.pipelineStage] ?? i.pipelineStage}
+                    {stageLabel(i.pipelineStage)}
                  </Badge>
                </td>
                <td className="px-3 py-2 text-muted-foreground">
--- a/src/components/clients/client-card.tsx
+++ b/src/components/clients/client-card.tsx
@@ -17,6 +17,7 @@ import {
  deriveInitials,
 } from '@/components/shared/list-card';
 import { getCountryName } from '@/lib/i18n/countries';
+import { stageBadgeClass, stageLabel } from '@/lib/constants';
 import type { ClientRow } from './client-columns';

 const SOURCE_LABELS: Record<string, string> = {
@@ -37,15 +38,20 @@ export function ClientCard({ client, portSlug, onEdit, onArchive }: ClientCardPr
  const primary = client.contacts?.find((c) => c.isPrimary);
  const nationality = client.nationalityIso ? getCountryName(client.nationalityIso, 'en') : null;
  const sourceLabel = client.source ? (SOURCE_LABELS[client.source] ?? client.source) : null;
-  const yachtCount = client.yachtCount ?? 0;
-  const companyCount = client.companyCount ?? 0;
  const tags = client.tags ?? [];

  const meta = [nationality, sourceLabel].filter(Boolean) as string[];
-  const counts: string[] = [];
-  if (yachtCount > 0) counts.push(`${yachtCount} ${yachtCount === 1 ? 'yacht' : 'yachts'}`);
-  if (companyCount > 0)
-    counts.push(`${companyCount} ${companyCount === 1 ? 'company' : 'companies'}`);
+
+  const interest = client.latestInterest ?? null;
+  const interestCount = client.interestCount ?? 0;
+  const interestBerthLabel = interest
+    ? interest.mooringNumber
+      ? `Berth ${interest.mooringNumber}`
+      : 'General interest'
+    : null;
+  const interestStageLabel = interest ? stageLabel(interest.stage) : null;
+  const interestStageBadge = interest ? stageBadgeClass(interest.stage) : null;
+  const extraInterests = interestCount > 1 ? interestCount - 1 : 0;

  return (
    <ListCard
@@ -102,8 +108,19 @@ export function ClientCard({ client, portSlug, onEdit, onArchive }: ClientCardPr
            </div>
          ) : null}

-          {counts.length > 0 ? (
-            <p className="mt-0.5 text-xs text-muted-foreground">{counts.join(' · ')}</p>
+          {interest ? (
+            <div className="mt-1 flex items-center gap-1.5 text-xs text-muted-foreground">
+              <span className="truncate">{interestBerthLabel}</span>
+              <span aria-hidden>·</span>
+              <span
+                className={`shrink-0 rounded-full px-1.5 py-0.5 text-[10px] font-medium ${interestStageBadge}`}
+              >
+                {interestStageLabel}
+              </span>
+              {extraInterests > 0 ? (
+                <span className="shrink-0 text-muted-foreground/80">+{extraInterests}</span>
+              ) : null}
+            </div>
          ) : null}

          {tags.length > 0 ? (
--- a/src/components/clients/pipeline-constants.ts
+++ b/src/components/clients/pipeline-constants.ts
@@ -0,0 +1,14 @@
+// Re-export from the canonical source so legacy imports keep working.
+export {
+  PIPELINE_STAGES,
+  STAGE_LABELS,
+  STAGE_BADGE,
+  STAGE_DOT,
+  STAGE_WEIGHTS,
+  STAGE_TRANSITIONS,
+  safeStage,
+  stageLabel,
+  stageBadgeClass,
+  stageDotClass,
+  type PipelineStage,
+} from '@/lib/constants';
--- a/src/components/dashboard/pipeline-chart.tsx
+++ b/src/components/dashboard/pipeline-chart.tsx
@@ -1,19 +1,12 @@
 'use client';

 import { useQuery } from '@tanstack/react-query';
-import {
-  Bar,
-  BarChart,
-  CartesianGrid,
-  ResponsiveContainer,
-  Tooltip,
-  XAxis,
-  YAxis,
-} from 'recharts';
+import { Bar, BarChart, CartesianGrid, ResponsiveContainer, Tooltip, XAxis, YAxis } from 'recharts';

 import { apiFetch } from '@/lib/api/client';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { CardSkeleton } from '@/components/shared/loading-skeleton';
+import { stageLabel } from '@/lib/constants';
 import { WidgetErrorBoundary } from './widget-error-boundary';

 interface PipelineRow {
@@ -21,17 +14,6 @@ interface PipelineRow {
  count: number;
 }

-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
-
 function PipelineChartInner() {
  const { data, isLoading } = useQuery<PipelineRow[]>({
    queryKey: ['dashboard', 'pipeline'],
@@ -45,7 +27,7 @@ function PipelineChartInner() {
  }

  const chartData = (data ?? []).map((row) => ({
-    stage: STAGE_LABELS[row.stage] ?? row.stage,
+    stage: stageLabel(row.stage),
    count: row.count,
  }));

--- a/src/components/dashboard/pipeline-funnel-chart.tsx
+++ b/src/components/dashboard/pipeline-funnel-chart.tsx
@@ -4,21 +4,11 @@ import { Bar, BarChart, CartesianGrid, ResponsiveContainer, Tooltip, XAxis, YAxi

 import { CardSkeleton } from '@/components/shared/loading-skeleton';
 import { EmptyState } from '@/components/shared/empty-state';
+import { stageLabel } from '@/lib/constants';
 import { ChartCard } from './chart-card';
 import { useFunnel } from './use-analytics';
 import type { DateRange } from '@/lib/services/analytics.service';

-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
-
 interface Props {
  range: DateRange;
 }
@@ -28,7 +18,7 @@ export function PipelineFunnelChart({ range }: Props) {

  const stages = data?.stages ?? [];
  const chartData = stages.map((s) => ({
-    stage: STAGE_LABELS[s.stage] ?? s.stage,
+    stage: stageLabel(s.stage),
    count: s.count,
    conversionPct: s.conversionPct,
  }));
--- a/src/components/dashboard/revenue-forecast.tsx
+++ b/src/components/dashboard/revenue-forecast.tsx
@@ -6,6 +6,7 @@ import { apiFetch } from '@/lib/api/client';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Badge } from '@/components/ui/badge';
 import { CardSkeleton } from '@/components/shared/loading-skeleton';
+import { stageLabel } from '@/lib/constants';
 import { WidgetErrorBoundary } from './widget-error-boundary';

 interface StageBreakdownRow {
@@ -20,17 +21,6 @@ interface ForecastData {
  weightsSource: 'db' | 'default';
 }

-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
-
 function formatCurrency(value: number): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
@@ -66,9 +56,7 @@ function RevenueForecastInner() {
      <CardContent className="space-y-4">
        <div>
          <p className="text-xs text-muted-foreground">Weighted Pipeline Value</p>
-          <p className="text-2xl font-bold">
-            {formatCurrency(data?.totalWeightedValue ?? 0)}
-          </p>
+          <p className="text-2xl font-bold">{formatCurrency(data?.totalWeightedValue ?? 0)}</p>
        </div>

        {activeStages.length > 0 && (
@@ -76,12 +64,10 @@ function RevenueForecastInner() {
            {activeStages.map((s) => (
              <div key={s.stage} className="flex items-center justify-between text-sm">
                <span className="text-muted-foreground">
-                  {STAGE_LABELS[s.stage] ?? s.stage}
+                  {stageLabel(s.stage)}
                  <span className="ml-1 text-xs">({s.count})</span>
                </span>
-                <span className="font-medium tabular-nums">
-                  {formatCurrency(s.weightedValue)}
-                </span>
+                <span className="font-medium tabular-nums">{formatCurrency(s.weightedValue)}</span>
              </div>
            ))}
          </div>
--- a/src/components/interests/interest-card.tsx
+++ b/src/components/interests/interest-card.tsx
@@ -17,43 +17,9 @@ import {
  deriveInitials,
 } from '@/components/shared/list-card';
 import { cn } from '@/lib/utils';
+import { stageBadgeClass, stageDotClass, stageLabel as toStageLabel } from '@/lib/constants';
 import type { InterestRow } from './interest-columns';

-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
-
-/** Pill colors (used for the stage badge in the meta row). */
-const STAGE_PILL: Record<string, string> = {
-  open: 'bg-slate-100 text-slate-700',
-  details_sent: 'bg-blue-100 text-blue-700',
-  in_communication: 'bg-sky-100 text-sky-700',
-  visited: 'bg-violet-100 text-violet-700',
-  signed_eoi_nda: 'bg-amber-100 text-amber-700',
-  deposit_10pct: 'bg-orange-100 text-orange-700',
-  contract: 'bg-green-100 text-green-700',
-  completed: 'bg-emerald-100 text-emerald-700',
-};
-
-/** Accent-bar colors — saturate progressively so the pipeline depth reads at a glance. */
-const STAGE_ACCENT: Record<string, string> = {
-  open: 'bg-slate-300',
-  details_sent: 'bg-blue-400',
-  in_communication: 'bg-sky-400',
-  visited: 'bg-violet-400',
-  signed_eoi_nda: 'bg-amber-400',
-  deposit_10pct: 'bg-orange-400',
-  contract: 'bg-green-500',
-  completed: 'bg-emerald-500',
-};
-
 const CATEGORY_LABELS: Record<string, string> = {
  general_interest: 'General',
  specific_qualified: 'Qualified',
@@ -75,9 +41,9 @@ interface InterestCardProps {
 }

 export function InterestCard({ interest, portSlug, onEdit, onArchive }: InterestCardProps) {
-  const stageLabel = STAGE_LABELS[interest.pipelineStage] ?? interest.pipelineStage;
-  const stagePill = STAGE_PILL[interest.pipelineStage] ?? 'bg-gray-100 text-gray-700';
-  const accentClass = STAGE_ACCENT[interest.pipelineStage] ?? 'bg-slate-300';
+  const stageLabel = toStageLabel(interest.pipelineStage);
+  const stagePill = stageBadgeClass(interest.pipelineStage);
+  const accentClass = stageDotClass(interest.pipelineStage);
  const isHotLead = interest.leadCategory === 'hot_lead';
  const categoryLabel = interest.leadCategory ? CATEGORY_LABELS[interest.leadCategory] : null;
  const sourceLabel = interest.source ? (SOURCE_LABELS[interest.source] ?? interest.source) : null;
--- a/src/components/interests/interest-columns.tsx
+++ b/src/components/interests/interest-columns.tsx
@@ -14,6 +14,7 @@ import {
 } from '@/components/ui/dropdown-menu';
 import { Badge } from '@/components/ui/badge';
 import { TagBadge } from '@/components/shared/tag-badge';
+import { stageBadgeClass, stageLabel } from '@/lib/constants';

 export interface InterestRow {
  id: string;
@@ -29,28 +30,6 @@ export interface InterestRow {
  tags?: Array<{ id: string; name: string; color: string }>;
 }

-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
-
-const STAGE_COLORS: Record<string, string> = {
-  open: 'bg-slate-100 text-slate-700',
-  details_sent: 'bg-blue-100 text-blue-700',
-  in_communication: 'bg-sky-100 text-sky-700',
-  visited: 'bg-violet-100 text-violet-700',
-  signed_eoi_nda: 'bg-amber-100 text-amber-700',
-  deposit_10pct: 'bg-orange-100 text-orange-700',
-  contract: 'bg-green-100 text-green-700',
-  completed: 'bg-emerald-100 text-emerald-700',
-};
-
 const CATEGORY_LABELS: Record<string, string> = {
  general_interest: 'General Interest',
  specific_qualified: 'Specific Qualified',
@@ -117,9 +96,9 @@ export function getInterestColumns({
        const stage = getValue() as string;
        return (
          <span
-            className={`inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium ${STAGE_COLORS[stage] ?? 'bg-gray-100 text-gray-700'}`}
+            className={`inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium ${stageBadgeClass(stage)}`}
          >
-            {STAGE_LABELS[stage] ?? stage}
+            {stageLabel(stage)}
          </span>
        );
      },
@@ -205,10 +184,7 @@ export function getInterestColumns({
              <Pencil className="mr-2 h-3.5 w-3.5" />
              Edit
            </DropdownMenuItem>
-            <DropdownMenuItem
-              className="text-destructive"
-              onClick={() => onArchive(row.original)}
-            >
+            <DropdownMenuItem className="text-destructive" onClick={() => onArchive(row.original)}>
              <Archive className="mr-2 h-3.5 w-3.5" />
              Archive
            </DropdownMenuItem>
--- a/src/components/interests/interest-filters.tsx
+++ b/src/components/interests/interest-filters.tsx
@@ -1,16 +1,5 @@
 import type { FilterDefinition } from '@/components/shared/filter-bar';
-import { PIPELINE_STAGES, LEAD_CATEGORIES } from '@/lib/constants';
-
-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
+import { PIPELINE_STAGES, STAGE_LABELS, LEAD_CATEGORIES } from '@/lib/constants';

 const CATEGORY_LABELS: Record<string, string> = {
  general_interest: 'General Interest',
@@ -30,7 +19,7 @@ export const interestFilterDefinitions: FilterDefinition[] = [
    label: 'Stage',
    type: 'multi-select',
    options: PIPELINE_STAGES.map((s) => ({
-      label: STAGE_LABELS[s] ?? s,
+      label: STAGE_LABELS[s],
      value: s,
    })),
  },
--- a/src/components/interests/interest-form.tsx
+++ b/src/components/interests/interest-form.tsx
@@ -35,20 +35,9 @@ import { YachtPicker } from '@/components/yachts/yacht-picker';
 import { apiFetch } from '@/lib/api/client';
 import { useEntityOptions } from '@/hooks/use-entity-options';
 import { createInterestSchema, type CreateInterestInput } from '@/lib/validators/interests';
-import { PIPELINE_STAGES, LEAD_CATEGORIES } from '@/lib/constants';
+import { PIPELINE_STAGES, STAGE_LABELS, LEAD_CATEGORIES } from '@/lib/constants';
 import { cn } from '@/lib/utils';

-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
-
 const CATEGORY_LABELS: Record<string, string> = {
  general_interest: 'General Interest',
  specific_qualified: 'Specific Qualified',
@@ -58,6 +47,11 @@ const CATEGORY_LABELS: Record<string, string> = {
 interface InterestFormProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
+  /**
+   * Pre-fill clientId when launching the form from a client detail page.
+   * Ignored when `interest` is provided (edit mode).
+   */
+  defaultClientId?: string;
  interest?: {
    id: string;
    clientId: string;
@@ -75,7 +69,7 @@ interface InterestFormProps {
  };
 }

-export function InterestForm({ open, onOpenChange, interest }: InterestFormProps) {
+export function InterestForm({ open, onOpenChange, defaultClientId, interest }: InterestFormProps) {
  const queryClient = useQueryClient();
  const isEdit = !!interest;

@@ -140,14 +134,14 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
      });
    } else if (!interest && open) {
      reset({
-        clientId: '',
+        clientId: defaultClientId ?? '',
        yachtId: undefined,
        pipelineStage: 'open',
        reminderEnabled: false,
        tagIds: [],
      });
    }
-  }, [interest, open, reset]);
+  }, [interest, defaultClientId, open, reset]);

  const mutation = useMutation({
    mutationFn: async (data: CreateInterestInput) => {
@@ -347,7 +341,7 @@ export function InterestForm({ open, onOpenChange, interest }: InterestFormProps
                  <SelectContent>
                    {PIPELINE_STAGES.map((s) => (
                      <SelectItem key={s} value={s}>
-                        {STAGE_LABELS[s] ?? s}
+                        {STAGE_LABELS[s]}
                      </SelectItem>
                    ))}
                  </SelectContent>
--- a/src/components/interests/interest-stage-picker.tsx
+++ b/src/components/interests/interest-stage-picker.tsx
@@ -22,18 +22,7 @@ import {
  SelectValue,
 } from '@/components/ui/select';
 import { apiFetch } from '@/lib/api/client';
-import { PIPELINE_STAGES } from '@/lib/constants';
-
-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
+import { PIPELINE_STAGES, STAGE_LABELS, stageLabel } from '@/lib/constants';

 interface InterestStagePickerProps {
  open: boolean;
@@ -76,9 +65,7 @@ export function InterestStagePicker({
        <div className="space-y-4 py-2">
          <div className="space-y-1">
            <Label>Current Stage</Label>
-            <p className="text-sm text-muted-foreground">
-              {STAGE_LABELS[currentStage] ?? currentStage}
-            </p>
+            <p className="text-sm text-muted-foreground">{stageLabel(currentStage)}</p>
          </div>

          <div className="space-y-1">
@@ -90,7 +77,7 @@ export function InterestStagePicker({
              <SelectContent>
                {PIPELINE_STAGES.map((s) => (
                  <SelectItem key={s} value={s}>
-                    {STAGE_LABELS[s] ?? s}
+                    {STAGE_LABELS[s]}
                  </SelectItem>
                ))}
              </SelectContent>
--- a/src/components/interests/interest-tabs.tsx
+++ b/src/components/interests/interest-tabs.tsx
@@ -1,16 +1,21 @@
 'use client';

-import { format } from 'date-fns';
+import { format, formatDistanceToNowStrict } from 'date-fns';
 import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { CheckCircle2, Circle, FileSignature, Send, Wallet } from 'lucide-react';

 import type { DetailTab } from '@/components/shared/detail-layout';
+import { Button } from '@/components/ui/button';
 import { NotesList } from '@/components/shared/notes-list';
 import { InlineEditableField } from '@/components/shared/inline-editable-field';
 import { InlineTagEditor } from '@/components/shared/inline-tag-editor';
 import { RecommendationList } from '@/components/interests/recommendation-list';
 import { InterestTimeline } from '@/components/interests/interest-timeline';
+import { InterestDocumentsTab } from '@/components/interests/interest-documents-tab';
+import { InterestFilesTab } from '@/components/interests/interest-files-tab';
 import { LEAD_CATEGORIES } from '@/lib/constants';
 import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';

 type InterestPatchField = 'leadCategory' | 'source' | 'notes';

@@ -58,6 +63,21 @@ function useInterestPatch(interestId: string) {
  });
 }

+function useStageMutation(interestId: string) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async ({ stage, reason }: { stage: string; reason?: string }) =>
+      apiFetch(`/api/v1/interests/${interestId}/stage`, {
+        method: 'PATCH',
+        body: { pipelineStage: stage, reason },
+      }),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ['interests', interestId] });
+      qc.invalidateQueries({ queryKey: ['interests'] });
+    },
+  });
+}
+
 function EditableRow({ label, children }: { label: string; children: React.ReactNode }) {
  return (
    <div className="flex gap-2 py-1.5 border-b last:border-0 items-center">
@@ -82,6 +102,117 @@ function formatDate(date: string | null) {
  return format(new Date(date), 'MMM d, yyyy');
 }

+function relativeDate(date: string | null) {
+  if (!date) return null;
+  return `${formatDistanceToNowStrict(new Date(date))} ago`;
+}
+
+interface MilestoneSectionProps {
+  title: string;
+  icon: React.ComponentType<{ className?: string }>;
+  /** Lifecycle for this milestone, in chronological order. */
+  steps: Array<{
+    label: string;
+    date: string | null;
+    /** Stage to advance to when the user clicks the action button for this step. */
+    advanceStage?: string;
+    /** Optional override for the action label. */
+    actionLabel?: string;
+  }>;
+  status: string | null;
+  onAdvance: (stage: string) => void;
+  isPending: boolean;
+}
+
+/**
+ * One milestone section (EOI / Deposit / Contract) — shows a vertical lifecycle
+ * with completed steps checked, the next step exposing a quick "mark as…"
+ * button that bumps the pipeline stage. Each stage flip auto-stamps its date
+ * via the service layer (interests.service.ts). When external systems wire in
+ * (Documenso webhook, paid invoice → deposit, etc.), they patch the same
+ * stage endpoint and these checkmarks light up automatically.
+ */
+function MilestoneSection({
+  title,
+  icon: Icon,
+  steps,
+  status,
+  onAdvance,
+  isPending,
+}: MilestoneSectionProps) {
+  const firstUnsetIdx = steps.findIndex((s) => !s.date);
+
+  return (
+    <section className="rounded-xl border border-border bg-card p-4 shadow-sm">
+      <header className="mb-3 flex items-center justify-between gap-2">
+        <div className="flex items-center gap-2">
+          <Icon className="size-4 text-muted-foreground" />
+          <h3 className="text-sm font-semibold tracking-tight text-foreground">{title}</h3>
+        </div>
+        {status ? (
+          <span className="rounded-full bg-muted px-2 py-0.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
+            {status.replace(/_/g, ' ')}
+          </span>
+        ) : null}
+      </header>
+
+      <ol className="space-y-2">
+        {steps.map((step, i) => {
+          const done = !!step.date;
+          const isNext = !done && i === firstUnsetIdx;
+          return (
+            <li key={step.label} className="flex items-start gap-2 text-sm">
+              {done ? (
+                <CheckCircle2 className="mt-0.5 size-4 shrink-0 text-emerald-600" />
+              ) : (
+                <Circle
+                  className={cn(
+                    'mt-0.5 size-4 shrink-0',
+                    isNext ? 'text-foreground/60' : 'text-muted-foreground/40',
+                  )}
+                />
+              )}
+              <div className="min-w-0 flex-1">
+                <div className="flex flex-wrap items-center gap-x-2 gap-y-0.5">
+                  <span
+                    className={cn(
+                      'truncate',
+                      done
+                        ? 'text-foreground'
+                        : isNext
+                          ? 'text-foreground'
+                          : 'text-muted-foreground',
+                    )}
+                  >
+                    {step.label}
+                  </span>
+                  {step.date ? (
+                    <span className="text-xs text-muted-foreground">
+                      {formatDate(step.date)} · {relativeDate(step.date)}
+                    </span>
+                  ) : null}
+                </div>
+                {isNext && step.advanceStage ? (
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    disabled={isPending}
+                    onClick={() => onAdvance(step.advanceStage!)}
+                    className="mt-2 h-7 px-2.5 text-xs"
+                  >
+                    {step.actionLabel ?? `Mark as ${step.label.toLowerCase()}`}
+                  </Button>
+                ) : null}
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+    </section>
+  );
+}
+
 function OverviewTab({
  interestId,
  interest,
@@ -90,11 +221,80 @@ function OverviewTab({
  interest: InterestTabsOptions['interest'];
 }) {
  const mutation = useInterestPatch(interestId);
+  const stageMutation = useStageMutation(interestId);
  const save = (field: InterestPatchField) => async (next: string | null) => {
    await mutation.mutateAsync({ [field]: next });
  };
+  const advance = (stage: string) =>
+    stageMutation.mutate({ stage, reason: 'Marked from overview' });

  return (
+    <div className="space-y-6">
+      {/* Sales-process milestones — the heart of the system. Each section is a
+          mini lifecycle that auto-completes as actions happen on the platform
+          (Documenso webhook, paid deposit invoice, signed contract). Until the
+          automation lands, salespeople nudge stages forward via the inline
+          buttons here, which auto-stamp the milestone date server-side. */}
+      <div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
+        <MilestoneSection
+          title="EOI"
+          icon={Send}
+          status={interest.eoiStatus}
+          isPending={stageMutation.isPending}
+          onAdvance={advance}
+          steps={[
+            {
+              label: 'EOI sent',
+              date: interest.dateEoiSent,
+              advanceStage: 'eoi_sent',
+              actionLabel: 'Mark EOI as sent',
+            },
+            {
+              label: 'EOI signed',
+              date: interest.dateEoiSigned,
+              advanceStage: 'eoi_signed',
+              actionLabel: 'Mark EOI as signed',
+            },
+          ]}
+        />
+        <MilestoneSection
+          title="Deposit"
+          icon={Wallet}
+          status={interest.depositStatus}
+          isPending={stageMutation.isPending}
+          onAdvance={advance}
+          steps={[
+            {
+              label: 'Deposit received',
+              date: interest.dateDepositReceived,
+              advanceStage: 'deposit_10pct',
+              actionLabel: 'Mark deposit received',
+            },
+          ]}
+        />
+        <MilestoneSection
+          title="Contract"
+          icon={FileSignature}
+          status={interest.contractStatus}
+          isPending={stageMutation.isPending}
+          onAdvance={advance}
+          steps={[
+            {
+              label: 'Contract sent',
+              date: interest.dateContractSent,
+              advanceStage: 'contract_sent',
+              actionLabel: 'Mark contract as sent',
+            },
+            {
+              label: 'Contract signed',
+              date: interest.dateContractSigned,
+              advanceStage: 'contract_signed',
+              actionLabel: 'Mark contract as signed',
+            },
+          ]}
+        />
+      </div>
+
      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
        {/* Lead & Source (editable) */}
        <div className="space-y-1">
@@ -114,28 +314,15 @@ function OverviewTab({
          </dl>
        </div>

-      {/* EOI & Contract Status (read-only — derived) */}
+        {/* Contact dates (read-only — kept compact next to Lead) */}
        <div className="space-y-1">
-        <h3 className="text-sm font-medium mb-2">Status</h3>
-        <dl>
-          <InfoRow label="EOI Status" value={interest.eoiStatus} />
-          <InfoRow label="Contract Status" value={interest.contractStatus} />
-          <InfoRow label="Deposit Status" value={interest.depositStatus} />
-          <InfoRow label="Reservation Status" value={interest.reservationStatus} />
-        </dl>
-      </div>
-
-      {/* Key Dates (read-only — set by workflow events) */}
-      <div className="space-y-1 md:col-span-2">
-        <h3 className="text-sm font-medium mb-2">Key Dates</h3>
+          <h3 className="text-sm font-medium mb-2">Contact</h3>
          <dl>
            <InfoRow label="First Contact" value={formatDate(interest.dateFirstContact)} />
            <InfoRow label="Last Contact" value={formatDate(interest.dateLastContact)} />
-          <InfoRow label="EOI Sent" value={formatDate(interest.dateEoiSent)} />
-          <InfoRow label="EOI Signed" value={formatDate(interest.dateEoiSigned)} />
-          <InfoRow label="Contract Sent" value={formatDate(interest.dateContractSent)} />
-          <InfoRow label="Contract Signed" value={formatDate(interest.dateContractSigned)} />
-          <InfoRow label="Deposit Received" value={formatDate(interest.dateDepositReceived)} />
+            {interest.reservationStatus ? (
+              <InfoRow label="Reservation" value={interest.reservationStatus} />
+            ) : null}
          </dl>
        </div>

@@ -174,6 +361,7 @@ function OverviewTab({
          />
        </div>
      </div>
+    </div>
  );
 }

@@ -198,20 +386,12 @@ export function getInterestTabs({
    {
      id: 'documents',
      label: 'Documents',
-      content: (
-        <div className="text-center py-12 text-muted-foreground">
-          <p>Documents tab available after document system is built</p>
-        </div>
-      ),
+      content: <InterestDocumentsTab interestId={interestId} />,
    },
    {
      id: 'files',
      label: 'Files',
-      content: (
-        <div className="text-center py-12 text-muted-foreground">
-          <p>Files tab available after file system is built</p>
-        </div>
-      ),
+      content: <InterestFilesTab interestId={interestId} />,
    },
    {
      id: 'recommendations',
--- a/src/components/interests/pipeline-board.tsx
+++ b/src/components/interests/pipeline-board.tsx
@@ -8,18 +8,7 @@ import { DndContext, closestCenter, type DragEndEvent } from '@dnd-kit/core';
 import { PipelineColumn } from '@/components/interests/pipeline-column';
 import { apiFetch } from '@/lib/api/client';
 import { usePipelineStore } from '@/stores/pipeline-store';
-import { PIPELINE_STAGES } from '@/lib/constants';
-
-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
+import { PIPELINE_STAGES, STAGE_LABELS } from '@/lib/constants';

 interface InterestRow {
  id: string;
@@ -116,7 +105,7 @@ export function PipelineBoard() {
          <PipelineColumn
            key={stage}
            stage={stage}
-            label={STAGE_LABELS[stage] ?? stage}
+            label={STAGE_LABELS[stage]}
            items={grouped[stage] ?? []}
          />
        ))}
--- a/src/lib/constants.ts
+++ b/src/lib/constants.ts
@@ -4,15 +4,106 @@ export const PIPELINE_STAGES = [
  'open',
  'details_sent',
  'in_communication',
-  'visited',
-  'signed_eoi_nda',
+  'eoi_sent',
+  'eoi_signed',
  'deposit_10pct',
-  'contract',
+  'contract_sent',
+  'contract_signed',
  'completed',
 ] as const;

 export type PipelineStage = (typeof PIPELINE_STAGES)[number];

+export const STAGE_LABELS: Record<PipelineStage, string> = {
+  open: 'Open',
+  details_sent: 'Details Sent',
+  in_communication: 'In Comms',
+  eoi_sent: 'EOI Sent',
+  eoi_signed: 'EOI Signed',
+  deposit_10pct: 'Deposit 10%',
+  contract_sent: 'Contract Sent',
+  contract_signed: 'Contract Signed',
+  completed: 'Completed',
+};
+
+export const STAGE_BADGE: Record<PipelineStage, string> = {
+  open: 'bg-slate-100 text-slate-700',
+  details_sent: 'bg-blue-100 text-blue-700',
+  in_communication: 'bg-sky-100 text-sky-700',
+  eoi_sent: 'bg-indigo-100 text-indigo-700',
+  eoi_signed: 'bg-amber-100 text-amber-700',
+  deposit_10pct: 'bg-orange-100 text-orange-700',
+  contract_sent: 'bg-yellow-100 text-yellow-700',
+  contract_signed: 'bg-green-100 text-green-700',
+  completed: 'bg-emerald-100 text-emerald-700',
+};
+
+export const STAGE_DOT: Record<PipelineStage, string> = {
+  open: 'bg-slate-400',
+  details_sent: 'bg-blue-500',
+  in_communication: 'bg-sky-500',
+  eoi_sent: 'bg-indigo-500',
+  eoi_signed: 'bg-amber-500',
+  deposit_10pct: 'bg-orange-500',
+  contract_sent: 'bg-yellow-500',
+  contract_signed: 'bg-green-500',
+  completed: 'bg-emerald-500',
+};
+
+// Default revenue-forecast probability weights per stage (0–1).
+// Editable per port via settings (`pipeline_weights`); these are the fallbacks.
+export const STAGE_WEIGHTS: Record<PipelineStage, number> = {
+  open: 0.05,
+  details_sent: 0.1,
+  in_communication: 0.2,
+  eoi_sent: 0.4,
+  eoi_signed: 0.6,
+  deposit_10pct: 0.75,
+  contract_sent: 0.85,
+  contract_signed: 0.95,
+  completed: 1.0,
+};
+
+// Allowed transitions out of each stage. Used by changeInterestStage to guard
+// against accidental skips (e.g. dragging a card from Completed back to Open,
+// or jumping Open straight to Completed). Forward moves of 1-2 stages are
+// permitted; backward moves are limited to the immediate predecessor unless
+// the lifecycle (EOI/contract chain) needs an explicit rewind.
+export const STAGE_TRANSITIONS: Record<PipelineStage, readonly PipelineStage[]> = {
+  open: ['details_sent', 'in_communication', 'eoi_sent', 'eoi_signed'],
+  details_sent: ['open', 'in_communication', 'eoi_sent', 'eoi_signed'],
+  in_communication: ['open', 'details_sent', 'eoi_sent', 'eoi_signed'],
+  eoi_sent: ['in_communication', 'eoi_signed', 'deposit_10pct'],
+  eoi_signed: ['eoi_sent', 'deposit_10pct', 'contract_sent', 'contract_signed'],
+  deposit_10pct: ['eoi_signed', 'contract_sent', 'contract_signed'],
+  contract_sent: ['eoi_signed', 'deposit_10pct', 'contract_signed'],
+  contract_signed: ['contract_sent', 'deposit_10pct', 'completed'],
+  completed: ['contract_signed'],
+};
+
+export function canTransitionStage(from: string, to: string): boolean {
+  if (from === to) return true;
+  const fromStage = safeStage(from);
+  const toStage = safeStage(to);
+  return STAGE_TRANSITIONS[fromStage].includes(toStage);
+}
+
+export function safeStage(value: string | null | undefined): PipelineStage {
+  return PIPELINE_STAGES.includes(value as PipelineStage) ? (value as PipelineStage) : 'open';
+}
+
+export function stageLabel(stage: string | null | undefined): string {
+  return STAGE_LABELS[safeStage(stage)];
+}
+
+export function stageBadgeClass(stage: string | null | undefined): string {
+  return STAGE_BADGE[safeStage(stage)];
+}
+
+export function stageDotClass(stage: string | null | undefined): string {
+  return STAGE_DOT[safeStage(stage)];
+}
+
 // ─── Berth Statuses ──────────────────────────────────────────────────────────

 export const BERTH_STATUSES = ['available', 'under_offer', 'sold'] as const;
@@ -21,23 +112,13 @@ export type BerthStatus = (typeof BERTH_STATUSES)[number];

 // ─── Lead Categories ─────────────────────────────────────────────────────────

-export const LEAD_CATEGORIES = [
-  'general_interest',
-  'specific_qualified',
-  'hot_lead',
-] as const;
+export const LEAD_CATEGORIES = ['general_interest', 'specific_qualified', 'hot_lead'] as const;

 export type LeadCategory = (typeof LEAD_CATEGORIES)[number];

 // ─── Document Types ──────────────────────────────────────────────────────────

-export const DOCUMENT_TYPES = [
-  'eoi',
-  'contract',
-  'nda',
-  'reservation_agreement',
-  'other',
-] as const;
+export const DOCUMENT_TYPES = ['eoi', 'contract', 'nda', 'reservation_agreement', 'other'] as const;

 export type DocumentType = (typeof DOCUMENT_TYPES)[number];

--- a/src/lib/db/seed-data.ts
+++ b/src/lib/db/seed-data.ts
@@ -862,11 +862,9 @@ export async function seedPortData(portId: string, portSlug: string): Promise<Se

    // ── 7. Interests (15) ──────────────────────────────────────────────────
    // Spread across pipeline stages.
-    // Valid stages (from interests schema comment):
-    //   open, details_sent, in_communication, visited, signed_eoi_nda,
-    //   deposit_10pct, contract, completed
-    // The task spec mentions "open, qualified, hot, won, lost" as logical buckets;
-    // map those loosely onto actual stages so we cover variety.
+    // Valid stages (see PIPELINE_STAGES in src/lib/constants.ts):
+    //   open, details_sent, in_communication, eoi_sent, eoi_signed,
+    //   deposit_10pct, contract_sent, contract_signed, completed
    const interestPlan: Array<{
      clientIdx: number;
      berthIdx: number | null;
@@ -875,10 +873,11 @@ export async function seedPortData(portId: string, portSlug: string): Promise<Se
        | 'open'
        | 'details_sent'
        | 'in_communication'
-        | 'visited'
-        | 'signed_eoi_nda'
+        | 'eoi_sent'
+        | 'eoi_signed'
        | 'deposit_10pct'
-        | 'contract'
+        | 'contract_sent'
+        | 'contract_signed'
        | 'completed';
      leadCategory: 'general_interest' | 'specific_qualified' | 'hot_lead';
      source: 'website' | 'manual' | 'referral' | 'broker';
@@ -916,7 +915,7 @@ export async function seedPortData(portId: string, portSlug: string): Promise<Se
        clientIdx: 3,
        berthIdx: 3,
        yachtIdx: 6,
-        pipelineStage: 'visited',
+        pipelineStage: 'eoi_sent',
        leadCategory: 'specific_qualified',
        source: 'referral',
        daysAgoFirst: 40,
@@ -934,7 +933,7 @@ export async function seedPortData(portId: string, portSlug: string): Promise<Se
        clientIdx: 5,
        berthIdx: 5,
        yachtIdx: 3,
-        pipelineStage: 'signed_eoi_nda',
+        pipelineStage: 'eoi_signed',
        leadCategory: 'hot_lead',
        source: 'manual',
        daysAgoFirst: 55,
@@ -952,7 +951,7 @@ export async function seedPortData(portId: string, portSlug: string): Promise<Se
        clientIdx: 0,
        berthIdx: 7,
        yachtIdx: 5,
-        pipelineStage: 'contract',
+        pipelineStage: 'contract_signed',
        leadCategory: 'hot_lead',
        source: 'broker',
        daysAgoFirst: 90,
@@ -1017,7 +1016,7 @@ export async function seedPortData(portId: string, portSlug: string): Promise<Se
        clientIdx: 6,
        berthIdx: 9,
        yachtIdx: 4,
-        pipelineStage: 'visited',
+        pipelineStage: 'eoi_sent',
        leadCategory: 'specific_qualified',
        source: 'broker',
        daysAgoFirst: 45,
--- a/src/lib/services/alert-rules.ts
+++ b/src/lib/services/alert-rules.ts
@@ -74,7 +74,9 @@ async function reservationNoAgreement(portId: string): Promise<AlertCandidate[]>
 // Pipeline stuck in mid-funnel stages with no contact for 14+ days.

 async function interestStale(portId: string): Promise<AlertCandidate[]> {
-  const STALE_STAGES = ['details_sent', 'in_communication', 'visited'];
+  // Mid-funnel stages where silence is a problem. EOI/deposit/contract stages
+  // have their own dedicated alerts (eoi.unsigned_long, deposit_overdue, etc.).
+  const STALE_STAGES = ['details_sent', 'in_communication', 'eoi_sent'];
  const rows = await db
    .select({
      id: interests.id,
--- a/src/lib/services/analytics.service.ts
+++ b/src/lib/services/analytics.service.ts
@@ -12,6 +12,7 @@ import { analyticsSnapshots } from '@/lib/db/schema/insights';
 import { interests } from '@/lib/db/schema/interests';
 import { invoices } from '@/lib/db/schema/financial';
 import { berthReservations } from '@/lib/db/schema/reservations';
+import { PIPELINE_STAGES } from '@/lib/constants';

 export type DateRange = '7d' | '30d' | '90d' | 'today';

@@ -117,17 +118,6 @@ function rangeToDays(range: DateRange): number {

 // ─── Computations ─────────────────────────────────────────────────────────────

-const PIPELINE_STAGES = [
-  'open',
-  'details_sent',
-  'in_communication',
-  'visited',
-  'signed_eoi_nda',
-  'deposit_10pct',
-  'contract',
-  'completed',
-] as const;
-
 export async function computePipelineFunnel(
  portId: string,
  range: DateRange,
--- a/src/lib/services/dashboard.service.ts
+++ b/src/lib/services/dashboard.service.ts
@@ -5,20 +5,9 @@ import { clients } from '@/lib/db/schema/clients';
 import { interests } from '@/lib/db/schema/interests';
 import { berths } from '@/lib/db/schema/berths';
 import { systemSettings, auditLogs } from '@/lib/db/schema/system';
-import { PIPELINE_STAGES } from '@/lib/constants';
+import { PIPELINE_STAGES, STAGE_WEIGHTS } from '@/lib/constants';

-// ─── Default pipeline weights ────────────────────────────────────────────────
-
-const DEFAULT_PIPELINE_WEIGHTS: Record<string, number> = {
-  open: 0.05,
-  details_sent: 0.10,
-  in_communication: 0.20,
-  visited: 0.35,
-  signed_eoi_nda: 0.50,
-  deposit_10pct: 0.70,
-  contract: 0.90,
-  completed: 1.00,
-};
+const DEFAULT_PIPELINE_WEIGHTS: Record<string, number> = STAGE_WEIGHTS;

 // ─── KPIs ─────────────────────────────────────────────────────────────────────

@@ -98,10 +87,7 @@ export async function getRevenueForecast(portId: string) {
  let weightsSource: 'db' | 'default' = 'default';

  const settingRow = await db.query.systemSettings.findFirst({
-    where: and(
-      eq(systemSettings.key, 'pipeline_weights'),
-      eq(systemSettings.portId, portId),
-    ),
+    where: and(eq(systemSettings.key, 'pipeline_weights'), eq(systemSettings.portId, portId)),
  });

  if (settingRow?.value) {
@@ -155,10 +141,7 @@ export async function getRevenueForecast(portId: string) {
    weightedValue: stageMap[stage]?.weightedValue ?? 0,
  }));

-  const totalWeightedValue = stageBreakdown.reduce(
-    (acc, s) => acc + s.weightedValue,
-    0,
-  );
+  const totalWeightedValue = stageBreakdown.reduce((acc, s) => acc + s.weightedValue, 0);

  return {
    totalWeightedValue,
--- a/src/lib/services/documents.service.ts
+++ b/src/lib/services/documents.service.ts
@@ -24,6 +24,7 @@ import { minioClient, buildStoragePath } from '@/lib/minio';
 import { env } from '@/lib/env';
 import { logger } from '@/lib/logger';
 import { evaluateRule } from '@/lib/services/berth-rules-engine';
+import { advanceStageIfBehind } from '@/lib/services/interests.service';
 import {
  createDocument as documensoCreate,
  sendDocument as documensoSend,
@@ -596,6 +597,9 @@ export async function sendForSigning(documentId: string, portId: string, meta: A

    // Trigger berth rules
    void evaluateRule('eoi_sent', interest.id, portId, meta);
+
+    // Advance pipeline stage to eoi_sent (no-op if already further along).
+    void advanceStageIfBehind(interest.id, portId, 'eoi_sent', meta, 'EOI sent for signing');
  }

  // Create document event
@@ -686,6 +690,15 @@ export async function uploadSignedManually(

    if (interest) {
      void evaluateRule('eoi_signed', doc.interestId, portId, meta);
+
+      // Advance to eoi_signed (no-op if already past it).
+      void advanceStageIfBehind(
+        doc.interestId,
+        portId,
+        'eoi_signed',
+        meta,
+        'Signed EOI uploaded manually',
+      );
    }
  }

@@ -877,12 +890,22 @@ export async function handleDocumentCompleted(eventData: { documentId: string })
      .where(eq(interests.id, doc.interestId));

    if (interest) {
-      void evaluateRule('eoi_signed', doc.interestId, doc.portId, {
+      const systemMeta: AuditMeta = {
        userId: 'system',
        portId: doc.portId,
        ipAddress: '0.0.0.0',
        userAgent: 'webhook',
-      });
+      };
+      void evaluateRule('eoi_signed', doc.interestId, doc.portId, systemMeta);
+
+      // Advance to eoi_signed (no-op if interest already past it).
+      void advanceStageIfBehind(
+        doc.interestId,
+        doc.portId,
+        'eoi_signed',
+        systemMeta,
+        'EOI signed via Documenso',
+      );
    }
  }

--- a/src/lib/services/interest-scoring.service.ts
+++ b/src/lib/services/interest-scoring.service.ts
@@ -6,6 +6,7 @@ import { interests, interestNotes } from '@/lib/db/schema/interests';
 import { reminders } from '@/lib/db/schema/operations';
 import { emailThreads } from '@/lib/db/schema/email';
 import { logger } from '@/lib/logger';
+import { PIPELINE_STAGES } from '@/lib/constants';

 // ─── Types ────────────────────────────────────────────────────────────────────

@@ -42,19 +43,8 @@ function scorePipelineAge(createdAt: Date): number {
 }

 function scoreStageSpeed(createdAt: Date, pipelineStage: string): number {
-  // Approximate stage index based on known pipeline order
-  const STAGE_ORDER: Record<string, number> = {
-    open: 0,
-    details_sent: 1,
-    in_communication: 2,
-    visited: 3,
-    signed_eoi_nda: 4,
-    deposit_10pct: 5,
-    contract: 6,
-    completed: 7,
-  };
-
-  const stageIndex = STAGE_ORDER[pipelineStage] ?? 0;
+  const idx = PIPELINE_STAGES.indexOf(pipelineStage as (typeof PIPELINE_STAGES)[number]);
+  const stageIndex = idx === -1 ? 0 : idx;
  if (stageIndex === 0) {
    // Still at open — no progression
    return 0;
--- a/src/lib/services/interests.service.ts
+++ b/src/lib/services/interests.service.ts
@@ -14,6 +14,7 @@ import { setEntityTags } from '@/lib/services/entity-tags.helper';
 import { buildListQuery } from '@/lib/db/query-builder';
 import { diffEntity } from '@/lib/entity-diff';
 import { softDelete, restore, withTransaction } from '@/lib/db/utils';
+import { PIPELINE_STAGES, canTransitionStage, type PipelineStage } from '@/lib/constants';
 import type {
  CreateInterestInput,
  UpdateInterestInput,
@@ -459,6 +460,15 @@ export async function changeInterestStage(
    throw new ValidationError('yachtId is required before leaving stage=open');
  }

+  // Block egregious skips. The transition table allows reasonable forward
+  // jumps (e.g. open → eoi_sent) while rejecting things like completed → open
+  // or open → contract_signed. Same-stage no-ops are allowed.
+  if (!canTransitionStage(existing.pipelineStage, data.pipelineStage)) {
+    throw new ValidationError(
+      `Cannot move interest from "${existing.pipelineStage}" directly to "${data.pipelineStage}".`,
+    );
+  }
+
  const oldStage = existing.pipelineStage;

  const [updated] = await db
@@ -469,9 +479,11 @@ export async function changeInterestStage(

  // BR-133: Auto-populate milestones based on stage
  const milestoneUpdates: Record<string, unknown> = {};
-  if (data.pipelineStage === 'signed_eoi_nda') milestoneUpdates.dateEoiSigned = new Date();
-  if (data.pipelineStage === 'contract') milestoneUpdates.dateContractSigned = new Date();
+  if (data.pipelineStage === 'eoi_sent') milestoneUpdates.dateEoiSent = new Date();
+  if (data.pipelineStage === 'eoi_signed') milestoneUpdates.dateEoiSigned = new Date();
  if (data.pipelineStage === 'deposit_10pct') milestoneUpdates.dateDepositReceived = new Date();
+  if (data.pipelineStage === 'contract_sent') milestoneUpdates.dateContractSent = new Date();
+  if (data.pipelineStage === 'contract_signed') milestoneUpdates.dateContractSigned = new Date();
  if (Object.keys(milestoneUpdates).length > 0) {
    await db
      .update(interests)
@@ -527,6 +539,45 @@ export async function changeInterestStage(
  return updated!;
 }

+// ─── Advance Stage If Behind ─────────────────────────────────────────────────
+//
+// Moves an interest forward to `target` if (and only if) it is currently behind
+// it in the pipeline order. Used by lifecycle events (EOI sent, EOI signed,
+// deposit recorded, contract signed) so the user-visible stage tracks reality
+// without overwriting a more advanced state — e.g. a late-arriving signed-EOI
+// webhook on an interest that has already moved on to `contract_sent` is a
+// no-op rather than a regression.
+//
+// Returns true when the stage was changed.
+export async function advanceStageIfBehind(
+  interestId: string,
+  portId: string,
+  target: PipelineStage,
+  meta: AuditMeta,
+  reason?: string,
+): Promise<boolean> {
+  const existing = await db.query.interests.findFirst({
+    where: and(eq(interests.id, interestId), eq(interests.portId, portId)),
+  });
+  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;
+  }
+
+  // yachtId gate: changeInterestStage requires a yacht before leaving `open`.
+  // EOI events imply a yacht is in the picture, but if the data is missing we
+  // bail rather than throw — the EOI itself shouldn't fail because of this.
+  if (existing.pipelineStage === 'open' && !existing.yachtId) {
+    return false;
+  }
+
+  await changeInterestStage(interestId, portId, { pipelineStage: target, reason }, meta);
+  return true;
+}
+
 // ─── Archive / Restore ────────────────────────────────────────────────────────

 export async function archiveInterest(id: string, portId: string, meta: AuditMeta) {
--- a/tests/integration/analytics-service.test.ts
+++ b/tests/integration/analytics-service.test.ts
@@ -30,7 +30,14 @@ describe('analytics service', () => {
      const port = await makePort();
      const client = await makeClient({ portId: port.id });
      // 3 open, 2 details_sent, 1 visited
-      for (const stage of ['open', 'open', 'open', 'details_sent', 'details_sent', 'visited']) {
+      for (const stage of [
+        'open',
+        'open',
+        'open',
+        'details_sent',
+        'details_sent',
+        'in_communication',
+      ]) {
        await db.insert(interests).values({
          portId: port.id,
          clientId: client.id,
@@ -42,7 +49,7 @@ describe('analytics service', () => {

      const open = result.stages.find((s) => s.stage === 'open');
      const details = result.stages.find((s) => s.stage === 'details_sent');
-      const visited = result.stages.find((s) => s.stage === 'visited');
+      const visited = result.stages.find((s) => s.stage === 'in_communication');
      expect(open?.count).toBe(3);
      expect(open?.conversionPct).toBe(100);
      expect(details?.count).toBe(2);
@@ -54,7 +61,7 @@ describe('analytics service', () => {
    it('returns zeros when port has no interests', async () => {
      const port = await makePort();
      const result = await computePipelineFunnel(port.id, '30d');
-      expect(result.stages).toHaveLength(8);
+      expect(result.stages).toHaveLength(9);
      expect(result.stages.every((s) => s.count === 0)).toBe(true);
    });
  });
--- a/tests/unit/constants.test.ts
+++ b/tests/unit/constants.test.ts
@@ -1,13 +1,9 @@
 import { describe, it, expect } from 'vitest';
-import {
-  PIPELINE_STAGES,
-  BERTH_STATUSES,
-  NOTIFICATION_TYPES,
-} from '@/lib/constants';
+import { PIPELINE_STAGES, BERTH_STATUSES, NOTIFICATION_TYPES } from '@/lib/constants';

 describe('PIPELINE_STAGES', () => {
-  it('has exactly 8 entries', () => {
-    expect(PIPELINE_STAGES).toHaveLength(8);
+  it('has exactly 9 entries', () => {
+    expect(PIPELINE_STAGES).toHaveLength(9);
  });

  it('starts with "open"', () => {
@@ -23,25 +19,18 @@ describe('PIPELINE_STAGES', () => {
      'open',
      'details_sent',
      'in_communication',
-      'visited',
-      'signed_eoi_nda',
+      'eoi_sent',
+      'eoi_signed',
      'deposit_10pct',
-      'contract',
+      'contract_sent',
+      'contract_signed',
      'completed',
    ]);
  });

-  it('is a readonly (frozen) tuple — cannot be mutated at runtime', () => {
-    expect(() => {
-      // TypeScript readonly doesn't prevent runtime mutation of `as const` arrays,
-      // but they are not Object.frozen. The important thing is the `as const` means
-      // the type system protects it. We verify immutability via the TypeScript type
-      // and check the array is not a plain mutable array.
+  it('is a readonly tuple — type-level immutability via `as const`', () => {
    const arr = PIPELINE_STAGES as unknown as string[];
-      // Attempting splice on a readonly const-asserted array at runtime won't throw
-      // but the values should be what we defined.
-      expect(arr).toHaveLength(8);
-    }).not.toThrow();
+    expect(arr).toHaveLength(9);
  });

  it('has no duplicate entries', () => {
--- a/tests/unit/validators.test.ts
+++ b/tests/unit/validators.test.ts
@@ -115,10 +115,11 @@ describe('createInterestSchema', () => {
      'open',
      'details_sent',
      'in_communication',
-      'visited',
-      'signed_eoi_nda',
+      'eoi_sent',
+      'eoi_signed',
      'deposit_10pct',
-      'contract',
+      'contract_sent',
+      'contract_signed',
      'completed',
    ];
    for (const stage of stages) {
@@ -143,7 +144,7 @@ describe('createInterestSchema', () => {

 describe('changeStageSchema', () => {
  it('accepts a valid stage', () => {
-    expect(changeStageSchema.safeParse({ pipelineStage: 'visited' }).success).toBe(true);
+    expect(changeStageSchema.safeParse({ pipelineStage: 'in_communication' }).success).toBe(true);
  });

  it('rejects invalid stage', () => {