feat(documenso): v2 coverage on getDocument/health + reminder webhook + admin UI benefits panel

- documenso-client.ts: getDocument now routes to /api/v2/envelope/{id} when port apiVersion=v2; checkDocumensoHealth surfaces resolved apiVersion for the admin Test button
- webhook route: handle DOCUMENT_REMINDER_SENT (structured log only, no audit-table noise) + DOCUMENT_CREATED / DOCUMENT_SENT (informational log)
- Admin Documenso page: prominent v1-vs-v2 explainer card listing v2-only capabilities the CRM already exploits (bulk fields, percent coords, richer fieldMeta, v2 webhook aliases, envelope endpoints) + amber roadmap callout for sequential signing / redirectUrl / template/use / envelope/update / non-SIGNER roles
- CLAUDE.md: idempotency + v2 webhook event list, berth-rules engine section, DOCUMENSO_API_URL gotcha, storage backend listByPrefix + timeout

Still v1-only (call out in admin UI roadmap): createDocument, generateDocumentFromTemplate, sendDocument, sendReminder, downloadSignedPdf. Migrating template/use to v2 requires per-template field-ID mapping in template config; deferred to a follow-up plan.

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

CLAUDE.md

@@ -88,7 +88,7 @@ src/
 - **Polymorphic ownership:** Yachts and invoice billing-entities use `<entity>_type` + `<entity>_id` column pairs (`'client' | 'company'`). Resolve owner identity through `src/lib/services/yachts.service.ts` / `eoi-context.ts` rather than reading the columns ad hoc — those services apply the type discriminator.
 - **EOI generation:** Two pathways share the same `EoiContext` (`src/lib/services/eoi-context.ts`). Documenso pathway calls the template-generate endpoint via `documenso-payload.ts`; in-app pathway fills the same source PDF (`assets/eoi-template.pdf`) via `src/lib/pdf/fill-eoi-form.ts` (pdf-lib AcroForm). Routed through `generateAndSign(...)` in `src/lib/services/document-templates.ts` with a `pathway` parameter.
 - **Merge fields:** Token catalog lives in `src/lib/templates/merge-fields.ts`; the `createTemplateSchema` validator uses `VALID_MERGE_TOKENS` as an allow-list, so unknown tokens are rejected at template creation time.
-- **Documenso webhooks:** Documenso (both v1.13 and 2.x) authenticates outbound webhooks by sending the configured secret in plaintext via the `X-Documenso-Secret` header — there is no HMAC. The receiver at `src/app/api/webhooks/documenso/route.ts` does a timing-safe equality check via `verifyDocumensoSecret`. Event names arrive as the uppercase Prisma enum on the wire (`DOCUMENT_SIGNED`, `DOCUMENT_COMPLETED`, etc.) even though the UI displays them as lowercase-dotted. The route also normalizes lowercase-dotted variants for forward-compat.
+- **Documenso webhooks:** Documenso (both v1.13 and 2.x) authenticates outbound webhooks by sending the configured secret in plaintext via the `X-Documenso-Secret` header — there is no HMAC. The receiver at `src/app/api/webhooks/documenso/route.ts` does a timing-safe equality check via `verifyDocumensoSecret`. Event names arrive as the uppercase Prisma enum on the wire (`DOCUMENT_SIGNED`, `DOCUMENT_COMPLETED`, etc.) even though the UI displays them as lowercase-dotted. The route also normalizes lowercase-dotted variants for forward-compat. `handleDocumentCompleted` is **idempotent** — early-returns when `doc.status === 'completed' && doc.signedFileId` so Documenso retries on 5xx don't insert duplicate file rows + orphan blobs. The switch handles `DOCUMENT_SIGNED|COMPLETED|REJECTED|DECLINED|OPENED|EXPIRED`, plus v2 aliases `RECIPIENT_VIEWED` / `RECIPIENT_SIGNED` (logged + routed to v1 equivalents).
 - **Documenso API responses:** 2.x renamed `id` → `documentId` and recipient `id` → `recipientId`; v1.13 still uses `id`. `src/lib/services/documenso-client.ts` runs every response through `normalizeDocument()` which reads either field name and surfaces the legacy `id` form to downstream consumers.
 - **Email templates:** Branded HTML lives in `src/lib/email/templates/`. The portal-auth flow uses `portal-auth.ts` (activation + reset). All templates use the legacy table-based layout with the Port Nimara logo + blurred overhead background, max-width 600px and `width:100%` for responsive shrink. The `<img>` URLs reference `s3.portnimara.com` directly (will move to `/public` later).
 - **Portal auth pages:** `/portal/login`, `/portal/activate`, `/portal/reset-password` and the CRM `/login`, `/reset-password`, `/set-password` all wrap their content in `<BrandedAuthShell>` (`src/components/shared/branded-auth-shell.tsx`) which renders the same blurred background + logo + white card the email templates use, so the in-app and email surfaces look unified.
