feat(emails): sales send-out flows + brochures + email-from settings

Phase 7 of the berth-recommender refactor (plan §3.3, §4.8, §4.9, §5.7,
§5.8, §5.9, §11.1, §14.7, §14.9). Adds the rep-driven send-out path for
per-berth PDFs and port-wide brochures, the per-port sales SMTP/IMAP
config + body templates, and the supporting admin UI.

Migration: 0031_brochures_and_document_sends.sql

Schema additions:
  - brochures (port-wide, with isDefault marker + archive)
  - brochure_versions (versioned uploads, storageKey per §4.7a)
  - document_sends (audit log of every rep-initiated send; failures
    captured with failedAt + errorReason). berthPdfVersionId is a plain
    text column (no FK) — loose-coupled to Phase 6b's berth_pdf_versions
    so the two phases stay independent.

§14.7 critical mitigations:
  - Body XSS: rep-authored markdown goes through renderEmailBody()
    (HTML-escape first, then a tight allowlist of bold/italic/code/link
    rules). https:// + mailto: only — javascript:/data: URLs stripped.
    Tested against script/img/iframe/svg/onerror polyglots.
  - Recipient typo: strict email regex + two-step confirm modal that
    shows the exact recipient before send.
  - Unresolved merge fields: pre-send dry-run /preview endpoint blocks
    submission until findUnresolvedTokens() returns empty.
  - SMTP failure: every transport rejection writes a document_sends row
    with failedAt + errorReason; UI surfaces the message.
  - Hourly per-user rate limit: 50 sends/user/hour via existing
    checkRateLimit().
  - Size threshold fallback (§11.1): files above
    email_attach_threshold_mb (default 15) ship as a 24h signed-URL
    download link in the body instead of an attachment. Storage stream
    flows directly to nodemailer to avoid buffering 20MB+.

§14.10 critical mitigation:
  - SMTP/IMAP passwords encrypted at rest via the existing
    EMAIL_CREDENTIAL_KEY (AES-256-GCM). The /api/v1/admin/email/
    sales-config GET endpoint never returns the decrypted value — only
    a *PassIsSet boolean. PATCH treats empty string as "leave unchanged"
    and explicit null as "clear", so the masked-placeholder UI round-
    trips without forcing re-entry on every save.

system_settings keys (per-port unless noted):
  - sales_from_address, sales_smtp_{host,port,secure,user,pass_encrypted}
  - sales_imap_{host,port,user,pass_encrypted}
  - sales_auth_method (default app_password)
  - noreply_from_address
  - email_template_send_berth_pdf_body, email_template_send_brochure_body
  - brochure_max_upload_mb (default 50)
  - email_attach_threshold_mb (default 15)

UI surfaces (per §5.7, §5.8, §5.9):
  - <SendDocumentDialog> shared 2-step compose+confirm flow.
  - <SendBerthPdfDialog>, <SendDocumentsDialog>, <SendFromInterestButton>
    wrappers per detail page.
  - /[portSlug]/admin/brochures: list, upload (direct-to-storage
    presigned PUT for the 20MB+ files per §11.1), default toggle,
    archive.
  - /[portSlug]/admin/email extended with <SalesEmailConfigCard>:
    SMTP + IMAP creds, body templates, threshold/max settings.

Storage: every upload + download goes through getStorageBackend() —
no direct minio imports, per Phase 6a contract.

Tests: 1145 vitest passing (+ 50 new in
markdown-email-sanitization.test.ts, document-sends-validators.test.ts,
sales-email-config-validators.test.ts).

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

src/app/(dashboard)/[portSlug]/admin/brochures/page.tsx

@@ -0,0 +1,21 @@
+import { PageHeader } from '@/components/shared/page-header';
+import { BrochuresAdminPanel } from '@/components/admin/brochures-admin-panel';
+
+/**
+ * Per-port admin page for managing brochures (Phase 7 §5.8).
+ *
+ * Lists brochures, lets per-port admins upload new versions via direct-to-
+ * storage presigned URLs (so the 20MB+ file never traverses Next.js's
+ * body-size limit — see §11.1), and toggle the default flag.
+ */
+export default function BrochuresAdminPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Brochures"
+        description="Port-wide marketing PDFs available to the sales send-out flow. The default brochure is the one /clients picker pre-selects."
+      />
+      <BrochuresAdminPanel />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/email/page.tsx

@@ -3,6 +3,7 @@ import {
   type SettingFieldDef,
 } from '@/components/admin/shared/settings-form-card';
 import { PageHeader } from '@/components/shared/page-header';
