feat(audit-cleanup): finish all 15 outstanding items from verified backlog

Audit cleanup completion plan, all tiers shipped:

Tier 1 (security + data integrity)
- A.7 RTBF true wipe: redact email_messages body/subject/addresses for
  threads owned by deleted client; redact document_sends.recipient_email;
  collect file storage keys + delete blobs post-commit.
- A.8 user_permission_overrides FK: documented inline why cascade is
  correct (not set-null as audit suggested) — overrides have no value
  without their user.
- W2.14 PII redaction: camelCase normalization in audit.ts +
  error-events.service.ts isSensitiveKey; added city/postal/country/
  birth fragments. firstName/lastName/dateOfBirth/postalCode etc. now
  caught in BOTH masker paths. 12 new test cases lock the coverage.

Tier 2 (Documenso completion + refactor)
- C.2: documentEvents.recipient_email column + partial unique index for
  per-recipient webhook dedup (migration 0075). handleDocumentSigned
  now sets recipient_email on insert.
- Phase 2: completion_cc_emails distribution. handleDocumentCompleted
  reads documents.completionCcEmails, filters out signer-duplicates
  case-insensitively, fans signed PDF out to non-signer recipients.
- C.4: extracted createPublicInterest() service from the 346-line
  api/public/interests route. Route becomes a thin shell (rate-limit,
  port resolution, audit log, email fan-out). The trio creation logic
  is now unit-testable without an HTTP fixture.
- Phase 4: POST /api/v1/document-templates/[id]/detect-fields wired
  to document-field-detector.detectFields(). Sparkles "Auto-detect"
  button added to template-editor.tsx — maps DetectedField → marker
  with best-guess merge token (DATE / NAME / EMAIL); user retags.

Tier 3 (reporting + recommender snapshot lockfiles)
- W7.reports: extracted rollupStageRevenue / rollupStageCounts /
  computeTotalForecast / computeOccupancyRate / rollupBerthStatusCounts
  into src/lib/services/report-math.ts (pure functions). 16 new tests
  including an inline-snapshot lockfile on a representative 7-stage
  forecast. report-generators.ts now delegates.
- W7.recommender: 18 new toMatchSnapshot tripwires on classifyTier
  boundaries + computeHeat at canonical input points.

Tier 4 (rolling)
- W6.attach: fixed outdated CLAUDE.md claim — threshold banner is
  informational and never depended on IMAP; bounce monitoring (the
  IMAP poller) is separate.
- D.1 + D.2: documented deferral inline with full why-not-build-it
  reasoning so a future engineer sees the rationale.
- G.1: representative formatDate sweep (audit-log-list, user-list,
  document-templates merge tokens, document-signing email). Rest of
  the ~100 sites stay rolling.

Quality gates: 1420/1420 vitest (46 new tests above baseline of 1374),
tsc clean, 0 lint errors.

Plan: docs/superpowers/plans/2026-05-18-audit-cleanup-completion.md
Migration: 0075_c2_document_events_recipient_email.sql (applied to dev DB).

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

src/app/api/v1/document-templates/[id]/detect-fields/route.ts

@@ -0,0 +1,66 @@
+import { NextResponse } from 'next/server';
+import { and, eq } from 'drizzle-orm';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { documentTemplates, files } from '@/lib/db/schema/documents';
+import { errorResponse, NotFoundError, ValidationError } from '@/lib/errors';
+import { getStorageBackend } from '@/lib/storage';
+import { detectFields } from '@/lib/services/document-field-detector';
+
+/**
+ * Phase 4 — Auto-detect signature/date/initials/name/email anchors in the
+ * template's current source PDF and return suggested field placements.
+ *
+ * The detector (`src/lib/services/document-field-detector.ts`) scans each
+ * page's text content via pdfjs-dist `getTextContent()` and matches anchors
+ * against a regex pattern table. Returned `DetectedField[]` is in percent-
+ * coords (0..100 of page dimensions), which the editor converts to its
+ * own 0..1 marker coords before adding to the field map.
+ *
+ * Permission: `admin.manage_settings` — same gate as the editor itself.
+ */
+export const POST = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx, params) => {
+    try {
+      const template = await db.query.documentTemplates.findFirst({
+        where: and(eq(documentTemplates.id, params.id!), eq(documentTemplates.portId, ctx.portId)),
+      });
+      if (!template) throw new NotFoundError('Template');
+      if (!template.sourceFileId) {
+        throw new ValidationError(
+          'Template has no source PDF — upload one first via the Replace PDF button',
+        );
+      }
+
+      const sourceFile = await db.query.files.findFirst({
+        where: and(eq(files.id, template.sourceFileId), eq(files.portId, ctx.portId)),
+      });
+      if (!sourceFile) {
+        throw new NotFoundError('Source PDF file row missing');
+      }
+
+      // Read the PDF blob from storage. Buffer the whole stream — the
+      // detector needs a contiguous Buffer for pdfjs-dist, and template
+      // source PDFs are capped at 10MB by the source-pdf upload route.
+      const backend = await getStorageBackend();
+      const stream = await backend.get(sourceFile.storagePath);
+      const chunks: Buffer[] = [];
+      for await (const chunk of stream) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : Buffer.from(chunk));
+      }
+      const pdfBuffer = Buffer.concat(chunks);
+
+      const detected = await detectFields(pdfBuffer);
+
+      return NextResponse.json({
+        data: {
+          fields: detected,
+          totalAnchors: detected.length,
+        },
+      });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);