@@ -112,8 +112,9 @@ src/
 - **Mooring number canonical format:** `^[A-Z]+\d+$` (e.g. `A1`, `B12`, `E18`) — no hyphen, no leading zeros. Stored, displayed, URL-encoded, and rendered in EOIs in this exact form. Phase 0 normalized the entire CRM dataset; the mooring-pattern regex gates the public `/api/public/berths/[mooringNumber]` route before any DB hit.
 - **Public berths API:** `/api/public/berths` (list) and `/api/public/berths/[mooringNumber]` (single) are the public-facing data feed for the marketing website. Output shape mirrors the legacy NocoDB Berths shape verbatim (`"Mooring Number"`, `"Side Pontoon"`, etc.) — see `src/lib/services/public-berths.ts`. Cache headers: `s-maxage=300, stale-while-revalidate=60`. Status mapping: `"Sold"` (berth.status=sold) > `"Under Offer"` (status=under_offer OR has any active `interest_berths.is_specific_interest=true` link with `interests.outcome IS NULL`) > `"Available"`. The companion `/api/public/health` endpoint is dual-mode: anonymous callers get `{status, timestamp}` (uptime monitors, never 503); requests carrying a timing-safe-matched `X-Intake-Secret` (compared against `WEBSITE_INTAKE_SECRET`) get the full `{status, env, appUrl, timestamp, checks: {db, redis}}` payload and a 503 if any dependency is down. The website uses the authenticated form on startup so it refuses to start when its `CRM_PUBLIC_URL` points at a different deployment env.
 - **Berth recommender:** Pure SQL ranking (no AI). Lives in `src/lib/services/berth-recommender.service.ts`. Tier ladder A/B/C/D classifies each feasible berth based on its `interest_berths` aggregates. Heat scoring (recency / furthest stage / interest count / EOI count) only fires for tier B (lost/cancelled-only history); per-port admin tunes weights via `system_settings` keys (`heat_weight_*`, `recommender_max_oversize_pct`, `recommender_top_n_default`, `fallthrough_policy`, `fallthrough_cooldown_days`, `tier_ladder_hide_late_stage`). The recommender enforces multi-port isolation both at the entry point (rejects cross-port interest lookups) AND inside the SQL aggregates CTE (defense-in-depth `i.port_id` filter).
+- **Berth rules engine:** Per-port `system_settings` rules in `src/lib/services/berth-rules-engine.ts`. Seven triggers, all wired: `eoi_sent`, `eoi_signed`, `deposit_received` (invoices.ts), `contract_signed` (documents.service.ts), `interest_archived` / `interest_completed` (interests.service.ts), `berth_unlinked` (interest-berths.service.ts). Service callers fire `evaluateRule(trigger, interestId, portId, meta)` via dynamic import to avoid circular deps. Default modes vary (`auto` for state changes, `suggest` for recommendations, `off` for `berth_unlinked`); admins tune via `berth_rules` system_settings key. Webhook auto-advance pairs the rule with `advanceStageIfBehind` so the pipeline stage and berth status move together.
 - **EOI bundle / range formatter:** Multi-berth EOIs render the in-bundle berth set as a compact range string ("A1-A3, B5-B7") via `formatBerthRange()` in `src/lib/templates/berth-range.ts`. Used only inside the Documenso `Berth Range` form field — CRM UI always shows berths as individual chips. The `{{eoi.berthRange}}` token is in `VALID_MERGE_TOKENS`.