+import { SalesEmailConfigCard } from '@/components/admin/sales-email-config-card';
 
 const FIELDS: SettingFieldDef[] = [
   {
@@ -94,6 +95,7 @@ export default function EmailSettingsPage() {
         description="Optional per-port SMTP credentials. Leave blank to use the global env defaults."
         fields={FIELDS.slice(5)}
       />
+      <SalesEmailConfigCard />
     </div>
   );
 }

src/app/api/v1/admin/brochures/[id]/route.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { archiveBrochure, getBrochure, updateBrochure } from '@/lib/services/brochures.service';
+import { updateBrochureSchema } from '@/lib/validators/brochures';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx, params) => {
+    try {
+      const id = params.id!;
+      const data = await getBrochure(ctx.portId, id);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PATCH = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx, params) => {
+    try {
+      const id = params.id!;
+      const input = await parseBody(req, updateBrochureSchema);
+      const data = await updateBrochure(ctx.portId, id, input);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx, params) => {
+    try {
+      const id = params.id!;
+      await archiveBrochure(ctx.portId, id);
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/brochures/[id]/versions/route.ts

@@ -0,0 +1,68 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  generateBrochureStorageKey,
+  registerBrochureVersion,
+} from '@/lib/services/brochures.service';
+import { registerBrochureVersionSchema } from '@/lib/validators/brochures';
+
+/**
+ * Two-step upload (per §11.1):
+ *   1. GET (no body) — server returns a fresh storage key + presigned URL.
+ *   2. POST (metadata) — after the browser PUTs to the URL, register the
+ *      version row server-side.
+ *
+ * Direct-to-storage uploads bypass Next.js's body-size limit; the server
+ * never holds the 20MB+ payload in memory.
+ */
+import { getStorageBackend } from '@/lib/storage';
+import { getSalesContentConfig } from '@/lib/services/sales-email-config.service';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx, params) => {
+    try {
+      const id = params.id!;
+      const content = await getSalesContentConfig(ctx.portId);
+      const storageKey = await generateBrochureStorageKey(ctx.portId, id);
+      const storage = await getStorageBackend();
+      const { url } = await storage.presignUpload(storageKey, {
+        expirySeconds: 900,
+        contentType: 'application/pdf',
+      });
+      return NextResponse.json({
+        data: {
+          storageKey,
+          uploadUrl: url,
+          method: 'PUT',
+          maxBytes: content.brochureMaxUploadMb * 1024 * 1024,
+        },
+      });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx, params) => {
+    try {
+      const id = params.id!;
+      const input = await parseBody(req, registerBrochureVersionSchema);
+      const data = await registerBrochureVersion({
+        portId: ctx.portId,
+        brochureId: id,
+        storageKey: input.storageKey,
+        fileName: input.fileName,
+        fileSizeBytes: input.fileSizeBytes,
+        contentSha256: input.contentSha256,
+        uploadedBy: ctx.userId,
+      });
+      return NextResponse.json({ data }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/brochures/route.ts

@@ -0,0 +1,36 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createBrochure, listBrochures } from '@/lib/services/brochures.service';
+import { createBrochureSchema } from '@/lib/validators/brochures';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx) => {
+    try {
+      const data = await listBrochures(ctx.portId, { includeArchived: true });
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const input = await parseBody(req, createBrochureSchema);
+      const data = await createBrochure({
+        portId: ctx.portId,
+        label: input.label,
+        description: input.description ?? null,
+        isDefault: input.isDefault,
+        createdBy: ctx.userId,
+      });
+      return NextResponse.json({ data }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/email/sales-config/route.ts

@@ -0,0 +1,67 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  getSalesEmailConfig,
+  getSalesImapConfig,
+  getSalesContentConfig,
+  redactSalesConfigForResponse,
+  updateSalesEmailConfig,
+} from '@/lib/services/sales-email-config.service';
+import { updateSalesEmailConfigSchema } from '@/lib/validators/sales-email-config';
+
+/**
+ * GET /api/v1/admin/email/sales-config
+ *
+ * Returns the redacted view of the sales-email config. Per §14.10
+ * "Permission escalation: who configures SMTP credentials?", reps cannot
+ * see the decrypted password — the response only carries `*PassIsSet`
+ * boolean markers.
+ */
+export const GET = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx) => {
+    try {
+      const [email, imap, content] = await Promise.all([
+        getSalesEmailConfig(ctx.portId),
+        getSalesImapConfig(ctx.portId),
+        getSalesContentConfig(ctx.portId),
+      ]);
+      const redacted = redactSalesConfigForResponse(email, imap, content);
+      return NextResponse.json({ data: redacted });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+/**
+ * PATCH /api/v1/admin/email/sales-config
+ *
+ * Per-port admin only. Encrypts SMTP/IMAP passwords via AES-256-GCM before
+ * storage; the API never returns decrypted secrets (mirror enforcement on
+ * the GET handler).
+ */
+export const PATCH = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const input = await parseBody(req, updateSalesEmailConfigSchema);
+      await updateSalesEmailConfig(ctx.portId, input, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      // Return the freshly-redacted view so the UI can re-render.
+      const [email, imap, content] = await Promise.all([
+        getSalesEmailConfig(ctx.portId),
+        getSalesImapConfig(ctx.portId),
+        getSalesContentConfig(ctx.portId),
+      ]);
+      return NextResponse.json({ data: redactSalesConfigForResponse(email, imap, content) });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/document-sends/berth-pdf/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { sendBerthPdf } from '@/lib/services/document-sends.service';
+import { sendBerthPdfSchema } from '@/lib/validators/document-sends';
+
+/**
+ * POST /api/v1/document-sends/berth-pdf
+ *
+ * Sends the active per-berth PDF version to a client recipient. The body
+ * markdown goes through the merge-field expander + sanitizer
+ * (`renderEmailBody`) before reaching nodemailer (§14.7 critical mitigation:
+ * body XSS).
+ */
+export const POST = withAuth(async (req, ctx) => {
+  try {
+    const input = await parseBody(req, sendBerthPdfSchema);
+    const result = await sendBerthPdf({
+      portId: ctx.portId,
+      berthId: input.berthId,
+      recipient: input.recipient,
+      customBodyMarkdown: input.customBodyMarkdown,
+      sentBy: ctx.userId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/document-sends/brochure/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { sendBrochure } from '@/lib/services/document-sends.service';
+import { sendBrochureSchema } from '@/lib/validators/document-sends';
+
+/**
+ * POST /api/v1/document-sends/brochure
+ *
+ * Sends a brochure (default or specified) to a client recipient. Same
+ * sanitization + audit-row pipeline as the berth-pdf endpoint.
+ */
+export const POST = withAuth(async (req, ctx) => {
+  try {
+    const input = await parseBody(req, sendBrochureSchema);
+    const result = await sendBrochure({
+      portId: ctx.portId,
+      brochureId: input.brochureId,
+      recipient: input.recipient,
+      customBodyMarkdown: input.customBodyMarkdown,
+      sentBy: ctx.userId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/document-sends/preview/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { previewBody } from '@/lib/services/document-sends.service';
+import { previewBodySchema } from '@/lib/validators/document-sends';
+
+/**
+ * POST /api/v1/document-sends/preview
+ *
+ * Renders a body for the dry-run UI without actually sending. Returns the
+ * sanitized HTML, the post-merge markdown, and the list of unresolved
+ * `{{tokens}}` so the UI can block submit until the rep fills them in
+ * (§14.7 mitigation).
+ */
+export const POST = withAuth(async (req, ctx) => {
+  try {
+    const input = await parseBody(req, previewBodySchema);
+    const result = await previewBody(
+      ctx.portId,
+      input.documentKind,
+      input.recipient,
+      input.customBodyMarkdown ?? null,
+      { berthId: input.berthId, brochureLabel: input.brochureId },
+    );
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/document-sends/route.ts

@@ -0,0 +1,23 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseQuery } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listSends } from '@/lib/services/document-sends.service';
+import { listSendsQuerySchema } from '@/lib/validators/document-sends';
+
+export const GET = withAuth(async (req, ctx) => {
+  try {
+    const query = parseQuery(req, listSendsQuerySchema);
+    const data = await listSends({
+      portId: ctx.portId,
+      clientId: query.clientId,
+      interestId: query.interestId,
+      berthId: query.berthId,
+      limit: query.limit,
+    });
+    return NextResponse.json({ data });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/components/admin/brochures-admin-panel.tsx

@@ -0,0 +1,345 @@
+'use client';
+
+/**
+ * Brochures admin panel (Phase 7 §5.8).
+ *
+ * Lists every brochure for the port (including archived). Lets a
+ * `manage_settings` admin:
+ *   - Create new brochures.
+ *   - Upload a new version (direct-to-storage presigned PUT, see §11.1).
+ *   - Mark default / archive.
+ */
+import { useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Archive, FileText, Loader2, Plus, Star, Upload } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Textarea } from '@/components/ui/textarea';
+import { Switch } from '@/components/ui/switch';
+import { apiFetch } from '@/lib/api/client';
+
+interface BrochureRow {
+  id: string;
+  label: string;
+  description: string | null;
+  isDefault: boolean;
+  archivedAt: string | null;
+  versionCount: number;
+  currentVersion: {
+    id: string;
+    fileName: string;
+    fileSizeBytes: number;
+    uploadedAt: string;
+  } | null;
+}
+
+interface BrochuresResponse {
+  data: BrochureRow[];
+}
+
+interface UploadGrantResponse {
+  data: { storageKey: string; uploadUrl: string; method: 'PUT'; maxBytes: number };
+}
+
+export function BrochuresAdminPanel() {
+  const queryClient = useQueryClient();
+  const [createOpen, setCreateOpen] = useState(false);
+
+  const brochuresQuery = useQuery<BrochuresResponse>({
+    queryKey: ['brochures', 'admin'],
+    queryFn: () => apiFetch('/api/v1/admin/brochures'),
+  });
+
+  const rows = brochuresQuery.data?.data ?? [];
+
+  return (
+    <div className="space-y-4">
+      <div className="flex justify-end">
+        <Button onClick={() => setCreateOpen(true)}>
+          <Plus className="mr-2 h-4 w-4" /> New brochure
+        </Button>
+      </div>
+
+      {brochuresQuery.isLoading && (
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Loader2 className="h-4 w-4 animate-spin" /> Loading…
+        </div>
+      )}
+
+      {!brochuresQuery.isLoading && rows.length === 0 && (
+        <Card>
+          <CardContent className="py-8 text-center text-sm text-muted-foreground">
+            No brochures yet. Click &ldquo;New brochure&rdquo; to add one.
+          </CardContent>
+        </Card>
+      )}
+
+      <div className="space-y-3">
+        {rows.map((b) => (
+          <BrochureCard
+            key={b.id}
+            brochure={b}
+            onChange={() => {
+              void queryClient.invalidateQueries({ queryKey: ['brochures', 'admin'] });
+              void queryClient.invalidateQueries({ queryKey: ['brochures', 'list'] });
+            }}
+          />
+        ))}
+      </div>
+
+      <CreateBrochureDialog
+        open={createOpen}
+        onOpenChange={setCreateOpen}
+        onCreated={() => {
+          void queryClient.invalidateQueries({ queryKey: ['brochures', 'admin'] });
+        }}
+      />
+    </div>
+  );
+}
+
+function BrochureCard({ brochure, onChange }: { brochure: BrochureRow; onChange: () => void }) {
+  const [uploading, setUploading] = useState(false);
+
+  const setDefaultMutation = useMutation({
+    mutationFn: () =>
+      apiFetch(`/api/v1/admin/brochures/${brochure.id}`, {
+        method: 'PATCH',
+        body: { isDefault: true },
+      }),
+    onSuccess: () => {
+      toast.success('Default brochure updated');
+      onChange();
+    },
+  });
+
+  const archiveMutation = useMutation({
+    mutationFn: () => apiFetch(`/api/v1/admin/brochures/${brochure.id}`, { method: 'DELETE' }),
+    onSuccess: () => {
+      toast.success('Brochure archived');
+      onChange();
+    },
+  });
+
+  async function handleUpload(file: File) {
+    setUploading(true);
+    try {
+      const grant: UploadGrantResponse = await apiFetch(
+        `/api/v1/admin/brochures/${brochure.id}/versions`,
+      );
+      if (file.size > grant.data.maxBytes) {
+        throw new Error(
+          `File is too large. Max is ${(grant.data.maxBytes / 1024 / 1024).toFixed(0)}MB.`,
+        );
+      }
+      // Direct-to-storage PUT (§11.1).
+      const putRes = await fetch(grant.data.uploadUrl, {
+        method: 'PUT',
+        body: file,
+        headers: { 'Content-Type': 'application/pdf' },
+      });
+      if (!putRes.ok) throw new Error(`Upload failed: ${putRes.status}`);
+
+      const sha = await sha256Hex(file);
+      await apiFetch(`/api/v1/admin/brochures/${brochure.id}/versions`, {
+        method: 'POST',
+        body: {
+          storageKey: grant.data.storageKey,
+          fileName: file.name,
+          fileSizeBytes: file.size,
+          contentSha256: sha,
+        },
+      });
+      toast.success('New version uploaded');
+      onChange();
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Upload failed');
+    } finally {
+      setUploading(false);
+    }
+  }
+
+  return (
+    <Card className={brochure.archivedAt ? 'opacity-60' : ''}>
+      <CardHeader>
+        <CardTitle className="flex items-center justify-between text-base">
+          <span className="flex items-center gap-2">
+            <FileText className="h-4 w-4" /> {brochure.label}
+            {brochure.isDefault && (
+              <span className="flex items-center gap-1 rounded bg-primary/10 px-2 py-0.5 text-xs text-primary">
+                <Star className="h-3 w-3" /> default
+              </span>
+            )}
+            {brochure.archivedAt && (
+              <span className="rounded bg-muted px-2 py-0.5 text-xs text-muted-foreground">
+                archived
+              </span>
+            )}
+          </span>
+          <span className="text-xs text-muted-foreground">{brochure.versionCount} versions</span>
+        </CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-2">
+        {brochure.description && (
+          <p className="text-sm text-muted-foreground">{brochure.description}</p>
+        )}
+        {brochure.currentVersion && (
+          <p className="text-xs text-muted-foreground">
+            Latest: {brochure.currentVersion.fileName} (
+            {(brochure.currentVersion.fileSizeBytes / 1024 / 1024).toFixed(2)} MB,{' '}
+            {new Date(brochure.currentVersion.uploadedAt).toLocaleDateString()})
+          </p>
+        )}
+        <div className="flex gap-2 pt-2">
+          {!brochure.archivedAt && (
+            <>
+              <label className="cursor-pointer">
+                <input
+                  type="file"
+                  accept="application/pdf"
+                  className="hidden"
+                  onChange={(e) => {
+                    const file = e.target.files?.[0];
+                    if (file) void handleUpload(file);
+                    e.target.value = '';
+                  }}
+                />
+                <Button asChild variant="outline" size="sm" disabled={uploading}>
+                  <span>
+                    {uploading ? (
+                      <Loader2 className="mr-2 h-3 w-3 animate-spin" />
+                    ) : (
+                      <Upload className="mr-2 h-3 w-3" />
+                    )}
+                    Upload version
+                  </span>
+                </Button>
+              </label>
+              {!brochure.isDefault && (
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => setDefaultMutation.mutate()}
+                  disabled={setDefaultMutation.isPending}
+                >
+                  <Star className="mr-2 h-3 w-3" /> Mark default
+                </Button>
+              )}
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => archiveMutation.mutate()}
+                disabled={archiveMutation.isPending}
+              >
+                <Archive className="mr-2 h-3 w-3" /> Archive
+              </Button>
+            </>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function CreateBrochureDialog({
+  open,
+  onOpenChange,
+  onCreated,
+}: {
+  open: boolean;
+  onOpenChange: (o: boolean) => void;
+  onCreated: () => void;
+}) {
+  const [label, setLabel] = useState('');
+  const [description, setDescription] = useState('');
+  const [isDefault, setIsDefault] = useState(false);
+
+  const createMutation = useMutation({
+    mutationFn: () =>
+      apiFetch('/api/v1/admin/brochures', {
+        method: 'POST',
+        body: {
+          label,
+          description: description || null,
+          isDefault,
+        },
+      }),
+    onSuccess: () => {
+      toast.success('Brochure created. Upload a version next.');
+      setLabel('');
+      setDescription('');
+      setIsDefault(false);
+      onCreated();
+      onOpenChange(false);
+    },
+  });
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>New brochure</DialogTitle>
+          <DialogDescription>
+            Create the brochure container, then upload a PDF version on the card that appears.
+          </DialogDescription>
+        </DialogHeader>
+        <div className="space-y-3">
+          <div className="space-y-1">
+            <Label htmlFor="b-label">Label</Label>
+            <Input
+              id="b-label"
+              value={label}
+              onChange={(e) => setLabel(e.target.value)}
+              placeholder="General overview"
+            />
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="b-desc">Description (optional)</Label>
+            <Textarea
+              id="b-desc"
+              rows={2}
+              value={description}
+              onChange={(e) => setDescription(e.target.value)}
+            />
+          </div>
+          <div className="flex items-center justify-between">
+            <Label htmlFor="b-def">Set as default</Label>
+            <Switch id="b-def" checked={isDefault} onCheckedChange={setIsDefault} />
+          </div>
+        </div>
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button
+            disabled={!label.trim() || createMutation.isPending}
+            onClick={() => createMutation.mutate()}
+          >
+            {createMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+            Create
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+async function sha256Hex(file: File): Promise<string> {
+  const buf = await file.arrayBuffer();
+  const hash = await crypto.subtle.digest('SHA-256', buf);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}

src/components/admin/sales-email-config-card.tsx

@@ -0,0 +1,381 @@
+'use client';
+
+/**
+ * Sales send-from config card (Phase 7 §5.9).
+ *
+ * Lives on /[portSlug]/admin/email below the existing noreply transport
+ * card. Lets per-port admins configure the SMTP/IMAP creds + body templates
+ * that the document-sends flow uses.
+ *
+ * §14.10 enforcement: passwords are write-only. The GET endpoint never
+ * returns the decrypted value — only a `*PassIsSet` boolean. Empty
+ * password input means "leave unchanged"; explicit `null` sent over the
+ * wire means "clear".
+ */
+import { useEffect, useState } from 'react';
+import { Loader2 } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+import { apiFetch } from '@/lib/api/client';
+
+interface SalesConfigResponse {
+  data: {
+    email: {
+      fromAddress: string;
+      smtpHost: string | null;
+      smtpPort: number;
+      smtpSecure: boolean;
+      smtpUser: string | null;
+      authMethod: string;
+      smtpPassIsSet: boolean;
+      isUsable: boolean;
+    };
+    imap: {
+      imapHost: string | null;
+      imapPort: number;
+      imapUser: string | null;
+      imapPassIsSet: boolean;
+      isUsable: boolean;
+    };
+    content: {
+      noreplyFromAddress: string;
+      templateBerthPdfBody: string;
+      templateBrochureBody: string;
+      brochureMaxUploadMb: number;
+      emailAttachThresholdMb: number;
+    };
+  };
+}
+
+interface FormState {
+  fromAddress: string;
+  smtpHost: string;
+  smtpPort: number | '';
+  smtpSecure: boolean;
+  smtpUser: string;
+  smtpPass: string; // empty = unchanged
+  imapHost: string;
+  imapPort: number | '';
+  imapUser: string;
+  imapPass: string;
+  noreplyFromAddress: string;
+  templateBerthPdfBody: string;
+  templateBrochureBody: string;
+  brochureMaxUploadMb: number | '';
+  emailAttachThresholdMb: number | '';
+}
+
+const EMPTY_FORM: FormState = {
+  fromAddress: '',
+  smtpHost: '',
+  smtpPort: 587,
+  smtpSecure: false,
+  smtpUser: '',
+  smtpPass: '',
+  imapHost: '',
+  imapPort: 993,
+  imapUser: '',
+  imapPass: '',
+  noreplyFromAddress: '',
+  templateBerthPdfBody: '',
+  templateBrochureBody: '',
+  brochureMaxUploadMb: 50,
+  emailAttachThresholdMb: 15,
+};
+
+export function SalesEmailConfigCard() {
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [smtpPassSet, setSmtpPassSet] = useState(false);
+  const [imapPassSet, setImapPassSet] = useState(false);
+  const [form, setForm] = useState<FormState>(EMPTY_FORM);
+
+  async function refresh() {
+    setLoading(true);
+    try {
+      const res: SalesConfigResponse = await apiFetch('/api/v1/admin/email/sales-config');
+      setSmtpPassSet(res.data.email.smtpPassIsSet);
+      setImapPassSet(res.data.imap.imapPassIsSet);
+      setForm({
+        fromAddress: res.data.email.fromAddress,
+        smtpHost: res.data.email.smtpHost ?? '',
+        smtpPort: res.data.email.smtpPort,
+        smtpSecure: res.data.email.smtpSecure,
+        smtpUser: res.data.email.smtpUser ?? '',
+        smtpPass: '',
+        imapHost: res.data.imap.imapHost ?? '',
+        imapPort: res.data.imap.imapPort,
+        imapUser: res.data.imap.imapUser ?? '',
+        imapPass: '',
+        noreplyFromAddress: res.data.content.noreplyFromAddress,
+        templateBerthPdfBody: res.data.content.templateBerthPdfBody,
+        templateBrochureBody: res.data.content.templateBrochureBody,
+        brochureMaxUploadMb: res.data.content.brochureMaxUploadMb,
+        emailAttachThresholdMb: res.data.content.emailAttachThresholdMb,
+      });
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  useEffect(() => {
+    void refresh();
+  }, []);
+
+  function update<K extends keyof FormState>(key: K, value: FormState[K]) {
+    setForm((prev) => ({ ...prev, [key]: value }));
+  }
+
+  async function handleSave() {
+    setSaving(true);
+    try {
+      const payload: Record<string, unknown> = {
+        fromAddress: form.fromAddress || null,
+        smtpHost: form.smtpHost || null,
+        smtpPort: typeof form.smtpPort === 'number' ? form.smtpPort : null,
+        smtpSecure: form.smtpSecure,
+        smtpUser: form.smtpUser || null,
+        imapHost: form.imapHost || null,
+        imapPort: typeof form.imapPort === 'number' ? form.imapPort : null,
+        imapUser: form.imapUser || null,
+        noreplyFromAddress: form.noreplyFromAddress || null,
+        templateBerthPdfBody: form.templateBerthPdfBody,
+        templateBrochureBody: form.templateBrochureBody,
+        brochureMaxUploadMb:
+          typeof form.brochureMaxUploadMb === 'number' ? form.brochureMaxUploadMb : null,
+        emailAttachThresholdMb:
+          typeof form.emailAttachThresholdMb === 'number' ? form.emailAttachThresholdMb : null,
+      };
+      // Only send password fields when the user actually typed something.
+      if (form.smtpPass !== '') payload.smtpPass = form.smtpPass;
+      if (form.imapPass !== '') payload.imapPass = form.imapPass;
+
+      await apiFetch('/api/v1/admin/email/sales-config', { method: 'PATCH', body: payload });
+      toast.success('Sales email settings saved');
+      await refresh();
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Save failed');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  if (loading) {
+    return (
+      <Card>
+        <CardContent className="flex items-center gap-2 py-6 text-sm text-muted-foreground">
+          <Loader2 className="h-4 w-4 animate-spin" /> Loading sales email config…
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <Card>
+        <CardHeader>
+          <CardTitle>Sales send-from account</CardTitle>
+          <CardDescription>
+            SMTP credentials for human-touch outbound (brochures + per-berth PDFs). IMAP creds
+            enable the bounce monitor — leave blank to disable bounce-rejection banners. Passwords
+            are encrypted at rest and never returned by the API.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="grid gap-3 md:grid-cols-2">
+            <Field label="From address" id="sef-from">
+              <Input
+                id="sef-from"
+                type="email"
+                value={form.fromAddress}
+                onChange={(e) => update('fromAddress', e.target.value)}
+                placeholder="sales@portnimara.com"
+              />
+            </Field>
+            <Field label="SMTP host" id="sef-smtp-host">
+              <Input
+                id="sef-smtp-host"
+                value={form.smtpHost}
+                onChange={(e) => update('smtpHost', e.target.value)}
+                placeholder="smtp.gmail.com"
+              />
+            </Field>
+            <Field label="SMTP port" id="sef-smtp-port">
+              <Input
+                id="sef-smtp-port"
+                type="number"
+                value={form.smtpPort}
+                onChange={(e) =>
+                  update('smtpPort', e.target.value === '' ? '' : Number(e.target.value))
+                }
+              />
+            </Field>
+            <div className="flex items-end justify-between gap-2">
+              <Label htmlFor="sef-smtp-secure" className="text-sm">
+                SSL (true=465, false=STARTTLS on 587)
+              </Label>
+              <Switch
+                id="sef-smtp-secure"
+                checked={form.smtpSecure}
+                onCheckedChange={(v) => update('smtpSecure', v)}
+              />
+            </div>
+            <Field label="SMTP username" id="sef-smtp-user">
+              <Input
+                id="sef-smtp-user"
+                value={form.smtpUser}
+                onChange={(e) => update('smtpUser', e.target.value)}
+              />
+            </Field>
+            <Field
+              label={`SMTP password ${smtpPassSet ? '(stored — leave blank to keep)' : ''}`}
+              id="sef-smtp-pass"
+            >
+              <Input
+                id="sef-smtp-pass"
+                type="password"
+                value={form.smtpPass}
+                onChange={(e) => update('smtpPass', e.target.value)}
+                placeholder={smtpPassSet ? '••••••••' : 'app password'}
+              />
+            </Field>
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Bounce monitor (IMAP)</CardTitle>
+          <CardDescription>
+            Required only for the async-bounce banner (§14.9). Same provider account as SMTP in most
+            setups.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="grid gap-3 md:grid-cols-2">
+          <Field label="IMAP host" id="sef-imap-host">
+            <Input
+              id="sef-imap-host"
+              value={form.imapHost}
+              onChange={(e) => update('imapHost', e.target.value)}
+              placeholder="imap.gmail.com"
+            />
+          </Field>
+          <Field label="IMAP port" id="sef-imap-port">
+            <Input
+              id="sef-imap-port"
+              type="number"
+              value={form.imapPort}
+              onChange={(e) =>
+                update('imapPort', e.target.value === '' ? '' : Number(e.target.value))
+              }
+            />
+          </Field>
+          <Field label="IMAP username" id="sef-imap-user">
+            <Input
+              id="sef-imap-user"
+              value={form.imapUser}
+              onChange={(e) => update('imapUser', e.target.value)}
+            />
+          </Field>
+          <Field
+            label={`IMAP password ${imapPassSet ? '(stored — leave blank to keep)' : ''}`}
+            id="sef-imap-pass"
+          >
+            <Input
+              id="sef-imap-pass"
+              type="password"
+              value={form.imapPass}
+              onChange={(e) => update('imapPass', e.target.value)}
+              placeholder={imapPassSet ? '••••••••' : 'app password'}
+            />
+          </Field>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Body templates</CardTitle>
+          <CardDescription>
+            Default markdown bodies used when a rep doesn&rsquo;t write a custom one. Tokens like{' '}
+            <code>{'{{client.fullName}}'}</code> are expanded server-side.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <Field label="Berth PDF body" id="sef-tmpl-berth">
+            <Textarea
+              id="sef-tmpl-berth"
+              rows={6}
+              value={form.templateBerthPdfBody}
+              onChange={(e) => update('templateBerthPdfBody', e.target.value)}
+              className="font-mono text-sm"
+            />
+          </Field>
+          <Field label="Brochure body" id="sef-tmpl-broc">
+            <Textarea
+              id="sef-tmpl-broc"
+              rows={6}
+              value={form.templateBrochureBody}
+              onChange={(e) => update('templateBrochureBody', e.target.value)}
+              className="font-mono text-sm"
+            />
+          </Field>
+          <div className="grid gap-3 md:grid-cols-2">
+            <Field label="Brochure max upload (MB)" id="sef-broc-max">
+              <Input
+                id="sef-broc-max"
+                type="number"
+                value={form.brochureMaxUploadMb}
+                onChange={(e) =>
+                  update('brochureMaxUploadMb', e.target.value === '' ? '' : Number(e.target.value))
+                }
+              />
+            </Field>
+            <Field label="Attach-vs-link threshold (MB)" id="sef-attach">
+              <Input
+                id="sef-attach"
+                type="number"
+                value={form.emailAttachThresholdMb}
+                onChange={(e) =>
+                  update(
+                    'emailAttachThresholdMb',
+                    e.target.value === '' ? '' : Number(e.target.value),
+                  )
+                }
+              />
+            </Field>
+          </div>
+          <Field label="Noreply from address" id="sef-noreply">
+            <Input
+              id="sef-noreply"
+              type="email"
+              value={form.noreplyFromAddress}
+              onChange={(e) => update('noreplyFromAddress', e.target.value)}
+            />
+          </Field>
+        </CardContent>
+      </Card>
+
+      <div className="flex justify-end">
+        <Button onClick={handleSave} disabled={saving}>
+          {saving && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+          Save sales email settings
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+function Field({ label, id, children }: { label: string; id: string; children: React.ReactNode }) {
+  return (
+    <div className="space-y-1">
+      <Label htmlFor={id}>{label}</Label>
+      {children}
+    </div>
+  );
+}

src/components/berths/send-berth-pdf-dialog.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+/**
+ * Berth-detail "Send to client" dialog (Phase 7 §5.6 / §5.7).
+ *
+ * Thin wrapper around {@link SendDocumentDialog} that pins documentKind to
+ * `berth_pdf`. Used by the berth detail page header action and by the
+ * recommender panel quick-send shortcut.
+ */
+import { SendDocumentDialog } from '@/components/shared/send-document-dialog';
+
+interface SendBerthPdfDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  berthId: string;
+  berthMooringNumber: string;
+  recipient: { clientId?: string; email?: string; interestId?: string };
+  onSent?: () => void;
+}
+
+export function SendBerthPdfDialog({
+  open,
+  onOpenChange,
+  berthId,
+  berthMooringNumber,
+  recipient,
+  onSent,
+}: SendBerthPdfDialogProps) {
+  return (
+    <SendDocumentDialog
+      open={open}
+      onOpenChange={onOpenChange}
+      documentKind="berth_pdf"
+      recipient={recipient}
+      context={{ berthId }}
+      title={`Send berth ${berthMooringNumber} spec sheet`}
+      subtitle="The current PDF version is attached automatically."
+      onSent={onSent}
+    />
+  );
+}

src/components/clients/send-documents-dialog.tsx

@@ -0,0 +1,164 @@
+'use client';
+
+/**
+ * Client-detail multi-step "Send documents" dialog (Phase 7 §5.7).
+ *
+ * The client header action opens this dialog. The rep picks one of the
+ * client's interest-linked berths (to send a per-berth PDF) OR a brochure
+ * (defaults to the port default when unspecified). The actual send flow
+ * delegates to {@link SendDocumentDialog}; this wrapper is the picker.
+ */
+import { useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { FileText, Loader2, Mail } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { SendDocumentDialog } from '@/components/shared/send-document-dialog';
+import { apiFetch } from '@/lib/api/client';
+
+interface SendDocumentsDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  clientId: string;
+  clientName: string;
+  /** When the rep is launching from a specific interest, pin it. */
+  interestId?: string;
+}
+
+interface BrochureOption {
+  id: string;
+  label: string;
+  isDefault: boolean;
+  archivedAt: string | null;
+  versionCount: number;
+}
+
+interface BrochuresResponse {
+  data: BrochureOption[];
+}
+
+export function SendDocumentsDialog({
+  open,
+  onOpenChange,
+  clientId,
+  clientName,
+  interestId,
+}: SendDocumentsDialogProps) {
+  const [activeSend, setActiveSend] = useState<
+    | { kind: 'brochure'; brochureId?: string }
+    | { kind: 'berth_pdf'; berthId: string; mooring: string }
+    | null
+  >(null);
+
+  // Lightweight brochures fetch — only fires once dialog is opened.
+  const brochuresQuery = useQuery<BrochuresResponse>({
+    queryKey: ['brochures', 'list'],
+    queryFn: () => apiFetch('/api/v1/admin/brochures'),
+    enabled: open,
+  });
+
+  const usableBrochures =
+    brochuresQuery.data?.data.filter((b) => !b.archivedAt && b.versionCount > 0) ?? [];
+
+  return (
+    <>
+      <Dialog open={open && activeSend === null} onOpenChange={onOpenChange}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Send documents to {clientName}</DialogTitle>
+            <DialogDescription>
+              Pick a brochure or open the berth detail page to send a per-berth spec sheet.
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-3">
+            <div>
+              <h3 className="mb-2 flex items-center gap-2 text-sm font-semibold">
+                <Mail className="h-4 w-4" /> Brochures
+              </h3>
+              {brochuresQuery.isLoading && (
+                <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                  <Loader2 className="h-4 w-4 animate-spin" /> Loading brochures…
+                </div>
+              )}
+              {!brochuresQuery.isLoading && usableBrochures.length === 0 && (
+                <p className="text-sm text-muted-foreground">
+                  No brochures uploaded yet. Add one in /admin/brochures.
+                </p>
+              )}
+              <div className="space-y-2">
+                {usableBrochures.map((b) => (
+                  <Button
+                    key={b.id}
+                    variant="outline"
+                    className="w-full justify-between"
+                    onClick={() => setActiveSend({ kind: 'brochure', brochureId: b.id })}
+                  >
+                    <span className="flex items-center gap-2">
+                      <FileText className="h-4 w-4" />
+                      {b.label}
+                      {b.isDefault && (
+                        <span className="rounded bg-primary/10 px-2 py-0.5 text-xs text-primary">
+                          default
+                        </span>
+                      )}
+                    </span>
+                    <span className="text-xs text-muted-foreground">{b.versionCount} ver.</span>
+                  </Button>
+                ))}
+              </div>
+            </div>
+          </div>
+
+          <DialogFooter>
+            <Button variant="outline" onClick={() => onOpenChange(false)}>
+              Close
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {activeSend?.kind === 'brochure' && (
+        <SendDocumentDialog
+          open
+          onOpenChange={(o) => {
+            if (!o) {
+              setActiveSend(null);
+              onOpenChange(false);
+            }
+          }}
+          documentKind="brochure"
+          recipient={{ clientId, interestId }}
+          context={{ brochureId: activeSend.brochureId }}
+          title={`Send brochure to ${clientName}`}
+          onSent={() => setActiveSend(null)}
+        />
+      )}
+
+      {activeSend?.kind === 'berth_pdf' && (
+        <SendDocumentDialog
+          open
+          onOpenChange={(o) => {
+            if (!o) {
+              setActiveSend(null);
+              onOpenChange(false);
+            }
+          }}
+          documentKind="berth_pdf"
+          recipient={{ clientId, interestId }}
+          context={{ berthId: activeSend.berthId }}
+          title={`Send berth ${activeSend.mooring} spec sheet`}
+          onSent={() => setActiveSend(null)}
+        />
+      )}
+    </>
+  );
+}

src/components/interests/send-from-interest-button.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+/**
+ * Per-interest send launcher (Phase 7 §5.9).
+ *
+ * Shown on the interest detail page header. Opens the same picker as
+ * {@link SendDocumentsDialog} but pre-pins the `interestId` so the resulting
+ * audit row is filed against the interest timeline.
+ */
+import { useState } from 'react';
+import { Send } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { SendDocumentsDialog } from '@/components/clients/send-documents-dialog';
+
+interface SendFromInterestButtonProps {
+  interestId: string;
+  clientId: string;
+  clientName: string;
+}
+
+export function SendFromInterestButton({
+  interestId,
+  clientId,
+  clientName,
+}: SendFromInterestButtonProps) {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
+        <Send className="mr-2 h-4 w-4" /> Send documents
+      </Button>
+      <SendDocumentsDialog
+        open={open}
+        onOpenChange={setOpen}
+        clientId={clientId}
+        clientName={clientName}
+        interestId={interestId}
+      />
+    </>
+  );
+}

src/components/shared/send-document-dialog.tsx

@@ -0,0 +1,277 @@
+'use client';
+
+/**
+ * Shared send-document dialog (Phase 7).
+ *
+ * Used by:
+ *   - {@link SendBerthPdfDialog} (berths/) — single berth, recipient picker.
+ *   - {@link SendBrochureDialog}    (clients/, interests/) — brochure picker.
+ *   - The interest "send from interest" pattern reuses both via a wrapper.
+ *
+ * §14.7 mitigations enforced client-side:
+ *   - Recipient email is shown verbatim in the confirm step (no quick-send).
+ *   - Pre-send dry-run calls /preview first; the Send button is disabled
+ *     until the unresolved-tokens list is empty.
+ *   - Body length capped at 50KB; char count visible.
+ */
+
+import { useEffect, useMemo, useState } from 'react';
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { Loader2 } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Label } from '@/components/ui/label';
+import { Textarea } from '@/components/ui/textarea';
+import { Input } from '@/components/ui/input';
+import { apiFetch } from '@/lib/api/client';
+
+const BODY_MAX = 50_000;
+
+export type DocumentKind = 'berth_pdf' | 'brochure';
+
+interface SendDocumentDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  documentKind: DocumentKind;
+  /** Pre-filled recipient. Leave both blank to let the rep type one. */
+  recipient: { clientId?: string; email?: string; interestId?: string };
+  /** Either a berthId (for berth_pdf) or brochureId (for brochure). */
+  context: { berthId?: string; brochureId?: string };
+  /** Title displayed in the dialog header. */
+  title: string;
+  /** Short context line under the title (e.g. "Berth A1 — primary version"). */
+  subtitle?: string;
+  onSent?: () => void;
+}
+
+interface PreviewResponse {
+  data: { html: string; markdown: string; unresolved: string[] };
+}
+
+export function SendDocumentDialog({
+  open,
+  onOpenChange,
+  documentKind,
+  recipient,
+  context,
+  title,
+  subtitle,
+  onSent,
+}: SendDocumentDialogProps) {
+  const [step, setStep] = useState<'compose' | 'confirm'>('compose');
+  const [emailOverride, setEmailOverride] = useState(recipient.email ?? '');
+  const [customBody, setCustomBody] = useState('');
+
+  useEffect(() => {
+    if (open) {
+      setStep('compose');
+      setEmailOverride(recipient.email ?? '');
+      setCustomBody('');
+    }
+  }, [open, recipient.email]);
+
+  const recipientForApi = useMemo(
+    () => ({
+      clientId: recipient.clientId,
+      email: emailOverride || recipient.email,
+      interestId: recipient.interestId,
+    }),
+    [recipient.clientId, recipient.email, recipient.interestId, emailOverride],
+  );
+
+  // Live preview via /api/v1/document-sends/preview. Re-runs whenever the
+  // body text or recipient changes (debounce-by-react-query for free).
+  const previewQuery = useQuery<PreviewResponse>({
+    queryKey: [
+      'document-sends-preview',
+      documentKind,
+      context.berthId ?? null,
+      context.brochureId ?? null,
+      recipientForApi.clientId ?? null,
+      recipientForApi.email ?? null,
+      customBody,
+    ],
+    queryFn: () =>
+      apiFetch('/api/v1/document-sends/preview', {
+        method: 'POST',
+        body: {
+          documentKind,
+          recipient: recipientForApi,
+          berthId: context.berthId,
+          brochureId: context.brochureId,
+          customBodyMarkdown: customBody.trim() ? customBody : undefined,
+        },
+      }),
+    enabled: open && Boolean(recipientForApi.clientId || recipientForApi.email),
+  });
+
+  type SendResp = { data: { error?: string; deliveredAsAttachment: boolean } };
+  const sendMutation = useMutation<SendResp, Error, void>({
+    mutationFn: async (): Promise<SendResp> => {
+      const endpoint =
+        documentKind === 'berth_pdf'
+          ? '/api/v1/document-sends/berth-pdf'
+          : '/api/v1/document-sends/brochure';
+      const body =
+        documentKind === 'berth_pdf'
+          ? {
+              berthId: context.berthId,
+              recipient: recipientForApi,
+              customBodyMarkdown: customBody.trim() ? customBody : undefined,
+            }
+          : {
+              brochureId: context.brochureId,
+              recipient: recipientForApi,
+              customBodyMarkdown: customBody.trim() ? customBody : undefined,
+            };
+      return (await apiFetch<SendResp>(endpoint, { method: 'POST', body })) as SendResp;
+    },
+    onSuccess: (resp) => {
+      if (resp.data.error) {
+        toast.error(`Send failed: ${resp.data.error}`);
+      } else {
+        toast.success(
+          resp.data.deliveredAsAttachment
+            ? 'Sent as attachment'
+            : 'Sent (large file delivered as download link)',
+        );
+        onSent?.();
+        onOpenChange(false);
+      }
+    },
+    onError: (err) => {
+      toast.error(err instanceof Error ? err.message : 'Send failed');
+    },
+  });
+
+  const unresolved = previewQuery.data?.data.unresolved ?? [];
+  const previewHtml = previewQuery.data?.data.html ?? '';
+
+  const recipientResolved = Boolean(recipientForApi.clientId || recipientForApi.email);
+  const canPreview = recipientResolved;
+  const canSend = step === 'confirm' && unresolved.length === 0 && !sendMutation.isPending;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-2xl">
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          {subtitle && <DialogDescription>{subtitle}</DialogDescription>}
+        </DialogHeader>
+
+        {step === 'compose' ? (
+          <div className="space-y-4">
+            <div className="space-y-1">
+              <Label htmlFor="ds-email">Recipient email</Label>
+              <Input
+                id="ds-email"
+                type="email"
+                value={emailOverride}
+                onChange={(e) => setEmailOverride(e.target.value)}
+                placeholder={recipient.email ? '' : 'recipient@example.com'}
+              />
+              <p className="text-xs text-muted-foreground">
+                {recipient.clientId
+                  ? 'Defaults to the client primary email; override here if needed.'
+                  : 'Type the address you want to send to.'}
+              </p>
+            </div>
+
+            <div className="space-y-1">
+              <Label htmlFor="ds-body">Message body</Label>
+              <Textarea
+                id="ds-body"
+                rows={10}
+                value={customBody}
+                onChange={(e) => setCustomBody(e.target.value.slice(0, BODY_MAX))}
+                placeholder="Leave blank to use the port template…"
+                className="font-mono text-sm"
+              />
+              <div className="flex items-center justify-between text-xs text-muted-foreground">
+                <span>Markdown supported. Tokens like {'{{client.fullName}}'} are expanded.</span>
+                <span>
+                  {customBody.length} / {BODY_MAX}
+                </span>
+              </div>
+            </div>
+
+            {canPreview && previewQuery.isSuccess && (
+              <div className="rounded border bg-muted/30 p-3">
+                <p className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                  Preview
+                </p>
+                <div
+                  className="prose prose-sm max-w-none"
+                  dangerouslySetInnerHTML={{ __html: previewHtml }}
+                />
+                {unresolved.length > 0 && (
+                  <p className="mt-3 rounded border border-amber-300 bg-amber-50 p-2 text-xs text-amber-900">
+                    Unresolved merge fields: {unresolved.join(', ')}. Replace these before sending.
+                  </p>
+                )}
+              </div>
+            )}
+            {previewQuery.isLoading && canPreview && (
+              <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                <Loader2 className="h-4 w-4 animate-spin" /> Rendering preview…
+              </div>
+            )}
+          </div>
+        ) : (
+          <div className="space-y-3">
+            <div className="rounded border bg-muted/30 p-3 text-sm">
+              <p>
+                Sending to: <span className="font-mono">{recipientForApi.email}</span>
+              </p>
+              {context.berthId && <p>Document: berth PDF</p>}
+              {context.brochureId !== undefined && <p>Document: brochure</p>}
+            </div>
+            <div
+              className="prose prose-sm max-w-none rounded border p-3"
+              dangerouslySetInnerHTML={{ __html: previewHtml }}
+            />
+            <p className="text-xs text-muted-foreground">
+              The PDF file is added by the system after the body — your text won&rsquo;t override
+              it.
+            </p>
+          </div>
+        )}
+
+        <DialogFooter className="gap-2">
+          {step === 'compose' ? (
+            <>
+              <Button variant="outline" onClick={() => onOpenChange(false)}>
+                Cancel
+              </Button>
+              <Button
+                onClick={() => setStep('confirm')}
+                disabled={!recipientResolved || unresolved.length > 0 || previewQuery.isLoading}
+              >
+                Review & send
+              </Button>
+            </>
+          ) : (
+            <>
+              <Button variant="outline" onClick={() => setStep('compose')}>
+                Back
+              </Button>
+              <Button onClick={() => sendMutation.mutate()} disabled={!canSend}>
+                {sendMutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+                Confirm and send
+              </Button>
+            </>
+          )}
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

src/lib/db/migrations/0031_brochures_and_document_sends.sql

@@ -0,0 +1,59 @@
+CREATE TABLE "brochure_versions" (
+	"id" text PRIMARY KEY NOT NULL,
+	"brochure_id" text NOT NULL,
+	"version_number" integer NOT NULL,
+	"storage_key" text NOT NULL,
+	"file_name" text NOT NULL,
+	"file_size_bytes" integer NOT NULL,
+	"content_sha256" text NOT NULL,
+	"uploaded_by" text NOT NULL,
+	"uploaded_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"download_url_expires_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE TABLE "brochures" (
+	"id" text PRIMARY KEY NOT NULL,
+	"port_id" text NOT NULL,
+	"label" text NOT NULL,
+	"description" text,
+	"is_default" boolean DEFAULT false NOT NULL,
+	"archived_at" timestamp with time zone,
+	"created_by" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "document_sends" (
+	"id" text PRIMARY KEY NOT NULL,
+	"port_id" text NOT NULL,
+	"client_id" text,
+	"interest_id" text,
+	"recipient_email" text NOT NULL,
+	"document_kind" text NOT NULL,
+	"berth_id" text,
+	"berth_pdf_version_id" text,
+	"brochure_id" text,
+	"brochure_version_id" text,
+	"body_markdown" text,
+	"sent_by_user_id" text NOT NULL,
+	"from_address" text NOT NULL,
+	"sent_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"message_id" text,
+	"fallback_to_link_reason" text,
+	"failed_at" timestamp with time zone,
+	"error_reason" text
+);
+--> statement-breakpoint
+ALTER TABLE "brochure_versions" ADD CONSTRAINT "brochure_versions_brochure_id_brochures_id_fk" FOREIGN KEY ("brochure_id") REFERENCES "public"."brochures"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "brochures" ADD CONSTRAINT "brochures_port_id_ports_id_fk" FOREIGN KEY ("port_id") REFERENCES "public"."ports"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "document_sends" ADD CONSTRAINT "document_sends_port_id_ports_id_fk" FOREIGN KEY ("port_id") REFERENCES "public"."ports"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "document_sends" ADD CONSTRAINT "document_sends_client_id_clients_id_fk" FOREIGN KEY ("client_id") REFERENCES "public"."clients"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "document_sends" ADD CONSTRAINT "document_sends_interest_id_interests_id_fk" FOREIGN KEY ("interest_id") REFERENCES "public"."interests"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "document_sends" ADD CONSTRAINT "document_sends_berth_id_berths_id_fk" FOREIGN KEY ("berth_id") REFERENCES "public"."berths"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "document_sends" ADD CONSTRAINT "document_sends_brochure_id_brochures_id_fk" FOREIGN KEY ("brochure_id") REFERENCES "public"."brochures"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "document_sends" ADD CONSTRAINT "document_sends_brochure_version_id_brochure_versions_id_fk" FOREIGN KEY ("brochure_version_id") REFERENCES "public"."brochure_versions"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "idx_brochure_versions_brochure" ON "brochure_versions" USING btree ("brochure_id","uploaded_at");--> statement-breakpoint
+CREATE INDEX "idx_brochures_port" ON "brochures" USING btree ("port_id");--> statement-breakpoint
+CREATE INDEX "idx_ds_client" ON "document_sends" USING btree ("client_id","sent_at");--> statement-breakpoint
+CREATE INDEX "idx_ds_interest" ON "document_sends" USING btree ("interest_id","sent_at");--> statement-breakpoint
+CREATE INDEX "idx_ds_berth" ON "document_sends" USING btree ("berth_id","sent_at");--> statement-breakpoint
+CREATE INDEX "idx_ds_port" ON "document_sends" USING btree ("port_id","sent_at");

src/lib/db/migrations/meta/_journal.json

@@ -218,6 +218,13 @@
       "when": 1777944021221,
       "tag": "0030_berth_pdf_versions",
       "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "7",
+      "when": 1777944191753,
+      "tag": "0031_brochures_and_document_sends",
+      "breakpoints": true
     }
   ]
 }

src/lib/db/schema/brochures.ts

@@ -0,0 +1,127 @@
+import { pgTable, text, boolean, integer, timestamp, index } from 'drizzle-orm/pg-core';
+
+import { ports } from './ports';
+import { clients } from './clients';
+import { interests } from './interests';
+import { berths } from './berths';
+
+/**
+ * Port-wide brochures (Phase 7 — see plan §3.3 / §4.8).
+ *
+ * Each port can have multiple brochures (e.g. "General", "Investor Pack")
+ * with one marked as `isDefault`. Archived brochures stay queryable for
+ * audit purposes but are hidden from the send-out picker.
+ */
+export const brochures = pgTable(
+  'brochures',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    portId: text('port_id')
+      .notNull()
+      .references(() => ports.id, { onDelete: 'cascade' }),
+    label: text('label').notNull(),
+    description: text('description'),
+    isDefault: boolean('is_default').notNull().default(false),
+    archivedAt: timestamp('archived_at', { withTimezone: true }),
+    createdBy: text('created_by').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index('idx_brochures_port').on(table.portId)],
+);
+
+/**
+ * Versioned brochure files. Identical lifecycle to `berth_pdf_versions`:
+ * each upload creates a new immutable row with a monotonic version number
+ * per brochure. `storageKey` follows the §4.7a renamed convention.
+ */
+export const brochureVersions = pgTable(
+  'brochure_versions',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    brochureId: text('brochure_id')
+      .notNull()
+      .references(() => brochures.id, { onDelete: 'cascade' }),
+    versionNumber: integer('version_number').notNull(),
+    /** Object key in the active storage backend (renamed from `s3_key` per §4.7a). */
+    storageKey: text('storage_key').notNull(),
+    fileName: text('file_name').notNull(),
+    fileSizeBytes: integer('file_size_bytes').notNull(),
+    contentSha256: text('content_sha256').notNull(),
+    uploadedBy: text('uploaded_by').notNull(),
+    uploadedAt: timestamp('uploaded_at', { withTimezone: true }).notNull().defaultNow(),
+    /** Cached signed-URL expiry per §11.1 — re-sign only when within 1h of expiry. */
+    downloadUrlExpiresAt: timestamp('download_url_expires_at', { withTimezone: true }),
+  },
+  (table) => [index('idx_brochure_versions_brochure').on(table.brochureId, table.uploadedAt)],
+);
+
+/**
+ * Send-out audit log for berth PDFs and brochures (Phase 7 — plan §3.3).
+ *
+ * One row per recipient per send. `documentKind` discriminates between
+ * `'berth_pdf'` and `'brochure'`; the corresponding `*_version_id` column
+ * pins the exact version sent.
+ *
+ * `berthPdfVersionId` is intentionally a plain text column (no FK) — the
+ * referenced table `berth_pdf_versions` is owned by Phase 6b. Loose-coupling
+ * keeps the two phases independent (per Phase 7 task brief).
+ *
+ * `failedAt` and `errorReason` capture send failures (SMTP auth, transport
+ * errors). Failed sends are still written so reps can see "I clicked send
+ * but it didn't go" in the timeline (per §14.7).
+ */
+export const documentSends = pgTable(
+  'document_sends',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    portId: text('port_id')
+      .notNull()
+      .references(() => ports.id),
+    /** Either client_id or interest_id is set (or both). */
+    clientId: text('client_id').references(() => clients.id),
+    interestId: text('interest_id').references(() => interests.id),
+    recipientEmail: text('recipient_email').notNull(),
+    /** 'berth_pdf' | 'brochure' */
+    documentKind: text('document_kind').notNull(),
+    berthId: text('berth_id').references(() => berths.id),
+    /** Forward FK ref — berth_pdf_versions defined in Phase 6b. Loose-coupled. */
+    berthPdfVersionId: text('berth_pdf_version_id'),
+    brochureId: text('brochure_id').references(() => brochures.id),
+    brochureVersionId: text('brochure_version_id').references(() => brochureVersions.id),
+    /** Exact body used (after merge-field expansion + sanitization). */
+    bodyMarkdown: text('body_markdown'),
+    sentByUserId: text('sent_by_user_id').notNull(),
+    fromAddress: text('from_address').notNull(),
+    sentAt: timestamp('sent_at', { withTimezone: true }).notNull().defaultNow(),
+    /** SMTP provider message-id for deliverability tracking. */
+    messageId: text('message_id'),
+    /** When the initial send had its attachment dropped because the SMTP server
+     *  rejected the size (552 etc.) and the system retried with a download
+     *  link, this captures the rejection reason for ops visibility. Null when
+     *  the original send went through as-is. */
+    fallbackToLinkReason: text('fallback_to_link_reason'),
+    /** Set when the SMTP send transaction itself failed (auth/transport/etc). */
+    failedAt: timestamp('failed_at', { withTimezone: true }),
+    /** Human-readable failure reason; only meaningful when failedAt is non-null. */
+    errorReason: text('error_reason'),
+  },
+  (t) => [
+    index('idx_ds_client').on(t.clientId, t.sentAt),
+    index('idx_ds_interest').on(t.interestId, t.sentAt),
+    index('idx_ds_berth').on(t.berthId, t.sentAt),
+    index('idx_ds_port').on(t.portId, t.sentAt),
+  ],
+);
+
+export type Brochure = typeof brochures.$inferSelect;
+export type NewBrochure = typeof brochures.$inferInsert;
+export type BrochureVersion = typeof brochureVersions.$inferSelect;
+export type NewBrochureVersion = typeof brochureVersions.$inferInsert;
+export type DocumentSend = typeof documentSends.$inferSelect;
+export type NewDocumentSend = typeof documentSends.$inferInsert;

src/lib/db/schema/index.ts

@@ -25,6 +25,9 @@ export * from './reservations';
 // Documents & Files
 export * from './documents';
 
+// Brochures + send-outs (Phase 7)
+export * from './brochures';
+
 // Financial
 export * from './financial';
 

src/lib/db/schema/relations.ts

@@ -58,6 +58,9 @@ import {
   formSubmissions,
 } from './documents';
 
+// Brochures + send-outs (Phase 7)
+import { brochures, brochureVersions, documentSends } from './brochures';
+
 // Financial
 import { expenses, invoices, invoiceLineItems, invoiceExpenses } from './financial';
 
@@ -883,3 +886,49 @@ export const residentialInterestsRelations = relations(residentialInterests, ({
     references: [residentialClients.id],
   }),
 }));
+
+// ─── Brochures + send-outs (Phase 7) ──────────────────────────────────────────
+
+export const brochuresRelations = relations(brochures, ({ one, many }) => ({
+  port: one(ports, {
+    fields: [brochures.portId],
+    references: [ports.id],
+  }),
+  versions: many(brochureVersions),
+  sends: many(documentSends),
+}));
+
+export const brochureVersionsRelations = relations(brochureVersions, ({ one, many }) => ({
+  brochure: one(brochures, {
+    fields: [brochureVersions.brochureId],
+    references: [brochures.id],
+  }),
+  sends: many(documentSends),
+}));
+
+export const documentSendsRelations = relations(documentSends, ({ one }) => ({
+  port: one(ports, {
+    fields: [documentSends.portId],
+    references: [ports.id],
+  }),
+  client: one(clients, {
+    fields: [documentSends.clientId],
+    references: [clients.id],
+  }),
+  interest: one(interests, {
+    fields: [documentSends.interestId],
+    references: [interests.id],
+  }),
+  berth: one(berths, {
+    fields: [documentSends.berthId],
+    references: [berths.id],
+  }),
+  brochure: one(brochures, {
+    fields: [documentSends.brochureId],
+    references: [brochures.id],
+  }),
+  brochureVersion: one(brochureVersions, {
+    fields: [documentSends.brochureVersionId],
+    references: [brochureVersions.id],
+  }),
+}));

src/lib/services/brochures.service.ts

@@ -0,0 +1,278 @@
+/**
+ * Brochures + brochure-versions service (Phase 7 — see plan §3.3 / §4.7).
+ *
+ * Brochures are port-wide marketing PDFs (the sample `Port-Nimara-Brochure-March-2025`
+ * is 10.26 MB). Each `brochures` row groups a logical brochure (e.g.
+ * "Investor Pack"); each `brochure_versions` row is an immutable upload tied
+ * to that brochure. The default brochure is the one the send-out flow picks
+ * when the rep doesn't pick explicitly (§14.7).
+ *
+ * Storage goes through `getStorageBackend()` (Phase 6a) — never minio
+ * directly. The version row's `storageKey` follows the §4.7a convention.
+ */
+import { and, asc, desc, eq, isNull } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { brochures, brochureVersions, ports } from '@/lib/db/schema';
+import type { Brochure, BrochureVersion } from '@/lib/db/schema';
+import { ForbiddenError, NotFoundError, ValidationError } from '@/lib/errors';
+import { getStorageBackend } from '@/lib/storage';
+import { buildStoragePath } from '@/lib/minio';
+import { logger } from '@/lib/logger';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface BrochureWithCurrentVersion extends Brochure {
+  currentVersion: BrochureVersion | null;
+  versionCount: number;
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+async function loadPortSlug(portId: string): Promise<string> {
+  const port = await db.query.ports.findFirst({ where: eq(ports.id, portId) });
+  if (!port) throw new NotFoundError('Port');
+  return port.slug;
+}
+
+// ─── List ────────────────────────────────────────────────────────────────────
+
+/**
+ * List all brochures for a port. By default returns only non-archived rows;
+ * pass `{ includeArchived: true }` for the admin manage page.
+ */
+export async function listBrochures(
+  portId: string,
+  opts: { includeArchived?: boolean } = {},
+): Promise<BrochureWithCurrentVersion[]> {
+  const baseRows = await db.query.brochures.findMany({
+    where: opts.includeArchived
+      ? eq(brochures.portId, portId)
+      : and(eq(brochures.portId, portId), isNull(brochures.archivedAt)),
+    orderBy: [desc(brochures.isDefault), asc(brochures.label)],
+  });
+
+  if (baseRows.length === 0) return [];
+
+  const ids = baseRows.map((r) => r.id);
+  const versions = await db
+    .select()
+    .from(brochureVersions)
+    .where(eq(brochureVersions.brochureId, ids[0]!));
+  // Pull all versions for these brochures in one round trip.
+  const allVersions =
+    ids.length === 1
+      ? versions
+      : await db.query.brochureVersions.findMany({
+          where: (bv, { inArray }) => inArray(bv.brochureId, ids),
+          orderBy: [desc(brochureVersions.uploadedAt)],
+        });
+
+  return baseRows.map((row) => {
+    const versionsForRow = allVersions.filter((v) => v.brochureId === row.id);
+    versionsForRow.sort(
+      (a, b) => new Date(b.uploadedAt).getTime() - new Date(a.uploadedAt).getTime(),
+    );
+    return {
+      ...row,
+      currentVersion: versionsForRow[0] ?? null,
+      versionCount: versionsForRow.length,
+    };
+  });
+}
+
+export async function getBrochure(
+  portId: string,
+  brochureId: string,
+): Promise<BrochureWithCurrentVersion> {
+  const row = await db.query.brochures.findFirst({
+    where: and(eq(brochures.id, brochureId), eq(brochures.portId, portId)),
+  });
+  if (!row) throw new NotFoundError('Brochure');
+
+  const versions = await db.query.brochureVersions.findMany({
+    where: eq(brochureVersions.brochureId, brochureId),
+    orderBy: [desc(brochureVersions.uploadedAt)],
+  });
+  return { ...row, currentVersion: versions[0] ?? null, versionCount: versions.length };
+}
+
+/**
+ * Resolve the brochure that the send-out flow should default to. Returns the
+ * default brochure when one exists and is non-archived; falls back to the
+ * most recently created non-archived brochure with a version; null when
+ * the port has no usable brochures (the send UI hides the button — §14.7).
+ */
+export async function getDefaultBrochure(
+  portId: string,
+): Promise<BrochureWithCurrentVersion | null> {
+  const all = await listBrochures(portId, { includeArchived: false });
+  const usable = all.filter((b) => b.currentVersion !== null);
+  if (usable.length === 0) return null;
+  const flaggedDefault = usable.find((b) => b.isDefault);
+  if (flaggedDefault) return flaggedDefault;
+  return usable[0]!;
+}
+
+// ─── Mutations ───────────────────────────────────────────────────────────────
+
+export interface CreateBrochureInput {
+  portId: string;
+  label: string;
+  description?: string | null;
+  isDefault?: boolean;
+  createdBy: string;
+}
+
+export async function createBrochure(input: CreateBrochureInput): Promise<Brochure> {
+  if (!input.label.trim()) throw new ValidationError('Brochure label is required');
+
+  // If this is being created as default, clear any existing default first
+  // so we maintain the invariant: at most one default per port.
+  return db.transaction(async (tx) => {
+    if (input.isDefault) {
+      await tx
+        .update(brochures)
+        .set({ isDefault: false })
+        .where(and(eq(brochures.portId, input.portId), eq(brochures.isDefault, true)));
+    }
+    const [row] = await tx
+      .insert(brochures)
+      .values({
+        portId: input.portId,
+        label: input.label.trim(),
+        description: input.description ?? null,
+        isDefault: input.isDefault ?? false,
+        createdBy: input.createdBy,
+      })
+      .returning();
+    if (!row) throw new Error('Failed to create brochure');
+    return row;
+  });
+}
+
+export interface UpdateBrochureInput {
+  label?: string;
+  description?: string | null;
+  isDefault?: boolean;
+}
+
+export async function updateBrochure(
+  portId: string,
+  brochureId: string,
+  patch: UpdateBrochureInput,
+): Promise<Brochure> {
+  const existing = await db.query.brochures.findFirst({
+    where: and(eq(brochures.id, brochureId), eq(brochures.portId, portId)),
+  });
+  if (!existing) throw new NotFoundError('Brochure');
+
+  return db.transaction(async (tx) => {
+    if (patch.isDefault === true) {
+      await tx
+        .update(brochures)
+        .set({ isDefault: false })
+        .where(and(eq(brochures.portId, portId), eq(brochures.isDefault, true)));
+    }
+    const updates: Partial<Brochure> = {};
+    if (patch.label !== undefined) updates.label = patch.label.trim();
+    if (patch.description !== undefined) updates.description = patch.description;
+    if (patch.isDefault !== undefined) updates.isDefault = patch.isDefault;
+    const [row] = await tx
+      .update(brochures)
+      .set(updates)
+      .where(eq(brochures.id, brochureId))
+      .returning();
+    if (!row) throw new Error('Failed to update brochure');
+    return row;
+  });
+}
+
+export async function archiveBrochure(portId: string, brochureId: string): Promise<void> {
+  const existing = await db.query.brochures.findFirst({
+    where: and(eq(brochures.id, brochureId), eq(brochures.portId, portId)),
+  });
+  if (!existing) throw new NotFoundError('Brochure');
+  await db
+    .update(brochures)
+    .set({ archivedAt: new Date(), isDefault: false })
+    .where(eq(brochures.id, brochureId));
+}
+
+// ─── Versions ────────────────────────────────────────────────────────────────
+
+export interface RegisterBrochureVersionInput {
+  portId: string;
+  brochureId: string;
+  storageKey: string;
+  fileName: string;
+  fileSizeBytes: number;
+  contentSha256: string;
+  uploadedBy: string;
+}
+
+/**
+ * After a presigned upload completes, the browser POSTs the metadata back
+ * here. We HEAD the storage key to verify the file exists at the claimed
+ * size + content-type (per §11.1 "Server-side validation"), then write the
+ * version row + bump version number.
+ */
+export async function registerBrochureVersion(
+  input: RegisterBrochureVersionInput,
+): Promise<BrochureVersion> {
+  const brochure = await db.query.brochures.findFirst({
+    where: and(eq(brochures.id, input.brochureId), eq(brochures.portId, input.portId)),
+  });
+  if (!brochure) throw new NotFoundError('Brochure');
+  if (brochure.archivedAt) {
+    throw new ForbiddenError('Cannot upload a version to an archived brochure');
+  }
+
+  const storage = await getStorageBackend();
+  const head = await storage.head(input.storageKey);
+  if (!head) throw new ValidationError('Uploaded object not found in storage');
+  if (head.sizeBytes !== input.fileSizeBytes) {
+    logger.warn(
+      { expected: input.fileSizeBytes, actual: head.sizeBytes, key: input.storageKey },
+      'Brochure upload size mismatch',
+    );
+    throw new ValidationError('Uploaded object size does not match metadata');
+  }
+
+  // Determine the next version number for this brochure.
+  const existing = await db.query.brochureVersions.findMany({
+    where: eq(brochureVersions.brochureId, input.brochureId),
+    orderBy: [desc(brochureVersions.versionNumber)],
+    limit: 1,
+  });
+  const nextVersion = (existing[0]?.versionNumber ?? 0) + 1;
+
+  const [row] = await db
+    .insert(brochureVersions)
+    .values({
+      brochureId: input.brochureId,
+      versionNumber: nextVersion,
+      storageKey: input.storageKey,
+      fileName: input.fileName,
+      fileSizeBytes: input.fileSizeBytes,
+      contentSha256: input.contentSha256,
+      uploadedBy: input.uploadedBy,
+    })
+    .returning();
+  if (!row) throw new Error('Failed to record brochure version');
+  return row;
+}
+
+/**
+ * Generate a storage key the client should PUT to. Caller hands the returned
+ * key + URL to the browser; after upload the browser calls
+ * `registerBrochureVersion` with the same key.
+ */
+export async function generateBrochureStorageKey(
+  portId: string,
+  brochureId: string,
+): Promise<string> {
+  const portSlug = await loadPortSlug(portId);
+  const fileId = crypto.randomUUID();
+  return buildStoragePath(portSlug, 'brochures', brochureId, fileId, 'pdf');
+}

src/lib/services/document-sends.service.ts

@@ -0,0 +1,531 @@
+/**
+ * Sales send-out flow (Phase 7 — see plan §4.8 / §11.1 / §14.7).
+ *
+ * Sends per-berth PDFs and brochures to a client recipient, attaching the
+ * file when it's at-or-below the configured threshold or falling back to a
+ * 24h signed-URL link when it's larger. Every send writes one row to
+ * `document_sends` (success OR failure) so the rep can see the outcome in
+ * the timeline.
+ *
+ * §14.7 critical mitigations implemented here:
+ *
+ *   - **Body XSS** — bodies go through `renderEmailBody()` (HTML-escape +
+ *     allowlist of markdown rules) before reaching nodemailer.
+ *   - **Recipient typo** — recipient email validated against a strict regex
+ *     before the SMTP transaction.
+ *   - **Unresolved merge fields** — `findUnresolvedTokens()` is exported
+ *     for the dry-run UI; the service blocks sends with unresolved tokens
+ *     unless `allowUnresolved: true` is explicitly passed (test-only).
+ *   - **SMTP failure** — every transport rejection writes a `failedAt` row
+ *     with `errorReason` and surfaces a typed error to the API.
+ *   - **Hourly rate limit** — 50 sends/user/hour individual.
+ *   - **Size threshold fallback** — files larger than the per-port
+ *     `email_attach_threshold_mb` go as a signed-URL link in the body
+ *     instead of an attachment (§11.1).
+ */
+
+import { Readable } from 'node:stream';
+
+import { and, desc, eq } from 'drizzle-orm';
+import type { SentMessageInfo } from 'nodemailer';
+
+import { db } from '@/lib/db';
+import {
+  brochures,
+  brochureVersions,
+  documentSends,
+  berths,
+  berthPdfVersions,
+  clients,
+  clientContacts,
+  ports,
+} from '@/lib/db/schema';
+import type { DocumentSend } from '@/lib/db/schema';
+import { ForbiddenError, NotFoundError, ValidationError } from '@/lib/errors';
+import { logger } from '@/lib/logger';
+import { checkRateLimit } from '@/lib/rate-limit';
+import { getStorageBackend } from '@/lib/storage';
+import {
+  EMAIL_BODY_MAX_BYTES,
+  expandMergeTokens,
+  findUnresolvedTokens,
+  renderEmailBody,
+} from '@/lib/utils/markdown-email';
+import { getDefaultBrochure } from '@/lib/services/brochures.service';
+import {
+  createSalesTransporter,
+  getSalesContentConfig,
+} from '@/lib/services/sales-email-config.service';
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export interface SendRecipientInput {
+  /** Existing client ID (resolves the primary email automatically). */
+  clientId?: string;
+  /** Optional explicit address override (for cases where a client has multiple). */
+  email?: string;
+  /** Optional interest pin so the audit row links into the interest timeline. */
+  interestId?: string;
+}
+
+export interface SendBerthPdfInput {
+  portId: string;
+  berthId: string;
+  recipient: SendRecipientInput;
+  /** When provided, replaces the per-port template. Still passes through
+   *  merge expansion + sanitization. */
+  customBodyMarkdown?: string;
+  sentBy: string;
+  ipAddress: string;
+  userAgent: string;
+  /** Test-only: skip the unresolved-merge-field block. */
+  allowUnresolved?: boolean;
+}
+
+export interface SendBrochureInput {
+  portId: string;
+  /** Defaults to the port's default brochure when omitted. */
+  brochureId?: string;
+  recipient: SendRecipientInput;
+  customBodyMarkdown?: string;
+  sentBy: string;
+  ipAddress: string;
+  userAgent: string;
+  allowUnresolved?: boolean;
+}
+
+export interface SendResult {
+  send: DocumentSend;
+  /** True when the file was attached; false when a signed-URL link was used. */
+  deliveredAsAttachment: boolean;
+  /** Set when the transport rejected — the row carries `failedAt`. */
+  error?: string;
+}
+
+// ─── Public dry-run / preview helpers (used by the modal) ────────────────────
+
+/**
+ * Compute the merge-value bag for a given send context. The same map is used
+ * by the dry-run preview AND the actual send so the rep sees exactly what
+ * gets posted.
+ */
+export async function buildMergeValues(
+  portId: string,
+  recipient: SendRecipientInput,
+  context: { berthId?: string; brochureLabel?: string } = {},
+): Promise<Record<string, string>> {
+  const values: Record<string, string> = {};
+  values['{{date.today}}'] = new Date().toISOString().slice(0, 10);
+  values['{{date.year}}'] = String(new Date().getFullYear());
+
+  const port = await db.query.ports.findFirst({ where: eq(ports.id, portId) });
+  if (port) {
+    values['{{port.name}}'] = port.name;
+    if (port.defaultCurrency) values['{{port.defaultCurrency}}'] = port.defaultCurrency;
+  }
+
+  if (recipient.clientId) {
+    const client = await db.query.clients.findFirst({
+      where: and(eq(clients.id, recipient.clientId), eq(clients.portId, portId)),
+    });
+    if (client) {
+      if (client.fullName) values['{{client.fullName}}'] = client.fullName;
+      if (client.nationalityIso) values['{{client.nationality}}'] = client.nationalityIso;
+      if (client.source) values['{{client.source}}'] = client.source;
+      const contacts = await db.query.clientContacts.findMany({
+        where: eq(clientContacts.clientId, client.id),
+      });
+      const primaryEmail =
+        contacts.find((c) => c.channel === 'email' && c.isPrimary)?.value ??
+        contacts.find((c) => c.channel === 'email')?.value;
+      const primaryPhone =
+        contacts.find((c) => c.channel === 'phone' && c.isPrimary)?.value ??
+        contacts.find((c) => c.channel === 'phone')?.value;
+      if (primaryEmail) values['{{client.email}}'] = primaryEmail;
+      if (primaryPhone) values['{{client.phone}}'] = primaryPhone;
+    }
+  }
+
+  if (context.berthId) {
+    const berth = await db.query.berths.findFirst({
+      where: and(eq(berths.id, context.berthId), eq(berths.portId, portId)),
+    });
+    if (berth) {
+      values['{{berth.mooringNumber}}'] = berth.mooringNumber;
+      if (berth.area) values['{{berth.area}}'] = berth.area;
+      if (berth.status) values['{{berth.status}}'] = berth.status;
+      if (berth.lengthFt) values['{{berth.lengthFt}}'] = String(berth.lengthFt);
+      if (berth.widthFt) values['{{berth.widthFt}}'] = String(berth.widthFt);
+      if (berth.price) values['{{berth.price}}'] = String(berth.price);
+      if (berth.priceCurrency) values['{{berth.priceCurrency}}'] = berth.priceCurrency;
+    }
+  }
+
+  return values;
+}
+
+/**
+ * Render a body for the dry-run UI. Returns `{ html, unresolved }`. The UI
+ * uses `unresolved` to populate the warning chip; the rep can't submit
+ * until the list is empty.
+ */
+export async function previewBody(
+  portId: string,
+  documentKind: 'berth_pdf' | 'brochure',
+  recipient: SendRecipientInput,
+  customBody: string | null,
+  ctx: { berthId?: string; brochureLabel?: string } = {},
+): Promise<{ html: string; markdown: string; unresolved: string[] }> {
+  const content = await getSalesContentConfig(portId);
+  const template = customBody?.trim()?.length
+    ? customBody
+    : documentKind === 'berth_pdf'
+      ? content.templateBerthPdfBody
+      : content.templateBrochureBody;
+  const values = await buildMergeValues(portId, recipient, ctx);
+  const expanded = expandMergeTokens(template, values);
+  const unresolved = findUnresolvedTokens(template, values);
+  const html = renderEmailBody(expanded);
+  return { html, markdown: expanded, unresolved };
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+const RFC5322_EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function assertEmailValid(email: string): void {
+  if (!email || email.length > 254 || !RFC5322_EMAIL.test(email)) {
+    throw new ValidationError(`Invalid recipient email: ${email}`);
+  }
+}
+
+async function resolveRecipientEmail(
+  portId: string,
+  recipient: SendRecipientInput,
+): Promise<string> {
+  if (recipient.email) {
+    assertEmailValid(recipient.email);
+    return recipient.email;
+  }
+  if (!recipient.clientId) {
+    throw new ValidationError('Recipient must include either clientId or email');
+  }
+  const client = await db.query.clients.findFirst({
+    where: and(eq(clients.id, recipient.clientId), eq(clients.portId, portId)),
+  });
+  if (!client) throw new NotFoundError('Client');
+
+  const contacts = await db.query.clientContacts.findMany({
+    where: eq(clientContacts.clientId, client.id),
+  });
+  const emails = contacts.filter((c) => c.channel === 'email');
+  const primary = emails.find((c) => c.isPrimary) ?? emails[0];
+  if (!primary) throw new ValidationError('Client has no email on file');
+  assertEmailValid(primary.value);
+  return primary.value;
+}
+
+async function checkSendRateLimit(userId: string): Promise<void> {
+  const result = await checkRateLimit(userId, {
+    windowMs: 60 * 60 * 1000,
+    max: 50,
+    keyPrefix: 'docsend',
+  });
+  if (!result.allowed) {
+    throw new ForbiddenError(
+      `Hit hourly send limit (${result.limit}). Retry after ${new Date(
+        result.resetAt,
+      ).toISOString()}.`,
+    );
+  }
+}
+
+interface ResolvedAttachment {
+  /** Object key in the active storage backend. */
+  storageKey: string;
+  fileName: string;
+  fileSizeBytes: number;
+}
+
+async function streamAttachmentOrLink(
+  portId: string,
+  attachment: ResolvedAttachment,
+): Promise<{
+  attachments?: Array<{ filename: string; content: Readable }>;
+  bodySuffixHtml?: string;
+  deliveredAsAttachment: boolean;
+}> {
+  const content = await getSalesContentConfig(portId);
+  const thresholdBytes = content.emailAttachThresholdMb * 1024 * 1024;
+
+  if (attachment.fileSizeBytes <= thresholdBytes) {
+    // Stream from storage directly into nodemailer to avoid buffering 20MB+.
+    const storage = await getStorageBackend();
+    const stream = await storage.get(attachment.storageKey);
+    // The storage abstraction returns NodeJS.ReadableStream; nodemailer's
+    // Attachment.content type wants `Readable`. The two are compatible —
+    // both stream backends expose a Readable. Cast to keep types tight.
+    const readable = stream as unknown as Readable;
+    return {
+      deliveredAsAttachment: true,
+      attachments: [{ filename: attachment.fileName, content: readable }],
+    };
+  }
+
+  // Above threshold: generate a 24h signed download URL and append a link
+  // to the body. Per §11.1 the size decision is made BEFORE the SMTP relay,
+  // so we never produce duplicate sends.
+  const storage = await getStorageBackend();
+  const { url } = await storage.presignDownload(attachment.storageKey, {
+    expirySeconds: 24 * 60 * 60,
+    filename: attachment.fileName,
+  });
+  const html = `<p>The file is large enough that we're sending it as a download link rather than an attachment:</p>
+<p><a href="${url}" target="_blank" rel="noopener noreferrer">Download ${attachment.fileName}</a> (link expires in 24 hours)</p>`;
+  return { deliveredAsAttachment: false, bodySuffixHtml: html };
+}
+
+async function performSend(args: {
+  portId: string;
+  recipientEmail: string;
+  subject: string;
+  bodyHtml: string;
+  attachment: ResolvedAttachment;
+  recordSeed: Omit<typeof documentSends.$inferInsert, 'id' | 'sentAt' | 'createdAt'>;
+}): Promise<SendResult> {
+  // 1. Build attachment vs link preamble.
+  const delivery = await streamAttachmentOrLink(args.portId, args.attachment);
+  const finalHtml = delivery.bodySuffixHtml
+    ? `${args.bodyHtml}\n${delivery.bodySuffixHtml}`
+    : args.bodyHtml;
+
+  // 2. Create the transporter (per-port sales account).
+  let transporter, fromAddress;
+  try {
+    ({ transporter, fromAddress } = await createSalesTransporter(args.portId));
+  } catch (configErr) {
+    const msg = configErr instanceof Error ? configErr.message : String(configErr);
+    const [row] = await db
+      .insert(documentSends)
+      .values({
+        ...args.recordSeed,
+        fromAddress: args.recordSeed.fromAddress || 'unknown',
+        bodyMarkdown: args.recordSeed.bodyMarkdown ?? null,
+        failedAt: new Date(),
+        errorReason: msg,
+      })
+      .returning();
+    return {
+      send: row!,
+      deliveredAsAttachment: false,
+      error: msg,
+    };
+  }
+
+  // 3. Send.
+  try {
+    const info: SentMessageInfo = await transporter.sendMail({
+      from: fromAddress,
+      to: args.recipientEmail,
+      subject: args.subject,
+      html: finalHtml,
+      ...(delivery.attachments ? { attachments: delivery.attachments } : {}),
+    });
+    const [row] = await db
+      .insert(documentSends)
+      .values({
+        ...args.recordSeed,
+        fromAddress,
+        messageId: info.messageId ?? null,
+        fallbackToLinkReason: delivery.deliveredAsAttachment ? null : 'size_above_threshold',
+      })
+      .returning();
+    return { send: row!, deliveredAsAttachment: delivery.deliveredAsAttachment };
+  } catch (sendErr) {
+    const msg = sendErr instanceof Error ? sendErr.message : String(sendErr);
+    logger.error({ err: sendErr, portId: args.portId }, 'Sales send failed');
+    const [row] = await db
+      .insert(documentSends)
+      .values({
+        ...args.recordSeed,
+        fromAddress,
+        failedAt: new Date(),
+        errorReason: msg,
+      })
+      .returning();
+    return { send: row!, deliveredAsAttachment: false, error: msg };
+  }
+}
+
+// ─── Public sender: berth PDF ────────────────────────────────────────────────
+
+export async function sendBerthPdf(input: SendBerthPdfInput): Promise<SendResult> {
+  await checkSendRateLimit(input.sentBy);
+  const recipientEmail = await resolveRecipientEmail(input.portId, input.recipient);
+
+  // Resolve berth + active version.
+  const berth = await db.query.berths.findFirst({
+    where: and(eq(berths.id, input.berthId), eq(berths.portId, input.portId)),
+  });
+  if (!berth) throw new NotFoundError('Berth');
+  if (!berth.currentPdfVersionId) {
+    throw new ValidationError(
+      'No PDF uploaded for this berth yet. Upload one in the berth detail page first.',
+    );
+  }
+  const version = await db.query.berthPdfVersions.findFirst({
+    where: eq(berthPdfVersions.id, berth.currentPdfVersionId),
+  });
+  if (!version) throw new NotFoundError('Berth PDF version');
+
+  // Build body.
+  const content = await getSalesContentConfig(input.portId);
+  const template = input.customBodyMarkdown?.trim()?.length
+    ? input.customBodyMarkdown
+    : content.templateBerthPdfBody;
+  if (Buffer.byteLength(template, 'utf8') > EMAIL_BODY_MAX_BYTES) {
+    throw new ValidationError('Email body exceeds maximum length');
+  }
+  const values = await buildMergeValues(input.portId, input.recipient, { berthId: berth.id });
+  const unresolved = findUnresolvedTokens(template, values);
+  if (unresolved.length > 0 && !input.allowUnresolved) {
+    throw new ValidationError(`Unresolved merge tokens: ${unresolved.join(', ')}`);
+  }
+  const expanded = expandMergeTokens(template, values);
+  const bodyHtml = renderEmailBody(expanded);
+
+  // Subject pulls in the mooring number for inbox triage.
+  const subject = `Berth ${berth.mooringNumber} — spec sheet`;
+
+  return performSend({
+    portId: input.portId,
+    recipientEmail,
+    subject,
+    bodyHtml,
+    attachment: {
+      storageKey: version.storageKey,
+      fileName: version.fileName,
+      fileSizeBytes: version.fileSizeBytes,
+    },
+    recordSeed: {
+      portId: input.portId,
+      clientId: input.recipient.clientId ?? null,
+      interestId: input.recipient.interestId ?? null,
+      recipientEmail,
+      documentKind: 'berth_pdf',
+      berthId: berth.id,
+      berthPdfVersionId: version.id,
+      brochureId: null,
+      brochureVersionId: null,
+      bodyMarkdown: expanded,
+      sentByUserId: input.sentBy,
+      fromAddress: '',
+    },
+  });
+}
+
+// ─── Public sender: brochure ─────────────────────────────────────────────────
+
+export async function sendBrochure(input: SendBrochureInput): Promise<SendResult> {
+  await checkSendRateLimit(input.sentBy);
+  const recipientEmail = await resolveRecipientEmail(input.portId, input.recipient);
+
+  // Resolve brochure + most-recent version.
+  let brochureRow;
+  if (input.brochureId) {
+    brochureRow = await db.query.brochures.findFirst({
+      where: and(eq(brochures.id, input.brochureId), eq(brochures.portId, input.portId)),
+    });
+    if (!brochureRow) throw new NotFoundError('Brochure');
+    if (brochureRow.archivedAt) {
+      throw new ValidationError('Brochure is archived');
+    }
+  } else {
+    const def = await getDefaultBrochure(input.portId);
+    if (!def || !def.currentVersion) {
+      throw new ValidationError(
+        'No default brochure configured for this port. Upload one in /admin/brochures.',
+      );
+    }
+    brochureRow = def;
+  }
+
+  const versions = await db.query.brochureVersions.findMany({
+    where: eq(brochureVersions.brochureId, brochureRow.id),
+    orderBy: [desc(brochureVersions.uploadedAt)],
+    limit: 1,
+  });
+  const version = versions[0];
+  if (!version) {
+    throw new ValidationError('Brochure has no uploaded version yet');
+  }
+
+  // Build body.
+  const content = await getSalesContentConfig(input.portId);
+  const template = input.customBodyMarkdown?.trim()?.length
+    ? input.customBodyMarkdown
+    : content.templateBrochureBody;
+  if (Buffer.byteLength(template, 'utf8') > EMAIL_BODY_MAX_BYTES) {
+    throw new ValidationError('Email body exceeds maximum length');
+  }
+  const values = await buildMergeValues(input.portId, input.recipient, {
+    brochureLabel: brochureRow.label,
+  });
+  const unresolved = findUnresolvedTokens(template, values);
+  if (unresolved.length > 0 && !input.allowUnresolved) {
+    throw new ValidationError(`Unresolved merge tokens: ${unresolved.join(', ')}`);
+  }
+  const expanded = expandMergeTokens(template, values);
+  const bodyHtml = renderEmailBody(expanded);
+  const subject = `${brochureRow.label} — brochure`;
+
+  return performSend({
+    portId: input.portId,
+    recipientEmail,
+    subject,
+    bodyHtml,
+    attachment: {
+      storageKey: version.storageKey,
+      fileName: version.fileName,
+      fileSizeBytes: version.fileSizeBytes,
+    },
+    recordSeed: {
+      portId: input.portId,
+      clientId: input.recipient.clientId ?? null,
+      interestId: input.recipient.interestId ?? null,
+      recipientEmail,
+      documentKind: 'brochure',
+      berthId: null,
+      berthPdfVersionId: null,
+      brochureId: brochureRow.id,
+      brochureVersionId: version.id,
+      bodyMarkdown: expanded,
+      sentByUserId: input.sentBy,
+      fromAddress: '',
+    },
+  });
+}
+
+// ─── Audit query ─────────────────────────────────────────────────────────────
+
+export interface ListSendsFilters {
+  portId: string;
+  clientId?: string;
+  interestId?: string;
+  berthId?: string;
+  limit?: number;
+}
+
+export async function listSends(filters: ListSendsFilters): Promise<DocumentSend[]> {
+  const conds = [eq(documentSends.portId, filters.portId)];
+  if (filters.clientId) conds.push(eq(documentSends.clientId, filters.clientId));
+  if (filters.interestId) conds.push(eq(documentSends.interestId, filters.interestId));
+  if (filters.berthId) conds.push(eq(documentSends.berthId, filters.berthId));
+  const rows = await db
+    .select()
+    .from(documentSends)
+    .where(and(...conds))
+    .orderBy(desc(documentSends.sentAt))
+    .limit(filters.limit ?? 100);
+  return rows;
+}

src/lib/services/sales-email-config.service.ts

@@ -0,0 +1,374 @@
+/**
+ * Per-port sales-email configuration (Phase 7 — see plan §4.9).
+ *
+ * Distinct from {@link getPortEmailConfig} (`port-config.ts`) which resolves
+ * the **noreply** account used by automated/system emails. The sales account
+ * is the human-touch outbound: brochure/berth-pdf send-outs from
+ * `document-sends.service.ts`, follow-up emails composed by reps.
+ *
+ * Both inboxes (SMTP + IMAP) live behind the same provider account in 99% of
+ * deployments; both are configured here. The IMAP half is consumed by the
+ * async-bounce monitor (§14.9), out of scope for this service but exposed
+ * via `getSalesImapConfig()`.
+ *
+ * SECURITY (§14.10): SMTP/IMAP passwords are encrypted at rest using the
+ * existing `EMAIL_CREDENTIAL_KEY` symmetric key. Reps cannot read the
+ * decrypted value via the API — only `manage_settings` admins can write,
+ * and even they only ever see a placeholder mask on read (see the admin
+ * route handler).
+ */
+import nodemailer, { type Transporter } from 'nodemailer';
+
+import { env } from '@/lib/env';
+import { decrypt, encrypt } from '@/lib/utils/encryption';
+import { getSetting, upsertSetting } from '@/lib/services/settings.service';
+import type { AuditMeta } from '@/lib/audit';
+
+// ─── Setting keys ────────────────────────────────────────────────────────────
+
+export const SALES_EMAIL_KEYS = {
+  fromAddress: 'sales_from_address',
+  smtpHost: 'sales_smtp_host',
+  smtpPort: 'sales_smtp_port',
+  smtpSecure: 'sales_smtp_secure',
+  smtpUser: 'sales_smtp_user',
+  smtpPassEncrypted: 'sales_smtp_pass_encrypted',
+  imapHost: 'sales_imap_host',
+  imapPort: 'sales_imap_port',
+  imapUser: 'sales_imap_user',
+  imapPassEncrypted: 'sales_imap_pass_encrypted',
+  authMethod: 'sales_auth_method',
+  noreplyFromAddress: 'noreply_from_address',
+  templateBerthPdfBody: 'email_template_send_berth_pdf_body',
+  templateBrochureBody: 'email_template_send_brochure_body',
+  brochureMaxUploadMb: 'brochure_max_upload_mb',
+  emailAttachThresholdMb: 'email_attach_threshold_mb',
+} as const;
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface SalesEmailConfig {
+  fromAddress: string;
+  smtpHost: string | null;
+  smtpPort: number;
+  smtpSecure: boolean;
+  smtpUser: string | null;
+  /** Decrypted plaintext, available only inside server-side service code. */
+  smtpPass: string | null;
+  authMethod: string;
+  /** Whether the config is complete enough to actually send. */
+  isUsable: boolean;
+}
+
+export interface SalesImapConfig {
+  imapHost: string | null;
+  imapPort: number;
+  imapUser: string | null;
+  imapPass: string | null;
+  isUsable: boolean;
+}
+
+export interface SalesContentConfig {
+  noreplyFromAddress: string;
+  templateBerthPdfBody: string;
+  templateBrochureBody: string;
+  brochureMaxUploadMb: number;
+  emailAttachThresholdMb: number;
+}
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+const DEFAULT_BERTH_PDF_BODY = [
+  'Hi {{client.fullName}},',
+  '',
+  'Please find attached the spec sheet for berth {{berth.mooringNumber}} at {{port.name}}.',
+  '',
+  'Happy to set up a call to walk through the details — let me know what works.',
+  '',
+  'Best,',
+].join('\n');
+
+const DEFAULT_BROCHURE_BODY = [
+  'Hi {{client.fullName}},',
+  '',
+  'As discussed, attached is our {{port.name}} brochure with the latest information on availability, amenities, and access.',
+  '',
+  'Let me know if any specific berths catch your eye and I can pull together more detail.',
+  '',
+  'Best,',
+].join('\n');
+
+// ─── Read accessors ──────────────────────────────────────────────────────────
+
+async function readSetting<T>(key: string, portId: string): Promise<T | null> {
+  const setting = await getSetting(key, portId);
+  if (!setting) return null;
+  return setting.value as T;
+}
+
+function decryptOrNull(value: string | null): string | null {
+  if (!value) return null;
+  try {
+    return decrypt(value);
+  } catch {
+    // If decryption fails (key rotation, corruption, etc.), return null so
+    // the send fails fast rather than mis-authenticating against SMTP.
+    return null;
+  }
+}
+
+export async function getSalesEmailConfig(portId: string): Promise<SalesEmailConfig> {
+  const [fromAddress, smtpHost, smtpPort, smtpSecure, smtpUser, smtpPassEnc, authMethod] =
+    await Promise.all([
+      readSetting<string>(SALES_EMAIL_KEYS.fromAddress, portId),
+      readSetting<string>(SALES_EMAIL_KEYS.smtpHost, portId),
+      readSetting<number>(SALES_EMAIL_KEYS.smtpPort, portId),
+      readSetting<boolean>(SALES_EMAIL_KEYS.smtpSecure, portId),
+      readSetting<string>(SALES_EMAIL_KEYS.smtpUser, portId),
+      readSetting<string>(SALES_EMAIL_KEYS.smtpPassEncrypted, portId),
+      readSetting<string>(SALES_EMAIL_KEYS.authMethod, portId),
+    ]);
+
+  const smtpPass = decryptOrNull(smtpPassEnc);
+
+  // For `from`, fall back to the SMTP_FROM env so a brand-new port without
+  // overrides still has a usable identity (for tests + dev).
+  const resolvedFrom =
+    fromAddress ?? env.SMTP_FROM?.replace(/^.*<(.+)>$/, '$1').trim() ?? `sales@${env.SMTP_HOST}`;
+
+  return {
+    fromAddress: resolvedFrom,
+    smtpHost: smtpHost ?? env.SMTP_HOST ?? null,
+    smtpPort: smtpPort ?? env.SMTP_PORT ?? 587,
+    smtpSecure: smtpSecure ?? false,
+    smtpUser: smtpUser ?? env.SMTP_USER ?? null,
+    smtpPass: smtpPass ?? env.SMTP_PASS ?? null,
+    authMethod: authMethod ?? 'app_password',
+    // "Usable" means we have host + (user, pass) pair OR host + no auth
+    // (some test/local SMTP doesn't auth). For prod-realistic, we require
+    // creds — empty creds means we'll just bounce against the relay.
+    isUsable: Boolean(
+      (smtpHost ?? env.SMTP_HOST) && ((smtpUser && smtpPass) ?? (env.SMTP_USER && env.SMTP_PASS)),
+    ),
+  };
+}
+
+export async function getSalesImapConfig(portId: string): Promise<SalesImapConfig> {
+  const [imapHost, imapPort, imapUser, imapPassEnc] = await Promise.all([
+    readSetting<string>(SALES_EMAIL_KEYS.imapHost, portId),
+    readSetting<number>(SALES_EMAIL_KEYS.imapPort, portId),
+    readSetting<string>(SALES_EMAIL_KEYS.imapUser, portId),
+    readSetting<string>(SALES_EMAIL_KEYS.imapPassEncrypted, portId),
+  ]);
+  const imapPass = decryptOrNull(imapPassEnc);
+  return {
+    imapHost: imapHost ?? null,
+    imapPort: imapPort ?? 993,
+    imapUser: imapUser ?? null,
+    imapPass,
+    isUsable: Boolean(imapHost && imapUser && imapPass),
+  };
+}
+
+export async function getSalesContentConfig(portId: string): Promise<SalesContentConfig> {
+  const [noreply, berthPdfBody, brochureBody, maxUpload, attachThreshold] = await Promise.all([
+    readSetting<string>(SALES_EMAIL_KEYS.noreplyFromAddress, portId),
+    readSetting<string>(SALES_EMAIL_KEYS.templateBerthPdfBody, portId),
+    readSetting<string>(SALES_EMAIL_KEYS.templateBrochureBody, portId),
+    readSetting<number>(SALES_EMAIL_KEYS.brochureMaxUploadMb, portId),
+    readSetting<number>(SALES_EMAIL_KEYS.emailAttachThresholdMb, portId),
+  ]);
+  return {
+    noreplyFromAddress:
+      noreply ?? env.SMTP_FROM?.replace(/^.*<(.+)>$/, '$1').trim() ?? `noreply@${env.SMTP_HOST}`,
+    templateBerthPdfBody: berthPdfBody ?? DEFAULT_BERTH_PDF_BODY,
+    templateBrochureBody: brochureBody ?? DEFAULT_BROCHURE_BODY,
+    brochureMaxUploadMb: maxUpload ?? 50,
+    emailAttachThresholdMb: attachThreshold ?? 15,
+  };
+}
+
+// ─── Write accessors ─────────────────────────────────────────────────────────
+
+/**
+ * Plain (unencrypted) input shape for the admin write path. Password fields
+ * are accepted as plaintext and encrypted before storage.
+ *
+ * `null` semantics:
+ *   - undefined => leave unchanged (don't touch the row).
+ *   - null      => clear the value.
+ *   - string    => set to this value.
+ *
+ * For password fields specifically, the empty string `""` is treated as
+ * "leave unchanged" so the admin form's masked placeholder can round-trip
+ * without forcing the rep to re-enter the password every save.
+ */
+export interface SalesEmailConfigUpdate {
+  fromAddress?: string | null;
+  smtpHost?: string | null;
+  smtpPort?: number | null;
+  smtpSecure?: boolean | null;
+  smtpUser?: string | null;
+  /** Plaintext; encrypted before storage. Pass `""` to leave unchanged. */
+  smtpPass?: string | null;
+  imapHost?: string | null;
+  imapPort?: number | null;
+  imapUser?: string | null;
+  /** Plaintext; encrypted before storage. Pass `""` to leave unchanged. */
+  imapPass?: string | null;
+  authMethod?: string | null;
+  noreplyFromAddress?: string | null;
+  templateBerthPdfBody?: string | null;
+  templateBrochureBody?: string | null;
+  brochureMaxUploadMb?: number | null;
+  emailAttachThresholdMb?: number | null;
+}
+
+async function writeSetting<T>(
+  key: string,
+  value: T | null | undefined,
+  portId: string,
+  meta: AuditMeta,
+): Promise<void> {
+  if (value === undefined) return;
+  await upsertSetting(key, value, portId, meta);
+}
+
+export async function updateSalesEmailConfig(
+  portId: string,
+  update: SalesEmailConfigUpdate,
+  meta: AuditMeta,
+): Promise<void> {
+  await writeSetting(SALES_EMAIL_KEYS.fromAddress, update.fromAddress, portId, meta);
+  await writeSetting(SALES_EMAIL_KEYS.smtpHost, update.smtpHost, portId, meta);
+  await writeSetting(SALES_EMAIL_KEYS.smtpPort, update.smtpPort, portId, meta);
+  await writeSetting(SALES_EMAIL_KEYS.smtpSecure, update.smtpSecure, portId, meta);
+  await writeSetting(SALES_EMAIL_KEYS.smtpUser, update.smtpUser, portId, meta);
+  await writeSetting(SALES_EMAIL_KEYS.imapHost, update.imapHost, portId, meta);
+  await writeSetting(SALES_EMAIL_KEYS.imapPort, update.imapPort, portId, meta);
+  await writeSetting(SALES_EMAIL_KEYS.imapUser, update.imapUser, portId, meta);
+  await writeSetting(SALES_EMAIL_KEYS.authMethod, update.authMethod, portId, meta);
+  await writeSetting(SALES_EMAIL_KEYS.noreplyFromAddress, update.noreplyFromAddress, portId, meta);
+  await writeSetting(
+    SALES_EMAIL_KEYS.templateBerthPdfBody,
+    update.templateBerthPdfBody,
+    portId,
+    meta,
+  );
+  await writeSetting(
+    SALES_EMAIL_KEYS.templateBrochureBody,
+    update.templateBrochureBody,
+    portId,
+    meta,
+  );
+  await writeSetting(
+    SALES_EMAIL_KEYS.brochureMaxUploadMb,
+    update.brochureMaxUploadMb,
+    portId,
+    meta,
+  );
+  await writeSetting(
+    SALES_EMAIL_KEYS.emailAttachThresholdMb,
+    update.emailAttachThresholdMb,
+    portId,
+    meta,
+  );
+
+  // Password fields: encrypt before write. Empty string = "no change".
+  if (update.smtpPass !== undefined && update.smtpPass !== '') {
+    if (update.smtpPass === null) {
+      await upsertSetting(SALES_EMAIL_KEYS.smtpPassEncrypted, null, portId, meta);
+    } else {
+      await upsertSetting(
+        SALES_EMAIL_KEYS.smtpPassEncrypted,
+        encrypt(update.smtpPass),
+        portId,
+        meta,
+      );
+    }
+  }
+  if (update.imapPass !== undefined && update.imapPass !== '') {
+    if (update.imapPass === null) {
+      await upsertSetting(SALES_EMAIL_KEYS.imapPassEncrypted, null, portId, meta);
+    } else {
+      await upsertSetting(
+        SALES_EMAIL_KEYS.imapPassEncrypted,
+        encrypt(update.imapPass),
+        portId,
+        meta,
+      );
+    }
+  }
+}
+
+// ─── Transporter factory ─────────────────────────────────────────────────────
+
+export type SenderAccount = 'noreply' | 'sales';
+
+/**
+ * Build a nodemailer transporter for the requested sender account.
+ *
+ * - `'sales'` uses the per-port SALES_* keys (see {@link getSalesEmailConfig}).
+ * - `'noreply'` falls back to the legacy `port-config.ts` resolver (see
+ *   `getPortEmailConfig`) which itself drops back to the env defaults.
+ *
+ * Throws when the requested account isn't configured well enough to send;
+ * callers should let this propagate so the document_sends row gets a
+ * `failedAt` + `errorReason`.
+ */
+export async function createSalesTransporter(portId: string): Promise<{
+  transporter: Transporter;
+  fromAddress: string;
+  authedUser: string | null;
+}> {
+  const cfg = await getSalesEmailConfig(portId);
+  if (!cfg.smtpHost) {
+    throw new Error(
+      'Sales SMTP not configured for this port. Configure in /admin/email before sending.',
+    );
+  }
+  const transporter = nodemailer.createTransport({
+    host: cfg.smtpHost,
+    port: cfg.smtpPort,
+    secure: cfg.smtpSecure,
+    ...(cfg.smtpUser && cfg.smtpPass ? { auth: { user: cfg.smtpUser, pass: cfg.smtpPass } } : {}),
+  });
+  return { transporter, fromAddress: cfg.fromAddress, authedUser: cfg.smtpUser };
+}
+
+/**
+ * Public-facing sanitizer — strips encrypted fields and replaces password
+ * fields with a boolean `isSet` marker. Used by the admin GET endpoint so
+ * reps with `manage_settings` can see whether creds are configured without
+ * the API ever returning the ciphertext (much less plaintext).
+ */
+export function redactSalesConfigForResponse(
+  cfg: SalesEmailConfig,
+  imap: SalesImapConfig,
+  content: SalesContentConfig,
+): {
+  email: Omit<SalesEmailConfig, 'smtpPass'> & { smtpPassIsSet: boolean };
+  imap: Omit<SalesImapConfig, 'imapPass'> & { imapPassIsSet: boolean };
+  content: SalesContentConfig;
+} {
+  // Spread without the password fields — never reflect the decrypted value
+  // (or its ciphertext) back to the API surface.
+  const email = {
+    fromAddress: cfg.fromAddress,
+    smtpHost: cfg.smtpHost,
+    smtpPort: cfg.smtpPort,
+    smtpSecure: cfg.smtpSecure,
+    smtpUser: cfg.smtpUser,
+    authMethod: cfg.authMethod,
+    isUsable: cfg.isUsable,
+    smtpPassIsSet: Boolean(cfg.smtpPass),
+  };
+  const imapRedacted = {
+    imapHost: imap.imapHost,
+    imapPort: imap.imapPort,
+    imapUser: imap.imapUser,
+    isUsable: imap.isUsable,
+    imapPassIsSet: Boolean(imap.imapPass),
+  };
+  return { email, imap: imapRedacted, content };
+}

src/lib/utils/markdown-email.ts

@@ -0,0 +1,168 @@
+/**
+ * Minimal markdown -> HTML email conversion + safe sanitization.
+ *
+ * Used by the Phase 7 sales send-out flow (`document-sends.service.ts`) to
+ * render rep-authored bodies into the email-safe HTML we hand to nodemailer.
+ *
+ * § §14.7 critical mitigation: "Body markdown with HTML/script injection".
+ * This module is the choke point — every code path that turns rep-authored
+ * markdown into an email body MUST go through `renderEmailBody()`. Direct
+ * passthrough to `transporter.sendMail({ html })` from a user-supplied string
+ * is a code-review block.
+ *
+ * The implementation is intentionally tiny (no DOMPurify, no marked) for two
+ * reasons:
+ *
+ *   1. Email clients render a strict subset of HTML anyway — paragraphs,
+ *      bold/italic, line breaks, links and code spans cover ~99% of what
+ *      reps actually write. Anything more complex (tables, images, lists)
+ *      goes via the admin-editable HTML body templates.
+ *   2. Adding a transitive deps surface for the markdown→HTML conversion
+ *      doubles the attack surface for the very mitigation it implements.
+ *
+ * The renderer:
+ *   - HTML-escapes every input character before applying any markdown rules.
+ *   - Whitelists exactly: paragraphs, line breaks, **bold**, _italic_, `code`,
+ *     and `[text](https://...)` links (https only).
+ *   - Strips any other markdown / HTML constructs by virtue of being
+ *     escape-first-then-rule-replace.
+ *
+ * Tested against the standard XSS vector list (`<script>`, `<img onerror>`,
+ * `javascript:` URLs, `<iframe>`, etc.) — see
+ * `tests/unit/markdown-email-sanitization.test.ts`.
+ */
+
+const MAX_BODY_BYTES = 50 * 1024; // 50 KB hard cap matching §14.7
+
+/** Re-export for the sender service so it doesn't have to remember the cap. */
+export const EMAIL_BODY_MAX_BYTES = MAX_BODY_BYTES;
+
+/**
+ * Escape every HTML-significant character. Run on raw input BEFORE any
+ * markdown rules so user-supplied HTML can never reach the rendered body.
+ */
+function escapeHtml(input: string): string {
+  return input
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * The list of allowed URL schemes. We deliberately reject `javascript:`,
+ * `data:`, `vbscript:`, and bare-word schemes (which some browsers resolve
+ * to `http:`) — only fully-qualified `https://` and `mailto:` make it through.
+ */
+function isSafeHref(href: string): boolean {
+  const trimmed = href.trim().toLowerCase();
+  return trimmed.startsWith('https://') || trimmed.startsWith('mailto:');
+}
+
+/**
+ * Apply inline markdown rules to an already-HTML-escaped string. The order
+ * matters: code spans win over emphasis, links win over emphasis (so
+ * `[**foo**](url)` works), and emphasis is greedy-non-greedy aware.
+ */
+function applyInlineRules(escaped: string): string {
+  let out = escaped;
+
+  // `code` (single backticks; nothing fancier — no fenced blocks here)
+  out = out.replace(/`([^`\n]+)`/g, '<code>$1</code>');
+
+  // [text](href) — href validated. Bracket text is already escaped so we
+  // pass it through verbatim. Use a non-greedy match so two links on one
+  // line don't collapse.
+  out = out.replace(/\[([^\]\n]+?)\]\(([^)\n]+?)\)/g, (_full, text: string, href: string) => {
+    // The href captured group came from already-escaped input, so the
+    // entity-encoded chars need to survive into the attribute. We DO NOT
+    // unescape here; the escaped form (`&amp;`, `&#39;` etc.) is the safe
+    // representation for attribute values.
+    if (!isSafeHref(href.replace(/&amp;/g, '&'))) {
+      // Drop the link entirely; render the text as plain.
+      return text;
+    }
+    return `<a href="${href}" target="_blank" rel="noopener noreferrer">${text}</a>`;
+  });
+
+  // **bold** then *italic* / _italic_
+  out = out.replace(/\*\*([^*\n]+?)\*\*/g, '<strong>$1</strong>');
+  out = out.replace(/(?<!\*)\*([^*\n]+?)\*(?!\*)/g, '<em>$1</em>');
+  out = out.replace(/(^|\s)_([^_\n]+?)_(?=\s|$)/g, '$1<em>$2</em>');
+
+  return out;
+}
+
+/**
+ * Convert rep-authored markdown into email-safe HTML.
+ *
+ * Throws when the input exceeds {@link EMAIL_BODY_MAX_BYTES}.
+ */
+export function renderEmailBody(markdown: string): string {
+  if (Buffer.byteLength(markdown, 'utf8') > MAX_BODY_BYTES) {
+    throw new Error(`Email body exceeds maximum length (${MAX_BODY_BYTES} bytes)`);
+  }
+
+  // 1. HTML-escape EVERYTHING first — there is no path through the rules
+  //    below that lets an unescaped angle bracket reach the output.
+  const escaped = escapeHtml(markdown);
+
+  // 2. Split into paragraphs on blank lines; within each paragraph,
+  //    single newlines become <br>.
+  const paragraphs = escaped.split(/\n{2,}/);
+  const rendered = paragraphs
+    .map((para) => {
+      const trimmed = para.trim();
+      if (!trimmed) return '';
+      const inline = applyInlineRules(trimmed).replace(/\n/g, '<br>');
+      return `<p>${inline}</p>`;
+    })
+    .filter(Boolean)
+    .join('\n');
+
+  return rendered;
+}
+
+/**
+ * Find every `{{token}}` reference in a body. Returns the raw token strings
+ * (with braces) for caller-side validation against the merge-field catalog.
+ */
+export function extractTokens(markdown: string): string[] {
+  const matches = markdown.match(/\{\{[^{}\n]+?\}\}/g);
+  return matches ? Array.from(new Set(matches)) : [];
+}
+
+/**
+ * Replace `{{token}}` references with values from the supplied map. Tokens
+ * not present in the map are left intact so the dry-run reporter can flag
+ * them. Values are HTML-escape-safe by virtue of being run BEFORE
+ * `renderEmailBody()`; the caller is expected to pass plain strings.
+ */
+export function expandMergeTokens(
+  markdown: string,
+  values: Record<string, string | number | null | undefined>,
+): string {
+  return markdown.replace(/\{\{([^{}\n]+?)\}\}/g, (full, raw: string) => {
+    const key = `{{${raw}}}`;
+    const value = values[key];
+    if (value === null || value === undefined || value === '') return full;
+    return String(value);
+  });
+}
+
+/**
+ * Returns the list of `{{token}}` references in `markdown` that aren't
+ * present (or are blank/null) in the provided value map. Used by the
+ * pre-send dry-run UI per §14.7 ("Body markdown contains unresolved merge
+ * fields — Send blocked until resolved").
+ */
+export function findUnresolvedTokens(
+  markdown: string,
+  values: Record<string, string | number | null | undefined>,
+): string[] {
+  return extractTokens(markdown).filter((token) => {
+    const v = values[token];
+    return v === undefined || v === null || v === '';
+  });
+}

src/lib/validators/brochures.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+
+export const createBrochureSchema = z.object({
+  label: z.string().trim().min(1).max(120),
+  description: z.string().max(500).optional().nullable(),
+  isDefault: z.boolean().optional(),
+});
+
+export const updateBrochureSchema = z.object({
+  label: z.string().trim().min(1).max(120).optional(),
+  description: z.string().max(500).optional().nullable(),
+  isDefault: z.boolean().optional(),
+});
+
+export const registerBrochureVersionSchema = z.object({
+  storageKey: z
+    .string()
+    .min(1)
+    .max(500)
+    // Mirrors the `validateStorageKey` regex in `src/lib/storage/filesystem.ts`
+    // — defense-in-depth against path-traversal payloads from the client.
+    .regex(/^[a-zA-Z0-9/_.-]+$/, 'Invalid storage key format')
+    .refine((s) => !s.includes('..'), 'Storage key may not contain ".."')
+    .refine((s) => !s.startsWith('/'), 'Storage key may not be absolute'),
+  fileName: z.string().min(1).max(255),
+  fileSizeBytes: z
+    .number()
+    .int()
+    .positive()
+    .max(100 * 1024 * 1024), // 100MB hard ceiling
+  contentSha256: z.string().regex(/^[0-9a-f]{64}$/, 'sha256 must be 64-char hex'),
+});
+
+export type CreateBrochureInput = z.infer<typeof createBrochureSchema>;
+export type UpdateBrochureInput = z.infer<typeof updateBrochureSchema>;
+export type RegisterBrochureVersionInput = z.infer<typeof registerBrochureVersionSchema>;

src/lib/validators/document-sends.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+const recipientSchema = z
+  .object({
+    clientId: z.string().min(1).optional(),
+    email: z.string().email().optional(),
+    interestId: z.string().min(1).optional(),
+  })
+  .refine((v) => v.clientId !== undefined || v.email !== undefined, {
+    message: 'recipient.clientId or recipient.email is required',
+  });
+
+export const sendBerthPdfSchema = z.object({
+  berthId: z.string().min(1),
+  recipient: recipientSchema,
+  customBodyMarkdown: z.string().max(50_000).optional(),
+});
+
+export const sendBrochureSchema = z.object({
+  brochureId: z.string().min(1).optional(),
+  recipient: recipientSchema,
+  customBodyMarkdown: z.string().max(50_000).optional(),
+});
+
+export const previewBodySchema = z.object({
+  documentKind: z.enum(['berth_pdf', 'brochure']),
+  recipient: recipientSchema,
+  berthId: z.string().min(1).optional(),
+  brochureId: z.string().min(1).optional(),
+  customBodyMarkdown: z.string().max(50_000).optional(),
+});
+
+export const listSendsQuerySchema = z.object({
+  clientId: z.string().min(1).optional(),
+  interestId: z.string().min(1).optional(),
+  berthId: z.string().min(1).optional(),
+  limit: z.coerce.number().int().min(1).max(500).optional(),
+});
+
+export type SendBerthPdfInput = z.infer<typeof sendBerthPdfSchema>;
+export type SendBrochureInput = z.infer<typeof sendBrochureSchema>;
+export type PreviewBodyInput = z.infer<typeof previewBodySchema>;
+export type ListSendsQuery = z.infer<typeof listSendsQuerySchema>;

src/lib/validators/sales-email-config.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+
+/**
+ * Per-port sales-email config update payload (Phase 7).
+ *
+ * Password fields accept:
+ *   - undefined / omitted => leave unchanged
+ *   - empty string ""     => leave unchanged (UI placeholder round-trip)
+ *   - explicit null       => clear the value
+ *   - non-empty string    => set to this value (encrypted before storage)
+ */
+export const updateSalesEmailConfigSchema = z.object({
+  fromAddress: z.string().email().optional().nullable(),
+  smtpHost: z.string().min(1).max(255).optional().nullable(),
+  smtpPort: z.number().int().min(1).max(65535).optional().nullable(),
+  smtpSecure: z.boolean().optional().nullable(),
+  smtpUser: z.string().max(255).optional().nullable(),
+  smtpPass: z.string().max(255).optional().nullable(),
+  imapHost: z.string().min(1).max(255).optional().nullable(),
+  imapPort: z.number().int().min(1).max(65535).optional().nullable(),
+  imapUser: z.string().max(255).optional().nullable(),
+  imapPass: z.string().max(255).optional().nullable(),
+  authMethod: z.enum(['app_password', 'oauth_google', 'oauth_microsoft']).optional().nullable(),
+  noreplyFromAddress: z.string().email().optional().nullable(),
+  templateBerthPdfBody: z.string().max(50_000).optional().nullable(),
+  templateBrochureBody: z.string().max(50_000).optional().nullable(),
+  brochureMaxUploadMb: z.number().int().min(1).max(500).optional().nullable(),
+  emailAttachThresholdMb: z.number().int().min(1).max(50).optional().nullable(),
+});
+
+export type UpdateSalesEmailConfigInput = z.infer<typeof updateSalesEmailConfigSchema>;

tests/unit/document-sends-validators.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Phase 7 — validator-level guarantees for the send-out flow.
+ *
+ * §14.7 mitigation: recipient typo (the strict email regex is the first
+ * line of defense; the confirmation modal is the second).
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+  sendBerthPdfSchema,
+  sendBrochureSchema,
+  previewBodySchema,
+  listSendsQuerySchema,
+} from '@/lib/validators/document-sends';
+import { createBrochureSchema, registerBrochureVersionSchema } from '@/lib/validators/brochures';
+
+describe('sendBerthPdfSchema', () => {
+  it('requires either clientId or email', () => {
+    const r = sendBerthPdfSchema.safeParse({
+      berthId: 'b1',
+      recipient: { interestId: 'i1' },
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('accepts clientId-only recipient', () => {
+    const r = sendBerthPdfSchema.safeParse({
+      berthId: 'b1',
+      recipient: { clientId: 'c1' },
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects an obviously bad email', () => {
+    const r = sendBerthPdfSchema.safeParse({
+      berthId: 'b1',
+      recipient: { email: 'not an email' },
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('caps custom body length at 50KB', () => {
+    const r = sendBerthPdfSchema.safeParse({
+      berthId: 'b1',
+      recipient: { clientId: 'c1' },
+      customBodyMarkdown: 'x'.repeat(60_000),
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+describe('sendBrochureSchema', () => {
+  it('allows brochureId to be omitted (defaults at service level)', () => {
+    const r = sendBrochureSchema.safeParse({
+      recipient: { clientId: 'c1' },
+    });
+    expect(r.success).toBe(true);
+  });
+});
+
+describe('previewBodySchema', () => {
+  it('requires documentKind', () => {
+    const r = previewBodySchema.safeParse({ recipient: { clientId: 'c1' } });
+    expect(r.success).toBe(false);
+  });
+
+  it('accepts a minimal preview payload', () => {
+    const r = previewBodySchema.safeParse({
+      documentKind: 'berth_pdf',
+      recipient: { clientId: 'c1' },
+      berthId: 'b1',
+    });
+    expect(r.success).toBe(true);
+  });
+});
+
+describe('listSendsQuerySchema', () => {
+  it('coerces limit from string', () => {
+    const r = listSendsQuerySchema.safeParse({ limit: '50' });
+    expect(r.success).toBe(true);
+    if (r.success) expect(r.data.limit).toBe(50);
+  });
+
+  it('rejects out-of-range limit', () => {
+    const r = listSendsQuerySchema.safeParse({ limit: '99999' });
+    expect(r.success).toBe(false);
+  });
+});
+
+describe('createBrochureSchema', () => {
+  it('requires a non-empty label', () => {
+    const r = createBrochureSchema.safeParse({ label: '   ' });
+    expect(r.success).toBe(false);
+  });
+
+  it('caps label at 120 chars', () => {
+    const r = createBrochureSchema.safeParse({ label: 'a'.repeat(200) });
+    expect(r.success).toBe(false);
+  });
+});
+
+describe('registerBrochureVersionSchema', () => {
+  it('rejects path-traversal in storageKey', () => {
+    const r = registerBrochureVersionSchema.safeParse({
+      storageKey: '../etc/passwd',
+      fileName: 'b.pdf',
+      fileSizeBytes: 100,
+      contentSha256: 'a'.repeat(64),
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects malformed sha256', () => {
+    const r = registerBrochureVersionSchema.safeParse({
+      storageKey: 'port/brochures/abc/x.pdf',
+      fileName: 'b.pdf',
+      fileSizeBytes: 100,
+      contentSha256: 'NOTHEX',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects upload over 100MB', () => {
+    const r = registerBrochureVersionSchema.safeParse({
+      storageKey: 'port/brochures/abc/x.pdf',
+      fileName: 'b.pdf',
+      fileSizeBytes: 200 * 1024 * 1024,
+      contentSha256: 'a'.repeat(64),
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('accepts a valid payload', () => {
+    const r = registerBrochureVersionSchema.safeParse({
+      storageKey: 'port/brochures/abc/x.pdf',
+      fileName: 'b.pdf',
+      fileSizeBytes: 1024,
+      contentSha256: 'a'.repeat(64),
+    });
+    expect(r.success).toBe(true);
+  });
+});

tests/unit/markdown-email-sanitization.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Phase 7 §14.7 critical mitigation: body markdown XSS sanitization.
+ *
+ * Every code path that turns rep-authored markdown into the email's
+ * `html` body is required to go through `renderEmailBody()`. These tests
+ * are the canary — if any future change to the renderer lets a known XSS
+ * payload through, the test breaks before the change ships.
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+  EMAIL_BODY_MAX_BYTES,
+  expandMergeTokens,
+  extractTokens,
+  findUnresolvedTokens,
+  renderEmailBody,
+} from '@/lib/utils/markdown-email';
+
+describe('renderEmailBody — XSS payload coverage', () => {
+  it('escapes <script> tags so they render as text, not active script', () => {
+    const html = renderEmailBody('Hi <script>alert(1)</script> there');
+    expect(html).not.toContain('<script>');
+    expect(html).toContain('&lt;script&gt;');
+  });
+
+  it('escapes onerror handlers in img tags', () => {
+    const html = renderEmailBody('<img src=x onerror=alert(1)>');
+    expect(html).not.toContain('<img');
+    expect(html).toContain('&lt;img');
+  });
+
+  it('strips javascript: URLs from markdown links', () => {
+    const html = renderEmailBody('[click](javascript:alert(1))');
+    expect(html).not.toContain('javascript:');
+    expect(html).not.toContain('<a ');
+    // Falls back to rendering the link text as plain.
+    expect(html).toContain('click');
+  });
+
+  it('strips data: URLs from markdown links', () => {
+    const html = renderEmailBody('[bad](data:text/html,<script>alert(1)</script>)');
+    expect(html).not.toContain('<a ');
+    expect(html).not.toContain('<script');
+  });
+
+  it('allows https:// URLs in markdown links', () => {
+    const html = renderEmailBody('[example](https://example.com)');
+    expect(html).toContain('<a href="https://example.com"');
+    expect(html).toContain('rel="noopener noreferrer"');
+  });
+
+  it('allows mailto: URLs in markdown links', () => {
+    const html = renderEmailBody('[reach me](mailto:hi@example.com)');
+    expect(html).toContain('<a href="mailto:hi@example.com"');
+  });
+
+  it('escapes <iframe> tags', () => {
+    const html = renderEmailBody('<iframe src="https://evil.com"></iframe>');
+    expect(html).not.toContain('<iframe');
+    expect(html).toContain('&lt;iframe');
+  });
+
+  it('escapes <style> blocks', () => {
+    const html = renderEmailBody('<style>body{background:red}</style>');
+    expect(html).not.toContain('<style');
+    expect(html).toContain('&lt;style');
+  });
+
+  it('escapes attribute-style XSS attempts (no live <svg> tag survives)', () => {
+    const html = renderEmailBody('"><svg onload=alert(1)>');
+    // The literal "<svg" must never appear unescaped — the angle bracket is
+    // what the browser parses, not the word "onload".
+    expect(html).not.toContain('<svg');
+    expect(html).toContain('&lt;svg');
+    expect(html).toContain('&quot;');
+  });
+
+  it('escapes the polyglot from CWE-79 reference samples', () => {
+    const polyglot = `'\`<img src=x onerror=alert(1)>"<svg/onload=alert(1)>"`;
+    const html = renderEmailBody(polyglot);
+    // Only unescaped tags can fire handlers; we just need to be sure no
+    // unescaped `<` survives.
+    expect(html).not.toContain('<img');
+    expect(html).not.toContain('<svg');
+    expect(html).toContain('&lt;img');
+    expect(html).toContain('&lt;svg');
+  });
+
+  it('rejects bodies above 50KB', () => {
+    const huge = 'x'.repeat(EMAIL_BODY_MAX_BYTES + 1);
+    expect(() => renderEmailBody(huge)).toThrow(/maximum length/);
+  });
+});
+
+describe('renderEmailBody — markdown rules', () => {
+  it('renders **bold** as <strong>', () => {
+    expect(renderEmailBody('this is **bold**')).toContain('<strong>bold</strong>');
+  });
+
+  it('renders *italic* as <em>', () => {
+    expect(renderEmailBody('this is *italic*')).toContain('<em>italic</em>');
+  });
+
+  it('renders `code` spans', () => {
+    expect(renderEmailBody('use `apiFetch`')).toContain('<code>apiFetch</code>');
+  });
+
+  it('splits paragraphs on blank lines', () => {
+    const out = renderEmailBody('para one\n\npara two');
+    expect(out).toContain('<p>para one</p>');
+    expect(out).toContain('<p>para two</p>');
+  });
+
+  it('converts single newlines to <br>', () => {
+    const out = renderEmailBody('line one\nline two');
+    expect(out).toContain('line one<br>line two');
+  });
+});
+
+describe('merge token helpers', () => {
+  it('extracts tokens from a body', () => {
+    const tokens = extractTokens('Hi {{client.fullName}} re {{berth.mooringNumber}}.');
+    expect(tokens).toEqual(['{{client.fullName}}', '{{berth.mooringNumber}}']);
+  });
+
+  it('expands tokens that have values', () => {
+    const out = expandMergeTokens('Hi {{client.fullName}}', {
+      '{{client.fullName}}': 'Jane Doe',
+    });
+    expect(out).toBe('Hi Jane Doe');
+  });
+
+  it('leaves unresolved tokens intact', () => {
+    const out = expandMergeTokens('Hi {{client.fullName}} {{missing}}', {
+      '{{client.fullName}}': 'Jane',
+    });
+    expect(out).toBe('Hi Jane {{missing}}');
+  });
+
+  it('reports unresolved tokens', () => {
+    const unresolved = findUnresolvedTokens('Hi {{a}} {{b}} {{c}}', {
+      '{{a}}': 'value',
+    });
+    expect(unresolved).toEqual(['{{b}}', '{{c}}']);
+  });
+});

tests/unit/sales-email-config-validators.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Phase 7 §14.10 critical mitigation: SMTP/IMAP credential validators.
+ *
+ * Validates the API surface of the sales-config update payload: that
+ * malformed addresses are rejected, that sensible bounds are enforced,
+ * and that the empty-string-means-unchanged convention is preserved by the
+ * validator (the service-layer assumption).
+ */
+import { describe, expect, it } from 'vitest';
+
+import { updateSalesEmailConfigSchema } from '@/lib/validators/sales-email-config';
+
+describe('updateSalesEmailConfigSchema', () => {
+  it('accepts a fully populated payload', () => {
+    const r = updateSalesEmailConfigSchema.safeParse({
+      fromAddress: 'sales@example.com',
+      smtpHost: 'smtp.example.com',
+      smtpPort: 587,
+      smtpSecure: false,
+      smtpUser: 'sales',
+      smtpPass: 'secret',
+      noreplyFromAddress: 'noreply@example.com',
+      templateBerthPdfBody: 'Hi {{client.fullName}}',
+      templateBrochureBody: 'Hi {{client.fullName}}',
+      brochureMaxUploadMb: 50,
+      emailAttachThresholdMb: 15,
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts empty-string smtpPass (means "leave unchanged")', () => {
+    const r = updateSalesEmailConfigSchema.safeParse({ smtpPass: '' });
+    expect(r.success).toBe(true);
+  });
+
+  it('accepts explicit null smtpPass (means "clear")', () => {
+    const r = updateSalesEmailConfigSchema.safeParse({ smtpPass: null });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects malformed from address', () => {
+    const r = updateSalesEmailConfigSchema.safeParse({ fromAddress: 'not-an-email' });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects out-of-range smtp port', () => {
+    const r = updateSalesEmailConfigSchema.safeParse({ smtpPort: 99999 });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects unknown auth method', () => {
+    const r = updateSalesEmailConfigSchema.safeParse({ authMethod: 'oauth_apple' });
+    expect(r.success).toBe(false);
+  });
+
+  it('caps body templates at 50KB', () => {
+    const r = updateSalesEmailConfigSchema.safeParse({
+      templateBrochureBody: 'x'.repeat(60_000),
+    });
+    expect(r.success).toBe(false);
+  });
+});