-- **Pluggable storage backend:** Code never imports MinIO/S3 directly. All file I/O goes through `getStorageBackend()` from `src/lib/storage/`. Configured via `system_settings.storage_backend` ('s3' | 'filesystem'). Switching backends is a settings change + `pnpm tsx scripts/migrate-storage.ts` run. **Filesystem backend is single-node only**: refuses to start when `MULTI_NODE_DEPLOYMENT=true`. Multi-node deployments must use the s3-compatible backend.
+- **Pluggable storage backend:** Code never imports MinIO/S3 directly. All file I/O goes through `getStorageBackend()` from `src/lib/storage/`. The `StorageBackend` interface requires `put`, `get`, `head`, `delete`, `listByPrefix`, `presignUpload`, `presignDownload` — any new backend must implement all seven. Configured via `system_settings.storage_backend` ('s3' | 'filesystem'). Switching backends is a settings change + `pnpm tsx scripts/migrate-storage.ts` run (the migrator round-trips every blob in `files`, `berth_pdf_versions`, `brochure_versions`, `gdpr_exports` and verifies SHA-256 — `TABLES_WITH_STORAGE_KEYS` populated in 9a5ba87; was no-op before). MinIO ops are wrapped in a 30s `withTimeout` to prevent TCP-blackhole worker stalls. **Filesystem backend is single-node only**: refuses to start when `MULTI_NODE_DEPLOYMENT=true`. Multi-node deployments must use the s3-compatible backend.
 - **Per-berth PDFs:** Versioned via `berth_pdf_versions`; `berths.current_pdf_version_id` always points to the latest active version. Storage key is UUID-based per upload (not version-numbered) so concurrent uploads can't collide on blob paths; `pg_advisory_xact_lock` per berth_id serializes the version-number allocation. 3-tier parser: AcroForm → OCR (Tesseract.js with positional heuristics) → optional AI (rep clicks "AI parse" only when OCR confidence is low). Magic-byte (`%PDF-`) check enforced on BOTH the in-server upload path AND the presigned-PUT path (the post-upload service streams the first 5 bytes via the storage backend). Mooring-number mismatch between PDF and target berth surfaces as a service-level `ConflictError` unless the apply call passes `confirmMooringMismatch: true`.
 - **Brochures:** Per-port; default brochure marked via `is_default` (enforced by partial unique index on `(port_id) WHERE is_default=true AND archived_at IS NULL`). Archived brochures retain version history. Same upload flow as berth PDFs (presign + magic-byte verification on the post-upload register endpoint).
 - **Send-from accounts (sales send-outs):** Configurable via `system_settings`; defaults to `sales@portnimara.com` for human-touch and `noreply@portnimara.com` for automation. SMTP/IMAP passwords are AES-256-GCM encrypted at rest; the API never returns decrypted secrets — only `*PassIsSet` boolean markers. Send-out audit goes to `document_sends` (separate from `audit_logs` because of volume + binary refs). Body markdown is XSS-safe via `renderEmailBody()` (escape-then-allowlist; tested against the standard XSS vector list). Rate limit: 50 sends/user/hour individual. Pre-send size threshold: files > `email_attach_threshold_mb` ship as a 24h signed-URL link rather than an attachment (avoids the duplicate-send race from async bounces). The download-link fallback HTML-escapes the filename to prevent injection from admin-supplied brochure names. Bounce monitoring requires IMAP credentials in addition to SMTP — without them, the size-rejection banner stays disabled.
@@ -131,6 +132,10 @@ When you run a `db:push` or apply a migration via `psql` against a running dev s
 
 Copy `.env.example` to `.env` for local dev. See `src/lib/env.ts` for the full schema. Set `SKIP_ENV_VALIDATION=1` to bypass validation (used in Docker build).
 
+Required env gotchas:
+
+- `DOCUMENSO_API_URL` — **bare host only**, never include `/api/v1`. The client appends versioned paths based on `DOCUMENSO_API_VERSION` (`v1` for 1.13.x, `v2` for 2.x). A double-pathed URL returns 404 on every call with no useful diagnostic.
+
 Optional dev/test-only env vars (not in `.env.example`):
 
 - `EMAIL_REDIRECT_TO=<address>` — when set, every outbound email is rerouted to this address regardless of the requested recipient and the subject is prefixed with `[redirected from <original>]`. Dev safety net so seeded fake-client emails don't escape; **must be unset in production**.

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

@@ -1,15 +1,19 @@
+import { CheckCircle2, Info } from 'lucide-react';
+
 import {
   SettingsFormCard,
   type SettingFieldDef,
 } from '@/components/admin/shared/settings-form-card';
 import { DocumensoTestButton } from '@/components/admin/documenso/documenso-test-button';
 import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 
 const API_FIELDS: SettingFieldDef[] = [
   {
     key: 'documenso_api_url_override',
     label: 'API URL override',
-    description: 'Optional. Falls back to DOCUMENSO_API_URL env when blank.',
+    description:
+      'Optional. Falls back to DOCUMENSO_API_URL env when blank. Bare host only — never include /api/v1; the client appends versioned paths based on the API version below.',
     type: 'string',
     placeholder: 'https://documenso.example.com',
     defaultValue: '',
@@ -25,11 +29,11 @@ const API_FIELDS: SettingFieldDef[] = [
     key: 'documenso_api_version_override',
     label: 'API version',
     description:
-      'Which Documenso REST API to call against this port. v1 supports Documenso 1.x (per-field PIXEL placement, /api/v1/templates and /api/v1/documents). v2 unlocks the envelope/embed endpoints introduced in Documenso 2.x. Use the test-connection button below after switching to confirm the chosen version actually works against this port’s instance.',
+      "Which Documenso REST API this port targets. v1 = Documenso 1.13.x stable. v2 = Documenso 2.x with the envelope model and richer per-field metadata. Test the connection after switching. See the v2 benefits card above for what changes when you flip this — and note that template-based EOI generation still uses the v1 formValues shape regardless of this setting (v2 template/use migration is on the roadmap).",
     type: 'select',
     options: [
-      { value: 'v1', label: 'v1 — Documenso 1.x (legacy stable)' },
-      { value: 'v2', label: 'v2 — Documenso 2.x (envelope + embedded signing)' },
+      { value: 'v1', label: 'v1 — Documenso 1.13.x (default, stable)' },
+      { value: 'v2', label: 'v2 — Documenso 2.x (envelope, recommended for new ports)' },
     ],
     defaultValue: 'v1',
   },
@@ -148,6 +152,108 @@ export default function DocumensoSettingsPage() {
         description="API credentials, signer identities, and document generation behaviour. Use the test-connection button to verify a saved configuration before relying on it."
       />
 
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2 text-base">
+            <Info className="h-4 w-4" aria-hidden="true" />
+            v1 vs v2 — what changes when you flip the API version
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4 text-sm">
+          <p className="text-muted-foreground">
+            The CRM supports both Documenso 1.13.x (v1) and 2.x (v2). v1 is the default for
+            backwards compatibility. v2 is recommended for new ports and unlocks the features
+            below. Switching versions does <strong>not</strong> require any code changes —
+            version-aware client methods pick the right endpoint per port. Switch, save, then run
+            the test-connection button to confirm the chosen instance is actually on the matching
+            Documenso version.
+          </p>
+
+          <div className="rounded-md border border-border bg-muted/40 p-3">
+            <p className="mb-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+              v2-only capabilities the CRM already uses when you pick v2
+            </p>
+            <ul className="space-y-1.5">
+              <li className="flex items-start gap-2">
+                <CheckCircle2 className="mt-0.5 h-4 w-4 flex-shrink-0 text-emerald-600" aria-hidden="true" />
+                <span>
+                  <strong>Bulk field placement.</strong> One API call per envelope vs. v1&apos;s
+                  per-field POST loop. Faster contract generation, fewer transient retries on
+                  multi-field uploaded contracts.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2 className="mt-0.5 h-4 w-4 flex-shrink-0 text-emerald-600" aria-hidden="true" />
+                <span>
+                  <strong>Percent-based field coordinates.</strong> No page-dimension lookup
+                  needed — coordinates are portable across page sizes. v1 requires us to assume A4
+                  for auto-placed fields.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2 className="mt-0.5 h-4 w-4 flex-shrink-0 text-emerald-600" aria-hidden="true" />
+                <span>
+                  <strong>Richer field metadata.</strong> TEXT labels &amp; required flags, NUMBER
+                  min/max + format, CHECKBOX/DROPDOWN/RADIO option lists with defaults — all
+                  ignored by v1, surfaced by v2 in the signing UI.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2 className="mt-0.5 h-4 w-4 flex-shrink-0 text-emerald-600" aria-hidden="true" />
+                <span>
+                  <strong>v2-flavoured webhook events.</strong> <code>RECIPIENT_VIEWED</code>,{' '}
+                  <code>RECIPIENT_SIGNED</code>, <code>DOCUMENT_RECIPIENT_COMPLETED</code>,{' '}
+                  <code>DOCUMENT_DECLINED</code>, <code>DOCUMENT_REMINDER_SENT</code> — all routed
+                  through the same dedup + audit pipeline as v1 events.
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <CheckCircle2 className="mt-0.5 h-4 w-4 flex-shrink-0 text-emerald-600" aria-hidden="true" />
+                <span>
+                  <strong>Envelope/embed endpoints.</strong> <code>GET</code> and{' '}
+                  <code>DELETE</code> go through <code>/api/v2/envelope/...</code> when v2 is
+                  selected. Future embedded-signing iframe work will plug in here.
+                </span>
+              </li>
+            </ul>
+          </div>
+
+          <div className="rounded-md border border-amber-200 bg-amber-50/60 p-3 dark:border-amber-900/40 dark:bg-amber-950/30">
+            <p className="mb-2 text-xs font-semibold uppercase tracking-wider text-amber-700 dark:text-amber-400">
+              v2 capabilities on the roadmap (not yet wired)
+            </p>
+            <ul className="space-y-1.5 text-muted-foreground">
+              <li>
+                <strong>Sequential signing</strong> (<code>signingOrder: SEQUENTIAL</code>) — would
+                force client → developer → approver order on EOIs instead of all-at-once.
+              </li>
+              <li>
+                <strong>Post-signing redirect URL</strong> (<code>redirectUrl</code>) — would land
+                signed clients back on the portal rather than Documenso&apos;s page.
+              </li>
+              <li>
+                <strong>Single-shot <code>/template/use</code></strong> (v2 prefillFields by ID
+                replacing v1 formValues by name) — currently the EOI flow still uses the v1
+                template path even when API version is v2. Needs per-template field-ID mapping in
+                the template config before we can switch.
+              </li>
+              <li>
+                <strong>Update envelope metadata</strong> (<code>/envelope/update</code>) — change
+                title / subject / redirectUrl after creation without re-generating.
+              </li>
+              <li>
+                <strong>Recipient roles beyond SIGNER</strong> (APPROVER / CC / VIEWER) — would let
+                sales managers receive copies without a signature slot.
+              </li>
+            </ul>
+            <p className="mt-2 text-xs text-muted-foreground">
+              These items have no admin setting yet because they need code changes first. They
+              live here so you know what&apos;s in the pipeline.
+            </p>
+          </div>
+        </CardContent>
+      </Card>
+
       <SettingsFormCard
         title="Documenso API"
         description="Per-port API credentials. Leave blank to use the global env defaults."

src/app/api/webhooks/documenso/route.ts

@@ -235,6 +235,29 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
         await handleDocumentExpired({ documentId: documensoId, ...portScope });
         break;
 
+      case 'DOCUMENT_REMINDER_SENT':
+        // Documenso auto-reminded a recipient. We don't mutate state — the
+        // reminder is informational. Structured log line is enough for
+        // telemetry without polluting the audit_logs table on every
+        // auto-reminder Documenso sends across all ports.
+        logger.info(
+          {
+            documensoId,
+            recipients: recipients.map((r) => r.email),
+            ...portScope,
+          },
+          'Documenso auto-reminder sent',
+        );
+        break;
+
+      case 'DOCUMENT_CREATED':
+      case 'DOCUMENT_SENT':
+        // Created + sent are informational — we initiated these from our
+        // side so the state is already authoritative in our DB. Log for
+        // forward-compat / out-of-band-creation telemetry.
+        logger.info({ event, documensoId, ...portScope }, 'Documenso lifecycle event');
+        break;
+
       default:
         logger.info({ event }, 'Unhandled Documenso webhook event type');
     }

src/lib/services/documenso-client.ts

@@ -229,7 +229,12 @@ export async function sendDocument(docId: string, portId?: string): Promise<Docu
 }
 
 export async function getDocument(docId: string, portId?: string): Promise<DocumensoDocument> {
-  return documensoFetch(`/api/v1/documents/${docId}`, undefined, portId).then(normalizeDocument);
+  const { apiVersion } = await resolveCreds(portId);
+  // v1: GET /api/v1/documents/{id}
+  // v2: GET /api/v2/envelope/{id} — same response normalizer (id ↔ documentId,
+  //      recipientId ↔ id handled by normalizeDocument).
+  const path = apiVersion === 'v2' ? `/api/v2/envelope/${docId}` : `/api/v1/documents/${docId}`;
+  return documensoFetch(path, undefined, portId).then(normalizeDocument);
 }
 
 /**
@@ -295,13 +300,16 @@ export async function downloadSignedPdf(docId: string, portId?: string): Promise
 /** Convenience health-check used by the admin "Test connection" button. */
 export async function checkDocumensoHealth(
   portId?: string,
-): Promise<{ ok: boolean; status?: number; error?: string }> {
+): Promise<{ ok: boolean; status?: number; error?: string; apiVersion?: DocumensoApiVersion }> {
   try {
-    const { baseUrl, apiKey } = await resolveCreds(portId);
+    const { baseUrl, apiKey, apiVersion } = await resolveCreds(portId);
+    // Both v1 and v2 expose /api/v1/health (v2 keeps the v1 path for
+    // backward compat). If a v2 deployment ever moves this we'll add a
+    // v2 branch — but as of Documenso 2.x there isn't a v2 health path.
     const res = await fetchWithTimeout(`${baseUrl}/api/v1/health`, {
       headers: { Authorization: `Bearer ${apiKey}` },
     });
-    return { ok: res.ok, status: res.status };
+    return { ok: res.ok, status: res.status, apiVersion };
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : 'Unknown error' };
   }