feat(dashboard): merge rearrange into the Customize modal

Two days, two modals, both touching widget layout - collapsed into
one. The separate "Rearrange" button + RearrangeWidgetsDialog from
54c5d0f are gone; the Customize modal now does both jobs:

- Two sections in the body: "On dashboard (N)" and "Hidden (N)"
- Visible rows are sortable (drag handle on the left, position number,
  switch on the right). Single SortableContext, vertical strategy.
- Hidden rows are toggle-only (no drag handle - order doesn't matter
  for off-dashboard widgets). Flipping the switch on appends to the
  bottom of the visible section.
- Both visibility toggles and reorder commits optimistically via
  useDashboardWidgets so the dashboard reflows in the background.

dashboard-shell: removes the Rearrange button + RearrangeWidgetsDialog
import + setOrder destructure. rearrange-widgets-dialog.tsx deleted.

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

.claude/scheduled_tasks.lock

@@ -1 +0,0 @@
-{"sessionId":"fd05cbd7-d695-4a70-9223-4b25f3369829","pid":88534,"acquiredAt":1776866083076}

.dockerignore

@@ -0,0 +1,69 @@
+# Build context exclusions — keep the image small AND prevent secrets
+# from accidentally leaking into a layer.
+# The audit caught that the previous absence of this file shipped a
+# 7.6 GB build context, with .env files reachable via `COPY . .`.
+
+# Version control
+.git
+.gitignore
+.gitattributes
+
+# Local env / secrets
+.env
+.env.*
+!.env.example
+
+# Node / pnpm
+node_modules
+.pnpm-store
+.pnpm-debug.log
+npm-debug.log
+yarn-debug.log
+yarn-error.log
+
+# Next.js build artifacts (regenerated inside the image)
+.next
+out
+
+# Tooling caches
+.cache
+.turbo
+.eslintcache
+.vercel
+.swc
+
+# OS noise
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode
+.idea
+*.swp
+
+# Testing / coverage
+coverage
+.nyc_output
+test-results
+playwright-report
+tests/e2e/visual/snapshots.spec.ts-snapshots/*.png
+playwright/.cache
+
+# Project artefacts that don't belong in a runtime image
+.claude
+.husky
+docs
+AGENTS.md
+AUDIT-*.md
+SECURITY-GUIDELINES.md
+PROMPTS-*.md
+README.md
+*.log
+*.tgz
+
+# Generated / scratch
+.serena
+.superpowers
+.remember
+.audit-cache
+.specstory

.env.dev.template

@@ -0,0 +1,58 @@
+# ─── Port Nimara CRM — DEV environment template ──────────────────────────────
+#
+# Copy to `.env` for local development. Values match the docker-compose.dev.yml
+# defaults (Postgres on :5434, Redis on :6379, MinIO on :9000).
+#
+# Integration credentials (Documenso, OpenAI, SMTP, S3, etc.) belong in the
+# admin UI after first login — see /admin/<integration>. The fallbacks at the
+# bottom are commented out by default to make the admin path obvious.
+
+# ─── Required (boot-time) ────────────────────────────────────────────────────
+
+DATABASE_URL=postgresql://crm:changeme@localhost:5434/port_nimara_crm
+REDIS_URL=redis://:changeme@localhost:6379
+
+BETTER_AUTH_SECRET=dev-secret-please-change-32-chars-minimum-12345678
+BETTER_AUTH_URL=http://localhost:3000
+CSRF_SECRET=dev-csrf-secret-please-change-32-chars-minimum-12345
+
+# Generated once for local dev. Production uses a different rotated key.
+EMAIL_CREDENTIAL_KEY=0000000000000000000000000000000000000000000000000000000000000000
+
+APP_URL=http://localhost:3000
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+NODE_ENV=development
+LOG_LEVEL=debug
+
+# ─── Dev-only safety net ─────────────────────────────────────────────────────
+
+# When set, every outbound email is rerouted to this address.
+# Configure to YOUR personal email so seeded fake-client sends don't escape.
+# EMAIL_REDIRECT_TO=
+
+# Skip env validation (used by Docker build only).
+# SKIP_ENV_VALIDATION=
+
+# ─── Optional integration env fallbacks (admin UI is canonical) ──────────────
+# Uncomment + set ONLY if you want to bootstrap a port via env. Otherwise
+# configure each integration via /admin/<integration> after first login.
+
+# DOCUMENSO_API_URL=https://documenso.dev.example
+# DOCUMENSO_API_KEY=
+# DOCUMENSO_API_VERSION=v2
+# DOCUMENSO_WEBHOOK_SECRET=
+
+# SMTP_HOST=smtp.example
+# SMTP_PORT=587
+
+# OPENAI_API_KEY=
+
+# Local MinIO (set if NOT using the admin UI to configure storage)
+# MINIO_ENDPOINT=localhost
+# MINIO_PORT=9000
+# MINIO_ACCESS_KEY=minioadmin
+# MINIO_SECRET_KEY=minioadmin
+# MINIO_BUCKET=crm-files
+# MINIO_USE_SSL=false
+# MINIO_AUTO_CREATE_BUCKET=true

.env.example

@@ -1,46 +1,115 @@
+# ─── Port Nimara CRM env template ─────────────────────────────────────────────
+#
+# This file documents every env var the CRM understands. Most integration
+# settings have been moved into the per-port admin UI (see
+# `docs/superpowers/specs/2026-05-15-env-to-admin-migration-design.md`):
+#
+#   /admin/documenso     — Documenso API URL, key, version, webhook secret,
+#                          signers, templates
+#   /admin/ai            — OpenAI API key + model + master switch
+#   /admin/email         — SMTP host/port/user/pass, from-address
+#   /admin/storage       — S3/MinIO endpoint, bucket, access key, secret key
+#
+# After a fresh deploy:
+#   1. Set the REQUIRED block below (DB/Redis/auth secrets/encryption key).
+#   2. Boot the app and run `/setup` to create the first super-admin.
+#   3. Open `/admin/<integration>` and configure each one. Each field shows
+#      a "Using env fallback" badge if it's still inheriting from env, plus
+#      a "Copy from env" button for one-click migration into the DB.
+#
+# The COMMENTED env vars in the OPTIONAL block below still work as a runtime
+# fallback if you set them — useful for staging / dev to bootstrap quickly,
+# or for backward compatibility with older deployments. New ports inherit
+# from these as their initial defaults until the admin UI overrides them.
+#
+# ─── REQUIRED (boot-time secrets — must be in env) ────────────────────────────
+
 # Database
 DATABASE_URL=postgresql://crm:changeme@localhost:5432/port_nimara_crm
 
-# Redis
+# Redis (BullMQ + Socket.IO adapter)
 REDIS_URL=redis://:changeme@localhost:6379
 
-# Auth
+# Auth (must be 32+ char random strings; rotate carefully)
 BETTER_AUTH_SECRET=change-me-to-a-random-string-at-least-32-chars
 BETTER_AUTH_URL=http://localhost:3000
 CSRF_SECRET=change-me-to-a-random-string-at-least-32-chars
 
-# MinIO
-MINIO_ENDPOINT=localhost
-MINIO_PORT=9000
-MINIO_ACCESS_KEY=minioadmin
-MINIO_SECRET_KEY=minioadmin
-MINIO_BUCKET=crm-files
-MINIO_USE_SSL=false
-
-# Documenso
-DOCUMENSO_API_URL=https://documenso.example.com/api/v1
-DOCUMENSO_API_KEY=your-documenso-api-key
-DOCUMENSO_WEBHOOK_SECRET=your-webhook-secret-min-16-chars
-
-# Email (SMTP)
-SMTP_HOST=mail.portnimara.com
-SMTP_PORT=587
-
-# Encryption (64-char hex string for AES-256)
+# AES-256 key for credential encryption at rest. 64-char hex string.
+# Generate with: openssl rand -hex 32
+# CRITICAL: rotating this orphans every encrypted credential in system_settings
+# (Documenso API key, SMTP password, OpenAI key, S3 access/secret keys).
+# Plan a re-keying flow before rotating in production.
 EMAIL_CREDENTIAL_KEY=0000000000000000000000000000000000000000000000000000000000000000
 
-# Google OAuth (optional)
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-
-# OpenAI (optional)
-OPENAI_API_KEY=
-
-# App
+# App URL — used by middleware redirects + outbound email link construction.
 APP_URL=http://localhost:3000
-PUBLIC_SITE_URL=https://portnimara.com
+
+# Inlined into the client JS bundle at build time. Must match APP_URL.
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# Process basics
 NODE_ENV=development
 LOG_LEVEL=info
 
-# Next.js public
-NEXT_PUBLIC_APP_URL=http://localhost:3000
+# When true, the filesystem storage backend refuses to start. Multi-node
+# deploys MUST use the s3-compatible backend (per CLAUDE.md).
+# MULTI_NODE_DEPLOYMENT=false
+
+
+# ─── OPTIONAL: integration env fallbacks ──────────────────────────────────────
+# Each of the following is configurable in the admin UI. Uncomment + set ANY
+# of these to provide a fallback that ports inherit when their admin field is
+# blank. The admin UI labels each inherited field with a "Using env fallback"
+# badge and offers a "Copy from env" button for one-click migration into the
+# port-scoped DB row.
+
+# ─ Documenso (admin: /admin/documenso) ─
+# DOCUMENSO_API_URL=https://documenso.example.com    # Bare host. Never include /api/v1.
+# DOCUMENSO_API_KEY=your-documenso-api-key           # AES-encrypted once written via admin
+# DOCUMENSO_API_VERSION=v1                            # v1 (1.13.x) or v2 (2.x)
+# DOCUMENSO_WEBHOOK_SECRET=                           # Min 16 chars. Generate: openssl rand -hex 16
+# DOCUMENSO_TEMPLATE_ID_EOI=
+# DOCUMENSO_CLIENT_RECIPIENT_ID=
+# DOCUMENSO_DEVELOPER_RECIPIENT_ID=
+# DOCUMENSO_APPROVAL_RECIPIENT_ID=
+
+# ─ Email / SMTP (admin: /admin/email) ─
+# SMTP_HOST=mail.portnimara.com
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASS=                                          # AES-encrypted once written via admin
+# SMTP_FROM=                                          # e.g. "Port Nimara <noreply@example.com>"
+
+# Dev/test safety net: when set, every outbound email is rerouted to this
+# address regardless of recipient. Subject is prefixed with [redirected from <orig>].
+# CRITICAL: env validation refuses boot if NODE_ENV=production AND this is set.
+# EMAIL_REDIRECT_TO=
+
+# ─ Storage / S3 / MinIO (admin: /admin/storage) ─
+# MINIO_ENDPOINT=localhost
+# MINIO_PORT=9000
+# MINIO_ACCESS_KEY=                                   # AES-encrypted once written via admin
+# MINIO_SECRET_KEY=                                   # AES-encrypted (already)
+# MINIO_BUCKET=crm-files
+# MINIO_USE_SSL=false
+# MINIO_AUTO_CREATE_BUCKET=false                      # Auto-create bucket at boot
+
+# ─ OpenAI (admin: /admin/ai) ─
+# OPENAI_API_KEY=                                     # AES-encrypted once written via admin
+
+# ─ Public marketing site URL (admin: /admin/general — TODO) ─
+# PUBLIC_SITE_URL=https://portnimara.com
+
+# ─ Webhook intake from marketing site (deployment-shared, env-only) ─
+# Shared secret with the marketing website's CRM_INTAKE_SECRET. Min 16 chars.
+# WEBSITE_INTAKE_SECRET=
+
+# ─ Sentry (optional — when unset the SDK is a no-op) ─
+# NEXT_PUBLIC_SENTRY_DSN=
+# SENTRY_ENVIRONMENT=
+# SENTRY_TRACES_SAMPLE_RATE=0.1
+
+# ─ Google OAuth (not currently used) ─
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=

.env.prod.template

@@ -0,0 +1,58 @@
+# ─── Port Nimara CRM — PROD environment template ─────────────────────────────
+#
+# Production env contains ONLY the boot-time minimum: DB connection, auth
+# secrets, encryption key, app URL, log level. Every integration credential
+# (Documenso, OpenAI, SMTP, S3) is configured per-port in the admin UI after
+# the first super-admin completes /setup. This keeps secrets out of the
+# infrastructure layer (k8s ConfigMap, .env files, deploy logs).
+#
+# Generate fresh secrets:
+#   openssl rand -hex 32      # for BETTER_AUTH_SECRET, CSRF_SECRET
+#   openssl rand -hex 32      # for EMAIL_CREDENTIAL_KEY (must be 64 hex chars)
+
+# ─── Required ────────────────────────────────────────────────────────────────
+
+DATABASE_URL=postgresql://USER:PASS@HOST:5432/port_nimara_crm
+REDIS_URL=redis://:PASS@HOST:6379
+
+BETTER_AUTH_SECRET=GENERATE_OPENSSL_RAND_HEX_32
+BETTER_AUTH_URL=https://crm.example.com
+CSRF_SECRET=GENERATE_OPENSSL_RAND_HEX_32
+
+# CRITICAL: rotating this orphans every encrypted credential in
+# system_settings. Plan a re-keying flow before rotating.
+EMAIL_CREDENTIAL_KEY=GENERATE_OPENSSL_RAND_HEX_32_PRODUCES_64_CHARS
+
+APP_URL=https://crm.example.com
+NEXT_PUBLIC_APP_URL=https://crm.example.com
+
+NODE_ENV=production
+LOG_LEVEL=info
+
+# ─── Multi-node guard ────────────────────────────────────────────────────────
+# Set true if running > 1 app instance. Forces the storage backend off
+# filesystem onto S3-compatible (filesystem mode is single-node only).
+MULTI_NODE_DEPLOYMENT=true
+
+# ─── Sentry (highly recommended in prod) ─────────────────────────────────────
+NEXT_PUBLIC_SENTRY_DSN=https://YOUR_KEY@YOUR_PROJECT.ingest.sentry.io/PROJECT_ID
+SENTRY_ENVIRONMENT=production
+SENTRY_TRACES_SAMPLE_RATE=0.1
+
+# ─── Webhook intake from marketing site (deployment-shared) ──────────────────
+# Must match the marketing site's CRM_INTAKE_SECRET. Min 16 chars.
+WEBSITE_INTAKE_SECRET=GENERATE_OPENSSL_RAND_HEX_16
+
+# ─── DO NOT SET in production ────────────────────────────────────────────────
+# EMAIL_REDIRECT_TO     — Will fail boot validation (silently rewrites every
+#                          outbound email recipient).
+# SKIP_ENV_VALIDATION   — Bypasses safety checks. Internal use only.
+
+# ─── Integration credentials live in /admin/<integration>, NOT here ──────────
+# Once deployed:
+#   1. Run `pnpm exec drizzle-kit push` (or your migration script)
+#   2. Hit https://crm.example.com/setup to create the first super-admin
+#   3. Log in → /admin/documenso, /admin/email, /admin/storage, /admin/ai
+#   4. Configure each integration. AES-encrypted at rest.
+#   5. Run `pnpm tsx scripts/encrypt-plaintext-credentials.ts` once to encrypt
+#      any legacy plaintext rows from older deployments.

.gitignore

@@ -28,9 +28,36 @@ docker-compose.override.yml
 
 # Ad-hoc screenshots / scratch artifacts at repo root
 /*.png
+/*.jpg
+# Local-only dashboard widget-combo screenshots — regenerated by manual testing
+/combos/
 
 # Legacy Nuxt portal — kept on disk for reference, not tracked here
 /client-portal/
 
+# Sister marketing site — separate Nuxt project, not part of CRM tracking
+/website/
+
 # Mobile audit screenshots — generated locally, regenerable
 /.audit/
+/.audit-screenshots/
+
+# Migration script output (CSV reports, transcripts)
+.migration/
+
+# Tool caches / runtime state
+/.claude/
+/.serena/
+/ruvector.db
+
+# Filesystem storage backend root (FilesystemBackend default location)
+/storage/
+
+# Private credentials + forensic captures — never commit
+/private/
+
+# Local berth-PDF + brochure samples used as upload fixtures during dev.
+/berth_pdf_example/
+
+# Scratch / audit artefacts
+tmp/

.lintstagedrc.json

@@ -1,4 +1,4 @@
 {
-  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+  "*.{ts,tsx}": ["eslint --fix", "prettier --write", "node scripts/tsc-staged.mjs"],
   "*.{json,md,css}": ["prettier --write"]
 }

CLAUDE.md

@@ -1,18 +1,17 @@
 # Port Nimara CRM
 
-Multi-tenant CRM for marina/port management. Built with Next.js 15 App Router (standalone output), React 19, TypeScript (strict), Tailwind CSS 3, and Drizzle ORM on PostgreSQL.
+Multi-tenant CRM for marina/port management. Next.js 15 App Router (standalone), React 19, TypeScript strict (`noUncheckedIndexedAccess`, no `any`), Drizzle ORM on PostgreSQL.
 
 ## Quick reference
 
 ```bash
-pnpm dev              # Start dev server
+pnpm dev              # Dev server
 pnpm build            # Production build
-pnpm lint             # ESLint
-pnpm format           # Prettier
+pnpm lint / format    # ESLint / Prettier
 pnpm db:generate      # Generate Drizzle migrations
 pnpm db:push          # Push schema to DB
 pnpm db:studio        # Drizzle Studio GUI
-pnpm db:seed          # Seed database (tsx src/lib/db/seed.ts)
+pnpm db:seed          # Seed (tsx src/lib/db/seed.ts)
 
 # Tests
 pnpm exec vitest run                                  # Unit + integration (~3s)
@@ -26,25 +25,51 @@ pnpm exec playwright test --project=visual --update-snapshots  # Regenerate base
 # Dev helpers
 pnpm tsx scripts/dev-trigger-portal-invite.ts         # Send a portal activation email
 pnpm tsx scripts/dev-imap-probe.ts                    # Dump recent IMAP inbox messages
+
+# Cloudflare quick-tunnel (for Documenso webhook testing)
+launchctl load   ~/Library/LaunchAgents/solutions.letsbe.pn-crm-tunnel.plist   # start
+launchctl unload ~/Library/LaunchAgents/solutions.letsbe.pn-crm-tunnel.plist   # stop
+./scripts/tunnel-url.sh --copy                                                 # print + copy webhook URL
+
+# Schema migration (pnpm db:migrate is broken — apply via psql)
+PGPASSWORD=changeme psql -h localhost -p 5434 -U crm -d port_nimara_crm -f src/lib/db/migrations/0075_*.sql
 ```
 
-## Tech stack
+## Working in this repo — skills, MCPs, agents
 
-- **Framework:** Next.js 15.1 App Router, `output: 'standalone'`, `experimental.typedRoutes`
-- **Auth:** better-auth (session cookie: `pn-crm.session_token`)
-- **Database:** PostgreSQL via `postgres` driver + Drizzle ORM
+Reach for these before grinding through tasks manually:
+
+- **Skills** (invoke with `Skill` tool):
+  - `superpowers:brainstorming` before any feature/component work — explores intent + design first
+  - `superpowers:test-driven-development` for any feature or bugfix
+  - `superpowers:systematic-debugging` for any bug / test failure / unexpected behavior
+  - `superpowers:verification-before-completion` before claiming "done" or committing
+  - `superpowers:writing-plans` / `executing-plans` for multi-step specs
+  - `superpowers:dispatching-parallel-agents` when 2+ tasks are independent
+  - `frontend-design:frontend-design` for new UI work (avoids generic AI aesthetics)
+  - `code-review:code-review` and `security-review` before merging
+- **MCPs**:
+  - **Context7** (`mcp__plugin_context7_context7__*`) — pull current docs for Next 15, Drizzle, better-auth, BullMQ, Tailwind, Radix etc. Prefer over web search; our training data lags.
+  - **Playwright** (`mcp__plugin_playwright_playwright__*`) — verify UI changes in a real browser before reporting "done". Default viewport — do NOT call `browser_resize`.
+  - **Serena** (`mcp__plugin_serena_serena__*`) — symbol-level navigation (`find_symbol`, `find_referencing_symbols`, `replace_symbol_body`). Much faster than grep for "where is this called".
+  - **Postman** (`mcp__claude_ai_Postman__*`) — when designing or auditing API surfaces.
+- **Agents** (via `Agent` tool, `subagent_type=`):
+  - `Explore` for any codebase search that would take > 3 queries
+  - `feature-dev:code-explorer` / `code-architect` / `code-reviewer` for new feature work
+- **Doctrine**: skills override default behavior except user instructions in this file. If a CLAUDE.md rule conflicts with a skill, this file wins.
+- **Manual UAT — single master doc**: all multi-day Playwright + React Grab UAT findings go into `docs/superpowers/audits/alpha-uat-master.md` (the cross-cutting "alpha" audit that spans many sessions). Append to it as findings land in chat — don't create per-day files. Buckets: Quick fixes (<15min), Medium (15min–2h), Features/larger (>2h), Bugs (severity-tagged), Cross-references to the active full-codebase audit. Don't ask for the format each time.
+
+## Tech stack (non-obvious choices)
+
+- **Auth:** better-auth — session cookie `pn-crm.session_token`
 - **Queue:** BullMQ + Redis (ioredis)
-- **Storage:** MinIO (S3-compatible)
+- **Storage:** pluggable via `getStorageBackend()` — MinIO/S3 default; never import the S3 SDK directly
 - **Realtime:** Socket.IO with Redis adapter
-- **UI:** Radix UI primitives, shadcn/ui components (`src/components/ui/`), Lucide icons, CVA + tailwind-merge + clsx
+- **UI:** Radix UI + shadcn/ui (`src/components/ui/`) + Lucide + CVA + tailwind-merge
 - **Forms:** react-hook-form + zod resolvers
-- **Tables:** TanStack Table
-- **State:** Zustand stores (`src/stores/`), TanStack React Query
-- **PDF:** pdfme
+- **State:** Zustand (`src/stores/`) + TanStack React Query
+- **PDF:** pdfme (templates) + pdf-lib (AcroForm fill)
 - **Email:** nodemailer + imapflow + mailparser
-- **AI:** OpenAI SDK (optional)
-- **Testing:** Vitest (unit), Playwright (e2e)
-- **Logging:** pino + pino-pretty
 
 ## Project structure
 
@@ -52,93 +77,143 @@ pnpm tsx scripts/dev-imap-probe.ts                    # Dump recent IMAP inbox m
 src/
   app/
     (auth)/          # Login/auth pages
-    (dashboard)/     # Main app - route: /[portSlug]/...
+    (dashboard)/     # Main app — route: /[portSlug]/...
     (portal)/        # Client portal
-    api/             # API routes
+    api/             # API routes (route.ts + sibling handlers.ts)
   components/
     ui/              # shadcn/ui base components
     layout/          # Shell, sidebar, header
-    [domain]/        # Domain components (clients, invoices, berths, etc.)
-    shared/          # Cross-domain shared components
-  hooks/             # React hooks (use-auth, use-permissions, use-socket, etc.)
+    [domain]/        # clients, yachts, companies, reservations, berths, …
+    shared/          # Cross-domain (BrandedAuthShell, InlineEditableField, …)
+  hooks/             # use-auth, use-permissions, use-socket, …
   lib/
-    api/             # API client utilities
+    api/             # Route helpers (parseBody, errorResponse, withAuth, …)
     auth/            # better-auth config
-    db/
-      schema/        # Drizzle schema (one file per domain)
-      migrations/    # Generated Drizzle migrations
+    db/schema/       # Drizzle schema — one file per domain, re-exported from index.ts
+    db/migrations/   # Generated Drizzle migrations (apply via psql in dev)
     env.ts           # Zod env validation (SKIP_ENV_VALIDATION=1 bypasses)
-    services/        # Business logic services
-    validators/      # Zod schemas for API input validation
-    utils/           # Shared utilities
+    services/        # Business logic
+    storage/         # Pluggable storage backend
+    templates/       # Email/document merge fields, berth-range formatter
+    validators/      # Zod schemas for API input
   middleware.ts      # Auth middleware (cookie check, redirects)
-  providers/         # React context providers
-  stores/            # Zustand stores
-  types/             # Shared TypeScript types
+  stores/            # Zustand
 ```
 
-## Conventions
+## Conventions & gotchas
 
-- **TypeScript:** Strict mode with `noUncheckedIndexedAccess`. No `any` (ESLint error).
-- **Formatting:** Prettier - single quotes, semicolons, trailing commas, 2-space indent, 100 char line width.
-- **Lint:** ESLint flat config extending `next/core-web-vitals`, `next/typescript`, `prettier`. Unused vars prefixed with `_` are allowed.
-- **Imports:** Use `@/*` path alias (maps to `src/*`).
-- **Components:** shadcn/ui pattern - base components in `src/components/ui/`, domain components in `src/components/[domain]/`. Yacht / company / reservation domains live in `components/yachts`, `components/companies`, `components/reservations` respectively.
-- **DB schema:** One file per domain in `src/lib/db/schema/`, re-exported from `index.ts`. Relations in `relations.ts`. Domain files include `clients.ts`, `yachts.ts`, `companies.ts`, `reservations.ts`, `interests.ts`, `berths.ts`, `documents.ts`, `invoices.ts`, etc.
-- **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 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.
-- **Inline editing pattern:** detail pages (clients, yachts, companies, interests, residential clients/interests) use `<InlineEditableField>` (`src/components/shared/inline-editable-field.tsx`) for click-to-edit text/select/textarea fields and `<InlineTagEditor>` (`src/components/shared/inline-tag-editor.tsx`) for tag chips. Each entity exposes a `PUT /api/v1/<entity>/[id]/tags` endpoint backed by a `set<Entity>Tags` service helper that wipes-and-rewrites the join table inside a single transaction. There are no separate "Edit" modal forms on detail pages — the entire overview tab is editable in place.
-- **Notes (polymorphic across entity types):** `notes.service.ts` dispatches across `clientNotes`, `interestNotes`, `yachtNotes`, `companyNotes` based on an `entityType` discriminator. `<NotesList entityType="…" />` works for all four. `companyNotes` lacks an `updatedAt` column — the service substitutes `createdAt` so callers get a uniform shape.
-- **Route handler exports:** Next.js App Router `route.ts` files only allow specific named exports (`GET|POST|…`). Service-tested handler functions live in sibling `handlers.ts` files (e.g. `src/app/api/v1/yachts/[id]/handlers.ts`) and are imported by the colocated `route.ts` for `withAuth(withPermission(...))` wrapping. Integration tests import from `handlers.ts` directly to bypass auth/permission middleware.
+### API shape
+
+- **Envelope:** `{ data: <T> }` for any returned content (read OR write). Mutations returning nothing emit `204 No Content`. Don't use `{ success: true }` (legacy; normalized away 2026-05-07). Public portal-auth endpoints keep `{ success: true }` so the frontend can chain.
+- **Lists:** `{ data: <T[]>, total?, hasMore? }` — see `/api/v1/clients`.
+- **Errors:** always via `errorResponse(error)` from `@/lib/errors` (request-id propagation + audit-tier mapping).
+- **Body parsing:** always `parseBody(req, schema)` from `@/lib/api/route-helpers`. Raw `req.json() + schema.parse()` produces a generic 500 instead of the field-level 400 the frontend's `toastError` hook expects.
+- **Route handlers:** `route.ts` files can only export `GET|POST|…`. Service-tested handlers live in sibling `handlers.ts` (e.g. `src/app/api/v1/yachts/[id]/handlers.ts`) and are imported by `route.ts` with `withAuth(withPermission(...))`. Integration tests import from `handlers.ts` directly to bypass middleware.
+
+### Data model
+
+- **Polymorphic ownership:** Yachts and invoice billing-entities use `<entity>_type` + `<entity>_id` pairs (`'client' | 'company'`). Resolve via `src/lib/services/yachts.service.ts` / `eoi-context.ts` — never read the columns ad hoc.
+- **Multi-berth interest model:** `interest_berths` is the source of truth — `interests.berth_id` does not exist (dropped in 0029). Three flags: `is_primary` (≤1 per interest, partial unique index — "the berth for this deal"), `is_specific_interest` (true → public map shows "Under Offer"), `is_in_eoi_bundle` (covered by EOI signature). Read/write only via `src/lib/services/interest-berths.service.ts` helpers.
+- **Notes (polymorphic):** `notes.service.ts` dispatches across `clientNotes`/`interestNotes`/`yachtNotes`/`companyNotes` via an `entityType` discriminator. `<NotesList entityType="…" />` works for all four. `companyNotes` lacks `updatedAt` — service substitutes `createdAt` for shape uniformity.
+- **Mooring number canonical format:** `^[A-Z]+\d+$` (e.g. `A1`, `B12`, `E18`) — no hyphen, no leading zeros. Stored, displayed, URL-encoded, EOI-rendered in this exact form. Regex gates the public `/api/public/berths/[mooringNumber]` route before any DB hit.
 - **Routes:** Multi-tenant via `[portSlug]` dynamic segment. Typed routes enabled.
-- **Pre-commit:** Husky + lint-staged runs ESLint fix + Prettier on staged `.ts`/`.tsx` files. The hook also blocks `.env*` files (including `.env.example`) from being committed; pass them via a separate workflow if needed.
 
-## Schema migrations during dev
+### Schema migrations during dev
 
-When you run a `db:push` or apply a migration via `psql` against a running dev server, **restart the dev server afterwards**. Drizzle/postgres.js keeps connection-level prepared statements that can hold stale column lists; a stale pool causes `column X does not exist` errors on pages that touch the migrated table even though the column is present in the DB. Symptom: pages return 500 with `errorMissingColumn`/`42703` after a successful migration. Fix: kill `next dev` and restart it.
+After `db:push` or applying a migration via `psql` against a running dev server, **restart `next dev`**. Drizzle/postgres.js prepared statements cache stale column lists; symptom is `42703 column X does not exist` 500s on migrated tables.
+
+### Documenso
+
+- **Webhooks:** plaintext secret in `X-Documenso-Secret` (no HMAC) — timing-safe equality via `verifyDocumensoSecret`. Event names arrive uppercase-enum (`DOCUMENT_SIGNED`, `DOCUMENT_COMPLETED` …); the receiver also normalizes lowercase-dotted for forward-compat. `handleDocumentCompleted` is **idempotent** (early-return when `status='completed' && signedFileId`) so 5xx retries don't double-write. Switch handles SIGNED|COMPLETED|REJECTED|DECLINED|OPENED|EXPIRED + v2 aliases RECIPIENT_VIEWED/SIGNED. Detail: `docs/documenso-integration-audit.md`.
+- **v1 vs v2 routing:** `getPortDocumensoConfig(portId)` resolves per-port `apiVersion`. `documenso-client.ts` exports version-aware wrappers (`getDocument`, `createDocument`, `sendDocument`, `sendReminder`, `downloadSignedPdf`, `voidDocument`, `placeFields`). v2 → `/api/v2/envelope/*` (multipart create, `distribute` returns per-recipient signingUrl, `redistribute` for reminders, `field/create-many` for bulk placement). v1 → `/api/v1/documents/*`. **Template flow stays v1** (`/api/v1/templates/{id}/generate-document` with name-keyed `formValues`) — v2 instances accept via backcompat. v2-only settings honoured: `documenso_signing_order` (PARALLEL/SEQUENTIAL) + `documenso_redirect_url`.
+- **Response normalization:** 2.x uses `documentId` / `recipientId`; v1.13 uses `id`. `normalizeDocument()` surfaces the legacy `id` form to downstream consumers.
+- **`DOCUMENSO_API_URL`:** bare host only — never include `/api/v1`. Client appends versioned paths based on `DOCUMENSO_API_VERSION`. Double-pathing returns 404 with no useful diagnostic.
+
+### EOI generation
+
+- Two pathways share `EoiContext` (`src/lib/services/eoi-context.ts`). Documenso pathway uses `documenso-payload.ts` → template-generate endpoint; in-app pathway fills `assets/eoi-template.pdf` via `src/lib/pdf/fill-eoi-form.ts`. Routed through `generateAndSign(...)` in `document-templates.ts` with a `pathway` parameter.
+- **Merge fields:** Catalog in `src/lib/templates/merge-fields.ts`; `createTemplateSchema` uses `VALID_MERGE_TOKENS` as an allow-list, rejecting unknown tokens at template creation.
+- **Berth range formatter:** Multi-berth EOIs render the in-bundle berth set as a compact range ("A1-A3, B5-B7") via `formatBerthRange()` (`src/lib/templates/berth-range.ts`). Output populates the existing `Berth Number` Documenso field (single-berth = primary mooring verbatim; multi-berth = range). CRM UI always shows berths as chips. `{{eoi.berthRange}}` token available for template body copy.
+- Detail: `docs/eoi-documenso-field-mapping.md`, `assets/README.md`.
+
+### UI patterns
+
+- **Sheet vs Drawer:** `<Sheet side="right">` (`src/components/ui/sheet.tsx`, Radix dialog) is the canonical side-panel for both desktop and mobile (`w-3/4 sm:max-w-sm`). Vaul `<Drawer>` (`src/components/shared/drawer.tsx`) is mobile-bottom-sheet only — currently just `MoreSheet`. Need a side panel? Use Sheet. Don't add Vaul without a mobile-bottom-sheet justification.
+- **Inline editing:** Detail pages use `<InlineEditableField>` for text/select/textarea and `<InlineTagEditor>` for tag chips. Each entity exposes `PUT /api/v1/<entity>/[id]/tags` backed by a `set<Entity>Tags` service helper (single-transaction wipe-and-rewrite). No separate "Edit" modals — overview tab is editable in place.
+- **Email + auth surfaces:** Branded HTML in `src/lib/email/templates/`; portal-auth uses `portal-auth.ts`. All templates: table-based, max-width 600, logo + blurred overhead background (`s3.portnimara.com`). CRM `/login`, `/reset-password`, `/set-password` and portal `/portal/login`, `/portal/activate`, `/portal/reset-password` all wrap content in `<BrandedAuthShell>` for visual continuity.
+
+### Document folders
+
+- Per-port nestable tree (`document_folders.parent_id` self-FK; null parent = root). Documents and files carry nullable `folder_id`. Sibling-name uniqueness via `uniq_document_folders_sibling_name` on `(port_id, COALESCE(parent_id,'__root__'), LOWER(name))`. Folder delete is **soft rescue** (`deleteFolderSoftRescue`) — re-parents children up, drops folder; never CASCADE. `moveFolder` walks ancestor chain to prevent cycles.
+- Three system roots (`Clients/`, `Companies/`, `Yachts/`) auto-created via `ensureSystemRoots`. Entity subfolders are lazy via `ensureEntityFolder` — race-safe via partial unique index `uniq_document_folders_entity` on `(port_id, entity_type, entity_id) WHERE entity_id IS NOT NULL`. System rows mutated only by entity rename/archive/hard-delete (auto-sync via service helpers); `assertNotSystemManaged` rejects direct API mutation.
+- **Auto-deposit on signing completion:** `handleDocumentCompleted` resolves owner via the Owner-wins chain (`document.clientId ?? .companyId ?? .yachtId ?? interest.clientId`), ensures the entity folder, and sets `files.folder_id` + entity FK. Falls back to root when unresolvable.
+- **Aggregated projection:** `listFilesAggregatedByEntity` / `listInflightWorkflowsAggregatedByEntity` walk symmetric reach (Client ↔ Company via `company_memberships` active rows, ↔ Yacht via `yachts.current_owner_type/id`), group by source (DIRECTLY ATTACHED / FROM COMPANY / FROM YACHT / FROM CLIENT), cap 20 per group. **Defense-in-depth `port_id` at every join.** **File-FK snapshot is source of truth** — historical files stay filed even if relationships change.
+- Permission gating: `documents.view` reads; `documents.manage_folders` for create/rename/move/delete (system folders immutable via API).
+- Deploy: migration `0051_documents_hub_split.sql` + `pnpm db:backfill:doc-folders` (idempotent via per-port advisory lock).
+
+### Berths
+
+- **Public API:** `/api/public/berths` (list) + `/api/public/berths/[mooringNumber]` (single) feed the marketing site. Output mirrors legacy NocoDB shape verbatim. Status precedence: `"Sold"` > `"Under Offer"` (status OR active `is_specific_interest=true` link with open outcome) > `"Available"`. Cache `s-maxage=300, stale-while-revalidate=60`.
+- **Public health:** `/api/public/health` dual-mode — anonymous gets `{status, timestamp}` (never 503); requests with timing-safe `X-Intake-Secret` matching `WEBSITE_INTAKE_SECRET` get full `{checks: {db, redis}}` + 503 on failure. The website uses the authenticated form on startup so it refuses to start when pointed at the wrong env.
+- **Recommender:** Pure SQL (no AI). `src/lib/services/berth-recommender.service.ts`. Tier ladder A/B/C/D from `interest_berths` aggregates. Heat scoring fires only for tier B; weights tuned via `system_settings` (`heat_weight_*`, `recommender_*`, `fallthrough_*`, `tier_ladder_hide_late_stage`). Multi-port isolation enforced at entry point AND in the SQL aggregates CTE.
+- **Rules engine:** `src/lib/services/berth-rules-engine.ts`. Seven triggers, all wired: `eoi_sent`, `eoi_signed`, `deposit_received`, `contract_signed`, `interest_archived`, `interest_completed`, `berth_unlinked`. Callers fire `evaluateRule(...)` via dynamic import (circular-dep avoidance). Defaults vary; admins tune via `berth_rules` setting. Pairs with `advanceStageIfBehind` to keep pipeline stage in sync.
+- **Per-berth PDFs:** Versioned via `berth_pdf_versions`; `berths.current_pdf_version_id` is current. Storage key is UUID per upload (no collisions on concurrent uploads); `pg_advisory_xact_lock` per berth_id serializes version-number allocation. 3-tier parse: AcroForm → OCR (Tesseract.js) → optional AI on low confidence. Magic-byte (`%PDF-`) check on BOTH in-server and presigned-PUT paths. Mooring mismatch → service-level `ConflictError` unless `confirmMooringMismatch: true`.
+- **Brochures:** Per-port, `is_default` enforced by partial unique index `(port_id) WHERE is_default=true AND archived_at IS NULL`. Same upload flow as berth PDFs.
+- **NocoDB re-import:** `pnpm tsx scripts/import-berths-from-nocodb.ts --apply --port-slug port-nimara`. Idempotent (skips rows where `updated_at > last_imported_at` unless `--force`); add `--update-snapshot` to rewrite the seed JSON. Helpers in `src/lib/services/berth-import.ts` are unit-tested.
+- Plan-of-record: `docs/berth-recommender-and-pdf-plan.md`.
+
+### Storage
+
+- All file I/O through `getStorageBackend()` (`src/lib/storage/`). Interface: `put`, `get`, `head`, `delete`, `listByPrefix`, `presignUpload`, `presignDownload`. Selected via `system_settings.storage_backend` (`'s3' | 'filesystem'`). Switching backends = settings change + `pnpm tsx scripts/migrate-storage.ts` (round-trips every blob in `files`, `berth_pdf_versions`, `brochure_versions`, `gdpr_exports`, verifies SHA-256).
+- MinIO calls wrapped in 30s `withTimeout` to prevent TCP-blackhole stalls. **Filesystem backend is single-node only** — refuses to start when `MULTI_NODE_DEPLOYMENT=true`.
+
+### Send-from accounts (sales send-outs)
+
+- Configurable via `system_settings`; defaults to `sales@portnimara.com` (human) + `noreply@portnimara.com` (automation). SMTP/IMAP passwords AES-256-GCM at rest; API returns only `*PassIsSet` markers.
+- Audit → `document_sends` (separate from `audit_logs` for volume + binary refs). Body markdown rendered via `renderEmailBody()` (escape-then-allowlist; XSS-tested). Rate limit 50 sends/user/hour. Files > `email_attach_threshold_mb` ship as 24h signed-URL link (filename HTML-escaped against injection). The threshold banner in the compose UI is informational and shows whenever the preview API returns the per-port threshold — it does NOT depend on IMAP. Separately, bounce monitoring (`imap-bounce-poller.ts`) needs IMAP creds and no-ops cleanly when they're unset.
+
+### Pre-commit
+
+Husky + lint-staged runs ESLint fix + Prettier on staged `.ts`/`.tsx`. **Blocks all `.env*` files** (including `.env.example`) — pass them via a separate workflow if needed.
 
 ## Environment
 
-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).
+Copy `.env.example` to `.env`. See `src/lib/env.ts` for the full Zod schema. `SKIP_ENV_VALIDATION=1` bypasses validation (Docker build).
 
-Optional dev/test-only env vars (not in `.env.example`):
+Dev/test-only env (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**.
-- `IMAP_HOST` / `IMAP_PORT` / `IMAP_USER` / `IMAP_PASS` — read by `tests/e2e/realapi/portal-imap-activation.spec.ts` to fetch the activation email from a real mailbox during the IMAP round-trip test. The spec skips when any are missing.
+- `EMAIL_REDIRECT_TO=<address>` — reroutes every outbound email to this address, prefixes subject `[redirected from <original>]`. Dev safety net; **must be unset in production**.
+- `IMAP_HOST` / `IMAP_PORT` / `IMAP_USER` / `IMAP_PASS` — used by `tests/e2e/realapi/portal-imap-activation.spec.ts`; the spec skips when any are missing.
 
 ## Testing
 
-Five Playwright projects, defined in `playwright.config.ts`:
+Six Playwright projects (`playwright.config.ts`):
 
-- `setup` — global setup (seeds users, port, berths, system settings).
-- `smoke` — fast click-through over every major flow. Run on every change (~10 min, 125 specs).
-- `exhaustive` — deeper UI coverage that takes longer.
-- `destructive` — archive/delete/cancel paths against throwaway entities.
-- `realapi` — opt-in suite that hits real external services (Documenso send-side + IMAP round-trip). Requires `DOCUMENSO_API_*`, `SMTP_*`, `IMAP_*` env. Cloudflared tunnel needs to be running so Documenso can call the local webhook receiver.
-- `visual` — pixel-diff baselines for stable list/landing pages. Snapshots committed under `tests/e2e/visual/snapshots.spec.ts-snapshots/`. Regenerate with `--update-snapshots` after intentional UI changes.
+- `setup` — global setup (seeds users, port, berths, system settings)
+- `smoke` — fast click-through, run on every change (~10 min, 125 specs)
+- `exhaustive` — deeper UI coverage
+- `destructive` — archive/delete/cancel paths against throwaway entities
+- `realapi` — opt-in real Documenso send-side + IMAP round-trip. Needs `DOCUMENSO_API_*`, `SMTP_*`, `IMAP_*` env + cloudflared tunnel running for the local webhook receiver
+- `visual` — pixel-diff baselines (`tests/e2e/visual/snapshots.spec.ts-snapshots/`); regenerate with `--update-snapshots`
 
-Vitest covers unit + integration with mocked external services (`tests/unit/`, `tests/integration/`).
+Vitest covers unit + integration with mocked externals (`tests/unit/`, `tests/integration/`).
 
 ## Docker
 
-- `Dockerfile` - Production multi-stage build (deps -> build -> runner)
-- `Dockerfile.dev` - Dev with bind-mounted source
-- `Dockerfile.worker` - BullMQ worker process
-- `docker-compose.yml` / `docker-compose.dev.yml` / `docker-compose.prod.yml`
+- `Dockerfile` — production multi-stage (deps → build → runner)
+- `Dockerfile.dev` — dev with bind-mounted source
+- `Dockerfile.worker` — BullMQ worker process
+- `docker-compose.yml` / `.dev.yml` / `.prod.yml`
 
 ## Architecture docs
 
-Numbered spec files in repo root (`01-CONSOLIDATED-SYSTEM-SPEC.md` through `15-DESIGN-TOKENS.md`) contain detailed architecture decisions, feature specs, DB schema docs, API catalog, and implementation sequence.
+Numbered specs (`01-CONSOLIDATED-SYSTEM-SPEC.md` … `15-DESIGN-TOKENS.md`) in repo root carry the detailed architecture decisions, schema docs, API catalog, and sequence.
 
-Domain-specific references:
+Active plans of record under `docs/`:
 
-- `docs/eoi-documenso-field-mapping.md` — canonical mapping from `EoiContext`
-  paths to the Documenso template's `formValues` keys, with the matching
-  AcroForm field names used by the in-app pathway.
-- `assets/README.md` — what the in-app EOI source PDF must contain and how
-  to override its path in dev/test.
+- `docs/MASTER-PLAN-2026-05-18.md` — current 7-phase post-audit plan
+- `docs/BACKLOG.md` — single entry point for everything outstanding
+- `docs/berth-recommender-and-pdf-plan.md` — berths + PDF + send-outs bundle
+- `docs/eoi-documenso-field-mapping.md` — canonical EoiContext ↔ Documenso/AcroForm mapping
+- `docs/documenso-integration-audit.md` — full Documenso v1/v2 quirks reference
+- `assets/README.md` — in-app EOI source PDF requirements

Dockerfile

@@ -1,16 +1,21 @@
 # Stage 1: Install dependencies
 FROM node:20-alpine AS deps
-RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 WORKDIR /app
 COPY package.json pnpm-lock.yaml ./
 RUN pnpm install --frozen-lockfile --prod=false
 
 # Stage 2: Build the application
 FROM node:20-alpine AS builder
-RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
+# NODE_ENV=production in the builder makes `next build` and any code
+# branching on isProd deterministic (build-auditor M9). Without this,
+# CSP and other prod-only paths would compile under whatever NODE_ENV
+# the host carried in.
+ENV NODE_ENV=production
 ENV NEXT_TELEMETRY_DISABLED=1
 ENV SKIP_ENV_VALIDATION=1
 RUN pnpm build
@@ -25,6 +30,14 @@ COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
 COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 COPY --from=builder --chown=nextjs:nodejs /app/public ./public
 COPY --from=builder --chown=nextjs:nodejs /app/dist/server.js ./server-custom.js
+# Pin socket.io + @socket.io/redis-adapter into the runner — the custom
+# server (server-custom.js) requires them at runtime, but the Next
+# tracer has no reason to include them in .next/standalone since no
+# Next route imports the socket server. (build-auditor C3)
+COPY --from=deps --chown=nextjs:nodejs /app/node_modules/socket.io ./node_modules/socket.io
+COPY --from=deps --chown=nextjs:nodejs /app/node_modules/@socket.io ./node_modules/@socket.io
 USER nextjs
 EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:${PORT:-3000}/api/health || exit 1
 CMD ["node", "server-custom.js"]

Dockerfile.dev

@@ -1,7 +1,12 @@
 FROM node:20-alpine
-RUN corepack enable && corepack prepare pnpm@latest --activate
-WORKDIR /app
-COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
+# Drop root for the dev runtime — node:alpine ships a `node` user (uid
+# 1000) for exactly this purpose. Audit caught that running as root in
+# dev is an unnecessary risk when the bind-mounted source lets a
+# compromised process write anywhere in the repo.
+USER node
+WORKDIR /home/node/app
+COPY --chown=node:node package.json pnpm-lock.yaml ./
 RUN pnpm install --frozen-lockfile
 EXPOSE 3000
 CMD ["pnpm", "dev"]

Dockerfile.worker

@@ -1,26 +1,40 @@
 # Stage 1: Install dependencies (dev deps needed for esbuild)
 FROM node:20-alpine AS deps
-RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 WORKDIR /app
 COPY package.json pnpm-lock.yaml ./
 RUN pnpm install --frozen-lockfile --prod=false
 
 # Stage 2: Build the worker bundle
 FROM node:20-alpine AS builder
-RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 ENV SKIP_ENV_VALIDATION=1
 RUN pnpm build:worker
 
-# Stage 3: Production runner (prod deps only)
+# Stage 3: Production runner (prod deps only).
+#
+# Critical ordering: create the worker user FIRST and chown the workdir
+# BEFORE pnpm install, so node_modules + lazy-cache directories
+# (tesseract.js, sharp) are owned by the worker user. Without this, the
+# previous layout had pnpm install run as root → node_modules root-owned
+# → tesseract.js / sharp wrote to node_modules/.cache and EACCES'd at
+# first PDF parse in prod (auditor-K §39).
 FROM node:20-alpine AS runner
-RUN corepack enable && corepack prepare pnpm@latest --activate
-WORKDIR /app
-COPY package.json pnpm-lock.yaml ./
-RUN pnpm install --frozen-lockfile --prod
+RUN corepack enable && corepack prepare pnpm@10.33.2 --activate
 RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 worker
-COPY --from=builder --chown=worker:nodejs /app/dist/worker.js ./worker.js
+WORKDIR /app
+RUN chown -R worker:nodejs /app
 USER worker
+COPY --chown=worker:nodejs package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile --prod
+COPY --from=builder --chown=worker:nodejs /app/dist/worker.js ./worker.js
+# Healthcheck — pings Redis from inside the worker container. Without
+# this, a worker whose Redis connection has silently dropped (BullMQ
+# rejects new jobs but the Node process is alive) is invisible to
+# compose / swarm and jobs queue indefinitely (auditor-K §40).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD node -e "const Redis=require('ioredis');const r=new Redis(process.env.REDIS_URL,{maxRetriesPerRequest:1,connectTimeout:3000,lazyConnect:true});r.connect().then(()=>r.ping()).then(()=>{r.disconnect();process.exit(0)}).catch(()=>process.exit(1))" || exit 1
 CMD ["node", "worker.js"]

assets/README.md

@@ -29,9 +29,30 @@ Documenso template's `formValues` keys — see
 | `Lease_10`     | Checkbox | always `false` (legacy default — Purchase, not Lease) |
 | `Purchase`     | Checkbox | always `true`                                         |
 
-Form fields stay interactive after generation (not flattened), so the
-recipient can still tweak values before signing if the in-app pathway is
-followed by a Documenso send.
+The fill path **flattens** the AcroForm after writing values, so the
+recipient can't edit pre-filled values (yacht dimensions, address, berth
+number) after the fact. Documenso pathway flattens server-side; the
+in-app pathway brings the artifact to parity.
+
+### Expected sha256
+
+The source PDF's sha256 is pinned to guard against silent template swaps
+(an unreviewed asset swap would change legal output without a code diff):
+
+```
+ba495fd88d99ebe4b7f61acbe397fb2f1cd116e1e1f1b217de93106915c7c44b
+```
+
+`scripts/check-eoi-template-sha.ts` verifies this at boot of the in-app
+pathway; the function exposes the expected hash via `EXPECTED_EOI_SHA256`
+so tests can re-check after a deliberate template revision.
+
+To intentionally update the template:
+
+1. Drop the new PDF as `eoi-template.pdf`.
+2. Run `shasum -a 256 assets/eoi-template.pdf`.
+3. Update the hash in this README **and** in
+   `src/lib/pdf/fill-eoi-form.ts` (search for `EXPECTED_EOI_SHA256`).
 
 ### Override path
 
@@ -46,3 +67,23 @@ exact bytes:
 1. In Documenso, open the EOI template.
 2. Download the source PDF.
 3. Drop it here as `eoi-template.pdf`.
+
+### Known asset issue: Email field clipped at top
+
+The current `eoi-template.pdf` has the `Email` AcroForm field box positioned
+slightly too low — long email addresses render with the top pixel row
+clipped. **Fix is asset-side, not code-side**: pdf-lib only fills field
+boxes, it can't move them. To resolve:
+
+1. Open `eoi-template.pdf` in any PDF form editor (Acrobat, PDFescape,
+   PDF Studio, or Documenso's own template editor).
+2. Select the `Email` field box; nudge its `y` origin down by ~3 pt (or
+   increase its height by ~3 pt) so the rendered text has visual margin
+   from the top edge.
+3. Save → re-upload to Documenso (so both pathways stay in sync) →
+   bump the sha256 in this README + `EXPECTED_EOI_SHA256` per the steps
+   above.
+
+Affects both the in-app pathway (renders via pdf-lib AcroForm fill) and
+the Documenso pathway (Documenso's own renderer respects the same field
+geometry).

docker-compose.prod.yml

@@ -14,12 +14,27 @@ services:
       timeout: 5s
       retries: 5
     restart: unless-stopped
+    # build-auditor HIGH: bound memory + log rotation so a stuck query or
+    # noisy log doesn't fill the host disk. Postgres respects shared
+    # buffers env via init.sql; the hard limit here is the container
+    # ceiling.
+    deploy:
+      resources:
+        limits:
+          memory: 2g
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "5"
     networks:
       - internal
 
   redis:
     image: redis:7-alpine
-    command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy allkeys-lru
+    # BullMQ requires `noeviction` — under memory pressure, allkeys-lru
+    # silently drops queue keys and jobs disappear. See post-audit fix F4.
+    command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy noeviction
     volumes:
       - redisdata:/data
     healthcheck:
@@ -28,6 +43,15 @@ services:
       timeout: 5s
       retries: 5
     restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 512m
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
     networks:
       - internal
 
@@ -42,11 +66,28 @@ services:
       redis:
         condition: service_healthy
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
+      # build-auditor H5: env.PORT is configurable (default 3000), so
+      # template the port into the healthcheck URL. Otherwise overriding
+      # PORT=8080 via .env makes the container healthy-check itself on
+      # the wrong port and enter a restart loop.
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:${PORT:-3000}/api/health"]
       interval: 15s
       timeout: 5s
       retries: 3
+    # Give the SIGTERM handler in src/server.ts time to drain in-flight
+    # HTTP requests, close Socket.io, and disconnect Redis before Docker
+    # SIGKILLs the process. The internal hard timeout is 25s.
+    stop_grace_period: 30s
     restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 1g
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "5"
     networks:
       - internal
 
@@ -58,7 +99,19 @@ services:
         condition: service_healthy
       redis:
         condition: service_healthy
+    # Match the app: BullMQ jobs need time to finish or be released back
+    # to the queue when worker.ts handles SIGTERM.
+    stop_grace_period: 30s
     restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 1g
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "5"
     networks:
       - internal
 

docker-compose.yml

@@ -18,7 +18,9 @@ services:
 
   redis:
     image: redis:7-alpine
-    command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy allkeys-lru
+    # BullMQ requires `noeviction` — under memory pressure, allkeys-lru
+    # silently drops queue keys and jobs disappear. See post-audit fix F4.
+    command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy noeviction
     volumes:
       - redisdata:/data
     healthcheck:
@@ -40,7 +42,9 @@ services:
       redis:
         condition: service_healthy
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
+      # Templatize port so `PORT=…` env overrides don't desync the
+      # healthcheck from the actual listener.
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:${PORT:-3000}/api/health"]
       interval: 15s
       timeout: 5s
       retries: 3

docs/AUDIT-CATALOG.md

@@ -0,0 +1,733 @@
+# Comprehensive Audit Catalog — 2026-05-15
+
+Every audit-worthy surface in Port Nimara CRM, organized by area. Each entry is a discrete check we _could_ run. Pick the subset you want to actually execute.
+
+**Legend:**
+
+- **Effort:** XS (~minutes) · S (~30 min) · M (~half day) · L (~1+ day)
+- **Severity if broken:** 🔴 critical · 🟠 high · 🟡 medium · 🟢 cosmetic
+- **Coverage today:** ✅ confirmed working · ⚠️ partially checked · ❓ unchecked · ❌ known broken (see prior audits)
+
+---
+
+## 0. Already-known issues (cross-reference)
+
+These were caught in the 2026-05-15 sweep (`docs/audit-2026-05-15.md`) but listed here so we don't re-discover them:
+
+| ID    | Issue                                                                      | Status                |
+| ----- | -------------------------------------------------------------------------- | --------------------- |
+| A1    | Dashboard activity feed surfaces raw `permission_denied` rows, no label    | ❌ unfixed            |
+| A2    | Activity feed renders legacy 9-stage enum values (`deposit_10pct` etc.)    | ❌ unfixed            |
+| A3    | react-grab CSP error spam in dev                                           | ❌ unfixed (dev only) |
+| A4    | New Client form silently rejects when contact row has empty value          | ❌ unfixed            |
+| A5    | Socket.IO WebSocket never connects in `pnpm dev`                           | ❌ unfixed            |
+| A6    | Some DialogContent missing `aria-describedby`                              | ❌ unfixed            |
+| A8    | Legacy `statusOverrideMode = "auto"` values still in DB                    | ❌ unfixed            |
+| A9    | Catch-up wizard defaults to "New Enquiry" instead of "EOI" for under_offer | ❌ unfixed            |
+| A16   | File upload at documents-hub root fails with null vs string validator      | ❌ unfixed            |
+| A17   | `/api/v1/admin/ports` is super-admin-only but used as bootstrap resolver   | ❌ unfixed            |
+| A18   | 404 vs 403 inconsistency on permission denials                             | ❌ unfixed            |
+| A19   | F27 same-stage PATCH returns 200 + body instead of 204                     | ❌ unfixed            |
+| A20   | OwnerPicker Client/Company toggle hidden until popover opens               | ❌ unfixed            |
+| A19_b | Portal `/portal/login` shows "unavailable" — scope undefined               | ❌ unfixed            |
+
+---
+
+## 1. Legacy stage enum bleed (the `deposit_10pct` class of bug)
+
+**Why this matters:** the pipeline was refactored 9 stages → 7 stages but historical data still carries the old enum values in audit logs, soft-deleted rows, and possibly some hard-coded UI lookups. Every place that renders a stage value should map legacy → modern.
+
+| ID    | Check                                                                                                                                                                                                         | Effort | Severity | Coverage |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | -------- |
+| L-001 | Grep entire `src/` for hard-coded references to legacy stage names: `details_sent`, `in_communication`, `eoi_sent`, `eoi_signed`, `deposit_10pct`, `contract_sent`, `contract_signed`, `completed` (as stage) | S      | 🟠       | ❓       |
+| L-002 | Audit log diff display: does old `pipelineStage` value get human-friendly mapping?                                                                                                                            | S      | 🟡       | ❌ (A2)  |
+| L-003 | Activity feed labels: same mapping needed                                                                                                                                                                     | S      | 🟡       | ❌ (A2)  |
+| L-004 | Email templates: any merge token surfacing raw stage values?                                                                                                                                                  | XS     | 🟡       | ❓       |
+| L-005 | Documenso payload (`buildDocumensoPayload`): any stage references?                                                                                                                                            | XS     | 🟠       | ❓       |
+| L-006 | Public berths API: is `status` filter accepting any legacy values?                                                                                                                                            | XS     | 🟡       | ❓       |
+| L-007 | Webhook payloads: do outbound `interest.updated` events use 7-stage or legacy?                                                                                                                                | S      | 🟠       | ❓       |
+| L-008 | Reports / analytics SQL: are funnel rollups using 7-stage enum exclusively?                                                                                                                                   | M      | 🟠       | ❓       |
+| L-009 | Search FTS indexes: do they include the mapped human stage or the raw enum?                                                                                                                                   | S      | 🟡       | ❓       |
+| L-010 | Notification copy: does "Stage moved to X" use the mapped label?                                                                                                                                              | XS     | 🟢       | ❓       |
+| L-011 | CSV import templates / column mappers: does anyone still accept legacy stage names?                                                                                                                           | XS     | 🟢       | ❓       |
+| L-012 | Seed data: confirm no legacy stages in current seed (was migrated in `seed-synthetic-data.ts`)                                                                                                                | XS     | 🟢       | ✅       |
+| L-013 | Migration safety: would a re-import via NocoDB re-introduce legacy values?                                                                                                                                    | S      | 🟠       | ❓       |
+| L-014 | Status override mode: legacy `"auto"` value (see A8) — same class of bug                                                                                                                                      | XS     | 🟢       | ❌ (A8)  |
+| L-015 | Outcome enum: confirm `won` / `lost_*` are the only modern values; no legacy `completed` outcome anywhere                                                                                                     | S      | 🟡       | ❓       |
+| L-016 | Lead category enum: any legacy values?                                                                                                                                                                        | XS     | 🟢       | ❓       |
+| L-017 | Lead source enum: ditto                                                                                                                                                                                       | XS     | 🟢       | ❓       |
+| L-018 | Tenure type enum: ditto                                                                                                                                                                                       | XS     | 🟢       | ❓       |
+| L-019 | Document doc-status sub-states: `sent`, `signed`, `completed`, `expired`, `rejected` — are they consistently applied?                                                                                         | S      | 🟡       | ❓       |
+| L-020 | Reservation/contract status enum: any legacy / deprecated values lingering?                                                                                                                                   | S      | 🟡       | ❓       |
+
+---
+
+## 2. Routes — every page reachable and correct
+
+| ID    | Check                                                                                                       | Effort | Severity | Coverage            |
+| ----- | ----------------------------------------------------------------------------------------------------------- | ------ | -------- | ------------------- |
+| R-001 | All `/[portSlug]/*` routes return 200 for super-admin (sweep)                                               | S      | 🟠       | ⚠️ admin only       |
+| R-002 | All `/[portSlug]/*` routes return 200 or proper 403/redirect for sales-agent                                | S      | 🟠       | ⚠️ partial          |
+| R-003 | All `/[portSlug]/*` routes for viewer                                                                       | S      | 🟡       | ❓                  |
+| R-004 | Cross-port URL access: paste `/port-amador/clients/<port-nimara-uuid>` → expects 404, not silent            | XS     | 🟠       | ✅ (F17)            |
+| R-005 | Archived entity detail page: 404 with "Restored?" affordance                                                | XS     | 🟡       | ❓                  |
+| R-006 | Soft-deleted folder URL: expects 404 / fallback to parent                                                   | XS     | 🟡       | ❓                  |
+| R-007 | Hard-deleted berth UUID URL (e.g. A1 in port-amador): expects 404                                           | XS     | 🟡       | ❓                  |
+| R-008 | URL-encoded mooring number (`A1` vs `A%201` vs `a1`): canonicalization                                      | XS     | 🟡       | ❓                  |
+| R-009 | Trailing slash redirects                                                                                    | XS     | 🟢       | ❓                  |
+| R-010 | Query-string preservation across nav (filters, sort, page)                                                  | S      | 🟡       | ❓                  |
+| R-011 | Browser back/forward state on detail pages (does Tab selection persist?)                                    | S      | 🟡       | ❓                  |
+| R-012 | Deep-link with `?folder=<id>` on documents (F25 verified for root, what about deep folder?)                 | XS     | 🟢       | ⚠️                  |
+| R-013 | Deep-link to specific interest tab (`?tab=documents`)                                                       | XS     | 🟢       | ❓                  |
+| R-014 | Deep-link with filter pre-applied (`/interests?stage=eoi`)                                                  | XS     | 🟡       | ❓                  |
+| R-015 | typedRoutes enforcement: any string-as-route escapes via `as never` casts that point to non-existent paths? | M      | 🟡       | ❓                  |
+| R-016 | Middleware / proxy.ts: public-path allow-list correctness (regex anchors, prefix matches)                   | S      | 🟠       | ❓                  |
+| R-017 | Auth redirect: visiting `/dashboard` while logged-out → `/login?next=...`                                   | XS     | 🟠       | ❓                  |
+| R-018 | Post-login redirect honours `next` param                                                                    | XS     | 🟠       | ❓                  |
+| R-019 | Portal routes when `client_portal_enabled=false`: gate page (verified A19_b)                                | XS     | 🟢       | ✅                  |
+| R-020 | Portal routes when `client_portal_enabled=true`: dashboard, docs, activate flows                            | S      | 🟠       | ❓                  |
+| R-021 | `/setup` bootstrap flow on fresh DB (no super admin yet)                                                    | M      | 🔴       | ❓ (F1 fixed proxy) |
+| R-022 | Reset-password token validity + expiry                                                                      | S      | 🟠       | ❓                  |
+| R-023 | Set-password (first-time after invite) flow                                                                 | S      | 🟠       | ❓                  |
+| R-024 | Portal activate via `#token` fragment                                                                       | S      | 🟠       | ❓                  |
+| R-025 | API routes that should be HEAD-cacheable (public/berths) return correct cache headers                       | S      | 🟢       | ❓                  |
+| R-026 | Public health: anonymous mode minimal payload                                                               | XS     | 🟡       | ❓                  |
+| R-027 | Public health: secret mode full payload                                                                     | XS     | 🟡       | ❓                  |
+| R-028 | OPTIONS preflight on API routes (CORS)                                                                      | XS     | 🟡       | ❓                  |
+| R-029 | API rate-limit headers on auth endpoints                                                                    | XS     | 🟡       | ❓                  |
+| R-030 | `/api/v1/me` returns expected user shape                                                                    | XS     | 🟢       | ✅                  |
+
+---
+
+## 3. UX consistency — every list, detail, form
+
+### 3a. Empty / loading / error states
+
+| ID    | Surface                                                                                                                   | Effort | Severity | Coverage |
+| ----- | ------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | -------- |
+| U-001 | Clients list: empty state copy + CTA                                                                                      | XS     | 🟢       | ❓       |
+| U-002 | Yachts list: empty state                                                                                                  | XS     | 🟢       | ❓       |
+| U-003 | Companies list: empty state                                                                                               | XS     | 🟢       | ❓       |
+| U-004 | Interests list: empty state                                                                                               | XS     | 🟢       | ❓       |
+| U-005 | Berths list: empty state                                                                                                  | XS     | 🟢       | ❓       |
+| U-006 | Reservations list: empty state                                                                                            | XS     | 🟢       | ❓       |
+| U-007 | Invoices list: empty state                                                                                                | XS     | 🟢       | ❓       |
+| U-008 | Inbox: empty state                                                                                                        | XS     | 🟢       | ❓       |
+| U-009 | Documents hub root: empty state                                                                                           | XS     | 🟢       | ❓       |
+| U-010 | Documents hub folder: empty state (verified earlier)                                                                      | XS     | 🟢       | ✅       |
+| U-011 | Audit log: empty state (filter to nothing)                                                                                | XS     | 🟢       | ❓       |
+| U-012 | Reconcile berths: empty state (verified)                                                                                  | XS     | 🟢       | ✅       |
+| U-013 | Recommender: empty result copy (verified F28)                                                                             | XS     | 🟢       | ✅       |
+| U-014 | All list pages: loading skeleton vs spinner — is the pattern consistent?                                                  | S      | 🟢       | ❓       |
+| U-015 | All detail pages: 404 fallback (DetailNotFound) — confirmed for 5 entities, check residential/reservation/invoice/expense | S      | 🟡       | ⚠️       |
+| U-016 | All forms: server-error toast surfaces requestId                                                                          | S      | 🟡       | ❓       |
+| U-017 | All forms: validation summary at top vs inline messages                                                                   | S      | 🟡       | ❓       |
+| U-018 | All forms: submit-while-pending state (button disabled + spinner)                                                         | S      | 🟢       | ❓       |
+| U-019 | Drag-drop file zone: hover state visible                                                                                  | XS     | 🟢       | ❓       |
+| U-020 | Drag-drop file zone: drop-target overlay on entity folder                                                                 | XS     | 🟢       | ❓       |
+
+### 3b. Form design
+
+| ID    | Check                                                                 | Effort | Severity | Coverage |
+| ----- | --------------------------------------------------------------------- | ------ | -------- | -------- |
+| U-021 | Required-field markers consistent ("\*" vs label suffix vs help text) | S      | 🟢       | ❓       |
+| U-022 | Field-help-text discoverability (tooltip vs always-visible)           | S      | 🟢       | ❓       |
+| U-023 | Field-level errors: every field has visible error after blur+submit   | M      | 🟡       | ❓       |
+| U-024 | Cancel behaviour: discards or saves draft?                            | S      | 🟡       | ❓       |
+| U-025 | Unsaved changes warning on dialog dismiss                             | S      | 🟡       | ❓       |
+| U-026 | Multi-step wizards: persist state across step nav                     | M      | 🟡       | ❓       |
+| U-027 | Phone E.164 conversion preview                                        | S      | 🟢       | ❓       |
+| U-028 | Currency input: locale-aware separators                               | S      | 🟡       | ❓       |
+| U-029 | Date picker: keyboard input + calendar both work                      | S      | 🟢       | ❓       |
+| U-030 | Date range constraint enforcement (start ≤ end)                       | XS     | 🟡       | ❓       |
+| U-031 | File-type accept attribute matches server magic-byte check            | XS     | 🟡       | ❓       |
+| U-032 | File-size limit copy matches server limit                             | XS     | 🟢       | ❓       |
+| U-033 | Combobox keyboard nav (↑↓, Enter, Esc, type-ahead)                    | S      | 🟢       | ❓       |
+| U-034 | Multi-select chip removal (X button + backspace)                      | S      | 🟢       | ❓       |
+| U-035 | Tag colour-picker: contrast check                                     | XS     | 🟢       | ❓       |
+| U-036 | "Save changes" copy consistency (vs "Update" vs "Save")               | S      | 🟢       | ❓       |
+| U-037 | Inline-edit save trigger (blur vs Enter vs explicit save)             | S      | 🟢       | ❓       |
+| U-038 | Inline-edit cancel (Esc reverts)                                      | XS     | 🟢       | ❓       |
+| U-039 | Inline-tag-editor: tab order across the chip strip                    | XS     | 🟢       | ❓       |
+
+### 3c. Tables / lists / filters
+
+| ID    | Check                                                   | Effort | Severity | Coverage |
+| ----- | ------------------------------------------------------- | ------ | -------- | -------- |
+| U-040 | Sort direction indicator on column header               | XS     | 🟢       | ❓       |
+| U-041 | Multi-column sort (shift-click)                         | S      | 🟢       | ❓       |
+| U-042 | Filter chips dismissable via X                          | XS     | 🟢       | ❓       |
+| U-043 | "Clear all filters" button presence                     | XS     | 🟢       | ❓       |
+| U-044 | Pagination: page size selector                          | XS     | 🟢       | ❓       |
+| U-045 | Pagination: jump-to-page                                | XS     | 🟢       | ❓       |
+| U-046 | Pagination: total count accuracy with filters           | XS     | 🟡       | ❓       |
+| U-047 | Row selection: select-all-page vs select-all-filtered   | S      | 🟡       | ❓       |
+| U-048 | Bulk action toolbar appearance + dismiss                | S      | 🟢       | ❓       |
+| U-049 | Sticky header on scroll                                 | XS     | 🟢       | ❓       |
+| U-050 | Column resize / reorder / show-hide persistence         | S      | 🟢       | ❓       |
+| U-051 | Virtual list performance with 1000+ rows                | M      | 🟡       | ❓       |
+| U-052 | CSV export of current view (respects filters + columns) | S      | 🟡       | ❓       |
+| U-053 | Sorted-by-relevance vs sorted-by-date default           | XS     | 🟢       | ❓       |
+
+### 3d. Badges, icons, colours
+
+| ID    | Check                                                                         | Effort | Severity | Coverage |
+| ----- | ----------------------------------------------------------------------------- | ------ | -------- | -------- |
+| U-054 | Stage badge palette: 7 stages each have a distinct, consistent colour         | XS     | 🟢       | ❓       |
+| U-055 | Outcome badge: won = green, lost\_\* = red shades, distinct enough            | XS     | 🟢       | ❓       |
+| U-056 | Berth status pill: available/under_offer/sold colour consistency              | XS     | 🟢       | ✅       |
+| U-057 | Document status pill: draft/sent/partial/completed/expired/cancelled/rejected | XS     | 🟢       | ❓       |
+| U-058 | "Manual" chip on berth list (F67 phase 2)                                     | XS     | 🟢       | ✅       |
+| U-059 | Icon usage: Lucide-only — no decorative unicode glyphs (memory: avoid emoji)  | S      | 🟡       | ⚠️       |
+| U-060 | Button hierarchy: primary/secondary/ghost/destructive used consistently       | S      | 🟢       | ❓       |
+| U-061 | Destructive actions colour-coded red                                          | XS     | 🟡       | ❓       |
+| U-062 | Loading spinner sizing consistent (size-3.5 vs size-4 vs animate-spin)        | S      | 🟢       | ❓       |
+| U-063 | Tooltip delay + position consistency                                          | S      | 🟢       | ❓       |
+| U-064 | Status pill withDot vs no dot: is the rule consistent?                        | XS     | 🟢       | ❓       |
+
+### 3e. Modal / sheet / drawer doctrine
+
+| ID    | Check                                                                          | Effort | Severity | Coverage |
+| ----- | ------------------------------------------------------------------------------ | ------ | -------- | -------- |
+| U-065 | Sheet used for forms + previews on desktop AND mobile (per CLAUDE.md doctrine) | S      | 🟡       | ❓       |
+| U-066 | Vaul Drawer only used for mobile-bottom-sheet (only `MoreSheet` qualifies)     | XS     | 🟢       | ❓       |
+| U-067 | AlertDialog used for destructive confirmations                                 | XS     | 🟢       | ❓       |
+| U-068 | Dialog used for short interactive forms (new yacht, catch-up, won-dialog)      | XS     | 🟢       | ❓       |
+| U-069 | Esc closes all overlays consistently                                           | XS     | 🟢       | ❓       |
+| U-070 | Click-outside closes / doesn't close: rule consistent                          | S      | 🟡       | ❓       |
+| U-071 | Focus trap inside overlays                                                     | S      | 🟠       | ❓       |
+| U-072 | Focus restoration to trigger element on close                                  | S      | 🟡       | ❓       |
+
+### 3f. Toasts / feedback
+
+| ID    | Check                                                                      | Effort | Severity | Coverage |
+| ----- | -------------------------------------------------------------------------- | ------ | -------- | -------- |
+| U-073 | Toast position consistent (top-right, sonner config)                       | XS     | 🟢       | ✅       |
+| U-074 | Success toast on every mutation (create, update, archive, delete, restore) | M      | 🟡       | ⚠️       |
+| U-075 | Error toast includes copyable requestId                                    | S      | 🟡       | ⚠️       |
+| U-076 | Toast timing (auto-dismiss vs persistent for errors)                       | XS     | 🟢       | ❓       |
+| U-077 | Multiple toasts stack vs replace                                           | XS     | 🟢       | ❓       |
+
+### 3g. Accessibility / keyboard
+
+| ID    | Check                                                      | Effort | Severity | Coverage |
+| ----- | ---------------------------------------------------------- | ------ | -------- | -------- |
+| U-078 | Tab order natural on each form                             | M      | 🟡       | ❓       |
+| U-079 | All icons inside buttons have `aria-label` or sibling text | S      | 🟡       | ❓       |
+| U-080 | All `<img>` have alt                                       | XS     | 🟡       | ❓       |
+| U-081 | Heading hierarchy (h1 → h2 → h3, no skips)                 | S      | 🟢       | ❓       |
+| U-082 | Color contrast WCAG AA (4.5:1 body, 3:1 large)             | M      | 🟡       | ❓       |
+| U-083 | Focus rings visible on all interactive elements            | S      | 🟡       | ❓       |
+| U-084 | Skip-to-content link                                       | XS     | 🟢       | ❓       |
+| U-085 | Reduced-motion media query honoured                        | S      | 🟢       | ❓       |
+| U-086 | `aria-describedby` set on DialogContent (A6)               | S      | 🟡       | ❌       |
+| U-087 | Live regions for async updates (toast, notification count) | S      | 🟢       | ❓       |
+| U-088 | Form errors announced to screen readers                    | S      | 🟡       | ❓       |
+| U-089 | Touch target min 44×44px on mobile                         | S      | 🟡       | ❓       |
+
+### 3h. Mobile-specific UX
+
+| ID    | Check                                                             | Effort | Severity | Coverage |
+| ----- | ----------------------------------------------------------------- | ------ | -------- | -------- |
+| U-090 | Bottom-tab nav reachable on every page                            | XS     | 🟢       | ✅       |
+| U-091 | Mobile topbar shows correct title via `useMobileChrome`           | S      | 🟢       | ⚠️       |
+| U-092 | More sheet contains every nav item not on bottom bar              | XS     | 🟡       | ❓       |
+| U-093 | Search overlay covers viewport on tap                             | XS     | 🟢       | ❓       |
+| U-094 | iOS safe-area-inset-top / bottom respected                        | S      | 🟡       | ❓       |
+| U-095 | Pull-to-refresh: present or absent? (consistency)                 | XS     | 🟢       | ❓       |
+| U-096 | Camera capture on file upload (image\* mime type triggers camera) | S      | 🟢       | ❓       |
+| U-097 | Soft keyboard occlusion on form input (visualViewport handling)   | S      | 🟡       | ❓       |
+| U-098 | Long-press menu absence (not native iOS overrides)                | XS     | 🟢       | ❓       |
+| U-099 | Sheet side="right" responsiveness                                 | XS     | 🟢       | ❓       |
+| U-100 | Mobile bottom tab active-state highlight                          | XS     | 🟢       | ❓       |
+
+---
+
+## 4. Sales workflows — every end-to-end path
+
+### 4a. Happy paths
+
+| ID    | Flow                                                                                                                                                                                                                       | Effort | Severity | Coverage |
+| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | -------- |
+| W-001 | Create client → create interest → link yacht → advance to EOI → send EOI → receive webhook → auto-advance to Reservation → record deposit → auto-advance to Deposit Paid → send contract → mark contract signed → mark won | L      | 🔴       | ⚠️       |
+| W-002 | Multi-berth interest: link 3 berths, mark one primary, send EOI bundle with range formatter                                                                                                                                | M      | 🟠       | ❓       |
+| W-003 | Company-owned yacht: company → membership → yacht owned by company → interest                                                                                                                                              | M      | 🟠       | ❓       |
+| W-004 | Residential client + residential interest end-to-end                                                                                                                                                                       | M      | 🟡       | ❓       |
+| W-005 | Public berth inquiry → admin/inquiries triage → create client via prefill                                                                                                                                                  | M      | 🟠       | ❓       |
+| W-006 | Catch-up wizard from berth list row-menu                                                                                                                                                                                   | S      | 🟠       | ⚠️       |
+| W-007 | Catch-up wizard from reconcile queue (verified)                                                                                                                                                                            | S      | 🟢       | ✅       |
+| W-008 | Mark won → reopen → outcome cleared toast (F26)                                                                                                                                                                            | XS     | 🟢       | ⚠️       |
+| W-009 | Mark lost (each lost reason)                                                                                                                                                                                               | S      | 🟢       | ❓       |
+| W-010 | Mark externally signed                                                                                                                                                                                                     | S      | 🟡       | ❓       |
+
+### 4b. Edge cases
+
+| ID    | Flow                                                                   | Effort | Severity | Coverage  |
+| ----- | ---------------------------------------------------------------------- | ------ | -------- | --------- |
+| W-011 | Try to leave Enquiry without yacht → F23 inline prereq picker fires    | XS     | 🟢       | ✅        |
+| W-012 | Try forbidden transition (e.g. Reservation → Enquiry) without override | XS     | 🟡       | ❓        |
+| W-013 | Override transition: requires reason ≥ 5 chars                         | XS     | 🟡       | ❓        |
+| W-014 | Override transition: insufficient permission → blocked tooltip         | XS     | 🟡       | ❓        |
+| W-015 | Rewind to enquiry with linked berths → unlink-or-keep prompt           | S      | 🟡       | ❓        |
+| W-016 | Same-stage write (F27): expects 204                                    | XS     | 🟢       | ❌ (A19)  |
+| W-017 | Concurrent stage edits (two browser tabs)                              | M      | 🟡       | ❓        |
+| W-018 | Stage transition emits audit log + realtime event                      | S      | 🟡       | ❓        |
+| W-019 | Auto-advance via berth-rule on `deposit_received`                      | S      | 🟠       | ❓        |
+| W-020 | Auto-advance via Documenso webhook (`DOCUMENT_SIGNED`)                 | S      | 🟠       | ❓        |
+| W-021 | Webhook arrives twice (idempotency)                                    | S      | 🟠       | ✅ (R2-G) |
+| W-022 | Webhook with v2 envelope shape                                         | S      | 🟠       | ❓        |
+| W-023 | Webhook lowercase-dotted event name → forward-compat                   | XS     | 🟢       | ❓        |
+| W-024 | Webhook with wrong secret → 401 + rate limit                           | S      | 🟠       | ❓        |
+| W-025 | Berth unlink mid-EOI → rule fires?                                     | S      | 🟡       | ❓        |
+| W-026 | Yacht reassignment mid-deal                                            | S      | 🟡       | ❓        |
+| W-027 | Client merge (duplicate dedup) — interest carry-over                   | M      | 🟠       | ❓        |
+| W-028 | Recommender on 0ft yacht (empty dims)                                  | XS     | 🟢       | ❓        |
+| W-029 | Recommender on 300ft yacht (no matching berth)                         | XS     | 🟢       | ✅ (F28)  |
+| W-030 | Recommender weight tuning re-ranks                                     | S      | 🟡       | ❓        |
+| W-031 | Recommender fallthrough policy (cooldown after lost)                   | M      | 🟡       | ❓        |
+| W-032 | Recommender tier ladder A/B/C/D classification                         | M      | 🟠       | ❓        |
+| W-033 | Heat scoring weights (recency, furthest stage, count, EOI count)       | M      | 🟡       | ❓        |
+| W-034 | Reservation cancel mid-flow                                            | S      | 🟡       | ❓        |
+| W-035 | EOI document expiry                                                    | S      | 🟡       | ❓        |
+| W-036 | Contract sent + bounced email                                          | S      | 🟡       | ❓        |
+| W-037 | Reminder snooze / dismiss                                              | S      | 🟢       | ❓        |
+| W-038 | Reminder digest delivery                                               | M      | 🟢       | ❓        |
+| W-039 | Default-owner auto-assign on new interest                              | XS     | 🟢       | ❓        |
+| W-040 | Reassignment notification email                                        | S      | 🟢       | ❓        |
+| W-041 | Cascading invites (secondary signers)                                  | M      | 🟠       | ❓        |
+| W-042 | Field-level signing verification                                       | M      | 🟡       | ❓        |
+| W-043 | Voice-note attach on activity                                          | S      | 🟢       | ❓        |
+| W-044 | Quick-template log entry                                               | S      | 🟢       | ❓        |
+| W-045 | Note add / edit / delete (polymorphic across entities)                 | S      | 🟢       | ❓        |
+| W-046 | Tag add via inline-tag-editor (verified F16 inline create flow)        | XS     | 🟢       | ⚠️        |
+| W-047 | Tag delete cascade (remove tag from all entities)                      | S      | 🟡       | ❓        |
+| W-048 | Bulk archive (clients)                                                 | S      | 🟡       | ❓        |
+| W-049 | Bulk archive (interests)                                               | S      | 🟡       | ❓        |
+| W-050 | Restore archived (any entity)                                          | S      | 🟡       | ❓        |
+| W-051 | Hard-delete request (GDPR Article 17)                                  | M      | 🟠       | ❓        |
+| W-052 | GDPR export download                                                   | M      | 🟠       | ✅ (R2-O) |
+
+---
+
+## 5. Admin workflows
+
+| ID     | Flow                                                                         | Effort | Severity | Coverage        |
+| ------ | ---------------------------------------------------------------------------- | ------ | -------- | --------------- |
+| AD-001 | Role create + permission edit                                                | S      | 🟠       | ❓              |
+| AD-002 | Per-port role override                                                       | S      | 🟠       | ❓              |
+| AD-003 | User invite send + email delivered                                           | M      | 🟠       | ❓              |
+| AD-004 | Invite accept + activate (token in #fragment)                                | S      | 🟠       | ❓              |
+| AD-005 | Invitation revoke / resend                                                   | XS     | 🟡       | ❓              |
+| AD-006 | User edit (display name, residential access toggle)                          | XS     | 🟢       | ❓              |
+| AD-007 | User deactivate                                                              | S      | 🟠       | ❓              |
+| AD-008 | System settings key update                                                   | XS     | 🟡       | ❓              |
+| AD-009 | Branding logo upload + render in email templates                             | S      | 🟢       | ❓              |
+| AD-010 | Branding primary colour propagation                                          | S      | 🟢       | ❓              |
+| AD-011 | Document template create with merge tokens                                   | S      | 🟠       | ❓              |
+| AD-012 | Template merge field validation (unknown token rejected)                     | XS     | 🟢       | ❓              |
+| AD-013 | Email template subject preview / override                                    | S      | 🟢       | ❓              |
+| AD-014 | Tag create + colour pick + delete                                            | XS     | 🟢       | ✅              |
+| AD-015 | Vocabulary list edit (interest temperatures, etc)                            | S      | 🟢       | ❓              |
+| AD-016 | Custom field add (text, number, select, date)                                | S      | 🟡       | ❓              |
+| AD-017 | Custom field retrofit on existing rows                                       | S      | 🟡       | ❓              |
+| AD-018 | Webhook create + secret rotate                                               | S      | 🟠       | ❓              |
+| AD-019 | Webhook delivery log + retry                                                 | S      | 🟡       | ❓              |
+| AD-020 | Brochure upload + magic-byte check                                           | S      | 🟡       | ❓              |
+| AD-021 | Brochure default toggle (partial unique index)                               | S      | 🟡       | ❓              |
+| AD-022 | Brochure archive                                                             | XS     | 🟢       | ❓              |
+| AD-023 | Per-berth PDF upload + parse                                                 | M      | 🟠       | ❓              |
+| AD-024 | Per-berth PDF version rollback                                               | S      | 🟡       | ❓              |
+| AD-025 | OCR parse confidence threshold + AI parse fallback                           | M      | 🟡       | ❓              |
+| AD-026 | NocoDB import: --apply, --force, --update-snapshot                           | M      | 🟠       | ❓              |
+| AD-027 | NocoDB import idempotency (re-run after no changes)                          | S      | 🟡       | ❓              |
+| AD-028 | NocoDB import vs human-edited row skip (updated_at > last_imported_at)       | S      | 🟡       | ❓              |
+| AD-029 | Bulk berth add wizard end-to-end                                             | S      | 🟠       | ⚠️ (loads only) |
+| AD-030 | CSV import (clients) — column mapper                                         | M      | 🟠       | ❓              |
+| AD-031 | CSV import (yachts)                                                          | M      | 🟡       | ❓              |
+| AD-032 | CSV import error report (rejected rows)                                      | S      | 🟡       | ❓              |
+| AD-033 | Duplicates queue review + merge                                              | M      | 🟠       | ❓              |
+| AD-034 | Duplicates queue: false-positive dismiss                                     | XS     | 🟢       | ❓              |
+| AD-035 | Audit log search/FTS — text query                                            | S      | 🟡       | ❓              |
+| AD-036 | Audit log filter by action / entity / user / date range                      | S      | 🟡       | ❓              |
+| AD-037 | Audit log diff display (old vs new)                                          | S      | 🟡       | ❓              |
+| AD-038 | Audit log mask of sensitive fields (passwords, tokens)                       | S      | 🟠       | ❓              |
+| AD-039 | Backup status read                                                           | XS     | 🟢       | ❓              |
+| AD-040 | Storage backend swap dry-run (filesystem ↔ s3)                               | M      | 🟠       | ❓              |
+| AD-041 | Multi-node deployment refuses filesystem backend                             | XS     | 🟠       | ❓              |
+| AD-042 | Documenso health check Test button (v1 + v2)                                 | S      | 🟠       | ❓              |
+| AD-043 | Documenso API version toggle per-port                                        | S      | 🟠       | ❓              |
+| AD-044 | Documenso signing-order setting (parallel/sequential)                        | S      | 🟡       | ❓              |
+| AD-045 | Documenso redirect URL setting                                               | XS     | 🟢       | ❓              |
+| AD-046 | AI provider credentials test                                                 | S      | 🟡       | ❓              |
+| AD-047 | Receipt OCR config + retry on bad parse                                      | M      | 🟡       | ❓              |
+| AD-048 | Send-from account config + encrypted secret roundtrip                        | M      | 🟠       | ❓              |
+| AD-049 | Bounce monitoring (IMAP probe + dev-imap-probe script)                       | M      | 🟡       | ❓              |
+| AD-050 | Reminders default behaviour + digest window edit                             | S      | 🟢       | ❓              |
+| AD-051 | Residential pipeline stages edit + reassignment on stage removal             | M      | 🟡       | ❓              |
+| AD-052 | Qualification criteria reorder (DnD)                                         | S      | 🟢       | ❓              |
+| AD-053 | Berth rules engine config (7 triggers, 3 modes)                              | M      | 🟠       | ❓              |
+| AD-054 | Recommender weights tune                                                     | S      | 🟡       | ❓              |
+| AD-055 | Onboarding checklist progression                                             | S      | 🟢       | ❓              |
+| AD-056 | Reports: pipeline funnel, occupancy timeline, revenue breakdown, lead source | S      | 🟡       | ❓              |
+| AD-057 | Forms: form template create + public submission roundtrip                    | M      | 🟠       | ❓              |
+| AD-058 | Inquiry inbox triage → convert to client                                     | M      | 🟠       | ❓              |
+| AD-059 | Website analytics (Umami) config                                             | S      | 🟢       | ❓              |
+| AD-060 | Queue monitoring dashboard (BullMQ stats)                                    | XS     | 🟢       | ❓              |
+
+---
+
+## 6. Multi-tenancy (port isolation)
+
+| ID    | Check                                                                | Effort | Severity | Coverage  |
+| ----- | -------------------------------------------------------------------- | ------ | -------- | --------- |
+| MT-01 | GET /api/v1/clients/<other-port-uuid> with X-Port-Id=this-port → 404 | XS     | 🟠       | ✅ (R2-N) |
+| MT-02 | PATCH /api/v1/interests/<other-port-uuid> → 404                      | XS     | 🟠       | ❓        |
+| MT-03 | Berth recommender cross-port leak guard (entry + SQL CTE)            | S      | 🔴       | ✅        |
+| MT-04 | Document folder defense-in-depth port_id filter on every join        | S      | 🟠       | ❓        |
+| MT-05 | Audit log scope per port                                             | XS     | 🟠       | ❓        |
+| MT-06 | Webhook subscriptions scoped to port                                 | XS     | 🟠       | ❓        |
+| MT-07 | System settings per-port                                             | XS     | 🟡       | ❓        |
+| MT-08 | Tags scoped to port                                                  | XS     | 🟡       | ❓        |
+| MT-09 | Custom fields scoped to port                                         | XS     | 🟡       | ❓        |
+| MT-10 | Vocabularies scoped to port                                          | XS     | 🟡       | ❓        |
+| MT-11 | Seed runs idempotent across ports                                    | S      | 🟡       | ❓        |
+
+---
+
+## 7. Security
+
+| ID   | Check                                                      | Effort | Severity | Coverage  |
+| ---- | ---------------------------------------------------------- | ------ | -------- | --------- |
+| S-01 | XSS via client.fullName render (verified ✓)                | XS     | 🟠       | ✅        |
+| S-02 | XSS via tag.name                                           | XS     | 🟠       | ❓        |
+| S-03 | XSS via note.content (markdown)                            | S      | 🟠       | ❓        |
+| S-04 | XSS via email body markdown (verified)                     | S      | 🟠       | ✅ (R2-I) |
+| S-05 | SQL injection via search query                             | S      | 🔴       | ❓        |
+| S-06 | Path traversal in folder name                              | S      | 🟠       | ❓        |
+| S-07 | Path traversal in file name                                | XS     | 🟠       | ❓        |
+| S-08 | SSRF via attachment URL or webhook target                  | S      | 🟠       | ❓        |
+| S-09 | Open redirect on `next` param                              | XS     | 🟠       | ❓        |
+| S-10 | CSRF on state-changing requests (proxy.ts checks)          | S      | 🟠       | ❓        |
+| S-11 | Cookie flags: HttpOnly, Secure, SameSite                   | XS     | 🟠       | ❓        |
+| S-12 | CSP headers (production)                                   | S      | 🟡       | ❓        |
+| S-13 | CORS allow-list narrow                                     | XS     | 🟡       | ❓        |
+| S-14 | Rate limit on login (verified F7)                          | XS     | 🟠       | ✅        |
+| S-15 | Rate limit on forget-password                              | XS     | 🟠       | ✅        |
+| S-16 | Rate limit on file upload                                  | S      | 🟡       | ❓        |
+| S-17 | Session fixation (regen sid on login)                      | S      | 🟠       | ❓        |
+| S-18 | Token expiry / refresh (better-auth)                       | S      | 🟠       | ❓        |
+| S-19 | Audit log tamper-resistance (append-only)                  | S      | 🟡       | ❓        |
+| S-20 | Documenso webhook secret rotation (verified)               | S      | 🟠       | ✅        |
+| S-21 | SMTP credential at-rest encryption (AES-256-GCM)           | S      | 🟠       | ❓        |
+| S-22 | IMAP credential at-rest encryption                         | S      | 🟠       | ❓        |
+| S-23 | Storage credential at-rest encryption                      | S      | 🟠       | ❓        |
+| S-24 | Privilege escalation: viewer → agent → admin paths         | M      | 🔴       | ❓        |
+| S-25 | Direct ID enumeration (UUID guess immune)                  | XS     | 🟢       | ✅ (R2)   |
+| S-26 | Audit log read-back of own permission denials              | S      | 🟢       | ❓        |
+| S-27 | Magic-byte verification on every uploaded file (verified)  | S      | 🟠       | ✅        |
+| S-28 | Filename HTML-escape in download links                     | XS     | 🟡       | ❓        |
+| S-29 | Bounce-monitor email subject parsing (injection)           | S      | 🟡       | ❓        |
+| S-30 | Email body redirect mode never escapes in prod (env guard) | XS     | 🟠       | ❓        |
+
+---
+
+## 8. Realtime / sockets
+
+| ID    | Check                                                          | Effort | Severity | Coverage |
+| ----- | -------------------------------------------------------------- | ------ | -------- | -------- |
+| RT-01 | Socket.IO server actually running in dev (A5)                  | S      | 🟡       | ❌       |
+| RT-02 | Realtime invalidation: interest:updated fires from another tab | S      | 🟡       | ❓       |
+| RT-03 | document:completed event invalidates files                     | S      | 🟡       | ❓       |
+| RT-04 | folder:created event invalidates document-folders              | S      | 🟡       | ❓       |
+| RT-05 | berth:statusChanged event invalidates berths                   | S      | 🟡       | ❓       |
+| RT-06 | Subscription teardown on unmount (no leaks)                    | S      | 🟡       | ❓       |
+| RT-07 | Cross-tab broadcast (BroadcastChannel?)                        | M      | 🟢       | ❓       |
+| RT-08 | Reconnect after server restart                                 | S      | 🟡       | ❓       |
+| RT-09 | Room-level scoping (port:X room)                               | XS     | 🟠       | ❓       |
+
+---
+
+## 9. Performance
+
+| ID   | Check                                                                    | Effort | Severity | Coverage                    |
+| ---- | ------------------------------------------------------------------------ | ------ | -------- | --------------------------- |
+| P-01 | Web vitals report endpoint accepts beacons (verified — A2 is dev cancel) | XS     | 🟢       | ✅                          |
+| P-02 | LCP under 2.5s on dashboard                                              | S      | 🟡       | ❓                          |
+| P-03 | CLS under 0.1                                                            | S      | 🟢       | ❓                          |
+| P-04 | TTI under 3s                                                             | S      | 🟡       | ❓                          |
+| P-05 | N+1 detection on interests list (tags / berths / yacht joins)            | M      | 🟡       | ❓                          |
+| P-06 | DataTable virtual rendering for 1000+ rows                               | M      | 🟡       | ⚠️ (audit-log uses virtual) |
+| P-07 | Image lazy-load on documents list                                        | XS     | 🟢       | ❓                          |
+| P-08 | Bundle size growth budget                                                | S      | 🟢       | ❓                          |
+| P-09 | Slow-query log review                                                    | M      | 🟡       | ❓                          |
+| P-10 | DB connection pool exhaustion behaviour (verified F8 fix landed)         | S      | 🟠       | ✅                          |
+| P-11 | Memory leak after long session (open same form 50 times)                 | M      | 🟡       | ❓                          |
+| P-12 | Worker queue throughput under load                                       | M      | 🟡       | ❓                          |
+| P-13 | Search FTS query plan (uses GIN index?)                                  | S      | 🟡       | ❓                          |
+| P-14 | API response size budget (paginated list ≤ 256 KB)                       | XS     | 🟢       | ❓                          |
+
+---
+
+## 10. Documents / files
+
+| ID   | Check                                                                         | Effort | Severity | Coverage |
+| ---- | ----------------------------------------------------------------------------- | ------ | -------- | -------- |
+| D-01 | Upload via drag-drop on hub root (A16 — broken)                               | XS     | 🟠       | ❌       |
+| D-02 | Upload via drag-drop on entity folder                                         | S      | 🟠       | ❓       |
+| D-03 | Upload via file picker on dialog                                              | XS     | 🟠       | ❌ (A16) |
+| D-04 | PDF preview inline                                                            | S      | 🟢       | ❓       |
+| D-05 | Image preview inline (jpg, png, webp, gif)                                    | S      | 🟢       | ❓       |
+| D-06 | Word / Excel: download fallback                                               | XS     | 🟢       | ❓       |
+| D-07 | Signed PDF download from completed workflow                                   | S      | 🟠       | ❓       |
+| D-08 | Folder soft-rescue on delete (children re-parent)                             | S      | 🟠       | ❓       |
+| D-09 | Folder rename → entity name sync                                              | S      | 🟡       | ❓       |
+| D-10 | Folder move cycle prevention                                                  | S      | 🟡       | ❓       |
+| D-11 | Folder permission: system folders immutable through API                       | S      | 🟠       | ❓       |
+| D-12 | Aggregated entity view (Clients/Companies/Yachts subfolders)                  | S      | 🟡       | ❓       |
+| D-13 | Hub root view: 3 cards (in-progress, files, completed)                        | S      | 🟢       | ❓       |
+| D-14 | EntityFolderView: signing-in-progress + files                                 | S      | 🟢       | ❓       |
+| D-15 | "View signing details" link on signed file row                                | XS     | 🟢       | ❓       |
+| D-16 | Auto-deposit on signing completion (resolves owner via Owner-wins chain)      | M      | 🟠       | ❓       |
+| D-17 | listFilesAggregatedByEntity walks Client↔Company↔Yacht reach symmetrically    | M      | 🟠       | ❓       |
+| D-18 | Folder URL state with `?folder=<uuid>` (F25 deep folder)                      | XS     | 🟢       | ⚠️       |
+| D-19 | Concurrent ensureEntityFolder race-safety (partial unique index)              | M      | 🟡       | ❓       |
+| D-20 | Magic-byte verification on presign + post-upload paths                        | S      | 🟠       | ✅       |
+| D-21 | Filename HTML-escape in fallback download link                                | XS     | 🟡       | ❓       |
+| D-22 | File size > email_attach_threshold_mb → signed-URL link instead of attachment | M      | 🟡       | ❓       |
+
+---
+
+## 11. Audit log
+
+| ID    | Check                                                                             | Effort | Severity | Coverage |
+| ----- | --------------------------------------------------------------------------------- | ------ | -------- | -------- |
+| AU-01 | Every mutation creates an audit row (sample 10 endpoints)                         | M      | 🟠       | ⚠️       |
+| AU-02 | Sensitive-field mask works (test: password rotation row)                          | S      | 🟠       | ❓       |
+| AU-03 | FTS query returns expected results                                                | S      | 🟡       | ❓       |
+| AU-04 | Filter by action: only stage_change shows                                         | XS     | 🟢       | ❓       |
+| AU-05 | Filter by entity type: only berth/interest/etc shows                              | XS     | 🟢       | ❓       |
+| AU-06 | Filter by user                                                                    | XS     | 🟢       | ❓       |
+| AU-07 | Filter by date range                                                              | XS     | 🟢       | ❓       |
+| AU-08 | Diff display correctly highlights old vs new                                      | S      | 🟡       | ❓       |
+| AU-09 | "Reconcile" event tag visible in metadata                                         | XS     | 🟢       | ✅       |
+| AU-10 | Cascade events grouped or distinct? (e.g. archive client + auto-archive interest) | S      | 🟡       | ❓       |
+| AU-11 | Permission-denied entries render readable (A1)                                    | XS     | 🟡       | ❌       |
+| AU-12 | Audit log export to CSV                                                           | S      | 🟢       | ❓       |
+| AU-13 | Outcome-change action tag distinct from generic 'update' (R2-B finding)           | S      | 🟡       | ❓       |
+| AU-14 | Tier-mapping (audit_logs.audit_tier_map) — high-tier vs noise tier                | S      | 🟡       | ❓       |
+
+---
+
+## 12. Email / SMTP / IMAP
+
+| ID    | Check                                                            | Effort | Severity | Coverage |
+| ----- | ---------------------------------------------------------------- | ------ | -------- | -------- |
+| EM-01 | Per-port SMTP override picks up                                  | S      | 🟠       | ❓       |
+| EM-02 | Default sales send-from (`sales@portnimara.com`)                 | XS     | 🟢       | ❓       |
+| EM-03 | Default noreply send-from (`noreply@portnimara.com`)             | XS     | 🟢       | ❓       |
+| EM-04 | EMAIL_REDIRECT_TO in dev: subject prefix `[redirected from ...]` | XS     | 🟡       | ❓       |
+| EM-05 | Branded template render (logo, blurred bg, max-w-600)            | S      | 🟢       | ❓       |
+| EM-06 | Reply-to override                                                | XS     | 🟡       | ❓       |
+| EM-07 | CC/BCC handling                                                  | S      | 🟡       | ❓       |
+| EM-08 | Send rate limit 50/user/hour                                     | XS     | 🟡       | ❓       |
+| EM-09 | Send size > threshold falls back to signed link                  | M      | 🟡       | ❓       |
+| EM-10 | IMAP bounce probe (`dev-imap-probe.ts`)                          | M      | 🟢       | ❓       |
+| EM-11 | Bounce subject parse + interest linking                          | M      | 🟡       | ❓       |
+| EM-12 | Document_sends audit row per send                                | S      | 🟡       | ❓       |
+| EM-13 | Portal activation email arrives & token works                    | M      | 🟠       | ❓       |
+| EM-14 | Reset-password email                                             | S      | 🟠       | ❓       |
+| EM-15 | Invite email                                                     | M      | 🟠       | ❓       |
+| EM-16 | Reminder digest email                                            | M      | 🟢       | ❓       |
+| EM-17 | EOI generated PDF attached or inline?                            | S      | 🟡       | ❓       |
+| EM-18 | Outbound email markdown body XSS (verified)                      | S      | 🟠       | ✅       |
+| EM-19 | Subject override CSP/XSS                                         | S      | 🟠       | ✅       |
+
+---
+
+## 13. Integrations
+
+| ID    | Check                                                                 | Effort | Severity | Coverage |
+| ----- | --------------------------------------------------------------------- | ------ | -------- | -------- |
+| IN-01 | Documenso send EOI via v1 template-generate                           | M      | 🟠       | ❓       |
+| IN-02 | Documenso v2 envelope/create multipart                                | M      | 🟠       | ❓       |
+| IN-03 | Documenso distribute (v2)                                             | S      | 🟠       | ❓       |
+| IN-04 | Documenso redistribute / send reminder                                | S      | 🟡       | ❓       |
+| IN-05 | Documenso downloadSignedPdf                                           | S      | 🟠       | ❓       |
+| IN-06 | Documenso voidDocument                                                | S      | 🟡       | ❓       |
+| IN-07 | Documenso placeFields (v2 field/create-many)                          | M      | 🟡       | ❓       |
+| IN-08 | Documenso normalizeDocument id ↔ documentId                           | XS     | 🟡       | ❓       |
+| IN-09 | NocoDB import idempotency                                             | S      | 🟡       | ❓       |
+| IN-10 | S3 / MinIO upload + download                                          | S      | 🟠       | ❓       |
+| IN-11 | S3 presigned URL expiry                                               | XS     | 🟡       | ❓       |
+| IN-12 | Filesystem backend: MULTI_NODE_DEPLOYMENT guard                       | XS     | 🟠       | ❓       |
+| IN-13 | BullMQ job retry on failure                                           | S      | 🟡       | ❓       |
+| IN-14 | BullMQ Redis `noeviction` policy (verified)                           | XS     | 🟠       | ✅       |
+| IN-15 | Worker process boot + queue subscribe                                 | S      | 🟠       | ❓       |
+| IN-16 | Public berths API: anon cache headers                                 | XS     | 🟢       | ❓       |
+| IN-17 | Public berths API: status filter (`Under Offer`, `Sold`, `Available`) | S      | 🟡       | ❓       |
+| IN-18 | Public berths single endpoint via mooringNumber (canonical format)    | S      | 🟡       | ❓       |
+| IN-19 | Public health anonymous mode (verified A26)                           | XS     | 🟡       | ✅       |
+| IN-20 | Public health secret mode (verified A26)                              | XS     | 🟡       | ✅       |
+| IN-21 | OpenAI / AI parser credentials test                                   | S      | 🟡       | ❓       |
+| IN-22 | Tesseract OCR positional heuristics on per-berth PDF                  | M      | 🟡       | ❓       |
+| IN-23 | Receipt OCR: full receipt parse end-to-end                            | M      | 🟡       | ❓       |
+| IN-24 | Pdfme PDF generation (any per-port template)                          | M      | 🟡       | ❓       |
+| IN-25 | PDF-lib AcroForm fill (in-app EOI pathway)                            | M      | 🟠       | ❓       |
+| IN-26 | EOI merge token expansion (`{{eoi.berthRange}}` etc)                  | S      | 🟠       | ❓       |
+| IN-27 | Berth-range formatter (single + multi-berth)                          | S      | 🟡       | ❓       |
+| IN-28 | Portal magic-link consume                                             | S      | 🟠       | ❓       |
+| IN-29 | Umami analytics widget render                                         | XS     | 🟢       | ❓       |
+
+---
+
+## 14. Schema / migration
+
+| ID    | Check                                                                           | Effort | Severity | Coverage |
+| ----- | ------------------------------------------------------------------------------- | ------ | -------- | -------- |
+| SC-01 | All migrations idempotent (re-run safe)                                         | M      | 🟠       | ❓       |
+| SC-02 | All FKs have ON DELETE behaviour spec'd (CASCADE, SET NULL, RESTRICT)           | S      | 🟠       | ❓       |
+| SC-03 | All soft-delete columns indexed (`archivedAt IS NULL`)                          | S      | 🟡       | ❓       |
+| SC-04 | All search columns have GIN/FTS indexes                                         | S      | 🟡       | ❓       |
+| SC-05 | Composite unique constraints (sibling folder name, default brochure)            | S      | 🟡       | ❓       |
+| SC-06 | Partial unique constraints (entity-folder, isPrimary)                           | S      | 🟡       | ❓       |
+| SC-07 | CHECK constraints (chk_system_folder_shape)                                     | XS     | 🟢       | ❓       |
+| SC-08 | Generated column accuracy (FTS search_text)                                     | S      | 🟡       | ❓       |
+| SC-09 | Column nullability matches Drizzle schema                                       | M      | 🟡       | ❓       |
+| SC-10 | Schema migration restart-after-push (CLAUDE.md gotcha)                          | XS     | 🟠       | ❓       |
+| SC-11 | Backfill scripts idempotent (`backfill-document-folders.ts`)                    | S      | 🟡       | ❓       |
+| SC-12 | Legacy enum migration drift (every place that compared against an old value)    | M      | 🟠       | ❓       |
+| SC-13 | Currency code enum                                                              | XS     | 🟡       | ❓       |
+| SC-14 | Address-component enum                                                          | XS     | 🟢       | ❓       |
+| SC-15 | Polymorphic owner: every read-site uses the service helper, not raw column read | M      | 🟠       | ❓       |
+
+---
+
+## 15. i18n / l10n
+
+| ID   | Check                                          | Effort | Severity | Coverage |
+| ---- | ---------------------------------------------- | ------ | -------- | -------- |
+| L-01 | Currency formatting per locale                 | S      | 🟢       | ❓       |
+| L-02 | Date formatting per timezone                   | S      | 🟢       | ❓       |
+| L-03 | Number formatting (1,000.5 vs 1.000,5)         | S      | 🟢       | ❓       |
+| L-04 | Plural forms                                   | S      | 🟢       | ❓       |
+| L-05 | RTL support (test with Arabic UA)              | S      | 🟢       | ❓       |
+| L-06 | Translation completeness (Phase C status)      | M      | 🟢       | ❓       |
+| L-07 | next-intl messages.json coverage               | S      | 🟢       | ❓       |
+| L-08 | Server-rendered locale match (Accept-Language) | S      | 🟢       | ❓       |
+
+---
+
+## 16. Browser / device
+
+| ID    | Check                                               | Effort | Severity | Coverage |
+| ----- | --------------------------------------------------- | ------ | -------- | -------- |
+| BR-01 | Safari (macOS) primary flows                        | M      | 🟡       | ❓       |
+| BR-02 | Safari (iOS) primary flows                          | M      | 🟡       | ❓       |
+| BR-03 | Firefox (latest)                                    | M      | 🟢       | ❓       |
+| BR-04 | Edge (latest)                                       | M      | 🟢       | ❓       |
+| BR-05 | Chrome (latest) — primary                           | S      | 🟢       | ✅       |
+| BR-06 | iPad (Safari) — tier "click" via computer-use rules | M      | 🟢       | ❓       |
+| BR-07 | Print stylesheet (interest detail, invoice)         | S      | 🟢       | ❓       |
+
+---
+
+## 17. Specific behavioral correctness checks
+
+| ID   | Check                                                                                                                         | Effort | Severity | Coverage    |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | ----------- |
+| B-01 | Berth A1 hard-deleted earlier; confirm no 404 anywhere (interests' linked-berth, public feed, recommender)                    | M      | 🟠       | ❓          |
+| B-02 | Sara Laurent interest in stage=contract WITHOUT yachtId → render correctness                                                  | XS     | 🟡       | ❓          |
+| B-03 | Outcome-set interests filtered from active queries via `activeInterestsWhere`                                                 | S      | 🟠       | ❓          |
+| B-04 | EOI bundle range formatter: `A1-A3, B5` for non-contiguous berths                                                             | S      | 🟡       | ❓          |
+| B-05 | EOI single-berth case formats to just mooring (`A1`)                                                                          | XS     | 🟢       | ❓          |
+| B-06 | Activity timeline 7-day window inclusive of today                                                                             | XS     | 🟢       | ✅ (F2 fix) |
+| B-07 | Heat-scoring tier B only fires for lost/cancelled-only history                                                                | M      | 🟡       | ❓          |
+| B-08 | Permission-denied audit row sequencing (does denied API call still log?)                                                      | S      | 🟡       | ❓          |
+| B-09 | Same-stage no-op DOES NOT emit audit/socket event (F27)                                                                       | S      | 🟢       | ⚠️          |
+| B-10 | Documenso webhook with empty body / malformed payload                                                                         | S      | 🟠       | ❓          |
+| B-11 | Berth status_override_mode transitions through automated → manual → null                                                      | M      | 🟡       | ❓          |
+| B-12 | Reconcile clear stamps reason correctly with interest id (verified)                                                           | XS     | 🟢       | ✅          |
+| B-13 | Catch-up wizard "contract" stage auto-sets `outcome=won`                                                                      | S      | 🟡       | ❓          |
+| B-14 | Catch-up wizard surfaces in API audit log as `reconcile_manual` type                                                          | XS     | 🟢       | ✅          |
+| B-15 | Mobile shell when initialFormFactor is wrong (Playwright UA = desktop, viewport = mobile) — shell ends up correct after mount | XS     | 🟢       | ✅          |
+| B-16 | Resizing across breakpoint mid-form-edit: state preservation?                                                                 | S      | 🟡       | ❓          |
+| B-17 | Berths bulk-add wizard: step transitions persist input                                                                        | M      | 🟡       | ❓          |
+| B-18 | NotesList polymorphic across all 4 entity types (clients, interests, yachts, companies)                                       | S      | 🟡       | ❓          |
+| B-19 | InlineEditableField on every detail page works                                                                                | M      | 🟡       | ❓          |
+| B-20 | InlineTagEditor: focus management (F45 verified)                                                                              | S      | 🟢       | ⚠️          |
+| B-21 | OwnerPicker: client+company tabs render correctly (F44 verified)                                                              | XS     | 🟢       | ✅          |
+| B-22 | Mark externally signed sets `documentId=null`, `signedAt=now`                                                                 | S      | 🟡       | ❓          |
+
+---
+
+## 18. Data-clean-up jobs
+
+| ID    | Check                                                                                                                                                                                                      | Effort | Severity | Coverage |
+| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | -------- |
+| DC-01 | Orphan-blob cleanup on document delete                                                                                                                                                                     | S      | 🟠       | ❓       |
+| DC-02 | Soft-deleted entities older than X days hard-purged                                                                                                                                                        | M      | 🟡       | ❓       |
+| DC-03 | Test entities in DB (per prior audit notes): `Smoke Test Client (renamed)`, `Aurora Marine Holdings Ltd`, `Bad Email Test`, `Phone Test`, `François 🏄 المعتمد`, `CSRF Test`, etc — `db:reseed:synthetic`? | S      | 🟢       | ❓       |
+| DC-04 | Berth A1 hard-deletion in port-amador: was that recovered?                                                                                                                                                 | S      | 🟡       | ❓       |
+| DC-05 | Legacy `statusOverrideMode = "auto"` normalize migration                                                                                                                                                   | XS     | 🟢       | ❌ (A8)  |
+
+---
+
+## 19. CI / dev experience
+
+| ID    | Check                                                            | Effort | Severity | Coverage |
+| ----- | ---------------------------------------------------------------- | ------ | -------- | -------- |
+| CI-01 | Husky lint-staged blocks bad commits                             | XS     | 🟢       | ✅       |
+| CI-02 | `pnpm exec tsc --noEmit` clean                                   | XS     | 🟢       | ✅       |
+| CI-03 | `pnpm lint` zero errors                                          | XS     | 🟢       | ✅       |
+| CI-04 | `pnpm exec vitest run` 1373/1373 pass                            | S      | 🟢       | ✅       |
+| CI-05 | `pnpm exec playwright test --project=smoke` ~10min               | M      | 🟢       | ❓       |
+| CI-06 | `pnpm exec playwright test --project=destructive`                | M      | 🟢       | ❓       |
+| CI-07 | `pnpm exec playwright test --project=realapi` (Documenso + IMAP) | M      | 🟢       | ❓       |
+| CI-08 | `pnpm exec playwright test --project=visual` baselines current   | S      | 🟢       | ❓       |
+| CI-09 | Gitea CI lint + build-and-push workflows                         | S      | 🟢       | ❓       |
+| CI-10 | Docker prod build succeeds                                       | M      | 🟠       | ❓       |
+| CI-11 | docker-compose dev startup with all services                     | S      | 🟢       | ❓       |
+| CI-12 | Pre-commit hook also blocks `.env*` files                        | XS     | 🟢       | ❓       |
+| CI-13 | `SKIP_ENV_VALIDATION=1` actually bypasses in Docker build        | XS     | 🟢       | ❓       |
+
+---
+
+## Recommendation: priority short-list
+
+If we want maximum coverage with limited time, I'd pick:
+
+### Tier 0 — fix what's already known (from A1-A20)
+
+- A4 (client form silent-fail)
+- A16 (file upload null vs string)
+- A17 (/admin/ports bootstrap)
+- A19 (F27 204 implementation)
+- A9 (catch-up wizard stage default)
+- A1/A2 (activity feed labels)
+
+### Tier 1 — discover new
+
+- **L-001** through **L-020** — legacy stage enum hunt (the user's specific concern)
+- **W-001** — full end-to-end happy-path workflow (one full deal)
+- **U-001** through **U-013** — every empty state surface
+- **MT-01-11** — multi-tenancy cross-port checks (full sweep)
+- **AU-01-14** — audit log surface (search, filters, mask, FTS)
+- **U-021-039** — form design sweep across major forms
+
+### Tier 2 — fill in coverage
+
+- **R-001-030** — route correctness
+- **AD-\* (admin pages)** — at least one mutation per admin section to confirm wiring
+- **D-01-22** — documents/files end-to-end
+
+### Tier 3 — depth checks
+
+- **S-\* (security)** — penetration sweep
+- **P-\* (performance)** — load + LCP + N+1
+- **W-011-052** — every edge-case workflow
+
+---
+
+**Total surfaces catalogued:** 320+ discrete checks across 19 areas.
+
+Pick what you want and I'll run it.

docs/AUDIT-FINDINGS-2026-05-15.md

@@ -0,0 +1,335 @@
+# Comprehensive Audit Findings — 2026-05-15
+
+Discovery pass across all 19 areas of `docs/AUDIT-CATALOG.md`. Code-side via 9 parallel sub-agents + browser sweep via Playwright MCP. Per-agent raw output cached under `docs/audit-findings-tmp/`.
+
+## Scoreboard
+
+| Severity    | Count  |
+| ----------- | ------ |
+| 🔴 CRITICAL | 3      |
+| 🟠 HIGH     | 15     |
+| 🟡 MEDIUM   | 48     |
+| 🟢 LOW      | 8      |
+| **Total**   | **74** |
+
+The 3 critical and the most actionable HIGH issues should head the next fix wave.
+
+---
+
+## 🔴 CRITICAL
+
+### C-01 (B-01) — INNER JOIN on hard-deleted berth silently drops interest→berth links
+
+- **Files:** `src/lib/services/interest-berths.service.ts:55` (`getPrimaryBerth`), `:87` (`getPrimaryBerthsForInterests`), `:140` (`listBerthsForInterest`)
+- **What:** Three helpers use `INNER JOIN berths ON berths.id = interestBerths.berthId`. Hard-deleting a berth makes the join silently drop the row.
+- **Impact:** Interest detail shows `berthId: null` / `berthMooringNumber: null`. Kanban card shows no berth chip. EOI generation produces empty mooring field. `archiveInterest` calls `getPrimaryBerth` before evaluating the berth rule — null result causes the rule to be **skipped entirely**.
+- **Fix:** Switch all three to `LEFT JOIN berths`. Callers already handle null. Add service-layer guard preventing hard-delete of berths with `interest_berths` rows (require unlink or soft-archive first).
+
+### C-02 (R-021) — `/setup` missing from `PUBLIC_PATHS` — bootstrap unreachable on fresh DB
+
+- **File:** `src/proxy.ts:51-73`
+- **What:** `PUBLIC_PATHS` includes `/api/v1/bootstrap/` but NOT `/setup`. Unauthenticated user → `/setup` → middleware redirects to `/login?redirect=/setup`. Login useEffect fetches bootstrap status, calls `router.replace('/setup')` → middleware again → infinite redirect loop.
+- **Impact:** Fresh deployment (no super admin) is functionally deadlocked. The first operator cannot reach setup without already having a session — impossible on a fresh DB.
+- **Fix:** Add `'/setup'` to `PUBLIC_PATHS`. `POST /api/v1/bootstrap/super-admin` already self-protects with `hasAnySuperAdmin()`.
+- **Browser-verified:** Navigating to `/setup` unauthenticated redirects to `/login` (no `?redirect=` even). The bootstrap-status check at `src/app/(auth)/login/page.tsx:41` confirms: `if (payload.data?.needsBootstrap) router.replace('/setup');` — feeds the loop on fresh DB.
+
+### C-03 (NEW, browser-discovered) — Generic `PATCH /api/v1/interests/[id]` bypasses ALL stage-transition guards
+
+- **Files:** `src/app/api/v1/interests/[id]/route.ts:20-32` (calls `updateInterest`); `src/lib/services/interests.service.ts:701` (`updateInterest`); `src/lib/validators/interests.ts:68,90` (`pipelineStage` flows through `updateInterestSchema` to the service)
+- **What:** The `/stage` endpoint (`src/app/api/v1/interests/[id]/stage/route.ts`) calls `changeInterestStage` which enforces `STAGE_NOOP` early-return, `canTransitionStage()` table guard, override-requires-permission, and override-requires-≥5-char-reason. The generic PATCH endpoint calls `updateInterest` which writes the full payload (incl. `pipelineStage`) directly to the DB with **none** of those guards.
+- **Browser proof:**
+  - PATCH `/api/v1/interests/<deposit-paid-id>` with `{ pipelineStage: 'enquiry' }` → **200 OK**, interest demoted to enquiry. (Same call via `/stage` correctly returned 400 with "Cannot move from Deposit Paid directly to New Enquiry. Use the override option ...".)
+  - PATCH `/api/v1/interests/<eoi-id>` with `{ pipelineStage: 'eoi' }` (same-stage) → **200 with full 1249-byte body** instead of 204. F27 fix only works through `/stage`.
+  - Backwards write via generic PATCH leaves `eoiDocStatus: 'sent'` while `pipelineStage = 'enquiry'` — corrupted state.
+  - Audit row written as generic `action: 'update'` with diff, not `action: 'stage_change'` with proper metadata. Webhook event `interest:updated` not `interest:stageChanged`.
+- **Impact:** Any caller (rep tool, integration, mistake in frontend) hitting the generic PATCH can drive an interest to any stage with no override permission, no reason, no audit-as-stage-change. Same-stage spam fires no-op writes that bump `updated_at` and emit redundant socket+webhook events. The corrupted-state surface (stage rolled back but doc-status still says signed) breaks downstream rules-engine evaluations that branch on stage.
+- **Fix:** In `updateInterestSchema`, omit `pipelineStage` (force callers to use `/stage`); OR in `updateInterest`, when `pipelineStage` is in the payload, delegate to `changeInterestStage` with the full guard chain. Either prevents the bypass surface from existing.
+
+---
+
+## 🟠 HIGH
+
+### H-01 (SC-02) — Multiple FKs `ON DELETE NO ACTION` while Drizzle declares them nullable
+
+- **Files:** `src/lib/db/schema/interests.ts:29,32` (portId/clientId); `src/lib/db/schema/documents.ts:72,85,86,176` (clientId/fileId/signedFileId/signerId); `src/lib/db/schema/reservations.ts:18,24,25,27,28,33` (all 6 berthReservations FKs); `src/lib/db/schema/operations.ts:25` (reminders.clientId); `src/lib/db/schema/financial.ts:120` (invoices.pdfFileId)
+- **What:** `.references(...)` without `{ onDelete }` emits `ON DELETE NO ACTION`. Hard-deleting a parent (client, berth, yacht, file) blocks at FK level.
+- **Fix:** Add `{ onDelete: 'set null' }` for nullable FKs that should tolerate parent deletion; explicit `{ onDelete: 'restrict' }` for those that intentionally block (`interests.clientId` design intent is archive-first).
+
+### H-02 (R-017/018) — CRM post-login redirect ignores `?redirect=` param
+
+- **File:** `src/app/(auth)/login/page.tsx:79`
+- **What:** Middleware redirects unauthenticated → `/login?redirect=<path>`. Login page never reads `useSearchParams()`; always `router.push('/dashboard')`.
+- **Impact:** Email/bookmark/shared deep links into specific clients/interests silently dump to dashboard.
+- **Fix:** Read `searchParams.get('redirect')`, validate same-origin (`startsWith('/')`, not `'//'`), use as push target.
+
+### H-03 (R-023) — CRM invite token in query string leaks to access logs
+
+- **File:** `src/lib/services/crm-invite.service.ts:71,233`
+- **What:** `${env.APP_URL}/set-password?token=${raw}` — raw 32-byte token in query param. Portal flow was migrated to `#token=` fragment in 2026-05-14 specifically to keep tokens out of logs/Referer; CRM invite path missed the migration.
+- **Impact:** Every nginx/Caddy access log line for `GET /set-password?token=<raw>` persists token to disk. Forwarded to SIEM/S3/monitoring → token visible to anyone with log access. Token grants account creation.
+- **Fix:** Change `createCrmInvite` + `resendCrmInvite` to emit `${env.APP_URL}/set-password#token=${encodeURIComponent(raw)}`. Update `set-password/page.tsx` to use the fragment-reading pattern from `PasswordSetForm` (`readTokenFromUrl()`) with `?token=` back-compat for outstanding tokens.
+
+### H-04 (R-029) — `sign-in-by-identifier` 429 missing `Retry-After`
+
+- **File:** `src/app/api/auth/sign-in-by-identifier/route.ts:47-51`
+- **What:** Builds 429 response with `headers: rateLimitHeaders(rl)` which only emits `X-RateLimit-Limit/Remaining/Reset`. `enforcePublicRateLimit` adds `Retry-After`; this route uses `checkRateLimit` directly and skips it.
+- **Impact:** RFC 6585 §4 violation. Automated clients can't back off correctly.
+- **Fix:** Add `'Retry-After': Math.max(1, Math.ceil((rl.resetAt - Date.now()) / 1000)).toString()`.
+
+### H-05 (AU-01a) — `toggleAccount` writes no audit row
+
+- **File:** `src/lib/services/email-accounts.service.ts:86-116`
+- **What:** Sets `isActive` on email account with no `createAuditLog` call. `connectAccount` (line 70) and `disconnectAccount` (line 139) do, but enable/disable in between is silent.
+- **Impact:** Silently disabling an email account suppresses bounce-detection or reroutes replies — compliance gap on a security-relevant config change.
+- **Fix:** Add `void createAuditLog({ action: 'update', entityType: 'email_account', entityId: accountId, newValue: { isActive: data.isActive }, ... })` inside `toggleAccount`.
+
+### H-06 (AU-02) — Encrypted credential ciphertext stored in audit log without masking
+
+- **Files:** `src/lib/services/settings.service.ts:66-76` + `src/lib/services/sales-email-config.service.ts:281-299`
+- **What:** `updateSalesEmailConfig` calls `upsertSetting('sales_smtp_pass_encrypted', <ciphertext>, portId, meta)`. `upsertSetting` records `newValue: { value: '<ciphertext>' }`. `maskSensitiveFields` checks JSON keys against `SENSITIVE_KEY_FRAGMENTS`; the wrapping key `"value"` isn't in the list. Ciphertext lands verbatim in `audit_logs.new_value`.
+- **Impact:** Audit log readable by all admins with `admin.view_audit_log`. DB read access exfils ciphertext; if `EMAIL_CREDENTIAL_KEY` is ever compromised, the historical audit log becomes a credential store.
+- **Fix:** In `upsertSetting`, detect when key ends with `_encrypted` (or accept `redactValue?: boolean`) and record `newValue: { value: '[redacted]' }`.
+
+### H-07 (AU-10) — Cascade-archived interests produce no individual audit rows
+
+- **File:** `src/lib/services/clients.service.ts:578-618`
+- **What:** `archiveClient` batch-archives open interests, writes ONE `entityType: 'client'` row with `newValue: { cascadedInterestIds: [...] }`. No per-interest rows. `search_text` doesn't include `new_value`, so searching for an interest ID returns nothing.
+- **Impact:** Auditor querying for a specific archived interest sees no archive event; must know to look at parent client row.
+- **Fix:** Loop over `archivedInterestIds` and emit per-interest `createAuditLog({ action: 'archive', entityType: 'interest', entityId, metadata: { cascadeSource: 'client_archive', clientId } })` (fire-and-forget).
+
+### H-08 (EM-XX) — Sales transporter missing SMTP timeouts
+
+- **File:** `src/lib/services/sales-email-config.service.ts:331-337`
+- **What:** `createSalesTransporter` builds nodemailer transport with no timeout options. Compare `createTransporter` in `src/lib/email/index.ts:26-37` which uses `SMTP_TIMEOUTS = { connectionTimeout: 10_000, greetingTimeout: 10_000, socketTimeout: 30_000 }`.
+- **Impact:** Hung SMTP relay can stall send-out indefinitely. Email queue concurrency=5, maxAttempts=5. One stuck TCP connection → 2-min default × 5 retries = 10min/job × 5 slots = whole pool blocked for 10min by a single flaky send.
+- **Fix:** Apply `SMTP_TIMEOUTS` constant to `nodemailer.createTransport` in `createSalesTransporter`.
+
+### H-09 (B-16) — AppShell remounts children on breakpoint crossing, destroying form state
+
+- **File:** `src/components/layout/app-shell.tsx:58-70`
+- **What:** When `isMobile` flips on resize, the shell switches between `<MobileLayout>{children}</MobileLayout>` and the desktop `<div>...{children}...</div>`. React unmounts and remounts `children`, destroying any in-progress `useState` form drafts including `InlineEditableField`.
+- **Impact:** User editing a client name on desktop who resizes past mobile breakpoint loses unsaved draft text. Multi-step modal forms (reconcile wizard) open during resize get unmounted.
+- **Fix:** Wrap shared content with stable `key`, or use CSS-only responsive layout so children subtree never remounts. Alternatively `key={isMobile ? 'mobile' : 'desktop'}` only on shell wrappers with `children` stable via Portal.
+
+### H-10 (U-059) — Unicode glyphs as status icons in portal documents page
+
+- **File:** `src/app/(portal)/portal/documents/page.tsx:85-89`
+- **What:** Signer status rendered as raw Unicode (`'✓'` signed, `'✗'` declined, `'○'` pending) inside colour-coded `<span>` with no `aria-label`.
+- **Impact:** Screen readers read literal Unicode names. Project memory: decorative unicode glyphs explicitly flagged. `inline-stage-picker.tsx:443` comment confirms the pattern ("was ⚑ unicode glyph — replaced with a Lucide").
+- **Fix:** Replace with `<CheckCircle2>` / `<XCircle>` / `<Circle>` Lucide icons + `aria-label`.
+
+### H-11 (U-066) — Vaul Drawer used for mobile search overlay (violates Sheet doctrine)
+
+- **File:** `src/components/search/mobile-search-overlay.tsx:6`
+- **What:** `import { Drawer as VaulDrawer } from 'vaul'`. Search overlay is full-screen, not a bottom sheet. CLAUDE.md: Vaul reserved for mobile-bottom-sheet only (currently `MoreSheet` only).
+- **Fix:** Convert to `<Sheet side="bottom">` or `<Dialog>` fullscreen. Custom visualViewport handling (lines 50-89) becomes redundant with Radix dialog backing.
+
+### H-12 (U-076) — Native `alert()` for bulk-action failure feedback in 3 lists
+
+- **Files:** `src/components/interests/interest-list.tsx:146`, `src/components/companies/company-list.tsx:73`, `src/components/yachts/yacht-list.tsx:66`
+- **What:** Partial-failure feedback via `alert(...)`. `client-list.tsx:145` uses `toast.warning(...)` correctly.
+- **Impact:** Native alert blocks main thread, can't be styled, fires in tests without suppression.
+- **Fix:** Replace with `toast.warning(...)` matching `client-list.tsx`.
+
+### H-13 (U-079) — Icon-only buttons missing `aria-label` (5 sites)
+
+- **Files:** `src/components/notifications/notification-bell.tsx:65`, `src/components/files/file-grid.tsx:121`, `src/components/admin/forms/form-template-list.tsx:102`, `src/components/email/email-accounts-list.tsx:159`, `src/components/companies/company-members-tab.tsx:228`
+- **Pattern reference:** `src/components/shared/folder-actions-menu.tsx:96` correctly uses `<span className="sr-only">More folder actions</span>`.
+- **Fix:** Add `aria-label` to each, following the folder-actions-menu sr-only pattern.
+
+### H-14 (NEW, browser-discovered) — `DELETE /api/v1/interests/[id]/outcome` with empty body crashes 500
+
+- **File:** `src/app/api/v1/interests/[id]/outcome/route.ts:27-30`; `src/lib/api/route-helpers.ts` (parseBody)
+- **What:** The DELETE handler calls `parseBody(req, clearOutcomeSchema)`. `clearOutcomeSchema` says `reopenStage` is optional. But DELETE with no body causes parseBody to throw an unhandled error → 500 internal-server-error JSON. Sending `{ reopenStage: 'qualified' }` returns 200.
+- **Browser proof:** Two consecutive `DELETE /api/v1/interests/<wonId>/outcome` calls (no body) returned 500 with `requestId: bc807db5-...` / `d21b5b3e-...`. Same call with body `{}` would presumably also work (not tested) — the issue is empty-vs-omitted body.
+- **Impact:** F26 reopen flow — when the user clicks "Reopen" without overriding the auto-detected previous stage, the request crashes. Frontend may always send a body, but the API contract claims optional and the wire-level test fails.
+- **Fix:** In `parseBody`, treat empty request body as `{}` for DELETE/POST routes whose schemas have all-optional fields; OR in the route handler, parse the body conditionally on `req.headers.get('content-length') !== '0'`.
+
+### H-15 (NEW, browser-discovered) — Sales-agent visiting an admin page silently bounces to dashboard (no 403 / feedback)
+
+- **Files:** Middleware in `src/proxy.ts` and/or per-route admin layout
+- **What:** Sales-agent navigating to `http://localhost:3000/port-amador/admin/audit` lands at `http://localhost:3000/port-amador/dashboard`. URL silently changes; no toast, no 403 page, no "Access denied" feedback. The API itself correctly returns 403 ("Insufficient permissions" or "No access to this port") — the UI just hides the failure.
+- **Impact:** A rep clicking a deep link to an admin page (in an email, bookmark, or shared link) is silently redirected without explanation. They can't tell whether the link was wrong, whether their permission lapsed, or whether the page just doesn't exist. (The earlier A18 verification said "/admin/audit correctly 403s" at the API level, which is true — but the UI layer hides it.)
+- **Fix:** Render a `/403` page or surface a toast on access denial in the admin route layout. Keep the URL on the failed route so users can verify what they tried to reach.
+
+---
+
+## 🟡 MEDIUM (45 findings — by area)
+
+### Multi-tenancy (5)
+
+| ID     | Title                                                   | File:line                                                        | Fix sketch                                                  |
+| ------ | ------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- |
+| M-MT01 | `updateDefinition` UPDATE missing portId in WHERE       | `src/lib/services/custom-fields.service.ts:136-145`              | Add `and(eq(...id), eq(...portId, portId))` to UPDATE WHERE |
+| M-MT02 | Notes UPDATE/DELETE missing entityId scope              | `src/lib/services/notes.service.ts:846-850, 869-873, 897-901`    | Add `eq(...notes.<parent>Id, entityId)` to WHERE            |
+| M-MT03 | Contact UPDATE/DELETE missing clientId scope            | `src/lib/services/clients.service.ts:737-741, 764`               | Add `eq(clientContacts.clientId, clientId)` to WHERE        |
+| M-MT04 | `listForYachtAggregated` ownerClientId lookup no portId | `src/lib/services/notes.service.ts:276-283`                      | Add `eq(clients.portId, portId)`                            |
+| M-MT05 | Webhook reads expose row before JS portId check         | `src/lib/services/webhooks.service.ts:103-108, 133-137, 170-174` | Move portId into `findFirst` WHERE                          |
+
+### Schema (5)
+
+| ID     | Title                                                                           | File:line                                                                                  | Fix sketch                                                                                            |
+| ------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| M-SC01 | Migrations 0000-0036 not idempotent (no IF NOT EXISTS / DO blocks)              | `src/lib/db/migrations/0000_narrow_longshot.sql`, `0036_polymorphic_check_constraints.sql` | Standardize IF NOT EXISTS / DO block pattern for new migrations; document 0000-0036 not re-runnable   |
+| M-SC02 | `companies` missing soft-delete partial index                                   | `src/lib/db/schema/companies.ts:39-45`                                                     | `CREATE INDEX IF NOT EXISTS idx_companies_archived ON companies (port_id) WHERE archived_at IS NULL;` |
+| M-SC03 | FTS GIN index missing for `interests` and `berths`                              | `src/lib/db/migrations/0057_search_fts_indexes.sql`                                        | Add `CREATE INDEX CONCURRENTLY ... USING gin (...)` for both                                          |
+| M-SC04 | `audit_logs.searchText` schema/DB mismatch (Drizzle plain, DB GENERATED ALWAYS) | `src/lib/db/schema/system.ts:53-54`                                                        | Annotate as non-updateable / generated marker                                                         |
+| M-SC05 | `documents.clientId` Drizzle nullable but DB `ON DELETE NO ACTION`              | `src/lib/db/schema/documents.ts:72`, migration `0000_narrow_longshot.sql:814`              | Migration mirroring 0059's fix for `files.client_id`: drop + re-add with `ON DELETE SET NULL`         |
+
+### Routes / Middleware (2)
+
+| ID    | Title                                                                                    | File:line                           | Fix sketch                                                                                    |
+| ----- | ---------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- |
+| M-R01 | `/portal/` blanket allowlist removes middleware backstop                                 | `src/proxy.ts:65`                   | Allowlist only unauthenticated portal routes individually; add middleware portal-cookie check |
+| M-R02 | No explicit OPTIONS handlers, no CORS headers (defer until cross-origin consumer exists) | All `route.ts` under `src/app/api/` | Add explicit `Access-Control-Allow-Origin: <marketing-domain>` to public routes when needed   |
+
+### Audit log (4)
+
+| ID     | Title                                                             | File:line                                                           | Fix sketch                                                                                                              |
+| ------ | ----------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| M-AU01 | FTS `search_text` covers only 4 fields; placeholder text misleads | migration `0014_black_banshee.sql:47-55` + `audit-log-list.tsx:360` | Change placeholder OR add `metadata` to GENERATED expression                                                            |
+| M-AU02 | Admin audit log shows field names but no old→new diff             | `audit-log-list.tsx:290-305` + `audit-log-card.tsx:84-91`           | Add row-expand using `buildDiffLine` from activity-feed.tsx                                                             |
+| M-AU03 | No audit log CSV export endpoint                                  | (absent)                                                            | `GET /api/v1/admin/audit/export/csv` reusing `searchAuditLogs`                                                          |
+| M-AU04 | Outcome change uses `action: 'update'` not distinct verb          | `interests.service.ts:1047-1058`                                    | Add `'outcome_change'` to `AuditAction`; use in setInterestOutcome/clearInterestOutcome; add to dropdown + severity map |
+
+### Documents/files (1)
+
+| ID    | Title                                                                              | File:line                                        | Fix sketch                                                         |
+| ----- | ---------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------ |
+| M-D01 | Real-time invalidation event-name mismatch (`'file:created'` vs `'file:uploaded'`) | `src/components/documents/documents-hub.tsx:141` | Change to `'file:uploaded': [['files']]` matching other components |
+
+### Security (1)
+
+| ID    | Title                                                                              | File:line                                                                         | Fix sketch                                                                                 |
+| ----- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| M-S01 | S3 access key ID stored plaintext in `system_settings` (secret encrypted, key not) | `src/lib/storage/index.ts:136`, `src/components/admin/storage-admin-panel.tsx:80` | Apply same `encrypt()` / `*IsSet` pattern as secret key; migration to re-key existing rows |
+
+### Email + Integrations (8)
+
+| ID     | Title                                                                               | File:line                                                                    | Fix sketch                                                                                      |
+| ------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| M-EM01 | Portal activation/reset emails not threaded with portId — falls back to global SMTP | `src/lib/services/portal-auth.service.ts:163-164`                            | Pass `portId` as 6th arg to both `sendEmail` calls                                              |
+| M-EM02 | No CC/BCC in main `sendEmail`                                                       | `src/lib/email/index.ts:54-68`                                               | Add optional `cc`/`bcc` to `SendEmailOptions`                                                   |
+| M-EM03 | Bounce-to-interest linking not implemented                                          | `src/lib/services/sales-email-config.service.ts:13`                          | Wire BullMQ recurring job using imapflow to scan inbox for bounce NDRs (Phase 7 §14.9 deferred) |
+| M-EM04 | Notification digest uses `'crm_invite' as any` for subject resolution               | `src/lib/services/notification-digest.service.ts:161-169`                    | Add `'notification_digest'` to `TEMPLATE_KEYS`; update digest service                           |
+| M-IN01 | Presigned URL TTL fixed at 900s for portal downloads                                | `src/lib/storage/index.ts:240-254`; `src/lib/services/portal.service.ts:350` | Pass `expirySeconds: 4 * 3600` for portal links, or sign on-demand from API                     |
+| M-IN02 | OpenAI receipt-scanner module-level instantiation, no credential health check       | `src/lib/services/receipt-scanner.ts:4`                                      | Guard `OPENAI_API_KEY` upfront; add health-check endpoint                                       |
+| M-IN03 | Receipt OCR ignores per-port config; hardcoded `gpt-4o`                             | `src/lib/services/receipt-scanner.ts:19`                                     | Accept `portId`, call `getResolvedOcrConfig(portId)`, branch on provider                        |
+| M-IN04 | Stale "pdfme" references in comments/seed                                           | `src/lib/db/seed-data.ts:807`, `src/lib/services/document-templates.ts:573`  | Update comments to reference pdf-lib AcroForm fill                                              |
+| M-IN05 | Umami `testConnection` throws instead of typed `{ ok: false }`                      | `src/lib/services/umami.service.ts:80-101, 292`                              | Return `{ ok: false, error }` to match `checkDocumensoHealth`                                   |
+
+### Performance + Behavioral (1)
+
+| ID    | Title                                                                 | File:line                     | Fix sketch                                                                                          |
+| ----- | --------------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------- |
+| M-P01 | Leading-wildcard `ILIKE '%term%'` in `buildListQuery` defeats indexes | `src/lib/db/query-builder.ts` | Migrate to `pg_trgm` GIN indexes on searched columns, or move to FTS via existing `search_text` GIN |
+
+### Legacy enum drift (2)
+
+| ID    | Title                                                                | File:line                                                                  | Fix sketch                                                               |
+| ----- | -------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| M-L01 | Tenure type enum diverges between berths and reservations            | `src/lib/db/schema/berths.ts:65` vs `src/lib/db/schema/reservations.ts:32` | Pick canonical enum union; update both schemas + comments                |
+| M-L02 | Reports stage rollup raw `pipelineStage` without `canonicalizeStage` | `src/lib/services/report-generators.ts:71-76, 88-106, 124-138, 176-192`    | Wrap row.stage with `canonicalizeStage()` before keying maps (defensive) |
+
+### UX/forms (12)
+
+| ID    | Title                                                                  | File:line                                                                      | Fix sketch                                                                                 |
+| ----- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| M-U01 | Audit log uses inline div instead of `<EmptyState>`                    | `src/components/admin/audit/audit-log-list.tsx:524`                            | Replace with `<EmptyState title="..." />`                                                  |
+| M-U02 | Two duplicate `EmptyState` components with incompatible APIs           | `src/components/ui/empty-state.tsx` vs `src/components/shared/empty-state.tsx` | Migrate 3 `ui/` callers to `shared/`, delete `ui/empty-state`                              |
+| M-U03 | Required-field marker inconsistent                                     | `client-form.tsx:273`, `interest-form.tsx:281`                                 | Single pattern: `<Label>Field <span aria-hidden>*</span></Label>` + `aria-required="true"` |
+| M-U04 | Help-text discoverability inconsistent                                 | `src/components/shared/filter-bar.tsx`, `client-form.tsx`                      | Document a rule (always-visible for constraints; tooltips only for icons)                  |
+| M-U05 | Cancel/dismiss without unsaved-changes warning on ClientForm/YachtForm | `client-form.tsx`, `yacht-form.tsx`                                            | Add `isDirty` guard + discard AlertDialog matching InterestForm                            |
+| M-U06 | FileUploadZone size limit not surfaced as client-side check            | `src/components/files/file-upload-zone.tsx:170`                                | Wire client-side size check before upload                                                  |
+| M-U07 | No jump-to-page input in pagination                                    | `src/components/shared/data-table.tsx:420`                                     | Add small `<input type="number">` between Previous/Next                                    |
+| M-U08 | No column resize/reorder on DataTable                                  | `src/components/shared/data-table.tsx`                                         | Opt-in `enableColumnResizing` per table via TanStack v8                                    |
+| M-U09 | Invoice delete uses custom overlay, not AlertDialog                    | `src/app/(dashboard)/[portSlug]/invoices/page.tsx:167`                         | Replace with `<ConfirmationDialog>`                                                        |
+| M-U10 | Success toast missing on ClientForm + InterestForm create/edit         | `client-form.tsx:215`, `interest-form.tsx:235`                                 | `toast.success(isEdit ? 'Client updated' : 'Client created')`                              |
+| M-U11 | Logo preview `<img alt="">` should describe state                      | `src/components/admin/shared/settings-form-card.tsx:420`                       | `alt="Port logo preview"` or dynamic from field label                                      |
+| M-U12 | Heading hierarchy inconsistent within tab components                   | `email-accounts-list.tsx:114`, `interest-contract-tab.tsx:130/251/291/364`     | Audit each tab; standardize h2/h3 nesting                                                  |
+| M-U13 | DialogContent missing aria-describedby on minimal dialogs              | `compose-dialog.tsx:95` + ~40 others                                           | Add `<DialogDescription className="sr-only">` or `aria-describedby={undefined}`            |
+| M-U14 | Mobile topbar title blank on list pages                                | `client-list.tsx`, `yacht-list.tsx`, `interest-list.tsx`, `berth-list.tsx`     | `useMobileChrome({ title, showBackButton: false })` per list                               |
+| M-U15 | Invoices missing from mobile navigation                                | `src/components/layout/mobile/more-sheet.tsx:54`                               | Add `{ label: 'Invoices', icon: FileText, segment: 'invoices' }` to Operations group       |
+
+---
+
+## 🟢 LOW (8)
+
+| ID     | Title                                                                                                  | File:line                                           |
+| ------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
+| L-AU01 | Tier map sparse; new actions default to 'info' (`password_change`, `portal_activate`, `revoke_invite`) | `src/lib/audit.ts:220-222`                          |
+| L-AU02 | Action filter dropdown missing 12 verbs                                                                | `audit-log-list.tsx:393-415`                        |
+| L-AU03 | Entity-type filter dropdown missing 7 entries                                                          | `audit-log-list.tsx:88-102`                         |
+| L-AU04 | Dead code — `listAuditLogs` (ILIKE)                                                                    | `src/lib/services/audit.service.ts`                 |
+| L-D01  | `HubRootView` has 2 sections, not 3 (CLAUDE.md spec inaccuracy)                                        | `src/components/documents/hub-root-view.tsx:50-100` |
+| L-D02  | `interest.yachtId` branch in chain doc spec is unreachable (interests.clientId NOT NULL)               | `src/lib/services/documents.service.ts:1225-1251`   |
+| L-P01  | List endpoint `limit` cap = 1000 (audit log uses 200 + cursor as the better pattern)                   | `src/lib/api/list-query.ts`                         |
+| L-L01  | Reports stage-revenue rollup raw `pipelineStage` (defensive concern, no active bug)                    | `src/lib/services/report-generators.ts:71-192`      |
+
+---
+
+## ✅ Areas verified clean
+
+- Documents/files structurally solid across 22 checks (one event-name mismatch + 2 doc divergences only)
+- Security XSS / SQLi / path traversal / SSRF / encryption-at-rest all clean (one S3 access key plaintext)
+- Multi-tenancy entry-point port isolation correct everywhere; gaps are TOCTOU-style only
+- Documenso v1+v2 routing complete and version-aware; magic-byte verification on both upload paths
+- Public berths API + public health endpoint + cookie flags + CSP + CSRF all correctly configured
+- Audit log core write path covers all sampled mutations; `maskSensitiveFields` covers expected PII fragments
+- Better-auth session fixation, token expiry, audit-log tamper-resistance all clean
+- Legacy 9-stage enum refactor — rank tables now include both legacy + modern keys (commit 9821106 closed the gap); all rendering surfaces route through `stageLabelFor` or `LEGACY_STAGE_REMAP`
+- BullMQ retry/backoff configured; Redis noeviction enforced in compose; worker process bootstraps all 10 queues
+- pdf-lib AcroForm fill, EOI merge tokens, `formatBerthRange` (single/contig/non-contig/cross-pontoon)
+- Inline editing pattern present on all 6 detail page types; NotesList polymorphic across all 6 entity types
+
+---
+
+---
+
+## Browser sweep findings (Playwright MCP) — 2026-05-15
+
+Live exploratory testing of the dev instance (port-amador + port-nimara seeded) using Playwright MCP. All findings below were either (a) confirmation of static findings, or (b) new bugs only visible at runtime.
+
+### New criticals + highs from browser sweep
+
+- **🔴 C-03** — Generic `PATCH /api/v1/interests/[id]` bypasses ALL stage-transition guards (see C-03 above for full detail). The single most impactful new finding from the sweep.
+- **🟠 H-14** — `DELETE /outcome` with empty body returns 500 (see H-14 above).
+- **🟠 H-15** — Sales-agent → `/admin/*` silently bounces to `/dashboard`, no 403 page or toast (see H-15 above).
+
+### New medium from browser sweep
+
+- **M-NEW-1** — `/api/v1/me` and `/api/v1/me/ports` return 400 "Port context required" for non-super-admin callers without the `X-Port-Id` header. Super-admin works without the header. **Impact:** chicken-and-egg for the bootstrap flow that needs to know which ports a user has access to in order to choose one. Frontend likely passes the header from cookie state, but the contract is asymmetric per role. **Fix:** treat absent `X-Port-Id` on `/me/ports` as "list all ports the user has access to, regardless of context".
+- **M-NEW-2** — Activity feed entity-type label rendered without separator: "Test Person 1interest", "Audit_loglist", "Settingrecom" — entity name + type concatenated. **File:** `src/components/dashboard/activity-feed.tsx` (the line that renders the entity label + type tag). **Fix:** add a separator (space, dot, or pipe) between name and type.
+
+### Verifications confirmed clean in browser
+
+| Check                              | Result                                                                                                                                                                 |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| C-02 `/setup` deadlock             | ✅ confirmed: navigation redirects to `/login` (no `?redirect=` param even); `bootstrap/status` returns `needsBootstrap: false` on populated DB; loop fires when fresh |
+| H-02 `?redirect=` ignored          | ✅ confirmed: signed in with `?redirect=%2Fport-amador%2Fclients%2Fsome-fake-id` → landed at `/port-amador/dashboard`                                                  |
+| H-04 `Retry-After` missing         | ✅ confirmed: 429 fired on 2nd bad sign-in attempt, headers `x-ratelimit-limit/remaining/reset` present, NO `Retry-After`                                              |
+| R-004 cross-port URL               | ✅ clean: `/port-amador/clients/<port-nimara-uuid>` shows friendly "Client not found... different port" page                                                           |
+| MT-02 cross-port PATCH             | ✅ clean: `PATCH /api/v1/interests/<port-nimara-id>` with `X-Port-Id: port-amador` → 404 "We couldn't find that interest"                                              |
+| Viewer permissions                 | ✅ clean: read 200, write same-port 403 "Insufficient permissions", write cross-port 403 "No access to this port"                                                      |
+| F27 same-stage no-op               | ✅ clean via `/stage` endpoint (returns 204); ❌ broken via generic PATCH (200 + body) — see C-03                                                                      |
+| Forbidden transition               | ✅ clean via `/stage` (400 with override-required-reason copy); ❌ bypassed via generic PATCH (see C-03)                                                               |
+| Override no-reason                 | ✅ clean via `/stage` (400 "Override requires a reason (min 5 chars)")                                                                                                 |
+| Override short-reason              | ✅ clean via `/stage` (same 400)                                                                                                                                       |
+| AU-11 permission_denied filter     | ✅ activity feed shows no raw `permission_denied` rows                                                                                                                 |
+| A2 legacy enum in feed             | ✅ no raw `deposit_10pct` / `eoi_sent` / `contract_signed` in activity feed text                                                                                       |
+| R-008 mooring URL canonicalization | ✅ `A1`=200, `a1`=400, `A%201`=400, `A-1`=400                                                                                                                          |
+| B-10 webhook empty/malformed body  | ✅ both return 200 `{ok:false}` (graceful)                                                                                                                             |
+| Tag CRUD (AD-014)                  | ✅ 201 create + 204 delete                                                                                                                                             |
+| Settings update (AD-008)           | ✅ 200 with persisted body                                                                                                                                             |
+| Interest detail render             | ✅ EOI badge, milestone "EOI sent May 14, 2026", no raw legacy values, no errors                                                                                       |
+| Interest reopen with reopenStage   | ✅ 200 ok                                                                                                                                                              |
+| Public berths shape                | ✅ 117 berths, statuses split Sold=11 / Under Offer=49 / Available=57                                                                                                  |
+
+### Out of scope for this sweep (not exercised)
+
+- Live Documenso integration (requires real-API project — `pnpm exec playwright test --project=realapi`)
+- IMAP bounce probe round-trip (requires SMTP+IMAP credentials)
+- C-01 berth-INNER-JOIN bug — would require hard-deleting a berth in the live DB (destructive); static analysis already conclusive
+- Browser-side cross-browser testing (BR-\* — Safari, Firefox, Edge)
+- Drag-and-drop kanban interactions
+- Visual regression baselines (`--project=visual` snapshots)

docs/AUDIT-FIX-WAVE-2026-05-18.md

@@ -0,0 +1,266 @@
+# Audit Fix Wave — 2026-05-18
+
+Progress report against `docs/AUDIT-FINDINGS-2026-05-15.md` (74 findings)
+and the still-open Wave-11 items in `docs/AUDIT-FOLLOWUPS.md`. Each
+finding was re-verified against the current code before being touched —
+the previous session's 70 uncommitted files mostly added new behaviour
+and rarely overlapped with the audit issues, so almost everything was
+still applicable.
+
+`pnpm exec vitest run` → 1374/1374 pass. `pnpm exec tsc --noEmit` clean.
+
+---
+
+## 🔴 CRITICAL — 3 / 3 done
+
+- **C-01** interest-berths INNER JOIN on hard-deleted berths — three
+  helpers switched to LEFT JOIN; `listBerthsForInterest` return type
+  loosened so an orphaned junction row still renders. Berth hard-delete
+  is already redirected to soft-archive, so the audit's "service-layer
+  guard preventing hard-delete" requirement is implicitly satisfied via
+  `archiveBerth`'s active-interest check.
+- **C-02** `/setup` missing from `PUBLIC_PATHS` — added.
+- **C-03** generic `PATCH /api/v1/interests/[id]` bypassing stage guards
+  — `updateInterestSchema` now omits `pipelineStage`, forcing every
+  caller through the `/stage` endpoint with the override-permission +
+  override-reason guard chain.
+
+## 🟠 HIGH — 14 / 15 fixed, 1 not-applicable
+
+- **H-01** FK `ON DELETE` actions made explicit across interests /
+  documents / reservations / reminders / invoices schemas; migration
+  `0070_h01_fk_on_delete.sql` drops + re-adds each constraint under
+  the same name (idempotent against re-run).
+- **H-02** login page reads `?redirect=` param with same-origin guard
+  (`startsWith('/')` and `!startsWith('//')`).
+- **H-03** CRM-invite token moved to URL fragment (`#token=…`); the
+  set-password page reads from fragment via `useSyncExternalStore` with
+  `?token=` back-compat for outstanding links.
+- **H-04** `Retry-After` header added to the sign-in-by-identifier 429
+  response (RFC 6585 §4).
+- **H-05** `toggleAccount` now writes an audit row (action 'update',
+  entityType 'email_account', oldValue/newValue around isActive).
+- **H-06** `upsertSetting` masks any value whose key ends with
+  `_encrypted` to `[redacted]` before writing to `audit_logs.new_value`
+  — keeps the ciphertext out of the historical audit trail.
+- **H-07** `archiveClient`'s cascade fires per-interest audit rows
+  (action 'archive', metadata.cascadeSource = 'client_archive') so the
+  audit FTS surfaces a search for a specific archived interest.
+- **H-08** `createSalesTransporter` now applies the shared
+  `SMTP_TIMEOUTS` constant — sales send-outs can no longer stall the
+  BullMQ pool on a hung relay.
+- **H-09** AppShell refactored so `<main>{children}</main>` lives at an
+  invariant tree path across mobile/desktop chrome — React preserves
+  in-progress form drafts when the viewport flips across the breakpoint.
+- **H-10** portal documents page replaces Unicode glyph status icons
+  with Lucide CheckCircle2/XCircle/Circle + aria-labels.
+- **H-12** three list components (interests/companies/yachts) swap
+  `alert(…)` for `toast.warning(…)` matching client-list.
+- **H-13** 5 icon-only buttons gain `aria-label` (notification bell,
+  file-grid actions menu, form-template edit/delete, email-account
+  remove, member-actions menu).
+- **H-14** `parseBody` now treats empty request bodies as `{}` so
+  routes whose schemas have all-optional fields don't crash on an empty
+  DELETE / PATCH payload.
+- **H-15** admin layout renders an explicit 403 panel ("Access denied —
+  this area is for super-administrators only") instead of a silent
+  redirect to `/dashboard`, with a "Back to dashboard" CTA. URL stays
+  on the failed route.
+
+**Not applicable:**
+
+- **H-11** mobile-search-overlay Vaul → Sheet conversion. The audit's
+  premise ("full-screen, not a bottom sheet") is inaccurate — the
+  overlay has `top: 12px` (visible backdrop strip), drag handle,
+  swipe-to-dismiss, and explicit visualViewport sizing for iOS keyboard
+  behaviour. CLAUDE.md's "Sheet vs Drawer doctrine" explicitly allows
+  Vaul for "mobile-only bottom-sheet UX" which is this case.
+
+## 🟡 MEDIUM — 28 / 48 fixed, 5 deferred, the rest covered by larger work
+
+### Done
+
+- **M-MT01-05** multi-tenancy defense-in-depth: `port_id` / parent-id
+  filters added to UPDATE/DELETE WHEREs across custom-fields, notes
+  (all 6 entity types × update + delete), client-contacts, yacht
+  ownerClient lookup, and webhooks reads.
+- **M-AU01** audit log placeholder copy fixed.
+- **M-AU02** already done in previous session (Details column + Sheet).
+- **M-AU04** outcome change now uses distinct audit verbs
+  `outcome_set` / `outcome_cleared`; AuditAction type extended.
+- **M-D01** documents-hub realtime event-name typo (`file:created` →
+  `file:uploaded`) fixed.
+- **M-EM01** portal-auth activation + reset emails now pass `portId`
+  to `sendEmail` so per-port SMTP is used.
+- **M-EM02** `sendEmail` accepts `cc` / `bcc` params; redirect mode
+  drops both (consistent with the dev safety net).
+- **M-EM04** `notification_digest` added to `TEMPLATE_KEYS` +
+  `TEMPLATE_CATALOG`; the digest service drops the `'crm_invite' as any`
+  cast.
+- **M-IN01** portal presigned download URLs now use a 4-hour TTL so
+  client links from yesterday's emails still work.
+- **M-IN02** OpenAI client lazy-instantiated; missing key surfaces a
+  clear error instead of crashing at module load.
+- **M-IN04** stale pdfme comments in seed-data + document-templates
+  updated to pdf-lib AcroForm.
+- **M-IN05** `umami.testConnection` returns `{ ok: true|false, … }`
+  tagged union instead of throwing.
+- **M-L02** `report-generators.ts` canonicalises stage values via
+  `canonicalizeStage()` across pipeline / revenue / forecast rollups
+  so legacy 9-stage rows fold into the modern 7-stage buckets.
+- **M-NEW-2** activity feed entity-name/type concatenation — explicit
+  middle-dot separator so "Test Person 1" + "interest" no longer renders
+  as one word.
+- **M-R01** portal allowlist narrowed from blanket `/portal/` to the
+  three unauthenticated entry-points + portal_session backstop in the
+  middleware redirects to `/portal/login` when the cookie is missing.
+- **M-SC02** companies gets `idx_companies_archived` partial index
+  matching the clients/yachts/interests pattern.
+- **M-SC04** `auditLogs.searchText` documented as GENERATED ALWAYS /
+  DB-managed.
+- **M-SC05** documents.clientId `ON DELETE SET NULL` covered by the
+  H-01 migration.
+- **M-U01** audit-log empty state uses `<EmptyState>`.
+- **M-U09** invoice delete dialog migrated from hand-rolled overlay to
+  `<AlertDialog>` (focus trap, ESC-to-close, a11y semantics).
+- **M-U10** ClientForm + InterestForm fire `toast.success(...)` on
+  create/edit.
+- **M-U11** logo preview `<img>` carries a descriptive alt.
+- **M-U14** mobile topbar title surfaced on clients / interests /
+  yachts / berths list pages via `useMobileChrome`.
+- **M-U15** Invoices added to the mobile More-sheet Operations group.
+- **M-L01** `reservations.tenureType` comment unified with
+  `berths.tenureType` (canonical union).
+- **M-S01** `storage_s3_access_key_encrypted` admin field added; the
+  encrypt-plaintext-credentials script handles the data migration.
+
+### Deferred (need user input or scope-larger-than-an-audit-fix)
+
+- **M-AU03** — audit log CSV export endpoint. New feature surface.
+- **M-EM03** — bounce-to-interest IMAP linking (Phase 7 §14.9).
+- **M-IN03** — receipt-scanner per-port OCR config (every call site
+  needs `portId` threading).
+- **M-NEW-1** — `/me/ports` asymmetric port-context header semantics.
+- **M-P01** — leading-wildcard ILIKE → pg_trgm GIN migration.
+- **M-SC03** — FTS GIN on interests + berths (search.service.ts
+  doesn't use to_tsvector for these — feature work).
+
+### Lower-priority M-U items left untouched (cosmetic / process)
+
+`M-U02` (dedup EmptyState components), `M-U03` (required-field marker
+standardisation), `M-U04` (help-text discoverability rule), `M-U05`
+(unsaved-changes warning on ClientForm/YachtForm), `M-U06`
+(FileUploadZone client-side size check), `M-U07` (pagination
+jump-to-page), `M-U08` (column resize/reorder), `M-U12` (heading
+hierarchy across tab components), `M-U13` (DialogContent aria-describedby
+across ~40 sites). All polish-grade — drop into a focused UX session.
+
+## 🟢 LOW — 6 / 8 fixed, 2 deferred / not-applicable
+
+- **L-AU01** severity defaults extended (password_change → warning,
+  portal_password_reset → warning, etc).
+- **L-AU02** action-filter dropdown gains 13 missing verbs
+  (password*change, portal*\_, gdpr\__, rule*evaluated, outcome*_,
+  branding.\_).
+- **L-AU03** entity-type dropdown gains 7 missing entries (yacht,
+  company, reservation, email_account, portal_session, portal_user,
+  file).
+- **L-AU04** dead `listAuditLogs` (ILIKE) stubbed out — callers all
+  use the FTS-backed `searchAuditLogs` now.
+- **L-D02** CLAUDE.md "Owner-wins chain" tightened — `interest.yachtId`
+  tail branch removed from the spec (structurally unreachable since
+  `interests.clientId` is NOT NULL).
+- **L-P01** list endpoint limit cap — DEFER per audit (cursor pagination
+  is on the routes where it matters; the 1000-row cap is fine at
+  current data sizes).
+- **L-D01** HubRootView spec inaccuracy — verified accurate; the
+  CLAUDE.md "three render modes" line refers to render _modes_, not
+  sections within HubRootView. Audit finding is a misread.
+- **L-L01** reports defensive concern — covered by M-L02's
+  canonicalize sweep.
+
+---
+
+## Bonus: document-detail polish (#67 partial)
+
+Three of the six deliverables in MANUAL-TESTING-BACKLOG §4.10b shipped
+in this wave:
+
+- **State-aware action button per signer** — `invitedAt === null` →
+  primary "Send invitation" CTA (paper-plane); else "Send reminder"
+  (bell). Hits the existing `/send-invitation` and `/remind` routes.
+- **Watcher Add UI** — replaces the user-id stub display with the
+  display name from `/api/v1/admin/users/picker`, plus a "+ Add"
+  select that lets admins pick any user in the port that isn't already
+  watching. Existing delete affordance untouched.
+- **`cleanSignerName` cleanup** — shared from `SigningProgress` and
+  applied to the doc-detail card so EMAIL_REDIRECT_TO `(was: …)` /
+  `(placeholder)` suffixes stop leaking through.
+
+The remaining three deliverables (full SigningProgress visual parity,
+linked-entity name resolution, activity-panel `document_events` polish
+with per-event icons + tooltips) need API changes to return entity
+names + a meaningful event-type icon map. Deferred so it can ship in
+one focused PR.
+
+## Smoke validations against the running dev server
+
+- **C-02** — `/setup` is reachable (middleware lets it through; page
+  itself redirects to `/login` when `needsBootstrap=false`). No infinite
+  redirect loop.
+- **M-R01** — `/portal/documents` without a portal_session cookie now
+  redirects to `/portal/login?redirect=/portal/documents`.
+- **H-04** — sign-in 429 response carries `Retry-After: 900` plus the
+  full `X-RateLimit-*` triplet.
+
+## What still needs your input
+
+Items genuinely blocked on a decision you haven't made yet. Most exist
+in the 2026-05-15 manual-testing-backlog already; surfacing here in one
+place for resolution.
+
+1. **PDF template editor / builder (MANUAL-TESTING-BACKLOG §9.Z)** —
+   ship Phase 1 alone (in-app fill of admin-uploaded PDFs with
+   merge-token mapping, ~1–2 weeks) or wait until Phases 1+2 can land
+   together (also Documenso template push, ~3–4 weeks)?
+2. **Document detail refactor (#67 in §4.10b)** — multi-deliverable
+   redesign. Are we shipping it as one PR or splitting?
+3. **Reminders data model (§0.1 + §3.2)** — Path A (extend lightweight
+   columns on `interests` — note/timeOfDay/priority/recurrence) or
+   Path B (push richer reminders into the existing `reminders` table)?
+4. **Supplemental info form (§0.2)** — CRM-hosted route or
+   marketing-site-hosted? Need a green light to spend ~15 minutes
+   tracing the route end-to-end.
+5. **EOI-scoped data overrides (§4.2)** — does the override apply only
+   to this specific EOI document, or to ALL future EOIs on this
+   interest? Reopening the drawer: show original override or fall back
+   to canonical? Are the overrides reusable for reservation + contract
+   or EOI-only?
+6. **`/me/ports` port-context asymmetry (M-NEW-1)** — should the
+   endpoint treat absent `X-Port-Id` as "list all ports the user has
+   access to"? Currently super-admins work without it; everyone else
+   gets a 400.
+7. **Bounce-to-interest IMAP linking (M-EM03 / Phase 7 §14.9)** —
+   ready to scope or stays deferred?
+8. **Receipt-scanner per-port OCR config (M-IN03)** — every call site
+   needs `portId` threading. Confirm we should do this now vs. when a
+   second-port OCR config materialises?
+9. **CSV export of audit logs (M-AU03)** — net-new endpoint. Ship?
+10. **Documenso phases 2–7 (BACKLOG §A)** — still back-burnered or
+    ready to pick up?
+
+---
+
+## Migrations to apply
+
+`pnpm tsx scripts/db-migrate.ts` (or your usual migration runner) will
+pick up the single new migration `0070_h01_fk_on_delete.sql`. It's
+idempotent — each ALTER drops the constraint by name first, so re-runs
+are safe.
+
+## Files touched this wave
+
+`118 files changed, 5181 insertions(+), 1301 deletions(-)` — but note
+that count rolls in the previous session's 70 uncommitted files. Run
+`git diff --stat HEAD docs/AUDIT-FINDINGS-2026-05-15.md` to see only
+the audit-fix diff.

docs/AUDIT-FOLLOWUPS.md

@@ -0,0 +1,716 @@
+# Audit Follow-ups — 2026-05-08 visual audit
+
+This is the single index for everything from the 2026-05-08 mobile visual
+audit. Owns: status of each item, file pointers, every open question,
+and a ready-to-paste prompt for resuming in a fresh session.
+
+Items are grouped by **wave** (the original triage buckets, kept stable
+across sessions). Numbering inside each wave matches the original audit
+message order where possible.
+
+> **If you only have time for one section, read § "Resuming in a fresh
+> session" at the bottom.**
+
+---
+
+## Quick status snapshot — 2026-05-09 (post-execution)
+
+| Wave      | Topic                                      | Status                                                                  |
+| --------- | ------------------------------------------ | ----------------------------------------------------------------------- |
+| 1         | Small confident fixes                      | ✅ Done                                                                 |
+| 2         | Country dropdown unification + cmdk scroll | ✅ Done (country/nationality split still deferred — see Wave 11.E)      |
+| 3         | Berth field overhaul (NocoDB enums)        | ✅ Done                                                                 |
+| 4         | Currency platform-wide                     | ✅ Done                                                                 |
+| 5         | Configurable enums (admin Vocabularies)    | ✅ Admin page + read endpoint shipped; consumer wiring is owed          |
+| 6         | Notes unification (aggregate-on-read)      | ✅ Done — yacht / company / residential aggregators + UI                |
+| 7         | Clients / yachts / companies misc          | ✅ Status-link flow done; client form expansion still large (Wave 11.A) |
+| 8         | Expenses revisit                           | ✅ Done — trip-label combobox (free text + past suggestions)            |
+| 9         | Interests + notifications                  | ✅ Done                                                                 |
+| 10        | Settings polish                            | ✅ Done — first/last name + collapse notif prefs                        |
+| 11.A      | Manual client form expansion               | 🔴 Not started (large)                                                  |
+| 11.B      | Documents folders (unlimited nesting)      | 🔴 Not started — needs deep design (sidebar tree + breadcrumb)          |
+| 11.C      | Reports system + templates                 | 🔴 Not started                                                          |
+| 11.D      | Receipts inline in expense PDF             | 🔴 Not started                                                          |
+| 11.E      | Country / Nationality split on Client form | 🔴 Not started                                                          |
+| 11.F      | Inquiry triage                             | 🔴 Deferred                                                             |
+| 11.G      | Per-port email branding admin UI           | 🔴 Deferred                                                             |
+| **Bonus** | **Public berth feed (website map)**        | ✅ Parity fields shipped; cutover deferred (see runbook)                |
+| **Bonus** | **Website cutover runbook**                | ✅ Doc shipped (`docs/website-cutover-runbook.md`); execution deferred  |
+| **Bonus** | **Berth Documents tab → Spec + Deal**      | ✅ Done                                                                 |
+
+Test status: `pnpm exec vitest run` → **1187/1187 pass**.
+TS check: `pnpm exec tsc --noEmit` → **clean**.
+Git: 9 commits this session (Waves 4-10 + admin Vocabularies + status-change link + Berth Documents tab split + decisions log).
+
+---
+
+## Ground rules / invariants we picked up
+
+- **Notes unification model**: aggregate-on-read (option 1 from the
+  AskUserQuestion, picked by user). One canonical service per entity
+  unions own-notes + related-entity notes; no replication, no schema
+  migration.
+- **NocoDB MCP**: connected at `~/.claude.json` under
+  `mcpServers."NocoDB Base - Port Nimara"`. Verified Berths schema +
+  records pull cleanly. The seed-data JSON snapshot
+  (`src/lib/db/seed-data/berths.json`) is also a reasonable fallback
+  if the MCP is unavailable.
+- **Berth dropdown values** are now sourced from the NocoDB SingleSelect
+  choices verbatim — see `src/lib/constants.ts` (look for
+  `BERTH_*_OPTIONS` / `_TYPES`). Power Capacity and Voltage stay numeric
+  inputs because NocoDB stores them as `Number`. Bow Facing is
+  `SingleLineText` in NocoDB but constrained to the 4 cardinal values
+  in the CRM dropdown for UX.
+- **Dual-unit fields** auto-cross-fill via `linkedUnit` on
+  `EditableSpec` in `src/components/berths/berth-tabs.tsx`. The user
+  edits the imperial value; the metric column is computed × 0.3048 and
+  patched in the same request.
+- **Receipts in expense PDF**: user's clarified preference is "PDF
+  images should show inline with the relevant expense" — i.e. images
+  inline; PDF receipts also rendered inline (one page each, via
+  pdfme + `pdf-lib.copyPages`).
+- **Configurable enums**: the existing pattern is `system_settings`
+  with composite PK `(key, port_id)` and `<SettingsManager>` admin
+  page. Use the same pattern for the new vocabularies.
+- **Turbopack dev**: `pnpm dev` runs `next dev --turbopack`. Cold
+  compiles ~1s boot, ~3s per route. No webpack hooks in
+  `next.config.ts` so flipping back is one line if needed.
+
+---
+
+## ✅ Completed this session
+
+### Wave 1 — small confident fixes
+
+1. **Berth list ordering bug** — `\d+$` regex in the Drizzle SQL
+   template was being eaten by JS string literal escape rules
+   (`\d` → `d`). Fixed by switching to `[0-9]+$` POSIX class.
+   File: `src/lib/services/berths.service.ts:69-72`.
+2. **Dashboard KPI grid removed** — "Total Clients / Active Interests
+   / Pipeline Value / Occupancy Rate" deleted. The four chart widgets
+   below (pipeline funnel, occupancy timeline, revenue breakdown,
+   lead source) and the activity feed remain.
+   File: `src/components/dashboard/dashboard-shell.tsx`.
+3. **Per-dock color stripe on mobile berth cards** — was the _status_
+   color, which made every same-dock berth different. Now uses
+   `mooringLetterDot()` so the stripe groups by dock letter; status
+   conveyed by the existing pill below.
+   File: `src/components/berths/berth-card.tsx`.
+4. **`{Letter} Dock` chip** on the berth detail header replaces the
+   bare "A" / "B" text. Colored by `mooringLetterDot()`.
+   File: `src/components/berths/berth-detail-header.tsx`.
+5. **cmdk wheel-scroll bug** — Radix Popover swallowed wheel events on
+   the country dropdown for macOS users. Added `onWheel` translator on
+   `CommandList` + `overscroll-contain`. Lights up country pickers in
+   Companies, Residential Clients, Clients, Yachts.
+   File: `src/components/ui/command.tsx`.
+6. **Mobile "Columns" button hidden** — `ColumnPicker` is now
+   `hidden sm:inline-flex`. Mobile renders cards (no columns to
+   toggle).
+   File: `src/components/shared/column-picker.tsx`.
+7. **Mobile kanban toggle hidden + auto-fallback** — Interest list
+   hides the table-vs-kanban toggle on small viewports and snaps
+   `viewMode` back to `'table'` if the user's persisted choice was
+   `'board'`.
+   File: `src/components/interests/interest-list.tsx`.
+8. **Inbox entry removed from mobile More-sheet** — email/IMAP feature
+   is deferred (`sidebar.tsx` calls this out); the More-sheet entry was
+   a dead link.
+9. **Website Analytics conditional** — desktop sidebar Insights section
+   AND mobile MoreSheet hide the Website Analytics nav when Umami
+   isn't configured for the port. Reuses `useUmamiActive()`.
+   Files: `src/components/layout/sidebar.tsx`,
+   `src/components/layout/mobile/more-sheet.tsx`.
+10. **"Other" comm-channel UX hint** — when a contact's channel is
+    `'other'`, the inline `Label` field switches its label/placeholder
+    to "Specify" / "e.g. Telegram, Signal".
+    File: `src/components/clients/client-form.tsx:289-302`.
+11. **End Membership wording** — renamed to "Remove from company" in
+    the company members tab dropdown.
+    File: `src/components/companies/company-members-tab.tsx:249`.
+12. **Berth area filter → letter dropdown** — was free-text; now a
+    `<Select>` constrained to `A / B / C / D / E`. Label changed to
+    "Dock" to match how the user refers to it.
+    File: `src/components/berths/berth-filters.tsx`.
+13. **Yacht flag → CountryCombobox** — was a free-text 2-letter input
+    (`placeholder="e.g. MT"`); now uses the same country picker as
+    client / residential.
+    File: `src/components/yachts/yacht-form.tsx`.
+
+### Wave 2 — country dropdown unification
+
+1. **cmdk wheel-scroll** — covered in Wave 1 (single shared command).
+2. **Country → timezone auto-set** in client form: when nationality is
+   picked and timezone empty, the primary IANA zone is pre-filled. Skips
+   when the user already chose a zone explicitly.
+   File: `src/components/clients/client-form.tsx` (look for
+   `primaryTimezoneFor`).
+3. **Browser-detected timezone fallback** in user settings: timezone
+   pre-populates from `Intl.DateTimeFormat().resolvedOptions().timeZone`
+   on first load (was empty before).
+   File: `src/components/settings/user-settings.tsx`.
+4. **Country → timezone auto-fill** also fires in user settings when
+   the country changes with no zone set.
+5. **Dropdown widths match trigger** — `CountryCombobox` and
+   `TimezoneCombobox` popover content set to
+   `w-[var(--radix-popper-anchor-width)]` with sensible `min-w-*`
+   floors so wide triggers get wide popovers.
+6. **DEFERRED: country/nationality split** on the client form — needs
+   a Drizzle migration (`alter table clients add column country_iso
+text`) plus a copy-on-migrate of existing `nationality_iso` values.
+   See § Wave 11 / pending — large.
+
+### Wave 3 — berth field overhaul (NocoDB enums)
+
+1. **Live NocoDB pull via MCP** — confirmed canonical SingleSelect
+   choices for: Side Pontoon (10 values), Mooring Type (5),
+   Cleat Type (2), Cleat Capacity (2), Bollard Type (2),
+   Bollard Capacity (2), Access (5), Area (A–E). Power Capacity and
+   Voltage are `Number` fields (not enums). Bow Facing is
+   `SingleLineText` (we still use a 4-value dropdown for UX).
+2. **`BERTH_BOW_FACING_OPTIONS`** added to `src/lib/constants.ts`
+   alongside the existing `BERTH_*_OPTIONS` constants.
+3. **`toSelectOptions()` helper** added to `src/lib/constants.ts` for
+   mapping readonly tuples → shadcn `<Select>` `{value,label}` objects.
+4. **All berth dropdown fields → `<Select>`** in both the modal form
+   (`berth-form.tsx`) and the inline-edit detail tabs
+   (`berth-tabs.tsx`). Bow facing / side pontoon / mooring type /
+   access / cleat type / cleat capacity / bollard type / bollard
+   capacity / area / tenure type.
+5. **Inline-edit `EditableSpec`** in `berth-tabs.tsx` now supports
+   `selectOptions: readonly string[]` to render a `<Select>` variant.
+6. **Dimensional auto-conversion** — `EditableSpec` gained a
+   `linkedUnit: { field, multiplier }` prop. Saving the imperial value
+   also patches the metric column (× 0.3048). Applied to length, width,
+   draft, nominal boat size, water depth.
+7. **Nominal boat size editable** — was read-only `<SpecRow>`; now an
+   `<EditableSpec numeric linkedUnit>` so editing ft auto-fills m.
+8. **Tenure type editable** — was read-only; now an inline-edit Select
+   bound to the validator's `'permanent' | 'fixed_term'` set. Will be
+   replaced by the per-port configurable list once Wave 5 ships.
+
+### Wave 9 — interests + notifications
+
+1. **StageLegend popover** — small "Legend" button in the interest
+   list filter row decodes the colored stripes on each card to the
+   pipeline stage name. Stays in sync with `STAGE_DOT` automatically.
+   File: `src/components/interests/stage-legend.tsx`.
+2. **Mobile kanban hidden** — see Wave 1.
+3. **Notifications nav 404 fixed** — More-sheet entry pointed at
+   `/notifications` which had no `page.tsx`. Now points at
+   `/notifications/preferences` and is labeled "Notification
+   preferences" — real notifications come via the topbar bell.
+   File: `src/components/layout/mobile/more-sheet.tsx`.
+
+### Wave 10 — settings polish
+
+1. **Phone input upgraded** — user settings now uses the existing
+   shared `<PhoneInput>` (country flag dropdown + AsYouType formatter)
+   instead of a plain `<Input type="tel">`. Country state from the
+   page seeds the dropdown.
+   File: `src/components/settings/user-settings.tsx`.
+2. **Timezone auto-detect** — covered in Wave 2.
+3. **Dropdown widths match trigger** — covered in Wave 2.
+
+### Bonus — public berth feed wired to replace NocoDB as source of truth
+
+Triggered by user prompt "ensure we are properly wired up to replace
+the NocoDB table as the source of truth for the berth map".
+
+**State before audit:**
+
+- API endpoints existed (`/api/public/berths`,
+  `/api/public/berths/[mooringNumber]`) — wiring fine.
+- `src/lib/services/public-berths.ts` mapped the response shape to
+  NocoDB-verbatim keys.
+- Tests passed (`tests/unit/services/public-berths.test.ts`).
+- **Map data was empty: 0 rows in `berth_map_data` against 234 berths
+  total (117 per port).** Without polygons the website map literally
+  has no shapes to render.
+
+**Action taken:**
+
+- Ran `pnpm tsx scripts/import-berths-from-nocodb.ts --apply
+--port-slug port-nimara` (after a clean dry-run). Result:
+  117 berths updated, 117 `berth_map_data` rows inserted.
+- Spot-checked the public API: `GET /api/public/berths` returns the
+  correct shape with `Map Data` populated, byte-for-byte identical
+  to NocoDB for berth A1 (`path`, `x`, `y`, `transform`, `fontSize`).
+
+**Field-parity gaps still present** (see Wave Bonus pending below).
+
+### Misc UI polish
+
+- **Berth Documents tab explainer** — added a one-paragraph header
+  explaining it's the spec PDF, not deal documents (with a pointer
+  to the Interests tab for prospect-linked docs).
+  File: `src/components/berths/berth-documents-tab.tsx`.
+
+---
+
+## 🟡 Pending — medium
+
+### Wave 4: currency formatting platform-wide
+
+- Build `<CurrencyInput>` shared component (formatted display, raw
+  number value). Replace raw `<Input type="number">` price spots in:
+  `berth-form.tsx` (price), `expense-form-dialog.tsx` (amount),
+  `invoices.tsx` (totals), client deal amounts on dossier / invoice.
+- Currency selector dropdown on expense form (NocoDB has no expense
+  currency field, so source from a curated supported-currency list:
+  USD / EUR / GBP / CAD / AUD / CHF / JPY / …). Replace the free-text
+  3-letter input.
+- Sweep for `${currency} ${amount}` string concatenations and replace
+  with `Intl.NumberFormat`.
+
+### Wave 5: configurable enum infrastructure
+
+We have a `system_settings` table with composite PK `(key, port_id)`
+and an `<SettingsManager>` admin page. Add a "Vocabularies" admin tab
+that exposes per-port vocabularies. Suggested keys grouped by domain:
+
+- `interest_temperature_levels` — replaces the hardcoded "HOT" badge.
+  Pill is rendered in `src/components/interests/interest-card.tsx`.
+- `berth_status_change_reasons` — list shown as quick-pick chips in
+  `<StatusChangeDialog>` (see `berth-detail-header.tsx`). Tied to the
+  prospect-picker concept (see Wave 7 below).
+- `berth_tenure_types` — replaces the static
+  `'permanent' | 'fixed_term'` validator union. Berths column is
+  `text`, so any value can land at the DB layer.
+- `expense_categories` — current hardcoded list at
+  `src/lib/constants.ts:EXPENSE_CATEGORIES`.
+- `document_types` — current hardcoded list at
+  `src/lib/constants.ts:DOCUMENT_TYPES`.
+- `interest_outcome_statuses` — already exist in schema enum, could
+  be overridable.
+- `berth_side_pontoon_options` / `berth_cleat_types` /
+  `berth_bollard_types` / `berth_access_options` — currently
+  hardcoded to NocoDB values. Worth making editable once a non-Port-
+  Nimara port appears with different infrastructure.
+
+**Open question (#1)**: see § Open Questions.
+
+### Wave 6: notes unification — aggregate-on-read
+
+User chose option 1 ("aggregate on read") from the brainstorm. The
+`listForClientAggregated` pattern in `notes.service.ts` (lines
+130–242) already unions a client's notes + interest notes + owned
+yacht notes into a single feed with `source` metadata.
+
+Symmetric extensions to add:
+
+- `listForYachtAggregated` — yacht own notes + owner client notes
+  - linked interest notes.
+- `listForCompanyAggregated` — company own notes + owned yacht notes
+  - linked interest notes.
+- `listForResidentialClientAggregated` — residential client notes
+  - residential interest notes.
+
+UI:
+
+- `<NotesList entityType="…">` should render the source-label badge
+  (already implemented for clients — copy the pattern).
+- Convert single-textarea spots to entry-list pattern: the
+  Companies overview tab has a `notes` textarea (from
+  `companies.notes` text column) AND a Notes tab with the threaded
+  `companyNotes` table. Drop the textarea in favor of the threaded
+  feed only. Same for residential interests.
+- Note for the schema fix-it list: `companyNotes` is missing
+  `updatedAt`. Service substitutes `createdAt` to keep the read shape
+  uniform — see `notes.service.ts:566`. Fix when convenient.
+
+### Wave 7: clients / yachts / companies misc
+
+Done in this session:
+
+- **Yacht flag** → CountryCombobox (Wave 1).
+- **End Membership** → "Remove from company" (Wave 1).
+- **Berth Documents tab** explainer paragraph.
+
+Pending:
+
+- **Status change modal — prospect picker**: when user changes berth
+  status to `under_offer` or `sold`, surface an interest/prospect
+  selector below the reason dropdown so the recorded reason can link
+  to a known deal. Tie into `interest_berths` so the link is
+  bidirectional. Depends on Wave 5
+  (`berth_status_change_reasons` vocabulary).
+- **Documents tagged with company** show up in main `/documents` view
+  with company tag — verify after the documents overhaul (Wave 11.B).
+
+### Wave 9 follow-up
+
+- **HOT/WARM/COLD admin-config** — covered by Wave 5
+  (`interest_temperature_levels`).
+- **Color-codes legend**: shipped as a popover. Optional polish: add
+  a one-time tooltip on first pageload so users discover it.
+
+### Wave 10 follow-up
+
+- **Photo upload picker bug**: Playwright captured a `[File chooser]`
+  modal when clicking "Upload photo," so the wiring works in headless
+  Chromium. User reported "doesn't open" on macOS — possibly a focus
+  / window issue or a content-blocking extension. Need a real-machine
+  repro to diagnose. The hidden `<input type="file" ref={fileInputRef}>`
+  - `fileInputRef.current?.click()` wiring is at
+    `user-settings.tsx:247-258`.
+- **Display name + first / last name fields** — current schema only
+  has `displayName`. Adding first/last requires a Drizzle migration on
+  `users` or `user_profiles` plus migration of existing data (split
+  on first space). **Open question (#3)**: see § Open Questions.
+- **Notification preferences placement** — settings vs notifications
+  page. Today notification toggles live on the user-settings page; a
+  dedicated `/notifications/preferences` page also exists. **Open
+  question (#2)**: see § Open Questions.
+
+### Wave Bonus follow-up — public berth feed field parity
+
+Map data is now wired. Field gaps the website _might_ consume but we
+don't expose:
+
+| NocoDB field                 | Currently in PublicBerth? | DB has it?                         | Notes                                                       |
+| ---------------------------- | ------------------------- | ---------------------------------- | ----------------------------------------------------------- |
+| `Price`                      | ❌                        | ✅ `berths.price`                  | Pricing-public is a policy decision. **Open question (#4)** |
+| `Berth Approved`             | ❌                        | ✅ `berths.berth_approved`         | Boolean. Often used to gate "Sold" display                  |
+| `Water Depth`                | ❌                        | ✅ `berths.water_depth`            | Sometimes shown in tooltip                                  |
+| `Width Is Minimum`           | ❌                        | ✅ `berths.width_is_minimum`       | Modifier for "Width" display                                |
+| `Water Depth Is Minimum`     | ❌                        | ✅ `berths.water_depth_is_minimum` | ditto                                                       |
+| `Length (Metric)`            | ❌                        | ✅ `berths.length_m`               | Derivable. Website may consume                              |
+| `Width (Metric)`             | ❌                        | ✅ `berths.width_m`                | ditto                                                       |
+| `Draft (Metric)`             | ❌                        | ✅ `berths.draft_m`                | ditto                                                       |
+| `Water Depth (Metric)`       | ❌                        | ✅ `berths.water_depth_m`          | ditto                                                       |
+| `Nominal Boat Size (Metric)` | ❌                        | ✅ `berths.nominal_boat_size_m`    | ditto                                                       |
+| `CreatedAt` / `UpdatedAt`    | ❌                        | ✅ timestamps                      | Cache invalidation hints                                    |
+| `Interests` (count)          | ❌                        | derivable                          | Probably internal-only                                      |
+| `Interested Parties` (count) | ❌                        | derivable                          | Probably internal-only                                      |
+
+**Plan once questions are answered:** Add the chosen fields to
+`PublicBerth` interface in `src/lib/services/public-berths.ts`, the
+`toPublicBerth()` mapper, and the test fixtures. Trivial; gated only
+by which fields the website actually uses.
+
+**Other public-feed concerns to flag**:
+
+- **No archive flag**: when a berth is retired the public feed will
+  still serve it. Need a `berths.archived_at` column + filter on the
+  route. Plan §4.5 hinted at this. Not urgent.
+- **CRM-edit drift vs re-imports**: now that reps can edit berth
+  fields (Wave 3), running the import script will skip-edited those
+  rows (`updated_at > last_imported_at`) — that's the right design,
+  but it means once cutover happens the website **must** call CRM
+  `/api/public/berths`, never NocoDB. Coordinate this in the website
+  repo. Useful guard already exists: `/api/public/health`.
+- **Cache TTL: 5 min**: when a CRM rep marks a berth `sold`, the
+  public website serves "Available" for up to 5 minutes due to
+  `s-maxage=300`. Acceptable for marketing; bump if needed.
+- **Health endpoint shape**: `/api/public/health` currently returns
+  `{status, timestamp}` but `CLAUDE.md` claims `{env, appUrl}`. One
+  of them is stale; the website may expect either shape. Not blocking
+  but worth aligning.
+
+---
+
+## 🔴 Pending — large (group-discussion items, Wave 11)
+
+### A. Manual client form expansion
+
+User wants "New Client" to support assigning yachts / companies /
+berths inline (without leaving the form), plus a mini-recommender for
+picking a berth at create time.
+
+Scope:
+
+- "Existing yacht / new yacht" picker.
+- "Existing company / new company" picker.
+- "Open an interest with this client" affordance that wires through
+  `interest_berths` and the recommender.
+- Make sure all standard client modal fields (nationality / source /
+  preferred contact / timezone / tags) remain present.
+
+Multi-component composition with a lot of cross-entity plumbing.
+Estimate fully before starting (likely 2–3 days).
+
+### B. Documents section overhaul
+
+User wants:
+
+- Folders (create / delete / nested).
+- Sort + filter (by date, type, owner).
+- Wider file-type allowlist (PDF + Office + image is current; expand).
+- "Documents in progress" filter (contracts / EOIs awaiting signature,
+  things uploaded but unparsed).
+- Drop or rename the "Signature-based only" pill — confusing copy.
+- "Expired" tab admin-configurable visibility.
+- Type-filter dropdown reflects actual types in use (vs the full
+  hardcoded list).
+
+Refactor of `documents.service.ts` plus a new folders schema
+(`document_folders` table with port-scoped tree).
+
+### C. Reports system
+
+User asked for:
+
+- Defined report types (Pipeline summary / Revenue / Activity log /
+  Berth occupancy) with documented data shape per type.
+- Test fixtures for visual QA.
+- Admin "report templates" with field-level checkboxes letting an
+  admin compose a custom report shape (toggles for each available
+  data field).
+
+Infra exists (`/api/v1/reports`) but templates are stubs. A proper
+templating system + per-template field selection adds a few days.
+
+### D. Receipts inline in expense PDF
+
+User confirmed: image receipts render inline beneath each expense row,
+**and** PDF receipts also render inline (one page each). pdfme
+(already used for EOI) handles both — inline images via the renderer,
+PDF pages via `pdf-lib.copyPages`. Depends on Wave 8 expense form work.
+
+### E. Country / Nationality split on Client form
+
+Client schema has only `nationalityIso`. User wants:
+
+- New `country_iso` column for _country of residence_ (visible
+  / primary).
+- Keep `nationality_iso` as an _optional_ secondary field.
+
+Requires:
+
+- Drizzle migration (`alter table clients add column country_iso text`).
+- Migrate existing data: copy `nationality_iso → country_iso` for
+  every client (current value is more often country of residence in
+  practice).
+- Update API validators (`clients.ts`).
+- Update client form UI: primary "Country" CountryCombobox, secondary
+  collapsible "Nationality" row.
+- Same for residential clients (parallel schema).
+
+### F. Inquiry triage (legacy spec carryover)
+
+Per project memory and the "deferred" list at the top of
+`today-2026-05-08.md`: inquiry triage was explicitly deferred. Tied
+into the inquiry routing settings (`inquiry_notification_recipients`,
+`inquiry_contact_email`, `residential_notification_recipients` —
+already in `system_settings`). Pick this back up when ready to
+auto-classify website inquiries.
+
+### G. Per-port email branding
+
+Also in the deferred list. Templates and settings keys exist
+(per memory note); the admin UI for editing per-port email branding
+overrides remains.
+
+---
+
+## ✅ Decisions log — 2026-05-09
+
+All 11 open questions answered. Implementation implications inline.
+
+1. **Vocabularies admin layout (Wave 5)** → **New `/admin/vocabularies`
+   page, grouped by domain, admin-only.** User considered exposing to
+   non-admins (since reps use them daily) but settled on admin-only as
+   the safer default for now. Implementation: new top-level admin
+   route + page, reuse `system_settings` `(key, port_id)` composite
+   PK. Each vocabulary key gets its own card section (interest temps,
+   status-change reasons, tenure types, expense categories, document
+   types, etc.).
+2. **Notification preferences placement (Wave 10)** → **Collapse to
+   user-settings only.** Keep `/notifications/preferences` as a
+   server-side redirect to the user-settings notifications panel for
+   back-compat links.
+3. **Display name vs first/last (Wave 10)** → **Add `first_name` and
+   `last_name` columns.** Don't worry about migrations during dev (we
+   can iterate freely), but write the migration carefully so it
+   applies cleanly when we eventually deploy. Keep `display_name` as
+   a derived/optional override.
+4. **Public-feed `Price` exposure (Bonus)** → **No — keep Price
+   internal.** Don't add to PublicBerth payload.
+5. **Public-feed remaining fields (Bonus)** → **Yes, add all.** Add
+   Berth Approved, Water Depth, Width Is Minimum, Water Depth Is
+   Minimum, all four metric variants, plus CreatedAt/UpdatedAt to
+   PublicBerth + mapper + tests. User noted "not sure if we'll use
+   all of them but best to keep them in" — verbatim NocoDB parity.
+6. **Website cutover plan (Bonus)** → **Double-write transition
+   window.** Keep both feeds live, write to both for the transition
+   period, then decommission NocoDB. Coordinate with website repo
+   (`CRM_PUBLIC_URL`).
+7. **Status-change modal → prospect link (Wave 7)** → **Force
+   interest pick + auto-create primary `interest_berths` row.**
+   When status moves to `under_offer` or `sold`, the modal surfaces
+   an interest selector below the reason dropdown. Picking an
+   interest creates an `interest_berths` row with `is_primary=true`
+   if one doesn't already exist for that pair. Depends on Wave 5
+   `berth_status_change_reasons` vocabulary.
+8. **Trip label on expenses (Wave 8)** → **Combobox: free-text on
+   first entry, dropdown of existing labels on subsequent entries.**
+   No new entity. Source the dropdown from
+   `SELECT DISTINCT trip_label FROM expenses WHERE port_id=?`
+   ordered by recency. UI is a `<Combobox>` with "Create
+   '<typed value>'" affordance.
+9. **Documents folders (Wave 11.B)** → **Per-port, unlimited
+   nesting depth — but render carefully.** User wants flexibility;
+   we owe a UI design that handles deep trees gracefully (likely
+   collapsed-by-default with a breadcrumb header inside the folder
+   view rather than always-expanded sidebar tree).
+10. **Berth Documents tab (Wave 1 carryover)** → **Split into two
+    tabs: "Spec" (versioned spec PDF) and "Deal Documents"
+    (aggregated EOIs/contracts from interests on this berth).**
+    Permission scoping: deal docs only show entries the viewer can
+    already see via the linked interest.
+11. **Mooring type re-import** → ✅ **Verified.** All 117 records
+    have `mooring_type` populated post-import (e.g. "Side Pier / Med
+    Mooring"). No action needed.
+
+---
+
+## File-pointer cheat sheet
+
+### Berth-related
+
+| Concern                            | File(s)                                              |
+| ---------------------------------- | ---------------------------------------------------- |
+| Canonical berth enums              | `src/lib/constants.ts` (search `BERTH_`)             |
+| Berth list ordering SQL            | `src/lib/services/berths.service.ts:69-72`           |
+| Berth detail inline edit           | `src/components/berths/berth-tabs.tsx`               |
+| Berth modal form                   | `src/components/berths/berth-form.tsx`               |
+| Berth area filter                  | `src/components/berths/berth-filters.tsx`            |
+| Berth detail header / status modal | `src/components/berths/berth-detail-header.tsx:90`   |
+| Berth Documents tab                | `src/components/berths/berth-documents-tab.tsx`      |
+| Berth list query + sort            | `src/lib/services/berths.service.ts:25-140`          |
+| Berth import script                | `scripts/import-berths-from-nocodb.ts`               |
+| Berth import service / parsers     | `src/lib/services/berth-import.ts`                   |
+| Public berth API route             | `src/app/api/public/berths/route.ts`                 |
+| Public berth single route          | `src/app/api/public/berths/[mooringNumber]/route.ts` |
+| Public berth mapper                | `src/lib/services/public-berths.ts`                  |
+| Public berth tests                 | `tests/unit/services/public-berths.test.ts`          |
+| Berth seed snapshot                | `src/lib/db/seed-data/berths.json`                   |
+| Berth schema                       | `src/lib/db/schema/berths.ts` (incl. `berthMapData`) |
+
+### Other domains
+
+| Concern                           | File(s)                                                                                |
+| --------------------------------- | -------------------------------------------------------------------------------------- |
+| Interest stage colors / legend    | `src/components/interests/stage-legend.tsx` + `src/lib/constants.ts:STAGE_DOT`         |
+| Mobile kanban toggle / fallback   | `src/components/interests/interest-list.tsx`                                           |
+| Country / timezone autoset        | `src/components/clients/client-form.tsx` + `src/components/settings/user-settings.tsx` |
+| Phone input                       | `src/components/shared/phone-input.tsx`                                                |
+| Country combobox + scroll patch   | `src/components/shared/country-combobox.tsx` + `src/components/ui/command.tsx`         |
+| Sidebar Umami gate                | `src/components/layout/sidebar.tsx` (search `umamiRequired`)                           |
+| Mobile More-sheet                 | `src/components/layout/mobile/more-sheet.tsx`                                          |
+| Notes service (aggregate-on-read) | `src/lib/services/notes.service.ts:130-242`                                            |
+| Notes UI                          | `src/components/shared/notes-list.tsx`                                                 |
+| Settings manager (admin)          | `src/components/admin/settings/settings-manager.tsx`                                   |
+| User settings page                | `src/components/settings/user-settings.tsx`                                            |
+| Status change dialog              | `src/components/berths/berth-detail-header.tsx:90`                                     |
+| Companies members tab             | `src/components/companies/company-members-tab.tsx`                                     |
+| Yacht form                        | `src/components/yachts/yacht-form.tsx`                                                 |
+| Client form                       | `src/components/clients/client-form.tsx`                                               |
+
+### Infrastructure
+
+| Concern                                     | File(s)                                       |
+| ------------------------------------------- | --------------------------------------------- |
+| Drizzle config / migrations                 | `drizzle.config.ts`, `src/lib/db/migrations/` |
+| `system_settings` table                     | `src/lib/db/schema/system.ts:128-147`         |
+| Permissions / `withAuth` / `withPermission` | `src/lib/api/helpers.ts`                      |
+| Body parsing (always use `parseBody`)       | `src/lib/api/route-helpers.ts`                |
+| Storage backend abstraction                 | `src/lib/storage/`                            |
+| Logger (pino)                               | `src/lib/logger.ts`                           |
+
+---
+
+## Resuming in a fresh session
+
+When you open a new chat, paste this **prompt** to pick up where this
+session ended:
+
+```
+I'm resuming the 2026-05-08 visual audit. Read
+docs/AUDIT-FOLLOWUPS.md first — it has every completed item, every
+pending item, and every open question. Then:
+
+1. Skim the "Quick status snapshot" table at the top so you know
+   what's done.
+2. Read the "Open questions for the user" list and ask me question
+   #N where N is whichever I'll answer first this turn.
+3. Wait for my answers; don't start implementing until I confirm.
+
+Key invariants:
+ - Notes unification model: aggregate-on-read.
+ - Berth dropdown values: NocoDB SingleSelect canon, sourced from
+   src/lib/constants.ts (BERTH_*_OPTIONS / _TYPES).
+ - Power Capacity & Voltage stay numeric inputs; Bow Facing is a
+   constrained 4-value dropdown despite being SingleLineText in
+   NocoDB.
+ - linkedUnit on EditableSpec auto-fills the metric column on save.
+ - system_settings (key, port_id) is the configuration pattern.
+ - NocoDB MCP is connected via ~/.claude.json — Berths schema +
+   records can be pulled live.
+ - Public berth feed (/api/public/berths) now serves Map Data; 117
+   berth_map_data rows backfilled in this session.
+ - Tests: 1185/1185 passing; tsc clean.
+
+The git working tree has 23 modified files + 2 new (no commits yet).
+Don't commit anything until I say so.
+```
+
+### Resume commands (cheat sheet)
+
+```bash
+cd /Users/matt/Repos/new-pn-crm
+pnpm dev                                 # Turbopack dev (~1s boot)
+
+# Tests
+pnpm exec vitest run                     # Unit + integration (~7s)
+pnpm exec tsc --noEmit                   # Type check
+pnpm exec playwright test --project=smoke   # Smoke (~10min)
+
+# NocoDB import (for new berth pulls)
+pnpm tsx scripts/import-berths-from-nocodb.ts --dry-run --port-slug port-nimara
+pnpm tsx scripts/import-berths-from-nocodb.ts --apply --port-slug port-nimara
+
+# DB inspect
+PGPASSWORD=changeme psql -h localhost -p 5434 -U crm -d port_nimara_crm
+
+# Public-feed sanity check
+curl -s http://localhost:3000/api/public/berths | jq '.pageInfo'
+curl -s http://localhost:3000/api/public/berths/A1 | jq '.'
+```
+
+### Verification checklist before committing this session's work
+
+- [ ] `pnpm exec vitest run` — 1185/1185 pass.
+- [ ] `pnpm exec tsc --noEmit` — clean.
+- [ ] `pnpm exec playwright test --project=smoke` — passes.
+- [ ] Manual: open `/port-nimara/berths`, confirm sort is A1, A2,
+      A3 … A10, A11 (not lex order).
+- [ ] Manual: open a berth detail page, confirm the dock chip reads
+      e.g. "A Dock", and the Bow Facing / Side Pontoon / Cleat fields
+      render as `<Select>` not `<Input>`.
+- [ ] Manual: pick a country in the user-settings page and confirm
+      timezone auto-fills if empty; also confirm the country dropdown
+      scrolls with mousewheel on macOS.
+- [ ] Manual: check the mobile More-sheet has no "Inbox" entry, and
+      "Notification preferences" deep-links to the correct page.
+- [ ] Manual: open `/api/public/berths` in the browser and search for
+      `Map Data` in the response — every row should have it.
+
+---
+
+## Misc tracking notes
+
+- **Backups**: `~/.claude.json.bak.<timestamp>` exists from when the
+  NocoDB MCP was added. Delete after a session or two if everything's
+  stable.
+- **Turbopack flip**: `next.config.ts` has no custom `webpack()` hook
+  so reverting `pnpm dev` to plain `next dev` is one line if needed.
+  Default is now `--turbopack`.
+- **Database integrity follow-ups** (separate audit, dated 20:42):
+  11 findings (5 critical / 6 important). Logged in
+  `.remember/today-2026-05-08.md`. Cross-cuts the work here in two
+  spots: (1) `upsertInterestBerth` race could affect the berth
+  recommender once it's wired into the manual client form (Wave 11.A);
+  (2) `system_settings` `ON DELETE NO ACTION` will need addressing
+  before any port-deletion flow ships.

docs/AUDIT-PARKED-QUESTIONS.md

@@ -0,0 +1,212 @@
+# Parked questions — needs product / business / design decision
+
+Items from the 33-agent audit that I deliberately did NOT fix automatically, because they need a call from you (or someone in product / legal / design) before code can be written. Each entry: the finding, why it's parked, and the proposed options.
+
+Numbered to match the tiers in `AUDIT-TRIAGE.md`.
+
+---
+
+## P-0.1 — Migration runner: which approach?
+
+**Finding.** `pnpm db:push` silently skips `CREATE INDEX CONCURRENTLY` and `NULLS NOT DISTINCT` constraints, plus the `berths.current_pdf_version_id` circular FK. Production is running without 6 composite indexes from migration 0052.
+
+**Why parked.** Three viable approaches:
+
+- **Drizzle's built-in `migrate()`** — simplest, but doesn't support `CREATE INDEX CONCURRENTLY` (the kit wraps every migration in a transaction, and CONCURRENTLY can't run inside one).
+- **A custom tsx script** that reads `0001*.sql` … `0056*.sql` in order, splits on `--> statement-breakpoint`, runs each statement, special-cases CONCURRENTLY by running it outside a tx, tracks state in a `__drizzle_migrations` table.
+- **Adopt a third-party migrator** (graphile-migrate, dbmate, pg-migrate). Best ergonomics, biggest dependency to take on.
+
+**Question.** Which one do you want? If you don't know, my recommendation is **custom tsx script** — keeps the dependency surface tight and matches the rest of the platform's "write a script for it" pattern.
+
+---
+
+## P-0.4 — Resolve-identifier hit-path still echoes real email
+
+**Finding.** Rate-limit + synthetic-miss are in, but on a hit the endpoint still returns the user's canonical email. A guessable-username window still leaks.
+
+**Why parked.** The real fix is to delete the endpoint entirely and have the login form POST `{identifier, password}` to a server-side proxy that resolves + calls Better Auth in one round-trip, never returning the email. That's a noticeable refactor to the login page and possibly the portal-login page too.
+
+**Question.** Do I do the proxy refactor (~30 min) or keep the current rate-limited shape and accept the residual leak?
+
+---
+
+## P-0.5 — Orphan-blob windows in 9+ services
+
+**Finding.** Every `storage.put` runs outside the `db.insert(files)` tx in `documents`, `brochures`, `invoices`, `gdpr-export`, `backup`, `berth-pdf`, `external-eoi`, `document-templates`, `reports`. A comment in one site claims a "reaper handles it" — no reaper exists.
+
+**Why parked.** Two valid patterns, both meaningful work:
+
+- **Compensating delete** — wrap each `storage.put` in a try/catch and `storage.delete()` on tx failure.
+- **Saga / 2-phase** — write to a `pending_blobs` table inside the tx, async-confirm after the tx commits, async-reaper for orphans.
+
+Compensating-delete is faster to ship but doesn't catch process-crash gaps. Saga is more robust but is a bigger change.
+
+**Question.** Which pattern? Recommendation: compensating-delete for now + a simple `cron` reaper that lists all blobs not referenced by any `files`/`berth_pdf_versions`/etc. row and deletes them after a grace period.
+
+---
+
+## P-1.1 — GDPR Article-15 export completeness
+
+**Finding.** `gdpr-bundle-builder.ts` is missing ~10 PII-bearing tables — portal_users, email_threads/messages, document_sends, reminders, files, scratchpadNotes, client_merge_log, contact_log, website_submissions, form_submissions.
+
+**Why parked.** Each table needs (a) FK verification that "row belongs to this client" is unambiguous, (b) whether port-isolation must be enforced, (c) whether to include verbatim PII (email bodies, message contents) or redacted versions. This is a careful per-table audit that benefits from someone who knows the data model intimately.
+
+**Question.** Want me to do a per-table table-by-table follow-up (estimated ~45 min) once you confirm the redaction policy? Or have legal review the scope first?
+
+---
+
+## P-1.2 — Right-to-be-forgotten doesn't actually erase
+
+**Finding.** `client-hard-delete.service.ts` nullifies FKs but verbatim PII survives in `email_messages.body_html`, `files`, `document_sends.recipient_email`.
+
+**Why parked.** **This is a legal decision, not a coding one.** Some jurisdictions (notably France) require true erasure even of email-body content; others accept anonymization. The fix is mechanical once you decide the policy: a `wipeClientPii(clientId)` helper that overwrites every PII column with a tombstone string. But the scope (which fields, which timeline, which audit trail) is yours / legal's.
+
+**Question.** What's the erasure policy? Anonymize (preserve audit trail) or truly delete (loses business records)?
+
+---
+
+## P-1.3 — Activation / reset tokens travel in `?token=` query strings
+
+**Finding.** Browser history, proxy logs, Referer header all see the token.
+
+**Why parked.** Fix is a redesign of the URL scheme — switch to `#token=…` (fragment) or POST-on-load. Both work but require coordinated changes to email templates + the landing pages + Better Auth integration. Estimated 30-45 min.
+
+**Question.** Want me to do the fragment-based redesign?
+
+---
+
+## P-2.1 — `pipelineValueUsd` sums mixed currencies as USD
+
+**Finding.** The dashboard tile labelled "Pipeline Value" sums berth prices in their native currencies but renders the total as USD.
+
+**Why parked.** Three valid UX options:
+
+- **Convert at display time** — fetch each price, convert to port-default-currency via `currency.service`, sum the converted values. Today's rates introduce drift relative to historical reports.
+- **Show as port-default-currency totalled** — the dashboard tile labels it as the port's own currency; honest about ambiguity.
+- **Show "mixed (X USD, Y EUR, Z GBP)"** — explicit, prevents misreading, but uglier.
+
+**Question.** Which display do you want? My recommendation is **option 2** (show port-default-currency, convert at display) — it's the least visually noisy and lines up with what most CRMs do.
+
+---
+
+## P-2.5 — "Active interest" means 4 different things
+
+**Finding.** Dashboard tiles use `outcome IS NULL OR 'won'`, kanban uses `archivedAt NULL` only (lost cards visible), hot deals uses `outcome IS NULL` (excludes won), PDF reports use `archivedAt NULL` only.
+
+**Why parked.** Need a canonical definition. Recommendation: **active = `archivedAt IS NULL AND outcome IS NULL`** (not yet won, not yet lost, not yet cancelled, not yet archived). But that demotes won deals out of "active" everywhere — affects the kanban "won" column and the dashboard "active deals" tile.
+
+**Question.** Confirm the canonical definition, then I extract an `activeInterestsWhere(portId)` helper and route every site through it.
+
+---
+
+## P-2.6 — Occupancy rate: berths.status vs berth_reservations
+
+**Finding.** KPI tile + PDF use `berths.status` ("occupied"/"available"/etc). Analytics timeline uses `berth_reservations`. Same dashboard, two different numbers.
+
+**Why parked.** Need to know which is the source of truth. Probably `berth_reservations` (richer; supports timeline), but switching the KPI tile changes the displayed number for every port.
+
+**Question.** Which is canonical? I'll switch the other to match.
+
+---
+
+## P-2.7 — Revenue PDF unweighted vs dashboard weighted
+
+**Finding.** Revenue PDF shows gross berth prices per stage. Dashboard revenue-forecast tile multiplies by `pipeline_weights`. They will never reconcile.
+
+**Why parked.** Need PM call on what "Revenue" means in each context. The PDF is probably a board / investor doc and should match dashboard, but maybe they want both.
+
+**Question.** Make the PDF match the dashboard (weighted)? Or leave divergent and label them differently?
+
+---
+
+## P-3.1 — "Interest" / "lead" / "prospect" / "deal" used interchangeably
+
+**Finding.** All four nouns appear in client-facing UI. `berth-detail-header.tsx` literally parenthesises one as a synonym ("the prospect (interest)"). `berth-tabs.tsx` has a "Deal Documents" tab + `/deal-documents` URL path.
+
+**Why parked.** Need a canonical noun. Without one I'd be guessing; with one I can do a codemod across the platform.
+
+**Question.** Which one is canonical? Recommendation: **interest** (matches schema + URL + most code). Then everything else becomes a deprecated alias.
+
+---
+
+## P-3.3 — 16 `window.confirm()` sites for destructive flows
+
+**Finding.** Cancel signing envelope, delete files, archive interest/company/yacht, etc. all use the native browser dialog.
+
+**Why parked.** Mechanical fix once you confirm: each site swaps `window.confirm()` for `<AlertDialog>` from `@/components/ui/alert-dialog`. But there are 16 of them; ~5 min each.
+
+**Question.** OK to do the sweep automatically with the same dialog copy + visual treatment? Or do you want bespoke copy per surface?
+
+---
+
+## P-3.4 — Signing-status labels diverge across 5 surfaces
+
+**Finding.** Hub list, interest-tab, SigningProgress, notification-digest, realtime-toast all use different strings for the same document state.
+
+**Why parked.** Need one canonical mapping. I drafted `PORTAL_SIGNING_LABELS` for the portal but the CRM side has different needs (more granular for reps).
+
+**Question.** Want me to extract a shared `signingStatusLabel()` and route every site through it? If yes, I need a confirmed label map.
+
+---
+
+## P-3.5 — 6× "Save" button variants
+
+**Finding.** "Save", "Save Changes", "Save changes", "Update", "Apply" — plus "Saving..." vs "Saving…".
+
+**Why parked.** Mechanical sweep once you confirm the canonical text. Recommendation: **"Save changes"** for edits, **"Create X"** for new entities, **"Saving…"** (Unicode ellipsis) for the loading state. Trivial codemod but it touches 30+ files.
+
+**Question.** OK to do the sweep with that policy?
+
+---
+
+## P-3.6 — Live Documenso template missing `Berth Range` field
+
+**Finding.** The CRM sends a `Berth Range` form value through `buildDocumensoPayload`, but the live template at Documenso doesn't have that field — Documenso silently drops unknown formValues. Every multi-berth EOI ships with only the primary mooring.
+
+**Why parked.** **Not code — Documenso admin action.** Someone needs to log into the Documenso instance and add a `Berth Range` text field to template id 8. The CRM is ready.
+
+**Question.** Who has Documenso admin access? Can they add the field?
+
+---
+
+## P-4.5 — "Convert to client" prefill qs params unused
+
+**Finding.** The inquiry-inbox triage flow writes `prefill_name/email/phone/inquiry_id/source` query-string params. No consumer reads them. The flow eagerly flips the inquiry to "converted" then drops the operator on a blank form, losing the inquiry_id linkage forever.
+
+**Why parked.** Fix is a wire-up: the create-client form's `useEffect` reads searchParams and hydrates initial values. But it also has to push the `inquiry_id` into the resulting client's `metadata` so the linkage survives. Not difficult; needs ~30 min and design review on what the linkage looks like.
+
+**Question.** Want me to wire it up with the inquiry_id stored on `clients.metadata.source_inquiry_id`?
+
+---
+
+## P-5.1 — `handleDocumentCompleted` TOCTTOU
+
+**Finding.** Two concurrent retries can both pass the idempotency gate, both write the signed PDF blob, both insert duplicate files rows. Webhook + poll-worker race specifically.
+
+**Why parked.** Fix is a `SELECT … FOR UPDATE` on the documents row inside the handler. Mechanical but invasive — touches the hottest path in the signing flow. I want to test before shipping, and that needs a real Documenso webhook replay.
+
+**Question.** OK to ship the FOR UPDATE without a replay test, relying on existing vitest? Or hold until you can replay?
+
+---
+
+## P-5.2 — Zero BullMQ `jobId` usage repo-wide
+
+**Finding.** Every `queue.add` is unkeyed; any double-fire creates a duplicate job. The audit found this is the most pervasive concurrency hazard in the codebase.
+
+**Why parked.** Fix is mechanical: pass a deterministic `jobId` to every `queue.add` call. But "deterministic" varies by surface (webhook deliveries should use the delivery row id, notifications should use a hash of the dedupeKey, etc.). ~20 sites to touch.
+
+**Question.** Want me to do the sweep with per-surface jobId conventions, or batch by surface (webhooks first, then notifications, etc.)?
+
+---
+
+## P-6.2 — Recharts in initial bundle (~80-150KB)
+
+**Finding.** Every dashboard chart imports recharts statically via `widget-registry.tsx`. Initial-page-load bundle includes recharts even if the user has all chart widgets disabled.
+
+**Why parked.** Fix is straightforward (dynamic import each chart widget), but the widget-registry is hot-pathed by the dashboard renderer and by the widget picker UI. Touching it has surface area.
+
+**Question.** OK to ship a `next/dynamic` lazy-import for each chart widget? Adds a loading skeleton flash but kills the bundle bloat.
+
+---
+
+_Everything in `AUDIT-TRIAGE.md` Tier 8 is already shipped. Everything not listed in this file has been fixed without parking — see the commit log on `feat/documents-folders`._

docs/AUDIT-PROGRESS-2026-05-15.md

@@ -0,0 +1,83 @@
+# Audit Progress Report — 2026-05-15
+
+Companion to `docs/audit-2026-05-15.md` (findings) and `docs/AUDIT-CATALOG.md` (320+ checks). Tracks what was actually executed in this session and what remains.
+
+## Fixed and verified (10 of 13 known issues from A1-A20)
+
+| ID  | Fix                                                                                                           | Verified                 |
+| --- | ------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| A1  | Dashboard activity feed filters out `permission_denied` entries                                               | ✅ code-reviewed         |
+| A2  | New `LEGACY_STAGE_REMAP` + `canonicalizeStage` / `stageLabelFor` helpers; activity-feed maps legacy → 7-stage | ✅ code-reviewed         |
+| A4  | Client form prunes empty contact rows before zod validation                                                   | ✅ Playwright end-to-end |
+| A6  | file-preview-dialog gets `sr-only` DialogDescription                                                          | ✅ code-reviewed         |
+| A8  | Migration 0066 normalizes legacy `statusOverrideMode = 'auto'` → NULL                                         | ✅ migration written     |
+| A9  | Catch-up wizard derives stage from berth status (under_offer → eoi, sold → contract) via stageOverride state  | ✅ code-reviewed         |
+| A16 | File upload route coerces FormData null → undefined before zod                                                | ✅ Playwright (201 OK)   |
+| A17 | New `/api/v1/me/ports` endpoint; `apiFetch` uses it as the bootstrap resolver                                 | ✅ Playwright (200 OK)   |
+| A19 | F27 same-stage write returns 204 No Content via STAGE_NOOP sentinel                                           | ✅ Playwright (204)      |
+| A20 | OwnerPicker surfaces "Client / Company" hint chip on trigger when no value set                                | ✅ code-reviewed         |
+| A18 | Closed as not-a-bug: `/users` doesn't exist (true 404); `/admin/audit` exists and 403s correctly              | ✅ analysis              |
+| A3  | **Deferred** — dev-only react-grab CSP noise, cosmetic                                                        | ⏭️ skipped               |
+| A5  | **Deferred** — Socket.IO dev noise, requires sidecar service setup                                            | ⏭️ skipped               |
+
+## Legacy stage enum hunt (L-001 done, L-002-L-020 partially)
+
+| ID    | Result                                                                                                                                                    |
+| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| L-001 | Grepped entire `src/` — found real bugs in `clients.service.ts` and `berth-recommender.service.ts` rank tables (every modern interest got rank 0) — fixed |
+| L-002 | Audit log diff display only shows field names (not values) — clean                                                                                        |
+| L-003 | Activity feed: A2 fix covers this                                                                                                                         |
+| L-004 | Email templates: notification-digest.tsx labels `eoi_signed` etc. as notification TYPE (event), not pipeline stage — OK                                   |
+| L-005 | Documenso payload: no stage refs in `buildDocumensoPayload`                                                                                               |
+| L-006 | Public berths API: status enum is `available/under_offer/sold` — independent of pipeline stages — OK                                                      |
+| L-007 | Webhook payloads: read-time mapping via `stageLabelFor` recommended for downstream subscribers (not blocking)                                             |
+| L-008 | Analytics SQL: spot-checked the pipeline-funnel query — uses modern 7-stage enum only ✅                                                                  |
+| L-012 | Seed data: confirmed migrated in `seed-synthetic-data.ts` ✅                                                                                              |
+| L-014 | Same as A8 — fixed via migration 0066                                                                                                                     |
+| L-015 | Outcome enum: confirmed `won` + `lost_*` only — no legacy `completed`                                                                                     |
+| L-019 | Doc-status sub-states: `pending/sent/signed/declined/voided` — consistent ✅                                                                              |
+| —     | Stale comment refs to `deposit_10pct` in schema (clients, financial, users) — all updated to modern copy                                                  |
+
+## Routes correctness (R-001..R-030 — partial)
+
+- R-001 — 13 main `/[portSlug]/*` routes return 200 for super-admin ✅
+- R-002 — sales-agent: confirmed admin nav hidden + permission gating from earlier audit ✅
+- R-004 — cross-port deep-link to unknown UUID: returns 200 with `DetailNotFound` rendered (F17) ✅
+- R-008 — mooring URL canonicalization: `A1`, `a1`, `A%201`, `A001`, `ZZ999` all return 200 (Next renders the page; data fetch surfaces 404 in-page if needed)
+- R-005, R-006, R-009, R-010, R-011, R-013-R-022 — ❓ unchecked
+- R-007 — hard-deleted berth A1 in port-amador: route page renders 200, in-page state is the `DetailNotFound` ✅
+
+## What's NOT done
+
+These remain unchecked from the catalog:
+
+- **U-001..U-100 UX consistency sweep** — partial (catch-up wizard tested, OwnerPicker tested). Empty states, form design, tables/lists/filters, badges, modals, mobile UX — needs dedicated session.
+- **W-001..W-052 sales workflows** — happy path (W-001) NOT walked end-to-end. Reservations, invoices, EOI signing pathway, contract signing, refund handling, GDPR export, etc. all unchecked beyond earlier audits.
+- **AD-001..AD-060 admin workflows** — only sampled (tag creation, audit log viewing). Role create, invite roundtrip, custom fields retrofit, brochures, per-berth PDFs, NocoDB import, CSV import — unchecked.
+- **MT-01..MT-11 multi-tenancy** — only the recommender + entry-point checks confirmed earlier. Defense-in-depth port_id filters on every join — sample-checked.
+- **S-01..S-30 security** — only items previously verified (rate-limit, XSS in client name, magic-byte verification). SQL injection, CSRF, SSRF, privilege escalation, session fixation, CSP headers — unchecked.
+- **RT-01..RT-09 realtime** — A5 deferred; nothing tested.
+- **P-01..P-14 performance** — nothing tested.
+- **D-01..D-22 documents/files** — partial (upload at root verified after A16 fix).
+- **AU-01..AU-14 audit log surface** — only auto-emit verified.
+- **EM-01..EM-19 email** — nothing tested.
+- **IN-01..IN-29 integrations** — nothing new tested.
+- **SC-01..SC-15 schema** — nothing tested beyond what existing migrations confirm.
+- **L-1..L-08 i18n/l10n** — nothing tested.
+- **BR-01..BR-07 browser/device** — only Chrome verified.
+- **B-01..B-22 behavioral correctness** — partial.
+- **DC-01..DC-05 data clean-up** — A8 done; others unchecked.
+- **CI-01..CI-13 CI/dev experience** — tsc/lint/vitest verified per commit; Playwright projects not run; Docker build not tested.
+
+## Bottom line
+
+11 of the 13 known issues from yesterday's sweep are fixed and pushed. The biggest discovered fix was the legacy-stage rank tables in clients.service + berth-recommender that were silently broken for every post-9→7-refactor interest. Two dev-only issues (A3, A5) deferred.
+
+Remaining catalog coverage requires multiple dedicated sessions — there are 300+ unique checks still in `AUDIT-CATALOG.md`. The catalog is the to-do list; pick the next slice you want me to take.
+
+## Commits in this session
+
+- `0d9208a` fix(audit): A1/A2/A4/A6/A8/A9/A16/A17/A19/A20
+- `9821106` fix(legacy-stage): purge 9-stage enum keys from rank tables and stale copy
+
+Test suite: 1373/1373 pass · tsc clean · lint clean.

docs/AUDIT-TRIAGE.md

@@ -0,0 +1,153 @@
+# Port Nimara CRM — Audit Triage (importance-grouped)
+
+Companion to `AUDIT-2026-05-12.md`. Every line below is a real finding from the 33-agent audit, regrouped strictly by **impact × likelihood of biting you**, not by which domain found it. Tackle tiers top-down.
+
+---
+
+## Tier 0 — Stop-ship: do these in the next session
+
+Anything here is a foot-gun that's actively armed in production right now.
+
+| #   | What                                                               | Where                                                                       | Why now                                                                                                                                                                                                     |
+| --- | ------------------------------------------------------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0.1 | Build a real `db:migrate` runner                                   | new tsx script                                                              | `pnpm db:push` silently skips `CREATE INDEX CONCURRENTLY` (6 indexes in 0052 never created) and skips 2 structural constraints. Every other "migration X exists" claim is unverifiable until this is fixed. |
+| 0.2 | `EMAIL_REDIRECT_TO` prod refusal in `src/lib/env.ts`               | env zod refine                                                              | One stray env value silently funnels every outbound (invites, EOI, portal magic links, contracts) to a single inbox. Only signal today is `logger.debug`.                                                   |
+| 0.3 | Admin self-target audit-log retention + alerting                   | audit_logs metadata + retention cron                                        | `audit_logs.metadata` not in `maskSensitiveFields`, no retention cron. PII grows unbounded; rotated-admin compromise is invisible.                                                                          |
+| 0.4 | Resolve-identifier hit-path still echoes the real email            | `/api/auth/resolve-identifier/route.ts`                                     | Rate-limit is in (just shipped), but on a hit we still return the canonical email. Replace with a server-side signIn proxy that takes `{identifier, password}` and never returns the email at all.          |
+| 0.5 | Orphan-blob windows in 9+ services                                 | `documents`, `brochures`, `invoices`, `gdpr-export`, `backup`, `berth-pdf`… | Every `storage.put` runs outside the `db.insert(files)` tx. "Reaper handles it" comment is wrong — no reaper exists. Months of operation = hundreds of orphans.                                             |
+| 0.6 | `backup_jobs.storage_path` missing from `TABLES_WITH_STORAGE_KEYS` | `src/lib/storage/migrate.ts:55-60`                                          | Flip the storage backend → silently orphans every pg_dump. Last-resort recovery path goes dark.                                                                                                             |
+
+---
+
+## Tier 1 — Compliance / legal liability
+
+Anything here puts the company in a regulator finding or a court case.
+
+| #   | What                                                                                                                      | Where                                                                                                                                                                                            |
+| --- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1.1 | GDPR Article-15 export bundle is incomplete                                                                               | `gdpr-bundle-builder.ts` — missing portal_users, email_threads/messages, document_sends, reminders, files, scratchpadNotes, client_merge_log, contact_log, website_submissions, form_submissions |
+| 1.2 | Right-to-be-forgotten doesn't actually erase                                                                              | `client-hard-delete.service.ts` — verbatim PII survives in `email_messages.body_html`, `files`, `document_sends.recipient_email`                                                                 |
+| 1.3 | Activation/reset tokens travel in `?token=` URL query strings                                                             | portal-auth flow — leaks to browser history, proxy logs, Referer headers                                                                                                                         |
+| 1.4 | `error_events.request_body_excerpt` redacts password/token but not email/phone/name/dob/address                           | error-classifier sanitizer                                                                                                                                                                       |
+| 1.5 | `audit_logs` no retention cron + IP captured on routine events                                                            | `lib/audit.ts` — lawful-basis-questionable                                                                                                                                                       |
+| 1.6 | S3 backend ships without `ServerSideEncryption` header                                                                    | `S3Backend.put` — signed contracts, GDPR exports, pg_dumps cleartext at rest unless bucket default is set                                                                                        |
+| 1.7 | `audit_logs.metadata` carries raw PII (full emails) at portal-auth, crm-invite, hard-delete, email-accounts service sites | `maskSensitiveFields` skips metadata                                                                                                                                                             |
+
+---
+
+## Tier 2 — Money/numbers correctness
+
+Anything where the dashboard or a PDF lies to the user about money.
+
+| #   | What                                                                                                                             | Where                                                                          |
+| --- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| 2.1 | `pipelineValueUsd` sums mixed currencies as USD                                                                                  | `dashboard.service.ts:39-51`, KPI cards, pipeline-value tile, revenue forecast |
+| 2.2 | Revenue PDF "TOTAL COMPLETED REVENUE" includes lost + cancelled                                                                  | `report-generators.ts:126-140` — no outcome filter                             |
+| 2.3 | Pipeline PDF crashes because `stageCounts` is missing `.groupBy()`                                                               | `report-generators.ts`                                                         |
+| 2.4 | Hot-deals widget rank ladder uses wrong stage names (`'in_comms'`, `'deposit_10'`)                                               | `dashboard.service.ts:198-208`, `hot-deals-card.tsx:26-36`                     |
+| 2.5 | "Active interest" means **4 different things** across dashboard / kanban / hot deals / PDFs                                      | extract `activeInterestsWhere(portId)` helper                                  |
+| 2.6 | Occupancy rate: KPI uses `berths.status`, analytics timeline uses `berth_reservations` — two different numbers on same dashboard | `dashboard.service.ts`                                                         |
+| 2.7 | Revenue PDF unweighted vs dashboard weighted-by-`pipeline_weights` — will never reconcile                                        | `report-generators.ts`                                                         |
+| 2.8 | `expenses.amountUsd` snapshot uses edit-time rate not `expenseDate`; nulls when Frankfurter is down                              | `expenses.service.ts`                                                          |
+| 2.9 | `convert()` rounds 2dp regardless of currency (JPY broken); invoice math has no rounding (sub-cent drift)                        | `currency.service.ts`, invoice math                                            |
+
+---
+
+## Tier 3 — Customer-visible polish (embarrassing in front of clients)
+
+| #    | What                                                                                                                                 | Where                                                                                                         |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| 3.1  | "Interest" / "lead" / "prospect" / "deal" used interchangeably in client-facing UI                                                   | `berth-detail-header.tsx`, `berth-tabs.tsx` "Deal Documents", `client-interests-tab.tsx`, `interest-tabs.tsx` |
+| 3.2  | Portal renders raw machine enums to clients ("EOI: waiting_for_signatures", "hot lead")                                              | `/portal/interests/page.tsx:80`                                                                               |
+| 3.3  | 16 destructive flows use native `window.confirm()`                                                                                   | cancel signing envelope, delete files, archive interest/company/yacht                                         |
+| 3.4  | Signing-status labels diverge across 5 surfaces (Hub / list / interest-tab / SigningProgress / notification-digest / realtime-toast) | normalize through one helper                                                                                  |
+| 3.5  | 6× "Save" button variants ("Save" / "Save Changes" / "Save changes") + 6× "Saving..." vs "Saving…"                                   | sweep                                                                                                         |
+| 3.6  | Live Documenso template missing `Berth Range` field — every multi-berth EOI ships with primary mooring only                          | Documenso admin                                                                                               |
+| 3.7  | URL interpolations in every email template are unescaped (`href="${data.link}"`) — a `"` in any URL breaks out                       | escape + scheme allow-list in `shell.ts`                                                                      |
+| 3.8  | Admin email-template subject editor silently does nothing on 5 of 8 templates                                                        | wire `overrides.subject`                                                                                      |
+| 3.9  | `/admin/email` Signature/Footer HTML fields write keys the shell never reads                                                         | wire `cfg.footerHtml` or delete fields                                                                        |
+| 3.10 | Mobile scan PWA "Save expense" sits flush against iPhone home indicator                                                              | safe-area-inset on ScanShell `<main>`                                                                         |
+
+---
+
+## Tier 4 — Authz / cross-tenant integrity
+
+| #   | What                                                                                                                         | Where                                                                                            |
+| --- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| 4.1 | Port admin with only `admin.manage_users` can grant other users any leaf they don't hold themselves (sock-puppet escalation) | permission-overrides PUT + `updateUser` role reassignment — require caller-superset before write |
+| 4.2 | `/api/v1/alerts` GET is ungated                                                                                              | add `admin.view_audit_log`                                                                       |
+| 4.3 | Webhooks bypass the platform-error pipeline entirely                                                                         | `documenso/route.ts` — `captureErrorEvent` on handler throw, apply to all webhook routes         |
+| 4.4 | Search graph-expansion writes into all merged buckets without re-checking per-bucket `view` permission                       | `search.service.ts:1893-1915` — gate each merge call                                             |
+| 4.5 | "Convert to client" writes prefill qs params no consumer reads; inquiry_id linkage dropped forever                           | inquiry-inbox triage flow                                                                        |
+| 4.6 | Inquiry email dedup is case-sensitive (capital-letter resubmits = duplicate client+yacht+interest)                           | `lower()` on `clientContacts.value === data.email`                                               |
+
+---
+
+## Tier 5 — Concurrency / data races
+
+| #   | What                                                                                                                       | Where                                                                            |
+| --- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| 5.1 | `handleDocumentCompleted` idempotency gate is TOCTTOU under webhook+poll race — duplicate files rows + orphan blob         | `documents.service.ts:1100-1253` — `SELECT … FOR UPDATE` or pre-claim transition |
+| 5.2 | **Zero BullMQ `jobId` usage repo-wide** — every queue.add is unkeyed, any double-fire creates a duplicate job              | every `queue.add` site                                                           |
+| 5.3 | `advanceStageIfBehind` reads stage outside any lock — parallel DOCUMENT_SIGNED + DOCUMENT_COMPLETED double-run berth rules | wrap in tx                                                                       |
+| 5.4 | `moveFolder` cycle check outside a tx — two concurrent moves can create A↔B cycles                                         | wrap in tx                                                                       |
+| 5.5 | Berth-PDF upload writes blob _before_ acquiring advisory lock — orphans on tx-rollback                                     | reorder                                                                          |
+| 5.6 | `user_email_changes` has no partial unique index on pending rows — spam-email vector                                       | add partial unique                                                               |
+
+---
+
+## Tier 6 — Perf / scale (silent today, painful at 10× traffic)
+
+| #   | What                                                                                                        | Where                  |
+| --- | ----------------------------------------------------------------------------------------------------------- | ---------------------- |
+| 6.1 | Documents tab opens with ~50 sequential queries via fetchWorkflowGroupRows                                  | `documents.service.ts` |
+| 6.2 | Recharts statically imported in `widget-registry.tsx` — every dashboard chart in initial bundle (~80-150KB) | lazy import            |
+| 6.3 | `DataTable` rebuilds `allColumns` every render (no useMemo) — resets TanStack internal state                | memo                   |
+| 6.4 | `tiptap-to-pdfme.ts` (571 lines) ships to client just to re-export TEMPLATE_VARIABLES                       | split                  |
+| 6.5 | `listUsers` runs 2 sequential queries with no pagination, returns all super-admins globally                 | paginate               |
+| 6.6 | `command-search` invalidates 2 queries every dropdown open — defeats its own 30s staleTime                  | drop invalidates       |
+
+---
+
+## Tier 7 — Build / deploy hardening
+
+| #   | What                                                                                                            | Where          |
+| --- | --------------------------------------------------------------------------------------------------------------- | -------------- |
+| 7.1 | No `.dockerignore` → 7.6 GB build context, secrets/.env leak risk via `COPY . .`                                | add            |
+| 7.2 | `socket.io` + `@socket.io/redis-adapter` not in `serverExternalPackages`; runner stage installs no runtime deps | next.config.ts |
+| 7.3 | Prod CSP keeps `'unsafe-inline'` on script-src                                                                  | tighten        |
+| 7.4 | `Dockerfile.dev` runs as root                                                                                   | non-root user  |
+| 7.5 | Compose has no memory/CPU/log-rotation limits                                                                   | add            |
+| 7.6 | `@types/node@^25` against Node-20 runtime — type checker greenlights APIs that don't exist                      | pin to ^20     |
+| 7.7 | `node:20-alpine` base image at/past EOL                                                                         | bump to 22     |
+
+---
+
+## Tier 8 — Already fixed in this session (don't redo)
+
+Already on `feat/documents-folders`:
+
+- Permission-overrides self-target privilege escalation block + canonical allow-list + cross-tenant guard
+- `/api/auth/resolve-identifier` rate-limit + synthetic miss email
+- Admin email-change updates `account.accountId` + revokes sessions
+- Middleware `PUBLIC_PATHS` for email confirm/cancel tokens
+- NAV_CATALOG dead-link sweep (10 entries)
+- formatRole / formatOutcome / stageLabel applied across user-list, user-card, role-list, sidebar, command-search, realtime-toasts, interest-detail-header, client-columns, yacht-tabs, interest-picker, next-in-line-notify, AI worker, PDF reports
+- Optional username sign-in (migration 0054)
+- Per-user permission overrides (migration 0055) + UserPermissionMatrix
+- UserForm: first/last + admin email change + auto-notify template + PhoneInput
+- User disable button
+
+---
+
+## Tier 9 — Nice-to-haves + AI opportunities (not blocking)
+
+Forward-looking (improvements-auditor):
+
+- **AI-where-it-actually-helps:** semantic search across notes + email threads, auto-summarise client history on detail-page open, anomaly detection on expenses paired with existing OCR.
+- **What NOT to AI-ify:** legal docs, EOI/contract field merges, money flow, regulatory text.
+- **Subtle UX wins:** keyboard shortcuts (j/k list nav, e to edit), smarter defaults (last-used port/currency/source), undo for accidental archives, "what changed since I last looked" digest.
+
+---
+
+_Pick a tier and we open it._

docs/BACKLOG.md

@@ -0,0 +1,428 @@
+# Master backlog index
+
+**Single source of truth for everything outstanding.** Start here when
+asking "what's left to build/fix?". Items are grouped by source doc;
+each entry links back to the original spec for full context.
+
+Last updated: 2026-05-12 (PDF stack overhaul shipped: react-pdf brand
+kit + port logo upload + 4 reports + 3 record exports + parent-company
+expense + pdfkit brand header + invoice removal + tiptap-to-pdfme
+deletion + unpdf for berth-parser tier-2; pdfme deps removed.
+Remaining 7 react-email templates ported. browser-image-compression
+wired into scan-shell. @axe-core/playwright smoke suite added.).
+Documenso phases 2-7 stay back-burnered per user.
+
+---
+
+## A. Documenso build (deferred for later)
+
+**Source:** [`docs/documenso-build-plan.md`](./documenso-build-plan.md) — full phase plan with locked decisions (Q1–Q10).
+**Tracker delta:** [`docs/admin-ux-backlog.md`](./admin-ux-backlog.md) — what landed in Phase 1.
+
+Phase 1 (EOI generate flow polish + APPROVER-as-CC + per-port settings + signing-URL fix) is **DONE** and committed.
+
+Remaining phases — explicitly back-burnered by the user on 2026-05-07:
+
+| Phase       | Scope                                                                                                                                                                                                                                                                                                                                                                         | Estimate   | Notes                                                                                                                                                            |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Phase 2** | Webhook handler enhancement: cascading "your turn" emails, on-completion PDF distribution, token-based recipient matching, idempotency lock                                                                                                                                                                                                                                   | ~3–4h      | Schema columns already in place from Phase 1 (`document_signers.invited_at / opened_at / signing_token`, `documents.completion_cc_emails`).                      |
+| **Phase 3** | Custom doc upload-to-Documenso: `custom-document-upload.service.ts` + `POST /api/v1/interests/[id]/upload-for-signing`                                                                                                                                                                                                                                                        | ~6–8h      | Depends on Phase 2 webhook UX in anger before locking the upload UX.                                                                                             |
+| **Phase 4** | Field placement UI: react-pdf + dnd-kit overlay + auto-detect anchor scanner via pdfjs `getTextContent`                                                                                                                                                                                                                                                                       | ~10–14h    | Largest piece. Plan locked in build-plan Phase 4 — regexes, anchors, type-to-bbox sizing all spelled out. Best done in a focused session with the user watching. |
+| **Phase 5** | Embedded signing URL emission verification: confirm website's `/sign/<type>/<token>` page handles every signer-role × documentType combination; update `signerMessages` map; apply nginx CORS block from integration audit                                                                                                                                                    | ~1–2h      |                                                                                                                                                                  |
+| **Phase 6** | Polish: auto-send delay, audit-log additions, per-document customisation, document expiration, reminder rate-limit display, failed-webhook recovery UI                                                                                                                                                                                                                        | each ~2–3h | All deferred until Phases 1–4 ship.                                                                                                                              |
+| **Phase 7** | Project Director RBAC — UI binding for the developer-user fields. Add "Linked to CRM user" dropdown in `/admin/documenso/page.tsx`; auto-fill name/email; webhook handler matches against linked user's email for in-CRM signing-status updates. Schema + setting keys (`documenso_developer_user_id`, `documenso_approver_user_id`, `_label`) already in place from Phase 1. | ~1h        | Smallest piece; could be picked off independently of Phase 2.                                                                                                    |
+| **Risk #4** | v2 webhook payload audit against a live v2 instance (`payload.documentId` vs `payload.id`, `recipient.token` vs `recipient.recipientId`) before relying on Phase 2 cascading emails                                                                                                                                                                                           | ~1h        | Needs a live v2 instance.                                                                                                                                        |
+
+---
+
+## B. Custom-fields hardening
+
+**Source:** [`docs/admin-ux-backlog.md`](./admin-ux-backlog.md) §7.
+
+- ✅ **Merge tokens** — `{{custom.<fieldName>}}` validators + resolver shipped 2026-05-08. Tokens expand at template-render time for client/interest/berth contexts via `mergeCustomFieldValues` in `document-sends.service.ts`. Banner updated.
+- **Search index** — DEFERRED as design limitation. Adding GIN coverage requires either joining `custom_field_values` per search (slow at scale) or materializing values into a search_text column on the parent (additive maintenance burden). The amber banner documents this.
+- **Audit diff** — N/A. Custom-field values live in their own table, not as a JSONB blob on the parent entity. The `setValues()` service-layer call already creates its own audit log entry (custom-fields.service.ts:349-358), so changes ARE audited — just separately from the entity-diff.
+- ✅ **UI surfacing of `{{custom.…}}` tokens in template-edit pickers** — landed 2026-05-13. Shared `<TemplateTokenPicker>` (`src/components/admin/shared/template-token-picker.tsx`) renders the canonical `MERGE_FIELDS` catalog grouped by scope plus a dynamically-fetched "Custom (port-specific)" group filtered to entityTypes resolvable at send-time (client/interest/berth). Wired into both `sales-email-config-card.tsx` and `document-templates/template-form.tsx` so both pickers share the same surface.
+
+---
+
+## C. Audit-final deferred items
+
+**Source:** [`docs/audit-final-deferred.md`](./audit-final-deferred.md) — pre-merge + post-merge audit findings explicitly carried over.
+
+The 2026-05-07 backlog sweep landed every small/concrete item. Remaining
+entries are deferred because they need design decisions, live external
+instances, or cross-cutting refactors:
+
+### Deferred — Documenso-related (back-burnered until phases 2-7 land)
+
+- **Documenso webhook does not enforce port_id on document lookups** — `src/app/api/webhooks/documenso/route.ts:96-148`. Bundle with Documenso Phase 2 (webhook handler enhancement) since they touch the same code.
+- **Webhook dedup vs per-recipient signed events** — `src/app/api/webhooks/documenso/route.ts:103-110`. Replacing the body-hash dedup with a `(documensoDocumentId, recipientEmail, eventType)` composite unique requires a recipient_email column on `documentEvents`. Bundle with Phase 2.
+- **v2 voidDocument endpoint shape verification** — `src/lib/services/documenso-client.ts:450-466`. Needs a live Documenso 2.x instance. Bundle with Phase 5.
+
+### Deferred — pure refactor (no active bug)
+
+- **Public POST routes bypass service layer** — `src/app/api/public/{interests,website-inquiries,residential-inquiries}/route.ts`. The audit's `userId: null as unknown as string` cast was already cleaned up to a proper `userId: null`. Remaining concern is testability: extract a shared `publicInterestService.create(...)`. Pure ergonomics — no active bug or security issue.
+
+### Done in 2026-05-08 sweep (latest)
+
+- ✅ Storage proxy port_id binding: `ProxyTokenPayload` gains optional `p` (port slug) claim; verifier asserts `key.startsWith(${p}/)`. document-sends 24h URLs opt in; other issuers continue working unchanged.
+- ✅ system_settings index rebuilt with `NULLS NOT DISTINCT` (migration 0047) — global settings are now uniquely keyed by `key` alone. Surfaced + cleaned 65 duplicate `(storage_backend, NULL)` rows that had accumulated from race-prone delete-then-insert patterns.
+- ✅ All 4 read-then-write systemSettings sites converted to true `onConflictDoUpdate` upserts (ocr-config, settings, residential-stages, ai-budget).
+- ✅ Response shape standardization: 16 routes converted from `{ success: true }` → `204 No Content`. CLAUDE.md documents the convention.
+- ✅ `req.json()` → `parseBody()` migration across 9 admin/CRM routes (custom-fields, expenses/export ×3, currency convert, search/recently-viewed, admin/duplicates, berths/pdf-{upload-url,versions,parse-results}). Portal-auth routes intentionally retained `{ success: true }`.
+- ✅ Custom-field merge tokens: validator accepts `{{custom.<fieldName>}}` shape; resolver in `mergeCustomFieldValues` substitutes from per-port custom_field_definitions + per-entity values for client/interest/berth contexts. Banner updated.
+- ✅ `/api/v1/files` accepts `companyId` and `yachtId` filters. uploadFile service writes both. file-upload-zone component accepts both props.
+- ✅ Company Documents tab (CompanyFilesTab) re-enabled and added to company detail tabs.
+
+### Done in 2026-05-07 sweep (commits in this session)
+
+- ✅ Partial archived indexes (migration 0046) — `clients`, `interests`, `yachts`, `residential_clients`, `residential_interests`
+- ✅ `document_sends` interestId port-verification helper
+- ✅ Custom-fields per-entity permission gate (replaces hardcoded `clients.view/edit`)
+- ✅ EOI Berth Range warn log (was already in place)
+- ✅ v1 `placeFields` retry with backoff (was already in place)
+- ✅ S3 bucket-exists check at boot (was already in place)
+- ✅ Filesystem dev HMAC fallback warn (was already in place)
+- ✅ Storage cache fingerprint documentation comment
+- ✅ AI worker cost ledger writes (was already in place)
+- ✅ Logger redact paths covering headers, encrypted blobs, two-level nesting (was already in place)
+- ✅ `loadRecommenderSettings` accepts string `"true"`/`"false"` JSONB booleans
+- ✅ `renderReceiptHeader` cursor math anchored to captured `baseY`
+- ✅ Berth PDF apply: silent-drop logging for non-finite numeric coercions
+- ✅ Saved-views: confirmed by-design owner-only (existing inline doc)
+- ✅ Alerts ack/dismiss: confirmed by-design port-wide (service correctly bounded)
+- ✅ Storage admin migration toasts (already in place)
+- ✅ Invoice send/payment toasts + permission gates (already in place)
+- ✅ Admin user list edit + remove gates (added remove gate)
+- ✅ Email threads list skeleton + empty state (already in place)
+- ✅ Scan page error state for OCR failures (already in place)
+- ✅ Invoice detail typed (replaced `any` with `InvoiceDetailData` interface)
+- ✅ All FK indexes called out in audit doc (already in place — audit was stale)
+- ✅ `documentSends.sentByUserId` FK (already had `.references(...)`)
+
+### Documented limitations (no action planned)
+
+- **`berths.current_pdf_version_id` lacks Drizzle FK** — `src/lib/db/schema/berths.ts:83`. The in-line comment fully documents why (circular FK between `berths` ↔ `berth_pdf_versions` makes column-level `.references()` infeasible). FK is enforced via migration 0030. Revisit if Drizzle adds deferred-FK support.
+- **`systemSettings` schema declares `uniqueIndex` instead of `NULLS NOT DISTINCT`** — Drizzle's `uniqueIndex` builder doesn't surface the flag. Migration 0047 is the source of truth; `db:push` against an empty DB would skip the flag. Same documented-limitation pattern as `berths.current_pdf_version_id`.
+- **One remaining `req.json()` in admin/custom-fields/[fieldId]** — intentional. The handler inspects raw body to detect `fieldType` mutation attempts; parseBody would lose the raw view. Documented inline.
+
+---
+
+## D. Inline TODOs in code (2 remaining)
+
+| File:line                                                                      | Note                                                            | Status                                                                                  |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| ~~`client-yachts-tab.tsx:93`~~                                                 | YachtForm preset owner prop                                     | ✅ landed 2026-05-07 (`initialOwner` prop)                                              |
+| ~~`interest-form.tsx:329`~~                                                    | Include company-owned yachts where client is a member           | ✅ landed 2026-05-07 (`yachtOwnerFilter` array filter)                                  |
+| ~~`interest-form.tsx:330`~~                                                    | "Add new yacht" inline shortcut                                 | ✅ landed 2026-05-07 (Plus button + YachtForm sheet)                                    |
+| [`src/lib/queue/scheduler.ts:44`](../src/lib/queue/scheduler.ts#L44)           | Per-user reminder schedule (override on top of per-port digest) | Placeholder — per-port digest works; revisit when a customer asks for per-user override |
+| [`src/lib/queue/workers/import.ts:13`](../src/lib/queue/workers/import.ts#L13) | CSV/Excel import worker — entire feature surface                | Placeholder — nothing currently enqueues `import` jobs (verified)                       |
+
+---
+
+## E. Hidden / stubbed UI tabs
+
+- ✅ **Company Documents tab** — landed 2026-05-08. `/api/v1/files` accepts `companyId`+`yachtId` filters; CompanyFilesTab + uploadZone wired through the storage abstraction.
+- **Berth Waiting List + Maintenance Log tabs** — `src/components/berths/berth-tabs.tsx:346`. Removed entirely; revisit if/when product asks.
+- **Interest Contract / Reservation tabs** — `src/components/interests/interest-{contract,reservation}-tab.tsx`. Render a "coming soon" friendly card; the real flow is gated on Documenso Phases 2–6.
+
+---
+
+## G. Dependencies / audit roadmap (post-PDF-overhaul)
+
+**Source:** [`docs/AUDIT-2026-05-12.md`](./AUDIT-2026-05-12.md) §§ 34-36 +
+[`docs/superpowers/specs/2026-05-12-pdf-stack-overhaul-design.md`](./superpowers/specs/2026-05-12-pdf-stack-overhaul-design.md).
+
+What's done (2026-05-12 session — all phases shipped):
+
+- ✅ **PDF stack overhaul** — `@react-pdf/renderer` + brand kit + port logo upload pipeline; 4 reports + 3 record exports + parent-company expense ported; pdfme uninstalled; pdfkit retained for streaming expense PDF (now with shared brand-header). Invoice PDF generation removed (deferred to AcroForm-fill admin-upload). TipTap-to-pdfme bridge (571 LOC) deleted; admin TipTap templates remain as Documenso seed bodies. `unpdf` wired into berth-PDF parser tier-2 (replaced broken tesseract-on-PDF path).
+- ✅ **react-email templates** — all 7 remaining (crm-invite, document-signing×3, inquiry×2, residential×2, notification-digest, admin-email-change) ported from string templates to React components. Public API surface now `async`. The whole email template directory is uniformly react-email.
+- ✅ **browser-image-compression** — wired into scan-shell so 4-12 MB phone photos crush to ~500 KB in a WebWorker before tesseract / upload. Massive mobile bandwidth + battery + perceived-latency win.
+- ✅ **@axe-core/playwright** — smoke spec runs WCAG 2.1 A/AA against 6 main pages; CI fails on new critical/serious violations.
+- ✅ **ts-pattern in search.service.ts** — converted both switches to `match().with().exhaustive()`; surfaced a real bug along the way (missing `notes` bucket dispatch — `searchNotes()` existed but was never wired into runSingleBucket). The audit flagged 3 other switch sites (client-restore, recently-viewed, custom-fields); those operate on tagged-union internal types where TypeScript already enforces exhaustiveness via control-flow narrowing — converting them adds noise without changing safety. **Done.**
+- ✅ **p-limit in mass-op services** — bounded fan-outs on the three real unbounded `Promise.all` sites the audit flagged: berth-pdf S3 presigns (20-version berths), custom-fields bulk upserts (50-definition admin scenarios), notifications watcher fan-out (hot pipeline items). Audit also speculatively flagged brochures.service + backup.service — verified neither has an unbounded fan-out. **Done.**
+- ✅ **formatDate helper** — single source of truth in `src/lib/utils/format-date.ts` backed by `Intl.DateTimeFormat` (no new dep). 9 named presets, TZ-aware via `tz` opt, defensive against null/Invalid Date. `formatDateRange` collapses same-year strings. `formatRelative` via `Intl.RelativeTimeFormat`. 17 unit tests. Sample sweep through 3 high-traffic sites (expense-pdf header, 3 document-template merge tokens); the remaining 93 `.toLocale*` sites can be migrated opportunistically when each file is touched.
+- ✅ **@tanstack/react-virtual in DataTable** — opt-in `virtual` prop. Existing server-paginated tables unchanged; large client-side lists (admin exports, audit-log archive) now render only viewport rows + small overscan at 60 fps. Pagination wins over virtual when both are passed; mobile card view untouched; sticky header, sort, selection all unchanged.
+- ✅ **drizzle-zod adoption** — pattern proven in tags.ts + brochures.ts (earlier commit). The remaining ~28 validators include heavy form-input transforms (numeric-string-to-null, refined business rules, partial omits/picks) that drizzle-zod's createInsertSchema doesn't preserve — most are NOT 1:1 with the table shape. Migration is net-wash on LOC and adds no safety. Pattern available for adoption when a validator genuinely matches its table.
+- ✅ **Tier 2 polish** — surveyed each candidate. `fast-deep-equal` not needed (existing memo comparators work). `use-debounce` package adds no value over the in-tree 13-LOC hook. `@use-gesture/react`, `embla-carousel-react`, `yet-another-react-lightbox`, `react-resizable-panels` all need concrete UX surfaces or product decisions before wiring — added them to the parked list.
+- ✅ **Pre-commit staged type-check** — `scripts/tsc-staged.mjs` (30-LOC shim) replaces the broken `tsc-files` package (which silently no-ops under pnpm). Pre-commit now runs `tsc -p <temp-config>` against staged ts/tsx in ~3s vs ~22s full-project; type errors caught before they hit CI.
+
+**React Compiler safety triage (post-Next-16 bump):**
+
+The Next 15 → 16 upgrade brought `react-hooks` v7 with React Compiler safety rules. Initial sweep surfaced ~89 findings; categorical triage status as of 2026-05-12:
+
+- ✅ `react-hooks/purity` (2 → 0) — promoted to `error`. Cleared by pinning `Date.now()` reads to a `useState`-backed `now` ticker in `notes-list.tsx`.
+- ✅ `react-hooks/set-state-in-render` (5 → 0) — promoted to `error`. `useMemo` mis-used for side effects in `interest-contact-log-tab.tsx`; converted to `useEffect`.
+- ✅ `react-hooks/immutability` (7 → 0) — promoted to `error`. Mutable `useMemo` value in `documents-hub.tsx` drag counter → `useRef`. `let angle` mutation in `PieChart.tsx` slice loop → `reduce`. Three "function used before declared" hits (load/loadProfile in admin/onboarding-checklist + settings/user-profile + settings/user-settings) → declared inside the calling `useEffect`.
+- ✅ `react-hooks/refs` (10 → 0) — promoted to `error`. Three `ref.current = x` writes during render moved into a layout-effect (`use-realtime-invalidation.ts`, `settings-form-card.tsx`, `inbox.tsx`). Three search-related `ref.current` reads during render rewritten to backed-by-state (`command-search.tsx`, `mobile-search-overlay.tsx`). Scan shell's `fileRef.current.files[0]` read replaced with a tracked `currentFile` state.
+- ✅ `react-hooks/incompatible-library` (13 → silenced as `off`) — purely informational ("Compiler skipped this file because of a non-Compiler-safe import"). No action needed.
+- ✅ `react-hooks/set-state-in-effect` (51 → 0) — promoted to `error` in eslint.config.mjs. All admin-form data-loading hits migrated to TanStack Query (`useQuery`); a small ring of justified eslint-disable comments cover canonical setState-on-subscription patterns (socket-provider, carousel, settings-form-card, etc.). New regressions block CI.
+
+**Data-fetching pattern migration: DONE.** All `useEffect → fetch → setState` sites in admin components migrated to TanStack Query. `set-state-in-effect` is now an ESLint error, so new regressions can't land.
+
+---
+
+Remaining (opportunistic, no concrete trigger):
+
+| Item                                                | Estimate            | Notes                                                                                                                                                                            |
+| --------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`.toLocale*` remainder (93 sites)**               | ~2-3h opportunistic | Migrate to `formatDate(...)` as you touch each file. Helper already shipped; 17 tests; sweep proven on PDF + template paths.                                                     |
+| **drizzle-zod remainder (~28 simple validators)**   | ~30 min per file    | Migrate when a validator file is touched. Pattern proven in tags + brochures.                                                                                                    |
+| **Wire `<DataTable virtual />`** on big tables      | ~15 min per site    | Prop is shipped + opt-in. Apply to: admin/audit-log-list (10k rows possible), super-admin port switcher (50+ ports), client export modal preview. None blocking.                 |
+| **Tier 2 polish — when product UX surfaces emerge** | each 30 min – 1 h   | `embla-carousel-react` + `yet-another-react-lightbox` for berth / yacht photo galleries · `react-resizable-panels` for docs hub sidebar · `@use-gesture/react` for kanban swipe. |
+
+Decisions / parked:
+
+- ~`@upstash/ratelimit`~ — **rejected on inspection.** Audit claimed "4 hand-rolled rate limiters"; actual state is **one** centralized sliding-window Redis limiter (`src/lib/rate-limit.ts`) with 14 named policies + atomic pipeline. Replacement is pure churn.
+- ~`@faker-js/faker`~ — **rejected on inspection.** Both seed files (`seed-data.ts`, `seed-synthetic-data.ts`) are hand-curated demo specs (per-pipeline-stage clients with locale-correct names/phones/addresses keyed to test selectors). No fake-data factory exists to replace — adopting faker means WRITING the factory + losing curation. Net add, not net subtract.
+- ~`msw`~ — **rejected on inspection.** Integration tests already mock external services via `vi.mock('@/lib/services/documenso-client', ...)` at the module boundary — equivalent determinism, no extra layer. MSW only wins when tests hit `fetch()` directly, which we don't.
+- `next-safe-action` — pilot on a new form first (no concrete trigger).
+- `@sentry/nextjs` — needs SaaS-dep decision.
+- `@tiptap/core` upgrade — needs product decision on rich notes.
+- `pdfjs-dist` / `@react-pdf-viewer/core` — in-browser PDF preview in docs hub (paired with Phase 2 docs-hub UX work).
+- `next-pwa` / `@serwist/next` — icons already in `public/`; revisit only when we want fuller service-worker integration (offline shell, install prompt UX).
+- `next-intl` — no current i18n target.
+- `posthog-js` — analytics scope decision.
+- `react-virtuoso` — only useful if inbox grows past ~hundreds of items; current `<ScrollArea max-h-[400px]>` handles realistic volumes fine.
+- `react-imask` / `react-number-format` — input masks across ~6 forms. Decision pending: hand-rolled formatters work today.
+- `type-fest` — opportunistic types; no concrete trigger.
+- `partysocket` — Socket.IO-protocol incompatible without significant rework.
+
+Major deferrals from §34 of audit:
+
+- ~**Next 15 → 16**~ — **DONE 2026-05-12**. middleware.ts → proxy.ts via codemod, native flat eslint config, react-hooks v7 Compiler safety rules surfaced + triaged.
+- ~**Tailwind 3 → 4**~ — **DONE 2026-05-12**. Official upgrade tool migrated 80 files; tailwind-animate → tw-animate-css; theme moved to @theme directive in globals.css.
+- **eslint 9 → 10** — attempted, reverted: `eslint-config-next@16` still has a transitive on `eslint-plugin-react@7` that uses removed eslint-9 context API. Re-attempt when upstream lands eslint-plugin-react@8.
+- **archiver 7 → 8** — no `@types/archiver@8` published; skip indefinitely.
+
+---
+
+## H. Grand audit cleanup plan (post-deps)
+
+**Source:** [`docs/AUDIT-2026-05-12.md`](./AUDIT-2026-05-12.md) — 534 findings across 27 domain reports + [`docs/AUDIT-FOLLOWUPS.md`](./AUDIT-FOLLOWUPS.md) + [`docs/AUDIT-TRIAGE.md`](./AUDIT-TRIAGE.md).
+
+Deps work is complete (sections A-G above). Remaining audit cleanup is grouped into focused waves so it's tackleable a chunk at a time. Each wave has clear scope, file pointers, and acceptance criteria.
+
+### Wave 1 — Stop-ship CRITICALs (security + data integrity)
+
+Roughly half-day each; ship in priority order. These are the items from the audit's `## Cross-cutting priority queue` marked `[C]`:
+
+1. **Real `db:migrate` runner** — `0052_audit_critical_fixes.sql` uses `CREATE INDEX CONCURRENTLY` which silently never runs under `db:push`. Six composite indexes missing in prod. Build a tsx runner that reads migrations in order, splits on `--> statement-breakpoint`, executes outside a tx, tracks state in `__drizzle_migrations`. ~3-4 h. **(data-model C1)**
+2. **`EMAIL_REDIRECT_TO` production guard** — `src/lib/env.ts` should refine to reject when `NODE_ENV === 'production'`; `src/lib/email/index.ts` should `logger.warn` at boot. 5-min change, prevents a very-bad-day class of incident. **(email C1)**
+3. **Orphan-blob fix in `handleDocumentCompleted`** — `src/lib/services/documents.service.ts:1100-1253`. Wrap `storage.put + files.insert + documents.update` in a transaction (or saga with compensating delete). Current catch-block leaves blob in storage AND marks `status='completed'` with no `signedFileId`. ~2 h. **(services C2)**
+4. **Escape URLs in email templates** — every template in `src/lib/email/templates/*` inlines `${data.link}` etc. into `href="…"` and link text without escaping. Add `escapeUrl` helper + http(s) scheme allow-list; route every template through it. ~3 h. **(email C2)**
+5. **Replace 16 native `window.confirm()` calls** — destructive flows bypassing `ConfirmationDialog` / `AlertDialog`. ui-ux-auditor's C1 lists the sites (cancel signing, delete files, archive interest/company/yacht…). ~30 min per site = full day. **(ui/ux C1)**
+6. **GDPR Article-15 export completeness** — `src/lib/services/gdpr-bundle-builder.ts` is missing: portal_users, email_threads/messages, document_sends, reminders, files, scratchpadNotes, client_merge_log, contact_log, website_submissions, form_submissions. Regulator-finding-level gap. ~half-day. **(gdpr C1)**
+7. **Right-to-be-forgotten actually erase** — `src/lib/services/client-hard-delete.service.ts` nullifies FKs but leaves verbatim PII in `email_messages.body_html`, `files`, `document_sends.recipient_email`. Add true-wipe path. ~half-day. **(gdpr C2)**
+8. **`user_permission_overrides.user_id` FK + `onDelete='set null'`** — data-model H1+H2. Single migration. ~30 min. **(data-model H1+H2)**
+9. **Resolve-identifier endpoint replacement** — current rate-limited hit still echoes the real canonical email on a successful username hit. Replace with a server-side signIn proxy that takes `{identifier, password}` together and never returns canonical emails at all. ~2 h. **(security/gdpr crossover)**
+
+### Wave 2 — HIGH-priority security + observability (5-7 days)
+
+10. **`audit_logs.metadata` PII masking** — extend `maskSensitiveFields` to cover `audit_logs.metadata`; add 90-day retention cron mirroring `error_events`. ~2 h. **(gdpr H)**
+11. **Webhook → error pipeline** — `src/app/api/webhooks/documenso/route.ts` bypasses `captureErrorEvent` on handler crash. Apply to every webhook route. ~2 h. **(observability H)**
+12. **Admin email-template subject editor** — 5 of 8 templates ignore `overrides.subject`; admins see "Saved" with zero effect. Wire all 8. ~2 h. **(email H1+H2)**
+13. **Admin signature/footer fields** — `/admin/email` writes `email_signature_html` + `email_footer_html` which the email shell never reads. Either delete the UI or wire it. ~half-day. **(email H3)**
+14. **PII redaction in error pipeline** — `error_events.request_body_excerpt` sanitizer redacts password/token but not email/phone/name/dob/address. ~2 h. **(observability H + gdpr)**
+15. **Notification email worker XSS** — `src/lib/queue/workers/notifications.ts:65-71` interpolates `notif.description` and `notif.link` into HTML unescaped. Apply `escapeHtml` + URL allow-list (the `isomorphic-dompurify` we shipped helps here). ~1 h. **(email H + security)**
+
+### Wave 3 — React Compiler set-state-in-effect cleanup (~40 sites remaining)
+
+Remaining `react-hooks/set-state-in-effect` warnings: **40** (was 41; reduced 2026-05-13). Two patterns established this session as templates:
+
+- **List/load pattern** (`src/components/admin/tags/tag-list.tsx` is the template): `useState([]) + useEffect(fetch+setState)` → `useQuery({ queryKey, queryFn })`. Mutation paths get `useMutation` with `onSuccess: queryClient.invalidateQueries`. ~10 min per site.
+- **Dialog open→reset pattern** (`src/components/clients/hard-delete-dialog.tsx` is the template; new exemplar: `src/components/documents/move-to-folder-dialog.tsx`): inner `<DialogBody key={id} ... />` mounted only while `open`, so `useState` initializers run naturally on each open without an open→reset useEffect. ~15 min per site.
+
+Migrate as a focused day's work (~40 × 10-15 min), then promote `react-hooks/set-state-in-effect` from `warn` to `error` in `eslint.config.mjs` to lock in. **NOTE:** Warnings only — no functional regressions; promotion blocked solely until 0 warnings remain.
+
+### Wave 4 — UI/UX consistency + accessibility (~3-4 days)
+
+- ✅ **Raw enum render via `.replace(/_/g, ' ')` (40+ sites)** — extracted to `constants.ts` `formatStage`/`formatStatus`/`formatPriority` helpers (audit-wave-4). **(ui/ux H1)**
+- ✅ **18 list components missing mobile `cardRender`** — Wave 9.4 covered the 5 actual DataTable consumers without `cardRender` (admin/tags, admin/roles, admin/ports, admin/document-templates, admin/custom-fields). **(ui/ux H2)**
+- ✅ **Berth status pills using ad-hoc Tailwind colors** — swapped to shared `StatusPill` in Wave 9.2. **(ui/ux M1)**
+- ✅ **UserList "Active"/"Disabled" badge** — aligned to `StatusPill` in Wave 9.2; also `PortList` in Wave 9.4. **(ui/ux M2)**
+- ✅ **Drawer vs Sheet usage drift** — single offender (`client-interests-tab`) swapped to Sheet; doctrine documented in CLAUDE.md (Wave 9.1). **(ui/ux M11)**
+- ✅ **Decorative icons missing `aria-hidden`** — Wave 10.4 mechanical sweep added `aria-hidden` to 444 self-closing single-line Lucide icons across 267 .tsx files. **(ui/ux M10)**
+- ✅ **Hard-coded "border-amber-300 bg-amber-50" callouts (15+ sites)** — `<WarningCallout>` shipped in Wave 4. **(ui/ux L5)**
+- ✅ **Dashboard route `loading.tsx` coverage** — default `[portSlug]/loading.tsx` plus tailored detail-page skeletons (Wave 9.5). **(ui/ux M3)**
+
+### Wave 5 — Performance + reliability (~2-3 days)
+
+- ✅ **Concurrency races** — Wave 10.3 closed the CRITICAL + tractable HIGH items: `handleDocumentCompleted` concurrent-retry TOCTOU via SELECT FOR UPDATE re-check (C-1), `moveFolder` cycle-check race via per-port pg_advisory_xact_lock (H-1), `upsertInterestBerth` 23505 → ConflictError (H-3), username uniqueness 23505 → ConflictError (M-2). Wide-impact items (BullMQ jobId plumbing — C-2) remain deferred. **(concurrency C, H)**
+- ✅ **Postgres FTS for `search.service.ts`** — migration `0057_search_fts_indexes.sql` shipped in Wave 5. **(audit 36.K.1)**
+- ✅ **`useEffect → fetch → setState` data-loading** — covered by Wave 3.
+
+### Wave 6 — Email + Documenso depth (~2-3 days)
+
+- **Documenso integration depth** (documenso-auditor report) — full v1/v2 audit, recipient signing URL handling, redirect URL per-port, sequential signing flag.
+- **Email deliverability** (email-auditor report) — subject editor wire-up (Wave 2 #12), signature/footer wire-up (Wave 2 #13), bounce monitoring sanity check, attachment threshold UX.
+
+### Wave 7 — Reporting + recommender quality (~half-week)
+
+- **Reporting math correctness** (reporting-auditor) — verify revenue, pipeline funnel, occupancy math against hand-computed truth set.
+- **Berth recommender quality** (recommender-auditor) — tier ladder edge cases, heat-score weight calibration.
+
+### Wave 8 — Long tail (whenever)
+
+- ✅ **PDF + brand asset correctness** (pdf-auditor) — Wave 9.6: wrong-port brand fallback (`'Port Nimara'` → `(port)`/throw), AcroForm field-drift warnings, EOI form flatten, PDF metadata, sha256 pinning of `assets/eoi-template.pdf`, berth-range warning noise. Items C-2/C-3 (tiptap-to-pdfme bugs) were eliminated by the 2026-05-12 PDF stack overhaul.
+- ✅ **Customer-facing copy + terminology** (copy-auditor) — Wave 9.7: centralized `lib/labels/document-status.ts` (C3), portal `leadCategory` chip removed (C2), `Save Changes` → `Save changes` + `Saving...` → `Saving…` codemod (H1, M3), envelope → signing request (M1), `Linked prospect` → `Linked interest`, `Deal Documents` → `Interest Documents`, `Hot Lead` → `Hot lead` (M5).
+- ✅ **Onboarding + first-run UX** (onboarding-auditor) — Wave 9.8: fixed wrong setting keys in checklist auto-checks (C1), broken `forms` href (C2), compound gate for Documenso EOI readiness (C3), catch-and-log around `ensureSystemRoots` (C4), fresh-port berth empty state (H5), admin-sections-browser description (M4).
+- ✅ **Type-safety + drizzle leak audit** (types-auditor) — Wave 10.1: `Tx` type exported (C-1), berth-detail `useQuery<any>` replaced with `BerthDetailData` (C-2), parseBody adopted across 7 portal/public routes (C-3), `toAuditJson<T>` helper removed 21 `as unknown as Record<…>` casts (H-5). Drizzle leak check came back clean (no `$inferSelect` crossing the API boundary).
+- ✅ **Build + deploy + prod readiness** (build-auditor) — Wave 10.2: socket.io + 6 other native deps added to `serverExternalPackages` + COPY-in-Dockerfile (C-3), `NEXT_PUBLIC_APP_URL` validation (H-2), healthcheck PORT templatization (H-5), `NODE_ENV=production` in builder (M9), image-level HEALTHCHECK (M7). CSP `'unsafe-inline'` (H-1) deferred pending nonce middleware infrastructure.
+- ✅ **Wave 11 — unaddressed-dossier sweep + cross-cutting infra**:
+  - **BullMQ jobId plumbing** (concurrency C-2): stable per-entity jobIds added across `invoices` (send-invoice, invoice-overdue-notify), `gdpr-export`, `webhook-dispatch`, `expenses`, `webhooks.service`, `notifications`, `inquiry-notifications`, `reports` (generate-report).
+  - **CSP nonce middleware** (build-auditor H-1): per-request nonce in `src/proxy.ts:buildCspWithNonce` with `'self' 'nonce-<n>' 'strict-dynamic'` in prod; `next.config.ts` fallback header kept for static assets / API JSON.
+  - **Error UX** (error-ux-auditor): `apiFetch` synthesizes a client-side correlation id for non-JSON 5xx (C3); `checkRateLimit` fails open on Redis outage so auth doesn't lock (C4); `StorageTimeoutError extends Error` with `name='TimeoutError'` for classifier hints (H2); `errorResponse()` adopted across `/api/storage/[token]`, `/api/public/website-inquiries`, Documenso webhook body cleaned (H5); 17 `toast.error(err.message)` sites swept to `toastError(err, …)` (C2).
+  - **Outbound webhooks** (outbound-webhook-auditor): Stripe-style `HMAC(secret, "${ts}.${body}")` + `X-Webhook-Timestamp` header (C1); dead-letter when secret is null (C3); retry policy `8 attempts × 30s base exponential` (H2); SSRF denylist gains Oracle Cloud `192.0.0.192` (M1); dispatch-time `https://` assertion (M2).
+  - **Storage-pathing** (storage-pathing-auditor): berth-PDF presigned-upload key prefixed with `${portSlug}/` + `portSlug` passed to `presignUpload` (H1); `presignDownloadUrl` infers the slug from the key's first segment when callers don't pass it explicitly — engages the filesystem-proxy port-binding `p` token verifier across every download site (H2).
+  - **Search** (search-auditor): dead `void wantEmail; void wantPhone;` + unused `looksLikeEmail` helper removed (H3).
+  - **Maintainability** (maintainability-auditor M2): swept seven `void <symbol>` abandoned-scaffolding markers and their dead imports across `clients/bulk`, `interests/bulk`, `admin/email-templates`, `admin/website-submissions`, `alert-rules`, and `notes.service`.
+
+### Wave 11 — explicitly deferred items (revisited 2026-05-13, deferred again)
+
+Each was flagged by the audit but assessed as not-yet-needed for production correctness. Listed here so future-you doesn't re-research them.
+
+**Engineering refactors deferred:**
+
+- **Orphan-blob reaper** (storage-pathing C2, ~4-6h) — `handleDocumentCompleted` already has compensating delete for the only frequent orphan path. Other paths (gdpr-export, backup, etc.) are low-frequency. Revisit when storage costs grow.
+- **Webhook deliveries reaper** (outbound-webhook C2, ~2-3h) — `webhook_deliveries` table grows unbounded on high-volume events. Zero active webhook subscribers today; revisit when customers actually subscribe.
+- **DNS-rebind TOCTOU** (outbound-webhook H1, ~2h) — Requires admin AND DNS control on the target host. Defense-in-depth on already-low-risk vector. Revisit before exposing webhooks to external integrators.
+- **Streaming pass on backup/migrator/email-compose** (storage-pathing H3+H4, ~4-6h) — pg_dump OOM at multi-GB. DB is ~10s of MB today. Revisit when DB grows 100x.
+- **Webhook circuit-breaker** (outbound-webhook H3, ~3-4h) — Auto-disable webhooks after N consecutive dead-letters. Saturating worker slots requires active webhook subscribers; none today.
+
+**Mechanical service splits deferred:**
+
+- `documents.service.ts` split (1982 lines → 4 files, ~3-4h)
+- `search.service.ts` split (2163 lines → per-bucket files, ~4-6h)
+- `notes.service.ts` dedup → dispatch table (1121 → ~500 lines, ~3-4h)
+- `interest-tabs.tsx` split (959 lines → 3 files, ~2-3h)
+- `expense-pdf.service.ts` split (987 → 3 files, ~2h)
+- `command-search.tsx` split (1177 → 5 files, ~3-4h)
+
+Pure code-hygiene work. The files are large but functional. Splitting touches hundreds of imports, risks regression, delivers zero user value. Revisit if/when navigation friction becomes a real bottleneck.
+
+### How to use this section
+
+- Pick a wave; pick an item; read the linked audit section for full context.
+- Each item closes with a commit in the `fix(audit-<wave>): ...` format so it's trivially greppable.
+- Mark items DONE inline in this section as they ship.
+- Audit-FOLLOWUPS.md tracks Wave 1-10 from an earlier sweep — items there may already be done or supplanted by AUDIT-2026-05-12.
+
+Future PDF-related work (carry-over from §A of the PDF overhaul spec):
+
+- **AcroForm-fill admin-uploaded PDF templates** (~1 week solo): new `pdf_templates` table + admin upload UI + field-mapping editor + generalize `fill-eoi-form.ts` into a reusable `fillAcroForm()` utility. Reinstates the invoice PDF path (and any future customer-facing standardized doc).
+- **Port brand color tokens** (~2 h): admin sets brand color → flows into the PDF brand kit accent.
+- **Optical receipt-photo rotation/deskew** (~half day): auto-rotate phone-upload receipts that EXIF misses.
+
+---
+
+## J. Activity / timeline copy normalization
+
+Every "Activity" or "Timeline" surface across the app currently leaks
+raw schema details — camelCase field names, UUID values, boolean
+`on`/`off` — straight into the user-visible copy. Real examples seen
+in production:
+
+- `Updated owner → mEcsLxo5kyFMyhbOSehxJjYSSD7CiLvv` (user UUID)
+- `Updated primary berth → a53e3b1d-d589-4f11-9f7b-3b3a3c1ebb8e` (berth UUID)
+- `Updated primary berth → a53e..., isInEoiBundle → on` (raw camelCase + boolean)
+
+Two distinct renderers need a single source of truth:
+
+1. **`InterestTimeline`** (`src/components/interests/interest-timeline.tsx`) reads pre-built `description` strings from `/api/v1/interests/[id]/timeline/route.ts` — see `buildAuditDescription` + `describeUpdateDiff` + `formatDiffValue`. Field-label catalog is partial; FK values are unresolved.
+2. **`EntityActivityFeed`** (`src/components/shared/entity-activity-feed.tsx`) — used by clients, companies, yachts, berths, residential clients, residential interests. Builds copy client-side via `sentence()` + `formatValueForField`. Catalog is even thinner (only `pipelineStage` / `source` / `leadCategory` / `outcome` get human labels).
+
+**Plan-of-work:**
+
+- Build a shared `src/lib/audit/format-audit.ts` with:
+  - `FIELD_LABELS` per entity type (interest, client, company, yacht, berth, residential\_\*) covering every column we actually surface in audits. Today's gaps: `isInEoiBundle`, `isSpecificInterest`, `isPrimary`, `assignedTo`, `currentOwnerType/Id`, `companyId`, `parentCompanyId`, `mooringNumber`, `priceCurrency`, all the `*_at`/date fields beyond the EOI/contract handful.
+  - Value formatter that handles: booleans contextually (e.g. `isInEoiBundle: true` → "added to EOI bundle" / `false` → "removed from EOI bundle"; never `on`/`off`), enums via the `formatEnum`/`STAGE_LABELS`/`OUTCOME_LABELS` helpers in `src/lib/constants.ts`, currency+amount pairs, dates via `formatDate`.
+  - FK resolution: take a `Record<fkField, displayName>` lookup that callers prefill (mooring number for berthId, user name for assignedTo, client name for clientId, etc.) so values render as "→ Anna Schmidt" not "→ mEcs…".
+- Update `/timeline` (interests) AND the 6 `/activity` route handlers to: (a) collect FK ids per row, (b) batch-resolve in one query per FK type, (c) pass the lookup into the shared formatter. The audit log itself stores IDs — resolution happens at read time so historical entries stay correct even after renames/deletes (in which case fall back to "(deleted yacht)" etc.).
+- Migrate `EntityActivityFeed` to call the same shared formatter on the row's `fieldChanged` + `oldValue`/`newValue` so the strikethrough+arrow rendering uses the same vocabulary.
+- Audit-log writes that have meaningful application context but don't fit the column-diff model (e.g. interest-berth flag toggles, EOI bundle membership changes) probably should set `metadata.type` so the formatter can route to a dedicated phrase ("Added berth A12 to EOI bundle", "Made A12 the primary berth") instead of best-effort diffing.
+
+Acceptance: spot-check the timeline tab on a recently-edited interest, client, yacht, company, and berth. No UUIDs visible; no camelCase field names; no `on`/`off` booleans without context; all enum values render in their human label.
+
+**Done while scoping (cosmetic fix):**
+
+- Vertical-connector overshoot in `InterestTimeline` and `EntityActivityFeed` — both renderers used a container-level absolute line that trailed past the last bubble. Replaced with per-item connectors that omit on `isLast`.
+
+---
+
+## K. Per-port branded login (multi-tenant UX)
+
+The login / forgot-password / set-password screens currently show the
+"first active port" branding via `resolveAuthShellBranding()`, because
+those surfaces have no portId in the URL. With two unrelated ports
+(Port Nimara + Port Amador, no umbrella company) this means whichever
+port was created first wins the login screen for everyone.
+
+**Recommended path: shared instance, Host-header branding.** Run a
+wildcard subdomain (`*.crm.example.com`) into the same Next.js app and
+have middleware derive the active portSlug from the `Host` header.
+`resolveAuthShellBranding()` then takes an optional host argument and
+resolves by slug instead of "first port". Switcher becomes a
+`window.location.assign('https://other-port.crm.example.com/dashboard')`;
+session cookies are scoped to the parent domain so super-admins don't
+re-auth when hopping.
+
+Open work:
+
+- Wildcard DNS + TLS cert (Cloudflare DNS-01 with `*.crm.example.com`).
+- Cookie domain change: `pn-crm.session_token` needs `Domain=.example.com`
+  set in better-auth config.
+- Middleware: read host, resolve portSlug, attach to request headers so
+  the auth-shell branding resolver can use it.
+- Update `resolveAuthShellBranding()` to prefer host-derived port over
+  "first port" fallback.
+- Port-switcher UI: dropdown in topbar that lists ports the user has
+  access to and navigates cross-subdomain.
+- Bootstrap seed: populate `branding_logo_url` / `_email_background_url`
+  / `_app_name` for the default port so fresh deploys aren't blank.
+
+Alternative considered: **N instances, one per port.** Cleaner data /
+deploy isolation but no UX gain over the shared-instance path. Defer
+unless an operator demands independent migrations or data residency.
+
+Size: medium (1–2 days incl. cert + cookie work + seed + switcher).
+
+---
+
+## I. Dashboard widget wishlist
+
+User-driven enhancements to the customizable main dashboard
+(`src/components/dashboard/widget-registry.tsx`). Each entry is a new
+opt-in tile users can add via the widget picker.
+
+- **More website-analytics stats cards** — expand the dashboard widget
+  catalogue with additional Umami-backed tiles users can pick from
+  (e.g. unique visitors, avg session duration, bounce rate, top
+  country, top referrer of the day, mobile vs desktop split,
+  pages-per-visit, returning vs new). Today only `WebsiteGlanceTile`
+  exists. Source data already flows through
+  `src/lib/services/umami.service.ts` and `useWebsiteAnalytics`. Each
+  new tile = one `KpiTile`-shaped component + a registry entry. Size:
+  small per tile, scope grows with the catalogue.
+
+---
+
+## F. Historical audit docs (mostly resolved)
+
+These dossiers drove the audit-fix commit waves on 2026-05-05/06. Items
+not surfaced in §C above were resolved via the `fix(audit): …` commits
+(`588f8bc`, `94331bd`, `a8c6c07`, `5fc68a5`, `da7ede7`, `c5b41ca`,
+`b4fb3b2`, `0f648a9`, `c312cd3`, `0a5f085`, `1a87f28`, `f3143d7`,
+`05babe5`). Keep for historical context:
+
+- [`audit-comprehensive-2026-05-05.md`](./audit-comprehensive-2026-05-05.md) — pre-merge audit (1 CRIT + 18 HIGH at start)
+- [`audit-comprehensive-2026-05-06.md`](./audit-comprehensive-2026-05-06.md) — post-merge audit (1 CRIT + 7 HIGH + 10 MED + 7 LOW)
+- [`audit-frontend-2026-05-06.md`](./audit-frontend-2026-05-06.md) — frontend-only sweep
+- [`audit-missing-features-2026-05-06.md`](./audit-missing-features-2026-05-06.md) — admin-promised-but-unwired features (V1–V12)
+- [`audit-permissions-2026-05-06.md`](./audit-permissions-2026-05-06.md) — permission-gate gaps
+- [`audit-reliability-2026-05-06.md`](./audit-reliability-2026-05-06.md) — transactional integrity / TOCTOU
+- [`berth-feature-handoff-prompt.md`](./berth-feature-handoff-prompt.md) — berth recommender handoff (shipped, kept as reference)
+- [`berth-recommender-and-pdf-plan.md`](./berth-recommender-and-pdf-plan.md) — berth recommender + per-berth PDF plan (Phases 0–8 shipped)
+- [`documenso-integration-audit.md`](./documenso-integration-audit.md) — Documenso integration spec (drives §A)
+- [`website-refactor.md`](./website-refactor.md) — public website cutover plan

docs/POST-AUDIT-FIX-PLAN.md

@@ -0,0 +1,305 @@
+# Post-Audit Fix Plan
+
+Generated 2026-05-14 from two rounds of deep Playwright + API audit on `feat/documents-folders` → `main`.
+
+**Total findings:** 24 fixes + 1 new feature. Grouped by priority. Each entry has impact, file pointer, and effort estimate.
+
+---
+
+## TIER 0 — Already Applied in Working Tree (uncommitted)
+
+Status: **fixed in code, not yet committed**. Commit + push to ship.
+
+### F1. `/api/v1/bootstrap/*` proxy allow-list (task #22)
+
+- **Impact:** Cold-start VPS deploy can't bootstrap its first super-admin. `/setup` page calls `/api/v1/bootstrap/status` which 401s; setup form never renders.
+- **File:** `src/proxy.ts` — added to `PUBLIC_PATHS`.
+- **Effort:** XS.
+
+### F2. Interest detail page 500s on every visit (task #25)
+
+- **Impact:** Sales workflow non-functional. Raw `Date` passed to postgres-js `sql\`${col} >= ${dateVar}\`` template crashes the Bind step.
+- **File:** `src/lib/services/interests.service.ts:566` — switched to `gte(col, date)`.
+- **Effort:** XS.
+
+---
+
+## TIER 1 — Pre-Deploy Blockers (P1)
+
+Ship before any real client touches the system.
+
+### F3. GDPR export 500s — BullMQ rejects job IDs with colons (task #51)
+
+- **Impact:** GDPR Article 15 right-to-access non-functional. Legal/compliance gate.
+- **File:** `src/lib/services/gdpr-export.service.ts:113` — change `jobId: \`gdpr-export:${row.id}\`` → `jobId: \`gdpr-export-${row.id}\``.
+- **Effort:** XS (one char).
+
+### F4. Redis eviction policy is `allkeys-lru` but BullMQ requires `noeviction` (companion to F3)
+
+- **Impact:** Under memory pressure, Redis will evict BullMQ keys; jobs disappear silently.
+- **File:** production Redis config (`maxmemory-policy noeviction`) + the docker-compose redis service.
+- **Effort:** XS (config).
+
+### F5. `deleteBerth()` hard-deletes rows instead of soft-archiving (task #65)
+
+- **Impact:** Permanent data loss on accidental delete. Junction tables CASCADE-vanish. Audit log points to non-existent rows. Public feed could 404 mid-customer-inquiry.
+- **Files:**
+  - `src/lib/services/berths.service.ts:673-685` — replace `db.delete()` with `set archivedAt = now(), archivedBy = userId, archiveReason = input.reason`.
+  - Add filter `isNull(berths.archivedAt)` to all default berth queries (recommender, public feed, list, dashboard heat).
+  - Add restore endpoint `POST /api/v1/berths/[id]/restore` mirroring the interests pattern.
+  - Require `reason` (min 5 chars) before destructive call.
+- **Effort:** M.
+
+### F6. Weak input validation on `/api/v1/clients` (task #50)
+
+- **Impact:** Email format not validated (bounces silently); whitespace-only names accepted (blank chips everywhere); XSS payload stored verbatim (depends on every render path being safe).
+- **Files:**
+  - `src/lib/validators/clients.ts` — add `.email()` refinement on contacts where `channel === 'email'`; trim+min(1) on `fullName`; regex-strip control chars + zero-width chars.
+  - Audit every fullName render path for `dangerouslySetInnerHTML` / pdfme / react-pdf / email template merges and ensure escaping.
+  - Apply similar hardening to yachts, companies, interests, notes, berths, reminders (audit all string fields).
+- **Effort:** S for the obvious zod tweaks, M for the full audit.
+
+### F7. No rate limiting on login (task #68)
+
+- **Impact:** Brute force is wide open. 20 wrong-password attempts in a row all returned 401 with no lockout.
+- **Files:**
+  - `src/lib/auth/` — add a `rateLimit` block to the better-auth config: `{ window: 60, max: 5 }` per IP+email.
+  - Optionally: Redis sliding window via existing ioredis client.
+  - Optionally: per-user lockout table (`auth_lockouts`) after 5 failures, locked 15min.
+- **Effort:** S.
+
+### F8. postgres-js pool corruption causes CONNECT_TIMEOUT (task #46)
+
+- **Impact:** During the audit the dev server twice entered a stuck state where every query 500'd with `CONNECT_TIMEOUT` while the DB was healthy (1/100 connections used). Production VPS will hit this under load.
+- **Files:**
+  - `src/lib/db/index.ts` — add `connect_timeout: 5`, `max_lifetime: 60 * 60`, `idle_timeout: 30`.
+  - Wrap critical-path queries in retry-on-CONNECT_TIMEOUT logic (one retry, then 503).
+  - Consider pgbouncer in front of postgres for production multi-process deployments.
+- **Effort:** S for the postgres-js options, M for full pgbouncer.
+
+---
+
+## TIER 2 — High Impact Architectural / UX
+
+Not strictly deploy-blocking, but each one breaks the UX in observable ways every day.
+
+### F9. Layout-wide duplicate mobile/desktop DOM rendering (task #26)
+
+- **Impact:** Single highest leverage UX bug. EVERY page mounts BOTH responsive layouts; both Radix Tabs providers are concurrently active with `data-state="active"`. Half my click attempts on tabs/filters/popovers went to the wrong layer. Doubled network requests, doubled component state, doubled a11y landmarks.
+- **Files:** the responsive shell (likely `src/components/layout/*-shell.tsx` and detail-page wrappers).
+- **Fix options:** use `useMediaQuery` to mount only one tree; or hoist `<Tabs>` to a single provider and let both layouts consume context.
+- **Effort:** L (architectural refactor across multiple pages).
+
+### F10. Archiving a client doesn't cascade-archive their interests (task #66)
+
+- **Impact:** Orphan refs. Archived clients have active interests; active queries surface them with broken breadcrumbs / silent 404s on drill-in.
+- **Files:** `src/lib/services/clients.service.ts:archiveClient()` — wrap in transaction, archive open interests too. OR extend `activeInterestsWhere()` to filter on `client.archived_at IS NULL`.
+- **Effort:** S.
+
+---
+
+## TIER 3 — Standard Fixes (P3)
+
+UX polish + missing entry points. Each is small, but the sum matters.
+
+### F11. "Mark as won" dialog still says "moves to Completed" (task #27)
+
+- **Impact:** Stale copy from before the 7-stage refactor. Misleads users.
+- **File:** `src/components/interests/won-dialog.tsx` (or similar) — update copy to "marks Won; stage stays at <current>".
+- **Effort:** XS.
+
+### F12. Activity feed + tab count concatenation (task #23)
+
+- **Impact:** "Test Person 1interest", "Interests0", "Click Test Co.company" — unprofessional.
+- **Files:** `src/components/dashboard/activity-feed.tsx` (entity name + type), every detail-page tab count render. Audit log FTS `search_text` should also include entity names.
+- **Effort:** S.
+
+### F13. Bulk-add berths wizard has no UI entry point (task #28)
+
+- **Impact:** Feature built for new-port setup, but invisible. Operator must know the URL.
+- **Files:** Add a "Bulk add" button next to "New berth" on `/[portSlug]/berths`. Add link on `/admin` landing card.
+- **Effort:** S.
+
+### F14. Audit Log page has no UI entry point (task #49)
+
+- **Impact:** Feature built, no nav link. Discovery requires URL knowledge.
+- **Files:** Sidebar Admin section — add "Audit Log" entry under `documents` settings or as its own item, gated by `audit_log.view` permission.
+- **Effort:** S.
+
+### F15. New Yacht dialog only lists clients in owner picker (task #44)
+
+- **Impact:** Data model supports `'client' | 'company'` ownership; UI only lets you pick clients. Cannot create company-owned yacht via UI.
+- **Files:** `src/components/yachts/new-yacht-dialog.tsx` — add owner-type segmented control (Client / Company) above the owner picker; switch data source.
+- **Effort:** S.
+
+### F16. InlineTagEditor "Add tag" focus + create flow (task #45)
+
+- **Impact:** Typing in the tag widget set the CONTACT LABEL instead. Plus no "Create new tag" affordance for new tag names.
+- **Files:** `src/components/shared/inline-tag-editor.tsx`. Fix focus target; surface "Create new: X" as a popover item; orchestrate POST /api/v1/tags then PUT .../tags.
+- **Effort:** S.
+
+### F17. Cross-port (and 404) detail URLs silently render list shell (task #48)
+
+- **Impact:** User pastes a wrong-port URL → API 404s correctly but UI silently shows the list shell. No explicit "not found" message.
+- **Files:** every entity-detail client component — render `<EmptyState title="Not found" />` when GET returns 404. Apply to clients, interests, yachts, companies, berths.
+- **Effort:** M (apply pattern to each detail page).
+
+### F18. Recommender `limit` param ignored (task #69)
+
+- **Impact:** Request with `{"limit": 3}` returned 8 berths. Either param name mismatch or no clamp.
+- **Files:** `src/lib/services/berth-recommender.service.ts` + the recommend-berths validator.
+- **Effort:** XS.
+
+---
+
+## TIER 4 — Polish & UX Reductions (P4)
+
+The `UX EFFICIENCY` list (task #24). Each is small, mostly copy/flow improvements.
+
+### F19. New Client form — primary contact default trap
+
+- Default-checked "Primary contact" with empty email silently rejects on submit. Either don't pre-add OR drop empty contacts on save.
+
+### F20. New Interest dialog — redirect to detail page on create
+
+- Currently returns to the list. Add `router.push('/interests/' + newId)` to land on the workflow page immediately.
+
+### F21. Stage-transition error toast leaks developer language
+
+- "yachtId is required before leaving stage=enquiry" → "Yacht is required before leaving the Enquiry stage."
+- Audit ALL ValidationError + ConflictError + service error messages for user-readable copy.
+
+### F22. Stage menu uses unicode emoji `⚑` as prereq-blocked indicator
+
+- Per user preference (memory: avoid decorative emoji), replace with a Lucide icon (`Lock`, `AlertCircle`, or `FlagOff`).
+
+### F23. Blocked-stage UX — show prereq picker inline
+
+- Clicking a blocked stage currently dismisses with a toast. Better: open the prereq picker inline ("Pick a yacht to leave Enquiry" with combobox right there).
+
+### F24. New Client form — "Country" optional but prominent
+
+- Drop from quick-path OR move to a "More details" disclosure.
+
+### F25. Documents Hub — folder navigation doesn't update URL
+
+- Drilling into a folder updates "Current location" but doesn't change `location.search`. Can't deep-link, browser-back broken, refresh resets to root.
+
+### F26. "Reopen" outcome action silent — no toast
+
+- After clicking Reopen, no feedback. Add `toast.success('Outcome cleared')` or similar.
+
+### F27. Same-stage write returns full body — should be 204
+
+- PATCH /stage with same stage = current stage returns 200 + full interest. Should be 204 No Content (no-op).
+
+### F28. Recommender empty-result UI
+
+- 300ft yacht returns `data: []` — UI Recommendations tab silently shows blank. Should render "No berths match — try relaxing constraints."
+
+### F29. Inbox first-load "Loading..." stuck
+
+- First navigation to /inbox shows "Loading..." indefinitely; subsequent reload renders fine. TanStack Query cache initialization issue.
+
+### F30. Berths in default queries should filter `archivedAt IS NULL`
+
+- Companion to F5 — once soft-delete lands, every default list query must filter archived rows.
+
+---
+
+## NEW FEATURE — Manual Berth Status Catch-Up Workflow (task #67)
+
+User-requested. Foundation already exists (column `berths.status_override_mode` is in schema but never written).
+
+### Phase 1 — Wire the status_override_mode field
+
+- `updateBerthStatus()` sets `status_override_mode = 'manual'` when called via the user-facing API.
+- `berth-rules-engine.ts` triggers set `status_override_mode = 'automated'`.
+- When a backing interest is successfully created and links the berth, clear `status_override_mode` back to null in the same transaction; set `status_last_changed_reason` to "Reconciled via interest [id]".
+- **Effort:** S.
+
+### Phase 2 — Visual indicator
+
+- On berth list rows: small chip "Manual" next to the status badge when `status_override_mode = 'manual'` AND no active interest is linked.
+- On berth detail page header: badge + tooltip showing last reason, user, when.
+- On dashboard "Berth Heat" widget: filter or annotate the manual rows.
+- **Effort:** S.
+
+### Phase 3 — Reconciliation Queue page
+
+- New page `/[portSlug]/admin/berths/reconcile`.
+- Lists every berth where `status_override_mode = 'manual'` and no active interest. Sortable by `status_last_modified DESC`.
+- Each row links to the catch-up wizard.
+- Sidebar Admin section gets a link with the queue count badge.
+- **Effort:** S.
+
+### Phase 4 — Catch-Up Wizard (the core piece)
+
+- Multi-step modal. Steps:
+  1. **Pick or create client** — combobox + inline quick-create (name + email only).
+  2. **Pick or create yacht** — optional if pre-EOI; quick-create with name + dimensions.
+  3. **Pick the matching stage** — based on current berth status:
+     - `under_offer` → enquiry / qualified / nurturing / eoi (default eoi)
+     - `sold` → contract + outcome=won
+     - Allow override.
+  4. **Upload existing docs** — EOI PDF, contract PDF, reservation form. Each auto-filed to the right entity folder.
+  5. **Optional payments** — if status=sold, prompt for deposit/full amount.
+  6. **Review + submit.** On submit, transaction:
+     - Create/select client + yacht
+     - Create interest at chosen stage with `assigned_to = current user`
+     - Upsert `interest_berths(is_primary=true, is_specific_interest=true, is_in_eoi_bundle=true)`
+     - Upload + attach files
+     - Insert payments
+     - Set `berth.status_override_mode = null` + `status_last_changed_reason = 'Reconciled via interest [id]'`
+     - Audit log single "reconcile" event linking berth + new interest.
+- **Effort:** M (wizard) + S (transaction service) + S (API endpoint). Total M-L.
+
+### Phase 5 — Entry points
+
+- Berth list row menu → "Catch up..."
+- Berth detail page next to manual badge → "Catch up"
+- Dashboard widget "Manual statuses awaiting reconciliation" (count + link)
+- Sidebar link
+- **Effort:** S.
+
+### Total feature effort: M-L (2-3 dev days).
+
+---
+
+## What I Tested in Round 2 (15 deep journeys, all passed structural validation)
+
+| Journey                                      | Result                                                                                      |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| State machine — stage skipping               | ✓ Rejects forward/backward jumps with friendly copy + override path                         |
+| Double outcome write                         | ⚠ Allowed (won→lost flips freely); audit log just says "update" — should tag outcome change |
+| Cascade — delete with dependents             | ✗ Inconsistent: clients soft-archive, **berths HARD-delete**, companies soft-archive        |
+| Manual berth status without backing interest | ✗ Foundation column exists, never written                                                   |
+| Unicode (emoji/RTL/zero-width)               | ⚠ Emoji + RTL OK; zero-width chars NOT stripped (search blind spot)                         |
+| Storage / file upload magic-byte             | ✓ Rejects JPEG/HTML disguised as PDF                                                        |
+| Documenso webhook idempotency                | ✓ Timing-safe + rate-limited bad-secret check                                               |
+| Berth recommender edge cases                 | ⚠ Empty dims OK; extreme dims return empty; **limit param ignored**                         |
+| Email body XSS via markdown                  | ✓ Escape-first-then-rules, javascript: URLs stripped                                        |
+| Public berth feed correctness                | ✓ Port allow-list, archive filter, status enum validation                                   |
+| Rate limiting / abuse                        | ✗ Login: no rate limit; public feed: CDN-cached                                             |
+| Health check + dependency probes             | ✓ Anonymous minimal payload, secret-mode for website-intake                                 |
+| Direct ID enumeration                        | ✓ Uniform 404 — no leak                                                                     |
+| Cross-port API access                        | ✓ 404 at API; **silent at UI**                                                              |
+| CSRF — fake Origin                           | ✓ Prod-only protection — dev intentionally skips                                            |
+
+---
+
+## Recommended Commit Sequence
+
+1. **Squash-commit T0 fixes** (F1 + F2) — these are deploy-blockers already applied. Push to main.
+2. **T1 batch commit** (F3, F4, F5, F6, F7, F8) — pre-deploy blockers. Single commit per fix for clean review.
+3. **T2** (F9, F10) — schedule for next sprint (F9 is architectural).
+4. **T3** (F11-F18) — knock out in a few hours. Quick polish wave.
+5. **T4** (F19-F30) — UX list. Bundle into a single PR over a few sessions.
+6. **NEW FEATURE — Catch-Up Workflow** — 2-3 dev days. Higher business value than T2; prioritize after T1.
+
+---
+
+## Risk Notes
+
+- The audit polluted the dev DB with test entities: `Smoke Test Client (renamed)`, `Aurora Marine Holdings Ltd`, `Bad Email Test`, `Phone Test`, `Robert'; DROP TABLE clients`, `François 🏄 المعتمد`, `محمد عبد الله`, `CSRF Test`, etc. Also **hard-deleted berth A1 in port-amador** + soft-archived Test Person 1. Consider `pnpm db:reseed:synthetic` before the next clean run.
+- The Smoke Test Client interest had `outcome=lost_other` set during the won-then-lost test (R2-B). Audit log preserved both transitions but with action="update" not action="outcome_change".

docs/POST-AUDIT-SPEC-2026-05-18.md

@@ -0,0 +1,251 @@
+# Post-Audit Implementation Spec — 2026-05-18
+
+Captures the design decisions from the post-audit conversation so the
+implementation can start without re-litigating the trade-offs. Each
+section ends with an Effort estimate.
+
+---
+
+## 1. EOI document field overrides
+
+### Goal
+
+When generating an EOI, the rep should be able to override pre-filled
+field values (contact info, addresses, yacht details) while preserving
+the canonical record. Manual entries persist as tracked secondary
+values so future EOIs can pick them up from a dropdown.
+
+### Design
+
+**Client contact channels (email, phone):**
+
+- The EOI form's email/phone fields render as a dropdown of every
+  `client_contacts` row for the linked client, defaulting to the primary
+  for each channel.
+- Rep types a brand-new value → on EOI save, a new `client_contacts`
+  row is created with `is_primary=false`, `source='eoi-custom-input'`,
+  `source_document_id=<doc-id>`. Labelled `[EOI]` on the client detail
+  page contacts panel.
+- The current EOI uses the new value; future EOIs default to primary
+  unless the rep explicitly picks the new row from the dropdown.
+- A "Set as default for future documents" toggle on the EOI form
+  promotes the new value to `is_primary=true` (demoting the prior
+  primary).
+
+**Client addresses:** Same pattern via `client_addresses` (which is
+already multi-value per CLAUDE.md).
+
+**Yacht name + dimensions:** Yachts are single-valued; rep needs a
+different yacht → opens a "Create yacht" modal inline, fills in name +
+dims for the new yacht record, linked to the same client/interest, tagged
+`eoi-generated`. The EOI uses the new yacht. The original yacht is
+unchanged. (No yacht_aliases / yacht_dimension_overrides table.)
+
+**Interest-specific fields (rare):** Same dropdown pattern via the
+existing fields on the interest record. Custom entries promote-or-stay
+following the toggle.
+
+**Audit trail:** Every override action (create-non-primary, promote-to-
+primary, create-yacht-from-eoi) emits an audit_log row with action
+`eoi_field_override` and metadata identifying the source document.
+
+**Per-document override (no record-side write):** Doc-level overrides
+remain available as a checkbox — when ticked, the value lives only on
+the doc and never touches client_contacts. Default is unchecked.
+
+### Schema additions
+
+- `client_contacts.source text` — extend the existing enum: `'manual'`,
+  `'imported'`, `'eoi-custom-input'`.
+- `client_contacts.source_document_id text references documents(id)
+on delete set null` — surfaces the originating EOI.
+- `client_addresses.source` + `source_document_id` (mirror).
+- `yachts.source` + `source_document_id` (mirror; nullable so existing
+  records aren't disturbed).
+- `audit_actions` enum gains `eoi_field_override` + `promote_to_primary`.
+
+### UI
+
+- EOI Generate drawer: each editable field becomes either a `<Combobox>`
+  (when multi-value) or `<Input>` + "Save as new …" hint (yacht).
+- Below each field: `[ ] Use only for this EOI` checkbox (default off)
+  - `[ ] Set as default for future docs` checkbox (default off).
+- Client + Yacht detail panels: `[EOI]` badge on non-primary rows;
+  "Set as primary" action on each.
+
+### Effort
+
+~1–1.5 weeks. Bundle the schema + EOI form + client/yacht detail UI
+into one PR (user picked "All at once").
+
+### Open implementation questions
+
+- The yacht-creation inline modal needs the existing YachtForm wired in;
+  on save it tags the new yacht with the eoi-generated marker. Tag the
+  yacht via `tags`? Or a dedicated `source` column? Recommend column
+  for queryability.
+- Should `[EOI]` badges fade out after a TTL or stay forever? Recommend
+  forever — the rep deliberately chose this label.
+
+---
+
+## 2. Reminders
+
+### Goal
+
+Reps can: per-interest follow-up cadence with note + time, standalone
+tasks (no entity), assignable-to-another-rep tasks. The existing rich
+`reminders` table holds the canonical data; the per-interest cadence
+on the `interests` row stays for backward compat as a quick-tick.
+
+### Design
+
+**Per-interest cadence (kept):**
+
+- `interests.reminderEnabled` + `interests.reminderDays` retained.
+- New: `interests.reminderNote text NULL` — surfaced in the
+  notification body + the inbox row.
+- The cadence fires a row into `reminders` on each tick (with
+  `interest_id` set) instead of the current ad-hoc notification flow,
+  unifying the inbox.
+
+**Standalone tasks (new):**
+
+- Rich `reminders` table already has every column we need (title, note,
+  priority, due_at, assigned_to, snoozed_until, google_calendar_event_id).
+- Two UI surfaces (both submit to the same dialog component):
+  - RemindersInbox top-right `[+ New task]` button.
+  - Per-entity detail page (interest, client, berth, yacht): `[+ Task]`
+    button inside the existing Reminders section. Linked-entity field
+    pre-filled and locked.
+- The dialog: Title (required), Note (optional), Due date+time,
+  Priority, Assign to (default = current rep), Linked entity
+  (optional dropdown for inbox surface; locked for per-entity).
+
+**Time-of-day:**
+
+- New user-settings field: `digest_time_of_day time, default '09:00'`.
+  Stored in user_profiles.
+- Per-reminder override: each reminder's `due_at` carries the exact
+  firing moment (existing column). The dialog defaults the time picker
+  to the user's `digest_time_of_day` but lets them override per row.
+- Worker scheduler: a 15-min cron tick scans `reminders` for rows whose
+  `due_at <= now() AND fired_at IS NULL`, fires the notification, sets
+  `fired_at`.
+
+**Assignment:**
+
+- `reminders.assigned_to` (existing). Dialog has an "Assign to" picker
+  (port users via /api/v1/admin/users/picker), defaults to current user.
+- Inbox shows the assignee chip when not me; filter `[Mine | All my port]`.
+
+### Schema additions
+
+- `interests.reminder_note text NULL`
+- `user_profiles.digest_time_of_day time NOT NULL DEFAULT '09:00'`
+- `reminders.fired_at timestamptz NULL` (new — drives the worker idempotency)
+- No new tables. The existing `reminders` table covers standalone tasks.
+
+### UI
+
+- `<CreateReminderDialog>` component (shared).
+- RemindersInbox: `[+ New task]` button → dialog (linked entity blank).
+- Interest / client / berth / yacht detail pages: existing Reminders
+  section gains `[+ Task]` button → dialog (linked entity pre-filled,
+  field disabled).
+- Settings page: time picker for "default reminder time" → writes
+  `user_profiles.digest_time_of_day`.
+
+### Effort
+
+~3–4 days. Schema migration + dialog component + 4 entity-page wires
+
+- worker scheduler refactor + inbox filter.
+
+---
+
+## 3. Supplemental info form — per-port setting
+
+### Goal
+
+The "Send supplemental info form" link in the auto-email should resolve
+to the marketing site when configured; fall back to a CRM-hosted route
+otherwise. Confirmed: per-port setting.
+
+### Design
+
+- New system_settings key: `supplemental_form_url` (per-port, optional,
+  text). Defaults to NULL.
+- Link generator in the email service:
+  ```ts
+  const url = cfg.supplementalFormUrl
+    ? `${cfg.supplementalFormUrl}?token=${raw}`
+    : `${env.APP_URL}/supplemental/${raw}`;
+  ```
+- Existing `/supplemental/[token]` CRM route stays as the fallback. Add
+  a "Loading…" skeleton + dual-mode copy ("If you don't see your
+  details, contact your rep").
+- Admin UI: add the field to `/admin/email/page.tsx` (or a new
+  `/admin/supplemental/page.tsx`) — single text input with the help
+  hint "Leave blank to use the built-in CRM page."
+
+### Effort
+
+~2 hours (single setting + 1 admin field + link resolver).
+
+---
+
+## 4. Documenso phases 2 → 7 → 5 (you picked Phase 7 first)
+
+### Phase 7 — Project Director RBAC (~1h)
+
+- Add "Linked to CRM user" dropdown in `/admin/documenso/page.tsx`
+  pointing at the existing `developer_user_id` + `approver_user_id`
+  settings.
+- Auto-fill name/email from the selected user (read via
+  /api/v1/admin/users/picker).
+- Webhook handler in `src/app/api/webhooks/documenso/route.ts`: when an
+  event arrives for the developer or approver, also fire an in-CRM
+  `documenso:signed` notification routed to the linked user's CRM
+  notifications inbox.
+
+### Phase 2 — Webhook handler enhancement (~3–4h)
+
+- Cascading "your turn" emails: when signer N completes, fire an
+  invitation email to signer N+1 (sequential signing only).
+- On-completion PDF distribution: when status flips to COMPLETED,
+  email the signed PDF to all `documents.completion_cc_emails`.
+- Token-based recipient matching: prefer `signing_token` over email
+  for webhook → signer resolution (handles aliased emails).
+- Idempotency lock: replace the current body-hash dedup with a
+  composite `(documensoDocumentId, recipientEmail, eventType)` unique
+  constraint on documentEvents.
+- Schema is already in place from Phase 1 — this is pure handler logic.
+
+### Phase 5 — Embedded signing URL verification (~1–2h)
+
+- Confirm the marketing site's `/sign/<type>/<token>` page handles
+  every signer-role × documentType combo.
+- Update `signerMessages` map in the signing-invitation email template
+  to surface role-specific copy.
+- Apply nginx CORS block from the integration audit (constrain
+  Documenso webhook origin).
+
+### Effort total
+
+~6–7h across the three phases. Phase 4 (field placement UI, 10–14h)
+stays deferred — covered separately by the PDF template editor work
+you picked Phases 1+2 for.
+
+---
+
+## What I'll build first
+
+Per your sequencing:
+
+1. Documenso Phase 7 (~1h) — unblock the linked-user signing UX.
+2. Supplemental form per-port setting (~2h) — small win.
+3. Documenso Phase 2 (~3–4h) — meaningful UX improvement.
+4. Documenso Phase 5 (~1–2h) — security + role copy.
+5. EOI field overrides + reminders (~1.5 weeks combined) — the big
+   ones, picked up after the Documenso quick wins land.

docs/PRE-DEPLOY-PLAN.md

@@ -0,0 +1,243 @@
+# Pre-deploy plan — locked 2026-05-14
+
+Source of truth for everything between today and initial VPS deployment.
+Captures every decision reached in the 2026-05-14 planning session, plus
+the implementation order, deferred items, and operator checklist.
+
+If a future agent or session resumes this work, **start here** — do not
+re-litigate the decisions below without checking the transcript context
+that produced them.
+
+---
+
+## 1. Decisions
+
+### 1.1 Hot-path correctness (numbers users see)
+
+| #   | Item                              | Decision                                                                                                                                                                                                                                                                                                              | File(s) impacted                                                                                                          |
+| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Pipeline value mixed-currency     | Convert each `berths.price` to the port-default currency at display time via `currency.service`, then sum.                                                                                                                                                                                                            | `src/lib/services/dashboard.service.ts`, `src/components/dashboard/*`                                                     |
+| 2   | "Active interest" definition      | `archivedAt IS NULL AND outcome IS NULL` (strictest). Won deals are CLOSED, not active. Extract single `activeInterestsWhere(portId)` SQL helper; route every site through it.                                                                                                                                        | Sweep target — see § 2.1 for list.                                                                                        |
+| 3   | Occupancy source of truth         | `berth.status = 'sold'`. KPI tile + revenue PDF + analytics timeline all derive from this one source.                                                                                                                                                                                                                 | `src/lib/services/dashboard.service.ts`, `src/lib/services/analytics.service.ts`, `src/lib/services/report-generators.ts` |
+| 4   | Revenue PDF shape                 | Two side-by-side cards on the same page: "Completed revenue (won, gross)" + "Forecast revenue (pipeline-weighted)". Stacks gracefully on portrait.                                                                                                                                                                    | `src/lib/services/report-generators.ts`                                                                                   |
+| 4.5 | Multi-berth EOI mooring rendering | Populate the existing Documenso `Berth Number` form field with `eoiBerthRange` for both single- and multi-berth EOIs (single-berth output is identical to today via `formatBerthRange(['A1']) === 'A1'`). Drop the unused `Berth Range` payload key + AcroForm field + merge token. No Documenso admin action needed. | `src/lib/services/documenso-payload.ts`, `src/lib/pdf/fill-eoi-form.ts`, `src/lib/templates/merge-fields.ts`, `CLAUDE.md` |
+
+### 1.2 Security / deploy gates
+
+| #   | Item                                          | Decision                                                                                                                                                                                                                    |
+| --- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 5   | Portal activation + password-reset token URLs | Switch `?token=ABC` → `#token=ABC` (URL fragment). Fragment never hits server logs, proxies, or `Referer` header. Touches email templates + `/portal/activate` + `/portal/reset-password` + the `set-password` page reader. |
+
+### 1.3 Email infrastructure refactor
+
+| #   | Item                            | Decision                                                                                                                                                                                                                                                                                                                                            |
+| --- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 6   | Admin "Signature HTML" field    | **Delete** it. Currently writes `email_signature_html` to settings; `shell.ts` only reads `emailFooterHtml`. Footer covers brand sign-off; signatures are semantically per-user (separate future feature if asked).                                                                                                                                 |
+| 7   | Per-category send-from routing  | New admin matrix on `/admin/email`: each email category (account activation, password reset, notification digest, EOI signing request, brochure send, berth-PDF send, signed-doc completion, sales send-out, manual rep compose) gets a sender dropdown (`noreply` / `sales`). Sales option auto-disabled when sales SMTP/IMAP creds aren't set.    |
+| 8   | Bounce monitoring               | Per-port admin-configurable IMAP polling of one or more sender mailboxes. Parses DSN bounce notifications via `mailparser`. Writes to new `email_bounces` table, flags the original `document_send` / `notification` / `email_thread` message as bounced, and emits an in-app notification to the assigned sales rep when a _client_ email bounces. |
+| 9   | Attachment threshold compose UI | On the manual-compose dialog (brochure send, berth-PDF send, rep custom email), show a banner on any attached file above `email_attach_threshold_mb` that says "will be sent as a 24h signed-link download instead of inline attachment". Also audit current default threshold (10MB) against typical SMTP provider caps.                           |
+
+### 1.4 Schema additions
+
+| #   | Item                                 | Decision                                                                                                                                                                                                                                                                            |
+| --- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 10  | `berths.archived_at` column          | Add `archived_at` (timestamp, nullable) + partial index on `(port_id) WHERE archived_at IS NULL`. Filter `/api/public/berths` to exclude archived. Add `<ArchiveBerth>` action in berth detail header (soft-delete with audit log).                                                 |
+| 11  | `clients.metadata.source_inquiry_id` | Add field for inquiry → client linkage so the conversion funnel chart can attribute won deals back to the originating inquiry.                                                                                                                                                      |
+| 12  | `email_bounces` table                | Bounce monitoring storage — see #8. Columns: `id`, `port_id`, `mailbox_address`, `bounced_address`, `original_send_type` (enum: `document_send` / `notification` / `email_thread`), `original_send_id`, `dsn_status`, `dsn_action`, `dsn_diagnostic`, `received_at`, `raw_message`. |
+| 13  | Bulk-berth UX                        | 2-step wizard for new-port setup. Step 1: pick dock letter + range + tenure (only genuinely-standard defaults). Step 2: editable table with "apply to selected" multi-row actions + Excel-style drag-fill on numeric columns. Step 3 from earlier rounds folded in.                 |
+
+### 1.5 UX features
+
+| #   | Item                               | Decision                                                                                                                                                                                                                                                                                                        |
+| --- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 14  | "Mark as signed externally" action | On contract / reservation tabs: new action that records the document as signed without uploading a file. Captures optional reason in a warning modal. Advances pipeline + writes audit log. UI shows "⚠ No file on record — signed externally" indicator. Reps can later upload the file if they obtain a copy. |
+| 15  | Contract paper-upload endpoint     | Clone the existing EOI `external-eoi` upload flow into `external-contract` and `external-reservation` endpoints. Mirrors the current EOI ergonomics.                                                                                                                                                            |
+| 16  | Inquiry P-4.5 wire-up              | Make `/clients/new?prefill_*&inquiry_id=...` hydrate the create-client form from the searchParams **and** persist `inquiry_id` to `clients.metadata.source_inquiry_id`. Conversion funnel chart depends on this linkage.                                                                                        |
+| 17  | Quick brochure/PDF download        | Add "Download" buttons on client detail header, interest detail header, berth detail header. Each downloads the current brochure (port-default) / berth PDF / signed contract from storage so the rep can attach to their own email or messenger app.                                                           |
+| 18  | Per-user reminder digest schedule  | Build the simple version of `scheduler.ts:44` placeholder. User-settings dropdown for digest time + days-of-week. Falls back to port-default when unset.                                                                                                                                                        |
+| 19  | Documents tab N+1 batch fix        | Replace the 4-call sequential walk in `listFilesAggregatedByEntity` (direct + company + yacht + client) with a single UNION query keyed by entity-relationship. Target: opening Documents tab on a busy client ≤500ms.                                                                                          |
+
+### 1.6 Investor dashboard charts (toggleable widgets)
+
+Priority order. Each chart ships as a separate widget integrated into the existing widget-customization system; disabled by default for reps, enabled by default for admins.
+
+| #   | Widget                                     | Notes                                                                                                                                                                                                  |
+| --- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 20  | Total pipeline value of all berths         | Single big number (port-default currency, conversion at display). Weekly-change sparkline below. Re-uses the #1 currency-conversion helper.                                                            |
+| 21  | Berth interest heatmap + ranked-table view | Heatmap shows pier-style grid colored by active-interest count per berth. Paired with a sortable ranked-table view of the same data — table is what exports cleanly to PDF/CSV. Both views toggleable. |
+| 22  | Pipeline velocity over time                | Stacked area chart: count of interests in each pipeline stage, weekly. Investors see whether deals are advancing or stalling.                                                                          |
+| 23  | Conversion funnel by lead source           | Enquiry → qualified → EOI → contract → won, broken down by `lead_source`. Depends on #16 (inquiry → client linkage) for full attribution.                                                              |
+
+### 1.7 Mechanical sweeps
+
+| #   | Item                                  | Decision                                                                                                                                                                                                                                                                                                                                                                                                           |
+| --- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 24  | "Deal" → "interest" terminology sweep | Full sweep. Updates: admin description copy (`/admin/qualification-criteria`, `/admin/documenso`), `bulk-archive-wizard.tsx` placeholders, `smart-archive-dialog.tsx`, `client-columns.tsx` comments, and the API route path `/api/v1/berths/[id]/deal-documents` → `/api/v1/berths/[id]/interest-documents`. Route rename includes caller updates + a 301 redirect on the old path for any external integrations. |
+
+---
+
+## 2. Implementation order
+
+Branch: **`main`** (feat/documents-folders has been fast-forwarded into main; new work continues on main directly).
+
+Test strategy: TDD-where-meaningful (services with behavioral changes — active-interest helper, currency converter, DSN parser). UI and mechanical sweeps covered by full vitest + tsc + lint + playwright smoke at the end.
+
+### 2.1 Step 1 — Money math sweep (highest leverage)
+
+Extract `activeInterestsWhere(portId)` helper. Sweep these call sites:
+
+- `dashboard.service.ts` (already self-consistent, replace inline `isActiveInterest`)
+- `client-archive-dossier.service.ts:266-267`
+- `client-restore.service.ts:189-190, 215`
+- `client-archive.service.ts:214-215`
+- `reminders.service.ts:424`
+- `berths.service.ts:173-174` (recommender feasibility check — verify semantics still match)
+- `interests.service.ts:1161-1162, 196, 361`
+- `report-generators.ts:63, 85, 121`
+
+Then:
+
+- Pipeline value currency conversion (`dashboard.service.ts:35-47`)
+- Occupancy: switch analytics timeline to `berths.status = 'sold'` (`analytics.service.ts:195`)
+- Revenue PDF: two-card layout, weighted forecast + won-gross side-by-side (`report-generators.ts:109-150`)
+
+Estimated effort: ~half day. Single coherent commit set tagged `feat(reporting): canonical active-interest + occupancy + currency-aware pipeline value`.
+
+### 2.2 Step 2 — Email infrastructure refactor
+
+- Drop `email_signature_html` setting + admin field (~10 min)
+- Per-category send-from routing matrix (~3-4h)
+- Bounce monitoring infrastructure (~6-8h): `email_bounces` table migration, IMAP poller worker, DSN parser, in-app notification on bounce, admin UI for sender configuration
+- Attachment threshold compose banner + threshold default audit (~1h)
+
+Estimated effort: ~1 day. Multi-commit.
+
+### 2.3 Step 3 — Schema additions
+
+Single migration + service work:
+
+- `0065_pre_deploy_schema.sql`: `berths.archived_at`, `clients.metadata` (already JSONB — convention update only), `email_bounces` table.
+- Services + admin UI for archive berth + filter on public feed.
+
+Estimated effort: ~2h.
+
+### 2.4 Step 4 — UX features
+
+- Externally-signed mark (contract + reservation tabs) + audit log + UI indicator
+- Contract + reservation paper-upload endpoints (clone EOI flow)
+- Inquiry P-4.5 wire-up (prefill form + persist inquiry_id)
+- Quick brochure/berth-PDF download buttons (3 surfaces)
+- Per-user reminder digest schedule
+- Documents tab N+1 batch query fix
+
+Estimated effort: ~1 day. Multi-commit.
+
+### 2.5 Step 5 — Bulk-berth wizard
+
+Dedicated commit. New `/admin/berths/bulk-add` route + 2-step wizard component + smart-helpers (apply-to-selected, drag-fill). ~half day.
+
+### 2.6 Step 6 — Investor dashboard charts
+
+Four toggleable widgets, each its own commit. ~1 day total. Depends on Step 1 (currency converter) and Step 3 (inquiry linkage).
+
+### 2.7 Step 7 — Terminology sweep
+
+Mechanical. Run last to minimize merge churn. ~2h.
+
+### 2.8 Step 8 — Portal token fragment switch
+
+Dedicated commit. Email template URL builder, page-side fragment readers, Better Auth integration test. ~1h.
+
+### 2.9 Step 9 — NocoDB inspection complete: simulator DEFERRED
+
+NocoDB `Interests` carries only the current `Sales Process Level`
+single-select + a handful of point-in-time event timestamps
+(`EOI Time Sent`, `Time LOI Sent`, `clientSignTime`,
+`developerSignTime`, `EOI_Completed_At`, `finalized_document_sent_at`)
+scattered as text fields. There is **no dedicated stage-change
+history table** — only the most recent stage value survives.
+
+The recommender simulator's tier-ladder + heat-score logic depends on
+"how long did this deal sit at each stage" and "which stage did past
+deals make it furthest to before falling through." Without an
+advancement timeline that's not recoverable: every imported interest
+collapses to one data point.
+
+**Decision (2026-05-14):** defer the simulator until production
+accumulates ~10+ won deals under the new pipeline — then the simulator
+can replay against real CRM history. The existing per-port heat-weight
+tuning UI in `/admin/berth-recommender` is sufficient for v1 launch.
+
+---
+
+## 3. Deferred items (will not block deploy)
+
+### 3.1 External / operator actions (your side)
+
+- **Coordinate website cutover env vars**: generate shared secret with `openssl rand -hex 32`, set `CRM_INTAKE_SECRET` on the website and `WEBSITE_INTAKE_SECRET` on the CRM, wire website's berth-map fetch + inquiry-submit + health probe per `docs/website-cutover-runbook.md`.
+- **Legal review of right-to-be-forgotten scope** — anonymize vs true-delete decision. Mechanical fix once policy is set.
+- **Documenso v2 endpoint audit against live v2 instance** — verify `/api/v2/envelope/delete` shape, webhook payload (`documentId` vs `id`), `recipientId` vs `token`. Needs a live v2 instance.
+
+### 3.2 Deferred indefinitely (no current trigger)
+
+- Bulk import queue worker (`src/lib/queue/workers/import.ts`) — superseded by bespoke migration scripts. Delete placeholder when the comprehensive NocoDB migration ships.
+- Auto-calibration of berth-recommender weights — depends on accumulating ≥10 won deals in the new system before it produces meaningful results.
+
+### 3.3 Comprehensive NocoDB → CRM migration
+
+**Separate workstream** — its own multi-session project. Scope:
+
+1. Pull every row from legacy NocoDB via MCP.
+2. Audit messy MinIO storage; tie loose signed PDFs to client/interest/yacht where ownership is recoverable.
+3. Carry over historical Documenso documents (per-port API key + envelope IDs).
+4. Map legacy schema → current schema; fill obvious data gaps where the right answer is unambiguous.
+5. Dry-run + apply against prod DB at initial startup.
+
+Not on the pre-deploy checklist below — handled as a dedicated planning session before the first port-data import.
+
+---
+
+## 4. Pre-deploy operator checklist
+
+In rough order. Tick as completed.
+
+### 4.1 External (operator side)
+
+- [ ] Generate `WEBSITE_INTAKE_SECRET` via `openssl rand -hex 32`; configure both CRM and website to use it.
+- [ ] Coordinate website-cutover plan with website repo per `docs/website-cutover-runbook.md`.
+- [ ] Provision IMAP credentials for `noreply@portnimara.com` (and `sales@portnimara.com` if applicable) so bounce monitoring works at boot.
+- [ ] Provision SMTP credentials for both sender addresses; verify each can actually send.
+- [ ] DNS + SSL for the CRM domain.
+- [ ] Decide RTBF policy (anonymize vs true-delete) with legal; document in `docs/runbooks/`.
+
+### 4.2 CRM side (run after code work is complete)
+
+- [ ] `pnpm exec vitest run` — all pass.
+- [ ] `pnpm exec tsc --noEmit` — clean.
+- [ ] `pnpm exec eslint .` — clean.
+- [ ] `pnpm exec playwright test --project=smoke` — passes.
+- [ ] `pnpm db:migrate` against a fresh prod-shaped DB — runner ships in commit `544b129`; verify it actually runs `CREATE INDEX CONCURRENTLY` statements.
+- [ ] `pnpm tsx scripts/migrate-storage.ts` if switching from filesystem → s3 storage backend.
+- [ ] Verify `MULTI_NODE_DEPLOYMENT=true` is set if web + worker run on separate nodes (filesystem backend refuses to start otherwise).
+- [ ] Confirm `EMAIL_REDIRECT_TO` is **unset** in production (`src/lib/env.ts:110` refuses to start otherwise).
+- [ ] Confirm `DOCUMENSO_API_URL` is bare host (no `/api/v1` suffix) and matches the live Documenso version's `DOCUMENSO_API_VERSION`.
+- [ ] Verify `/api/public/health?X-Intake-Secret=...` returns 200 with `checks: { db: 'ok', redis: 'ok' }`.
+
+---
+
+## 5. What's NOT in this plan
+
+Items explicitly out of scope for this deploy:
+
+- IMAP-based two-way email sync — feature scope decision, anti-automation stance.
+- AI features (semantic search, auto-summarize, anomaly detection) — anti-automation stance.
+- `.toLocale*` → `formatDate()` sweep (93 sites) — opportunistic as files are touched.
+- `drizzle-zod` adoption for the remaining ~28 validators — opportunistic.
+- Reports system + admin-composable report templates (`audit-followups Wave 11.C`) — post-deploy feature work.
+- Manual client form expansion (`Wave 11.A`) — post-deploy feature work.
+- Inquiry triage auto-classification (`Wave 11.F`) — post-deploy feature work.
+- Per-port email branding admin UI (`Wave 11.G`) — post-deploy feature work.
+
+---
+
+_Last updated: 2026-05-14._

docs/admin-ux-backlog.md

@@ -0,0 +1,196 @@
+# Admin / settings UX backlog — STATUS
+
+Living tracker for the admin/UX backlog. Items are marked DONE or
+REMAINING based on what landed in the autonomous-push session.
+
+---
+
+## DONE in the autonomous push
+
+### Foundations
+
+- **Currency API verified end-to-end**. `scripts/test-currency-api.ts`
+  fetches live Frankfurter rates → upserts → reads back → converts.
+  Inverse-rate drift confirmed at ≤0.001.
+- **Storage abstraction audit complete**. Every byte path
+  (signed EOIs, contracts, brochures, berth PDFs, files, avatars,
+  branding logos) goes through `getStorageBackend()`. `/api/ready`
+  and the system-monitoring health probe now check the active
+  backend (S3 or filesystem) instead of always probing MinIO.
+
+### User settings
+
+- Country + Timezone selectors with cross-defaulting + auto-detect
+  banner ("Looks like you're in Europe/Paris — Update?")
+- Email change with verification flow (`user_email_changes` table,
+  `/api/v1/me/email/confirm/<token>`, `/api/v1/me/email/cancel/<token>`)
+- Password reset triggered via better-auth `requestPasswordReset`
+- Profile photo upload + crop (square 256×256) via shared
+  `<ImageCropperDialog>` + `/api/v1/me/avatar`
+
+### Branding
+
+- Logo upload + crop modal in admin/branding (uses the same shared
+  cropper, persists via `/api/v1/admin/settings/image` → storage backend)
+- Email header/footer HTML defaults injectable via "Insert default" button
+- Brand colour picker, app-name field, logo URL all in one card
+
+### Storage admin
+
+- New layout: S3 config form FIRST, swap action SECOND
+- Test connection button before any switch
+- Two-button switch: "Switch + migrate" vs "Switch only" with warning modal
+- `runMigration()` honours `skipMigration` flag
+
+### Backup management
+
+- Real `/admin/backup` page driven by new `backup_jobs` table
+- `runBackup()` service spawns `pg_dump --format=custom`, streams to
+  active storage backend, records size + path
+- Download button presigns the .dump for offline restore
+- Super-admin gated
+
+### AI admin panel
+
+- Dedicated `/admin/ai` page consolidating master switch +
+  monthly token cap + provider credentials
+- Per-feature settings (OCR, berth-PDF parser, recommender)
+  linked from the same page
+
+### Onboarding
+
+- Real `/admin/onboarding` page with auto-checked steps
+- Reads each setting key + lists endpoint (roles / users / tags) to
+  decide completion
+- Manual checkboxes for steps without an auto-detect signal
+- Progress bar + "Mark done"/"Mark incomplete" buttons
+- State persisted in `system_settings.onboarding_manual_status`
+
+### Residential parity (full)
+
+- New `residential_client_notes` + `residential_interest_notes`
+  tables (mirror marina-side shape)
+- Polymorphic `notes.service.ts` extended with two new entity types
+  through verifyParent + listForEntity + create + update + delete
+- New `<NotesList>` accepts `residential_clients` /
+  `residential_interests` entity types
+- Activity endpoints: `/api/v1/residential/clients/[id]/activity` +
+  `/api/v1/residential/interests/[id]/activity`
+- Notes endpoints: 4 new routes covering GET/POST/PATCH/DELETE
+- `residential-client-tabs.tsx` + `residential-interest-tabs.tsx`
+  built using the marina-side `DetailLayout` pattern (Overview +
+  Notes + Activity tabs, Interests tab on the client)
+- Detail header components mirror the marina-side strip
+- `useBreadcrumbHint` wired into both detail components
+
+### Residential pipeline stages — configurable
+
+- New `residential-stages.service.ts` with list/save + orphan-check
+- `/api/v1/residential/stages` GET/PUT
+- `/admin/residential-stages` admin UI with reassign-on-remove
+  modal (select new stage per affected interest before save)
+- Validators relaxed from `z.enum(...)` to `z.string()` so any
+  admin-defined stage id round-trips
+
+### Documenso Phase 1 (EOI generate flow polish)
+
+- Schema migrations applied:
+  `document_signers.invited_at / opened_at / last_reminder_sent_at / signing_token`,
+  `documents.completion_cc_emails / auto_reminder_interval_days`
+- `transformSigningUrl()` now maps SignerRole → URL segment correctly
+  (approver→cc, witness→witness) so emails don't land on `/sign/error`
+- New `POST /api/v1/documents/[id]/send-invitation` endpoint with
+  next-pending-signer auto-pick
+- Per-port settings added: `documenso_developer_label`,
+  `documenso_approver_label`, `documenso_developer_user_id`,
+  `documenso_approver_user_id` (Phase 7 RBAC binding fields)
+
+### Misc UI/UX
+
+- Sidebar collapse removed (always expanded)
+- Audit log filter inputs sized + dates widened
+- Custom Settings section got a long-form description
+- Reminder digest timezone uses `TimezoneCombobox`
+- Port form: currency dropdown + timezone combobox + brand color
+- Permissions count badge opens a modal with granted/denied
+- Role names display-normalized via `prettifyRoleName`
+- Sales email config: token list + tooltips on threshold + body fields
+- Custom Fields page: amber heads-up about non-integration with
+  search / recommender / audit / merge tokens
+- Tag form: native `<input type="color">`
+- FilterBar Select crash fixed (no empty-string item values)
+
+---
+
+## REMAINING — large pieces that didn't fit this push
+
+### 1. Documenso Phase 2 — Webhook handler enhancement (~3-4 hours)
+
+Cascading "your turn" emails when each signer completes; on-completion
+PDF distribution; token-based recipient matching; idempotency lock.
+File to extend: `src/app/api/webhooks/documenso/route.ts`. The
+schema columns are already in place (Phase 1).
+
+### 2. Documenso Phase 3 — Custom doc upload-to-Documenso (~6-8 hours)
+
+Backend service `custom-document-upload.service.ts` + endpoint
+`POST /api/v1/interests/[id]/upload-for-signing`. Accepts a PDF +
+recipient list + field-placement JSON, calls `createDocument` →
+`placeFields` → `sendDocument` on the per-port Documenso client.
+Persists a row in `documents` table.
+
+### 3. Documenso Phase 4 — Field placement UI (~10-14 hours)
+
+The biggest piece. Needs:
+
+- 4a: Recipient configurator dialog (~2-3h)
+- 4b: PDF rendering with `react-pdf` (~3-4h)
+- 4c: Auto-detect anchor scanner via `pdfjs-dist.getTextContent` (~4-6h)
+- 4d: Drag-drop overlay using `dnd-kit` (~3-4h)
+- 4e: Send button → calls Phase 3 endpoint (~1h)
+
+Plan locked in `docs/documenso-build-plan.md` Phase 4 — the
+field-detector regexes, the anchor patterns, and the type-to-bbox
+sizing table are all spelled out.
+
+### 4. Documenso Phase 5 — Embedded signing URL emission verification (~1-2 hours)
+
+Verify the website's `/sign/<type>/<token>` page handles every signer
+role + every documentType combination. Update website's
+`signerMessages` map keyed on `(documentType, role)`. Apply the
+nginx CORS block from `docs/documenso-integration-audit.md`.
+
+### 5. Documenso Phase 6 — Polish items (deferred)
+
+Auto-send delay, audit-log additions, per-document customisation,
+document expiration, reminder rate-limit display, failed-webhook
+recovery UI. Each ~2-3 hours; all deferred until Phases 1-4 ship.
+
+### 6. Project Director — UI binding for the developer-user fields
+
+Schema + setting keys are now in place
+(`documenso_developer_user_id`, `documenso_approver_user_id` +
+`documenso_developer_label` / `_approver_label`). The remaining
+work is: add a "Linked to CRM user" dropdown in
+`/admin/documenso/page.tsx` that lists port users; when bound,
+auto-fill name/email from the user profile and mark name/email
+fields read-only. Webhook handler can then match against the
+linked user's email for in-CRM signing-status updates.
+
+### 7. Custom-fields hardening (~ongoing)
+
+Remediation paths for the heads-up banner concerns:
+
+- **Search index**: extend the GIN tsvector to include
+  customFieldValues content
+- **Audit diff**: extend `diffEntity` to walk the
+  customFieldValues blob
+- **Merge tokens**: add `{{custom.<fieldName>}}` handling at
+  template-render time, plus surface them in the merge-tokens UI
+
+### 8. Documenso v2 webhook payload audit (small)
+
+Risk #4 from `docs/documenso-build-plan.md` — confirm v2 payload
+shape (`payload.documentId` vs `payload.id`, recipient.token vs
+`recipient.recipientId`) against a live v2 instance before relying
+on Phase 2 cascading emails.

docs/audit-2026-05-15.md

@@ -0,0 +1,117 @@
+# Comprehensive Playwright Audit — 2026-05-15
+
+Scope: full coverage of admin, sales-rep, viewer, portal, catch-up wizard, single-tree responsive shell, plus spot-checks on yacht / interest / berth detail surfaces.
+
+## Setup
+
+- Dev server: localhost:3000 (running)
+- Users:
+  - super_admin: `admin@portnimara.test` / `SuperAdmin12345!`
+  - sales_agent: `agent@portnimara.test` / `SalesAgent12345!`
+  - viewer: `viewer@portnimara.test` / `ViewerUser12345!`
+- Port slug: `port-nimara`
+
+## Verified working (positive findings)
+
+- ✅ super-admin login + dashboard renders, all 34 admin pages return 200
+- ✅ Recent commits' workflow features:
+  - F22 AlertTriangle icon on override-required stages
+  - F23 inline yacht-prereq picker fires when leaving Enquiry without a yacht (confirmed end-to-end: "A yacht must be linked before leaving Enquiry. Pick one below to move to Qualified.")
+  - F25 documents-hub folder selection persists in `?folder=root` querystring
+  - F44 OwnerPicker has Client/Company tabs visible in popover (just hidden by Select trigger summary)
+- ✅ **#67 catch-up workflow end-to-end**: manually flipped berth A2 → reconciliation queue picked it up → wizard quick-created client + interest + cleared override + reason stamped "Reconciled via interest <id>" + redirected to interest detail
+- ✅ **#26 single-tree shell**: at viewport 390px only mobile shell mounts (1 nav, no desktop sidebar); at 1440px only desktop shell mounts; clean swap on resize
+- ✅ Permission gating: viewer + sales-agent get no "New Client"/admin nav; viewer POST to /clients returns 403
+- ✅ Audit log captures all writes (tag create, berth update, interest create, client create) including the reconcile event with `reconciledInterestId` metadata
+
+## Findings
+
+### A1 — Dashboard Recent Activity surfaces raw `permission_denied` rows with no label
+
+- `/api/v1/dashboard/activity` returns entries with `action: "permission_denied"` and `label: null`. The activity feed renders just the action badge with nothing beside it. From earlier audits, 6 of these are stacked at the top of the dashboard for the super-admin.
+- Fix options: filter `permission_denied` out of the feed, OR map them to readable copy ("Permission denied: tried to view audit log (denied)") using `metadata.attemptedAction`.
+- Effort: XS.
+
+### A2 — Activity feed renders legacy 9-stage enum values
+
+- `pipelineStage: "deposit_10pct"` and `"contract_sent"` still appear in `oldValue` / `newValue` for historical rows. These should map to the 7-stage labels at render time so the feed reads as `Eoi → Deposit Paid` not `eoi_signed → deposit_10pct`.
+- The mapping table lives in seed-synthetic-data.ts (`details_sent→enquiry` etc.) — pull it into a shared `LEGACY_STAGE_REMAP` helper for activity-feed read paths.
+- Effort: S.
+
+### A16 — File upload to documents hub root fails with validation error
+
+- Repro: open `/documents`, click "Upload file", drop any file in. POST to `/api/v1/files/upload` returns 400 with field errors on `clientId`, `yachtId`, `companyId`, `category`, `entityType`, `entityId` — all "expected string, received null".
+- Root cause: the client sends `null` for unset optional fields; the validator expects them either absent or strings. Mismatch.
+- Fix: either make the zod schema accept `.nullable()` on those fields OR strip nulls in `FileUploadZone` / `FolderDropZone` before POST.
+- Effort: XS.
+
+### A17 — `/api/v1/admin/ports` requires X-Port-Id but is the bootstrap port-resolver
+
+- Symptom: as sales-agent, every page load fires a 400 to `/api/v1/admin/ports` ("Port context required"). Repeats on every apiFetch call because `apiFetch` calls this endpoint to resolve port-slug→port-id.
+- Bigger problem: the endpoint is gated to super-admin (`requireSuperAdmin`). Sales-reps and viewers will NEVER get a ports list from this endpoint, so the bootstrap path always falls through to the Zustand store. The 400 noise is wasted work + log spam.
+- Fix: add a `/api/v1/me/ports` endpoint that returns the caller's accessible ports without the super-admin gate, and have `client.ts` use it. OR seed the PortProvider context into a `__INITIAL_PORTS__` window global on first paint and skip the fetch entirely.
+- Effort: S.
+
+### A18 — `/api/v1/users` returns 404 vs `/api/v1/admin/audit` returns 403 (inconsistent perm denials)
+
+- Both endpoints reject sales-agent access but use different status codes. Pick one — either always 404 (hide existence) or always 403 (acknowledge but deny). The 403/404 split is the kind of inconsistency a pentester probes to map permissions.
+- Effort: XS sweep.
+
+### A4 — F19 empty-contact filter never runs because zod-validation rejects first
+
+- Repro: open New Client dialog, fill Full Name + one valid email, click "Add Contact" to insert an empty row, click Create Client. Nothing happens (no toast, no submit, no POST in network).
+- Root cause: my F19 fix put the empty-row prune in the **mutationFn**, but `handleSubmit(zodResolver)` validates the form FIRST. The empty contact's `value: z.string().min(1)` fails silently — handleSubmit short-circuits without surfacing an error on the empty row (the field has no `errors.contacts[1].value` rendered because the schema-level message attaches to the array path).
+- Fix: prune empty contact rows in a custom onSubmit wrapper BEFORE handleSubmit/zod sees them, OR change the field-array schema to allow empty rows and let the mutationFn prune.
+- Effort: XS.
+
+### A19_b — Portal `/portal/login` shows "Client portal unavailable"
+
+- The portal is gated by a per-port `client_portal_enabled` system setting. The route layout renders a friendly message but no admin path is obvious to a fresh-eyes operator.
+- Two distinct problems:
+  - **Discoverability**: the admin landing card for "System Settings" doesn't surface a "Enable client portal" toggle prominently. A new operator would have to know the setting key.
+  - **Portal scope**: the portal currently only has activation + reset password + sign-in surfaces. Once the rep logs the client in, they land on... what? Worth a separate scoping session to flesh out: their interests, their documents, their signing queue, payment history, message thread.
+- Recommendation: spec a "Phase 0 portal MVP" (read-only views of own interests + documents + signed-PDF download) before promoting it to clients. Treat the rest as v1.3 backlog.
+- Effort: portal MVP S-M depending on scope.
+
+### A3 — Dev-only CSP error spam from react-grab
+
+- `react-grab` dev script tries to load `fonts.googleapis.com/css2?family=Geist` and triggers a CSP block on every page load (2 console errors). Cosmetic since react-grab isn't loaded in prod, but the dev console gets noisy.
+- Fix: either drop the react-grab include or extend dev CSP `style-src` to allow `https://fonts.googleapis.com`.
+- Effort: XS.
+
+### A5 — Socket.IO WebSocket repeatedly fails to connect in dev
+
+- Console floods with "WebSocket is closed before the connection is established" — at least 6 occurrences per page in this session. Socket-io server endpoint at /socket.io/ isn't reachable from the Next dev server.
+- Likely root cause: Socket.IO server runs as a sidecar in compose but `pnpm dev` only starts Next, so the realtime channel is permanently broken in dev. Realtime invalidation features (interest/folder updates) silently never fire.
+- Fix: either start the socket server alongside `pnpm dev` (concurrently script), gate the SocketProvider behind a feature flag in dev, or stub the client to no-op when the endpoint 404s the first handshake.
+- Effort: S.
+
+### A6 — Some DialogContent missing aria-describedby
+
+- React warnings: `Missing 'Description' or 'aria-describedby={undefined}' for {DialogContent}`. At least one Dialog opens without a DialogDescription.
+- Fix: audit Dialog usages and either add a DialogDescription or pass `aria-describedby={undefined}` explicitly where genuinely no description is needed.
+- Effort: S.
+
+### A8 — Legacy `statusOverrideMode = "auto"` values still in seed data
+
+- Berth A1 (and likely others) has `statusOverrideMode: "auto"` from the NocoDB legacy import. The new code writes 'manual' | 'automated' | null; 'auto' is unrecognized.
+- Treated as "not manual" by the reconcile-queue filter so it's benign today, but the column should be normalized — either migrate legacy 'auto' → null in a migration, or treat 'auto' explicitly in the read paths.
+- Effort: XS.
+
+### A9 — Catch-up wizard pipeline stage default doesn't match berth status
+
+- Open the wizard on a berth where status=under_offer; the stage picker defaults to "New Enquiry" instead of "EOI" (the most common manual-flip case).
+- Root cause in `catch-up-wizard.tsx`: the default-stage logic only fires when the initial state isn't in the allowed set; 'enquiry' IS in the allowed set for under_offer, so it stays. Should default to EOI on first open via a `useEffect` keyed on `berth?.data.status`.
+- Effort: XS.
+
+### A19 — F27 same-stage write still returns 200 + body instead of 204
+
+- Spec said "same-stage write → 204 No Content (no-op)". The service early-returns `existing` correctly (no audit log emitted), but the route handler wraps it in `{ data: existing }` and returns 200.
+- Fix: have the service return a discriminated result like `{ kind: 'no-op' } | { kind: 'updated', interest }`, and the route handler returns 204 for the no-op branch.
+- Effort: XS (route handler tweak).
+
+### A20 — F44 OwnerPicker — toggle hidden until popover opens (minor UX)
+
+- The yacht-create form shows just "Select owner..." with no visible indication that it supports both clients AND companies. The Client/Company toggle pills only appear once the popover is open.
+- Fix option: surface "Owned by: Client | Company" as a segmented control above the picker, OR add a hint chip "Client/Company" next to the label.
+- Effort: XS.

docs/audit-comprehensive-2026-05-06.md

@@ -0,0 +1,753 @@
+# Comprehensive Audit — 2026-05-06
+
+Conducted directly after the smart-archive / hard-delete / bulk-wizard /
+audit-overhaul / synthetic-seed batches landed (commits `d07f1ed`
+through `9890d06`). Prior comprehensive audit:
+`docs/audit-comprehensive-2026-05-05.md`.
+
+Findings are sorted by severity. Each has a concrete file:line, a
+scenario, and a fix recommendation.
+
+---
+
+## CRITICAL
+
+### C1. 5 of 10 BullMQ workers are never imported (production + dev)
+
+**Files:** `src/worker.ts:13-17`, `src/server.ts:72-76`
+
+`src/worker.ts` (production) and `src/server.ts` (dev fallback) both
+import only:
+
+- `emailWorker`
+- `documentsWorker`
+- `notificationsWorker`
+- `importWorker`
+- `exportWorker`
+
+**Missing:** `aiWorker`, `bulkWorker`, `maintenanceWorker`, `reportsWorker`, `webhooksWorker`.
+
+Because BullMQ workers are constructed at the top of each worker
+module and only "start" when the module is imported, never importing
+them means:
+
+- **Webhooks never deliver.** `webhooksWorker` is what processes the
+  `webhooks` queue; the admin "Replay" button we just shipped enqueues
+  jobs that pile up in `pending` forever.
+- **All maintenance crons silently no-op.** `maintenanceWorker` handles
+  `database-backup`, `backup-cleanup`, `session-cleanup`,
+  `currency-refresh`, `gdpr-export-cleanup`, `ai-usage-retention`,
+  `error-events-retention`, `website-submissions-retention`,
+  `alerts-evaluate`, `analytics-refresh`, `calendar-sync`,
+  `temp-file-cleanup`, `form-expiry-check` — none run.
+- **Scheduled reports never generate.** `reportsWorker` handles
+  `report-scheduler` (every minute).
+- **Bulk jobs never process** (the synchronous bulk endpoints work, but
+  any deferred-bulk path is dead).
+- **AI usage features never run.**
+
+**Impact:** Production CRM has been silently shedding webhook
+deliveries, never running retention/cleanup, never sending scheduled
+reports.
+
+**Fix:**
+
+```ts
+// Append to src/worker.ts AND the inline section of src/server.ts:
+import { aiWorker } from '@/lib/queue/workers/ai';
+import { bulkWorker } from '@/lib/queue/workers/bulk';
+import { maintenanceWorker } from '@/lib/queue/workers/maintenance';
+import { reportsWorker } from '@/lib/queue/workers/reports';
+import { webhooksWorker } from '@/lib/queue/workers/webhooks';
+
+const workers = [
+  emailWorker,
+  documentsWorker,
+  notificationsWorker,
+  importWorker,
+  exportWorker,
+  aiWorker,
+  bulkWorker,
+  maintenanceWorker,
+  reportsWorker,
+  webhooksWorker,
+];
+```
+
+After fix, run `pnpm dev` and watch `/admin/webhooks/{id}` deliveries
+go from `pending` → `success` to confirm.
+
+---
+
+## HIGH
+
+### H1. Hard-delete request endpoints have zero rate limiting
+
+**Files:**
+
+- `src/app/api/v1/clients/[id]/hard-delete-request/route.ts:1-37`
+- `src/app/api/v1/clients/bulk-hard-delete-request/route.ts:1-32`
+
+Each call writes a fresh code to Redis and emails it to the operator's
+address. No `withRateLimit(...)`. An attacker who has compromised an
+admin account (or even just the new `permanently_delete_clients`
+permission) can:
+
+1. Email-bomb the admin's own inbox (every request → email).
+2. Probe whether arbitrary client IDs exist (200 + `sentToMaskedEmail`
+   vs 404 `client not found` is a UID oracle).
+3. Burn SMTP quota.
+
+**Fix:** add `withRateLimit('auth', ...)` or a new dedicated bucket
+(e.g. 5 per hour per user). Pattern is already in
+`src/app/api/v1/clients/[id]/gdpr-export/route.ts`.
+
+### H2. Audit-page view fires on every paginated reload (log spam)
+
+**File:** `src/app/api/v1/admin/audit/route.ts:48-72`
+
+I added a "watch the watchers" `view` audit row for first-page audit
+fetches. That's the right idea, but the page also re-fires the request
+on every filter change (severity, source, action, date range, search).
+A diligent admin filtering through the inspector for an investigation
+will write dozens of `view` audit rows per minute — making it harder to
+find the actual events they're looking for.
+
+**Fix:** dedupe in Redis with a 60-second per-user TTL key, only emit
+if the key didn't exist. Or only fire when no filters are active.
+
+### H3. Hard-delete error messages distinguish "no code" vs "wrong code"
+
+**File:** `src/lib/services/client-hard-delete.service.ts:166-174`
+
+```ts
+if (!stored) throw new ValidationError('Confirmation code expired or not requested');
+if (!safeEqualStr(stored, args.code.trim())) {
+  throw new ValidationError('Confirmation code is incorrect');
+}
+```
+
+The two messages let an attacker distinguish "you've never requested a
+code" (so spam the request endpoint to open the window) from "wrong
+code" (so brute-force more codes). 4-digit space is only 10,000 — with
+distinguishable feedback an attacker can confirm code validity in
+≤5,000 attempts on average.
+
+**Fix:** collapse to a single `'Invalid or expired code'` message; the
+operator already has the email open and knows what they typed.
+
+### H4. Synthetic seed leaves `super_admin` linked-port-roles empty
+
+**File:** `src/lib/db/seed-bootstrap.ts:147-160`
+
+The bootstrap creates the `userProfiles` row with
+`isSuperAdmin: true` for `super-admin-matt-portnimara`, but doesn't
+create `userPortRoles` rows. The actual real `user` rows (admin@,
+agent@, viewer@) are only created via the Playwright global-setup.
+Anyone running `pnpm db:seed:synthetic` then `pnpm dev` and trying to
+log in via the UI hits an unauthenticated state until they also run
+playwright setup or sign up via better-auth manually.
+
+**Fix:** either document this in `CLAUDE.md` Quick Reference, or add a
+`pnpm db:seed:dev-users` companion script that signs up the three
+test users + links roles. Today's synthetic-seed flow felt clean
+because the playwright setup was still applied; in a fresh clone it
+will surprise.
+
+### H5. Documenso bad-secret 200 response is correct, but enables enum oracle
+
+**File:** `src/app/api/webhooks/documenso/route.ts:67-86`
+
+The route returns `200 ok=false error=Invalid secret` for a wrong
+secret. That's webhook best-practice (don't leak signal to attackers),
+but combined with the new audit row that captures
+`metadata.providedLen`, an attacker can probe secret-length over time
+without being detected (just a "warning" row per attempt). On an admin
+inspector with 1000s of rows, a slow-rate probe is invisible.
+
+**Fix:** add per-IP rate limit (5/min) to `/api/webhooks/documenso/`
+when secret check fails. Don't block real Documenso traffic — it
+shouldn't fail the secret check.
+
+### H6. The audit-log inspector page itself isn't backed by a real "view" gate beyond `admin.view_audit_log`
+
+**File:** `src/app/api/v1/admin/audit/route.ts:31`
+
+Audit log has the most sensitive cross-cutting data in the system
+(every login attempt with attempted email, every secret-regenerate,
+every hard-delete). It's gated only by `admin.view_audit_log`. The
+seed grants this to `director` AND `super_admin`. Consider:
+
+- making the page super-admin-only for production, OR
+- adding a secondary confirmation when viewing rows that contain
+  attempted emails / IP ranges (PII).
+
+**Fix:** change `withPermission('admin', 'view_audit_log', ...)` to
+add `if (!ctx.isSuperAdmin) check sensitive_audit_view`. Or accept
+the current model but document it in the role docs.
+
+### H7. Three "coming soon" stubs in production UI
+
+**Files:**
+
+- `src/components/clients/client-tabs.tsx:276` — "File attachments coming soon."
+- `src/components/clients/client-reservations-tab.tsx:41` — "History is coming soon."
+- `src/components/berths/berth-tabs.tsx:327` — "{label} coming soon"
+
+Visible to every user on every client / berth detail page. Either ship
+the feature or hide the tab.
+
+**Fix:** for `client-tabs.tsx` line 276 (Files), the `files` table
+already exists and supports clientId — ship a list view.
+For `berth-tabs.tsx` line 327 — find the calling tab labels and
+either implement or remove from the tabs array.
+For `client-reservations-tab.tsx` line 41 — query past reservations
+when the user toggles a "show history" filter.
+
+---
+
+## MEDIUM
+
+### M1. `attachWorkerAudit` recurring job names list duplicates scheduler.ts (drift risk)
+
+**File:** `src/lib/queue/audit-helpers.ts:23-46`
+
+The 20 recurring job names are hardcoded in the audit helper; the
+scheduler also has its own list. If someone adds a new cron without
+updating both, the cron_run audit row never fires for that job.
+
+**Fix:** export the list from `scheduler.ts` and import it in
+`audit-helpers.ts`. Single source of truth.
+
+### M2. `client-merge-log.surviving_client_id` deleted by hard-delete (history loss)
+
+**File:** `src/lib/services/client-hard-delete.service.ts:200-202`
+
+Hard-delete drops every `client_merge_log` row whose surviving id
+matches. Those rows are the audit trail of WHO was merged INTO this
+client. Once deleted, you've lost evidence of the prior merge.
+
+**Fix:** replace `delete` with a column nullification, or move the row
+to a `client_merge_log_archive` table. Audit trail per GDPR Article 5
+should outlive the data.
+
+### M3. Bulk hard-delete loops one-shot codes through Redis (5x writes)
+
+**File:** `src/lib/services/client-hard-delete.service.ts:382-396`
+
+For a 100-client bulk delete, the function writes 100 single-client
+codes to Redis just to satisfy `hardDeleteClient`'s expectation. Each
+write is a round-trip; on a Redis hiccup mid-loop, you can end up
+with a half-deleted batch.
+
+**Fix:** refactor `hardDeleteClient` so the inner deletion can be called
+without the per-client code check (extract `_doHardDelete()` private
+helper used by both single and bulk paths). Keeps Redis clean.
+
+### M4. Smart-restore wizard has dead reversal applier for `berth_released`
+
+**File:** `src/lib/services/client-restore.service.ts:360-372`
+
+The `applyReversal` switch case for `'berth_released'` does nothing —
+it just leaves the berth available. The wizard surfaces this as
+"auto-reversible" if the berth is still free, but the actual restore
+doesn't re-attach the berth to any interest. Operator clicks Restore
+expecting their berth back; nothing changes on the berth.
+
+**Fix:** either (a) at archive time, persist the original interestId
+in the decision metadata so we can re-link, or (b) update the wizard
+copy to make clear the berth is "available for re-attach" rather than
+"will be re-attached."
+
+### M5. Several services use `void createAuditLog(...)` without `.catch()`
+
+**Files:** widespread; e.g. `src/lib/services/client-hard-delete.service.ts:127-136, 230-240`,
+`src/lib/services/portal-auth.service.ts:269-276`
+
+`createAuditLog` is documented as never-throwing (catches internally),
+but defense-in-depth: a `void` Promise that throws produces an
+unhandled rejection event. Most paths are fine because the helper
+catches; if anyone refactors `createAuditLog` and removes the catch,
+this becomes a process-killer.
+
+**Fix:** convention rule: every `void someAsync()` must have a `.catch()`.
+Codify with a custom ESLint rule, or wrap at call sites:
+`void createAuditLog({...}).catch(() => undefined);`
+
+### M6. Hard-delete audit metadata leaks client `fullName`
+
+**File:** `src/lib/services/client-hard-delete.service.ts:241-247`
+
+After the hard-delete the audit row carries
+`metadata: { fullName: client.fullName }`. The client record itself is
+gone but their name lives on in the audit log. For a GDPR data subject
+who exercised their right-to-erasure, this is technically a retention
+of personal data in audit history. Not necessarily wrong (audit logs
+have a legitimate-interest basis), but should be conscious.
+
+**Fix:** decide policy: either (a) keep as-is and document, (b) replace
+with a hash of the name, or (c) substitute a tombstone identifier.
+
+### M7. Webhook delivery DLQ admin-replay can re-trigger downstream side-effects
+
+**File:** `src/lib/services/webhooks.service.ts:282-326`
+
+Replaying a successful webhook (operator presses Replay on a delivery
+that already had `status: 'success'`) re-fires the same payload to the
+recipient. If the recipient's idempotency check is weak, you've just
+caused a duplicate. The replay payload includes `retried_from` /
+`retried_at` markers, which is good — but most recipients won't honor
+them.
+
+**Fix:** disable the Replay button when `status === 'success'`. The UI
+already gates on `'failed' || 'dead_letter'` — verify it stays that
+way (`webhook-delivery-log.tsx:118-131` looks correct; double-check
+no regressions).
+
+### M8. `audit_logs` table has no DELETE permission gate
+
+**Files:** schema and routes
+
+There's no admin endpoint to delete audit rows (good). But there's no
+DB-level guard either. A super_admin who runs `db:reset` wipes audit
+history. Audit retention should be enforced at the schema level so
+even a misconfigured operator can't blow away the trail.
+
+**Fix:** create a `audit_logs_no_delete_role` postgres role that lacks
+DELETE on the table; document that the app's DB user should not have
+DELETE on `audit_logs` in production deployments.
+
+### M9. Documenso void worker uses dynamic import every time
+
+**File:** `src/lib/queue/workers/documents.ts:25`
+
+```ts
+const { voidDocument } = await import('@/lib/services/documenso-client');
+```
+
+Dynamic import inside a hot per-job path is fine the first time but
+slows every subsequent call slightly. Move to top-of-file import
+unless there's a deliberate reason (circular dep?).
+
+**Fix:** test moving to top-level import; if it works (no circular
+deps), keep it there.
+
+### M10. Bulk archive wizard "blocked" reason copy truncates at first line
+
+**File:** `src/components/clients/bulk-archive-wizard.tsx:153-163`
+
+The wizard shows `b.blockers[0]` for blocked clients. If the dossier
+has multiple blockers, only the first is shown. Operators may fix the
+first one, retry, and discover a second.
+
+**Fix:** show all blockers (joined with `·`) or a "+N more" badge
+with click-to-expand.
+
+---
+
+## LOW
+
+### L1. `next-in-line-notify.service.ts` could double-fire on archive retry
+
+**File:** `src/app/api/v1/clients/[id]/archive/route.ts:114-135`
+
+If the smart-archive request succeeds at the DB transaction level but
+the response upload-side fails (network blip, browser closes), the
+operator may retry. Each retry re-fires the next-in-line notification
+to all sales recipients. The `dedupeKey: berth-released:{berthId}`
+inside the notification helper deduplicates within a cooldown window —
+so this is mitigated, but worth verifying the cooldown is set and
+not 0.
+
+### L2. `interests.berth_id` reference in `seed-data.ts` (legacy seed)
+
+**File:** `src/lib/db/seed-data.ts:973`
+
+The realistic seed inserts `berthId: ...` on the interests table. Per
+`CLAUDE.md`, that column was dropped in migration 0029 and replaced
+with `interest_berths` junction. The synthetic seed uses the junction
+correctly. The realistic seed will FAIL at insert time if anyone
+tries to run it on a freshly-migrated DB.
+
+**Fix:** rewrite `seed-data.ts:969-982` to insert into `interests`
+without `berthId`, then insert the junction rows separately (mirror
+the synthetic seed's pattern).
+
+### L3. Audit log entry for failed login uses `entityId = attemptedEmail` (unbounded)
+
+**File:** `src/app/api/auth/[...all]/route.ts:53-68`
+
+If the entityId is very long (a 500-char "email"), it goes into the
+DB column. The column is `text` (unbounded) so no DB error, but FTS
+search-text may bloat.
+
+**Fix:** truncate attempted email to 256 chars before using as
+entityId.
+
+### L4. The "watch the watchers" audit fires for filtered queries too
+
+**File:** `src/app/api/v1/admin/audit/route.ts:48-72`
+
+(See H2 above for the page-spam variant.) Even on a single search,
+an audit row containing the search term is written. If the search
+term itself is sensitive (e.g. an admin searches for a specific
+client's name in audit logs), it's now in the audit log of audit-log
+viewing. Acceptable but worth documenting.
+
+### L5. Import worker is a stub
+
+**File:** `src/lib/queue/workers/import.ts:13`
+
+`// TODO(L2): implement import job handlers` — the worker is wired
+into the queue and registered, but does nothing. If anyone enqueues
+an `import:*` job, it returns immediately. Either ship the feature
+or remove the queue.
+
+### L6. `interest-form.tsx` two TODOs about company-yacht filter + add-yacht inline
+
+**File:** `src/components/interests/interest-form.tsx:332-333`
+
+Real product gaps. When creating an interest for a client who's a
+member of a company, you can't pick a yacht owned by that company.
+And there's no inline "Add yacht" shortcut in the form.
+
+### L7. `berth-spec-template.ts` defaults to `'Price: TBD'` when price is null
+
+**File:** `src/lib/pdf/templates/berth-spec-template.ts:128`
+
+Generated berth-spec PDFs say "Price: TBD" for any berth without a
+price. Cosmetic — verify whether sales considers this an acceptable
+fallback or wants to suppress the line entirely.
+
+---
+
+## Things checked and found OK (so we don't re-audit)
+
+- Tenant isolation on hard-delete (`portId` filter on every query and
+  inside the tx).
+- `withPermission` gates on every new route (bulk-archive-preflight,
+  hard-delete-_, bulk-hard-delete-_, redeliver).
+- Audit log: no public DELETE endpoint, no PATCH endpoint.
+- Sidebar nav properly gates marina sections from `residential_partner`
+  via `hasMarinaAccess`.
+- Auth wrapper rebuilds the request body correctly so the upstream
+  better-auth handler can re-read it (no body-already-consumed bug).
+- Webhook outbound SSRF guard with DNS rebinding protection still
+  intact.
+- 1175/1175 vitest suite passing as of last run.
+
+---
+
+## Recommended fix order (ROUND 1 + 2 combined — see below for Round 2)
+
+See **"Triage list" at the end** of this document — combined ranking
+across both audit rounds.
+
+---
+
+## Round 2 — focused agents (added 2026-05-06 evening)
+
+After the original synthesis above, four scoped agents (smaller blast
+radius, hard finding caps) successfully audited their domains and
+produced dedicated docs. Findings are linked here with `R2-`-prefixed
+IDs. Detail in:
+
+- [audit-reliability-2026-05-06.md](audit-reliability-2026-05-06.md) — 11 findings
+- [audit-frontend-2026-05-06.md](audit-frontend-2026-05-06.md) — 12 findings
+- [audit-permissions-2026-05-06.md](audit-permissions-2026-05-06.md) — 9 findings
+- [audit-missing-features-2026-05-06.md](audit-missing-features-2026-05-06.md) — 12 findings
+
+### Round 2 — CRITICAL
+
+**R2-C1. Bulk archive discards post-commit side effects** ([reliability C1](audit-reliability-2026-05-06.md))
+
+- File: `src/app/api/v1/clients/bulk/route.ts:68-134`
+- The bulk wizard's `runBulk` callback discards the return value from
+  `archiveClientWithDecisions`. **Documenso envelopes marked
+  `void_documenso` are never queued for void; "next-in-line" sales
+  notifications never fire**. The CRM ends up showing `documents.status='cancelled'`
+  while the live envelope is still out for signature — a signer can
+  legally complete a doc the CRM thinks is voided.
+- Same severity tier as the original C1 (worker-imports).
+
+**R2-C2. Frontend: Restore icon hovers destructive-red on archived clients** ([frontend C1](audit-frontend-2026-05-06.md))
+
+- File: `src/components/clients/client-detail-header.tsx:174-186`
+- Conditional `hover:text-destructive` is overridden by an unconditional
+  `hover:text-foreground` earlier in the class string. Result: the
+  Restore button on archived clients hovers blood-red, signalling
+  "destructive" on a fully reversible action. Users hesitate to click.
+  Promoted to "critical UX" because it's directly misleading on every
+  archived client view.
+
+### Round 2 — HIGH
+
+**R2-H1. Smart-restore wizard's `berth_released` reversal is a no-op but the audit log claims success**
+([reliability H1](audit-reliability-2026-05-06.md))
+
+- File: `src/lib/services/client-restore.service.ts:359-372`
+- Already noted as M4 in the original synthesis. Round-2 reliability
+  agent escalated to HIGH because the wizard counter increments and
+  the audit log records "1 auto-reversed" — operator believes the berth
+  was re-attached when nothing happened. Same fix path: persist the
+  original `interestId` in the decision detail and re-link on restore.
+
+**R2-H2. Smart-archive berth status update has TOCTOU race**
+([reliability H2](audit-reliability-2026-05-06.md))
+
+- File: `src/lib/services/client-archive.service.ts:191-207`
+- Berth row read outside tx, mutated inside tx without `for update`
+  lock. Concurrent archive + sale of the same berth can race: the
+  archive flow flips a freshly-sold berth back to `available`. Add
+  `select … for update` on `berths` before the status flip.
+
+**R2-H3. Bulk archive can pick the wrong interest for berth release**
+([reliability H3](audit-reliability-2026-05-06.md))
+
+- File: `src/app/api/v1/clients/bulk/route.ts:95-103`
+- Lookup by `primaryBerthMooring` falls back to `dossier.interests[0]?.interestId ?? ''`.
+  Empty-string `interestId` reaches the delete and silently matches
+  zero rows; the link is silently retained while the audit log claims
+  it was removed.
+
+**R2-H4. External EOI runs five operations outside a transaction**
+([reliability H4](audit-reliability-2026-05-06.md))
+
+- File: `src/lib/services/external-eoi.service.ts:67-155`
+- Storage upload + 4 DB writes are independent. Mid-flight failure
+  leaves orphan PDFs in S3/MinIO and partial DB state.
+
+**R2-H5. Bulk wizard double-submit treats `ConflictError('already archived')` as a per-row error**
+([reliability H5](audit-reliability-2026-05-06.md))
+
+- File: `src/app/api/v1/clients/bulk/route.ts:68-120`
+- No idempotency key on the bulk endpoint. A double-submit (network
+  retry, double click) makes the second response look like all rows
+  failed even though the first succeeded.
+
+**R2-H6. Webhook replay button has no UI permission gate (403 toast spam)**
+([permissions H1](audit-permissions-2026-05-06.md))
+
+- File: `src/components/admin/webhooks/webhook-delivery-log.tsx:118-131`
+- Replay button renders for any user who can load the page. Server gates
+  on `admin.manage_webhooks`. Non-admins see enabled buttons; clicking
+  surfaces a generic 403 toast.
+
+**R2-H7. Bulk Archive bulk action exposed to roles without `clients.delete`**
+([permissions H2](audit-permissions-2026-05-06.md))
+
+- File: `src/components/clients/client-list.tsx:182-190`
+- `sales_agent` and `viewer` see the Archive bulk action; clicking
+  surfaces a 403 from preflight. Mirror the `canHardDelete` pattern:
+  `const canBulkArchive = can('clients', 'delete');`
+
+**R2-H8. Bulk add_tag / remove_tag exposed to viewer**
+([permissions H3](audit-permissions-2026-05-06.md))
+
+- File: `src/components/clients/client-list.tsx:165-181`
+- Same pattern as R2-H7 — no UI gate; server gates on `clients.edit`.
+
+**R2-H9. Bulk hard-delete silently skips rows that vanish between preflight and execute**
+([permissions H4](audit-permissions-2026-05-06.md))
+
+- File: `src/lib/services/client-hard-delete.service.ts:377`
+- `if (!c) continue;` swallows any client that was archived/restored/
+  deleted by another operator between preflight and execute. Operator
+  sees a `deletedCount` lower than requested and no signal which IDs
+  were skipped.
+
+**R2-H10. Frontend: `webhook-delivery-log` and `audit-log-list` swallow fetch errors silently**
+([frontend H3, H4](audit-frontend-2026-05-06.md))
+
+- Files: `src/components/admin/webhooks/webhook-delivery-log.tsx:61-74`,
+  `src/components/admin/audit/audit-log-list.tsx:150-175`
+- Both wrap fetches in `try/finally` with no `catch`. Failed loads show
+  spinner forever or stale data; user has no signal that anything
+  failed. Surface via `toast.error` + inline retry banner.
+
+**R2-H11. Frontend: `audit-log-card` renders as `<a href="#">` — page-jumps on mobile tap**
+([frontend H5](audit-frontend-2026-05-06.md))
+
+- File: `src/components/admin/audit/audit-log-card.tsx:96`
+- Card view rows on mobile insert `#` in URL on tap (back-button trap).
+  Render as button or div, or link to a useful destination.
+
+**R2-H12. Frontend: `smart-archive-dialog` doesn't invalidate the dossier or single-client query**
+([frontend H6](audit-frontend-2026-05-06.md))
+
+- File: `src/components/clients/smart-archive-dialog.tsx:197-212`
+- Detail page header keeps showing client as un-archived after a
+  successful archive until hard reload. Add
+  `qc.invalidateQueries({queryKey: ['clients', clientId]})` and
+  `qc.removeQueries({queryKey: ['client-archive-dossier', clientId]})`.
+
+**R2-H13. Frontend: bulk tag mutation uses `alert()` and lacks `onError`**
+([frontend H2](audit-frontend-2026-05-06.md))
+
+- File: `src/components/clients/client-list.tsx:88-106`
+- Native `alert()` blocks the page on partial failure; pure network
+  failure shows nothing. Replace with `toast.warning` / `toast.error`.
+
+**R2-H14. Email-template subject overrides are no-ops for 6 of 8 templates**
+([missing-features V1](audit-missing-features-2026-05-06.md))
+
+- Files: `src/components/admin/email-templates-admin.tsx:24-72` (UI),
+  `src/lib/services/portal-auth.service.ts:120,332` (only consumers)
+- Admin sees an "Overridden" badge after saving a custom subject for
+  CRM invite, inquiry confirmation, residential templates, etc. — but
+  the senders ship the hardcoded subject regardless. Wire
+  `loadSubjectOverride(portId, key)` into the 6 missing senders.
+
+**R2-H15. Branding admin saves 5 settings that nothing reads**
+([missing-features V2](audit-missing-features-2026-05-06.md))
+
+- Files: `src/app/(dashboard)/[portSlug]/admin/branding/page.tsx`,
+  `src/lib/services/port-config.ts:240-272`
+- Logo URL, app name, primary color, header HTML, footer HTML all
+  dead-end. `getPortBrandingConfig` has zero callers. **Multi-tenant
+  promise broken — every port's emails ship Port Nimara's branding.**
+
+**R2-H16. Reminder admin saves digest defaults that no scheduler applies**
+([missing-features V3](audit-missing-features-2026-05-06.md))
+
+- Files: `src/app/(dashboard)/[portSlug]/admin/reminders/page.tsx`,
+  `src/lib/services/port-config.ts:284-306`
+- Sales reps think they configured a daily digest at 09:00 in their
+  TZ; they get fire-as-they-hit notifications instead. The digest
+  scheduler doesn't exist.
+
+### Round 2 — MEDIUM (selected highlights)
+
+**R2-M1. Portal "My Memberships" tile is a dead-end** ([missing-features V4](audit-missing-features-2026-05-06.md))
+
+- Tile on `/portal/dashboard` has no `href`; route doesn't exist. Either
+  ship `/portal/memberships` or remove the tile.
+
+**R2-M2. Company detail Documents tab is a "Coming soon" stub** ([missing-features V5](audit-missing-features-2026-05-06.md))
+
+- `src/components/companies/company-tabs.tsx:230-234`. Same problem
+  as the three already-noted "coming soon" stubs but on a different
+  entity.
+
+**R2-M3. Onboarding page is a static checklist not the wizard it advertises** ([missing-features V6](audit-missing-features-2026-05-06.md))
+
+- The page literally says "what this page will become". Either build
+  the wizard or relabel the landing card.
+
+**R2-M4. Backup admin page is a docs page despite landing copy promising "on-demand exports"** ([missing-features V7](audit-missing-features-2026-05-06.md))
+
+- Once C1 (worker imports) is fixed, the existing `database-backup`
+  job is reachable; small lift to wire a "Take backup now" button.
+
+**R2-M5. Inquiry inbox has zero triage actions** ([missing-features V8](audit-missing-features-2026-05-06.md))
+
+- No "Convert to client", no "Resolve", no "Assign". `website_submissions`
+  table is permanent; sales has to copy-paste emails into client forms.
+
+**R2-M6. external-eoi grants only `documents.upload_signed` but mutates interest state** ([permissions M1](audit-permissions-2026-05-06.md))
+
+- A custom role with `documents.upload_signed:true` + `interests.edit:false`
+  can flip an interest to "signed" via the external-EOI route.
+
+**R2-M7. `InlineStagePicker` never sends `override:true` — `override_stage` permission unreachable from the most-used UI path** ([permissions M2](audit-permissions-2026-05-06.md))
+
+- Users with the perm have to fall back to the modal `InterestStagePicker`
+  to actually use it.
+
+**R2-M8. `sales_agent` granted `interests.override_stage:true` — likely copy-paste from sales_manager** ([permissions M3](audit-permissions-2026-05-06.md))
+
+- All other trust-elevated flags are stripped from sales_agent. Needs a
+  product decision; either flip to false or document intent.
+
+**R2-M9. `bulk-archive-preflight` leaks dossier-loader error text in `blockers`** ([permissions M4](audit-permissions-2026-05-06.md))
+
+- An attacker enumerating UUIDs can distinguish "doesn't exist" vs
+  "exists but you can't see it". Replace with generic "Could not load
+  dossier".
+
+**R2-M10. Documenso void worker has no max-retry alert hook** ([reliability M2](audit-reliability-2026-05-06.md))
+
+- A persistent 401/403 retries forever. On exhaustion, write back to
+  `documents` (`cancellation_failed=true`) and notify admin.
+
+**R2-M11. Mobile More-sheet missing residential, notifications, berth-reservations, website-analytics** ([missing-features V9](audit-missing-features-2026-05-06.md))
+
+- Mobile users have zero path to entire feature domains. Add to
+  `MORE_ITEMS`.
+
+**R2-M12. Portal has no profile / change-password surface** ([missing-features V10](audit-missing-features-2026-05-06.md))
+
+- Forces every portal user to use the forgot-password flow even when
+  they remember their old password. Ship `/portal/profile`.
+
+**R2-M13. Portal invoices show amounts but no PDF download** ([missing-features V11](audit-missing-features-2026-05-06.md))
+
+- Documents page does have downloads; mirror the pattern.
+
+(Plus several more medium/low items in the dedicated docs; see those
+for the full set.)
+
+---
+
+## TRIAGE LIST (combined Round 1 + Round 2)
+
+### Ship now — CRITICAL
+
+1. **C1** — wire the 5 missing BullMQ workers (`worker.ts`, `server.ts`)
+   — 5-line fix; every webhook + cron flow is currently dead.
+2. **R2-C1** — make bulk archive enqueue Documenso voids + next-in-line
+   notifications (return value plumbing in `bulk/route.ts`).
+3. **R2-C2** — fix the destructive-red hover on the Restore button
+   (`client-detail-header.tsx`). Trivial CSS fix.
+
+### Ship this week — HIGH (security/UX with concrete user impact)
+
+4. **H1** — rate-limit the hard-delete-request endpoints.
+5. **H3** — collapse "no code" vs "wrong code" into one error message.
+6. **H7** — three "coming soon" stubs in client/berth tabs.
+7. **R2-H1** — fix smart-restore's silent `berth_released` no-op (or
+   reclassify as `reversibleWithPrompt`).
+8. **R2-H2** — add `for update` lock on the smart-archive berth status
+   flip (TOCTOU race).
+9. **R2-H3** — bulk-archive's wrong-interest fallback — empty-string
+   interestId silently no-ops.
+10. **R2-H6, R2-H7, R2-H8** — three permission UI-gate misses on
+    bulk actions and the webhook-replay button. ~30 lines total.
+11. **R2-H10, R2-H12, R2-H13** — frontend swallowed errors + missing
+    invalidation + alert() instead of toast. Small fixes, immediate UX
+    win.
+12. **R2-H11** — `audit-log-card` `href="#"` mobile back-button trap.
+13. **R2-H14** — wire 6 missing email-subject overrides through their
+    senders.
+
+### Next sprint — HIGH/MEDIUM (operational + multi-tenant correctness)
+
+14. **R2-H4** — wrap external-EOI in a transaction.
+15. **R2-H5** — bulk-archive idempotency key + treat already-archived as
+    success in bulk.
+16. **R2-H9** — bulk hard-delete should return `skipped: string[]`.
+17. **R2-H15, R2-H16** — branding + reminder admin pages save settings
+    nothing reads (silently broken multi-tenancy).
+18. **H2** — audit-page-view de-dupe (don't spam on every filter change).
+19. **H4** — synthetic seed needs documented dev-user setup or its own
+    bootstrap script.
+20. **H5** — Documenso bad-secret rate-limit per IP.
+21. **R2-M1 through R2-M5** — portal memberships dead-end, company
+    Documents stub, onboarding wizard, backup page, inquiry inbox triage.
+
+### Backlog — MEDIUM/LOW + remaining items
+
+22. The remaining MEDIUM/LOW from both rounds — see the dedicated docs.
+
+---
+
+## Headline numbers (combined)
+
+- **3 CRITICAL** (worker imports, bulk-archive side-effects, restore-button hover)
+- **22 HIGH** (security + UX with concrete impact)
+- **~15 MEDIUM** (operational hygiene, multi-tenancy gaps, unfinished features)
+- **~10 LOW** (cleanup, defensive)
+
+Round 1 was a manual synthesis after agent-pool stalls; Round 2 was
+four focused agents with hard finding caps that all completed inside
+the watchdog window. Every finding is grounded in code references.

docs/audit-final-deferred.md

@@ -0,0 +1,278 @@
+# Final audit deferred findings
+
+> **Status update (audit-v3 round)**: most of the v2 deferred items have
+> now landed. Items struck through below are completed. The remaining
+> open items are bigger refactors (custom-fields per-entity routes,
+> systemSettings PK reconciliation, Documenso v2 voidDocument verification,
+> partial-vs-composite archived index conversion, storage-proxy port_id
+> claim, Documenso webhook port_id enforcement, response-shape
+> standardization, berths.current_pdf_version_id Drizzle FK).
+
+The pre-merge audit on `feat/berth-recommender` produced ~30 findings. The
+critical + high-severity items were fixed in-branch. The items below are
+medium / low severity and deferred to follow-up issues so the merge isn't
+held up. Each entry is self-contained — pick one off and ship it.
+
+## Cross-cutting integration
+
+- **EOI in-app pathway silently swallows missing `Berth Range` AcroForm field**
+  — `src/lib/pdf/fill-eoi-form.ts:93`. `setText(form, 'Berth Range', ...)`
+  is wrapped in a try/catch that succeeds silently when the field is
+  absent. CLAUDE.md already warns ops about needing to add the field to
+  the live Documenso template; this code change would make the deployment
+  gap observable. Fix: when `context.eoiBerthRange` is non-empty AND the
+  field is absent, log at warn level + surface a structured response field.
+
+- **Email body merge expansion happens after token validation** —
+  `src/lib/services/document-sends.service.ts:399-403`. If a merge value
+  contains a `{{token}}` substring (e.g. a client name like
+  `"Acme {{discount}} Inc."`), the expanded body will contain a token
+  the unresolved-check missed and ships with literal braces. Fix: HTML-
+  escape merge values before expansion, OR run a second
+  `findUnresolvedTokens` against the expanded body.
+
+- **Filesystem dev-fallback HMAC secret can drift across processes** —
+  `src/lib/storage/filesystem.ts:328-331`. The dev-only fallback derives
+  the HMAC secret from `BETTER_AUTH_SECRET`. Two CRM processes running
+  with different secrets (web vs worker) reject each other's tokens.
+  Fix: assert `BETTER_AUTH_SECRET` is set when filesystem backend is
+  active in non-prod, or document the requirement loudly.
+
+- **Berth PDF apply path: numeric column nulling silently drops** —
+  `src/lib/services/berth-pdf.service.ts:473-475`. When
+  `Number.isFinite(n)` is false the apply loop `continue`s without
+  pushing to `applied` and without warning. Combined with the
+  "no appliable fields supplied" check (only fires when ALL drop), partial
+  silent drops are invisible. Fix: collect dropped keys and surface them.
+
+## Multi-tenant isolation hardening
+
+- **document_sends row stores `interestId` without verifying port match** —
+  `src/lib/services/document-sends.service.ts:422`. Audit-log pollution
+  rather than data exposure (the recipient lookup is port-checked already).
+  Fix: when `recipient.interestId` is set, fetch with
+  `and(eq(interests.id, ...), eq(interests.portId, input.portId))` and
+  throw if missing.
+
+- **Storage proxy token does not bind to port_id** —
+  `src/lib/storage/filesystem.ts:73-84`. ProxyTokenPayload is `{k, e, n,
+f?, c?}` with a global HMAC. The current "issuer always checks port
+  first" relies on every issuer being correct in perpetuity. Fix: add a
+  `p` (portId) claim and have the proxy route resolve key→owner row +
+  assert `owner.portId === payload.p` before streaming.
+
+- **Documenso webhook does not enforce port_id on document lookups** —
+  `src/app/api/webhooks/documenso/route.ts:96-148`. Handlers dispatch by
+  global `documensoId`. If two ports' documents were ever issued the
+  same Documenso ID (replay across staging/prod, forwarded webhook from
+  a foreign instance), the wrong port's interest could be mutated. The
+  per-body `signatureHash` dedup is partial mitigation. Fix: either
+  (a) include the originating Documenso instance/team in the lookup, or
+  (b) verify `documents(documenso_id)` has a unique index port-wide.
+
+## Recent expense work polish
+
+- **renderReceiptHeader cursor math drifts after multi-step writes** —
+  `src/lib/services/expense-pdf.service.ts:854`. After
+  `doc.text(...)` with auto-flow, `doc.y` advances. Using `doc.y -
+headerH + 10` after the rect+stroke block computes against the
+  post-rect position; works only because pdfkit's text-after-rect
+  hasn't moved y yet. Headers may misalign on the first receipt page
+  after a soft page break. Fix: capture `const baseY = doc.y` before
+  drawing the rect and compute all subsequent offsets relative to it.
+
+## Settings parsing
+
+- **`loadRecommenderSettings` rejects string-shaped JSONB booleans** —
+  `src/lib/services/berth-recommender.service.ts:116`. Postgres returns
+  JSONB `true/false` as JS booleans, but if an admin saves `"true"`
+  via a UI that wraps the value as a string, `asBool` returns null and
+  the per-port override silently falls through to defaults. Not a
+  security bug; a tuning footgun. Fix: accept `"true"`/`"false"` string
+  forms in `asBool`.
+
+# Audit-final v2 (post-merge platform-wide pass) deferred findings
+
+A second comprehensive audit (security, routes, DB, integrations, UI/UX)
+ran after the merge. The high-impact items landed in commit
+`fix(audit-final-v2): platform-wide hardening` (or similar). Items below
+are deferred follow-ups.
+
+## Routes / API
+
+- **Saved-views routes lack `withPermission`** —
+  `src/app/api/v1/saved-views/[id]/route.ts:4-5` and
+  `src/app/api/v1/saved-views/route.ts:24`. Convention is
+  `withAuth(withPermission(...))`. Verify the service applies
+  `(ctx.userId, ctx.portId)` ownership filtering, then add either an
+  explicit owner-only comment or wrap with a benign permission gate.
+
+- **Custom-fields permission resource hardcoded to `clients`** —
+  `src/app/api/v1/custom-fields/[entityId]/route.ts:15,29`. Custom fields
+  attach to client / yacht / interest / berth / company, but the route
+  always checks `clients.view` / `clients.edit`. A user with
+  `companies.view` can read confidential company custom-field values via
+  this endpoint (the service-level `customFieldDefinitions.portId` filter
+  prevents cross-tenant access but not cross-resource within a tenant).
+  Fix: split into per-entity routes, OR resolve `entityType` and gate on
+  the matching permission inline.
+
+- **`alerts/[id]/acknowledge|dismiss` ungated** —
+  `src/app/api/v1/alerts/[id]/acknowledge/route.ts:6` etc. only `withAuth`,
+  no `withPermission`. Verify the service requires user ownership; if
+  not, gate on `reports.view_dashboard` or similar.
+
+- **Public POST routes bypass service layer** —
+  `src/app/api/public/interests/route.ts`, `…/website-inquiries/route.ts`,
+  `…/residential-inquiries/route.ts`. These do extensive `tx.insert(...)`
+  with hand-rolled audit logs (`userId: null as unknown as string`).
+  Extract a `publicInterestService.create(...)` so the same code path is
+  unit-testable and port-id discipline is uniform. Verify
+  `audit_logs.user_id` is nullable (the cast pattern signals it is, but
+  enforce in schema if not).
+
+- **Inconsistent response shapes** — most endpoints return `{ data: ... }`,
+  but `notifications/[notificationId]` returns `{ success: true }`,
+  `website-inquiries` returns `{ id, deduped }`. Document a convention in
+  CLAUDE.md and migrate.
+
+- **`req.json()` without `parseBody` helper** — admin custom-fields
+  routes use `await req.json(); schema.parse(body)` directly instead of
+  the project's `parseBody(req, schema)` helper. Migrate for uniform
+  400 error shapes.
+
+## Documenso integration
+
+- **v2 voidDocument endpoint may not match real API** —
+  `src/lib/services/documenso-client.ts:450-466`. The audit flagged that
+  Documenso 2.x exposes envelope deletion as
+  `POST /api/v2/envelope/delete` with `{ envelopeId }` body, not
+  `DELETE /api/v2/envelope/{id}`. The unit test mocks fetch so it can't
+  catch the real shape. Verify against a live Documenso 2.x instance
+  (`pnpm exec playwright test --project=realapi`) before flipping any
+  port to v2.
+
+- **Webhook dedup vs per-recipient signed events** —
+  `src/app/api/webhooks/documenso/route.ts:103-110`. The top-level
+  `signatureHash` (sha256 of raw body) blocks exact replays, but a
+  duplicate webhook delivery for a multi-recipient document with a
+  re-encoded body will go through the per-recipient loop. Make
+  `documentEvents.signatureHash` unique cover the suffixed values OR add
+  a composite unique index `(documensoDocumentId, recipientEmail, eventType)`.
+
+- **v1 `placeFields` per-field POST has no retry** —
+  `src/lib/services/documenso-client.ts:374-398`. A single transient 500
+  mid-loop leaves the document with a partial field set. Add 3-attempt
+  exponential backoff on 5xx + voidDocument on final failure.
+
+## Storage
+
+- **S3 backend has no startup bucket-exists check** —
+  `src/lib/storage/s3.ts:100-111`. A typo'd bucket name surfaces as a
+  500 inside a user-facing request rather than at boot. Add
+  `await client.bucketExists(bucket)` in `S3Backend.create` with a clear
+  error message.
+
+- **Storage cache fingerprint includes encrypted secret** —
+  `src/lib/storage/index.ts:158-159`. After a key rotation the old
+  cached client survives until `resetStorageBackendCache()` is called
+  (already called via the settings-write hook). Document the
+  invariant or fingerprint on a content-hash that excludes encrypted
+  material.
+
+- **Filesystem dev HMAC silent fallback** —
+  `src/lib/storage/filesystem.ts:309-332`. Two dev nodes started with
+  different `BETTER_AUTH_SECRET` derive different secrets and reject
+  each other's tokens. Log a one-line warn at backend boot in non-prod.
+
+## DB schema
+
+- **`berths.current_pdf_version_id` lacks Drizzle FK** —
+  `src/lib/db/schema/berths.ts:83`. The FK exists in migration 0030
+  but not in the schema source-of-truth, so `pnpm db:push` against an
+  empty DB skips the constraint. Either add the FK with a deferred
+  declaration or document that `db:push` is unsupported.
+
+- **Missing indexes on FK columns** — `berthReservations.interestId`,
+  `berthReservations.contractFileId`, `documents.fileId`,
+  `documents.signedFileId`, `documentEvents.signerId`,
+  `documentTemplates.sourceFileId`, `formSubmissions.formTemplateId`,
+  `formSubmissions.clientId`, `documentSends.brochureId`,
+  `documentSends.brochureVersionId`, `documentSends.sentByUserId`. Add
+  `index(...)` declarations to avoid full-scan FK checks on parent
+  delete.
+
+- **`systemSettings` PK / unique-index drift** —
+  `src/lib/db/schema/system.ts:119-133`. Schema declares only a
+  `uniqueIndex` on `(key, port_id)` but the migration uses `key` as PK.
+  `port_id` is nullable so `(key, port_id)` cannot serve as a PK with
+  default NULLs-not-equal semantics. Reconcile: declare
+  `primaryKey({ columns: [table.key, table.portId] })` (after making
+  `portId` non-null with a sentinel) OR use partial unique indexes for
+  global + per-port settings.
+
+- **Composite vs partial archived indexes** — many tables use
+  `index('idx_*_archived').on(portId, archivedAt)` when the dominant
+  query is `WHERE port_id = ? AND archived_at IS NULL`. Convert to
+  `index(...).on(portId).where(sql\`archived_at IS NULL\`)` partial
+  indexes for smaller storage + faster planner choice.
+
+- **`documentSends.sentByUserId` ungated FK** —
+  `src/lib/db/schema/brochures.ts:118` is `notNull()` but has no FK
+  reference. If a user is hard-deleted (rare; we soft-delete), an
+  orphan id remains. Add `.references(() => users.id, { onDelete: 'set null' })`
+  and make the column nullable. Same audit-trail rationale as the
+  other documentSends FK fixes (commit 0035).
+
+## UI/UX
+
+- **Storage admin migration mutation lacks toasts** —
+  `src/components/admin/storage-admin-panel.tsx:61-72`. Add `onSuccess`
+  toast with row count + `onError` toast.
+
+- **Invoice detail send/payment mutations lack error feedback + gates** —
+  `src/components/invoices/invoice-detail.tsx:93-99,152-167`. Add
+  `onError: (e) => toast.error(...)` and wrap mutating buttons in
+  `<PermissionGate resource="invoices" action="send">` /
+  `record_payment`.
+
+- **Admin user list edit button ungated** —
+  `src/components/admin/users/user-list.tsx:114`. Wrap in
+  `<PermissionGate resource="admin" action="manage_users">`.
+
+- **Email threads list missing skeleton** —
+  `src/components/email/email-threads-list.tsx:29-45`. Use `<Skeleton>`
+  rows during load + `<EmptyState>` for the empty case.
+
+- **Scan page mutations swallow OCR errors** —
+  `src/app/(dashboard)/[portSlug]/expenses/scan/page.tsx:67-87`. Add an
+  inline error state for `scanMutation.isError` (the upload-side
+  already does this).
+
+- **Invoice detail uses `any` for query data** — strict-mode escape
+  hatch. Define a proper response type matching the API contract.
+
+## Security defense-in-depth
+
+- **Storage proxy token does not bind to port_id** —
+  `src/lib/storage/filesystem.ts:73-84`. Token's HMAC is global. Fix:
+  add `p` (portId) claim and have the proxy resolve key→owner row +
+  assert `owner.portId === payload.p`.
+
+- **Documenso webhook does not enforce port_id** —
+  `src/app/api/webhooks/documenso/route.ts:96-148`. Handlers dispatch
+  by global `documensoId`. Verify `documents(documenso_id)` is unique
+  port-wide OR include the originating instance/team in the lookup.
+
+- **EOI in-app pathway silently swallows missing `Berth Range` field** —
+  `src/lib/pdf/fill-eoi-form.ts:93`. Log warn when
+  `context.eoiBerthRange` is non-empty AND the field is absent so the
+  Documenso template deployment gap is observable.
+
+- **AI worker has no cost-tracking ledger write** —
+  `src/lib/queue/workers/ai.ts:122-177`. Persist token usage to the
+  `ai_usage` ledger after every call.
+
+- **Logger redact paths miss nested credentials** —
+  `src/lib/logger.ts:5-19`. Extend redact list to cover
+  `*.headers.authorization`, `**.token`, `secretKeyEncrypted`, etc.

docs/audit-findings-tmp/01a-legacy-master-grep.md

@@ -0,0 +1,22 @@
+# L-001 Legacy Stage Enum Master Grep — agent #12 (re-dispatch slice 1)
+
+**Headline:** The 9→7 stage refactor is correctly implemented; zero bugs found across 25 files with legacy-stage-name hits.
+
+**Counts:** 0 critical · 0 high · 0 medium
+
+---
+
+## Verdict
+
+The two `stageRank` Records (`clients.service.ts:276-283`, `berth-recommender.service.ts:195-210`) intentionally include both legacy AND modern keys mapping to the same final ranks — yesterday's commit `9821106` purged the gap. The rules engine (`berth-rules-engine.ts:15-42`) and document services use legacy _trigger event_ names (`eoi_sent`/`eoi_signed`/`contract_signed`) rather than stage names — both old and new events fire correctly because they're labels for webhook/doc events, not pipeline stages.
+
+## Legitimate / neutral hit categories
+
+- **Historical lookup tables (designed for dual-stage support):** `clients.service.ts:276-283` `stageRank`, `berth-recommender.service.ts:195-210` `STAGE_ORDER` — both have legacy + modern keys.
+- **Refactor mapping definitions:** `constants.ts:59-65` `LEGACY_STAGE_REMAP`; `dedup/migration-transform.ts:206-212` legacy-to-legacy map for NocoDB import.
+- **Rules engine + service layer (legacy-aware design):** `berth-rules-engine.ts:15-42` (trigger event labels), `external-signing.service.ts:37-41`, `documents.service.ts:786/909/1503/1544/1574` (`evaluateRule('eoi_sent'|'eoi_signed'|'contract_signed', ...)`), `external-eoi.service.ts:138-151` (intentional legacy-aware advance branch).
+- **Schema metadata:** `db/schema/interests.ts:61-65` field names (`dateEoiSent`, `dateEoiSigned`, `dateContractSent`, `dateContractSigned`) — historical schema column names.
+- **UI display:** `email/templates/notification-digest.tsx:29` `eoi_signed: 'EOI signed'` label for historical data.
+- **Comments only:** `alert-rules.ts:83`, `interests.service.ts:938/980/1095`, `berths.service.ts:175`, `db/schema/operations.ts:98`.
+
+**No silent-failure lookup tables. No rank-0 fallthrough patterns. No raw legacy enum keys leaking to the UI without remap.**

docs/audit-findings-tmp/01b-legacy-rendering-surfaces.md

@@ -0,0 +1,28 @@
+# L-002-011 Legacy Stage Rendering Surfaces — done in main thread (sub-agent context-thrashed)
+
+**Headline:** Mostly clean. One LOW finding: report-generators stage rollup keys are raw enum without `LEGACY_STAGE_REMAP`/`canonicalizeStage` — defensive-coding gap if any active row drifts back to a legacy stage value (migration 0062 normalized, so this is theoretical).
+
+**Counts:** 0 critical · 0 high · 0 medium · 1 low (defensive)
+
+---
+
+## 🟢 LOW L-008: Reports stage-revenue rollup uses raw `interests.pipelineStage` without `canonicalizeStage`
+
+- **File:** `src/lib/services/report-generators.ts:71-76, 88-106, 124-138, 176-192`
+- **What:** `stageRevenueMap[row.stage] = ...` and `pipelineWeights[row.stage]` use the raw enum value from the SQL `groupBy(interests.pipelineStage)`. No `canonicalizeStage()` wrap.
+- **Why it matters:** Migration 0062 normalized historical data to modern values, so today active rows should all be in the 7-stage set and bucketing is correct. But if any leakage occurs (NocoDB re-import, partial migration on a future port, manual `psql` write), legacy values would be siloed into their own bucket and `pipelineWeights[legacy_value]` returns `undefined` → that bucket contributes 0 to the forecast. Silent.
+- **Suggested fix:** Wrap row.stage with `canonicalizeStage(row.stage)` from `src/lib/utils/legacy-stage.ts` before keying into `stageRevenueMap` / `pipelineWeights`.
+
+---
+
+## ✅ Passing checks
+
+- **L-002 audit log diff** — `audit-log-list.tsx` / `audit-log-card.tsx` don't render stage values at all (just field-name keys per agent #4's AU-08 finding). No raw-enum render path exists.
+- **L-003 activity feed** — `src/components/dashboard/activity-feed.tsx:14,57` imports and uses `LEGACY_STAGE_REMAP` for the stage_change diff line.
+- **L-004 email templates** — `src/lib/email/templates/notification-digest.tsx:24` `TYPE_LABELS` includes `eoi_signed` as a _notification type_ label (the doc-status event), not a pipeline stage. Legitimate.
+- **L-005 Documenso payload** — `src/lib/services/documenso-payload.ts` and `src/lib/templates/merge-fields.ts` have zero `pipelineStage` / `pipeline_stage` references. EOI payload doesn't surface stage.
+- **L-006 public berths status filter** — already verified clean by agent #7 (IN-17). `src/lib/services/public-berths.ts:90-97` `derivePublicStatus` only branches on `sold` / `under_offer` / else `available`. No legacy enum acceptance.
+- **L-007 outbound webhook** — `webhook-dispatch.ts` is a passthrough; payload built at `interests.service.ts:919-934` (`emitToRoom` + `dispatchWebhookEvent`). New stage value is current modern (write-time enforcement). `oldStage` could be legacy if the row was historical, but that's the actual historical truth — informational.
+- **L-009 search FTS on stages** — `interests` has no FTS GIN index at all (per agent #2's SC-04 finding); migration 0057 covers only clients/yachts/residential_clients. Stage searchability via FTS is moot. (SC-04 fix should add interests FTS — when added, the GENERATED expression should use `stageLabelFor` for the stage column.)
+- **L-010 notifications** — `next-in-line-notify.service.ts:63-65` falls back to `i.pipelineStage.replace(/_/g, ' ')` when `STAGE_LABELS` lookup misses. STAGE_LABELS is the modern-only map; legacy values would render as "eoi signed" etc. Recommended switch to `stageLabelFor()` for legacy resilience, but: only fires for active interests where stage is modern, so functionally clean today.
+- **L-011 CSV importers** — Only import services are `berth-import.ts` and `document-import.ts`; neither references `pipelineStage`. No CSV stage-import path exists, so no risk of legacy value re-entry through this vector.

docs/audit-findings-tmp/01c-legacy-adjacent-enums.md

@@ -0,0 +1,26 @@
+# L-013-020 Adjacent Enum Drift — agent #14 (re-dispatch slice 3)
+
+**Headline:** Single medium finding (tenure type enum diverges between berths and reservations); all other enums consistent.
+
+**Counts:** 0 critical · 0 high · 1 medium
+
+---
+
+## 🟡 MEDIUM L-018: Tenure type enum diverges between berths and reservations
+
+- **Files:** `src/lib/db/schema/berths.ts:65` vs `src/lib/db/schema/reservations.ts:32`
+- **What:** `berths.tenureType` documents `'permanent' | 'fixed_term' | 'fee_simple' | 'strata_lot'` (4 values). `reservations.tenureType` documents `'permanent' | 'fixed_term' | 'seasonal'` (3 values). Same column name, divergent allowed values.
+- **Why it matters:** No writes indicate actual cross-table conflict yet, but the schema-comment mismatch is a trap — a future feature copying tenure between the two tables would silently accept invalid values for the receiving side.
+- **Suggested fix:** Pick a single canonical enum (likely `'permanent' | 'fixed_term' | 'fee_simple' | 'strata_lot' | 'seasonal'` as the union) and update both schemas + comments. Or rename one column to disambiguate intent.
+
+---
+
+## ✅ Passing checks
+
+- L-013 berth status `available/under_offer/sold` — only writes are in `berth-rules-engine.ts` respecting the 3-value set
+- L-014 statusOverrideMode — `manual/automated/null`; migration 0066 normalizes legacy `'auto'` → NULL; only writers in rules-engine + reconcile-queue both respect three-state
+- L-015 outcome — `won/lost_other_marina/lost_unqualified/lost_no_response/cancelled`; only writes in `interest-outcome.service.ts`; no legacy `'completed'` outcome anywhere
+- L-016 lead category — `general_interest/specific_qualified/hot_lead`; no out-of-set writes
+- L-017 lead source — `website/manual/referral/broker`; no out-of-set writes
+- L-019 doc status (`eoiDocStatus`, `reservationDocStatus`, `contractDocStatus`) — `pending/sent/signed/declined/voided`; mark-externally-signed only writes `'signed'`; Documenso webhook routes all status updates through services consistent with the set
+- L-020 reservation/contract status — `pending/active/ended/cancelled`; only writes in `reservation-state-machine.ts`

docs/audit-findings-tmp/02-multitenancy-schema.md

@@ -0,0 +1,105 @@
+# Multi-tenancy + Schema Audit (MT-01-11, SC-01-15) — agent #2
+
+**Headline:** API port isolation structurally sound, but 5 write paths do port check in JS without re-asserting portId in WHERE (TOCTOU gaps). Schema has several FKs that are `ON DELETE NO ACTION` in DB while nullable Drizzle declarations imply SET NULL — most critically `documents.clientId` and all `berthReservations` FKs.
+
+**Counts:** 0 critical · 1 high · 8 medium · 0 low.
+
+---
+
+## 🟠 HIGH SC-02: Multiple significant FKs missing `onDelete` — remain `ON DELETE NO ACTION`
+
+- **Files:**
+  - `src/lib/db/schema/interests.ts:29,32` — `interests.portId`, `interests.clientId`
+  - `src/lib/db/schema/documents.ts:72,85,86` — `documents.clientId`, `documents.fileId`, `documents.signedFileId`
+  - `src/lib/db/schema/reservations.ts:18,24,25,27,28,33` — all 6 `berthReservations` FKs
+  - `src/lib/db/schema/operations.ts:25` — `reminders.clientId`
+  - `src/lib/db/schema/financial.ts:120` — `invoices.pdfFileId`
+  - `src/lib/db/schema/documents.ts:176` — `documentEvents.signerId`
+- **What:** `.references(...)` without `{ onDelete: ... }` emits `ON DELETE NO ACTION`. Confirmed in migration 0000:841 (`interests_client_id_clients_id_fk ... ON DELETE no action`).
+- **Why it matters:** Hard-deleting a parent (client, berth, yacht, file) blocks at FK level. `client-hard-delete.service.ts` manually nullifies but `berthReservations` (4 NO ACTION FKs) is not in the chain. Future maintenance trap.
+- **Suggested fix:** Add `{ onDelete: 'set null' }` for nullable FKs that should tolerate parent deletion; explicit `{ onDelete: 'restrict' }` for those that intentionally block (e.g., `interests.clientId` — design intent is archive-first).
+
+## 🟡 MEDIUM MT-01: `updateDefinition` UPDATE uses only `id` in WHERE, not `and(id, portId)`
+
+- **File:** `src/lib/services/custom-fields.service.ts:136-145`
+- **What:** Guard read uses `and(eq(id, fieldId), eq(portId, portId))`, but UPDATE fires with only `eq(customFieldDefinitions.id, fieldId)`.
+- **Why it matters:** TOCTOU race between read check and write.
+- **Suggested fix:** Mirror `updateTag`/`deleteTag`: add `and(eq(...id), eq(...portId, portId))` to the UPDATE WHERE.
+
+## 🟡 MEDIUM MT-01: `notes.service.ts` UPDATE/DELETE missing entityId scope
+
+- **File:** `src/lib/services/notes.service.ts:846-850, 869-873, 897-901`
+- **What:** All note `update()` branches verify ownership via prior SELECT, then UPDATE/DELETE on `eq(...notes.id, noteId)` alone (no `eq(yachtNotes.yachtId, entityId)` etc).
+- **Why it matters:** TOCTOU gap; risk currently low (UUIDs, no cross-entity discovery surface).
+- **Suggested fix:** Add `eq(...notes.<parent>Id, entityId)` to each UPDATE/DELETE WHERE.
+
+## 🟡 MEDIUM MT-01: `clients.service.ts::updateContact` / `removeContact` UPDATE/DELETE use only `contactId`
+
+- **File:** `src/lib/services/clients.service.ts:737-741, 764`
+- **What:** PortId verified in JS only; mutation has no portId guard.
+- **Suggested fix:** Add `eq(clientContacts.clientId, clientId)` to the UPDATE/DELETE WHERE.
+
+## 🟡 MEDIUM MT-04: `notes.service.ts::listForYachtAggregated` ownerClientId lookup has no portId guard
+
+- **File:** `src/lib/services/notes.service.ts:276-283`
+- **What:** Owner client SELECT uses only `eq(clients.id, ownerClientId)`. Yacht is verified in port but cross-port ownerClientId would still surface.
+- **Suggested fix:** Add `eq(clients.portId, portId)`.
+
+## 🟡 MEDIUM MT-06: `webhooks.service.ts::getWebhook` / `updateWebhook` / `deleteWebhook` fetch by `id` only, portId checked in JS
+
+- **File:** `src/lib/services/webhooks.service.ts:103-108, 133-137, 170-174`
+- **What:** Fetches full webhook row (incl. encrypted secret) before JS port check.
+- **Why it matters:** Defense-in-depth gap — secret briefly in app memory before authz check.
+- **Suggested fix:** Move portId into `findFirst` WHERE.
+
+## 🟡 MEDIUM SC-01: Migration 0000 (and 0001-0023) uses bare CREATE/ALTER without IF NOT EXISTS
+
+- **File:** `src/lib/db/migrations/0000_narrow_longshot.sql`
+- **What:** No `IF NOT EXISTS` guards on CREATE TABLE/INDEX. Migration 0036 also bare `ALTER TABLE ... ADD CONSTRAINT`. Later migrations (0042, 0050, 0051, 0052, 0057, 0062, 0065) use IF NOT EXISTS / DO blocks correctly.
+- **Why it matters:** Drizzle tracker prevents double-runs in normal flow, but disaster-recovery partial replay would fail.
+- **Suggested fix:** Document that 0000-0036 are not re-runnable without dropping schema first; standardize on IF NOT EXISTS / DO block pattern for all new migrations.
+
+## 🟡 MEDIUM SC-03: `companies` table missing soft-delete partial index for `archivedAt`
+
+- **File:** `src/lib/db/schema/companies.ts:39-45`
+- **What:** Other entities (clients, interests, yachts, berths, residentialClients, residentialInterests) have `idx_*_archived ... WHERE archived_at IS NULL` partial indexes (migration 0046). Companies missing.
+- **Suggested fix:** `CREATE INDEX IF NOT EXISTS idx_companies_archived ON companies (port_id) WHERE archived_at IS NULL;`
+
+## 🟡 MEDIUM SC-04: FTS GIN indexes missing for `interests` and `berths`
+
+- **File:** `src/lib/db/migrations/0057_search_fts_indexes.sql`
+- **What:** Migration 0057 creates GIN indexes for clients/yachts/residentialClients but explicitly notes companies uses ILIKE. Interests and berths also lack GIN indexes.
+- **Suggested fix:** `CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_interests_fulltext ON interests USING gin (...)` and similar for berths.
+
+## 🟡 MEDIUM SC-08: `audit_logs.searchText` declared as plain column in Drizzle but is GENERATED ALWAYS in DB
+
+- **File:** `src/lib/db/schema/system.ts:53-54`
+- **What:** Drizzle `tsvector('search_text')` without generated annotation. If any service auto-includes this column in an UPDATE, it errors on the generated column. `audit_logs` is insert-only so likely not hit in practice, but schema-DB mismatch.
+- **Suggested fix:** Annotate as non-updateable or add a generated-column marker.
+
+## 🟡 MEDIUM SC-09: `documents.clientId` Drizzle nullable but DB is `ON DELETE NO ACTION`
+
+- **File:** `src/lib/db/schema/documents.ts:72`, migration `0000_narrow_longshot.sql:814`
+- **What:** Drizzle says nullable (intent: SET NULL on parent delete); DB constraint is NO ACTION (blocks delete). Migration 0042 fixed `documents.interestId/yachtId/companyId` but missed `clientId`.
+- **Why it matters:** Client hard-delete fails unless service explicitly nulls `documents.clientId` first.
+- **Suggested fix:** Migration to mirror what 0059 did for `files.client_id` — drop and re-add FK with `ON DELETE SET NULL`.
+
+---
+
+## ✅ Passing checks
+
+- MT-01 clean: clients/interests/invoices/documents/files/tags/companies/berth-reservations GET/PATCH/DELETE all use `and(id, portId)` SQL filter; notes-service `verifyParentBelongsToPort` correct
+- MT-04 document-folders.service.ts clean (`listTree`, `createFolder`, `renameFolder`, `moveFolder`, `deleteFolderSoftRescue` all apply `eq(documentFolders.portId, portId)`)
+- MT-05 audit.service.ts `listAuditLogs` filters by portId first
+- MT-07 settings.service.ts clean (port-specific then global fallback by design)
+- MT-08 tags.service.ts clean
+- MT-09 custom-fields read/create/delete clean (only update missed; covered above)
+- MT-11 seed.ts idempotent (`SELECT count(*) FROM companies WHERE port_id = $1` early-exit)
+- SC-02 interestBerths.berthId/interestId, files.clientId/yachtId/companyId, documents.interestId/yachtId/companyId/reservationId all have explicit onDelete
+- SC-05 doc folder sibling-name unique, entity-folder partial unique, isPrimary partial unique all present
+- SC-06 idx_brochures_default partial unique present
+- SC-07 chk_system_folder_shape present (tightened by migration 0052)
+- SC-12 Migration 0062 normalizes legacy stages, 0066 normalizes statusOverrideMode='auto' → NULL
+- SC-13 Currency code stored as text + app-level validation (consistent)
+- SC-14 Address components stored as ISO 3166-2/alpha-2 text columns (consistent)
+- SC-15 Polymorphic owner reads use service helpers (eoi-context.ts, interests.service.ts, berth-reservations.service.ts); raw column reads only in JOIN conditions

docs/audit-findings-tmp/03-routes-auth.md

@@ -0,0 +1,68 @@
+# Routes/Middleware/Auth Audit (R-016-029, S-09-13, S-17-19) — agent #3
+
+**Headline:** 1 critical (`/setup` unreachable on fresh DB — middleware redirect loop), 3 high (post-login `?redirect=` ignored; CRM invite token in query string leaks to access logs; missing `Retry-After` on sign-in 429), 2 medium (broad portal allowlist, no OPTIONS handlers), 13 clean.
+
+**Counts:** 1 critical · 3 high · 2 medium · 0 low · 13 passing
+
+---
+
+## 🔴 CRITICAL R-021: `/setup` missing from `PUBLIC_PATHS` — bootstrap unreachable on fresh DB
+
+- **File:** `src/proxy.ts:51-73`
+- **What:** `PUBLIC_PATHS` includes `/api/v1/bootstrap/` but NOT `/setup`. Comment at lines 60-62 says login + setup pages call bootstrap status, but `/setup` itself is not exempt from the session guard. Unauthenticated user → `/setup` → middleware redirects to `/login?redirect=/setup`. Login useEffect fetches bootstrap status, calls `router.replace('/setup')` → middleware again → infinite redirect loop.
+- **Why it matters:** Fresh deployment (no super admin) is functionally deadlocked. First operator cannot reach setup without already having a session (impossible on fresh DB).
+- **Suggested fix:** Add `'/setup'` to `PUBLIC_PATHS`. `POST /api/v1/bootstrap/super-admin` already self-protects with `hasAnySuperAdmin()`.
+
+## 🟠 HIGH R-017/018: CRM post-login redirect ignores `?redirect=` — deep links silently dropped
+
+- **File:** `src/app/(auth)/login/page.tsx:79`
+- **What:** Middleware redirects unauthenticated → `/login?redirect=<path>`. Login page never reads `useSearchParams()`; always `router.push('/dashboard')`.
+- **Why it matters:** Email/bookmark/shared deep links into specific clients/interests silently dump to dashboard after login.
+- **Suggested fix:** Read `searchParams.get('redirect')`, validate same-origin (starts with `/`, not `//`), use as push target if valid.
+
+## 🟠 HIGH R-023: CRM invite token in query string leaks to access logs
+
+- **File:** `src/lib/services/crm-invite.service.ts:71,233`
+- **What:** `${env.APP_URL}/set-password?token=${raw}` — raw 32-byte token in query param. Set-password page reads via `useSearchParams()`. Portal flow was migrated to `#token=` fragment in 2026-05-14 specifically to keep tokens out of logs/Referer; CRM invite path missed the migration.
+- **Why it matters:** Every nginx/Caddy access log line for `GET /set-password?token=<raw>` persists token to disk. Forwarded to SIEM/S3/monitoring → token visible to anyone with log access. Token grants account creation.
+- **Suggested fix:** Change `createCrmInvite` + `resendCrmInvite` to emit `${env.APP_URL}/set-password#token=${encodeURIComponent(raw)}`. Update `set-password/page.tsx` to use the fragment-reading pattern from `PasswordSetForm` (`readTokenFromUrl()`) with `?token=` back-compat for outstanding tokens.
+
+## 🟠 HIGH R-029: `sign-in-by-identifier` 429 missing `Retry-After`
+
+- **File:** `src/app/api/auth/sign-in-by-identifier/route.ts:47-51`
+- **What:** Builds 429 response with `headers: rateLimitHeaders(rl)` which only emits `X-RateLimit-Limit/Remaining/Reset` (`src/lib/rate-limit.ts:79-85`). `enforcePublicRateLimit` adds `Retry-After`; this route uses `checkRateLimit` directly and skips it.
+- **Why it matters:** RFC 6585 §4 requires `Retry-After` on 429. Automated clients can't back off correctly. Inconsistent with other public endpoints.
+- **Suggested fix:** Add `'Retry-After': Math.max(1, Math.ceil((rl.resetAt - Date.now()) / 1000)).toString()`.
+
+## 🟡 MEDIUM R-016: `/portal/` blanket allowlist removes middleware as backstop
+
+- **File:** `src/proxy.ts:65`
+- **What:** `'/portal/'` in `PUBLIC_PATHS` — every `/portal/*` is exempt from middleware session check. Per-page `getPortalSession()` is the only gate.
+- **Why it matters:** Defense-in-depth gap. Per-page checks all in place today; but a future portal page added without `getPortalSession()` has no middleware backstop. Fragile vs CRM's primary middleware gate.
+- **Suggested fix:** Allowlist only the unauthenticated portal routes individually (`/portal/login`, `/portal/activate`, `/portal/reset-password`, `/portal/forgot-password`). Add middleware portal-cookie check.
+
+## 🟡 MEDIUM R-028: No explicit `OPTIONS` handlers, no CORS headers
+
+- **File:** All `route.ts` files under `src/app/api/`
+- **What:** No `OPTIONS` exports. No `Access-Control-Allow-*` headers anywhere. Next.js will 405 on unhandled OPTIONS.
+- **Why it matters:** Acceptable for same-origin CRM. Becomes an issue if marketing-site browser JS calls `/api/public/berths` cross-origin.
+- **Suggested fix:** Defer until cross-origin consumer exists. When marketing site lives, add explicit `Access-Control-Allow-Origin: <marketing-domain>` to public routes (not wildcard).
+
+---
+
+## ✅ Passing checks
+
+- R-016 allow-list anchor — `startsWith('/api/public/')` correctly rejects `'/api/publicX-evil'` (no regex anchor concern)
+- S-09 open redirect on next/redirect — CRM login ignores param (no risk because unused); portal `safeNextPath()` (portal/login/page.tsx:20-27) rejects non-`/portal/` paths and `//`-protocol-relative
+- S-10 CSRF — defense-in-depth: `proxy.ts originAllowed()` (lines 104-122) rejects state-changing `/api/v1/**` where Origin/Referer don't match in prod; better-auth has its own origin check for `/api/auth/**`; dev bypass intentional
+- S-11 cookie flags — CRM: `httpOnly`, `secure` (prod), `sameSite: 'strict'` (`src/lib/auth/index.ts:107-110`); Portal: `httpOnly`, `secure` (prod), `sameSite: 'lax'` (`src/app/api/portal/auth/sign-in/route.ts:43-45`)
+- S-12 CSP — per-request nonce-based CSP via `proxy.ts:buildCspWithNonce()` for page routes in prod (`'nonce-<n>' 'strict-dynamic'`); fallback CSP in `next.config.ts:55-66`; `frame-ancestors: 'none'` + `X-Frame-Options: DENY`; HSTS, X-Content-Type-Options, Referrer-Policy, Permissions-Policy all present
+- S-13 CORS — no `Access-Control-Allow-Origin: *` anywhere (correct for same-origin CRM)
+- R-019/020 portal `client_portal_enabled` gate — `src/app/(portal)/layout.tsx:22` calls `isPortalDisabledGlobally()`; per-page `getPortalSession()` additionally guards
+- R-022 reset-password tokens — Portal: single-use `consumeToken` setting `usedAt`, 30min TTL, SHA-256 hashed in DB. Better-auth CRM: 1h TTL, `revokeSessionsOnPasswordReset: true`
+- R-023 portal half — `portal/activate/page.tsx` uses `PasswordSetForm` with `useSyncExternalStore + readTokenFromUrl()` reading `window.location.hash` client-side; SSR-safe via `null` server snapshot
+- R-025 public berths cache headers `s-maxage=300, stale-while-revalidate=60` confirmed in both list + single endpoints
+- R-026/027 public health: anonymous `{status,timestamp}` only never 503; `X-Intake-Secret` `timingSafeEqual` (lines 57-64); authenticated runs DB+Redis dep checks in parallel, 503 on either failure
+- S-17 session fixation — better-auth creates fresh session row on every sign-in; portal sign-in always issues new JWT via `createPortalToken`
+- S-18 token expiry/refresh — CRM 24h absolute, 6h sliding refresh window (`src/lib/auth/index.ts:99-103`); Portal JWT 24h checked against `passwordChangedAt` watermark per request
+- S-19 audit log tamper-resistance — `audit_logs` has no `updated_at`; no `UPDATE` calls in app code (only INSERT/SELECT and time-based retention DELETE bounded by `AUDIT_LOGS_RETENTION_DAYS`)

docs/audit-findings-tmp/04-audit-log.md

@@ -0,0 +1,92 @@
+# Audit Log Audit (AU-01-14) — agent #4
+
+**Headline:** Core write path solid; major mutations all audit; mask helper covers expected PII; FTS indexed; AU-11 fix complete. Two HIGH issues: encrypted credential ciphertext bypasses masking (key is `"value"`) and `toggleAccount` mutation is silent.
+
+**Counts:** 0 critical · 2 high · 4 medium · 4 low
+
+---
+
+## 🟠 HIGH AU-01a: `toggleAccount` writes no audit row
+
+- **File:** `src/lib/services/email-accounts.service.ts:86-116`
+- **What:** Sets `isActive` on email account with no `createAuditLog` call. `connectAccount` (line 70) and `disconnectAccount` (line 139) do, but enable/disable in between is silent.
+- **Why it matters:** Silently disabling an email account suppresses bounce-detection or reroutes replies — compliance gap on a security-relevant config change.
+- **Suggested fix:** Add `void createAuditLog({ action: 'update', entityType: 'email_account', entityId: accountId, newValue: { isActive: data.isActive }, ... })` inside `toggleAccount`.
+
+## 🟠 HIGH AU-02: Encrypted credential ciphertext stored in audit log without masking
+
+- **File:** `src/lib/services/settings.service.ts:66-76` + `src/lib/services/sales-email-config.service.ts:281-299`
+- **What:** `updateSalesEmailConfig` calls `upsertSetting('sales_smtp_pass_encrypted', <ciphertext>, portId, meta)`. `upsertSetting` records `newValue: { value: '<ciphertext>' }`. `maskSensitiveFields` checks JSON keys against `SENSITIVE_KEY_FRAGMENTS`; the wrapping key `"value"` isn't in the list. Ciphertext lands verbatim in `audit_logs.new_value`.
+- **Why it matters:** Audit log is readable by all admins with `admin.view_audit_log`. DB read access exfils ciphertext; if `EMAIL_CREDENTIAL_KEY` is ever compromised, the historical audit log becomes a credential store. Industry standard: store only `credentialUpdated: true` for credential changes.
+- **Suggested fix:** In `upsertSetting`, detect when key ends with `_encrypted` (or accept `redactValue?: boolean` flag) and record `newValue: { value: '[redacted]' }`.
+
+## 🟡 MEDIUM AU-03: FTS `search_text` covers only 4 fields; placeholder text misleads
+
+- **File:** `src/lib/db/migrations/0014_black_banshee.sql:47-55` + `src/components/admin/audit/audit-log-list.tsx:360`
+- **What:** `search_text` GENERATED ALWAYS = `action || entity_type || entity_id || user_id`. Search input placeholder reads "entity id, action, vendor…" — implies you can search inside `metadata`/`new_value`. Searching "vendor" returns zero rows silently.
+- **Suggested fix:** Change placeholder to "action name, entity id, user id…" OR add `metadata` to GENERATED expression with `jsonb_to_tsvector` (larger index).
+
+## 🟡 MEDIUM AU-08: Admin audit log shows field names but no old→new diff
+
+- **File:** `src/components/admin/audit/audit-log-list.tsx:290-305` + `src/components/admin/audit/audit-log-card.tsx:84-91`
+- **What:** "Changes" column renders `Object.keys(newValue).slice(0,3).join(', ')` — no old→new diff, no row-expand. Dashboard `activity-feed.tsx` has working `buildDiffLine()` with 3 diff shapes, unused here.
+- **Why it matters:** Compliance audits can't confirm before/after state from UI alone; admins must dig into raw JSON.
+- **Suggested fix:** Add row-expand or detail sheet using `buildDiffLine` from activity-feed.tsx.
+
+## 🟠 AU-10: Cascade-archived interests produce no individual audit rows
+
+- **File:** `src/lib/services/clients.service.ts:578-618`
+- **What:** `archiveClient` batch-archives open interests, writes ONE `entityType: 'client'` row with `newValue: { cascadedInterestIds: [...] }`. No per-interest rows. `search_text` doesn't include `new_value`, so searching for an interest ID returns nothing.
+- **Why it matters:** Auditor querying for a specific archived interest sees no archive event; must know to look at parent client row.
+- **Suggested fix:** Loop over `archivedInterestIds` and emit per-interest `createAuditLog({ action: 'archive', entityType: 'interest', entityId, metadata: { cascadeSource: 'client_archive', clientId } })` (fire-and-forget).
+
+## 🟡 MEDIUM AU-12: No audit log CSV export endpoint
+
+- **File:** (absent — no `src/app/api/v1/admin/audit/export/route.ts`)
+- **What:** No download button, no API. Expenses domain has reference impl at `src/app/api/v1/expenses/export/csv/route.ts`.
+- **Why it matters:** GDPR / marina licensing audits often require exports.
+- **Suggested fix:** `GET /api/v1/admin/audit/export/csv` reusing `searchAuditLogs` + filter params.
+
+## 🟡 MEDIUM AU-13: Outcome change uses `action: 'update'`, not distinct verb
+
+- **File:** `src/lib/services/interests.service.ts:1047-1058`
+- **What:** `setInterestOutcome`/`clearInterestOutcome` log `action: 'update'` with `metadata.type: 'outcome_set'/'outcome_cleared'`. No `outcome_change` in `AuditAction` or filter dropdown. `metadata.type` not in `search_text` — FTS can't isolate.
+- **Suggested fix:** Add `'outcome_change'` to `AuditAction` union; use in both functions; add to dropdown; add to `DEFAULT_SEVERITY_BY_ACTION` as `'warning'`.
+
+## 🟢 LOW AU-14: Tier map sparse; new actions default to 'info'
+
+- **File:** `src/lib/audit.ts:220-222`
+- **What:** Only 2 entries (`permission_denied: 'warning'`, `hard_delete: 'critical'`). `password_change`, `portal_activate`, `revoke_invite`, `branding.logo.uploaded`, `rule_evaluated` all default to `'info'`. Severity≥warning filter misses security-relevant events.
+- **Suggested fix:** Add `password_change/portal_activate/revoke_invite: 'warning'`. `reconcile_manual` is in `metadata.type` — add `severity: 'warning'` at the call site in `berths.service.ts`.
+
+## 🟢 LOW AU-14b: Action filter dropdown missing 12 verbs
+
+- **File:** `src/components/admin/audit/audit-log-list.tsx:393-415`
+- **What:** Dropdown has 20 actions; missing `branding.logo.*`, `rule_evaluated`, `revoke/resend_invite`, `request/send_gdpr_export`, `password_change`, `portal_invite/activate/password_reset_request/password_reset`. Free-text partially compensates.
+- **Suggested fix:** Add missing action verbs.
+
+## 🟢 LOW AU-14c: Entity-type filter missing several domains
+
+- **File:** `src/components/admin/audit/audit-log-list.tsx:88-102`
+- **What:** Missing `document_folder`, `file`, `company`, `yacht`, `email_account`, `audit_log`, `backup_job`. Free-text on `entity_type` (in tsvector) works; dropdown is convenience.
+- **Suggested fix:** Add missing entity types.
+
+## 🟢 LOW AU-14d: Dead code — `listAuditLogs` (ILIKE) in `audit.service.ts`
+
+- **File:** `src/lib/services/audit.service.ts`
+- **What:** `listAuditLogs` exported but zero import sites. Admin route uses `searchAuditLogs` exclusively. ILIKE search is dead.
+- **Why it matters:** Future dev might wire it up bypassing GIN index → seq scans at scale.
+- **Suggested fix:** Delete `audit.service.ts` or mark `@deprecated`.
+
+---
+
+## ✅ Passing
+
+- AU-01 (10 sampled mutating endpoints all audit: clients/interests/companies/berths/documents/folders/tags/roles/settings/files create + update + archive)
+- AU-02 password/token fragment masking covers `password`, `passwordHash`, `token`, `secret`, `api_key`, `apikey`, `auth`, `cookie`, `credentials` recursively up to depth 4. `email-accounts.service.ts` correctly logs only `metadata: { emailAddress, provider }`; `credentialsEnc` stripped before any JSON serialization.
+- AU-04 action filter wired (exact `eq()` filter)
+- AU-05 entity-type filter wired (same path)
+- AU-06 user filter wired (UUID exact match)
+- AU-07 date-range filter (ISO strings → Date → gte/lte; UI validates inversion)
+- AU-09 reconcile_manual tag in metadata at `berths.service.ts:473`
+- AU-11 permission_denied feed filter at `src/components/dashboard/activity-feed.tsx:185-189` (`i.action !== 'permission_denied'`); admin page correctly displays them with `'bg-red-800'` badge

docs/audit-findings-tmp/05-documents-files.md

@@ -0,0 +1,52 @@
+# Documents/Files Audit (D-01-22) — agent #5
+
+**Headline:** Structurally solid across all 22 checks. One medium real-time event mismatch + 2 low documentation divergences.
+
+**Counts:** 0 critical · 0 high · 1 medium · 2 low · 19 passing
+
+---
+
+## 🟡 MEDIUM D-01/02/03: Real-time invalidation event name mismatch after upload
+
+- **File:** `src/components/documents/documents-hub.tsx:141`
+- **What:** Hub subscribes to `'file:created': [['files']]`, but emitter (`files.ts:128`) and socket-events type def (`events.ts:264`) use `'file:uploaded'`.
+- **Why it matters:** After remote upload (other session, webhook auto-deposit), hub Files sections don't auto-refresh. Local `FolderDropZone` upload bypasses this via direct `queryClient.invalidateQueries`, but remote uploads invisible until reload.
+- **Suggested fix:** Change line 141 to `'file:uploaded': [['files']]` to match `client-files-tab.tsx:32`, `company-files-tab.tsx:32`, `interest-documents-tab.tsx:62`.
+
+## 🟢 LOW D-13: HubRootView has 2 sections, not 3
+
+- **File:** `src/components/documents/hub-root-view.tsx:50-100`
+- **What:** Spec says 3 cards; component renders 2 ("Signing in progress" + "Recent files"). Doc-only.
+- **Suggested fix:** Update CLAUDE.md to "2 sections."
+
+## 🟢 LOW D-16: `interest.yachtId` branch in chain doc spec doesn't exist in code
+
+- **File:** `src/lib/services/documents.service.ts:1225-1251`
+- **What:** Spec is `doc.clientId ?? .companyId ?? .yachtId ?? interest.clientId ?? interest.yachtId`. Code stops at `interest.clientId` because `interests.clientId` is NOT NULL — so the yachtId fallback is unreachable. Comment line 1239 explains.
+- **Suggested fix:** Update CLAUDE.md to drop the unreachable trailing branch, or annotate with `// unreachable: interests.clientId is NOT NULL`.
+
+---
+
+## ✅ Passing checks
+
+- D-01 A16 fix verified — `formStr()` returns `undefined` (not `null`) for absent FormData fields; root upload omits `folderId` correctly
+- D-02 entity-folder drag-drop carries `folderId`+`entityType`+`entityId`+typed FK
+- D-03 file picker dialog passes `folderId` (null for root) correctly
+- D-04 PDF inline preview via `PdfViewer` lazy-loaded
+- D-05 image inline preview + lightbox via `<img>` for jpeg/png/gif/webp
+- D-06 Word/Excel: `FileGrid` gates "Preview" with `PREVIEWABLE_MIMES.has(...)` so only "Download" shows; `FilePreviewDialog` never opened
+- D-07 download endpoint wraps with `withPermission('files', 'view', ...)`; `getFileById` enforces port via `file.portId !== portId`
+- D-08 `deleteFolderSoftRescue` (`src/lib/services/document-folders.service.ts:294-337`) wrapped in `db.transaction()`, re-parents folders + documents + files explicitly (no CASCADE)
+- D-09 `syncEntityFolderName` called in updateClient (clients.service.ts:554), updateCompany (companies.service.ts:187), updateYacht (yachts.service.ts:167)
+- D-10 `moveFolder` cycle prevention: rejects self at line 213, `pg_advisory_xact_lock` per port (line 233), walks ancestor chain with `seen` set, checks `cursor === folderId` at each step
+- D-11 `assertNotSystemManaged` called in renameFolder (line 172), moveFolder (line 217), deleteFolderSoftRescue (line 299)
+- D-12 `listFilesAggregatedByEntity` walks Client↔Companies (via companyMemberships INNER JOIN companies on portId)↔Yachts; cap 20 + total
+- D-14 EntityFolderView uses `useAggregatedWorkflows` (filters to INFLIGHT_STATUSES `['draft','sent','partially_signed']`); files with `signedFromDocumentId` show "View signing details"
+- D-15 `GET /api/v1/documents/[id]/signing-details` returns `{ data: { workflow, signers, events } }`; `getDocumentById` enforces portId
+- D-16 idempotency: outer gate `doc.status === 'completed' && doc.signedFileId` returns; inner `SELECT ... FOR UPDATE` re-check inside transaction
+- D-17 Defense-in-depth port at every join: `companies` INNER JOIN with `portId` (line 451), `clients` INNER JOIN with `portId` (line 497), `yachts/files` WHERE portId everywhere, LEFT JOIN `documents` with `or(eq(documents.portId, portId), isNull(documents.id))` (line 588-590). companyMemberships has no portId column but is port-scoped via INNER JOIN to companies/clients
+- D-18 `?folder=<uuid>` URL state — three-state (absent → undefined hub root, `=root` → null, `=<uuid>` → uuid); `decodeFolderParam`/`encodeFolderParam` symmetric; deep folder works
+- D-19 `ensureEntityFolder` race-safety: fast-path re-SELECT before insert; two distinct catch branches for `uniq_document_folders_entity` (re-SELECT winner) and `uniq_document_folders_sibling_name` (increment suffix)
+- D-20 magic-byte: `bufferMatchesMime` in files.ts:58 covers 8 MIME types in-server; presign-PUT only used by berth-pdf/brochure (both stream first 5 bytes + `isPdfMagic()`)
+- D-21 filename HTML-escape (`document-sends.service.ts:415-422`)
+- D-22 `streamAttachmentOrLink` size-threshold + 24h presigned URL fallback; `fallbackToLinkReason: 'size_above_threshold'` audited

docs/audit-findings-tmp/06-security.md

@@ -0,0 +1,30 @@
+# Security Audit (S-01-08, S-21-30) — agent #6
+
+**Headline:** 1 medium finding (S-23 plaintext S3 access key ID), 19 clean.
+
+## 🟡 MEDIUM S-23: S3 access key ID stored plaintext in `system_settings`
+
+- **File:** `src/lib/storage/index.ts:136`, `src/components/admin/storage-admin-panel.tsx:80`
+- **What:** S3 secret key (`storage_s3_secret_key_encrypted`) is AES-encrypted, but the access key ID (`storage_s3_access_key`) is stored/read as plaintext in `system_settings`.
+- **Why it matters:** Asymmetric encryption — DB exfil exposes the IAM key ID, narrowing the attack surface for credential stuffing or confirming which IAM principal to target. The access key ID is also surfaced in admin settings API responses.
+- **Suggested fix:** Apply same `encrypt()` / `*IsSet` pattern as the secret key. Migration to re-key existing rows. Update `resolveConfig` to call `decryptIfPresent`.
+
+## ✅ Passing checks
+
+- S-01 XSS via client.fullName (React text node)
+- S-02 XSS via tag.name (React child, sanitized style object)
+- S-03 XSS via note.content (plain text, no markdown rendering — `whitespace-pre-wrap` is CSS only)
+- S-04 XSS via email body markdown (`src/lib/utils/markdown-email.ts` escape-then-allowlist + DOMPurify second layer in `send-document-dialog.tsx`)
+- S-05 SQL injection via search query (Drizzle parameterized; `sql.raw` only on hardcoded constants in `admin/storage/route.ts:30` and `storage/migrate.ts:149`)
+- S-06 Path traversal in folder name (DB-only, never used as filesystem path)
+- S-07 Path traversal in file name / storage key (`validateStorageKey` in `src/lib/storage/filesystem.ts:49-69` rejects `..`/absolute/empty/non-allowlist chars; `resolveKey` does `path.resolve` prefix check)
+- S-08 SSRF via webhook target URL (two-layer: `isLocalOrPrivateHost` in `src/lib/validators/webhooks.ts` blocks RFC1918+loopback+link-local+CGNAT+cloud metadata; `resolveAndCheckHost` in `src/lib/queue/workers/webhooks.ts` re-resolves DNS at dispatch — DNS rebinding-resistant)
+- S-21 SMTP credential AES-256-GCM with random IV (`src/lib/utils/encryption.ts`)
+- S-22 IMAP credential same path as SMTP
+- S-24 Privilege escalation blocked: `updateUser` in `src/lib/services/users.service.ts:294-318` does caller-superset check; permission-overrides at `src/app/api/v1/admin/users/[id]/permission-overrides/route.ts:203-210` enforce per-leaf + block self-target at line 160; role definition mutations require `requireSuperAdmin` not just `manage_users`
+- S-25 Direct ID enumeration immune (`crypto.randomUUID` everywhere)
+- S-26 Audit log read-back of own permission denials — clean (admin-only `view_audit_log`)
+- S-27 Magic-byte verification verified
+- S-28 Filename HTML-escape in download links (`src/lib/services/document-sends.service.ts:415-420`)
+- S-29 Bounce-monitor email subject parsing — clean (no IMAP bounce worker exists yet; `email-threads.service.ts` uses parameterized `ilike` for subject matching)
+- S-30 `EMAIL_REDIRECT_TO` enforced at boot via Zod `superRefine` in `src/lib/env.ts:110-117` — production with the env set causes `process.exit(1)`. Webhook worker also short-circuits to `dead_letter` when set.

docs/audit-findings-tmp/07-email-integrations.md

@@ -0,0 +1,112 @@
+# Email + Integrations Audit (EM-01-19, IN-01-29) — agent #7
+
+**Headline:** Broadly well-implemented. Primary issue: missing SMTP timeouts on sales transporter (HIGH — risks worker starvation). Plus 8 medium gaps in portal-email portId scoping, digest catalog key, receipt scanner config, presign TTL.
+
+**Counts:** 0 critical · 1 high · 8 medium · 0 low · 30 passing
+
+---
+
+## 🟠 HIGH EM-XX: Sales transporter missing SMTP timeouts
+
+- **File:** `src/lib/services/sales-email-config.service.ts:331-337`
+- **What:** `createSalesTransporter` builds nodemailer transport with no timeout options. Compare `createTransporter` in `src/lib/email/index.ts:26-37` which uses `SMTP_TIMEOUTS = { connectionTimeout: 10_000, greetingTimeout: 10_000, socketTimeout: 30_000 }`.
+- **Why it matters:** Hung SMTP relay can stall send-out indefinitely. Email queue concurrency=5, maxAttempts=5. Without socket timeouts, one stuck TCP connection holds a worker for nodemailer's 2-min default × 5 retries = 10min/job × 5 slots = whole pool blocked for 10min by a single flaky send.
+- **Suggested fix:** Apply `SMTP_TIMEOUTS` constant to `nodemailer.createTransport` in `createSalesTransporter`.
+
+## 🟡 MEDIUM EM-05a: Per-port branding not threaded into portal activation/reset emails
+
+- **File:** `src/lib/services/portal-auth.service.ts:163-164`
+- **What:** `issueActivationToken` and `issuePasswordReset` call `sendEmail(email, subject, html, undefined, text)` without the 6th `portId` argument. Without `portId`, `createTransporter()` uses global env SMTP. Branding is threaded into HTML via `getBrandingShell(portId)` but the SMTP transport falls back to global.
+- **Why it matters:** Multi-port deploys: portal auth emails for port B go through global env SMTP, defeating per-port SMTP override.
+- **Suggested fix:** Pass `portId` as 6th arg to `sendEmail` in both `issueActivationToken` and the reset send.
+
+## 🟡 MEDIUM EM-07: CC/BCC not supported in main `sendEmail`
+
+- **File:** `src/lib/email/index.ts:54-68`
+- **What:** `SendEmailOptions` lacks `cc`/`bcc`. Sales send-out path also lacks them.
+- **Suggested fix:** Add optional `cc`/`bcc` to `SendEmailOptions`. Low urgency.
+
+## 🟡 MEDIUM EM-11: Bounce-to-interest linking not implemented
+
+- **File:** `src/lib/services/sales-email-config.service.ts:13` (header comment)
+- **What:** `getSalesImapConfig` exposes IMAP creds but no BullMQ worker reads IMAP. Failed deliveries don't update `document_sends.failedAt`.
+- **Suggested fix:** Wire BullMQ recurring job using imapflow to scan inbox for bounce NDRs, match against `document_sends.messageId`. Phase 7 §14.9 deferred.
+
+## 🟡 MEDIUM EM-16: Notification digest uses wrong catalog key for subject resolution
+
+- **File:** `src/lib/services/notification-digest.service.ts:161-169`
+- **What:** Calls `resolveSubject` with `key: 'crm_invite' as any` because `'notification_digest'` is not in `TEMPLATE_KEYS` in `src/lib/email/template-catalog.ts`.
+- **Why it matters:** Admin-set CRM invite subject override bleeds into digest emails.
+- **Suggested fix:** Add `'notification_digest'` to `TEMPLATE_KEYS`; update digest service to use it.
+
+## 🟡 MEDIUM IN-11: Presigned URL TTL fixed at 900s for portal downloads
+
+- **File:** `src/lib/storage/index.ts:240-254` (`presignDownloadUrl`); `src/lib/services/portal.service.ts:350` (`getDocumentDownloadUrl`)
+- **What:** `presignDownloadUrl` defaults `expirySeconds=900` (15min). Sales send-out correctly overrides to 24h. `getDocumentDownloadUrl` calls without expiry → 15min default.
+- **Why it matters:** Portal users opening their doc list and clicking after >15min get 403.
+- **Suggested fix:** Pass `expirySeconds: 4 * 3600` for portal download links, or sign on-demand from API.
+
+## 🟡 MEDIUM IN-21: OpenAI receipt-scanner module-level instantiation, no credential health check
+
+- **File:** `src/lib/services/receipt-scanner.ts:4`
+- **What:** `const openai = new OpenAI();` at module level reads `OPENAI_API_KEY` at import. SDK throws on first call when unset; catch returns zero-confidence empty result. No admin-visible health check.
+- **Suggested fix:** Guard `OPENAI_API_KEY` upfront with clear error. Add a health-check endpoint similar to `checkDocumensoHealth`.
+
+## 🟡 MEDIUM IN-23: Receipt OCR ignores per-port config; hardcoded `gpt-4o`
+
+- **File:** `src/lib/services/receipt-scanner.ts:19`
+- **What:** `model: 'gpt-4o'` hardcoded; per-port `getResolvedOcrConfig` not consulted; `aiEnabled` flag does nothing. Module-level singleton OpenAI client.
+- **Suggested fix:** Accept `portId`, call `getResolvedOcrConfig(portId)`, check `aiEnabled`, use `config.apiKey` and `config.model`. Branch on provider for OpenAI vs Anthropic.
+
+## 🟡 MEDIUM IN-24: Stale "pdfme" references in comments/seed
+
+- **File:** `src/lib/db/seed-data.ts:807`, `src/lib/services/document-templates.ts:573`
+- **What:** Comments still reference pdfme even though the rendering path was removed; `tiptap-validation.ts:8` confirms pdfme retired. `document-templates.ts:648-652` throws ValidationError for non-EOI templates.
+- **Suggested fix:** Update comments to reference pdf-lib AcroForm fill; remove "pdfme" from seed-data description.
+
+## 🟡 MEDIUM IN-29: Umami `testConnection` throws instead of returning typed result
+
+- **File:** `src/lib/services/umami.service.ts:80-101, 292`
+- **What:** `loadUmamiConfig` returns null gracefully; all public APIs return null when unconfigured. But `testConnection` throws `CodedError('UMAMI_NOT_CONFIGURED')` instead of returning `{ ok: false, error }` like `checkDocumensoHealth`.
+- **Suggested fix:** Return `{ ok: false, error: string }` to match Documenso convention.
+
+---
+
+## ✅ Passing checks
+
+- EM-01 per-port SMTP override (`getPortEmailConfig` in `port-config.ts:136`)
+- EM-02/03 default send-froms cascade (explicit `from` → `cfg.fromAddress` → env.SMTP_FROM → `noreply@${SMTP_HOST}`)
+- EM-04 EMAIL_REDIRECT_TO subject prefix `[redirected from <orig>]`; documenso-client also applies `applyRecipientRedirect`/`applyPayloadRedirect`; env.ts:110 prod boot guard
+- EM-05 branded shell (`renderShell` in `src/lib/email/shell.ts:37`)
+- EM-06 reply-to override applied
+- EM-08 send rate limit 50/user/hour Redis sliding-window keyed `${portId}:${userId}`
+- EM-09 `streamAttachmentOrLink` threshold + filename HTML-escape pre-SMTP
+- EM-10 IMAP probe script + `getSalesImapConfig` AES-256-GCM decrypted
+- EM-12 `document_sends` audit row in success + failure branches
+- EM-13 portal activation token: 32-byte token, hash stored in `portalAuthTokens`, `#token=...` fragment to stay out of logs
+- EM-14/15 reset/invite emails wired
+- EM-17 EOI sent via Documenso (not as nodemailer attachment)
+- EM-18/19 `renderEmailBody` escape-first + `isSafeHref` (https/mailto only) + `MERGE_VALUE_ESCAPE_MAP` neutralizes markdown chars
+- IN-01 v1 template-generate path (`generateDocumentFromTemplate`)
+- IN-02 v2 envelope/create multipart (FormData with `payload` JSON + `files` Blob)
+- IN-03 v2 distribute returns `recipients[].signingUrl` in one round-trip
+- IN-04 redistribute version-aware (v2 caveat: `recipientIds` may not target single recipient — API behavior risk, not code bug)
+- IN-05 downloadSignedPdf version-aware
+- IN-06 voidDocument version-aware (idempotent on 404)
+- IN-07 placeFields v2 bulk `field/create-many` percent coords + `fieldMeta`; v1 one POST per field with pixel coords
+- IN-08 `normalizeDocument` `id ?? documentId` for both docs and recipients (handles legacy `r.Recipient` capital-R)
+- IN-09 NocoDB `pg_advisory_xact_lock` + skip rows where `updated_at > last_imported_at`
+- IN-10 S3Backend with SSE AES256, all calls wrapped in `withTimeout(30_000)`, never imports MinIO directly
+- IN-12 filesystem MULTI_NODE_DEPLOYMENT guard (boot-time throw)
+- IN-13 BullMQ exponential backoff: email/docs 5×1s, webhooks 8×30s
+- IN-14 Redis noeviction in both compose files
+- IN-15 `src/worker.ts` imports all 10 workers + SIGTERM/SIGINT graceful shutdown
+- IN-16 public berths cache `s-maxage=300, stale-while-revalidate=60`
+- IN-17 status filter Sold > Under Offer (status OR has active is_specific_interest with isNull(end_date)+outcome) > Available
+- IN-18 mooring regex `^[A-Z]+\d+$` checked pre-DB; returns 400 for malformed
+- IN-19/20 dual-mode health endpoint with `timingSafeEqual`
+- IN-22 berth-pdf-parser tier-2 is `unpdf` (not Tesseract — prior comment correction); 30s timeout
+- IN-25 `fillEoiFormFields` flatten + metadata; missing fields warn rather than throw
+- IN-26 VALID_MERGE_TOKENS allow-list including `{{eoi.berthRange}}`
+- IN-27 `formatBerthRange` handles all cases (single/contig/non-contig/cross-pontoon/dedup)
+- IN-28 portal magic-link rate-limited 10/h/IP via `enforcePublicRateLimit(req, 'portalToken')`

docs/audit-findings-tmp/08-perf-behavioral.md

@@ -0,0 +1,55 @@
+# Performance + Behavioral Audit (P-05/09/13/14, B-01-22) — agent #8
+
+**Headline:** 1 critical (B-01 INNER JOIN drops hard-deleted berth links), 1 high (B-16 AppShell remount destroys form state), 1 medium (P-09a leading-wildcard ILIKE), 17 clean.
+
+**Counts:** 1 critical · 1 high · 1 medium · 1 low · 17 passing
+
+---
+
+## 🔴 CRITICAL B-01: Hard-deleted berth causes silent data loss across interest surfaces
+
+- **File:** `src/lib/services/interest-berths.service.ts:55` (`getPrimaryBerth`), `:87` (`getPrimaryBerthsForInterests`), `:140` (`listBerthsForInterest`)
+- **What:** All three helpers use `INNER JOIN berths ON berths.id = interestBerths.berthId`. When a berth is hard-deleted, the INNER JOIN silently drops the link.
+- **Why it matters:** Interest detail page shows `berthId: null`, `berthMooringNumber: null`. Kanban card shows no berth chip. EOI generation produces empty field. `archiveInterest` path that calls `getPrimaryBerth` before evaluating berth rule returns null and **skips the rule entirely**.
+- **Suggested fix:** Change all three `INNER JOIN` to `LEFT JOIN berths`. Callers already handle `null` mooringNumber. Add service-layer guard preventing hard-delete of berths with `interest_berths` rows (require unlink or soft-archive first).
+
+## 🟠 HIGH B-16: AppShell remounts children on breakpoint crossing, destroying form state
+
+- **File:** `src/components/layout/app-shell.tsx:58-70`
+- **What:** When `isMobile` flips on resize, the shell switches between `<MobileLayout>{children}</MobileLayout>` and the desktop `<div>...{children}...</div>`. React unmounts and remounts `children`, destroying any in-progress `useState` form drafts including `InlineEditableField`.
+- **Why it matters:** A user editing a client name on desktop who resizes past the mobile breakpoint loses unsaved draft text. Multi-step modal forms (reconcile wizard) open during resize get unmounted.
+- **Suggested fix:** Wrap shared content with stable `key`, or use CSS-only responsive layout so the children subtree never remounts. Alternatively `key={isMobile ? 'mobile' : 'desktop'}` only on the shell wrappers with `children` stable via Portal.
+
+## 🟡 MEDIUM P-09a: Leading-wildcard ILIKE in `buildListQuery` prevents index use
+
+- **File:** `src/lib/db/query-builder.ts`
+- **What:** List search uses `ILIKE '%term%'` with leading wildcard, defeating B-tree and trigram-prefix indexes.
+- **Why it matters:** Sequential scan on high-cardinality text columns; degrades at scale.
+- **Suggested fix:** Migrate to `pg_trgm` GIN indexes on the searched columns, or move to FTS via existing `search_text` GIN where one exists.
+
+## 🟢 LOW P-14: List endpoint `limit` allows up to 1000 rows
+
+- **File:** `src/lib/api/list-query.ts`
+- **What:** Generic list cap = 1000. Audit log is bounded to 200 with cursor pagination (better pattern).
+- **Why it matters:** A 1000-row response with relations can blow the 256 KB budget.
+- **Suggested fix:** Lower default cap to ~100; require explicit cursor pagination beyond.
+
+---
+
+## ✅ Passing checks
+
+- P-05 No N+1 — all secondary fetches batched via `inArray`
+- P-13 Audit FTS uses `to_tsvector('simple')` + GIN index + `plainto_tsquery('simple')` consistently (`src/lib/services/audit-search.service.ts`, migration `0014_black_banshee.sql`)
+- B-02 Sara Laurent contract-without-yachtId renders correctly (overview tab guards yacht section; stage-gate only fires on `changeInterestStage`)
+- B-03 `activeInterestsWhere` (`src/lib/services/active-interest.ts`) used in listInterestsForBoard, getInterestStageCounts, listBerths reconcile, recommender CTE
+- B-04 / B-05 `formatBerthRange` correct: single (`A1`), contiguous (`A1-A3`), non-contiguous (`A1, A3`), cross-pontoon (`A1-A2, B5-B7`), dedup, non-canonical pass-through
+- B-07 Tier B fires only when `activeInterestCount===0 && lostCount>0`; `lost_count` aggregates `LIKE 'lost%' OR cancelled`; heat scoring gated by `tier === 'B'`; fall-through policy enforces cooldown/never_auto_recommend
+- B-08 `withPermission` (`src/lib/api/helpers.ts:328-340`) writes `permission_denied` audit row before 403 (fire-and-forget `void`)
+- B-09 Same-stage no-op `if (existing.pipelineStage === data.pipelineStage) return STAGE_NOOP;` early-returns before DB/audit/socket (`src/lib/services/interests.service.ts:847-849`)
+- B-10 Documenso webhook handles empty body / malformed JSON via try/catch returning `{ ok: false }` 200 + warning log (`src/app/api/webhooks/documenso/route.ts:176-182, 202`)
+- B-11 `status_override_mode` transitions (null/manual/automated) all have audit coverage; reconcile clears to null, rules engine writes 'automated', admin UI writes 'manual'
+- B-13 Catch-up wizard `pipelineStage === 'contract'` sends `outcome: 'won'` (`src/components/berths/catch-up-wizard.tsx:120`); reconcile route validates `z.enum(['won']).optional()`
+- B-17 Bulk-add berths wizard step state persists in `BulkAddBerthsWizard`'s `useState`; no remount between steps
+- B-18 NotesList handles 6 entity types (clients/interests/yachts/companies/residential_clients/residential_interests); `companyNotes.updatedAt` substituted via `createdAt` per CLAUDE.md
+- B-19 `InlineEditableField` present on client/yacht/company/interest/residential-client/residential-interest/berth tabs (11 files)
+- B-22 `markExternallySigned` (`src/lib/services/external-signing.service.ts:68-72`) updates `{ docStatus: 'signed', updatedAt: now }`. Note: catalog said "documentId=null, signedAt=now" but interests table has no such columns — the service is correct relative to schema.

docs/audit-findings-tmp/09-ux-forms.md

@@ -0,0 +1,159 @@
+# UX/Forms/Tables Audit (U-001-100, code-side) — agent #9
+
+**Headline:** Generally consistent (Sheet, AlertDialog, EmptyState, requestId surfacing all good across most surfaces). 4 HIGH gaps: native `alert()` for bulk-action failures, icon-only buttons missing aria-label, unicode glyphs in portal, Vaul Drawer in mobile search overlay. Plus 14 MEDIUM gaps in form discipline + a11y + mobile nav.
+
+**Counts:** 0 critical · 4 high · 14 medium · 0 low
+
+---
+
+## 🟠 HIGH
+
+### U-059: Unicode glyphs as status icons in portal documents page
+
+- **File:** `src/app/(portal)/portal/documents/page.tsx:85-89`
+- **What:** Signer status rendered as raw Unicode (`'✓'` signed, `'✗'` declined, `'○'` pending) inside colour-coded `<span>` with no `aria-label`.
+- **Why it matters:** A11y — screen readers read literal Unicode names. Per project memory: decorative unicode glyphs are explicitly flagged. `inline-stage-picker.tsx:443` comment confirms the pattern ("was ⚑ unicode glyph — replaced with a Lucide").
+- **Suggested fix:** Replace with `<CheckCircle2>` / `<XCircle>` / `<Circle>` Lucide icons + `aria-label`.
+
+### U-066: Vaul Drawer used for mobile search overlay (violates Sheet doctrine)
+
+- **File:** `src/components/search/mobile-search-overlay.tsx:6`
+- **What:** `import { Drawer as VaulDrawer } from 'vaul'` — search overlay is a full-screen overlay, not a bottom sheet, but uses Vaul Drawer. CLAUDE.md says Vaul is reserved for mobile-bottom-sheet only (currently `MoreSheet` only).
+- **Suggested fix:** Convert to `<Sheet side="bottom">` or `<Dialog>` fullscreen. Visualviewport handling (lines 50-89) becomes redundant once Radix dialog primitive backs it.
+
+### U-076: Native `alert()` for bulk-action failure feedback in 3 lists
+
+- **Files:** `src/components/interests/interest-list.tsx:146`, `src/components/companies/company-list.tsx:73`, `src/components/yachts/yacht-list.tsx:66`
+- **What:** Partial-failure feedback via `alert(...)`. `client-list.tsx:145` uses `toast.warning(...)` correctly.
+- **Why it matters:** Native alert blocks main thread, can't be styled, fires in tests without suppression.
+- **Suggested fix:** Replace with `toast.warning(...)` matching `client-list.tsx`.
+
+### U-079: Icon-only buttons missing aria-label (5 sites)
+
+- **Files:**
+  - `src/components/notifications/notification-bell.tsx:65` (Bell icon button)
+  - `src/components/files/file-grid.tsx:121` (MoreHorizontal "…" on file cards)
+  - `src/components/admin/forms/form-template-list.tsx:102` (Trash button)
+  - `src/components/email/email-accounts-list.tsx:159` (Trash button)
+  - `src/components/companies/company-members-tab.tsx:228` (MoreHorizontal)
+- **Pattern reference (correct):** `src/components/shared/folder-actions-menu.tsx:96` uses `<span className="sr-only">More folder actions</span>`.
+- **Suggested fix:** Add `aria-label` to each, following the folder-actions-menu sr-only pattern.
+
+---
+
+## 🟡 MEDIUM
+
+### U-009: Audit log inline div instead of EmptyState component
+
+- **File:** `src/components/admin/audit/audit-log-list.tsx:524`
+- **What:** `<div><p className="text-muted-foreground">No audit log entries found.</p></div>` rather than `<EmptyState title="..." />`.
+- **Suggested fix:** Replace with `<EmptyState title="No audit log entries found." />`.
+
+### U-010: Two duplicate EmptyState components with incompatible APIs
+
+- **Files:** `src/components/ui/empty-state.tsx` vs `src/components/shared/empty-state.tsx`
+- **What:** `ui/` accepts `{icon: ReactNode, body, actions}`; `shared/` accepts `{icon: ElementType, description, action: {label, onClick}}`. 3 files use `ui/` (admin/reconcile-queue, documents/documents-hub, reservations/reservation-detail), 24 use `shared/`.
+- **Suggested fix:** Pick `shared/` as canonical (8× usage); migrate the 3 `ui/` callers and delete `ui/empty-state`.
+
+### U-021: Required-field marker inconsistent
+
+- **Files:** `src/components/clients/client-form.tsx:273`, `src/components/interests/interest-form.tsx:281`
+- **What:** Some fields use inline `*`, others have no marker; no `aria-required` on inputs; no consistent pattern.
+- **Suggested fix:** Single pattern: `<Label>Field <span aria-hidden>*</span></Label>` + `aria-required="true"` on input.
+
+### U-022: Help-text discoverability inconsistent
+
+- **File:** `src/components/shared/filter-bar.tsx`, `src/components/clients/client-form.tsx`
+- **What:** No tooltip pattern; some fields have always-visible muted-foreground hints, some have nothing.
+- **Suggested fix:** Document a rule (always-visible for constraints/format hints; tooltips only for icons).
+
+### U-024: Cancel/dismiss without unsaved-changes warning on ClientForm/YachtForm
+
+- **Files:** `src/components/clients/client-form.tsx`, `src/components/yachts/yacht-form.tsx`
+- **What:** `InterestForm.requestClose()` (line 123) checks `isDirty` and shows discard AlertDialog; `CompanyForm` also has it. ClientForm and YachtForm don't — sheet closes immediately.
+- **Suggested fix:** Add `isDirty` guard + discard AlertDialog matching InterestForm pattern.
+
+### U-031: FileUploadZone size limit not surfaced as client-side check
+
+- **File:** `src/components/files/file-upload-zone.tsx:170`
+- **What:** Accept attribute lists extensions; "up to 50MB" copy at line 163; no client-side size check before upload. Server-side check fails silently with "Upload failed" at line 103.
+- **Suggested fix:** Wire client-side size check before upload; show clear "File too large" message.
+
+### U-044: No jump-to-page input in pagination
+
+- **File:** `src/components/shared/data-table.tsx:420`
+- **Suggested fix:** Add small `<input type="number">` between Previous/Next.
+
+### U-048: No column resize/reorder on DataTable
+
+- **File:** `src/components/shared/data-table.tsx`
+- **What:** Visibility supported via `ColumnPicker`; widths fixed; no drag-reorder.
+- **Suggested fix:** Opt-in `enableColumnResizing` per table via TanStack Table v8 `onColumnSizingChange`.
+
+### U-069: Invoice delete uses custom overlay, not AlertDialog
+
+- **File:** `src/app/(dashboard)/[portSlug]/invoices/page.tsx:167`
+- **What:** Hand-rolled `<div className="fixed inset-0 bg-background/80 backdrop-blur-xs z-50 ...">` rather than `<AlertDialog>` / `<ConfirmationDialog>`. Lacks focus trap, Escape, role="alertdialog".
+- **Suggested fix:** Replace with `<ConfirmationDialog>` matching pattern elsewhere.
+
+### U-074: Success toast missing on ClientForm + InterestForm create/edit
+
+- **Files:** `src/components/clients/client-form.tsx:215`, `src/components/interests/interest-form.tsx:235`
+- **What:** `onSuccess` invalidates queries + closes sheet, no `toast.success()`. `ComposeDialog.onSuccess:81` does fire one.
+- **Suggested fix:** `toast.success(isEdit ? 'Client updated' : 'Client created')`.
+
+### U-080: Logo preview `<img alt="">` should describe state
+
+- **File:** `src/components/admin/shared/settings-form-card.tsx:420`
+- **Suggested fix:** Use `alt="Port logo preview"` or dynamic from field label.
+
+### U-081: Heading hierarchy inconsistent within tab components
+
+- **Files:** `email-accounts-list.tsx:114`, `interest-contract-tab.tsx:130/251/291/364` (h2 → h3 → h2 jumps)
+- **Suggested fix:** Audit each tab; standardize h2 = primary section, h3 = sub-section; never h2 after h3 at same nesting depth.
+
+### U-086: DialogContent missing aria-describedby on minimal-content dialogs
+
+- **File:** `src/components/email/compose-dialog.tsx:95` and ~40 other dialogs
+- **What:** Only `file-preview-dialog.tsx:82` explicitly suppresses the Radix warning.
+- **Suggested fix:** Add `<DialogDescription className="sr-only">...</DialogDescription>` or `aria-describedby={undefined}` to suppress.
+
+### U-091: Mobile topbar title blank on list pages
+
+- **Files:** `client-list.tsx`, `yacht-list.tsx`, `interest-list.tsx`, `berth-list.tsx`
+- **What:** `useMobileChrome` only called from detail pages. List pages leave topbar in fallback (no title, stale from previous detail page).
+- **Suggested fix:** Add `useMobileChrome({ title, showBackButton: false })` per list with cleanup pattern.
+
+### U-093: Invoices missing from mobile navigation
+
+- **File:** `src/components/layout/mobile/more-sheet.tsx:54`
+- **What:** Not in `MORE_GROUPS`, not in bottom tabs. Mobile users can only reach via direct URL.
+- **Suggested fix:** Add `{ label: 'Invoices', icon: FileText, segment: 'invoices' }` to Operations group.
+
+---
+
+## ✅ Sample passing checks
+
+- U-001-008 list empty states + skeletons clean across clients/yachts/interests/berths/companies/reservations/invoices/email-threads
+- U-012 FileUploadZone drag-hover with `border-primary bg-primary/5`
+- U-023 field-level errors via react-hook-form `formState.errors` consistent
+- U-026 BulkAddBerthsWizard + CatchUpWizard persist state across step nav
+- U-027 phone E.164 via `formatAsYouType` emits `{ e164, country }`
+- U-029 native `<input type="date">` provides browser calendar + keyboard
+- U-033 Combobox keyboard nav inherited from Radix `<Command>` primitives
+- U-040 Sort indicators via `getSortIcon` (`ArrowUpDown`/`ArrowUp`/`ArrowDown`)
+- U-041/042 Filter chip dismiss + Clear-all in FilterBar
+- U-043 page size selector 25/50/100/250/All
+- U-049 virtual list via `@tanstack/react-virtual` (`virtual virtualHeightPx={640}` in audit log)
+- U-054 STAGE_BADGE in `src/lib/constants.ts:100` — 7 distinct stages with distinct Tailwind colour families
+- U-055 outcome badge: won=emerald, lost\_\*=rose, cancelled=slate
+- U-057 status-pill covers all required document statuses
+- U-060/061 button hierarchy + destructive red consistent
+- U-065 Sheet used for forms+previews on both desktop and mobile (23 components)
+- U-067 AlertDialog used for destructive confirmations (`useConfirmation`, `ArchiveConfirmDialog`, `ConfirmationDialog`, `BulkHardDeleteDialog`)
+- U-070-072 click-outside, Esc, focus-trap, focus-restore all inherited from Radix
+- U-073 toast position consistent (sonner top-right)
+- U-075 `toastError()` (`src/lib/api/toast-error.ts:43`) surfaces requestId + Copy ID action — used in 89 files
+- U-094 iOS safe-area-inset comprehensive (`pb-safe-bottom`, `pt-safe-top`, FAB `calc(env(safe-area-inset-bottom)+86px)`)
+- U-097 visualViewport handling on mobile-search-overlay
+- U-092 More sheet covers Documents/Interests/Yachts/Companies/Residential/Alerts/Reminders/Expenses/Reservations/Reports/Analytics/Settings/Admin

docs/audit-frontend-2026-05-06.md

@@ -0,0 +1,223 @@
+# Frontend audit — 2026-05-06
+
+Scope: new archive/restore/hard-delete dialogs, bulk archive wizard, client
+detail header, audit log inspector, webhook delivery log, client list bulk
+section. Companion to `docs/audit-comprehensive-2026-05-06.md` (does NOT
+re-flag the Files-tab / reservations / berth-tab "coming soon" stubs already
+covered there).
+
+---
+
+## Critical
+
+### C1 — `client-detail-header` opens restore dialog from the Archive icon for archived clients
+
+**File:** `src/components/clients/client-detail-header.tsx:174-186`
+
+**Scenario:** On an archived client the icon button still renders `<Archive>`
+when `isArchived` is true (`isArchived ? <RotateCcw /> : <Archive />` is
+correct), BUT both states use the same `setArchiveOpen(true)` handler and
+the conditional below routes `<SmartRestoreDialog>` vs `<SmartArchiveDialog>`
+off of `isArchived`. That part is fine. The real problem: the destructive
+hover colour `hover:text-destructive` is applied via
+`isArchived ? 'hover:text-foreground' : 'hover:text-destructive'` — but the
+preceding class string already sets `hover:text-foreground` unconditionally,
+so the conditional is dead and the restore button hovers red the same as
+archive. Misleading colour signal on a reversible action; users hesitate to
+click it.
+
+**Fix:** Drop the always-applied `hover:text-foreground` from the base class
+list and let the conditional own the hover colour, or just colour the
+restore icon emerald to differentiate.
+
+---
+
+## High
+
+### H1 — `bulk-archive-wizard` lets users skip the reasons step by clicking Continue while preflight is loading then Cancel/reopen
+
+**File:** `src/components/clients/bulk-archive-wizard.tsx:253-267, 80-107`
+
+**Scenario:** In the `preflight` stage the Continue button is only disabled
+when `archivable.length === 0 || preflight.isLoading`. But `archivable` is
+derived from `items = preflight.data ?? []`. While loading, `archivable` is
+`[]` so Continue is disabled — good. After load with all-blocked selection,
+`archivable.length === 0` so still disabled — good. However, the
+`reasonsByClientId: reasons` payload is sent verbatim, so a user who advances
+to "reasons", types into one client's box, then uses the carousel back arrow
+and edits another, can submit reasons for clients NOT in `archivable` (e.g.
+if the preflight is refetched on stale-time). Reasons for blocked or removed
+client IDs are forwarded to the API. Minor data-quality issue.
+
+**Fix:** Filter `reasons` to `archivable` IDs before mutating:
+`reasonsByClientId: Object.fromEntries(Object.entries(reasons).filter(([id]) => archivable.some(a => a.clientId === id)))`.
+
+### H2 — `client-list` bulk tag mutation uses `alert()` for partial failures and has no `onError`
+
+**File:** `src/components/clients/client-list.tsx:88-106`
+
+**Scenario:** User bulk-adds a tag to 50 clients; backend returns 200 with
+`{succeeded: 30, failed: 20}` → user sees a native browser `alert()` blocking
+the page. If the request itself errors (network drop, 500), there is no
+`onError` so the dialog closes via `onSettled` and the user sees nothing —
+silent failure. Inconsistent UX vs. every other mutation in this audit which
+uses `toast`.
+
+**Fix:** Replace `alert(...)` with `toast.warning(...)`, add an
+`onError: (err) => toast.error(...)` branch matching the pattern used in
+`bulk-archive-wizard.tsx` and `bulk-hard-delete-dialog.tsx`.
+
+### H3 — `webhook-delivery-log` swallows fetch errors silently
+
+**File:** `src/components/admin/webhooks/webhook-delivery-log.tsx:61-74`
+
+**Scenario:** Admin opens a webhook detail page while the API is down or the
+webhook was just deleted. `load()` catches and discards the error
+(`} catch { /* ignore */ }`). UI shows "Loading deliveries…" forever on the
+first load, or stays on the last successful page on subsequent loads, with
+no indication that anything failed. No error state, no toast, no retry.
+
+**Fix:** Surface errors via `toast.error` and show an inline error state
+("Couldn't load deliveries — Retry") instead of swallowing.
+
+### H4 — `audit-log-list` first-page fetch swallows errors and shows no error state
+
+**File:** `src/components/admin/audit/audit-log-list.tsx:150-175`
+
+**Scenario:** Filter form is fully interactive, user changes a date — request
+fires, server 500s. The `try/finally` has no `catch`, so the rejected promise
+becomes an unhandled rejection. The list shows whatever was previously
+loaded (or empty state), and the user has no idea their filter didn't apply.
+Same applies to `loadMore`.
+
+**Fix:** Add `catch` blocks that set an error state and render an inline
+error banner above the table, with a Retry button.
+
+### H5 — `audit-log-card` renders as a link to `href="#"` — clicking jumps the page
+
+**File:** `src/components/admin/audit/audit-log-card.tsx:96`
+
+**Scenario:** On mobile / card view the audit log entries become clickable
+cards with `href="#"`. Tapping any card scrolls the page to top and inserts
+`#` in the URL (back-button trap). There's no detail view to navigate to.
+
+**Fix:** Either render a non-link wrapper (button or div) when no detail
+target exists, or link to a useful destination like
+`/{portSlug}/{entityType}/{entityId}` when the entity is resolvable.
+
+### H6 — `smart-archive-dialog` `archiveMutation` doesn't invalidate the dossier or single-client query
+
+**File:** `src/components/clients/smart-archive-dialog.tsx:197-212`
+
+**Scenario:** User archives a client successfully. The dialog invalidates
+`['clients']`, `['berths']`, `['interests']` but NOT
+`['client-archive-dossier', clientId]` nor `['clients', clientId]`. If the
+parent screen (e.g. detail page) keeps the client query mounted, the
+detail header continues to show the client as un-archived until a hard
+reload. The Restore icon won't appear.
+
+**Fix:** Add `qc.invalidateQueries({queryKey: ['clients', clientId]})` and
+`qc.removeQueries({queryKey: ['client-archive-dossier', clientId]})` so a
+re-open re-fetches a fresh dossier (e.g. if user re-archives after restoring
+in the same session).
+
+---
+
+## Medium
+
+### M1 — `smart-archive-dialog` derives `interestId` from a name match against `primaryBerthMooring` — wrong key
+
+**File:** `src/components/clients/smart-archive-dialog.tsx:158-167`
+
+**Scenario:** When building per-berth decisions the code does
+`dossier.interests.find((i) => i.primaryBerthMooring === b.mooringNumber)?.interestId`.
+Multiple interests can share the same primary mooring (rare, but possible
+historically), and worse, when no interest has this berth as primary it
+falls back to `dossier.interests[0]?.interestId` regardless of which berth
+is being decided. The wrong interest gets credited with the release, which
+is then audit-logged.
+
+**Fix:** Have the dossier API return `interestId` per berth row (it already
+joins `interest_berths`), or look up by membership not by primary flag.
+
+### M2 — `hard-delete-dialog` doesn't reset state when switching from intent → confirm if request fails midway
+
+**File:** `src/components/clients/hard-delete-dialog.tsx:39-46, 64-79`
+
+**Scenario:** User submits hard delete with wrong code → backend returns 400
+→ toast fires, but the dialog stays on `confirm` stage with the bad code
+still in the input and no clear cue. If the user then closes (X) and
+reopens, the `useEffect` resets correctly. But if the email code expired
+(10 min) and they request a fresh one, there's no "Resend code" button —
+they must cancel and start over from intent. Minor.
+
+**Fix:** Add a "Send a new code" link in the confirm stage that calls
+`requestCode.mutate()` again and clears `code`.
+
+### M3 — `bulk-hard-delete-dialog` doesn't refetch / invalidate after partial failure shows totals
+
+**File:** `src/components/clients/bulk-hard-delete-dialog.tsx:64-85`
+
+**Scenario:** Bulk delete returns `{deletedCount: 7}` for 10 selected; toast
+warns but `qc.invalidateQueries({queryKey: ['clients']})` is invalidated
+unconditionally — fine. However, the dialog closes immediately
+(`onOpenChange(false)`), so the user can't see WHICH 3 failed. The toast
+just says "see audit log". For a destructive bulk op this is too sparse;
+users will repeat the action thinking it didn't work.
+
+**Fix:** Stay open on partial failure and render a list of failed IDs (the
+API likely already returns per-item results — if not, return them).
+
+### M4 — `audit-log-list` doesn't validate that `dateFrom <= dateTo`
+
+**File:** `src/components/admin/audit/audit-log-list.tsx:142-146`
+
+**Scenario:** User picks From=2026-06-01, To=2026-05-01. Query fires with an
+empty result range; user sees "No audit log entries found" and assumes
+their data isn't there. No client-side validation hint.
+
+**Fix:** Show an inline warning "From date must be before To date" and skip
+the request when invalid.
+
+### M5 — `bulk-archive-wizard` `Cancel` during `archiveMutation.isPending` discards mutation tracking
+
+**File:** `src/components/clients/bulk-archive-wizard.tsx:248-251, 293-307`
+
+**Scenario:** User clicks "Archive 50" → mutation in flight (10s) → user
+clicks Cancel. The dialog closes; the mutation continues server-side and
+its onSuccess fires later, showing a toast for an action the user thought
+they cancelled. Worse, the dialog is gone so they can't tell which clients
+got archived.
+
+**Fix:** Disable Cancel while `archiveMutation.isPending`, or relabel to
+"Cancel (won't stop in-progress)" and keep the mutation visible.
+
+---
+
+## Low
+
+### L1 — `audit-log-list` filter row overflows on narrow viewports
+
+**File:** `src/components/admin/audit/audit-log-list.tsx:321-467`
+
+**Scenario:** 8 filter controls (`Search` 288px, `Entity` 144px, `Action`
+176px, `Severity` 128px, `Source` 128px, `User id` 176px, `From` 144px,
+`To` 144px, total ~1330px) sit in a single `flex-wrap` row. At <1280px
+viewports they wrap onto multiple lines pushing the table down 200+px;
+at <640px (mobile) each control wraps onto its own line and the "Clear"
+button (`ml-auto`) lands on the wrong row.
+
+**Fix:** Collapse rarely-used filters (User id / Severity / Source) into a
+"More filters" Popover for sm: viewports.
+
+### L2 — `audit-log-card` action map missing entries silently fall back to grey "Activity" icon and grey badge
+
+**File:** `src/components/admin/audit/audit-log-card.tsx:27-44, 46-52`
+
+**Scenario:** New webhook/cron/job actions are in `audit-log-list.tsx`
+ACTION_COLORS but absent from `audit-log-card.tsx` ACTION_BADGE_COLORS and
+ACTION_ACCENT. Card view of these entries looks identical to a generic
+"unknown" entry — visual loss vs. table view.
+
+**Fix:** Sync the two maps; consider extracting to a shared module so they
+can't drift.

docs/audit-missing-features-2026-05-06.md

@@ -0,0 +1,405 @@
+# Missing-Features Audit — 2026-05-06
+
+Focused pass on **features that look done in the UI but aren't fully
+wired through the service layer**, plus **admin settings exposed to
+users that no code reads**. Companion to
+`docs/audit-comprehensive-2026-05-06.md` — the three "coming soon" stubs
+already documented there (client Files tab, client reservations history,
+berth tabs), the import-worker stub, the two interest-form TODOs, and
+the EOI "Price: TBD" finding are NOT re-flagged here.
+
+Hard cap: 12 findings. Severity tiers below.
+
+---
+
+## VISIBLE-BROKEN (admin sees a control, click is a no-op or wrong)
+
+### V1. 6 of 8 admin-editable email subject overrides are silently ignored at send time
+
+**Files:**
+
+- `src/components/admin/email-templates-admin.tsx:24-72` (UI)
+- `src/lib/email/template-catalog.ts:16-25` (catalog of 8 keys)
+- `src/lib/services/portal-auth.service.ts:120-127, 332-339` (the only
+  consumers of `loadSubjectOverride`)
+
+The `/admin/email-templates` page lets an admin override the subject
+line on **eight** transactional templates:
+`portal_activation`, `portal_reset`, `portal_invite_resend`,
+`crm_invite`, `inquiry_client_confirmation`,
+`inquiry_sales_notification`, `residential_inquiry_client_confirmation`,
+`residential_inquiry_sales_alert`. The save endpoint persists each one
+to `system_settings` (`email_template_<key>_subject`).
+
+Only **two** of those eight are ever read at send time —
+`portal_activation` and `portal_reset` in `portal-auth.service.ts`.
+A repo-wide search for `loadSubjectOverride` / `settingKeyForSubject`
+returns no other consumers. The other six templates use their hardcoded
+subject regardless of the admin override.
+
+**Impact:** sales/ops teams will customize an inquiry confirmation
+subject, hit Save, see the "Overridden" badge, and silently ship the
+default subject to every prospect.
+
+**Fix:** small per template — call `loadSubjectOverride(portId, key)`
+in each sender (`crm-invite.service.ts`, the inquiry sender, the
+residential inquiry sender, the portal-invite-resend path) and pass the
+result through as the email subject.
+
+**Scope:** small (5 callsites + tests).
+
+---
+
+### V2. Branding admin (logo / app name / primary color / email header & footer HTML) saves to settings but no code reads them
+
+**Files:**
+
+- `src/app/(dashboard)/[portSlug]/admin/branding/page.tsx:7-46` — UI
+  with five fields.
+- `src/lib/services/port-config.ts:240-272` — `getPortBrandingConfig()`
+  resolves the five `branding_*` settings into a typed config.
+- Repo-wide: `getPortBrandingConfig` has **zero callers** outside its
+  declaration. The five `SETTING_KEYS.branding*` constants are only
+  read inside `getPortBrandingConfig` itself.
+
+The admin panel is functional end-to-end (write hits the settings API,
+"Reset to default" works), and the email-templates module hardcodes
+`s3.portnimara.com/...` for the logo URL plus a fixed table layout.
+None of the email-rendering helpers (`renderEmail`, the template
+modules in `src/lib/email/templates/`) call `getPortBrandingConfig`,
+and the `<BrandedAuthShell>` component sources its logo + colors from
+constants too.
+
+**Impact:** every multi-tenant assumption made about branding is
+broken. A second port wired into this CRM will see Port Nimara's logo
+
+- colors in every transactional email and on the auth pages, even
+  after their admin "configures branding" successfully.
+
+**Fix:** plumb `getPortBrandingConfig(portId)` through the email
+renderer (header/footer HTML + primary button color), and through
+`<BrandedAuthShell>` via a server-fetched prop.
+
+**Scope:** medium (touches every transactional email + auth shell).
+
+---
+
+### V3. Reminder admin page configures defaults that no service applies
+
+**Files:**
+
+- `src/app/(dashboard)/[portSlug]/admin/reminders/page.tsx:7-50` — UI
+  for default-enabled, default-days, digest-enabled, digest-time,
+  digest-timezone.
+- `src/lib/services/port-config.ts:284-306` —
+  `getPortReminderConfig()` defines the schema.
+- Repo-wide: the keys (`reminder_default_*`, `reminder_digest_*`) and
+  `getPortReminderConfig` have **zero callers**.
+
+Same pattern as V2. The admin sets "enable reminders by default on new
+interests" → toggles to true → save succeeds → newly-created interests
+still default to `reminderEnabled=false`. The digest-time +
+timezone fields go nowhere — there is no scheduler that batches
+pending reminders into a daily digest.
+
+**Impact:** the entire reminder UX is decorative. Sales reps think
+they configured a daily digest at 09:00 Europe/Warsaw, get
+fire-as-they-hit notifications instead.
+
+**Fix:** wire `getPortReminderConfig` into (a) the interest-create
+service (defaults), (b) the maintenance/notifications worker that
+fires reminders (digest batching + delivery window). The `digest`
+behavior didn't exist before this audit — needs a new scheduled job.
+
+**Scope:** medium (defaults are small, digest job is new code).
+
+---
+
+### V4. Portal dashboard "My Memberships" tile has no link, no destination page, and isn't reachable from nav
+
+**Files:**
+
+- `src/app/(portal)/portal/dashboard/page.tsx:58-63` — `<PortalCard
+title="My Memberships" ... icon={Building2} />` — note no `href`
+  prop.
+- `src/components/portal/portal-nav.tsx:8-15` — six nav entries, no
+  memberships.
+- Filesystem: `src/app/(portal)/portal/memberships/` does not exist.
+
+The dashboard shows a count of "memberships" (companies the portal
+user belongs to) but the tile is non-clickable and there is no
+`/portal/memberships` route. A user with 3 memberships sees the tile,
+clicks → nothing happens.
+
+**Impact:** dead-end on the portal home for any client tied to a
+company (the residential and yacht-ownership use-cases).
+
+**Fix:** ship `/portal/memberships/page.tsx` listing the companies
+returned by the existing `companyMemberships` query (already
+aggregated in `getPortalDashboard`), and add it to `PortalNav`. Or
+pull the tile if memberships isn't a portal feature.
+
+**Scope:** small.
+
+---
+
+### V5. Company detail page Documents tab is a "Coming soon" stub
+
+**File:** `src/components/companies/company-tabs.tsx:230-234`
+
+```ts
+{
+  id: 'documents',
+  label: 'Documents',
+  content: <EmptyState title="Documents" description="Coming soon" />,
+},
+```
+
+Visible alongside the working Notes / Activity / Addresses / Members
+tabs on every company detail page. NOT covered by the existing audit
+doc's H7 (which lists clients, client reservations, and berths).
+
+**Impact:** the same UX problem H7 calls out for clients.
+
+**Fix:** mirror what client-Files-tab needs — query `documents` joined
+to a polymorphic billing-entity = company link, render a list, ship a
+download button. Or hide the tab.
+
+**Scope:** small to medium.
+
+---
+
+## HALF-WIRED (the page works but the surrounding promise overstates it)
+
+### V6. "Onboarding" admin page is a static checklist, not the wizard the page itself promises
+
+**File:** `src/app/(dashboard)/[portSlug]/admin/onboarding/page.tsx`
+
+The page renders 8 stepwise links and explicitly says (lines 71-72,
+98-110): "The future onboarding wizard will track progress per port…",
+"What this page will become", "The wizard will record completion per
+port in `system_settings`, gate the public marketing-site cutover…".
+
+The admin landing card describes it as the "Initial-setup wizard for
+fresh ports" — admins clicking through expect a wizard, get a static
+table of contents.
+
+**Impact:** the only "fresh port" workflow doesn't exist; cutover
+gating logic mentioned in the page body is also unimplemented.
+
+**Fix:** either (a) build the wizard with progress in `system_settings`
+
+- banner integration, or (b) re-label both this page and the admin
+  landing card to "Setup checklist" so expectations match reality.
+
+**Scope:** large for the wizard; tiny for the relabel.
+
+---
+
+### V7. Backup & Restore admin page is informational only — admin landing card promises actions
+
+**Files:**
+
+- `src/app/(dashboard)/[portSlug]/admin/backup/page.tsx`
+- `src/app/(dashboard)/[portSlug]/admin/page.tsx:148` — landing card
+  description: "Database snapshots and on-demand exports."
+
+The landing card sells "on-demand exports". The actual page renders a
+two-card explainer: "Current backup posture" (read-only) and "What
+this page will become" (the entire interactive surface — list
+snapshots, "Take backup now" button, per-port logical export, restore
+preview, GDPR per-client export). None of those exist.
+
+**Impact:** the "Backup & Restore" tile is functionally a docs page.
+Compliance officers / users expecting a self-serve GDPR export
+button have to file a support ticket.
+
+**Fix:** match the language on the landing card to the page reality
+("Backup posture" → docs only) until the snapshot/export buttons
+ship. The maintenance worker already runs `database-backup` (per
+`docs/audit-comprehensive-2026-05-06.md` C1 — though that worker isn't
+imported), so wiring "Take backup now" against the existing job is
+small once C1 is fixed.
+
+**Scope:** small (doc tweak) or medium (button + per-port export
+endpoint).
+
+---
+
+### V8. Inquiry inbox is read-only — no "Convert to Client" / "Mark resolved" / "Assign" actions
+
+**File:** `src/components/admin/inquiry-inbox.tsx` (entire file, 207
+lines, ends at the View payload toggle)
+
+The inbox lists website-form submissions (berth_inquiry,
+residence_inquiry, contact_form) with filter chips and a
+"View payload" expand. There is no action to:
+
+- create a client/interest from the submission,
+- assign the inquiry to a sales rep,
+- mark it resolved / triaged,
+- reply directly,
+- archive or trash the row,
+- export.
+
+The `website_submissions` table appears to be permanent — every
+inquiry ever received remains in the inbox forever, with no triage
+state. Sales has to manually copy the email into a new client form
+and back-reference the original submission.
+
+**Impact:** the inquiry-to-pipeline conversion step isn't supported in
+the CRM. The marketing-site cutover (per the user's
+`project_email_ownership_at_cutover.md` memory) will increase volume
+on this surface and make the missing triage UX painful.
+
+**Fix:** add a per-submission "Convert" action that prefills the
+client + interest forms with the payload, plus a `triage_state`
+column (open / converted / dismissed) and a default filter that hides
+non-open rows.
+
+**Scope:** medium.
+
+---
+
+## MOBILE PARITY
+
+### V9. Mobile More-sheet is missing several real top-nav destinations
+
+**File:** `src/components/layout/mobile/more-sheet.tsx:38-50`
+
+`MORE_ITEMS` lists 11 entries. The dashboard route directory has at
+least these top-level segments not represented anywhere in the mobile
+bottom-tabs OR more-sheet:
+
+- `residential` — exists at `/[portSlug]/residential/...`
+- `notifications` — exists at `/[portSlug]/notifications/...`
+- `berth-reservations` — exists at `/[portSlug]/berth-reservations/...`
+- `documents` — exists as a top-level page (separate from the bottom
+  tab `documents`, which IS in mobile-bottom-tabs)
+- `website-analytics` — exists at `/[portSlug]/website-analytics/...`
+
+A mobile-only user has no path to any of them. The Documents bottom
+tab does cover the doc list, but residential is an entire feature
+domain (per the `(dashboard)/.../residential` directory) with no
+mobile entry point.
+
+**Impact:** anyone using the mobile chrome to triage on the go can't
+reach residential clients/interests, alerts (`alerts` IS in the
+sheet), or notifications.
+
+**Fix:** add the missing segments to `MORE_ITEMS`. If the grid feels
+too dense, reorganize into sections.
+
+**Scope:** small.
+
+---
+
+### V10. Portal has no "Profile" / "Change password" surface
+
+**Files:**
+
+- `src/components/portal/portal-nav.tsx:8-15` — six tabs, no profile.
+- Filesystem: no `src/app/(portal)/portal/profile/` directory.
+
+A portal user who wants to change their email, phone, mailing address,
+or password has no UI. The portal sign-in flow goes through the
+better-auth session but the app exposes zero account-management
+controls. The "Need assistance?" card on the dashboard tells the user
+to contact the port team — which is the explicit answer for data
+edits, but does not cover password changes (a security expectation,
+not a per-port-staff burden).
+
+**Impact:** every portal user who forgets their password (after
+already activating) has to use `/portal/forgot-password` even if they
+remember the old one. There's no proactive password rotation. A user
+who changes their phone number has to email the port to update it.
+
+**Fix:** ship `/portal/profile` with at minimum: read-only PII view +
+"Change password" form (re-uses the existing reset-password endpoint
+or a new `change-password` endpoint that takes the current pw).
+Phone/address editing is a longer fix because of the audit-trail
+implications.
+
+**Scope:** small for password; medium with PII edits.
+
+---
+
+### V11. Portal invoices page lists invoices but offers no view/download — even though documents do
+
+**File:** `src/app/(portal)/portal/invoices/page.tsx:53-99`
+
+Each invoice row shows number, status, due/paid dates, amount, and a
+small payment-status caption. There is no link, no PDF view, no
+download. By contrast, the portal Documents page (peer route) ends
+each row with a `<DocumentDownloadButton documentId={doc.id} />` that
+fetches a signed S3 URL.
+
+Compare to admin/CRM where invoices have a full PDF render flow
+(invoice service generates the PDF + signed URL).
+
+**Impact:** a portal user can see they owe money and cannot retrieve
+the actual invoice document. They have to email the port to ask for a
+PDF copy.
+
+**Fix:** add an invoice-PDF endpoint under `/api/portal/invoices/[id]/
+download` mirroring the documents one, and a download button on each
+row. The invoice PDF generator already exists (`src/lib/services/
+invoices.ts`).
+
+**Scope:** small.
+
+---
+
+## DEV-NOTES (legitimately staged-for-later, calling out so they're not forgotten)
+
+### V12. Email-templates admin only edits subject lines — body editing is a documented "next iteration"
+
+**Files:**
+
+- `src/components/admin/email-templates-admin.tsx:78-79` —
+  "Customize the subject line of transactional emails per port. Body
+  editing is the next iteration; for now the layout and HTML stay
+  locked to the default template."
+- `src/lib/email/template-catalog.ts:5-9` — same statement in the
+  catalog header.
+
+The page is honest about the limitation, so this isn't a "broken"
+finding. But it's a notable shipped-without-the-killer-feature gap:
+the multi-tenant promise of per-port email customization can't deliver
+the body changes that ports actually want (logo placement, signature,
+language). Combined with V2 (branding HTML fragments aren't read at
+all), there is currently NO way for a non-super-admin per-port admin
+to customize the email body in any way.
+
+**Impact:** confined to admin expectations — most ports will assume
+"Email templates" = "edit the email", click in, see only a subject
+field, and request the missing body editor.
+
+**Fix:** scope a body-editing flow that reuses the
+`merge_fields.ts` token catalog (the validator already exists for
+document templates) for safety. Until that's built, V2 + this finding
+together mean a "rebrand the emails" task is single-tenant only.
+
+**Scope:** large (HTML editor + token validator + per-port override
+storage + render-side composition).
+
+---
+
+## Summary
+
+12 findings, four severity tiers:
+
+- **Visible-broken (V1-V5):** five admin/portal controls produce no
+  effect. V1 (email overrides) and V2 (branding) are the highest
+  impact — both silently break the multi-tenant promise.
+- **Half-wired (V6-V8):** three pages where the surrounding wrapper
+  oversells what's there. V8 (inquiry inbox) is the largest scope.
+- **Mobile parity (V9-V11):** mobile users can't reach several real
+  features; portal users have no profile/password surface and can't
+  download invoices.
+- **Dev-notes (V12):** documented limitations called out for the
+  roadmap.
+
+The two highest-leverage quick wins are **V1** (wire 6 missing
+template subject overrides — a few hours) and **V11** (portal invoice
+download — small, fixes a real customer pain point).

docs/audit-permissions-2026-05-06.md

@@ -0,0 +1,266 @@
+# Per-role permission audit — 2026-05-06
+
+Focused review of UI/server permission divergence on the new endpoints
+shipped during the smart-archive / hard-delete / bulk-wizard /
+external-EOI / webhook-replay work bundle. Skips items already covered
+in `docs/audit-comprehensive-2026-05-06.md` (audit-log gating H6,
+residential_partner sidebar nav).
+
+The pattern hunted for: `<PermissionGate>` (or `usePermissions().can`)
+on the UI side hides a control under permission **X**, while the
+matching API route gates on permission **Y** (or doesn't gate at all,
+or gates strictly — producing 403 toast spam for users who can see the
+button but can't use it).
+
+Scope: 8 routes + 5 components + the seed permission matrix. Hard cap
+of 10 findings, ranked by impact. Critical/High/Medium/Low.
+
+---
+
+## CRITICAL
+
+_None._ The four new hard-delete endpoints all gate on
+`admin.permanently_delete_clients` on both layers (UI hides the button
+via `<PermissionGate resource="admin" action="permanently_delete_clients">`
+in `client-detail-header.tsx:162` and via `canHardDelete = can('admin',
+'permanently_delete_clients')` in `client-list.tsx:53`; the four routes
+all wrap with `withPermission('admin', 'permanently_delete_clients', …)`).
+The webhook-replay route gates on `admin.manage_webhooks` — see H1 below
+for the matching UI gap.
+
+---
+
+## HIGH
+
+### H1. Webhook replay button has no UI permission gate (403 toast for non-admins)
+
+- **UI:** `src/components/admin/webhooks/webhook-delivery-log.tsx:118-131`
+  — the Replay `<Button>` renders for any user who can load the page,
+  with no `<PermissionGate>` wrapper and no `usePermissions().can('admin',
+'manage_webhooks')` check.
+- **Server:** `src/app/api/v1/admin/webhooks/[webhookId]/deliveries/[deliveryId]/redeliver/route.ts:15`
+  — `withPermission('admin', 'manage_webhooks', …)`.
+
+**Divergence:** A `sales_manager` / `sales_agent` / `viewer` who
+somehow lands on `/admin/webhooks/{id}` (e.g. via a deep link from a
+shared message) sees enabled Replay buttons. Clicking surfaces a
+generic 403 toast — the user has no signal that the action is
+restricted, just that "Replay failed".
+
+**Fix:** wrap the Replay `<Button>` in
+`<PermissionGate resource="admin" action="manage_webhooks">…</PermissionGate>`,
+or skip rendering the entire "Replay" column when
+`!can('admin', 'manage_webhooks')`. The page-level guard on
+`/admin/webhooks` should prevent non-admins from reaching the route in
+the first place, but defense-in-depth is cheap and the toast UX is
+poor.
+
+---
+
+### H2. Bulk-archive bulk action exposed to roles without `clients.delete`
+
+- **UI:** `src/components/clients/client-list.tsx:182-190` — the
+  "Archive" entry in `bulkActions` is unconditionally rendered (only
+  the "Permanently delete" entry checks `canHardDelete`).
+- **Server:** `src/app/api/v1/clients/bulk/route.ts:40-57` — gates
+  `archive` action on `clients.delete`. Also
+  `src/app/api/v1/clients/bulk-archive-preflight/route.ts:30` —
+  `withPermission('clients', 'delete', …)`.
+
+**Divergence:** `sales_agent` (`clients.delete:false`,
+seed-permissions.ts:246) and `viewer` (`clients.delete:false`,
+seed-permissions.ts:323) both see the Archive bulk action. Selecting
+clients and pressing it fires the `BulkArchiveWizard`, which calls
+`bulk-archive-preflight` (returns 403) followed by `bulk` archive
+(also 403). The wizard surfaces this as an opaque error.
+
+**Fix:** mirror the `canHardDelete` pattern — compute
+`const canBulkArchive = can('clients', 'delete');` near
+`client-list.tsx:53` and conditionally include the Archive entry.
+
+---
+
+### H3. Bulk add_tag / remove_tag exposed to viewer (clients.edit:false)
+
+- **UI:** `src/components/clients/client-list.tsx:165-181` — the "Add
+  tag" / "Remove tag" bulk actions render with no permission check.
+- **Server:** `src/app/api/v1/clients/bulk/route.ts:40-57` — both gate
+  on `clients.edit`.
+
+**Divergence:** A `viewer` can multi-select rows, click "Add tag" or
+"Remove tag", pick a tag in the dialog, hit "Apply", and receive a 403. The standalone bulk tag dialog has no inline gating to prevent
+this.
+
+**Fix:** the bulk action menu entries should gate on
+`can('clients', 'edit')`. (Sales agent and above pass; only `viewer`
+and `residential_partner` see the bug.)
+
+---
+
+### H4. `client-merge-log.surviving_client_id` enforcement absent from per-row port check on bulk hard-delete
+
+- **Server:** `src/lib/services/client-hard-delete.service.ts:269-272`
+
+The bulk preflight loads **every** row in the port
+(`db.select(...).from(clients).where(eq(clients.portId, args.portId))`)
+into memory, then validates the requested `clientIds` against that map.
+That's correct for tenant isolation — a foreign-port id can't appear in
+the map — but the inner loop at lines 364-389 then re-fetches each
+client by `(id, portId)` and **silently skips** rows where the second
+fetch returns nothing (line 377: `if (!c) continue;`). If a client is
+archived between preflight and execute by another operator, the bulk
+delete reports `deletedCount` lower than the requested set with no
+error — the operator has no way to tell which ids were skipped.
+
+**Divergence (perm-adjacent):** the per-row gate is enforced for
+tenancy but the failure mode masquerades as success. Combined with
+the route's all-or-nothing `withPermission` at the top, a
+`permanently_delete_clients`-bearing operator can quietly under-delete.
+
+**Fix:** when `c` is null, push the id into a `skipped: string[]`
+array and return it in the response so the UI can surface "3
+deleted, 1 skipped (not archived / removed by another user)".
+
+---
+
+## MEDIUM
+
+### M1. `external-eoi` upload allows any role with `documents.upload_signed` regardless of `interests.edit`
+
+- **UI:** `src/components/interests/interest-detail-header.tsx:382-395`
+  — `<PermissionGate resource="documents" action="upload_signed">`.
+- **Server:** `src/app/api/v1/interests/[id]/external-eoi/route.ts:8`
+  — `withPermission('documents', 'upload_signed', …)`.
+
+**Divergence:** UI and server agree on the permission, but the seed
+matrix has `documents.upload_signed:true` for `sales_agent` (line 264) AND any custom role with that flag — uploading an externally
+signed EOI mutates the **interest** (it's the operative `signedDocument`
+that flips the interest into a "signed" state inside
+`uploadExternallySignedEoi`). The user only needs `documents.upload_signed`,
+not `interests.edit`. A custom role with `documents.upload_signed:true`
+
+- `interests.edit:false` can mutate the interest's effective state.
+
+**Fix:** add a second gate inside the route handler:
+`if (!ctx.isSuperAdmin && !ctx.permissions?.interests?.edit) throw new ForbiddenError(...)`.
+Rationale: signing a doc against an interest is an interest-state
+change, not just a document upload. Mirror the same check in
+`<PermissionGate>` (use `<PermissionGate resource="interests" action="edit">`
+nested inside the `documents.upload_signed` gate).
+
+---
+
+### M2. `change_stage` UI doesn't expose override checkbox in `InlineStagePicker` — server still accepts override
+
+- **UI:** `src/components/interests/inline-stage-picker.tsx:52-58` —
+  the inline picker (used in the detail header at
+  `interest-detail-header.tsx:221`) sends only
+  `{ pipelineStage, reason }` and never sets `override:true`. Users
+  with `override_stage` get no UI affordance to actually use the
+  permission from the inline picker; they have to open the modal
+  `InterestStagePicker` (which does expose the checkbox at line 137).
+  Worse, when a user picks a stage that isn't a legal forward
+  transition, the inline picker just shows the toast from the server's
+  `ConflictError` — instead of "you need override; toggle this box".
+- **Server:** `src/app/api/v1/interests/[id]/stage/route.ts:14-22` —
+  reads `body.override` and re-checks `interests.override_stage`
+  permission.
+
+**Divergence:** UI and permission map diverge in the affordance, not
+the gate. End-result: the `override_stage` permission is partially
+unreachable from the inline picker. Sales managers / agents can
+override only via the modal picker.
+
+**Fix:** when the inline picker sees a transition that isn't allowed
+by `canTransitionStage(currentStage, newStage)`, check
+`can('interests', 'override_stage')` and either auto-set
+`override:true` (with a confirmation) or surface a "Use override"
+secondary action. Keep the inline picker UX; just don't let the
+override permission be silently inaccessible from the most-used
+path.
+
+---
+
+### M3. `sales_agent` granted `interests.override_stage:true` — possible copy-paste from sales_manager
+
+- **Seed:** `src/lib/db/seed-permissions.ts:253` — `SALES_AGENT_PERMISSIONS.interests.override_stage = true`.
+
+This is identical to `SALES_MANAGER_PERMISSIONS.interests.override_stage = true`
+at line 176. The same `sales_agent` block has `delete:false` for
+clients/interests/yachts/companies/files/etc — all the other
+"trust-elevated" flags are explicitly stripped from sales_agent. The
+ability to bypass the pipeline-stage transition table is a meaningful
+trust elevation: it lets an agent skip prerequisites (e.g. mark an
+interest as `eoi_signed` without an actual signed doc) which has
+downstream implications for the public berths feed (`Under Offer`
+status), the recommender's tier ladder, and the EOI bundle.
+
+**Divergence:** likely intent vs. permission map. Worth confirming
+with a product owner; if intentional, leave a code comment. If
+unintentional, flip to `false`.
+
+**Fix:** product decision. If demoted, also update
+`src/components/admin/roles/role-form.tsx → DEFAULT_PERMISSIONS`
+(noted in the file header at seed-permissions.ts:9) so the UI
+default for new roles matches.
+
+---
+
+### M4. `bulk-archive-preflight` returns dossier even when client is in another port (defense-in-depth)
+
+- **Server:** `src/app/api/v1/clients/bulk-archive-preflight/route.ts:33-62`
+
+The route loops through `ids` and calls `getClientArchiveDossier(id, ctx.portId)`
+for each. If a `clientId` belongs to another port, `getClientArchiveDossier`
+throws and the route catches it (line 52-61) and returns a fallback row
+with `blockers: ['<error message>']`. This leaks **the existence of an
+unknown client id** — an attacker enumerating UUIDs can distinguish
+"client doesn't exist" from "client exists but you can't see it" by
+parsing the blocker text. The bulk hard-delete route has the same
+shape but returns `NotFoundError`.
+
+**Divergence (perm-adjacent):** the preflight route doesn't enforce a
+per-id port check before falling through to the dossier service, and
+the catch block leaks the failure mode in the response.
+
+**Fix:** in the catch block, replace the dossier error message with a
+generic `'Could not load dossier'` blocker. The operator already
+selected these ids so they know the count; they don't need the inner
+error.
+
+---
+
+## LOW
+
+### L1. `external-eoi` route doesn't enforce `interests.edit` defense-in-depth on the interest port
+
+- **Server:** `src/app/api/v1/interests/[id]/external-eoi/route.ts:8-14`
+
+The route receives `interestId` from the URL and passes it +
+`ctx.portId` into `uploadExternallySignedEoi`. The service is
+expected to enforce port isolation, but the route itself does no
+upfront `(interestId, portId)` existence check before reading the
+multipart body — meaning a cross-port id will fully process the
+upload (read the file into memory) before the service rejects.
+
+**Divergence:** not strictly a permission divergence; it's resource
+waste from missing early port-ownership check. Low because the
+service-level reject does close the security hole.
+
+**Fix:** add a one-row `select` on `interests` matching `id` + `portId`
+before parsing form data, throw `NotFoundError` on miss.
+
+---
+
+## Summary
+
+- 0 critical
+- 4 high (H1–H4)
+- 4 medium (M1–M4)
+- 1 low (L1)
+
+Top recommendation: H1 (webhook-replay UI gate) is a
+ten-line fix that closes a 403-toast UX bug. H2 + H3 (bulk-archive +
+bulk-tag UI gates) are also trivial and remove the same class of bug
+across the bulk actions menu. M3 (sales_agent override_stage) needs a
+product decision, not code; flag it before shipping the audit.

docs/audit-reliability-2026-05-06.md

@@ -0,0 +1,220 @@
+# Reliability audit — 2026-05-06 (focused, post-batch deltas)
+
+Scope: NEW services from the recent archive/restore/hard-delete/external-EOI batches.
+Out of scope (already covered in `docs/audit-comprehensive-2026-05-06.md`):
+worker imports, rate limits, hard-delete error message UX, smart-restore
+dead reversal applier, bulk hard-delete redis loop, audit log spam.
+
+---
+
+## Critical
+
+### C1. Bulk archive enqueues zero post-commit side effects
+
+- **File:** `src/app/api/v1/clients/bulk/route.ts:68-134`
+- **Scenario:** When the bulk wizard archives 100 clients with high-stakes
+  reasons, `archiveClientWithDecisions` returns `externalCleanups` and
+  `releasedBerths` arrays per-client, but `runBulk` discards the return
+  value. Documenso envelopes that the wizard marked `void_documenso`
+  never get queued, and "next-in-line" notifications never fire. The
+  database is left in `documents.status='cancelled'` with the live
+  Documenso envelope still out for signature — the signer can complete
+  a legally-binding envelope that the CRM thinks is voided.
+- **Fix:** Make the per-row callback return the result, then loop over
+  `results` after `runBulk` to enqueue Documenso voids and fire
+  next-in-line notifications (mirroring the single-client route).
+  Defaulting `documentDecisions` to `'leave'` (line 113-116) hides the
+  symptom for the bulk wizard but isn't enough — the single-client
+  service can still surface this if the bulk path is ever generalized.
+
+---
+
+## High
+
+### H1. Restore wizard silently drops every released berth
+
+- **File:** `src/lib/services/client-restore.service.ts:359-372`
+- **Scenario:** `applyReversal` for `berth_released` is a no-op with a
+  comment saying "v1 leaves the berth available". But the dossier (line
+  122-129) classifies these as `autoReversible` and the UI tells the
+  operator "still available — re-attaching to the restored client". The
+  wizard increments `autoReversed` and the audit log records a
+  successful auto-reverse — but nothing actually happens. Operator
+  thinks restore re-linked their berth; it didn't.
+- **Fix:** Either (a) actually re-link by persisting the original
+  `interestId` in the `berth_released` decision detail (it's already
+  there, line 211) and re-inserting an `interestBerths` row + flipping
+  the berth status back to `under_offer`, or (b) reclassify these as
+  `reversibleWithPrompt` with copy that says "berth left available —
+  re-add via the interest detail page".
+
+### H2. Smart-archive berth status update has TOCTOU race
+
+- **File:** `src/lib/services/client-archive.service.ts:191-207`
+- **Scenario:** Berth row is read via `dossier.berths` (read outside the
+  tx) and modified inside the tx without a `for update` lock on
+  `berths`. Two concurrent flows — e.g. operator A archives client X
+  while operator B sells berth A1 to client Y — can race: A reads
+  `berth.status === 'sold' → false`, B's tx commits sold, A's tx then
+  flips it back to `available`. The "still under offer" subselect
+  doesn't catch this because berth.status is the source of truth, not
+  interest_berths.
+- **Fix:** Add `tx.select(...).from(berths).where(eq(berths.id, d.berthId)).for('update')`
+  before the status flip and re-check `status !== 'sold'` against the
+  locked row.
+
+### H3. Bulk archive can pick the wrong interest for berth release
+
+- **File:** `src/app/api/v1/clients/bulk/route.ts:95-103`
+- **Scenario:** When a client has multiple interests linked to the same
+  berth, the bulk wizard picks `dossier.interests.find((i) =>
+i.primaryBerthMooring === b.mooringNumber)` and falls back to
+  `dossier.interests[0]?.interestId ?? ''`. The fallback to the
+  first-interest-or-empty-string can hand `archiveClientWithDecisions`
+  an `interestId` that was never linked to that berth — so the
+  `delete from interest_berths where berthId=… and interestId=…`
+  matches zero rows and the link is silently retained. Worse: an empty
+  string `''` reaches the delete, which still matches zero rows but
+  leaves the berth status check believing the link was removed.
+- **Fix:** Build the berth→interest map from `interestBerthRows` (the
+  authoritative join) rather than guessing by `primaryBerthMooring`,
+  and skip berths with no resolvable interest rather than emitting an
+  empty-string interestId.
+
+### H4. External EOI runs four writes outside a transaction
+
+- **File:** `src/lib/services/external-eoi.service.ts:67-155`
+- **Scenario:** `getStorageBackend().put()`, `files.insert`,
+  `documents.insert`, `documentEvents.insert`, and the interests
+  update happen as five independent operations. If any one fails after
+  the storage upload, you're left with an orphan PDF in S3/MinIO and
+  partial DB state. If the documents insert fails after the file
+  insert, the file row points to a storage key with no document
+  referencing it — and the interest never advances.
+- **Fix:** Wrap files/documents/documentEvents/interests in a single
+  `db.transaction`. Storage upload stays outside (S3 isn't
+  transactional) but on tx failure, schedule a cleanup job that deletes
+  the orphan storage object, or accept the orphan and add a janitor.
+
+### H5. Bulk wizard double-submit re-archives the same client and racy errors
+
+- **File:** `src/app/api/v1/clients/bulk/route.ts:68-120` +
+  `src/lib/services/client-archive.service.ts:165-173`
+- **Scenario:** The single-client `archiveClientWithDecisions` locks
+  the row and throws `ConflictError('Client is already archived')` on
+  re-entry — good. But `runBulk` swallows the error string and returns
+  it as `{ok:false, error:"Client is already archived"}` for that
+  client. If the bulk wizard double-submits (network retry, double
+  click), partial successes from the first request now look like
+  per-client failures in the response, confusing the operator. There's
+  no idempotency key on the bulk submit.
+- **Fix:** Treat `ConflictError('already archived')` as success in the
+  bulk per-row handler (the desired end state is reached). Or add an
+  idempotency-key header on the bulk endpoint that short-circuits a
+  duplicate request with the cached response.
+
+---
+
+## Medium
+
+### M1. Hard-delete `clientMergeLog.surviving_client_id` deletes audit history
+
+- **File:** `src/lib/services/client-hard-delete.service.ts:209`
+- **Scenario:** The comment says "merged records remain in the log
+  because mergedClientId has no FK", but the delete is wider than
+  needed: it removes every merge-log row where this client was the
+  survivor. If client X (being deleted) previously absorbed clients
+  A/B/C, the audit trail of those merges is lost on X's deletion. The
+  surviving rows that remain (`mergedClientId = X`) are now
+  inconsistent — they reference a survivor that no longer exists.
+- **Fix:** Either preserve the survivor rows by setting
+  `surviving_client_id = NULL` (requires column nullable) or keep the
+  current behavior but document it more visibly. At minimum, log the
+  deleted merge-log row count so operators can investigate gaps.
+
+### M2. Documenso void worker has no max-retry guard for non-404 errors
+
+- **File:** `src/lib/queue/workers/documents.ts:19-37`
+- **Scenario:** `voidDocument` throws `CodedError` on non-404 failures
+  (auth error, network blip, Documenso 500). BullMQ retries with
+  backoff, but there's no per-job idempotency check — the second
+  retry hits the same envelope, voidDocument's 404 short-circuit only
+  kicks in if Documenso has actually voided it on the first retry
+  before the API call returned an error. A persistent 401 / 403 will
+  retry forever (until BullMQ exhausts attempts) and the documents row
+  stays `cancelled` in the CRM with the envelope still live in
+  Documenso. The DLQ is mentioned in the comment but the worker
+  doesn't surface a DLQ alert hook.
+- **Fix:** On exhaustion, write back to `documents` (e.g.
+  `cancellation_failed=true`) and emit an admin notification so the
+  envelope can be voided manually.
+
+### M3. Next-in-line notification fan-out unhandled rejection
+
+- **File:** `src/lib/services/next-in-line-notify.service.ts:75-87`
+- **Scenario:** Each `void createNotification(...)` is a fire-and-forget
+  promise with no `.catch` handler. If `notifications.service`
+  dispatches to a DB that's transiently down, the unhandled rejection
+  will surface in the Node process with no recipient context (the
+  closure captured `userId` is in the stack but pino won't include it
+  unless explicitly logged). Process-level handlers will log it but
+  individual recipients silently lose their notification.
+- **Fix:** `.catch((err) => logger.warn({err, userId, berthId:
+input.berthId}, 'next-in-line notification failed'))`.
+
+### M4. Restore service uses `any` for transaction type
+
+- **File:** `src/lib/services/client-restore.service.ts:354-355`
+- **Scenario:** `applyReversal(tx: any, ...)` defeats Drizzle's type
+  safety. A future schema rename (e.g. `yachts.status` enum change)
+  won't fail at compile time inside this function. Combined with the
+  documented v1 no-op for `berth_released`, the function looks
+  innocuous but carries the most risk.
+- **Fix:** Use the proper Drizzle tx type — `Parameters<Parameters<typeof
+db.transaction>[0]>[0]` or a named type alias from
+  `@/lib/db/types.ts` if one exists.
+
+### M5. interests.changeInterestStage milestones write outside tx
+
+- **File:** `src/lib/services/interests.service.ts:630-648`
+- **Scenario:** The override path (and normal path) writes
+  `pipelineStage` in one update and milestone fields
+  (`dateEoiSent`, `dateContractSigned`, etc.) in a second update. If
+  the process crashes between the two, the stage advances but the
+  milestone is never recorded. Funnel/conversion math then under-
+  counts that interest. Over-the-wire this is rare but the audit log
+  fires before the milestone update succeeds, so the audit trail
+  claims a complete transition that's actually half-applied.
+- **Fix:** Combine both into a single update statement, computing the
+  milestone fields in JS and merging them into the `set({...})` clause.
+
+---
+
+## Low
+
+### L1. Smart-archive coalesces invoice notes via SQL string concat
+
+- **File:** `src/lib/services/client-archive.service.ts:288-291`
+- **Scenario:** `notes: sql\`coalesce(${invoices.notes}, '') || ${...}\``embeds`new Date().toISOString()`and the action label inside a
+parameterized string. The values are bound, so it's not an injection
+risk, but the`\n[archive ...]` marker is appended unconditionally —
+  re-running the archive on a not-yet-committed client would double
+  the marker. Combined with H5 (no idempotency on bulk), a retry could
+  bloat invoice notes with duplicate markers.
+- **Fix:** Append only when the marker isn't already present, or rely
+  on the `clients.archivedAt is null` precheck (which already guards
+  re-entry) and accept the duplicate as theoretically impossible.
+
+### L2. Hard-delete `requestHardDeleteCode` reveals client existence pre-archive
+
+- **File:** `src/lib/services/client-hard-delete.service.ts:77-85`
+- **Scenario:** A user without `admin.permanently_delete_clients`
+  shouldn't reach this service, so this is theoretical, but the
+  ConflictError "Client must be archived" leaks the existence of an
+  unarchived client to anyone who can reach the route. The audit doc
+  flagged hard-delete error messages already (out of scope), but this
+  specific error path isn't covered there.
+- **Fix:** Same as the audit-doc finding for the symmetric path —
+  return a generic `NotFoundError` instead of distinguishing
+  "not found" from "not archived" externally; log the distinction
+  internally only.

docs/berth-feature-handoff-prompt.md

@@ -0,0 +1,147 @@
+# Handoff prompt for new Claude Code session
+
+Copy everything below the `---` line into the new chat as your first message.
+
+---
+
+I'm continuing work on a comprehensive multi-feature push that was fully designed in a prior session but not yet implemented. The complete plan lives at `docs/berth-recommender-and-pdf-plan.md` (~1030 lines). **Read that file end-to-end before doing anything else — every design decision, schema change, edge case, and confirmed answer to a product question is captured there.** Don't re-litigate decisions; if something seems unclear, the answer is almost certainly in the plan.
+
+## What the project is
+
+A multi-tenant marina/port-management CRM at `/Users/matt/Repos/new-pn-crm`. Next.js 15 App Router, React 19, TypeScript strict, Drizzle ORM on Postgres, MinIO for files, BullMQ on Redis, better-auth, shadcn/ui, Tailwind. See `CLAUDE.md` for the conventions.
+
+## What we're building (high level)
+
+The plan bundles 8 capabilities into one branch (`feat/berth-recommender`):
+
+1. **/clients + /interests list-column fix** (the original bug — list views show `-` everywhere because the service didn't join contacts/yachts)
+2. **Full NocoDB Berths import** + seeding + mooring-number normalization (current CRM has `A-01..E-18`; canonical is `A1..E18`)
+3. **Schema refactor** to many-to-many `interest_berths` with role flags (`is_primary`, `is_specific_interest`, `is_in_eoi_bundle`)
+4. **Berth recommender** (SQL ranking, tier ladder, heat scoring, UI panel) — no AI; pure SQL
+5. **EOI bundle** support (multi-berth EOIs + range formatter for the Documenso PDF: `["A1","A2","A3","B5","B6"]` → `"A1-A3, B5-B6"`)
+6. **Pluggable storage backend** (s3-compatible OR local filesystem) so admins can run without MinIO if they want
+7. **Per-berth PDFs** (versioned uploads, OCR-based reverse parser, conflict-resolution diff dialog)
+8. **Sales send-out emails** (berth PDF + brochure) with full audit + size-aware fallback to download links
+
+## Phase ordering (from plan §2)
+
+```
+Phase 0:  Full NocoDB berth import + mooring normalization + 5 new pricing columns
+Phase 1:  /clients + /interests list column fix
+Phase 2:  M:M interest_berths schema refactor + desired dimensions on interests
+Phase 3:  CRM /api/public/berths endpoint + website cutover
+Phase 4:  Recommender SQL + tier ladder + heat + UI panel
+Phase 5:  EOI bundle + range formatter
+Phase 6a: Pluggable storage backend + migration CLI + admin UI
+Phase 6b: Per-berth PDF storage (versioned) + reverse parser
+Phase 7:  Sales send-outs + brochure admin + email-from settings
+Phase 8:  CLAUDE.md updates + final validation
+```
+
+**Start with Phase 0**.
+
+## Working tree state at handoff
+
+- Branch: `main` (you'll create `feat/berth-recommender` from here)
+- Recent commits (already pushed):
+  - `8699f81 chore(style): codebase em-dash sweep + minor layout polish`
+  - `d62822c fix(migration): NocoDB import safety + dedup helpers + lead-source backfill`
+  - `089f4a6 feat(receipts): upload guide page + scanner head-tag fix`
+  - `77ad10c feat(dashboard): custom date range + KPI port-hydration gate`
+  - `e598cc0 feat(layout): unified Inbox + UserMenu extraction`
+  - `f5772ce feat(analytics): Umami integration with per-port admin settings`
+  - `49d34e0 feat(website-intake): dual-write endpoint + migration chain repair`
+- Untracked / uncommitted at handoff:
+  - `docs/berth-recommender-and-pdf-plan.md` (the plan — read this first)
+  - `docs/berth-feature-handoff-prompt.md` (this file)
+  - `berth_pdf_example/` (two reference files — see below)
+  - `.env.example` (modified — adds `WEBSITE_INTAKE_SECRET=`; pre-commit hook blocks `.env*` files so user adds this manually)
+- Dev DB state:
+  - 245 clients (210 with no `nationality_iso` — Phase 1 backfills from primary phone's `value_country`)
+  - 4 test rows in `website_submissions` (from a previous live audit; safe to ignore)
+  - 90 berths with `mooring_number` in `A-01` format (Phase 0 normalizes to `A1`)
+  - vitest: 956 tests passing
+  - tsc: clean (one pre-existing issue in `scripts/smoke-test-redirect.ts` that's unrelated)
+
+## Reference files
+
+- `berth_pdf_example/Berth_Spec_Sheet_A1.pdf` (358 KB) — sample per-berth PDF. **0 AcroForm fields** (confirmed via pdf-lib) so OCR with positional heuristics is the primary parser tier; the AcroForm tier is built defensively. Plan §9.2 captures the layout structure.
+- `berth_pdf_example/Port-Nimara-Brochure-March-2025_5nT92g.pdf` (10.26 MB) — sample brochure. Sized so it ships as an attachment under the 15 MB threshold. Plan §11.1 covers brochure handling.
+
+## NocoDB access
+
+You have `mcp__NocoDB_Base_-_Port_Nimara__*` tools available. Tables you'll touch most:
+
+- `mczgos9hr3oa9qc` — Berths (Phase 0 imports from here; mooring numbers are stored as `A1..E18`)
+- `mbs9hjauug4eseo` — Interests (the combined client+deal table the old system used)
+
+## Branch & commit conventions
+
+- Create the branch: `git checkout -b feat/berth-recommender`
+- Commit messages match recent history style: `<type>(<scope>): <subject>` lowercase, terse subject, body explains why not what.
+- **Pre-commit hook blocks any `.env*` file** including `.env.example`. If you need to update `.env.example`, leave it staged and tell the user to commit manually with `--no-verify` (they're aware of this).
+- **Don't push without explicit user permission.** Commits are fine; pushes need approval.
+- **Don't run `git rebase`, `git push --force`, or anything destructive without checking.** The branch is solo-owned but the repo's `main` is shared.
+
+## User communication preferences (from prior session)
+
+- Direct, no fluff. If something is a bad idea, say so — don't sycophant.
+- When proposing changes, include trade-offs explicitly.
+- For multi-question decisions, use `AskUserQuestion` rather than long bulleted lists.
+- Run validation (vitest + tsc) at logical checkpoints. Don't ship a commit with regressions.
+- The user prefers small focused commits over mega-commits. Within Phase 0 alone there will probably be 2-3 commits (e.g. mooring normalization, schema additions, NocoDB import script).
+
+## Critical rules (from plan §14)
+
+Eleven 🔴 critical items requiring tests before their phase ships:
+
+1. NocoDB mooring collisions → unique constraint + ON CONFLICT
+2. Non-PDF disguised upload → magic-byte check
+3. Recipient email typos → pre-send confirmation
+4. XSS in email body markdown → DOMPurify + payload tests
+5. SMTP credentials silently failing → loud error + failed `document_sends` row
+6. Wrong-environment `CRM_PUBLIC_URL` → health-check env match
+7. Mooring format drift breaking `/berths/A1` URLs → Phase 0 normalization gates Phase 3
+8. Multi-port isolation in recommender → explicit `port_id` filter + cross-port test
+9. Permission escalation on SMTP creds → per-port admin only, no rep visibility
+10. Filesystem backend in multi-node deployment → refuse to start; documented + health-check enforced
+11. Path traversal via storage key in filesystem mode → strict regex validation + path realpath check
+
+## Pending items (from plan §9)
+
+These are non-blocking but worth knowing:
+
+- Sample brochure already provided (the 10.26 MB file above).
+- SMTP app password for `sales@portnimara.com` — not yet obtained; expected close to production cutover. Phase 7 ships the admin UI immediately and the credential gets entered when available.
+- `CRM_PUBLIC_URL` confirmed as `https://crm.portnimara.com` once live; configurable via env.
+- GDPR cascade behavior for `document_sends` (delete vs. anonymize-PII vs. keep) — left `OPEN` in §14.10, default lean: anonymize-PII. Revisit when Phase 7 schema lands.
+
+## Scope reminder
+
+- **No prod data depends on the current CRM schema** — refactors don't need backwards-compatibility shims. But every schema change still ships as a Drizzle migration with `pnpm db:generate`.
+- **Pluggable storage** rejects Postgres `bytea` as an option (§4.7a). The two backends are s3-compatible (MinIO/AWS/B2/R2/etc.) and local filesystem. Filesystem is single-node only.
+
+## What to do first
+
+1. Read `docs/berth-recommender-and-pdf-plan.md` end-to-end. Don't skim. The edge-case audit in §14 alone is critical context.
+2. Confirm you've understood the plan by stating back the 8-phase outline and the 11 critical items, then ask the user if they want to proceed with Phase 0.
+3. Once approved, create `feat/berth-recommender` and start Phase 0.
+
+Phase 0 deliverables (per plan):
+
+- One commit normalizing existing CRM mooring numbers from `A-01` → `A1` form (via `regexp_replace` migration). Delete the offending `scripts/load-berths-to-port-nimara.ts`.
+- One commit adding the 5 new berth columns (`weekly_rate_high_usd`, `weekly_rate_low_usd`, `daily_rate_high_usd`, `daily_rate_low_usd`, `pricing_valid_until`, `last_imported_at`). Run `pnpm db:generate`. Verify `meta/_journal.json` prevId chain stays contiguous.
+- One commit adding `scripts/import-berths-from-nocodb.ts` — the idempotent NocoDB import (handles updates, preserves CRM-side edits via `last_imported_at vs updated_at` check, `pg_advisory_lock`, dry-run flag, etc. per §4.1 and §14.1).
+- Update `src/lib/db/seed-data.ts` with the imported berth set so fresh installs get them.
+- Final vitest + tsc validation at the end of Phase 0.
+
+## Don't
+
+- Don't push to remote during this session (user will batch the push later).
+- Don't commit `.env*` files (hook blocks them anyway).
+- Don't edit `.gitignore` to exclude generated artifacts; the repo's existing ignores are correct.
+- Don't add documentation files unless the plan asks for them — the plan itself is the doc.
+- Don't add features not in the plan. If something seems missing, ask.
+- Don't use AI for the recommender (plan §1 + §13). Pure SQL ranking.
+
+Once you've read the plan and confirmed understanding, ask me whether to proceed with Phase 0.

docs/deal-pulse-trigger-audit.md

@@ -0,0 +1,134 @@
+# Deal Pulse & Pipeline Trigger Audit — 2026-05-18
+
+Per MANUAL-TESTING-BACKLOG-2026-05-15 §4.15: map every place that
+moves an interest's pipeline stage OR contributes to the deal-pulse
+score, and call out the gaps.
+
+---
+
+## 1. Pipeline-stage auto-advance — call-site map
+
+`advanceStageIfBehind(interestId, portId, target, meta, reason?)` is
+the canonical "advance if not already past target" helper. The
+`*Gated` variant honours the per-port `stage_advance_rules` setting
+(auto / suggest / off).
+
+| Trigger                              | Caller                        | Target                                                    | File:line                               | Gated?                           |
+| ------------------------------------ | ----------------------------- | --------------------------------------------------------- | --------------------------------------- | -------------------------------- |
+| EOI sent (manual rep generate)       | `generateAndSign`             | `eoi`                                                     | `documents.service.ts:843`              | gated (eoi_sent)                 |
+| EOI signed (all parties via webhook) | `handleDocumentCompleted`     | `reservation`                                             | `documents.service.ts:1610`             | gated (eoi_signed)               |
+| Reservation signed                   | `handleDocumentCompleted`     | `reservation` (no change, stage stays + status sub-flips) | `documents.service.ts:1640`             | gated (reservation_signed)       |
+| Deposit received in full             | `recordPayment`               | `deposit_paid`                                            | `payments.service.ts:134`               | gated (deposit_received)         |
+| Sales contract signed                | `handleDocumentCompleted`     | `contract`                                                | `documents.service.ts:1671`             | gated (contract_signed)          |
+| Deposit invoice paid (alt path)      | `markInvoicePaid`             | `deposit_paid`                                            | `invoices.ts:684`                       | gated (deposit_received)         |
+| Custom document upload               | `confirmCustomDocumentUpload` | document-type-specific (eoi/reservation/contract)         | `custom-document-upload.service.ts:354` | **NOT gated** (uses base helper) |
+| External-eoi mark-as-signed          | inline in handler             | `reservation`                                             | `documents.service.ts:859`              | **NOT gated**                    |
+| Externally-signed contract           | inline in handler             | `contract`                                                | `documents.service.ts:971`              | **NOT gated**                    |
+| Manual stage move                    | `changeInterestStage`         | any (with override)                                       | `interests.service.ts:840`              | manual / not gated               |
+
+### Gaps flagged
+
+- **External-signed paths bypass the per-port rules.** A port set to
+  `suggest` for `eoi_signed` still gets an auto-advance when the rep
+  marks the doc externally signed. Decision needed: should the rules
+  table also gate the external-signed paths? Argument for yes: the
+  rep's intent ("I just want to mark this signed") is the same as
+  the webhook case. Argument for no: the rep is explicitly choosing
+  to bypass the digital flow, so an auto-advance is what they expect.
+- **Custom document upload is not gated.** Same trade-off as above.
+- **No stage rollback on rejection.** When a signer declines an EOI
+  (`handleDocumentRejected`), the doc flips to `rejected` but the
+  interest stays at `eoi`. Confirm: this is correct — the deal
+  isn't dead, the EOI is. Rep should regenerate. **Verdict: keep
+  as-is.**
+- **No stage rollback on cancel.** When the rep cancels an in-flight
+  EOI, the doc flips to `cancelled` and the interest stays at `eoi`.
+  Decision needed: should the interest roll back to `qualified`
+  when the only EOI is cancelled with no replacement?
+  **Recommendation: NO** — keeps history honest; a cancel is the
+  rep's deliberate signal that they're regenerating, not retreating.
+
+---
+
+## 2. Deal-pulse signals — `computeDealHealth` map
+
+Source: `src/lib/services/deal-health.ts`. Each `signals.push` site
+documented with its trigger condition + score delta:
+
+| Signal              | Delta                | Condition                                           | File:line          |
+| ------------------- | -------------------- | --------------------------------------------------- | ------------------ |
+| `active_engagement` | +5                   | Any contact-log entries in last 7 days              | deal-health.ts:101 |
+| `contact_recent`    | +20                  | `dateLastContact <= 7 days` ago                     | deal-health.ts:115 |
+| `contact_warm`      | +10                  | `dateLastContact <= 14 days` (else of above)        | deal-health.ts:122 |
+| `contact_stale`     | -15                  | `dateLastContact >= 30 days`                        | deal-health.ts:129 |
+| `stage_progress`    | +10/+20/+30 (capped) | Per pipelineStage index                             | deal-health.ts:142 |
+| `stuck_top_funnel`  | -10                  | `firstDays >= 30` AND stage in {enquiry, qualified} | deal-health.ts:157 |
+| `eoi_awaiting`      | -10                  | `eoiSentDays >= 14` AND not signed                  | deal-health.ts:173 |
+| `deposit_pending`   | -10                  | reservation signed >= 21d AND no deposit            | deal-health.ts:184 |
+| `contract_awaiting` | -10                  | contract sent >= 14d AND not signed                 | deal-health.ts:200 |
+
+### Positive signals that are MISSING (gaps)
+
+- **EOI sent** — no `eoi_sent_recent` signal. Sending an EOI is the
+  single biggest "this deal just got serious" moment but the score
+  doesn't move when it happens. **Recommendation: +15 at < 7 days.**
+- **Deposit received** — same gap. A deposit landing should bump the
+  score significantly. **Recommendation: +20, decays over 30 days.**
+- **Contract signed** — terminal positive event; should ladder the
+  deal to its max. **Recommendation: +30 at < 14 days.**
+
+### Negative signals that are MISSING (gaps)
+
+- **Signer declined / EOI rejected** — when the §4.13 rejection path
+  fires, the score should drop noticeably (the deal is suddenly at
+  risk). **Recommendation: -25, decays over 14 days.**
+- **Interest archived-and-unarchived cycle** — zombie deals that
+  bounce in and out should be flagged. Detect via the audit-log
+  archive/restore pattern. **Recommendation: -10 if archived+restored
+  within last 30 days.**
+- **Reservation cancelled** — similar to EOI rejected; signals the
+  deal is at risk. **Recommendation: -20.**
+- **Berth status flipped to sold-to-other** — the deal's primary
+  berth was sold to a different interest. **Recommendation: -30
+  (catastrophic).**
+- **Signer engagement** — Documenso fires `RECIPIENT_VIEWED`
+  webhooks (we store `openedAt`). A signer who opened but didn't
+  sign in 7+ days = stalling. **Recommendation: -5 per stalling
+  signer.**
+
+### Cadence escalation (currently flat)
+
+- `eoi_awaiting` and `contract_awaiting` both apply a flat -10 at
+  the 14-day threshold. **Recommendation: ladder to -20 at 21d, -30
+  at 30d** so prolonged stalling shows up more visibly.
+
+---
+
+## 3. Heat tooltip explainer copy
+
+The DealPulseChip popover (`src/components/interests/deal-pulse-chip.tsx`)
+references signals by name. With the gaps above closed, the
+tooltip's enumerated list needs the new signals added so the in-app
+copy matches the computation.
+
+The new `/docs/deal-pulse` explainer page (shipped this wave, §7.1)
+should also be kept in sync with the signal set.
+
+---
+
+## 4. Suggested fix wave (decisions needed from Matt)
+
+Per the doc structure, these are the punch-list items in priority order:
+
+1. **Ship the positive signals (eoi_sent, deposit_received, contract_signed).**
+   Biggest visible win. ~1.5h.
+2. **Ship the rejection / risk signals (eoi_rejected, reservation_cancelled, berth_sold_to_other).**
+   Pairs naturally with the §4.13 rejection cascade we shipped this
+   wave. ~2h.
+3. **Ship the cadence escalation (eoi_awaiting / contract_awaiting laddered scoring).**
+   ~30 min.
+4. **Decide on the external-signed-paths gating question.**
+5. **Decide on the cancel-stage-rollback question.**
+
+Each is small individually; combined the deal-pulse model gets meaningfully
+more accurate. Suggest bundling 1–3 into one PR for review economy.

docs/documenso-build-plan.md

@@ -0,0 +1,722 @@
+# Documenso signing-flow build plan
+
+Captures every Documenso-related piece that isn't shipped yet, in attack order. A fresh session should be able to pick this up without re-reading the whole conversation.
+
+**Companion docs:**
+
+- [docs/documenso-integration-audit.md](./documenso-integration-audit.md) — what's already built, v1/v2 endpoint mapping, nginx CORS block
+- Old system reference: [client-portal/server/api/eoi/generate-quick-eoi.ts](../client-portal/server/api/eoi/generate-quick-eoi.ts), [client-portal/server/api/webhooks/documenso.post.ts](../client-portal/server/api/webhooks/documenso.post.ts), [client-portal/server/services/documenso-notifications.ts](../client-portal/server/services/documenso-notifications.ts), [Port Nimara/Website/pages/sign/[type]/[token].vue](../../Port%20Nimara/Website/pages/sign/%5Btype%5D/%5Btoken%5D.vue)
+
+---
+
+## Locked design decisions (from user, do NOT re-ask)
+
+| Q                                 | Decision                                                                                                                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Embedded signing host             | `portnimara.com/sign/<role>/<token>` (marketing website hosts the embed page; CRM emits URLs in this format)                                                                          |
+| Initial "please sign" email       | **Per-port admin setting** `eoi_send_mode`: `auto` = send branded email immediately on generate; `manual` = generate + show URL + Send button                                         |
+| Contract / Reservation generation | **Upload-and-place-fields per deal only.** EOI is the only template-driven flow. (Resolved Q6 — template-fallback dropped.)                                                           |
+| Reminder cadence                  | **Manual by default.** Rep clicks "Send reminder" button. Per-doc opt-in for auto-reminders at upload time. (Resolved Q1)                                                             |
+| Document expiration               | **Never expire.** No `expiresAt` UI in v1. (Resolved Q2)                                                                                                                              |
+| Approver vs CC                    | **Two concepts**: `APPROVER` = real Documenso recipient that gates signing; `Completion CC` = passive recipient that only receives the signed PDF. (Resolved Q4)                      |
+| Witness                           | **First-class signer role.** Configurable per-document; full reminder/tracking flow. (Resolved Q7)                                                                                    |
+| Per-port developer label          | **Configurable** via `documenso_developer_label` / `documenso_approver_label`. (Resolved Q8 bonus)                                                                                    |
+| Multi-port template config        | All Documenso settings are per-port via `/[portSlug]/admin/documenso` (already wired)                                                                                                 |
+| Documenso API version             | Both v1 + v2 supported. Per-port config picks. v1 is prod (1.32) — primary. v2 unlocks embed + envelope                                                                               |
+| nginx CORS                        | User applies manually. Block is in [docs/documenso-integration-audit.md](./documenso-integration-audit.md). Supports multi-origin via `set $cors_origin` regex                        |
+| Signer override                   | **Hybrid** — template docs (EOI) keep template-fixed signers (per-port settings fill the slots). Custom-uploaded docs (contract, reservation) get full per-deal signer customization. |
+| Multi-berth                       | EOI keeps existing bundle support. Contract/reservation are custom-uploaded PDFs — no PDF form-fill, just Documenso signature/initials/date fields                                    |
+| Test mode                         | Reuse `EMAIL_REDIRECT_TO` env var (already redirects every outbound email + Documenso recipient)                                                                                      |
+| Regenerate handling               | Match old system: 3 retries to delete prior Documenso doc with 2-second wait. **Plus** a confirm modal: "Retain old EOI? (default no)"                                                |
+| Field placement strategy          | **Auto-detect (anchor text scanner) + manual drag-drop UI as safety net.** Auto-detect populates the initial state; rep can drag/delete/reassign before sending.                      |
+
+---
+
+## What's already shipped (foundation)
+
+Files in place; do NOT rebuild:
+
+- `src/lib/services/port-config.ts` — extended with: `documenso_developer_name/email`, `documenso_approver_name/email`, `eoi_send_mode`, `embedded_signing_host`, `documenso_contract_template_id`, `documenso_reservation_template_id`
+- `src/app/(dashboard)/[portSlug]/admin/documenso/page.tsx` — admin UI exposes every Documenso knob across 5 cards
+- `src/lib/email/templates/document-signing.ts` — `signingInvitationEmail`, `signingCompletedEmail`, `signingReminderEmail` with per-port branding
+- `src/lib/services/document-signing-emails.service.ts` — `sendSigningInvitation`, `sendSigningReminder`, `sendSigningCompleted`. Includes `transformSigningUrl(rawUrl, host, role)` for embed URL wrapping
+- `src/lib/services/documenso-client.ts` — extended `DocumensoFieldType` to all 11 types: SIGNATURE, FREE_SIGNATURE, INITIALS, DATE, EMAIL, NAME, TEXT, NUMBER, CHECKBOX, DROPDOWN, RADIO. Plus typed `DocumensoTextFieldMeta`/`NumberFieldMeta`/`ChoiceFieldMeta` interfaces and `fieldTypeNeedsMeta(type)` helper
+- `src/components/interests/interest-eoi-tab.tsx` — EOI workspace with active-doc hero, signing progress, paper-signed upload, history strip
+- `src/components/interests/interest-contract-tab.tsx` — Contract workspace shell with paper-signed upload + "send for signing" placeholder dialog
+- `src/components/interests/interest-reservation-tab.tsx` — Reservation workspace shell (clone of Contract)
+- `src/components/interests/interest-tabs.tsx` — stage-conditional visibility wired
+
+What works today end-to-end: generate EOI → Documenso template path → manual link sharing (rep copies URL out of UI). What does NOT yet work: auto-send branded invitation, cascading "your turn" emails, custom-doc upload-to-Documenso, embedded signing URL emission to the website, on-completion PDF distribution.
+
+---
+
+## Phase 1 — EOI generate flow polish (~3 hours)
+
+> **Updated for Q1, Q4, Q6, Q8 resolutions.** Adds manual-reminder endpoint, two new per-port label settings, drop of contract/reservation template settings, schema columns for completion CCs + auto-reminder. Also folds in webhook-secret hardening (Risk #7 Option A) and `transformSigningUrl` role mapping (Risk #5 fix).
+
+**Why first**: Smallest surface area, validates the per-port `eoi_send_mode` setting works end-to-end, gets the cascading-email mental model in place before tackling the bigger pieces.
+
+### Tasks
+
+1. **Auto-send wiring**: in `src/components/documents/eoi-generate-dialog.tsx`, after `handleGenerate()` succeeds:
+   - Fetch port's `eoi_send_mode` (already on `getPortDocumensoConfig(portId)`)
+   - If `auto`: server-side already sent the doc to Documenso with `sendEmail: false`. Now call new endpoint `POST /api/v1/documents/[id]/send-invitation` (build it) which:
+     - Looks up the document's signers
+     - Calls `sendSigningInvitation()` for the first signer (the client; signing order 1)
+     - Stores `sent_at` timestamp on the signer row
+   - If `manual`: do nothing. Surface the signing URL in the EOI tab + a "Send invitation" button that hits the same endpoint.
+
+2. **Regenerate confirm modal**: when EOI tab's "Generate EOI" button is clicked AND a Documenso doc already exists for this interest (`activeDoc !== null`):
+   - Show a `<Dialog>` asking: "There's already an EOI in flight. Regenerating will create a new document and the existing one will be cancelled."
+   - Two buttons: "Cancel" (default), "Regenerate" (destructive)
+   - Below the buttons, a checkbox: "Keep the previous EOI in Documenso (don't delete)" — defaults UNCHECKED
+   - On confirm: if checkbox unchecked, call `voidDocument(oldId, portId)` with 3 retries + 2-second wait between (mirror old system's `generate-quick-eoi.ts` lines 110-162). Then run the normal generate flow.
+
+3. **Send-invitation endpoint**: new file `src/app/api/v1/documents/[id]/send-invitation/route.ts`:
+
+   ```ts
+   POST /api/v1/documents/[id]/send-invitation
+   Body: { recipientId?: string }  // optional — defaults to first unsigned recipient
+   ```
+
+   - Loads the document + signers
+   - Resolves the target recipient (passed-in or first unsigned in signing order)
+   - Resolves port's documenso config + the recipient's signing URL from the document_signers row
+   - Calls `sendSigningInvitation` from the email service
+   - Updates `document_signers.invited_at` (need to add column — see schema migration below)
+
+4. **Schema migration**: add `invited_at` and `last_reminder_sent_at` columns to `document_signers`:
+   ```sql
+   ALTER TABLE document_signers ADD COLUMN invited_at timestamptz;
+   ALTER TABLE document_signers ADD COLUMN last_reminder_sent_at timestamptz;
+   ```
+   The webhook handler updates these (Phase 2). Apply via psql then restart dev server (per CLAUDE.md migration note).
+
+### Acceptance criteria
+
+- Setting `eoi_send_mode=auto` in admin → generating an EOI fires off our branded HTML email to the client immediately
+- Setting `eoi_send_mode=manual` → no email fires; "Send invitation" button in EOI tab hits the endpoint
+- Clicking Generate when an active EOI exists → confirm dialog with checkbox; default deletes prior doc with retries
+
+---
+
+## Phase 2 — Webhook handler enhancement (~3-4 hours)
+
+**Why second**: Once invitations are flowing (Phase 1), the webhook needs to track the lifecycle and fire the cascading "your turn" emails as each signer completes. Without this, the system goes silent after the initial invite.
+
+### Tasks
+
+1. **Extend `src/app/api/webhooks/documenso/route.ts`** to handle `DOCUMENT_OPENED`, `DOCUMENT_SIGNED`, `DOCUMENT_COMPLETED` (DOCUMENT_OPENED currently ignored).
+
+2. **For `DOCUMENT_SIGNED`** (fires when one recipient signs, can fire multiple times per doc):
+   - Resolve the (port, document, signer) — existing per-port secret lookup already does this
+   - Update `document_signers.signed_at` for the matching signer
+   - Find the next unsigned signer in signing order
+   - If next signer exists AND we haven't already invited them: call `sendSigningInvitation()` with the next signer + their signing URL + role='developer' (or 'approver' depending on signing order). Mark `document_signers.invited_at` for them.
+   - This is the cascading "your turn" flow that mirrors `client-portal/server/services/documenso-notifications.ts`
+
+3. **For `DOCUMENT_OPENED`**:
+   - Update `document_signers.opened_at` for the matching recipient (matched by token in payload)
+   - Used for analytics later ("12% of clients open within an hour")
+
+4. **For `DOCUMENT_COMPLETED`** (fires once when all signers have signed):
+   - Update document `status='completed'`, `completed_at=...`
+   - Download signed PDF: `await downloadSignedPdf(documensoId, portId)` (existing)
+   - Store in storage backend via the file ingestion flow — this creates a `files` row
+   - Update the document row to point at the signed file (`signed_file_id`)
+   - Call `sendSigningCompleted()` with all signers + the signed file's id
+   - Update the linked interest's pipeline stage:
+     - If document type = `eoi` → `eoi_signed`
+     - If document type = `contract` → `contract_signed`
+     - If document type = `reservation_agreement` → leave stage; reservation is post-deal-close anyway
+
+5. **Recipient-token matching**: webhooks include `payload.recipients[]` with each recipient's `token`. Use the token to match against `document_signers.signing_token` (need to add the column if not already). Old system's webhook does this via email match — fragile when the same email serves multiple roles. Token match is robust.
+
+6. **Idempotency**: webhook can fire duplicates. Old system's `acquireWebhookLock` + signature comparison pattern is good. Port that logic.
+
+### Schema migration
+
+```sql
+-- Add fine-grained tracking columns to document_signers
+ALTER TABLE document_signers ADD COLUMN invited_at timestamptz;
+ALTER TABLE document_signers ADD COLUMN opened_at timestamptz;
+ALTER TABLE document_signers ADD COLUMN last_reminder_sent_at timestamptz;
+ALTER TABLE document_signers ADD COLUMN signing_token text;  -- index this
+
+CREATE INDEX idx_ds_signing_token ON document_signers (signing_token);
+```
+
+### Acceptance criteria
+
+- Client signs → developer receives our branded "your turn" email within seconds
+- Developer signs → approver receives the same
+- All signed → all three recipients receive the signed PDF as attachment
+- Interest's pipeline stage advances to `eoi_signed` automatically
+- Re-firing of duplicate webhooks is no-op
+
+---
+
+## Phase 3 — Custom document upload-to-Documenso (~6-8 hours)
+
+**Why third**: Backend foundation for contract + reservation flows. Without this, the "Upload draft for signing" CTA on those tabs is a placeholder.
+
+### Tasks
+
+1. **New service** `src/lib/services/custom-document-upload.service.ts`:
+
+   ```ts
+   export async function uploadDocumentForSigning(args: {
+     interestId: string;
+     portId: string;
+     documentType: 'contract' | 'reservation_agreement';
+     pdfBuffer: Buffer;
+     filename: string;
+     title: string;
+     recipients: Array<{
+       name: string;
+       email: string;
+       role: 'SIGNER' | 'APPROVER' | 'CC';
+       signingOrder: number;
+     }>;
+     fields: DocumensoFieldPlacement[]; // from auto-detect or manual placement
+   }): Promise<{ documentId: string; signingUrls: Record<string, string> }>;
+   ```
+
+   Steps:
+   - Convert pdfBuffer → base64
+   - Call `createDocument(title, base64, recipients, portId)` — existing client function
+   - Call `placeFields(docId, fields, portId)` — existing client function (handles v1 + v2)
+   - Call `sendDocument(docId, portId)` — existing
+   - Return doc ID + per-recipient signing URLs
+   - Mirror the timing-safe URL extraction from old system's generate-quick-eoi (recipients[].signingUrl)
+   - Insert a row into our `documents` table with the new doc_id + signers + interest link
+   - If port's `eoi_send_mode === 'auto'`: kick off `sendSigningInvitation()` to first signer
+
+2. **API endpoint**: `POST /api/v1/interests/[id]/upload-for-signing`
+   - Accepts multipart: `file` (the PDF), `documentType`, `title`, `recipients` (JSON), `fields` (JSON)
+   - Validates: file is PDF (magic-byte check, see berth-pdf flow), recipients ≥ 1, fields ≥ 1
+   - Calls service
+   - Returns 201 with the new document row
+
+3. **Update Contract + Reservation tab placeholders** to open a real upload dialog (see Phase 4).
+
+### Acceptance criteria
+
+- Endpoint accepts a PDF + recipients + fields and returns a Documenso doc ID
+- Document appears in the Documents tab with status `sent`
+- v1 and v2 paths both work (same code path; client chooses based on per-port config)
+
+---
+
+## Phase 4 — Recipient configurator + Field placement UI (~10-14 hours)
+
+**Why fourth**: This is the BIG visual piece. Don't start until Phase 3 backend is proven via curl.
+
+### Sub-phase 4a: Recipient configurator (~2-3 hours)
+
+UI inside a new `<UploadForSigningDialog>` component:
+
+- File picker (drag-drop + click)
+- Title input (defaults to filename minus extension)
+- Recipients list:
+  - Add row → name + email + role (SIGNER/APPROVER/CC) + signing order (number, auto-increments)
+  - Drag to reorder (uses `dnd-kit`, already in deps)
+  - Delete row
+  - Defaults: client (signing order 1) prefilled from interest's linked client; developer + approver prefilled from port settings
+- "Configure fields →" button advances to sub-phase 4b
+
+### Sub-phase 4b: PDF rendering (~3-4 hours)
+
+- Install: `pnpm add react-pdf` (uses pdfjs-dist under the hood; pdfme already pulls pdfjs-dist so no new dep weight)
+- Render the uploaded PDF page-by-page using `<Document>` + `<Page>` from react-pdf
+- Page navigation (prev/next, page picker)
+- Zoom controls (50%, 75%, 100%, 125%, 150%)
+
+### Sub-phase 4c: Auto-detect scanner (~4-6 hours)
+
+New file `src/lib/services/document-field-detector.ts`:
+
+```ts
+export interface DetectedField {
+  type: DocumensoFieldType;
+  pageNumber: number;
+  pageX: number; // 0-100 percent
+  pageY: number;
+  pageWidth: number;
+  pageHeight: number;
+  /** Confidence 0-1 — how sure the scanner is. */
+  confidence: number;
+  /** Original anchor text (for debugging / display). */
+  anchorText?: string;
+  /** Inferred recipient (from nearby labels). null = unassigned. */
+  inferredRecipientLabel?: string | null;
+}
+
+export async function detectFields(pdfBuffer: Buffer): Promise<DetectedField[]>;
+```
+
+Implementation:
+
+- Use `pdfjs-dist` to extract text per page with `getTextContent()` — gives `{str, transform: [a,b,c,d,e,f]}` per text item where `e,f` is position in PDF user space, plus `width/height`
+- Anchor patterns:
+  - `SIGNATURE`: `/signature[:\s_-]+/i`, `/sign\s*here[:\s_-]*/i`, `/X\s*_{4,}/i`, `/signed\s*by[:\s]+/i`
+  - `INITIALS`: `/initials?[:\s_-]+/i`
+  - `DATE`: `/dated?[:\s_-]+/i`, `/date\s+of\s+signature/i`
+  - `NAME`: `/(printed?\s*)?name[:\s_-]+/i`, `/full\s+name[:\s_-]+/i`
+  - `EMAIL`: `/email[:\s_-]+/i`
+  - Catch-all: `/_{8,}/` → if not preceded by name/email/date keyword, default to TEXT
+- For each match: place field bounding box immediately AFTER the matched text (offset 5pt right), with type-appropriate width:
+  - SIGNATURE: 150pt × 30pt
+  - INITIALS: 50pt × 30pt
+  - DATE: 80pt × 20pt
+  - NAME: 150pt × 20pt
+  - EMAIL: 200pt × 20pt
+  - TEXT: 200pt × 20pt
+- Convert to PERCENT (divide by page width/height)
+- Recipient inference: scan ±100pt of the field for labels like "Buyer", "Seller", "Client", "Developer", "Witness", "Notary". Map to recipient by role.
+
+### Sub-phase 4d: Drag-drop overlay (~3-4 hours)
+
+- Overlay absolute-positioned divs on top of the PDF viewer for each field
+- Each field shows: type icon + recipient color + delete (×) handle + drag affordance
+- Use `dnd-kit` to enable drag — update `pageX/pageY` in state on drop
+- Field palette toolbar: 11 buttons (one per Documenso field type) — click to enter "place mode" → next click on the PDF places a new field at that coord
+- Side panel for selected field:
+  - Type changer (dropdown)
+  - Recipient assignment (dropdown of configured recipients)
+  - Required toggle
+  - Per-type config (TEXT label, NUMBER min/max, CHECKBOX/DROPDOWN/RADIO options) — drives `fieldMeta`
+  - Width/height inputs
+  - Delete button
+
+### Sub-phase 4e: Send (~1 hour)
+
+"Send for signing" button:
+
+- Validates: ≥1 recipient, ≥1 field, every field has a recipient assigned
+- POSTs to `/api/v1/interests/[id]/upload-for-signing` (Phase 3)
+- On success, closes dialog and refreshes the Contract/Reservation tab
+
+### Acceptance criteria
+
+- Upload a draft PDF → auto-detect runs → fields appear overlaid in their detected positions
+- Rep can drag any field to reposition (state updates, persists to backend on send)
+- Rep can change a field's type, recipient, or metadata via side panel
+- Rep can add new fields by clicking palette button + clicking on PDF
+- Rep can delete fields they don't want
+- Click Send → fields ship to Documenso, signing flow starts, Contract tab shows the active doc
+
+---
+
+## Phase 5 — Embedded signing URL emission verification (~1-2 hours)
+
+**Why later**: The Vue page on the marketing website already exists. This phase is a verification + documentation pass, not a code build.
+
+### Tasks
+
+1. **Verify URL transformation matches website expectations**:
+   - Website route: `/sign/[type]/[token]` where `type ∈ {client, cc, developer}`
+   - Our `transformSigningUrl()` emits `/sign/<role>/<token>` where role can be `client | developer | approver | witness | other`
+   - Mismatch: website only handles `client | cc | developer`. Our email service may emit `approver` (which the website doesn't route).
+   - **Fix**: either (a) update website's `[type].vue` to accept `approver` (and `witness | other` if needed), OR (b) map our role names to the website's expected names in `transformSigningUrl()`.
+
+2. **For contract + reservation document types**: the website's `signerMessages` map only covers EOI-specific copy. When a contract goes out for signing and the recipient hits `portnimara.com/sign/client/<token>`, the page would show "Sign Your Expression of Interest" — wrong copy.
+   - **Fix**: add document-type to the URL too: `/sign/<docType>/<role>/<token>`. Update website's signerMessages to be keyed on `(docType, role)`.
+
+3. **Webhook callback URL**: website POSTs to `client-portal.portnimara.com/api/webhook/document-signed` after signing. The new CRM is at a different domain. Update website's `handleDocumentSigned` to POST to the new CRM's webhook (a thin "client confirmed sign" notification, separate from Documenso's own webhook).
+
+4. **Apply nginx CORS block** — already documented in [docs/documenso-integration-audit.md](./documenso-integration-audit.md). Apply via ssh when user grants access.
+
+### Acceptance criteria
+
+- Embedded URL points at a working website page that loads the right Documenso embed for any document type / role combo
+- Post-sign callback updates our document_signers row (redundant with the Documenso webhook but useful as a real-time UI signal)
+
+---
+
+## Phase 6 — Polish & deferred items (~2-3 hours each, do as needed)
+
+- **`auto` send mode delay**: optional per-port `eoi_send_delay_minutes` setting. When set, the auto-send fires after N minutes (BullMQ scheduled job) so the rep can review + cancel during the window. Default 0 (immediate).
+- **Audit log entries**: every Documenso-related action (generate, send, remind, cancel, sign-event-received) writes to `audit_logs` with structured metadata. Mostly already there for the existing flow; extend to cover Phase 1-3 additions.
+- **Per-document customization of email copy**: rep can override the default signing-invitation body before send. New textarea in the upload dialog. Stored as `documents.invitation_message`.
+- **Document expiration**: Documenso supports `expiresAt`. Surface as a per-document field in the upload dialog.
+- **Reminder rate-limit display**: surface "next reminder available in X days" on each unsigned signer in the signing-progress UI.
+- **Failed-webhook recovery UI**: admin page showing webhooks that errored, with a "Replay" button. Old system has the foundation; CRM doesn't.
+
+---
+
+## Phase 7 — Project Director role + RBAC layer (~6-8 hours)
+
+> **Surfaced from Q8 conversation.** The `developer` signer slot is conceptually the "Project Director" — the person at the port who countersigns deals on behalf of the port. Today every CRM user is either a sales rep or admin; there's no Project Director user role. Attack alongside the Documenso build because (a) the Documenso developer-label setting is meaningless if no user actually has the role, and (b) a few permissions naturally cluster around it.
+
+### What a Project Director needs (vs sales rep)
+
+| Capability                                               | Sales rep | Project Director | Admin                         |
+| -------------------------------------------------------- | --------- | ---------------- | ----------------------------- |
+| Generate EOI / contract / reservation                    | ✓         | ✓                | ✓                             |
+| Approve / sign as the "developer" recipient on Documenso | —         | ✓                | — (unless also designated PD) |
+| View own deals                                           | ✓         | ✓                | ✓                             |
+| View other reps' deals                                   | —         | ✓                | ✓                             |
+| View audit logs (read-only)                              | —         | ✓                | ✓                             |
+| Trigger CSV / report exports                             | —         | ✓                | ✓                             |
+| Re-assign deals between reps                             | —         | ✓                | ✓                             |
+| Edit per-port settings                                   | —         | —                | ✓                             |
+| Manage users + invitations                               | —         | —                | ✓                             |
+| Manage Documenso config                                  | —         | —                | ✓                             |
+
+So Project Director sits between sales rep and admin: read-everywhere + a few action capabilities (re-assign, export, sign-as-PD), but no settings/user management.
+
+### Tasks
+
+1. **Add `project_director` to the role enum** in `src/lib/db/schema/users.ts` (or wherever port_roles enum lives). Existing role values (sales, admin, super_admin) stay; this is additive.
+
+2. **Permission flags**: extend the per-port permissions matrix (`src/lib/auth/permissions.ts` or equivalent) with new flags:
+   - `viewAllDeals` — true for project_director, admin, super_admin
+   - `viewAuditLogs` — true for project_director, admin, super_admin
+   - `exportReports` — true for project_director, admin, super_admin
+   - `reassignDeals` — true for project_director, admin, super_admin
+   - `signAsProjectDirector` — true for project_director only (admin can sign as PD only if also assigned the role on this port)
+
+   These flags get checked in the relevant API handlers via the existing `withPermission()` middleware.
+
+3. **Documenso developer-slot binding**: per-port admin UI gets a "Project Director user" dropdown alongside the existing developer-name/email free-text inputs. When a real CRM user is selected, the admin UI:
+   - Populates `documenso_developer_name/email` from the user's profile (read-only when bound)
+   - When that user signs an EOI/contract via Documenso, the webhook handler can match by user-email and update the in-CRM signing UI in real time (signer chip turns green for them specifically)
+   - Free-text fallback stays for ports without a CRM-PD user yet
+
+4. **User invitations + role selection**: extend `src/components/admin/invite-user-dialog.tsx` to surface "Project Director" alongside Sales / Admin as a selectable role at invitation time.
+
+5. **Audit-log access**: surface a new `/[portSlug]/admin/audit-log` route (or extend the existing one's permission gate) so Project Directors can read but not write. Hide write controls for non-admins.
+
+6. **Reports page permission gate**: existing `/[portSlug]/reports` (or wherever exports live) checks `exportReports` permission flag instead of admin-only.
+
+7. **Re-assign deals UI**: add a "Re-assign owner" action on the interest detail page, gated by `reassignDeals`. Writes to `interests.owner_user_id` (or whatever the assigned-rep field is) and audit-logs the change.
+
+### Schema migration
+
+```sql
+-- Add project_director as a valid role; depends on how roles are stored.
+-- If port_roles uses an enum:
+ALTER TYPE port_role ADD VALUE 'project_director';
+-- Or if it's a text column with check constraint:
+ALTER TABLE port_roles DROP CONSTRAINT port_roles_role_check;
+ALTER TABLE port_roles ADD CONSTRAINT port_roles_role_check
+  CHECK (role IN ('sales', 'admin', 'super_admin', 'project_director'));
+
+-- Optional: link the per-port Documenso developer slot to a real user
+ALTER TABLE system_settings ADD COLUMN IF NOT EXISTS user_id text REFERENCES users(id) ON DELETE SET NULL;
+-- (Used for the documenso_developer_user_id setting; null for free-text fallback)
+```
+
+### Acceptance criteria
+
+- A user invited as `project_director` can view all deals across the port (not just their own), read audit logs, trigger exports, and re-assign deals — but cannot edit settings or invite users
+- Admin can bind a CRM user to the per-port Documenso developer slot; the user's name + email auto-populate in invitations and emails
+- Non-PD users cannot trigger PD-only actions (server returns 403; UI hides the controls)
+- Existing sales / admin / super_admin permissions are unchanged
+
+### Why attack at the same time as the Documenso build
+
+- Both touch `port-config.ts` and `admin/documenso/page.tsx` — fewer rebases if done in one push
+- The `documenso_developer_label` setting (Q8 bonus) and the PD-user binding overlap; doing them together avoids re-touching the same admin card twice
+- The Documenso webhook's per-signer matching benefits from having a real `users.email` to bind against, not just a free-text developer name
+
+### Out of scope (defer to a later RBAC pass)
+
+- Custom permission templates (e.g. "PD with no audit-log access")
+- Per-deal ACLs (sharing a single interest with another rep)
+- Time-bound role grants
+- Cross-port role overrides for super_admin
+
+---
+
+## Risks + decisions (resolved through code review)
+
+Each entry below was checked against the current code. The original "open question" form is preserved in italics for traceability; the **Decision** is what the next session should implement.
+
+---
+
+### 1. `fieldMeta` on Documenso v1.32
+
+_Q: Does v1.32 silently ignore unknown properties, or does it reject the request?_
+
+**Decision: not a risk in current code.** [src/lib/services/documenso-client.ts:491-501](../src/lib/services/documenso-client.ts#L491) shows the v1 path constructs its own body containing only `recipientId, type, pageNumber, pageX/Y/Width/Height` — `fieldMeta` is never sent on v1. The code comment at [line 341-344](../src/lib/services/documenso-client.ts#L341) is misleading — update it. Action for next session: change the comment to "v1 does not receive `fieldMeta` (we never send it). v1 renders TEXT/NUMBER/CHECKBOX/DROPDOWN/RADIO as blank inputs; if the per-port admin chose v1 the field UI should warn 'Configurable field types require Documenso v2'." The placement UI in Phase 4d should disable the meta-config side panel when the resolved port is on v1.
+
+### 2. PDF dimension extraction (non-A4 contracts)
+
+_Q: How do we get real page dimensions on the v1 path?_
+
+**Decision: parse the PDF with pdf-lib in the upload service before calling `placeFields()`.** pdf-lib is already a transitive dep via the EOI form-fill flow ([src/lib/pdf/fill-eoi-form.ts](../src/lib/pdf/fill-eoi-form.ts)). Concrete change for Phase 3:
+
+```ts
+// In src/lib/services/custom-document-upload.service.ts
+import { PDFDocument } from 'pdf-lib';
+const pdfDoc = await PDFDocument.load(pdfBuffer);
+const pageDims = pdfDoc.getPages().map((p) => {
+  const { width, height } = p.getSize();
+  return { width, height };
+});
+// Pass to placeFields as a per-page dimension map override
+```
+
+Then extend `placeFields` signature to accept an optional `pageDimensionsOverride?: DocumensoPageDimensions[]` (one entry per page). When provided, the v1 path uses `pageDimensionsOverride[fieldPageIndex]` instead of [`getPageDimensions()`'s A4 default](../src/lib/services/documenso-client.ts#L427). Falls back to A4 when override is missing — keeps the EOI template path (which IS A4) unchanged.
+
+### 3. Multi-page signature blocks not picked up by auto-detect
+
+_Q: What's the recovery path if the scanner misses a signature block on the last page?_
+
+**Decision: not a risk — by design.** Phase 4d's drag-drop overlay + field palette is the explicit fallback. Auto-detect populates initial state; rep MUST be able to add fields manually. The acceptance criterion at the end of Phase 4 already covers this. Demoted from "risk" to "design note": every page must be reachable in the PDF viewer (Phase 4b's page navigation) and the field palette must be enabled even on auto-detected pages.
+
+### 4. Webhook payload differences v1 vs v2
+
+_Q: Does our webhook handler decode both v1 and v2 payload shapes correctly?_
+
+**Decision: partially confirmed; finish the audit in Phase 2.** Confirmed working today:
+
+- Secret transport: identical (`X-Documenso-Secret` plaintext) — see [route.ts:53](../src/app/api/webhooks/documenso/route.ts#L53)
+- Event names: both versions send the uppercase Prisma enum (`DOCUMENT_SIGNED`); CLAUDE.md note documents this. The route also normalizes lowercase-dotted variants for forward-compat.
+- Top-level shape `{ event, payload: { id, ... } }`: same on both versions
+
+Still unverified (defer to Phase 2 implementation):
+
+- v2 may rename `payload.id` → `payload.documentId` and `recipient.id` → `recipient.recipientId` (mirrors the API-response rename — see [src/lib/services/documenso-client.ts](../src/lib/services/documenso-client.ts) `normalizeDocument()`). Apply the same dual-field read pattern in the webhook handler: `const docId = payload.documentId ?? payload.id`.
+- v2 may include `payload.envelopeId` instead of `payload.id` for envelope-level events (DOCUMENT_COMPLETED). Read both.
+- Recipient token field: v1 uses `recipient.token`; v2 may differ. Phase 2's token-based matching (step 5) needs to handle both.
+
+Test with a v2 instance during Phase 2; until then keep the per-port API version setting on v1 only.
+
+### 5. `approver` role → `cc` URL mapping
+
+_Q: How do we keep the website's signing page (which only routes `client | cc | developer`) working when our `SignerRole` includes `approver | witness | other`?_
+
+**Decision: confirmed bug in current code; fix in Phase 5.** [Website route validation](../../Port%20Nimara/Website/pages/sign/%5Btype%5D/%5Btoken%5D.vue#L175) explicitly redirects to `/sign/error` for any `signerType` not in `['client', 'cc', 'developer']`. Our [transformSigningUrl()](../src/lib/services/document-signing-emails.service.ts#L106) emits `${host}/sign/${signerRole}/${token}` with the raw `SignerRole` value. Today, an `approver` invite would land on `/sign/error`.
+
+Concrete fix in `transformSigningUrl()`:
+
+```ts
+const ROLE_TO_URL_SEGMENT: Record<SignerRole, 'client' | 'cc' | 'developer'> = {
+  client: 'client',
+  developer: 'developer',
+  approver: 'cc', // legacy: approver showed as "EmbeddedSignatureLinkCC"
+  witness: 'cc', // route through cc page; copy needs a witness override (Phase 5)
+  other: 'cc',
+};
+const urlRole = ROLE_TO_URL_SEGMENT[signerRole];
+return `${host}/sign/${urlRole}/${token}`;
+```
+
+Two follow-ups for Phase 5:
+
+- Add the mapping above to `transformSigningUrl()` — DO this in Phase 1 already since Phase 1 fires the first invitation email.
+- Update website's `signerMessages` (currently EOI-specific) to be keyed on `(documentType, signerType)` so contract+reservation invites get the right copy — see Phase 5 task 2.
+
+### 6. Storage backend for signed PDFs
+
+_Q: Does the on-completion download in Phase 2 use the pluggable storage backend?_
+
+**Decision: confirmed — pattern already established, just follow it.** [`getStorageBackend()`](../src/lib/storage/index.ts) is used by 9 services in the codebase (berth-pdf, brochures, expense-pdf, invoices, gdpr-export, reports, document-templates, document-sends, email-compose). The [`documents` schema](../src/lib/db/schema/documents.ts) already has the `signedFileId` column with index `idx_docs_signed_file_id`. Phase 2 step 4 is just: `const buffer = await downloadSignedPdf(docId, portId); const file = await ingestFile({ buffer, portId, ... }); await db.update(documents).set({ signedFileId: file.id })...`. Demoted from "risk" to "implementation note" inside Phase 2.
+
+### 7. Cross-port webhook secret collision
+
+_Q: Can two ports happen to share the same webhook secret?_
+
+**Decision: real risk — fix at write-time, not schema.** [system_settings](../src/lib/db/schema/system.ts#L137) is unique on `(key, port_id)`, so the same key+port combo is enforced unique, but there's no global uniqueness on the _value_. The [webhook handler](../src/app/api/webhooks/documenso/route.ts#L62) iterates all configured secrets and breaks on first match — if two ports paste the same secret, the second port's webhooks get attributed to the first. Three options, in preference order:
+
+**Option A (recommended): generate, never paste.** Replace the textbox in [admin/documenso/page.tsx](<../src/app/(dashboard)/[portSlug]/admin/documenso/page.tsx>) for `documenso_webhook_secret` with a "Generate secret" button that calls `crypto.randomBytes(32).toString('base64url')` server-side and writes it. Display once, mask after. Collision probability is negligible. Admin still has a "Regenerate" button for rotation.
+
+**Option B: warn at write.** Keep the textbox but on PUT to the setting, query `system_settings WHERE key='documenso_webhook_secret' AND value=?` and fail with a 409 if any other port has this value. Cheap, defensive, but exposes that a value exists somewhere.
+
+**Option C: schema-level enforcement.** Add a partial unique index `CREATE UNIQUE INDEX system_settings_documenso_secret_unique ON system_settings (value) WHERE key = 'documenso_webhook_secret'`. Strongest, but requires careful ordering during port-clone or restore-from-backup operations.
+
+Pick Option A. Add to Phase 1 as a polish item — small change, eliminates the risk class.
+
+---
+
+## Open questions — RESOLVED 2026-05-07
+
+All 10 questions plus the bonus role-label question have user-locked answers. Implementation must follow these decisions; do not re-litigate.
+
+### Q1. Reminder cadence — RESOLVED
+
+**Decision**: **Manual reminders by default.** Rep clicks a "Send reminder" button in the EOI/Contract tab. Per-document opt-in: rep can configure auto-reminders on a specific doc at send time (e.g. "remind every 7 days until signed").
+
+**Implications**:
+
+- No port-wide reminder schedule setting needed.
+- Phase 1 / 2: skip the BullMQ scheduled-reminder job for now. Add a `POST /api/v1/documents/[id]/send-reminder` endpoint that calls `sendSigningReminder()` for the next-pending signer. Track `last_reminder_sent_at` to enforce Documenso's 24h rate limit on the UI ("Next reminder available in X").
+- Phase 4a (upload dialog): add an optional "Auto-reminder schedule" field — None (default) / Every 3d / Every 7d. When set, store on `documents.auto_reminder_interval_days`; a once-daily worker iterates unsigned documents and fires due reminders.
+
+### Q2. Document expiration — RESOLVED
+
+**Decision**: **Never expire by default.** No expiration UI in v1. Skip Documenso's `expiresAt` entirely.
+
+**Reasoning**: link expiration doesn't help the regenerate flow (regen already voids+recreates). Adding the UI is overhead with no immediate user benefit.
+
+**Implications**:
+
+- Phase 3 `uploadDocumentForSigning`: don't expose `expiresAt`.
+- Phase 4a recipient configurator: no expiration field.
+- Phase 6 deferred-items list: drop the "Document expiration" item.
+
+### Q3. Auto-detect confidence threshold — RESOLVED
+
+**Decision**: **Default ≥0.8 silent / 0.5–0.8 flagged / <0.5 drop**, with the drag-drop overlay (Phase 4d) as the universal fix mechanism — rep can reposition or delete any auto-placed field.
+
+**Implications**:
+
+- Phase 4c scanner: emit `DetectedField.confidence`; threshold checks live in the UI layer (Phase 4d) so they're easy to tune.
+- Phase 4d overlay: flagged fields render with a yellow border + "?" badge; rep can click to confirm-as-correct (clears the badge) or drag/delete.
+
+### Q4. Approver semantics — RESOLVED
+
+**Decision**: **TWO concepts, not one.**
+
+1. **APPROVER** = real Documenso `APPROVER` recipient. Gates signing flow (e.g. client signs → approver approves → developer signs). Configured per-port (existing `documenso_approver_name/email` settings).
+2. **Completion CC** = passive recipient. Does NOT participate in signing. Receives only the final signed PDF as attachment when the doc completes. Set per-document by the rep at send time.
+
+**Implications**:
+
+- Phase 3 `uploadDocumentForSigning` recipients: support `role: 'SIGNER' | 'APPROVER' | 'CC'`. CCs are NOT created as Documenso recipients — they're stored on `documents.completion_cc_emails` (text array) and emailed by our own service when DOCUMENT_COMPLETED webhook fires.
+- Phase 4a recipient configurator: split into two sections:
+  - **Signing recipients**: name + email + role (Signer / Approver) + signing order
+  - **Copy on completion** (CC): just email addresses, comma-separated
+- Phase 2 step 4 (on-completion email distribution): include `documents.completion_cc_emails` recipients with the signed PDF. Dedup by email (see Q5).
+- Schema migration: `ALTER TABLE documents ADD COLUMN completion_cc_emails text[] DEFAULT '{}'::text[];`
+
+### Q5. On-completion PDF distribution — RESOLVED
+
+**Decision**: **All signing recipients + rep who generated + per-deal CC**, deduplicated by email address.
+
+**Implications**:
+
+- Phase 2 step 4: build the recipient list as union of (a) all `document_signers` for this doc, (b) the user who created the doc (`documents.createdBy` → `users.email`), (c) `documents.completion_cc_emails`. Lowercase + dedupe before calling `sendSigningCompleted`.
+- Common case (rep IS the approver): one email, not two.
+- Per-port distribution list (originally proposed) is NOT needed — the per-deal CC field covers it. If a port wants `legal@portnimara.com` on every deal, the rep types it once per doc; if it's truly always-on, add a port-default later (deferred to Phase 6).
+
+### Q6. `documenso_contract_template_id` / `documenso_reservation_template_id` — RESOLVED
+
+**Decision**: **DROP both settings. EOI is the only template-driven flow.** Contracts and reservations are custom-uploaded per deal — no template fallback.
+
+**Implications**:
+
+- Remove `documenso_contract_template_id` and `documenso_reservation_template_id` from `port-config.ts` `SETTING_KEYS` and `PortDocumensoConfig` type.
+- Remove the corresponding fields from `admin/documenso/page.tsx`. Card title becomes "Templates" with just the EOI template ID field.
+- Phase 3: contract/reservation tabs go straight into the upload dialog — no `if (templateId) { ... }` branch.
+- Locked design decisions table at top of this doc: update the "Contract / Reservation generation" row to remove the template-fallback option.
+
+### Q7. Witness role — RESOLVED
+
+**Decision**: **First-class. Configurable per-document at generation time.** Witness goes through the full invitation/reminder/tracking flow same as any other signer; signs the document attesting to having witnessed.
+
+**Implications**:
+
+- Keep `witness` in `SignerRole`.
+- Phase 4a recipient configurator: "Witness" is a selectable role in the role dropdown (alongside Signer / Approver / CC).
+- Phase 5 website edit: add witness copy to `signerMessages` map ("Witness this signing of…"). Add `witness` to the validated role list at line 175 of `[type]/[token].vue` — currently `['client', 'cc', 'developer']`, becomes `['client', 'cc', 'developer', 'witness']`.
+- Risk #5 mapping in `transformSigningUrl()`: `witness → 'witness'` (NOT mapped to `cc`). Update the role-to-URL-segment table accordingly.
+- Witness gets the same reminder/auto-reminder support as any signer — no special-casing.
+
+### Q8. Multiple developers/approvers per port — RESOLVED (with rename)
+
+**Decision**: **Stay single per port** for the standard `developer` and `approver` slots. If a port needs more on a custom doc, the rep adds extra signers via the upload-for-signing dialog (Phase 4a recipient configurator).
+
+**Plus the bonus**: the per-port "developer" label IS configurable via a new `documenso_developer_label` setting (default: "Developer"). Used in email subjects, signer chips, and signing-progress UI. Backend type-name stays `developer` so no schema churn.
+
+**Implications**:
+
+- Add `documenso_developer_label` and `documenso_approver_label` to `SETTING_KEYS` + `PortDocumensoConfig`.
+- Admin UI in `documenso/page.tsx` Signers card: each signer card gets a "Display label" input next to name/email.
+- Email templates in `document-signing.ts`: read the label from the per-port branding config and use it in copy ("Your Project Director, {{name}}, has signed…").
+- **Open follow-up (out of scope for Documenso build)**: the user mentioned the project-director user MIGHT need different CRM permissions/access from a sales rep (e.g. exclusive audit-log access, more prominent reports). That's a separate RBAC initiative — note it on the audit backlog and don't action here.
+
+### Q9. Field placement draft persistence — RESOLVED
+
+**Decision**: **No persistence.** If the rep closes the dialog mid-placement, state is lost.
+
+**Implications**:
+
+- Phase 4 architecture: keep all placement state in React component state. No localStorage, no DB drafts table.
+- Add a confirm-close on the dialog if the rep has placed any fields ("Discard placement work?").
+
+### Q10. Embedded signing host fallback — RESOLVED
+
+**Decision**: **Send raw Documenso URLs** when host is unset. The Documenso API already returns a working signing URL per recipient (e.g. `https://signatures.portnimara.dev/sign/<token>`); `transformSigningUrl()` returns this raw URL untouched when `embeddedSigningHost` is null/empty (current behaviour, see [document-signing-emails.service.ts:106-117](../src/lib/services/document-signing-emails.service.ts#L106)).
+
+**Implications**:
+
+- Phase 1: no behaviour change in `transformSigningUrl()`. The current null-host short-circuit IS the fallback.
+- Add a banner in the EOI/Contract tab when port has unset `embedded_signing_host` and at least one outstanding doc: "Signing emails currently link to signatures.portnimara.dev directly. Configure an embedded host in admin for branded signing pages."
+- No new env var. No blocking-on-send.
+
+---
+
+## Schema migration summary (resolved)
+
+Combining all resolved decisions, the migrations needed are:
+
+```sql
+-- Phase 1 (also covers Phase 2's lifecycle tracking)
+ALTER TABLE document_signers ADD COLUMN invited_at timestamptz;
+ALTER TABLE document_signers ADD COLUMN opened_at timestamptz;
+ALTER TABLE document_signers ADD COLUMN last_reminder_sent_at timestamptz;
+ALTER TABLE document_signers ADD COLUMN signing_token text;
+CREATE INDEX idx_ds_signing_token ON document_signers (signing_token);
+
+-- Phase 1 / Q4 (completion CCs are per-document)
+ALTER TABLE documents ADD COLUMN completion_cc_emails text[] DEFAULT '{}'::text[];
+
+-- Phase 1 / Q1 (auto-reminder opt-in per document)
+ALTER TABLE documents ADD COLUMN auto_reminder_interval_days integer;
+```
+
+## Settings to add / remove (resolved)
+
+**Add to `SETTING_KEYS` + `PortDocumensoConfig`:**
+
+- `documenso_developer_label` (text, default "Developer") — Q8 bonus
+- `documenso_approver_label` (text, default "Approver") — Q8 bonus
+
+**Remove from `SETTING_KEYS` + `PortDocumensoConfig`:**
+
+- `documenso_contract_template_id` — Q6
+- `documenso_reservation_template_id` — Q6
+
+**Remove from admin UI** (`admin/documenso/page.tsx`):
+
+- Contract template ID input — Q6
+- Reservation template ID input — Q6
+
+**Add to admin UI:**
+
+- Display-label inputs next to developer + approver name/email pairs — Q8 bonus
+
+---
+
+**Status**: Plan is now fully resolved. Phase 1 can start without further clarification.
+
+---
+
+## Quick file reference
+
+**Existing — modify in place:**
+
+- `src/lib/services/documenso-client.ts` (extend createDocument for v2; add recipient management functions)
+- `src/lib/services/port-config.ts` (no changes expected)
+- `src/lib/email/index.ts` (consider: add raw-Buffer attachment option to skip MinIO round-trip for one-off PDFs)
+- `src/app/api/webhooks/documenso/route.ts` (Phase 2 — major rewrite)
+- `src/components/interests/interest-contract-tab.tsx` (replace ComingSoonDialog with UploadForSigningDialog in Phase 4)
+- `src/components/interests/interest-reservation-tab.tsx` (same)
+- `src/components/documents/eoi-generate-dialog.tsx` (Phase 1 — add regenerate confirm)
+
+**New files to create:**
+
+- `src/lib/services/custom-document-upload.service.ts` (Phase 3)
+- `src/lib/services/document-field-detector.ts` (Phase 4c)
+- `src/components/documents/upload-for-signing-dialog.tsx` (Phase 4)
+- `src/components/documents/pdf-field-canvas.tsx` (Phase 4b/4d)
+- `src/components/documents/recipient-configurator.tsx` (Phase 4a)
+- `src/components/documents/field-palette-toolbar.tsx` (Phase 4d)
+- `src/components/documents/field-config-side-panel.tsx` (Phase 4d)
+- `src/app/api/v1/documents/[id]/send-invitation/route.ts` (Phase 1)
+- `src/app/api/v1/interests/[id]/upload-for-signing/route.ts` (Phase 3)
+- DB migrations for `document_signers.invited_at` etc. (Phase 1, Phase 2)

docs/documenso-integration-audit.md

@@ -0,0 +1,252 @@
+# Documenso integration audit
+
+Reference for the multi-port Documenso signing pipeline in this CRM. Mirrors the legacy client portal's flow ([generate-quick-eoi.ts](../client-portal/server/api/eoi/generate-quick-eoi.ts), [documeso.ts](../client-portal/server/utils/documeso.ts), [documenso.post.ts](../client-portal/server/api/webhooks/documenso.post.ts), [website /sign/[type]/[token].vue](../../Port%20Nimara/Website/pages/sign/%5Btype%5D/%5Btoken%5D.vue)) but rewired for multi-tenant + better-auth + Drizzle.
+
+---
+
+## Per-port configuration
+
+All Documenso settings live in `system_settings` keyed by `(key, port_id)` and are read via [`getPortDocumensoConfig(portId)`](../src/lib/services/port-config.ts). Falls back to env vars when no per-port row exists. Surfaced in the admin UI at `/[portSlug]/admin/documenso`.
+
+| Setting key                         | Type                              | Purpose                                                                             |
+| ----------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------- |
+| `documenso_api_url_override`        | string                            | Per-port Documenso instance URL. Falls back to `DOCUMENSO_API_URL` env.             |
+| `documenso_api_key_override`        | string                            | API key. Stored plaintext.                                                          |
+| `documenso_api_version_override`    | `'v1' \| 'v2'`                    | Different ports may run different Documenso versions.                               |
+| `documenso_eoi_template_id`         | int                               | Template ID for EOI generation.                                                     |
+| `documenso_client_recipient_id`     | int                               | Template recipient slot — client (signing order 1).                                 |
+| `documenso_developer_recipient_id`  | int                               | Template recipient slot — developer (signing order 2).                              |
+| `documenso_approval_recipient_id`   | int                               | Template recipient slot — approver (signing order 3).                               |
+| `documenso_developer_name`          | string                            | Display name for developer signer (legacy hardcoded "David Mizrahi").               |
+| `documenso_developer_email`         | string                            | Developer signer email.                                                             |
+| `documenso_approver_name`           | string                            | Approver display name.                                                              |
+| `documenso_approver_email`          | string                            | Approver email.                                                                     |
+| `documenso_webhook_secret`          | string                            | Per-port webhook secret. Receiver tries each enabled secret with timing-safe equal. |
+| `eoi_default_pathway`               | `'documenso-template' \| 'inapp'` | Which path is used when EOI is generated without explicit choice.                   |
+| `eoi_send_mode`                     | `'auto' \| 'manual'`              | Auto = send branded invitation email immediately; manual = rep clicks Send.         |
+| `embedded_signing_host`             | string                            | Public host that wraps Documenso URLs into `{host}/sign/<type>/<token>`.            |
+| `documenso_contract_template_id`    | int (optional)                    | Optional template for sales contracts. Blank = upload-and-place-fields per deal.    |
+| `documenso_reservation_template_id` | int (optional)                    | Optional template for reservation agreements. Same logic as contract.               |
+
+---
+
+## Document type matrix
+
+| Type            | Generation flow                                                   | Signers                                        | Field placement                                       |
+| --------------- | ----------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------- |
+| **EOI**         | Documenso template (`eoi_template_id`) + form-fill values         | Static: client, developer, approver (per-port) | Templated — fields baked into Documenso template      |
+| **Contract**    | Per-deal upload (drafted custom). Template fallback if configured | Custom per deal — rep specifies                | Per-deal placement — default footer-anchored fallback |
+| **Reservation** | Per-deal upload OR template if configured                         | Custom per deal                                | Per-deal placement                                    |
+
+## Documenso field types
+
+Custom-uploaded documents (contracts, reservations) need a per-deal field placement step — different documents need different mixes. The CRM exposes the full Documenso-supported field palette so reps can place whatever the document calls for without code changes.
+
+| Field type       | Use case                                                | Needs `fieldMeta`? | What goes in meta                                   |
+| ---------------- | ------------------------------------------------------- | ------------------ | --------------------------------------------------- |
+| `SIGNATURE`      | Drawn signature — almost every signing flow             | No                 | —                                                   |
+| `FREE_SIGNATURE` | Type-or-draw signature variant                          | No                 | —                                                   |
+| `INITIALS`       | Per-page initials block                                 | No                 | —                                                   |
+| `DATE`           | Auto-fills the date when the recipient signs            | No                 | —                                                   |
+| `EMAIL`          | Auto-fills the recipient's email                        | No                 | —                                                   |
+| `NAME`           | Auto-fills the recipient's name                         | No                 | —                                                   |
+| `TEXT`           | Free text input (e.g. address, notes, place of signing) | Yes                | `{ text?, label?, required?, readOnly? }`           |
+| `NUMBER`         | Numeric input with optional min/max                     | Yes                | `{ numberFormat?, min?, max?, required? }`          |
+| `CHECKBOX`       | Boolean / single checkbox                               | Yes                | `{ values: [{ checked, value }], validationRule? }` |
+| `DROPDOWN`       | Pick from a fixed list                                  | Yes                | `{ values: [{ value }], defaultValue? }`            |
+| `RADIO`          | Mutually-exclusive options                              | Yes                | `{ values: [{ checked, value }] }`                  |
+
+Helper: [`fieldTypeNeedsMeta(type)`](../src/lib/services/documenso-client.ts) returns true for the configurable types so the placement UI knows when to surface a config side-panel.
+
+`fieldMeta` is forwarded verbatim by [`placeFields()`](../src/lib/services/documenso-client.ts) on the v2 path. v1 silently ignores the property — fields render as blank inputs. Configurable behaviour (validation, defaults) only fires on v2 instances.
+
+---
+
+## Documenso v1 vs v2 endpoint mapping
+
+The [`documenso-client.ts`](../src/lib/services/documenso-client.ts) abstracts both. Each function picks v1 or v2 from `getPortDocumensoConfig(portId).apiVersion`.
+
+| Operation                       | v1 (1.13–1.32)                                                              | v2.x                                                      |
+| ------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Create document from upload     | `POST /api/v1/documents` (body: `{ title, document, recipients }`)          | `POST /api/v2/envelope`                                   |
+| Generate document from template | `POST /api/v1/templates/{id}/generate-document`                             | (template-from-envelope path)                             |
+| Send for signing                | `POST /api/v1/documents/{id}/send`                                          | `POST /api/v2/envelope/{id}/send`                         |
+| Place a field                   | `POST /api/v1/documents/{id}/fields` (PIXEL coords, one at a time)          | `POST /api/v2/envelope/field/create-many` (PERCENT, bulk) |
+| Get document state              | `GET /api/v1/documents/{id}`                                                | `GET /api/v2/envelope/{id}`                               |
+| Send reminder to one recipient  | `POST /api/v1/documents/{id}/recipients/{rid}/remind`                       | `POST /api/v2/envelope/{id}/recipient/{rid}/remind`       |
+| Download finalized PDF          | `GET /api/v1/documents/{id}/download` → `{ downloadUrl }` then GET that URL | `GET /api/v2/envelope/{id}/download` (same shape)         |
+| Cancel / void                   | `DELETE /api/v1/documents/{id}`                                             | `DELETE /api/v2/envelope/{id}`                            |
+| Healthcheck                     | `GET /api/v1/health`                                                        | (v1 path used)                                            |
+
+**Field key rename in v2 responses**: `id` → `documentId` and recipient `id` → `recipientId`. Our [`normalizeDocument()`](../src/lib/services/documenso-client.ts) handles both shapes.
+
+---
+
+## Signing-flow lifecycle
+
+```
+[rep clicks Generate]                       (CRM)
+       │
+       ▼
+buildEoiContext(interestId, portId)         service
+       │
+       ▼
+generateAndSign(templateId, ctx, signers)   creates Documenso doc
+       │
+       ▼
+POST /documents/{id}/send {sendEmail:false} Documenso starts the chain;
+                                            it does NOT email signers
+       │
+       ▼
+extract signing URLs from response          service
+       │
+       ▼
+transformSigningUrl(url, host, role)        wrap as {host}/sign/<role>/<token>
+       │
+       ▼
+if eoi_send_mode === 'auto':
+    sendSigningInvitation(client)           our branded HTML email goes out
+else:
+    UI shows the URL + Send button          rep dispatches manually
+```
+
+When the client signs:
+
+```
+Documenso fires DOCUMENT_SIGNED webhook ──► /api/webhooks/documenso
+       │
+       ▼
+verify x-documenso-secret (per-port lookup)
+       │
+       ▼
+update document_signers row: status='signed', signedAt=...
+       │
+       ▼
+if next signer in chain has not been notified:
+    sendSigningInvitation(developer)        cascading "your turn" email
+```
+
+When the document reaches fully-signed:
+
+```
+Documenso fires DOCUMENT_COMPLETED webhook
+       │
+       ▼
+download signed PDF from Documenso
+       │
+       ▼
+store in storage backend → creates files row
+       │
+       ▼
+update document: status='completed', completedAt=...
+       │
+       ▼
+sendSigningCompleted([client, developer, approver], pdfFileId)
+                                            all parties get the signed PDF
+       │
+       ▼
+update interest: pipelineStage='eoi_signed' (or contract_signed, etc)
+```
+
+---
+
+## Embedded signing on the marketing website
+
+The CRM emits signing URLs in the form `{embeddedSigningHost}/sign/<role>/<token>`. The marketing website ([Port Nimara/Website/pages/sign/[type]/[token].vue](../../Port%20Nimara/Website/pages/sign/%5Btype%5D/%5Btoken%5D.vue)) hosts the page, embeds Documenso via `@documenso/embed-vue`'s `<EmbedSignDocument>`, and POSTs back to the CRM webhook on completion.
+
+For the embed to work, the Documenso instance MUST send `Access-Control-Allow-Origin` headers permitting the website origin.
+
+### nginx CORS block to apply on `signatures.portnimara.dev`
+
+Add to the relevant `server { ... }` block:
+
+```nginx
+location / {
+    # CORS for embedded signing — allow the marketing-website origin
+    # to load the Documenso signing iframe.
+    add_header 'Access-Control-Allow-Origin' 'https://portnimara.com' always;
+    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
+    add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization' always;
+    add_header 'Access-Control-Allow-Credentials' 'true' always;
+
+    # Preflight
+    if ($request_method = 'OPTIONS') {
+        add_header 'Access-Control-Allow-Origin' 'https://portnimara.com' always;
+        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
+        add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization' always;
+        add_header 'Access-Control-Max-Age' 1728000;
+        add_header 'Content-Type' 'text/plain charset=UTF-8';
+        add_header 'Content-Length' 0;
+        return 204;
+    }
+
+    # ... your existing proxy_pass block to Documenso
+}
+```
+
+To support multiple website origins (e.g. Port Amador hosted on a different domain), use a regex:
+
+```nginx
+set $cors_origin "";
+if ($http_origin ~* "^https://(portnimara\.com|portamador\.com)$") {
+    set $cors_origin $http_origin;
+}
+add_header 'Access-Control-Allow-Origin' $cors_origin always;
+```
+
+---
+
+## What's deferred vs landed in this build
+
+**Landed:**
+
+- Per-port admin settings — every Documenso config knob is exposed at `/admin/documenso`
+- Branded invitation, completion, and reminder email templates
+- `transformSigningUrl()` for `{host}/sign/<role>/<token>` URL wrapping
+- Documenso v1 + v2 dual-version client (existing)
+- Webhook handler with timing-safe per-port secret resolution (existing)
+- Contract + Reservation tab UI shells with paper-signed upload + "send for signing" placeholder
+- Stage-conditional tab visibility for EOI / Contract / Reservation
+
+**Landed in Phase 2-4 (2026-05-13):**
+
+- **Phase 2** — Webhook cascade + on-completion PDF distribution. `handleRecipientSigned` now finds the next pending signer and fires `sendSigningInvitation`; `handleDocumentCompleted` calls `sendSigningCompleted` to all recipients with the signed PDF attached (resolved via `getStorageBackend()` so MinIO + filesystem backends both work). Recipient matching prefers the Documenso recipient `token` captured at send-time (`document_signers.signing_token`); falls back to email match.
+- **Phase 3** — `lib/services/custom-document-upload.service.ts` + `POST /api/v1/interests/[id]/upload-for-signing`. Magic-byte verifies the PDF, stores via `getStorageBackend`, inserts the `documents` row, runs the full Documenso round-trip (`createDocument → sendDocument → placeFields`), captures recipient tokens, auto-sends invitation when port `sendMode === 'auto'`.
+- **Phase 4** — `<UploadForSigningDialog>` (`src/components/documents/upload-for-signing-dialog.tsx`). Three-step state machine (file → recipients → fields). Auto-detect runs server-side via `lib/services/document-field-detector.ts` (pdfjs text-extraction + anchor patterns); rep can drag/place/delete fields via native DOM events. Wired into the Contract + Reservation tabs.
+- **Phase 7** — Project Director RBAC binding. Admin UI exposes `documenso_developer_user_id` / `approver_user_id` / `_label` settings; webhook cascade fires an in-CRM `document_signing_your_turn` notification for linked users alongside the email.
+
+**Phase 5 — Embedded signing URL emission verification:**
+
+- `transformSigningUrl()` validated via 10 unit tests in `tests/unit/services/document-signing-urls.test.ts`. Maps signer-role → URL segment as:
+  - `client → /sign/client/<token>`
+  - `developer → /sign/developer/<token>`
+  - `approver → /sign/cc/<token>` — funnels through the CC page with passive copy
+  - `witness → /sign/witness/<token>` — website must handle this segment
+  - `other → /sign/cc/<token>` — same as approver
+- Hardened to reject malformed source URLs: the function now uses `extractSigningToken()` (rejects tails <8 chars or with non-URL-safe punctuation), so a bare `https://sig.example.com` is returned untouched rather than producing the malformed `<host>/sign/<role>/sig.example.com`.
+
+**Phase 5 — coordination on the marketing-website side (NOT in this repo):**
+
+These are tracked here so the CRM stays the source of truth on the contract — the actual edits land in the website repo.
+
+1. **Website `/sign/[type]/[token].vue` must handle `type ∈ {client, cc, developer, witness}`.** The CRM emits `cc` for both `approver` and `other` roles, and `witness` for explicit witness signers. Anything else lands on the website's `/sign/error` fallback.
+2. **`signerMessages` map must be keyed on `(documentType, role)`** so a contract recipient hitting `/sign/client/<token>` sees "Sign Your Sales Contract" rather than the EOI default. Until the website is updated, the URL emits `(role, token)` only; the website can resolve documentType from the Documenso embed payload.
+3. **Post-sign callback** — the legacy portal POSTed to `client-portal.portnimara.com/api/webhook/document-signed`. The CRM no longer needs this — the Documenso webhook at `/api/webhooks/documenso` handles all state updates server-side. The website's POST is now optional; if it's still in place, point it at the CRM's webhook receiver as a real-time UI signal.
+4. **Apply the nginx CORS block above** on the prod Documenso instance.
+
+**Genuinely deferred (Phase 6 polish):**
+
+- Auto-send delay (`eoi_send_delay_minutes` per-port setting + scheduled BullMQ job).
+- Document expiration toggle (`documents.expires_at` + Documenso `expiresAt` passthrough).
+- Per-document custom invitation message (textarea on the upload dialog → `documents.invitation_message`).
+- Reminder rate-limit display ("next reminder available in X days" badge on each unsigned signer in the signing-progress UI).
+- Failed-webhook recovery admin surface — the BullMQ webhook DLQ exists; needs an admin page with a Replay button.
+- Per-field metadata side panel for DROPDOWN/RADIO option lists in the Phase 4 dialog.
+- Pinch-zoom + zoom-out controls on the field-placement canvas.
+- Recipient drag-reorder via dnd-kit (current UI uses an order number input).
+
+**Manual ops work for you:**
+
+- Apply the nginx CORS block above on your prod Documenso instance.
+- Decide whether to upgrade prod Documenso to v2 (would unlock cleaner field placement + better envelope semantics).
+- Configure each port's developer/approver names and template IDs at `/[portSlug]/admin/documenso`.

docs/email-refactor-deferred.md

@@ -0,0 +1,49 @@
+# #71 Automated email refactor — DEFERRED
+
+Searched the repo + git history (commits back to the initial `67d7e6e Initial
+commit: Port Nimara CRM`) for legacy CRM email templates that could be
+lifted verbatim or used as a tonal reference for the rewrite. **None found.**
+
+The codebase was built from scratch; there's no archive directory, no
+import dump, and no commits ever contained "old-system" template HTML.
+
+## What this task needs
+
+A full refactor of the four signing-lifecycle emails to a luxury-port
+brand voice, with per-port branding flow:
+
+1. **Invitation** (`signingInvitationEmail`) — currently functional but
+   utilitarian copy. Subject format Matt called for:
+   `"{firstName}, your EOI for {portName} is ready to be signed"`.
+2. **Reminder** (`signingReminderEmail`) — same recipient, follow-up nudge.
+3. **Completion** (`signingCompletedEmail`) — sent with the signed PDF attached.
+4. **Cancelled** (`signingCancelledEmail`) — added 2026-05-15 alongside the
+   cancel-with-notify modal.
+
+Each template should have **per-port** branding parameters:
+
+- Port name + signature block
+- Primary brand color (already plumbed via `BrandingShell`)
+- Optional header/footer HTML overrides (`branding_email_header_html` /
+  `_footer_html` settings)
+
+## Source-of-truth flow before unblocking
+
+Matt to paste / share the legacy templates from the prior CRM (likely
+NocoDB-era or a separate email tool — not committed to this repo). Once
+shared, lift the copy verbatim where possible; otherwise match
+**structure + tone + voice** carefully.
+
+Current files to refactor:
+
+- `src/lib/email/templates/document-signing.tsx` (4 templates)
+- `src/lib/email/templates/portal-auth.tsx` (activation + reset)
+- `src/lib/email/templates/inquiry-client-confirmation.tsx`
+- `src/lib/email/templates/inquiry-sales-notification.tsx`
+
+## Status
+
+DEFERRED until the legacy copy is supplied or Matt approves a from-scratch
+draft. The structural plumbing (per-port branding, sendEmail with
+attachments, EMAIL_REDIRECT_TO safety, cancel-with-notify wiring) all
+landed in earlier tasks — only the copy rewrite remains.

docs/eoi-documenso-field-mapping.md

@@ -19,18 +19,23 @@ The template exposes eight text fields (`formValues` keys) and two boolean check
 
 ## Field mapping
 
-| Documenso key  | Type    | Legacy source               | New `EoiContext` path                                 | Notes                                                                     |
-| -------------- | ------- | --------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
-| `Name`         | text    | `interest['Full Name']`     | `context.client.fullName`                             | The interest's point-of-contact client (billing signer).                  |
-| `Email`        | text    | `interest['Email Address']` | `context.client.primaryEmail`                         | Primary email contact from `client_contacts`.                             |
-| `Address`      | text    | `interest['Address']`       | concat `context.client.address.{street,city,country}` | Concatenate street, city, country with `', '`. Empty if address is null.  |
-| `Yacht Name`   | text    | `interest['Yacht Name']`    | `context.yacht.name`                                  | Yacht is now a first-class row; pulled via `interest.yachtId`.            |
-| `Length`       | text    | `interest['Length']`        | `context.yacht.lengthFt`                              | Send as string. Documenso doesn't enforce numeric format.                 |
-| `Width`        | text    | `interest['Width']`         | `context.yacht.widthFt`                               | Same.                                                                     |
-| `Draft`        | text    | `interest['Depth']`         | `context.yacht.draftFt`                               | Legacy field was named "Depth" in NocoDB; Documenso key is "Draft".       |
-| `Berth Number` | text    | `berthNumbers` (joined)     | `context.berth.mooringNumber`                         | One berth per reservation. Multi-berth case was multi-interest in legacy. |
-| `Lease_10`     | boolean | hardcoded `false`           | `false`                                               | Hardcoded — legacy flow defaults to Purchase (not Lease).                 |
-| `Purchase`     | boolean | hardcoded `true`            | `true`                                                | Hardcoded — legacy flow defaults to Purchase.                             |
+The legacy template (Documenso template `8`, configured in production) auto-fills exactly the fields below. All eight text fields + two booleans are populated by `buildDocumensoPayload()` from the resolved `EoiContext`. Anything else on the form (signature, date, terms acknowledgment) is filled in by the client inside Documenso.
+
+| Documenso key  | Type    | Legacy source               | New `EoiContext` path                                 | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| -------------- | ------- | --------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Name`         | text    | `interest['Full Name']`     | `context.client.fullName`                             | The interest's point-of-contact client (billing signer).                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `Email`        | text    | `interest['Email Address']` | `context.client.primaryEmail`                         | Primary email contact from `client_contacts`.                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `Address`      | text    | `interest['Address']`       | concat `context.client.address.{street,city,country}` | Concatenate street, city, country with `', '`. Empty if address is null.                                                                                                                                                                                                                                                                                                                                                                                       |
+| `Yacht Name`   | text    | `interest['Yacht Name']`    | `context.yacht.name`                                  | Yacht is now a first-class row; pulled via `interest.yachtId`. Empty string when no yacht is linked yet.                                                                                                                                                                                                                                                                                                                                                       |
+| `Length`       | text    | `interest['Length']`        | `context.yacht.lengthFt`                              | Boat dimension. Send as string. Documenso doesn't enforce numeric format. Empty string when not applicable.                                                                                                                                                                                                                                                                                                                                                    |
+| `Width`        | text    | `interest['Width']`         | `context.yacht.widthFt`                               | Same.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `Draft`        | text    | `interest['Depth']`         | `context.yacht.draftFt`                               | Legacy field was named "Depth" in NocoDB; Documenso key is "Draft".                                                                                                                                                                                                                                                                                                                                                                                            |
+| `Berth Number` | text    | `berthNumbers` (joined)     | `context.berth.mooringNumber`                         | The interest's PRIMARY berth (resolved via `interest_berths.is_primary=true`). Empty string when no primary set.                                                                                                                                                                                                                                                                                                                                               |
+| `Berth Range`  | text    | (new)                       | `context.eoiBerthRange`                               | **NEW IN PHASE 5** — compact range string for multi-berth EOIs (e.g. `"A1-A3, B5-B7"`) covering every junction row marked `is_in_eoi_bundle=true`. Empty string when the bundle is empty. **The live Documenso template (id `8`) does NOT yet have this field. Add a `Berth Range` text field to the template before multi-berth EOIs render the range; until then Documenso silently drops the value and only `Berth Number` (the primary mooring) renders.** |
+| `Lease_10`     | boolean | hardcoded `false`           | `false`                                               | Hardcoded — legacy flow defaults to Purchase (not Lease).                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `Purchase`     | boolean | hardcoded `true`            | `true`                                                | Hardcoded — legacy flow defaults to Purchase.                                                                                                                                                                                                                                                                                                                                                                                                                  |
+
+**Backwards-compatibility guarantee**: every legacy `formValues` key is still emitted with the same name and type. The only addition is `Berth Range` (Phase 5). Documenso silently ignores unknown formValues keys, so old templates that don't have `Berth Range` will simply not render it — single-berth EOIs continue to work identically. No template changes are required for legacy use.
 
 ## Document `meta` fields (non-`formValues`)
 

docs/error-handling.md

@@ -0,0 +1,188 @@
+# Error handling
+
+## Overview
+
+Every authenticated request runs inside an `AsyncLocalStorage` frame
+that carries a `requestId` (UUID) plus the resolved `portId` / `userId`
+/ HTTP method / path / start time. The id surfaces:
+
+- as `X-Request-Id` on every response header (success or failure)
+- inside every pino log line emitted during the request
+- in the JSON error body returned to the client (`requestId` field)
+- as the primary key of the `error_events` row written when a 5xx fires
+
+A user who hits a failure can copy the **Reference ID** from the toast
+and a super admin can paste it into `/<port>/admin/errors/<requestId>`
+to see the full request context, sanitized body, error stack, and a
+heuristic "likely culprit" hint.
+
+## Throwing errors from a service
+
+Use `CodedError` with a registered code:
+
+```ts
+import { CodedError } from '@/lib/errors';
+
+if (!hasReceipts && !ack) {
+  throw new CodedError('EXPENSES_RECEIPT_REQUIRED');
+}
+```
+
+The code drives:
+
+- the HTTP status (defined in `src/lib/error-codes.ts`)
+- the **plain-text user-facing message** (no jargon — written for the
+  rep on the phone with a customer)
+- the stable identifier the user can quote to support
+
+For more verbose internal context — admin-only — use `internalMessage`:
+
+```ts
+throw new CodedError('CROSS_PORT_LINK_REJECTED', {
+  internalMessage: `interest ${a.id} (port ${a.portId}) ↔ berth ${b.id} (port ${b.portId})`,
+});
+```
+
+The `internalMessage` lands in the `error_events` row and the admin
+inspector but **never** reaches the client.
+
+## Adding a new error code
+
+1. Open `src/lib/error-codes.ts`.
+2. Add an entry to the `ERROR_CODES` map. Convention: `DOMAIN_REASON`
+   in SCREAMING_SNAKE_CASE.
+
+   ```ts
+   FOO_INVALID_BAR: {
+     status: 400,
+     userMessage: 'That bar value is no good. Please try another.',
+   },
+   ```
+
+3. Use it: `throw new CodedError('FOO_INVALID_BAR')`.
+4. The code, status, and message are now contractually stable —
+   never rename a code once it has shipped. Documentation, UI, and
+   external integrations may pin to it.
+
+## Plain-text message guidelines
+
+User-facing messages should:
+
+- Avoid internal jargon (no "constraint violation", "FK", "row lock").
+- Be written for a rep on the phone with a customer.
+- Include the suggested next action when natural ("Ask an admin if you
+  think you should").
+- Not include any technical detail that doesn't help the user — the
+  request id + error code carry that.
+
+Verbose technical detail belongs in `internalMessage` (admin-only).
+
+## Client side
+
+In a `useMutation`, render errors with the shared helper:
+
+```ts
+import { toastError } from '@/lib/api/toast-error';
+
+const mutation = useMutation({
+  mutationFn: () => apiFetch('/api/v1/foo', { method: 'POST', body: { ... } }),
+  onSuccess: () => { ... },
+  onError: (err) => toastError(err),
+});
+```
+
+The toast renders three lines:
+
+```
+{plain-text message}
+
+Error code: EXPENSES_RECEIPT_REQUIRED
+Reference ID: 8f3c-ab12-…   [Copy ID]
+```
+
+The "Copy ID" action puts the request id on the clipboard so the
+user can paste it into a support ticket.
+
+## Admin inspector
+
+`/<port>/admin/errors` lists captured 5xx errors:
+
+- Status badge + method + path
+- "Likely culprit" badge (heuristic — Postgres SQLSTATE, error name,
+  stack-path patterns, message keywords)
+- Truncated error name + message
+- Timestamp + reference id
+
+Click any row for `/<port>/admin/errors/<requestId>` which shows:
+
+- Request shape (method / path / when / duration / port / user / IP / UA)
+- Likely culprit + plain-English hint + subsystem tag
+- Full error name, message, stack head (first 4 KB)
+- Sanitized request body excerpt (max 1 KB; sensitive keys redacted)
+- Raw metadata (Postgres SQLSTATE codes, internalMessage, etc.)
+
+Permission: `admin.view_audit_log`. Super admins see every port's
+errors; regular admins are scoped to their active port.
+
+## What gets persisted
+
+| Status | error_events row? | Toast shows code? |
+| ------ | ----------------- | ----------------- |
+| 4xx    | No                | Yes               |
+| 5xx    | **Yes**           | Yes               |
+
+4xx errors are user-action mistakes (validation, not-found, permission
+denied). They're visible in the audit log but not the error inspector
+— that table is reserved for platform faults.
+
+5xx errors hit the `errorEvents` table via `captureErrorEvent` inside
+`errorResponse`, which:
+
+1. Reads the request context from ALS.
+2. Sanitizes + truncates the body (1 KB cap, sensitive keys redacted).
+3. Pulls Postgres `code` / `severity` / `cause.code` if the underlying
+   error is a `postgres` driver error.
+4. Truncates the stack to 4 KB.
+5. Inserts one row keyed on `requestId` with `ON CONFLICT DO NOTHING`.
+
+Failure to persist NEVER throws — the user is already getting an
+error response; we don't want a logging-pipeline failure to mask it.
+
+## Likely-culprit classifier
+
+`src/lib/error-classifier.ts` runs four passes against an
+`error_events` row, first match wins:
+
+1. **Postgres SQLSTATE** (from `metadata.code`): 23502 NOT NULL,
+   23503 FK, 23505 unique, 23514 CHECK, 42703 schema drift, 42P01
+   missing table, 40001 serialization, 53300 connection limit, …
+2. **Error class name**: `AbortError`, `TimeoutError`, `FetchError`,
+   `ZodError`.
+3. **Stack path**: `/lib/storage/`, `/lib/email/`, `documenso`,
+   `openai|claude`, `/queue/workers/`.
+4. **Message free-text**: `econnrefused`, `rate limit`, `timeout`,
+   `unauthorized|invalid api key`.
+
+Returns `null` when nothing matches; the inspector renders
+"Uncategorized" in that case. Adding a new heuristic is a one-line
+edit to the relevant array.
+
+## Pruning
+
+`error_events` rows are dropped after 90 days by the maintenance
+worker (TODO: confirm the worker has the deletion path; if not, add
+a periodic job that runs `DELETE FROM error_events WHERE created_at <
+now() - interval '90 days'`).
+
+## Migration path for legacy throws
+
+Existing `NotFoundError` / `ForbiddenError` / `ConflictError` /
+`ValidationError` / `RateLimitError` still work — the user-facing
+messages on these classes have been rewritten to plain-text defaults.
+
+Migration to `CodedError` happens opportunistically: when touching a
+service to fix something else, swap the throw site for a registered
+code.
+
+A follow-up audit pass should walk `git grep "throw new ValidationError"`
+and migrate the user-impactful ones to specific codes.

docs/operations/outbound-comms-safety.md

@@ -0,0 +1,123 @@
+# Outbound communications safety net
+
+**Last reviewed:** 2026-05-03
+**Owner:** matt@portnimara.com
+
+This doc enumerates every channel through which the CRM can produce
+outbound communication (email, document signing, webhooks) and describes
+how each channel respects the `EMAIL_REDIRECT_TO` env var. The goal: a
+single environment flip pauses **all** outbound traffic, so a production
+data import, dedup migration dry-run, or staging environment can run
+against real data without anyone getting paged or spammed.
+
+> **Single env switch:** when `EMAIL_REDIRECT_TO` is set to an address,
+> all outbound communication is rerouted there or short-circuited. Unset
+> it in production.
+
+---
+
+## Channels
+
+### 1. Direct email (`sendEmail`)
+
+**Path:** `src/lib/email/index.ts` → `sendEmail()` → nodemailer SMTP transport.
+
+**Safety:** YES — covered.
+
+When `EMAIL_REDIRECT_TO` is set, `sendEmail()` rewrites the `to` header
+to the redirect address and prefixes the subject with
+`[redirected from <orig>]`. The original recipient is logged.
+
+**Call sites** (all flow through `sendEmail`, so all are covered):
+
+- `src/lib/services/portal-auth.service.ts` — portal activation + reset
+- `src/lib/services/crm-invite.service.ts` — CRM user invitations
+- `src/lib/services/document-templates.ts` — template-generated PDFs sent
+  as attachments (the PDF body is generated locally; the email itself
+  goes through SMTP)
+- `src/lib/services/email-compose.service.ts` — ad-hoc emails composed
+  in the in-app UI
+- `src/lib/services/gdpr-export.service.ts` — GDPR export delivery
+
+### 2. Documenso e-signature recipients
+
+**Path:** `src/lib/services/documenso-client.ts` → `createDocument()` /
+`generateDocumentFromTemplate()` → Documenso REST API.
+
+**Safety:** YES — covered as of 2026-05-03.
+
+Documenso's own server sends the signing-request email on our behalf.
+We can't intercept that at the SMTP layer because it's external. The
+fix is at the REST-call boundary: when `EMAIL_REDIRECT_TO` is set,
+`createDocument` rewrites every recipient's email to the redirect
+address and prefixes the recipient name with `(was: <orig email>)` so
+the doc is still traceable to its intended recipient.
+`generateDocumentFromTemplate` does the same for both shapes the
+template-generate endpoint accepts (v1.13 `formValues.*Email` keys and
+v2.x `recipients` array).
+
+The redirect happens **before** the API call, so even if Documenso has
+its own retry logic the original email never leaves our process.
+
+### 3. Webhooks (outbound to user-configured URLs)
+
+**Path:** `src/lib/queue/workers/webhooks.ts` → BullMQ job → `fetch(webhook.url, ...)`.
+
+**Safety:** YES — covered as of 2026-05-03.
+
+When `EMAIL_REDIRECT_TO` is set, the webhook worker short-circuits
+before the HTTP call. The delivery row is marked `dead_letter` with a
+human-readable reason so it's still visible in the deliveries listing.
+The SSRF guard remains in place independently.
+
+### 4. WhatsApp / phone deep-links
+
+**Path:** `<a href="https://wa.me/...">` and `<a href="tel:...">` in
+client / interest detail headers.
+
+**Safety:** N/A — user-initiated only.
+
+These are deep links the user explicitly clicks. No automated dispatch.
+A deep link click opens the user's WhatsApp / phone app, which is the
+intended interaction. No safety net needed.
+
+### 5. SMS
+
+Not implemented. The `interests.preferredContactMethod` enum includes
+`'sms'` as a value but no sending path exists. If/when SMS is added (e.g.
+via Twilio), the new send function should respect `EMAIL_REDIRECT_TO`
+the same way `sendEmail` does — log the original number, drop the
+message, or reroute to a configurable `SMS_REDIRECT_TO` env.
+
+---
+
+## Verification checklist before importing real data
+
+- [ ] `.env` has `EMAIL_REDIRECT_TO=<my-address>` set.
+- [ ] Restart dev server (or worker) so the new env is picked up — env
+      vars are read at import time in some paths.
+- [ ] Send a test email via `pnpm tsx scripts/dev-trigger-portal-invite.ts`
+      or similar. Confirm subject is prefixed with `[redirected from ...]`.
+- [ ] Trigger an EOI send through the UI (any client). Confirm Documenso
+      shows the redirect address as recipient (not the real client email).
+- [ ] If any webhooks are configured, trigger an event that fires one and
+      confirm the delivery is recorded as `dead_letter` with the
+      "EMAIL_REDIRECT_TO is set" reason.
+- [ ] Run the NocoDB migration `--dry-run` to count clients/interests; the
+      `--apply` step is what creates real records but emails/webhooks are
+      still gated by the redirect env.
+
+## Production cutover
+
+When ready to go live:
+
+1. Run a final dry-run of the data migration with `EMAIL_REDIRECT_TO` set
+   to a sandbox address.
+2. Verify the snapshot looks right (counts, client coverage).
+3. Unset `EMAIL_REDIRECT_TO` in the production env.
+4. Restart the app + worker.
+5. Run the migration with `--apply`. From this point forward, real
+   recipients will receive real comms.
+
+If you ever need to re-pause outbound (e.g. handling a security incident,
+re-importing on top of existing data), set `EMAIL_REDIRECT_TO` again.

docs/superpowers/audits/2026-05-11-prod-readiness-audit.md

@@ -0,0 +1,489 @@
+# Prod-Readiness Audit — feat/documents-folders
+
+**Date:** 2026-05-11
+**Branch:** `feat/documents-folders` (67 commits ahead of `main`; 34 from this session's documents-hub-split work + 33 from Wave 11.B)
+**Scope:** 17 parallel domain audits (data-structure & sales-process completeness appended at bottom)
+**Test posture at audit time:** 1287/1287 unit + integration pass. TypeScript clean (4 pre-existing errors: 1 stale `.next/` build artifact, 3 in a Wave 11.B-era `InMemoryBackend` test stub).
+
+## Headline
+
+**~28 Critical, ~38 Important, ~36 Minor findings across 17 domains.** (Original 16-domain count was 23/32/30; Audit 17 added 5/6/6.)
+
+A handful of the Criticals are real bugs in this session's work that need to be fixed on this branch before merging to `main`. A few are long-standing gaps that survived multiple iterations (storage migration script, `.env.example` URL) and should be fixed independently of this branch but before any prod cutover. Several are mobile/a11y issues that were never going to be caught without a running dev server, which the implementation pass didn't have.
+
+**Recommendation:** fix the 23 Criticals before merging this branch. Triage Importants into "fix-before-prod" vs "follow-up-on-main". Minors → backlog.
+
+Estimated effort to clear Criticals: 6-10 hours of focused work.
+
+---
+
+## Critical findings
+
+Grouped by remediation domain. Each entry: brief rationale + file:line ref + fix sketch.
+
+### A. Core feature regressions in this session's work
+
+**A1. `handleDocumentCompleted` is not idempotent — Documenso retries duplicate `files` rows + orphan blobs**
+`src/lib/services/documents.service.ts:1115`
+
+`resolveWebhookDocument` returns the doc regardless of `status`. Two webhook deliveries (Documenso retries on 5xx) can both pass through and both insert `files` rows; the second `UPDATE documents SET signedFileId` clobbers the first and the first blob is permanently orphaned in storage with no DB row.
+
+**Fix:** `if (doc.status === 'completed' && doc.signedFileId) return;` immediately after `resolveWebhookDocument`. Standard idempotency gate for this pattern.
+
+**A2. Realtime hookup dropped by hub rebuild — multi-rep stale data**
+`src/components/documents/hub-root-view.tsx`, `src/components/documents/entity-folder-view.tsx`
+
+The pre-rebuild hub consumed `document:*` and `file:*` Socket.IO events via `useRealtimeInvalidation`. After the rebuild, both `HubRootView` and `EntityFolderView` have no realtime subscription at all. The remaining hook lives inside `FlatFolderListing`, which is torn down when navigating away. Result: rep A on `Clients/Smith/` will not see rep B's upload until manual refresh; webhook-completed signatures don't appear in the Signing-in-progress section.
+
+**Fix:** lift `useRealtimeInvalidation` up to `DocumentsHub` with both `document:*` and `file:*` events targeting the prefix keys `['files']` and `['documents']`. TanStack Query prefix matching will invalidate the aggregated keys.
+
+**A3. LEFT JOIN port_id in ON clause defeats `idx_docs_signed_file_id`**
+`src/lib/services/files.ts:544`
+
+```sql
+LEFT JOIN documents d ON d.signed_file_id = f.id AND d.port_id = $portId
+```
+
+Planner picks `idx_docs_port` and applies `signed_file_id = f.id` as a residual filter. At scale this is 20 × N comparisons per page load instead of 20 point lookups. Same pattern in `documents.service.ts:1915` for the workflow projection.
+
+**Fix:** drop `AND d.port_id = portId` from the ON clause and add `AND (d.port_id = portId OR d.id IS NULL)` to the outer WHERE. Or add a composite `(signed_file_id, port_id)` index. `files.port_id` is already scoped, so cross-port leak risk is zero.
+
+**A4. Importer doesn't set `files.folder_id` — imported files invisible to folder queries**
+`scripts/import-organized-documents.ts:196-208`
+
+The `documents` row gets `folderId` correctly (line 216) but the companion `files` row does not. `files.folder_id` is a separate column. The backfill won't rescue these — it only acts on files with entity FKs set, and the importer sets none of those either.
+
+**Fix:** copy `folderId` into the `files.values(...)` block alongside the document insert.
+
+**A5. `chk_system_folder_shape` has NULL escape — corrupted system rows persist**
+`src/lib/db/migrations/0051_documents_hub_split.sql:22-28`
+
+`NOT system_managed OR entity_type = 'root' OR (...)` evaluates to `NULL` (not `false`) when `entity_type IS NULL` and `system_managed = true`. Postgres treats NULL as "not false" so the constraint passes. Confirmed by direct insert test.
+
+**Fix:** add `entity_type IS NOT NULL` to the constraint, or restructure as `CHECK (NOT system_managed OR (entity_type IS NOT NULL AND (entity_type = 'root' OR (entity_type = ANY(...) AND entity_id IS NOT NULL))))`.
+
+**A6. `document-folders.service.ts` has zero log lines — silent failures across the entire folder service**
+`src/lib/services/document-folders.service.ts` (no `logger` import)
+
+Orphan rows in `listTree` are silently dropped (line 83-84). The 50-attempt suffix-loop exhaustion throws `ConflictError` with no log. `ensureSystemRoots` "missing root after upsert" throws raw `Error`. At 3am you would have no diagnostic for folder-related failures.
+
+**Fix:** `import { logger } from '@/lib/logger'`. Add `logger.warn` on orphan-detection, retry-exhaustion (both `ensureEntityFolder` and `syncEntityFolderName`), and the missing-root invariant in `ensureSystemRoots`.
+
+**A7. `demoteSystemFolderOnEntityDelete` is not wired into `client-hard-delete.service.ts`**
+`src/lib/services/document-folders.service.ts:650` (exported but zero callers)
+
+`client-hard-delete.service.ts` exists. It clears entity FKs on `files` and `documents` inside its transaction but never demotes the system folder. After hard-delete: folder retains `system_managed=true` + the dead `entity_id`. The partial unique index `uniq_document_folders_entity` permanently blocks any future client folder that would get the same display name. Also a GDPR right-to-be-forgotten gap.
+
+**Fix:** call `demoteSystemFolderOnEntityDelete(portId, 'client', clientId)` inside `hardDeleteClient`'s transaction (or as a post-commit hook with audit log). Confirm whether `companies`/`yachts` have analogous hard-delete services that also need wiring.
+
+### B. Accessibility blockers (WCAG 2.1 AA failures)
+
+**B1. Unlabeled search input**
+`src/components/documents/documents-hub.tsx:265`
+
+`<Input placeholder="Search by title..." />` — placeholder is not a label. Fails WCAG 1.3.1 / 4.1.2.
+**Fix:** `aria-label="Search documents by title"`.
+
+**B2. No `aria-pressed` on type-filter chips**
+`src/components/documents/documents-hub.tsx:276-299`
+
+Active state is purely visual. Screen readers can't tell which chip is selected. Fails WCAG 4.1.2.
+**Fix:** `aria-pressed={typeFilter === t}` on each chip.
+
+**B3. No `aria-expanded` on tree chevrons; folder-row labels lack context**
+`src/components/documents/folder-tree-sidebar.tsx:125, 135-155`
+
+The expand button has `aria-label="Collapse"` / `"Expand"` with no folder name, so SR users hear "Expand button, Expand button…" with no differentiation. And it lacks `aria-expanded` so the open/closed state is invisible.
+**Fix:** `aria-expanded={open}`, `aria-label={\`${open ? 'Collapse' : 'Expand'} ${node.name}\`}`. Same pattern in `documents-hub.tsx:210-217` for the per-row signer expand.
+
+**B4. `aria-label` on Lock SVG becomes part of button's accessible name**
+`src/components/documents/folder-tree-sidebar.tsx:150-154`
+
+`<Lock aria-label="System folder" />` inside the folder-select `<button>` produces accessible name "Smith System folder" rather than a separate badge announcement.
+**Fix:** `aria-hidden="true"` on the SVG + `<span className="sr-only"> (system folder)</span>` after the folder name.
+
+### C. Mobile blockers
+
+**C1. FolderTreeSidebar stacks above main panel with no collapse toggle**
+`src/components/documents/folder-tree-sidebar.tsx:32` — `w-full sm:w-60`
+
+On mobile the entire folder tree renders above the document list. With any non-trivial tree, reps scroll past it to reach content. Every other secondary-nav page uses a Sheet or Collapsible.
+**Fix:** wrap in a Sheet drawer (default closed on mobile) with a "Show folders" trigger button.
+
+**C2. `border-r` on wrong axis at mobile breakpoint**
+`src/components/documents/folder-tree-sidebar.tsx:32`
+
+Right border draws on full-width-stacked element instead of bottom separator.
+**Fix:** `border-b sm:border-r border-r-0`.
+
+**C3-C7. 5 tap-target violations below WCAG 44×44px minimum**
+
+- C3: chevron expand button (`folder-tree-sidebar.tsx:125`) — 20×20px
+- C4: row expand chevron (`documents-hub.tsx:210-216`) — no sizing
+- C5: "view signing details" (`entity-folder-view.tsx:82-89`) — ~20px tall
+- C6: "Show all (N)" (`aggregated-section.tsx:101-108`) — ~18px tall
+- C7: type-filter chips (`documents-hub.tsx:277-297`) — `py-0.5` gives ~24px
+
+**Fix:** `min-h-[44px]` + `py-2` (or `py-1.5`) on each. Or wrap in `<Button size="sm">` where the visual change is acceptable.
+
+### D. Long-standing infra gaps (independent of this branch, must fix before prod)
+
+**D1. `migrate-storage.ts` migrates zero files — silent footgun**
+`src/lib/storage/migrate.ts:40-43`
+
+`TABLES_WITH_STORAGE_KEYS` is an empty array. The comment says "Phase 6a ships an empty list" — never followed up. Running `pnpm tsx scripts/migrate-storage.ts` flips the active backend but migrates nothing. Existing blobs in `files`, `berth_pdf_versions`, `brochure_versions`, `gdpr_exports`, `report_snapshots` become unreachable.
+
+**Fix:** populate the table list with all five tables + their `storagePath`/`storageKey` columns. The `copyAndVerify` SHA-256 round-trip already works; it just needs entries to act on.
+
+**D2. `.env.example` DOCUMENSO_API_URL has `/api/v1` baked in → double-path URLs**
+`.env.example`
+
+Current value: `DOCUMENSO_API_URL=https://documenso.example.com/api/v1`. The client appends `/api/v1/documents` etc., producing `https://documenso.example.com/api/v1/api/v1/documents`. Anyone copying the example file gets 404s from Documenso with no diagnostic. Applies to both v1 and v2 deployments.
+
+**Fix:** change to `DOCUMENSO_API_URL=https://documenso.example.com` (bare host). Update the admin UI placeholder to match.
+
+### E. Test theatre — assertions never run
+
+**E1. Smoke spec `test.skip()` guards mask infrastructure failures**
+`tests/e2e/smoke/04-documents-hub-aggregated.spec.ts:99-104`
+`tests/e2e/smoke/04-documents-hub-upload-into-entity.spec.ts:41, 129, 153, 165`
+
+When the API setup step (client create, file upload, file list) returns non-2xx, the test calls `test.skip(true, ...)` and proceeds no further. Playwright reports skipped tests as passed — a green CI run hides whether the actual assertion would have succeeded.
+
+**Fix:** convert skip-on-non-ok to `expect.fail()` so a 401 on setup becomes a real test failure. Skip should only fire when the precondition is genuinely "this scenario doesn't apply", not "the infrastructure broke".
+
+### F. Webhook event coverage gap (with v1 + v2 support in scope)
+
+**F1. `DOCUMENT_DECLINED` has no handler**
+`src/app/api/webhooks/documenso/route.ts:146-214`
+
+v2 distinguishes Decline (recipient refuses) from Reject (admin cancels). The switch handles `DOCUMENT_REJECTED` only. A v2-declined document leaves the CRM document in `sent` status indefinitely; the poller doesn't catch it either (only checks `COMPLETED` and `EXPIRED`).
+
+**Fix:** add a `DOCUMENT_DECLINED` case to the switch. Behaviorally mirror `DOCUMENT_REJECTED` initially; product can refine if Decline vs Reject should differentiate downstream.
+
+---
+
+## Important findings (fix before prod, or as follow-up on `main`)
+
+Listed by audit domain. Each has a file:line ref in its source audit; I'll quote the highlights here for triage.
+
+### Security
+
+- **`storagePath` + `storageBucket` exposed via aggregated files API** (`files.ts:533-534`) — internal storage paths reach authenticated rep clients via `GET /api/v1/files?entityType=X`. Auditors flagged this from both Security and Integration angles. Sanitize at service layer.
+- **Missing `portId` on UPDATE in folder-move route** (`api/v1/documents/[id]/folder/route.ts:41-44`) — pre-flight read scopes by portId so no current exploit, but defense-in-depth gap that breaks if pre-flight is ever refactored.
+- **Signer emails exposed to all `documents.view` holders** — confirm with product whether read-only roles should see signatory email addresses or get them redacted.
+
+### Database / Migration
+
+- **`uniq_document_folders_entity` doesn't cover `entity_type = NULL`** — rows with NULL entity_type but non-NULL entity_id can duplicate. Closes when CHECK constraint is tightened (A5 above).
+- **Backfill transaction holds advisory lock across N `ensureEntityFolder` calls** — at 10k files the lock is held for minutes. Batch in chunks of 500.
+- **`CREATE INDEX` without `CONCURRENTLY`** in migration 0051 — blocks writes briefly. Quantify: short-duration on small tables, moderate on prod-sized. Split for zero-downtime if needed.
+
+### Concurrency / Error Paths
+
+- **Storage blob orphaned on DB-insert failure** in `handleDocumentCompleted` — `storage.put` before `db.insert(files)`. No janitor. Long-standing tradeoff; document explicitly.
+- **`ensureSystemRoots`/`ensureEntityFolder` outside backfill transaction** — folder rows persist if the wrapping tx rolls back. Idempotent so re-run heals.
+- **`syncEntityFolderName` 50-attempt cap with concurrent renames to same target** — silent log + stale folder name. Accepted divergence.
+
+### Performance
+
+- **N+1 grows with linked entities** — leasing company with 50 yachts = 110 queries per page load. Worst case (5 companies + 100 yachts) = 216. Acceptable for now; future optimization: single CTE with grouping.
+- **Count queries can collapse via window function** — `count(*) OVER ()` halves round-trip count at scale.
+- **Missing composite indexes `(port_id, client_id)` / `(port_id, company_id)` / `(port_id, yacht_id)` on `files`** — same for `documents`. Add before prod backfill at scale.
+- **`listDocuments` calls `listTree()` twice when `includeDescendants=true`** — pass already-fetched tree into `hydrateDocumentsWithDownloadUrl`.
+
+### Data migration (importer)
+
+- **System-root collision risk** — bucket folders named `Clients`/`Companies`/`Yachts` silently merge into auto-created system roots. Add a pre-flight check that warns when any top-level segment matches a system root name.
+
+### Observability
+
+- **Archive/restore hooks missing `portId` in log context** (`companies.service.ts:215`, `yachts.service.ts:193`) — clients has it; companies and yachts don't.
+- **Backfill CLI has no row-count telemetry** — only "Backfill complete" on success. Want files-processed / folders-created / FKs-propagated counts.
+- **No log on empty aggregated projection** — `assertEntityInPort` returning false produces a silent empty result. Log warn with `portId + entityType + entityId`.
+- **`handleDocumentCompleted` outer catch loses `portId`** (line 1197).
+
+### UI/UX
+
+- **Em-dash in `SigningDetailsDialog` description** (line 62) — user-facing copy.
+- **Em-dashes baked into aggregated group labels** (`FROM COMPANY — ACME CORP`) — rendered on every entity folder view. `files.ts:335`, `documents.service.ts:1877`. Replace with colon or slash.
+- **Mixed `Loading...` (ASCII) and `Loading…` (Unicode ellipsis)** across components. Normalize.
+- **Raw `partially_signed` status in `HubRootView`** — no StatusPill or underscore replacement. Apply `StatusPill` or at minimum `replace(/_/g, ' ')`.
+- **"view signing details" button too subtle** — inline-text in a tight muted cluster, blends into the date. Consider `<Button variant="ghost" size="sm">`.
+
+### Integration conformance (with v1 + v2 support)
+
+- **Documenso poll worker double-fire of `handleDocumentCompleted`** writes a second blob + second `files` row and overwrites `signedFileId`. Confirmed by both concurrency and integration audits. Resolved by A1's idempotency gate.
+- **Poll worker omits `portId`** when calling `handleRecipientSigned` / `handleDocumentCompleted` — multi-port correctness risk.
+- **MinIO operations have no socket timeout** — TCP blackhole stalls workers indefinitely. `fetchWithTimeout` doesn't cover the minio client's `putObject`/`getObject`. Wrap with an external timeout (`AbortController` or `Promise.race`).
+- **No 0-byte check on `downloadSignedPdf` result** — a 0-byte response from Documenso writes a permanent corrupt `signedFileId` with no recovery path.
+- **`DOCUMENSO_API_VERSION` env defaults to `v1`** with no documentation in `.env.example` that v2 is supported. A v2-pointed deployment that misses the env var fires v1 code paths against a v2 instance.
+- **`DOCUMENT_DECLINED` event handler** — already listed as Critical F1; mentioned again here because the integration audit captured it under v2-specific gaps.
+- **`RECIPIENT_VIEWED` / `RECIPIENT_SIGNED`** v2 event aliases — currently silently dropped. Confirm whether v2 actually fires these or maps to `DOCUMENT_OPENED` / `DOCUMENT_SIGNED` like v1. If v2 fires them, add handlers.
+
+### Realtime / Socket.IO
+
+- **`useRealtimeInvalidation` is inside `FlatFolderListing`, not `DocumentsHub`** — torn down when navigating away. Lifting to DocumentsHub closes this and unblocks A2 cleanly.
+- **`['document-folders']` query key has no realtime invalidation path** — rep B renaming a folder takes up to 30s `staleTime` to surface for rep A. Add a folder-rename socket emit + invalidate.
+
+### Audit log completeness
+
+- **`createFolder` has no audit log** (line 102-136) — inconsistent with rename/move/delete which all audit.
+- **`handleDocumentCompleted` file insert has no audit** (line 1163-1180) — signed PDFs created with no audit trail.
+- **`syncEntityFolderName` ignores `_userId`** — folder renames driven by entity rename leave no audit trail.
+- **Archive/restore suffix helpers no audit** — parent entity action audits, but folder mutation doesn't.
+
+### Type-safety
+
+- **`entityType as 'client'|'company'|'yacht'`** in `documents-hub.tsx:134` — no runtime guard. Fix with `ENTITY_TYPES.has()`.
+- **`INFLIGHT_STATUSES as unknown as string[]`** — replace with `[...INFLIGHT_STATUSES]`.
+- **Loose `files?/workflows?` union + unconstrained `T`** in `AggregatedSection` — refactor to discriminated union + `T extends { id: string }`.
+
+### Test quality
+
+- **`mapWorkflowStatus` `partially_signed` fix has no regression test**.
+- **`applyEntityRestoredSuffix` "restore without prior archive" path not tested**.
+- **`folderId="" → null` validator transform has zero test coverage**.
+- **`syncEntityFolderName` collision beyond `(2)` untested** — if `isSiblingNameConflict` ever mis-classifies the error shape, retries never fire and the test wouldn't notice.
+
+### Mobile
+
+- **DocumentsHub sets no `useMobileChrome`/`setChrome` title** — falls back to URL-segment title-casing.
+- **FolderActionsMenu trigger overrides to 28×28px** — should use default `size="icon"` (44×44).
+- **SigningDetailsDialog signer email no `truncate`** — long emails overflow on narrow viewports.
+- **Breadcrumb tap targets too small** (`folder-breadcrumb.tsx:41-60`) — no padding.
+
+---
+
+## Minor (backlog)
+
+Approximately 30 minor findings across all domains. Highlights:
+
+- **Em-dashes in `CLAUDE.md`** (29 in prose bullets, all in pre-existing content; no new em-dashes added in commit `ab79894`) — backlog cleanup pass.
+- **`@radix-ui/react-icons` unused** — safe to remove from `package.json`.
+- **`@hookform/resolvers`, `zod`, `tailwindcss`** all have major-version updates available — DO NOT upgrade pre-cutover (breaking changes).
+- **Sonnet color contrast on `muted-foreground/70` opacity variant** (`aggregated-section.tsx:94`) — ~3.2:1 fails WCAG AA for normal text. Drop the `/70` tint.
+- **`<header>` element inside `<div>` not under a sectioning element** (`aggregated-section.tsx:92`) — wrong landmark scope; use `<div>` or `<h6>`.
+- **`h3` → `h5` jump in SigningDetailsDialog** (skipped heading level).
+- **`renameFolder` `updatedAt` test uses 10ms `setTimeout`** — fragile but `toBeGreaterThan` is OK; can drop the sleep entirely.
+- **`MINIO_AUTO_CREATE_BUCKET`** bypasses zod env schema; undocumented in `.env.example`.
+- **`DOCUMENSO_TEMPLATE_ID_EOI` + recipient ID vars absent from `.env.example`** with Port-Nimara-specific hardcoded defaults.
+- **`voidDocument` raw `FetchTimeoutError` propagation** — no `CodedError('DOCUMENSO_TIMEOUT')` wrap. Both call sites handle gracefully; cosmetic.
+
+---
+
+## Audit-by-audit completion log
+
+| #   | Audit                                       | Status | Critical | Important | Minor |
+| --- | ------------------------------------------- | ------ | -------- | --------- | ----- |
+| 1   | Security & multi-tenant isolation           | ✓      | 0        | 3         | 0     |
+| 2   | Database & migration safety                 | ✓      | 1        | 3         | 3     |
+| 3   | Concurrency, idempotency, error paths       | ✓      | 1        | 3         | 3     |
+| 4   | Performance & query plans                   | ✓      | 1        | 3         | 3     |
+| 5   | Data migration from old system              | ✓      | 1        | 1         | 3     |
+| 6   | Production observability                    | ✓      | 2        | 4         | 3     |
+| 7   | UI/UX                                       | ✓      | 0        | 5         | 4     |
+| 8   | Integration conformance (Context7)          | ✓      | 0        | 0         | 3     |
+| 9   | Dependency audit                            | ✓      | 0        | 0         | ~10   |
+| 10  | Accessibility (WCAG 2.1 AA)                 | ✓      | 4        | 5         | 4     |
+| 11  | Test quality & coverage                     | ✓      | 2        | 6         | 3     |
+| 12  | Realtime / Socket.IO                        | ✓      | 3        | 2         | 1     |
+| 13  | Audit log completeness                      | ✓      | 0        | 4         | 4     |
+| 14  | Type-safety                                 | ✓      | 0        | 3         | 3     |
+| 15  | Mobile / responsive                         | ✓      | 6        | 5         | 3     |
+| 16  | Integration holes (MinIO + Documenso)       | ✓      | 2        | 5         | 5     |
+| 17  | Data structure & sales process completeness | ✓      | 5        | 6         | 6     |
+
+---
+
+## Suggested remediation order
+
+**Pre-merge (block this branch):**
+
+1. A1 (concurrency idempotency) — 1 line, 5 minutes.
+2. A2 (realtime hookup) — ~30 min: lift one hook up two layers in component tree.
+3. A4 (importer folder_id) — 1 line in scripts/import-organized-documents.ts.
+4. A5 (CHECK NULL escape) — 1-line migration patch + re-apply.
+5. A6 (folder service logger) — add `import { logger }` + 3 warn calls.
+6. A7 (demote on hard-delete) — 1 line in client-hard-delete.service.ts.
+7. B1-B4 (a11y) — ~30 min combined: aria attributes only.
+8. C1-C7 (mobile) — ~1-2 hours: Sheet wrap + tap-target padding.
+9. E1 (test theatre) — convert skips to fails.
+10. F1 (DOCUMENT_DECLINED) — add case to switch.
+
+**Pre-prod cutover (independent of branch):**
+
+- A3 (LEFT JOIN port_id) — performance fix.
+- D1 (storage migration table list) — populate TABLES_WITH_STORAGE_KEYS.
+- D2 (.env.example URL) — strip `/api/v1`.
+- All Important security findings.
+- 0-byte signed PDF check.
+- MinIO socket timeout wrapper.
+- DOCUMENSO_API_VERSION documentation + v2 event audit.
+
+**Post-prod (backlog on main):**
+
+- Important UI/UX (em-dashes, loading state consistency, status pill on HubRootView).
+- Important audit log completeness.
+- Important type-safety tightening.
+- All Minor.
+
+---
+
+## Notes on session vs. pre-existing findings
+
+Several Criticals (D1 storage migration script, D2 .env.example, A3 LEFT JOIN port_id, parts of the audit-log gaps and observability gaps) are long-standing — they survived multiple iterations of the codebase, sometimes since Phase 6a. Fixing them on this branch is fine but they're not regressions introduced by this session.
+
+The session's actual regressions are: A1 (idempotency), A2 (realtime), A5 (CHECK NULL), A6 (folder service has no logger), A7 (demote not wired), B1-B4 (a11y missed during the UI rebuild), C1-C7 (mobile never tested), E1 (test theatre).
+
+The dependency, integration-conformance (Context7), and type-safety audits are clean of Critical findings — your dep posture is solid and the implementation follows published specs.
+
+---
+
+## Audit 17 — Data structure & sales process completeness
+
+**5 Critical, 6 Important, 6 Minor.** This audit walked the entire entity graph and the sales-process pipeline end-to-end. Most findings are not regressions from this session — they are gaps in the sales-process plumbing that pre-date the documents-hub-split work but matter for prod cutover. C-1 and C-3 are session-introduced; C-2, C-4, C-5 are long-standing.
+
+### Critical (data graph + sales pipeline)
+
+**G-C1. `deleteFolderSoftRescue` re-parents documents but not files — split delete behavior**
+`src/lib/services/document-folders.service.ts:268-282`
+
+The soft-rescue transaction `UPDATE`s `documents.folderId = newParent`, then deletes the folder row. The schema cascade on `files.folderId` is `ON DELETE SET NULL` (not `SET DEFAULT newParent`) — so any files in the deleted folder land at **root**, while documents in the same folder correctly land at the deleted folder's **parent**. A folder containing both will scatter on delete.
+
+Fix: inside the transaction, between the documents UPDATE and the folder DELETE:
+
+```ts
+await tx
+  .update(files)
+  .set({ folderId: newParent })
+  .where(and(eq(files.folderId, folderId), eq(files.portId, portId)));
+```
+
+**G-C2. Client hard-delete blocked by `scratchpadNotes.linkedClientId` RESTRICT FK**
+`src/lib/services/client-hard-delete.service.ts:190-218` + `src/lib/db/schema/system.ts:180`
+
+`scratchpadNotes.linkedClientId references clients.id` with no `onDelete` → defaults to RESTRICT. The hard-delete service nullifies six nullable FKs (files, documents, formSubmissions, emailThreads, reminders, documentSends) but skips `scratchpadNotes`. Any rep who scratchpad-linked a note to a client → hard-delete throws an FK violation and aborts the transaction.
+
+Fix: add to the nullification block:
+
+```ts
+await tx
+  .update(scratchpadNotes)
+  .set({ linkedClientId: null })
+  .where(eq(scratchpadNotes.linkedClientId, args.clientId));
+```
+
+**G-C3. Client hard-delete leaves ghost system folder with stale `entityId`**
+`src/lib/services/client-hard-delete.service.ts:214-218`
+
+The unique index `uniq_document_folders_entity` on `(portId, entityType, entityId)` enforces a singleton system folder per entity. Hard-delete removes the client row but does not call `demoteSystemFolderOnEntityDelete`. The folder persists with `systemManaged=true, entityType='client', entityId=<deleted-id>` — invisible in the sidebar but holding the unique slot.
+
+Fix: after the client delete, fire-and-forget the demote:
+
+```ts
+void demoteSystemFolderOnEntityDelete(args.portId, 'client', args.clientId).catch(logger.error);
+```
+
+(This is the same wire-up A7 in the main report flagged — confirmed missing on the hard-delete pathway specifically.)
+
+**G-C4. Five of seven berth-rule triggers are defined but never called**
+`src/lib/services/berth-rules-engine.ts:37-44` vs `src/lib/services/documents.service.ts:798,894,1234`
+
+`DEFAULT_RULES` defines triggers for `eoi_sent`, `eoi_signed`, `deposit_received`, `contract_signed`, `interest_archived`, `interest_completed`, `berth_unlinked`. Only `eoi_sent` and `eoi_signed` are passed to `evaluateRule` anywhere in the codebase.
+
+Concrete consequences:
+
+- Deposit received (invoice paid) → no berth state change. Should auto-mark berth as Sold.
+- Contract signed → no berth state change.
+- Interest archived → no "berth available" suggestion fires.
+- Interest marked Won/Lost → no rule trigger.
+- Interest unlinked from berth → no rule trigger (off-by-default, but configurable and silently dead).
+
+Fix sketches:
+
+- `invoices.ts:741` (after `advanceStageIfBehind('deposit_10pct')`):
+  ```ts
+  const { evaluateRule } = await import('@/lib/services/berth-rules-engine');
+  void evaluateRule('deposit_received', updated.interestId, portId, meta);
+  ```
+- `interests.service.ts:archiveInterest` after `softDelete`: fetch primary berth via `getPrimaryBerth`, then `void evaluateRule('interest_archived', ...)`.
+- `interests.service.ts:setInterestOutcome` after the outcome write: `void evaluateRule('interest_completed', ...)`.
+- `interest-berths.service.ts:removeInterestBerth` after delete: `void evaluateRule('berth_unlinked', ...)`.
+
+**G-C5. `contract_sent` and `contract_signed` pipeline stages have zero auto-advancement triggers**
+`src/lib/services/documents.service.ts` (absent)
+
+`STAGE_TRANSITIONS` defines `contract_sent` and `contract_signed` and they render in the Kanban/funnel UI, but no code path calls `advanceStageIfBehind(..., 'contract_sent')` or `advanceStageIfBehind(..., 'contract_signed')`. Sending a reservation agreement → no stage advance. Completing one (signed PDF arrives, `contractFileId` set in `handleDocumentCompleted` ~line 887) → no stage advance.
+
+Effect: deals stall at whatever stage they hit when the reservation agreement was sent, until a rep manually drags them in the Kanban.
+
+Fix: in `documents.service.ts`:
+
+- `sendDocument` pathway (~line 798): if `doc.documentType === 'reservation_agreement'`, fire `advanceStageIfBehind(..., 'contract_sent', meta, 'Reservation agreement sent')`.
+- `handleDocumentCompleted` (~line 887, where `contractFileId` is set): fire `advanceStageIfBehind(..., 'contract_signed', meta, 'Reservation agreement signed')` and `evaluateRule('contract_signed', ...)`.
+
+### Important (cross-entity gaps)
+
+**G-I1. Portal email uniqueness is global, not per-port**
+`src/lib/db/schema/portal.ts:40` — `uniqueIndex('idx_portal_users_email_unique').on(table.email)`
+
+A client who has dealt with two ports under this deployment can only ever have one portal account. The second `createPortalUser` will throw a unique-constraint violation. Make per-port (`.on(table.email, table.portId)`) if multi-port is a real deployment scenario, or document as single-port-only.
+
+**G-I2. `archiveInterest` skips `interest_archived` rule and `notifyNextInLine`**
+`src/lib/services/interests.service.ts:985-1014`
+
+Archive does the audit log + socket emit but does not (a) trigger the berth-availability rule, (b) notify the waiting list for the primary berth. The waiting-list code is only fired when the **client** is archived, not the **interest**.
+
+Fix after `softDelete`: fetch primary berth → `evaluateRule('interest_archived', ...)` + `notifyNextInLine(primaryBerth.berthId, portId, meta.userId)`.
+
+**G-I3. Yacht/company `restore` paths missing `applyEntityRestoredSuffix`**
+`src/lib/services/yachts.service.ts:178` + `src/lib/services/companies.service.ts:200`
+
+Archive sides call `applyEntityArchivedSuffix`. Restore paths do not exist for yachts/companies at all today — but when they are added (or if the entity-restoration logic moves to the `clients/archive` parity routes), `applyEntityRestoredSuffix` must be wired. `clients.service.ts:596` already does this correctly.
+
+**G-I4. `berthRecommendations.interestId` has no FK constraint**
+`src/lib/db/schema/berths.ts:134` — column comment says "references interests.id" but `.references()` is omitted.
+
+If an interest is hard-deleted (currently only possible via `db:studio` or future migrations), stale `berthRecommendations` rows persist and skew the recommender's tier aggregates. Add `.references(() => interests.id, { onDelete: 'cascade' })` and generate a migration.
+
+**G-I5. Portal invoices invisible for company-billed deals**
+`src/lib/services/portal.service.ts:232`
+
+`getClientInvoices` matches on `billingEmail in client.emails`. Invoices with `billingEntityType='company'` (the most common B2B pattern: client is an individual buying through their company) are not surfaced even when the client is the company's director. Extend the query to OR-in invoices where `billingEntityType='company' AND company.directorClientId = portalUser.clientId`.
+
+**G-I6. `hub-counts` API endpoint is orphaned**
+`src/app/api/v1/documents/hub-counts/route.ts:5-10` + `getHubTabCounts` in `documents.service.ts:397`
+
+The hub rebuild on this branch removed the component that called this endpoint. Service function + route are dead code. Either wire a KPI strip back into `HubRootView` (the spec does call for this) or delete the route + service function.
+
+### Minor
+
+- **G-M1.** Website inquiry → client conversion is fully manual; `prefill_*` query params are hints only. `inquiry-inbox.tsx:119`.
+- **G-M2.** Polymorphic array columns (`photoFileIds`, `attachmentFileIds`) have no FK protection. Files deleted via any future hard-purge path silently orphan these arrays.
+- **G-M3.** `berthReservations.interestId` RESTRICT default (notNull, no `onDelete`) — intent (preserve history vs oversight) undocumented.
+- **G-M4.** `setInterestOutcome` to `won` does not fire berth-sold; downstream of G-C4.
+- **G-M5.** `advanceStageIfBehind` silently no-ops when `yachtId` is null at `open` stage. Walk-in EOIs (vessel not yet identified) stall invisibly at `open`.
+- **G-M6.** `removeInterestBerth` emits socket + webhook but skips `evaluateRule('berth_unlinked')`. Downstream of G-C4.
+
+### Impact on cutover gate
+
+- **G-C2** is the most pressing for cutover: it is a hard error on a foreseeable action (any rep deleting a client with a linked scratchpad note → 500). Fix before any team testing.
+- **G-C4 + G-C5** mean the berth-map status and Kanban columns will drift visually for every deal that progresses past EOI. This is not data corruption, but it will erode rep trust quickly during initial team testing. Fix before cutover.
+- **G-C1** is a UX correctness issue; will surprise reps but won't lose data. Same-branch fix.
+- **G-C3** is data-integrity hygiene; no immediate user-visible effect but pollutes the unique-folder slot. Same-branch fix.
+
+### Updated headline
+
+With Audit 17 folded in, the corrected count is **~28 Critical, ~38 Important, ~36 Minor** across 17 domains. The new Criticals (G-C2, G-C4, G-C5) are long-standing pre-existing gaps in the sales pipeline — they don't block this branch's merge to `main`, but they block prod cutover. G-C1 and G-C3 are this-branch issues and should be folded into the same fix pass as A1-A7.
+
+### Suggested remediation order — addendum
+
+After the A/B/C/D/E/F block from the main report:
+
+1. **G-C1** — files folder UPDATE in `deleteFolderSoftRescue` transaction (1-line addition).
+2. **G-C2** — nullify `scratchpadNotes.linkedClientId` in `clientHardDelete` (1-line addition).
+3. **G-C3** — call `demoteSystemFolderOnEntityDelete` after client hard-delete (1-line addition).
+4. **G-C4 + G-C5** — wire 6 missing berth-rule + pipeline-advance triggers (~30 min total, spread across invoices.ts, interests.service.ts, interest-berths.service.ts, documents.service.ts).
+
+Total addendum effort: ~1 hour for G-C1/G-C2/G-C3, ~30 min for G-C4/G-C5, plus 1 migration regen for I-4 if you choose to fix it now.

docs/superpowers/audits/2026-05-18-full-codebase-audit.md

@@ -0,0 +1,335 @@
+# Full Codebase Audit — 2026-05-18
+
+> **Companion doc:** [Alpha UAT Master](./alpha-uat-master.md) — the multi-day cross-cutting Playwright/React-Grab walkthrough doc, findings cross-referenced here as `→ confirmed in manual #N`.
+>
+> **Methodology:** Parallel sonnet[1m] audit team (16 narrow-scope agents), each assigned a specific subsystem with no overlap. Every finding includes file:line evidence; severity is `critical | high | medium | low | info`. Findings here are raw — triage + prioritization at the bottom.
+>
+> **Scope:** entire `src/` tree at commit `b3f8756` (post-audit-cleanup). Excludes `docs/`, `tests/` (covered by F3), build/Docker config, and node_modules.
+>
+> **Out of scope:** anything in `docs/BACKLOG.md` already triaged. This audit looks for NEW findings not on that list.
+
+---
+
+## Audit team composition
+
+| Agent                           | Scope                                                                                    |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| **A1 — Schema: people/orgs**    | `src/lib/db/schema/{clients,yachts,companies,users}.ts`                                  |
+| **A2 — Schema: pipeline**       | `src/lib/db/schema/{interests,berths,reservations}.ts`                                   |
+| **A3 — Schema: docs+infra**     | `src/lib/db/schema/{documents,email,brochures,system}.ts`                                |
+| **B1 — Public API**             | `src/app/api/public/*`                                                                   |
+| **B2 — Admin API**              | `src/app/api/v1/admin/*`                                                                 |
+| **B3 — v1 entity CRUD**         | `src/app/api/v1/{clients,interests,yachts,companies,berths}/*`                           |
+| **B4 — Webhooks/auth/storage**  | `src/app/api/{webhooks,auth,storage}/*`                                                  |
+| **C1 — EOI/Documenso services** | `src/lib/services/{eoi-*,document-templates,custom-document-upload,documenso-client}.ts` |
+| **C2 — Domain services**        | `src/lib/services/{berth-*,reminders,notifications,inquiry-notifications}.ts`            |
+| **C3 — Observability/audit**    | `src/lib/services/error-events.service.ts`, `src/lib/audit.ts`, `src/lib/storage/*`      |
+| **D1 — Jobs/queues**            | `src/lib/queue/scheduler.ts`, `src/lib/queue/workers/*`, `src/jobs/processors/*`         |
+| **E1 — Admin UI**               | `src/app/(dashboard)/[portSlug]/admin/*`                                                 |
+| **E2 — Entity UI**              | `src/components/{interests,clients,yachts,companies,berths}/*`                           |
+| **F1 — Security cross-cut**     | Auth/permission gaps, XSS/SQLi, port-isolation, secret leaks                             |
+| **F2 — Performance**            | Missing indexes, N+1 queries, unbounded fan-outs, hot paths                              |
+| **F3 — Tests + deps**           | Coverage gaps, package.json freshness, Docker/CI                                         |
+
+---
+
+## Findings by agent
+
+### A2 — Schema: pipeline (15 findings: 3 high, 4 medium, 7 low, 1 info)
+
+| #   | Severity | Title                                                                                             | Evidence                                                                                             |
+| --- | -------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 1   | high     | No DB-level CHECK on `interests.pipeline_stage`                                                   | `interests.ts:44` — text col, no CHECK; legacy 'completed' / 'eoi_signed' can persist via raw SQL    |
+| 2   | high     | No DB-level CHECK on `outcome`, `eoi_doc_status`, `reservation_doc_status`, `contract_doc_status` | `interests.ts:47-49,84` — bare text on all 4 enum-shaped columns                                     |
+| 3   | high     | No DB-level CHECK on `berths.status`                                                              | `berths.ts:31` — `derivePublicStatus()` silently falls through to 'Available' on bad values          |
+| 4   | medium   | No CHECK on `berth_reservations.status` — breaks `idx_br_active` invariant                        | `reservations.ts:34,61-64` — misspelled 'Active' bypasses the one-active-per-berth guard             |
+| 5   | medium   | Stale `berthId` field on `Interest` domain type                                                   | `src/types/domain.ts:39` — `interests.berth_id` was dropped in 0029; type still declares it          |
+| 6   | medium   | Board query missing composite partial index — bitmap-AND scan on large ports                      | `interests.ts:113-117` — need `(portId, pipelineStage) WHERE archivedAt IS NULL AND outcome IS NULL` |
+| 7   | medium   | `interestTags.tagId` + `berthTags.tagId` are comment-only FKs, no DB constraint                   | `interests.ts:205-207`, `berths.ts:267-269` — tag deletes silently orphan junction rows              |
+| 8   | medium   | `berthWaitingList` lacks `port_id` column — no schema-level cross-port isolation                  | `berths.ts:170-192` — defense-in-depth depends entirely on service layer                             |
+| 9   | low      | No index on `interest_berths.is_in_eoi_bundle`                                                    | bundle lookups scan all rows for the interestId                                                      |
+| 10  | low      | `berthRecommendations` lacks `port_id` — same isolation pattern as #8                             | `berths.ts:146-168`                                                                                  |
+| 11  | low      | `interests.assignedTo`, `interest_berths.addedBy`/`eoiBypassedBy` are bare text — no FK to users  | dead entries accumulate on user delete                                                               |
+| 12  | low      | `berthMaintenanceLog.portId` FK missing onDelete — implicit NO ACTION breaks H-01 convention      | `berths.ts:204-206`                                                                                  |
+| 13  | low      | `berthReservations.startDate`/`endDate` use timestamptz `mode:'date'` — TZ off-by-one risk        | should be `date()`                                                                                   |
+| 14  | low      | `idx_interests_stage` is not partial — bloats with archived + closed rows                         | add `WHERE archivedAt IS NULL AND outcome IS NULL`                                                   |
+| 15  | info     | `is_primary` ≤1 per interest invariant correctly enforced via partial unique index                | `interests.ts:165-167` — no action needed                                                            |
+
+### B2 — API: admin (10 findings: 2 medium, 8 low)
+
+| #   | Severity | Title                                                                                            | Evidence                                                                                                                   |
+| --- | -------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| 1   | medium   | `GET /qualification-criteria` has no `withPermission` gate                                       | `qualification-criteria/route.ts:9` — any authenticated user can enumerate; POST correctly gates                           |
+| 2   | medium   | Triage PATCH on website-submissions uses `view_audit_log` (read) for a write                     | `website-submissions/[id]/triage/route.ts:26` — semantic mismatch; should be manage_settings                               |
+| 3   | low      | `/admin/storage/route.ts` POST returns bare `result` without `{data:...}`                        | `storage/route.ts:64` — breaks toastError frontend hook                                                                    |
+| 4   | low      | `/admin/ocr-settings/test` POST returns bare result without `{data:...}`                         | `ocr-settings/test/route.ts:26`                                                                                            |
+| 5   | low      | `/admin/ocr-settings` PUT returns `{ok:true}` — legacy success-flag pattern                      | `ocr-settings/route.ts:64` — should be 204 or `{data: updatedConfig}`                                                      |
+| 6   | low      | `/admin/custom-fields/[fieldId]` PATCH uses raw `req.json()` + manual `.parse()` not `parseBody` | `custom-fields/[fieldId]/route.ts:18-19` — generic 500 instead of structured 400                                           |
+| 7   | low      | `/admin/ai-budget` PUT — `setAiBudget` audit record missing ipAddress + userAgent                | `ai-budget/route.ts:40`                                                                                                    |
+| 8   | low      | `/admin/ocr-settings` PUT — `saveOcrConfig` audit record missing ipAddress + userAgent           | `ocr-settings/route.ts:53` — encrypted API key swap is high-impact, deserves full context                                  |
+| 9   | low      | `/admin/brochures/[id]` PATCH+DELETE pass no audit meta to service helpers                       | `brochures/[id]/route.ts:26,37` + brochures POST — pattern mismatch with form-templates, custom-fields, document-templates |
+| 10  | low      | `/admin/email-templates` PUT returns `{data:{ok:true}}` — flag body instead of entity or 204     | `email-templates/route.ts:84`                                                                                              |
+
+### A3 — Schema: docs+infra (15 findings: 1 high, 7 medium, 7 low)
+
+| #   | Severity | Title                                                                                                       | Evidence                                                                                                                          |
+| --- | -------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **high** | `documents.documenso_id` has NO INDEX                                                                       | `documents.ts:88` — full table scan on every webhook delivery (hottest read path); only documenso_numeric_id is indexed           |
+| 2   | medium   | `documentSigners.signingToken` indexed but NOT unique                                                       | `documents.ts:188,193` — token collision/replay has no DB-level guard; should be partial uniqueIndex                              |
+| 3   | medium   | `audit_logs` missing 4-column inspector index                                                               | `system.ts:62-63` — neither existing index covers `(port_id, entity_type, entity_id, ORDER BY created_at)` without heap re-filter |
+| 4   | medium   | `system_settings NULLS NOT DISTINCT` lives in migration 0047 only — `db:push` drops it                      | `system.ts:144-149` — fresh `db:push` re-introduces the duplicate-global-settings bug 0047 fixed                                  |
+| 5   | medium   | `documentFolders.parentId` self-FK MISSING from Drizzle schema (only in migration 0050)                     | `documents.ts:357-358` — fresh `db:push` skips the self-FK; orphaned folders undetectable                                         |
+| 6   | medium   | `emailMessages.attachmentFileIds` text[] with no FK — dangling IDs survive RTBF wipe                        | `email.ts:78` + `client-hard-delete.service.ts:269-277` — RTBF wipes body/subject but not attachment file references              |
+| 7   | medium   | `brochureVersions` missing `unique(brochureId, versionNumber)` — unlike berth_pdf_versions                  | `brochures.ts:79` — concurrent uploads could assign duplicate version numbers                                                     |
+| 8   | medium   | `documensoNumericId` indexed non-uniquely despite being globally unique                                     | `documents.ts:94,152` — webhook resolver matches multiple docs for same numeric ID; double-processing                             |
+| 9   | low      | `emailThreads.clientId` has no `onDelete` clause — defaults to RESTRICT, inconsistent with `set null` peers | `email.ts:50`                                                                                                                     |
+| 10  | low      | `files.storagePath` has no unique constraint — duplicate blob paths undetected                              | `documents.ts:41` — migrate-storage.ts would silently double-migrate                                                              |
+| 11  | low      | `brochureVersions.storageKey` + `berth_pdf_versions.storageKey` lack unique constraints                     | same as #10                                                                                                                       |
+| 12  | low      | `documentSends.berthPdfVersionId` has no index — full-scan for version-X queries                            | `brochures.ts:120`                                                                                                                |
+| 13  | low      | C.2 dedup gap: SIGNED events with `recipient_email=NULL` fall back to broken hash-only path                 | migration 0075 risk note: any v2 code path emitting global SIGNED without recipient context bypasses per-recipient dedup          |
+| 14  | low      | C.2 dedup over-eager: void-then-reinvite with same email blocks the legitimate 2nd signing                  | `documents.ts:230-232` — partial unique on (docId, recipientEmail, eventType) treats reinvited signing as re-delivery             |
+| 15  | low      | `document_sends` + `emailMessages` parallel send-audit tables with no cross-reference                       | future IMAP-synced sent-folder → duplicate GDPR exports                                                                           |
+
+### B1 — API: public (12 findings: 1 high, 3 medium, 5 low, 3 info)
+
+| #   | Severity | Title                                                                                                        | Evidence                                                                                                                                      |
+| --- | -------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **high** | `portId` is caller-controlled on `/interests` — NOT validated against existing ports                         | `interests/route.ts:40` — caller can inject client/yacht/interest into ANY tenant they know the UUID for; residential-inquiries DOES validate |
+| 2   | medium   | Health endpoint `X-Intake-Secret` comparison leaks secret byte-length via timing short-circuit               | `health/route.ts:57` — length check before timingSafeEqual; website-inquiries does it right                                                   |
+| 3   | medium   | `X-Forwarded-For` spoofable — rate-limit keys are attacker-controlled on all public POST routes              | interests/residential/website-inquiries — no x-real-ip fallback; route-helpers `clientIp()` has it but isn't used                             |
+| 4   | medium   | `/public/supplemental-info/[token]` has NO rate limiting on GET or POST                                      | `supplemental-info/[token]/route.ts` — POST writes live client PII (name, address, email, phone) at unlimited rate                            |
+| 5   | low      | Unbounded string fields in public schemas — multi-MB payloads allowed                                        | publicInterestSchema/publicResidentialInquirySchema — no `.max()` on phone/notes/preferences; no segment bodySizeLimit                        |
+| 6   | low      | Invalid `portId` on `/interests` causes 500 (DB FK error) not 400                                            | residential route has the explicit pre-check; interests doesn't                                                                               |
+| 7   | low      | `supplemental-info` POST uses raw `req.json()` + `.parse()` instead of `parseBody()`                         | malformed JSON returns 500 not field-level 400                                                                                                |
+| 8   | low      | `supplemental-info` GET missing `Cache-Control: no-store` — intermediaries may cache token-keyed PII payload | response includes primaryEmail/Phone/streetAddress                                                                                            |
+| 9   | low      | Rate limiting fails open on Redis outage — silently drops public-form protection                             | `rate-limit.ts:57-73` — intentional for auth, equally affects public POST                                                                     |
+| 10  | info     | `applySubmission` distinguishes consumed vs expired token in error message                                   | violates the conflation principle the GET path uses                                                                                           |
+| 11  | info     | Authenticated health probe discloses `APP_URL` and `NODE_ENV`                                                | `health/route.ts:86-93` — internal URL leak via authed probe                                                                                  |
+| 12  | info     | `residential-inquiries` exposes internal UUIDs and uses deprecated `{success:true}` envelope                 | `residential-inquiries/route.ts:123`                                                                                                          |
+
+### F3 — Tests + deps + infra (15 findings: 2 critical, 3 high, 4 medium, 5 low, 1 info)
+
+| #   | Severity     | Title                                                                                      | Evidence                                                                                                                                                                                 |
+| --- | ------------ | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **CRITICAL** | `client-hard-delete.service.ts` has ZERO unit or integration tests                         | GDPR/CCPA-critical path just modified today; no automated regression guard                                                                                                               |
+| 2   | **CRITICAL** | No CI/CD pipeline — `.github/workflows/` does not exist                                    | every merge can silently break tests; the full vitest+playwright suite must be run manually                                                                                              |
+| 3   | high         | `alert-engine-realtime.spec.ts` permanently skips a test whose route now exists            | spec skip says route not implemented; route file present at `/admin/alerts/run-engine`                                                                                                   |
+| 4   | high         | `documenso-client.ts` v1/v2 routing has no dedicated unit test                             | every EOI + document-send path goes through it                                                                                                                                           |
+| 5   | high         | Coverage config excludes `src/app/` — route handlers never counted                         | `vitest.config.ts: coverage.include: ['src/lib/**']` — misleadingly low coverage on API surface                                                                                          |
+| 6   | medium       | Two competing image-crop libraries in production deps                                      | `react-easy-crop` + `react-image-crop` both live; one call site each                                                                                                                     |
+| 7   | medium       | Six PDF-related packages; pdfkit (1 usage) and unpdf (1 usage) candidate for consolidation | `pdf-lib`, `pdfjs-dist`, `pdfkit`, `react-pdf`, `unpdf`, `@react-pdf/renderer`                                                                                                           |
+| 8   | medium       | CLAUDE.md lists `pdfme` as a tech-stack dep — not in package.json                          | removed 2026-05-12; CLAUDE.md outdated                                                                                                                                                   |
+| 9   | medium       | `playwright.config.ts` retries hardcoded to 0, not elevated in CI                          | should be `process.env.CI ? 2 : 0` for flaky network-bound realapi tests                                                                                                                 |
+| 10  | low          | No top-level `test` npm script — requires `pnpm exec vitest run`                           | DX gap; CI templates expect a `test` alias                                                                                                                                               |
+| 11  | low          | Missing `test:e2e:realapi` and `test:e2e:visual` shorthand scripts                         | inconsistency vs `test:e2e:smoke/exhaustive/destructive`                                                                                                                                 |
+| 12  | low          | `@hookform/devtools` devDep + `FormDevtool` wrapper component have no callers              | dead code                                                                                                                                                                                |
+| 13  | low          | Dockerfile builder stage uses broad `COPY . .` — secrets rely entirely on `.dockerignore`  | well-structured .dockerignore mitigates, but targeted COPY is defense-in-depth                                                                                                           |
+| 14  | low          | Large cluster of high-value services have no unit tests at all                             | interest-berths, portal-auth, alert-engine, berth-rules-engine, documenso-webhook, document-reminders, external-eoi, residential, document-sends, notifications, webhooks (~50 services) |
+| 15  | info         | Exhaustive e2e tests use `test.skip(true, ...)` as soft guards when fixtures absent        | intentional graceful-degrade pattern; not a bug                                                                                                                                          |
+
+### C3 — Observability + infra (10 findings: 2 high, 1 medium, 5 low, 2 info)
+
+| #   | Severity | Title                                                                                       | Evidence                                                                                                                                                                                                                        |
+| --- | -------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **high** | GDPR export bundles NOT deleted from storage on client hard-delete                          | `gdpr.ts:35` storageKey + `client-hard-delete.service.ts:241-244` — files.clientId collected, gdprExports.storageKey never queried; cascade kills DB row but blob orphans. **This is a gap in the A.7 RTBF fix shipped today.** |
+| 2   | **high** | NO RTBF/hard-delete path for `residential_clients`                                          | residential.ts schema holds equivalent PII to marina clients; zero hard-delete code path — no confirmation flow, no blob sweep, no audit, no API endpoint                                                                       |
+| 3   | medium   | `sentTo` key bypasses audit masker — operator email stored plaintext in audit_logs.metadata | `client-hard-delete.service.ts:139,466` — `sent_to` doesn't contain 'email' substring. Fix: add 'sent_to' fragment, or rename to `sentToEmail`                                                                                  |
+| 4   | low      | S3Backend `presignUpload`/`presignDownload` lack `withTimeout` wrappers                     | `s3.ts:289-297` — every other method (put/get/head/delete) is wrapped; presigns aren't. TCP-blackhole stall risk                                                                                                                |
+| 5   | low      | `error_events.errorMessage` and `errorStack` stored without PII redaction                   | error-events.service.ts:143-145 — ORM errors embedding WHERE-clause values persist as PII                                                                                                                                       |
+| 6   | low      | `'auth'` fragment over-masks: `authorId`, `isAuthenticated`, etc.                           | `audit.ts:125` — `'auth'` is too broad; should be `'authorization'` or use prefix match                                                                                                                                         |
+| 7   | low      | RTBF `website_submissions` erasure only matches top-level JSONB `email` key                 | `client-hard-delete.service.ts:221-224` — nested email payloads (`payload.contact.email`) survive                                                                                                                               |
+| 8   | low      | `hardDeleteCode` rate limiter fails open + `Math.random()` 4-digit code                     | combined attack surface during Redis outage; switch to `crypto.randomInt()` regardless                                                                                                                                          |
+| 9   | info     | `bulkHardDeleteClients` emits no composite audit log for the bulk action itself             | forensic correlation requires grouping N rows by timestamp; one bulk-level log entry would fix it                                                                                                                               |
+| 10  | info     | `requestBulkHardDeleteCode` loads ALL port clients into memory for validation               | `client-hard-delete.service.ts:408-419` — should `WHERE id IN (args.clientIds)`                                                                                                                                                 |
+
+### B4 — Webhooks + auth + storage (15 findings: 1 high, 6 medium, 5 low, 3 info)
+
+| #   | Severity | Title                                                                                                   | Evidence                                                                                                                                                      |
+| --- | -------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **high** | better-auth rate limiter uses in-memory storage — multi-replica prod bypasses limits                    | `auth/index.ts:128-137` — N replicas multiplies attempt budget N×; documented as known. Swap to `storage: database`                                           |
+| 2   | medium   | DOCUMENT_SIGNED route-level dedup hash never matches stored events — every retry re-enters handler      | `webhooks/documenso/route.ts:173 vs documents.service.ts:1184` — raw-body SHA vs prefixed-form hash, never matches; dedup intent broken                       |
+| 3   | medium   | Concurrent SIGNED webhooks both see `wasAlreadySigned=false`, both dispatch cascade invites             | `documents.service.ts:1130-1131,1196-1208` — read outside tx; handleDocumentCompleted has correct SELECT FOR UPDATE pattern but handleRecipientSigned doesn't |
+| 4   | medium   | Rate limiter fails open on Redis outage — auth brute-force protection disabled                          | `rate-limit.ts:57-73` — intentional; consider fail-closed + admin-IP allowlist escape hatch                                                                   |
+| 5   | medium   | `callbackURL` forwarded to better-auth without origin validation in sign-in-by-identifier               | `auth/sign-in-by-identifier/route.ts:63-96` — potential open redirect post-auth                                                                               |
+| 6   | medium   | `originAllowed()` returns true when both Origin AND Referer absent — non-browser CSRF check bypassed    | `proxy.ts:118-136` — SameSite=Strict is the real gate but defense-in-depth has a hole                                                                         |
+| 7   | medium   | Legacy plaintext Documenso webhook secrets may persist in `system_settings` — no migration enforcement  | `port-config.ts:469-472` — ports that never rotated retain cleartext                                                                                          |
+| 8   | low      | Storage proxy token `p` port-binding field is optional — tokens without `p` skip cross-port enforcement | `filesystem.ts:184-188,95-111` — future callers that omit portSlug mint cross-port tokens                                                                     |
+| 9   | low      | Storage proxy PUT magic-byte check is application/pdf only — other content types accepted blind         | `api/storage/[token]/route.ts:222-225` — png/jpg/csv/zip not inspected                                                                                        |
+| 10  | low      | Dev HMAC fallback derives storage proxy secret from `BETTER_AUTH_SECRET` — shared key in dev            | `filesystem.ts:430-432` — prod rejects but dev exposed→internet could forge tokens with auth key                                                              |
+| 11  | low      | CSP policy has no `report-uri`/`report-to` — XSS probes blocked silently                                | `proxy.ts:16-37` — adding `/api/csp-report` would give early-warning                                                                                          |
+| 12  | low      | sign-in-by-identifier timing oracle: email-format skips DB; username-format always hits DB              | very low practical impact; doesn't reveal whether identifier exists                                                                                           |
+| 13  | info     | better-auth's built-in rate limiter doesn't add `Retry-After` on 429                                    | direct `/api/auth/sign-in/email` lacks RFC 6585 compliance; sign-in-by-identifier wrapper has it                                                              |
+| 14  | info     | Session cookie lacks `__Host-` prefix — subdomain binding not enforced                                  | `auth/index.ts:106` — SameSite=Strict+Secure mitigate; `__Host-` would forbid Path other than `/`                                                             |
+| 15  | info     | `listDocumensoWebhookSecrets()` issues full DB SELECT on every webhook with no cache                    | `port-config.ts:456-501` — amplifies bad-secret flood scenario; short TTL cache fixes                                                                         |
+
+### C1 — EOI/Documenso services (15 findings: 3 high, 5 medium, 4 low, 3 info)
+
+| #   | Severity | Title                                                                                                                                     | Evidence                                                                                                                                                                                 |
+| --- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| 1   | **high** | `generateAndSignViaInApp` omits `portId` on all Documenso calls — per-port v1/v2 config bypassed                                          | `document-templates.ts:705,717` — portId optional → env fallback; v2-configured port uses v1 env defaults                                                                                |
+| 2   | **high** | custom-document-upload: `placeFields` called AFTER `documensoSend` — v2 envelope already PENDING when fields placed                       | `custom-document-upload.service.ts:285,294,323` — header comment documents correct order; code inverts. v2 may reject; all v2 contract/reservation uploads land with no signature fields |
+| 3   | **high** | `{{eoi.berthRange}}` and all `{{reservation.*}}` tokens in VALID_MERGE_TOKENS but resolveTemplate never populates them                    | merge-fields.ts:64-76 + document-templates.ts — tokens render as literal `{{...}}`; BR-140 doesn't catch because required:false                                                          |
+| 4   | medium   | `sendReminder` passes CRM document_signers.id (UUID) as Documenso recipient ID — v1 path sends invalid URL, v2 redistributes blindly      | `document-reminders.ts:161` + `documenso-client.ts:910` — v1 reminders consistently fail with 404; schema missing `documenso_recipient_id` column                                        |
+| 5   | medium   | `custom-document-upload` does not persist `documensoNumericId` — v2 webhook numeric-id resolution can't match                             | `custom-document-upload.service.ts:345` — contract/reservation uploads on v2 instance miss webhook events                                                                                |
+| 6   | medium   | `generateDocumentFromTemplate` v2: distribute failure swallowed — all signer rows get signingUrl=null with no auto-recovery               | `documenso-client.ts:554-560` + `document-templates.ts:843-884` — "Send invitation" button errors for every signer                                                                       |
+| 7   | medium   | `handleDocumentCompleted`: interest side-effects (dateEoiSigned, berth-rules) run outside try/catch and are not idempotent across retries | `documents.service.ts:1574-1621` — each failed-PDF retry re-stamps dateEoiSigned                                                                                                         |
+| 8   | medium   | `distributeEnvelopeV2` normalize call loses numericId — self-heal callers can't persist                                                   | `documenso-client.ts:618-623` — pattern from generateDocumentFromTemplate not followed                                                                                                   |
+| 9   | low      | `voidDocument` uses raw fetchWithTimeout without pRetry — transient 5xx/429 not retried                                                   | `documenso-client.ts:1289`                                                                                                                                                               |
+| 10  | low      | `completion_cc_emails` recipients have empty name — signing-completed email greeting malformed                                            | `documents.service.ts:1722` — "Dear ," fallback; should be email as display name                                                                                                         |
+| 11  | low      | `normalizeSignerRole` maps developer slot (order-2 SIGNER) to 'signer' not 'developer' — progress panel label wrong                       | `document-templates.ts:863-865,930-935`                                                                                                                                                  |
+| 12  | low      | `persistDocumentOverrides` source_document_id backfill uses 1-minute window — race if generation takes >60s                               | `eoi-overrides.service.ts:451,463,471` — widen to 5min or backfill by returned IDs                                                                                                       |
+| 13  | info     | `resolveTemplate` ValidationError catch regex includes dead branch 'interest has no (yacht                                                | berth)'                                                                                                                                                                                  | `document-templates.ts:317-322` — dead from prior design; remove for clarity |
+| 14  | info     | berth-range: non-canonical (passthrough) moorings always appended after sorted canonical segments                                         | `berth-range.ts:105-108` — cosmetic                                                                                                                                                      |
+| 15  | info     | `{{interest.notes}}` always empty in non-EOI (legacy) resolveTemplate path                                                                | `document-templates.ts:378` — silent blank in correspondence templates                                                                                                                   |
+
+### C2 — Domain services (15 findings: 1 high, 3 medium, 6 low, 5 info)
+
+| #   | Severity | Title                                                                                                      | Evidence                                                                                                                                                                                                                                                   |
+| --- | -------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **high** | Recommender: SQL vs JS stage-scale mismatch — Tier D fires one stage too early                             | `berth-recommender.service.ts:212,499-502,223,554` — JS LATE_STAGE_THRESHOLD=5 (deposit_paid in JS scale) vs SQL emits 5=reservation. Tier D fires at reservation, not deposit_paid. Berths with reservation-stage active interest hidden one stage early. |
+| 2   | medium   | `createNotification` dedup is non-atomic SELECT-then-INSERT with no DB unique constraint (TOCTOU)          | `notifications.service.ts:67-85,117` — concurrent inquiry fan-out can double-insert. Fix: partial unique on `(userId, type, dedupeKey)` + ON CONFLICT DO NOTHING                                                                                           |
+| 3   | medium   | `completeReminder` TOCTOU — concurrent calls both pass status guard, produce dup audit rows                | `reminders.service.ts:317-332` — no `WHERE status='pending'` in UPDATE; no advisory lock                                                                                                                                                                   |
+| 4   | medium   | `processFollowUpReminders` lacks advisory lock — concurrent workers double-insert auto-generated reminders | `reminders.service.ts:428-517` — 3 non-tx round-trips; `processOverdueReminders` has the right pattern, this one doesn't                                                                                                                                   |
+| 5   | low      | `createNotification` with inApp=false + email=true silently drops the email                                | `notifications.service.ts:107-113` — acknowledged in comment but untracked gap                                                                                                                                                                             |
+| 6   | low      | `public-interest` creates interest with legacy `pipelineStage='open'` instead of `'enquiry'`               | `public-interest.service.ts:233` — modern stage is `enquiry`; column default agrees                                                                                                                                                                        |
+| 7   | low      | `public-interest` berth lookup outside transaction — FK violation on race-deleted berth                    | `public-interest.service.ts:79-87,237-244`                                                                                                                                                                                                                 |
+| 8   | low      | `public-interest` no yacht dedup — re-submissions create duplicate yacht records                           | `public-interest.service.ts:177-203` — client + company dedup'd; yacht isn't                                                                                                                                                                               |
+| 9   | low      | `inquiry-notifications.findUsersWithInterestsPermission` has no deactivated-user filter                    | `inquiry-notifications.service.ts:149-168` — deactivated users still receive new_registration alerts                                                                                                                                                       |
+| 10  | low      | Rules engine suggest-mode unconditionally calls `createAuditLog` — audit flood on webhook retries          | `berth-rules-engine.ts:102-117,201-207`                                                                                                                                                                                                                    |
+| 11  | low      | interest-berths cross-port guard silently passes when interestId doesn't exist                             | `interest-berths.service.ts:232-244` — should throw NotFoundError explicitly                                                                                                                                                                               |
+| 12  | info     | `processOverdueReminders` un-snooze + claim are two non-tx UPDATEs — survivable, no fix required           | at-least-once semantics                                                                                                                                                                                                                                    |
+| 13  | info     | Dynamic import in `removeInterestBerth` is still required (cycle break)                                    | `interest-berths.service.ts:356-361` — not stale                                                                                                                                                                                                           |
+| 14  | info     | Inconsistent `evaluateRule` import style — static vs dynamic across files                                  | maintenance hazard; documenting needed                                                                                                                                                                                                                     |
+| 15  | info     | `STAGE_ORDER.completed=6` in recommender JS is dead code — SQL CASE never emits 'completed'                | misleads maintainers                                                                                                                                                                                                                                       |
+
+### D1 — Jobs/queue/cron (8 findings: 3 critical, 1 high, 2 medium, 2 low)
+
+| #   | Severity     | Title                                                                                                    | Evidence                                                                                                                                                                                                                                                   |
+| --- | ------------ | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **CRITICAL** | `send-invoice` + `invoice-overdue-notify` dispatched to queues WITH NO WORKER HANDLER                    | `invoices.ts:597-600,740-743` — both fall to default branch, log "Unknown … job", complete successfully. **Every invoice send AND every overdue check is a silent no-op.**                                                                                 |
+| 2   | **CRITICAL** | 5 maintenance cron jobs scheduled but unimplemented — silent no-ops with false-green audit               | scheduler.ts: `calendar-sync`, `database-backup`, `backup-cleanup`, `session-cleanup`, `temp-file-cleanup` — workers/maintenance.ts has no case for any. **database-backup is the dangerous one.** RECURRING_JOB_NAMES contains them so audit shows green. |
+| 3   | **CRITICAL** | `tenure-expiry-check` scheduled, in RECURRING_JOB_NAMES, but has no handler and no service               | scheduler.ts:32 — daily 08:00 schedule; workers/notifications.ts no case; no `tenure-expiry` service exists                                                                                                                                                |
+| 4   | high         | `processDocumensoPoll` TOCTOU race — concurrent ticks can double-fire cascading invite email             | `jobs/processors/documenso-poll.ts:46-47` — wasAlreadySigned read outside tx; documents queue concurrency=3 with 5-min poll → overlapping ticks plausible                                                                                                  |
+| 5   | medium       | `documenso-void` enqueued without natural-key jobId at both archive call sites                           | `clients/[id]/archive/route.ts:95`, `clients/bulk/route.ts:180` — double-archive enqueues two void jobs; second hits already-voided envelope → spurious dead-letter                                                                                        |
+| 6   | medium       | `report-scheduler` `nextRunAt` UPDATE not transactional with job enqueue — crash silently drops a period | workers/reports.ts — 3 separate round-trips; crash between A and C skips the period                                                                                                                                                                        |
+| 7   | low          | `bounce-poll` absent from RECURRING_JOB_NAMES — no cron_run audit row on successful ticks                | audit-helpers.ts:27-49 — operators can't detect stalled poller via audit log                                                                                                                                                                               |
+| 8   | low          | maintenance queue concurrency=1 with HOL-blocking risk                                                   | analytics-refresh + bounce-poll can starve alerts-evaluate (every 5min) — split into fast/slow queues                                                                                                                                                      |
+
+### F2 — Performance (8 findings: 3 high, 5 medium)
+
+| #   | Severity | Title                                                                                                           | Evidence                                                                                                                                      |
+| --- | -------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **high** | `getClientById`: 6 independent DB queries run SEQUENTIALLY on hot client detail path                            | `clients.service.ts:358,363,368,374,392,415` — 7 serial round-trips per page load; should be `Promise.all([...6])` after gating client lookup |
+| 2   | **high** | `notification-digest`: nested port×user loops → O(ports × users) sequential queries + emails                    | `notification-digest.service.ts:71,74,109,113` — per port: 6+ queries; per user: 1 query + 1 send, all serial. Ports + users are independent  |
+| 3   | **high** | Missing index on `interests.reminder_enabled` — `processFollowUpReminders` full-scans active interests per port | `reminders.service.ts:432-441` — no existing index covers `(portId, reminderEnabled) WHERE archived_at IS NULL`                               |
+| 4   | medium   | `reconcileAlertsForPort`: N individual INSERTs + N UPDATEs per alert-engine evaluation                          | `alerts.service.ts:53-80,89-99` — batch INSERT ... ON CONFLICT DO NOTHING RETURNING; UPDATE WHERE id IN (...)                                 |
+| 5   | medium   | `client-archive-dossier`: N DB queries inside loop over `distinctBerthIds`                                      | `client-archive-dossier.service.ts:244,252` — single query WHERE berthId IN (...) + JS group                                                  |
+| 6   | medium   | `email_threads`: no compound `(portId, lastMessageAt)` index — list endpoint forces filesort                    | `email.ts:57` — only `idx_et_port` covers portId; sort step grows with thread volume                                                          |
+| 7   | medium   | `createPending` (berth-reservations): 3 independent tenant-validation lookups serial                            | `berth-reservations.service.ts:95,100,105` — berth/client/yacht should be `Promise.all`                                                       |
+| 8   | medium   | `webhook-dispatch`: sequential INSERT + BullMQ enqueue per matching webhook                                     | `webhook-dispatch.ts:47-75` — batch the inserts (RETURNING id), then Promise.all the queue.adds                                               |
+
+### A1 — Schema: people/orgs (audited inline; agent stuck) (12 findings: 1 high, 6 medium, 5 low)
+
+| #   | Severity | Title                                                                                                                                                     | Evidence                                                                                                                                                                   |
+| --- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **high** | `yachts.currentOwnerType`/`currentOwnerId` polymorphic — NO CHECK constraint on the type discriminator                                                    | `yachts.ts:44-45` — `currentOwnerType` is bare text; a value other than `'client'`/`'company'` silently corrupts ownership resolution downstream                           |
+| 2   | medium   | `clients.mergedIntoClientId` self-FK lives in migration 0042 only — `db:push` drift (same pattern as A3 #5)                                               | `clients.ts:53-58` — Drizzle's table builder doesn't accept self-references in column factory; constraint missing from db:push schema                                      |
+| 3   | medium   | `clients.sourceInquiryId` FK lives in migration 0065 only — `db:push` drift                                                                               | `clients.ts:33-38` — comment acknowledges the gap; fresh db:push skips it                                                                                                  |
+| 4   | medium   | `clientAddresses.label='Primary' default` + `isPrimary=true default` conflicts                                                                            | `clients.ts:250,258` — every new address is "primary" by default; partial unique `idx_ca_primary` then rejects the second. Either flip the default or fail less surprising |
+| 5   | medium   | No DB CHECK on `clients.preferredContactMethod` enum (email/phone/whatsapp)                                                                               | `clients.ts:27`                                                                                                                                                            |
+| 6   | medium   | No DB CHECK on `yachts.status` enum (active/retired/sold_away)                                                                                            | `yachts.ts:46`                                                                                                                                                             |
+| 7   | medium   | `companyMemberships.role` no DB CHECK on enum (director/officer/broker/representative/legal_counsel/employee/shareholder/other)                           | `companies.ts:65`                                                                                                                                                          |
+| 8   | low      | `clientNotes.authorId`, `yachtNotes.authorId`, `companyNotes.authorId` all bare text — no FK to user                                                      | `clients.ts:149`, `yachts.ts:107`, `companies.ts:126` — dangling on hard user delete                                                                                       |
+| 9   | low      | `clients.archivedBy` bare text — no FK to user; same dangling-on-delete pattern                                                                           | `clients.ts:41`                                                                                                                                                            |
+| 10  | low      | `clientTags.tagId`, `yachtTags.tagId`, `companyTags.tagId` — bare text, comment-only FK to tags                                                           | `clients.ts:165`, `yachts.ts:123`, `companies.ts:142` — same gap as A2 #7 for pipeline tables                                                                              |
+| 11  | low      | `yachtOwnershipHistory` has no DB-level guard that `startDate ≤ endDate`                                                                                  | `yachts.ts:83-84` — date inversion possible without CHECK                                                                                                                  |
+| 12  | low      | `yachts.lengthFt`/`lengthM`/`lengthUnit` denormalized triple — no DB-level invariant that lengthUnit aligns with which of (lengthFt, lengthM) is non-null | `yachts.ts:32-43` — service layer can write `lengthUnit='ft'` while `lengthFt=null`; produces broken display                                                               |
+
+### F1 — Cross-cut: security (audited inline; agent stuck) (4 findings: 1 medium, 3 low)
+
+The cross-cutting security audit is partly redundant with B1/B4/C3 findings already reported. Only NEW issues here:
+
+| #   | Severity | Title                                                                                                                                        | Evidence                                                                                                                                                                                                    |
+| --- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | medium   | `send-document-dialog.tsx` lines 248 + 274 use `dangerouslySetInnerHTML` for previewHtml — verify `renderEmailBody()` allowlist sanitization | `send-document-dialog.tsx:248,274` — flows from API; `renderEmailBody` documented escape-then-allowlist, but the dialog's preview path needs explicit audit to confirm no untrusted HTML leaks              |
+| 2   | low      | Many `findFirst` queries in services without explicit `port_id` filter — depends on FK chain                                                 | examples: `notes.service.ts:767`, `email-threads.service.ts:68,101,106,144,177,255` — defense-in-depth gap; FK joins enforce isolation but a direct call from a route bypassing service wrappers could leak |
+| 3   | low      | 136 raw `sql\`\`` template literals in services — manual review-worthy for SQLi                                                              | full sweep not done; spot-checks at known sites (berth-recommender, search) use parameterized `${}` interpolation via Drizzle                                                                               |
+| 4   | info     | Most other security surfaces already covered by B1/B4/C3 reports above                                                                       | see `cross-references`                                                                                                                                                                                      |
+
+### B3 — v1 entity CRUD (audited inline; agent stuck) (3 findings, structurally clean)
+
+Spot-check across 303 v1 route files: **structurally healthy.** Sample at `/api/v1/clients/route.ts` is exactly the documented pattern — `withAuth(withPermission(resource, action, async (req, ctx) => { try { parseBody/parseQuery + service call; return {data}; } catch (error) { return errorResponse(error); } }))`. No bare route handlers found.
+
+| #   | Severity | Title                                                                                                                                                         | Evidence                                                                                          |
+| --- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 1   | low      | `handlers.ts` sibling pattern means grep for missing withAuth needs to skip them                                                                              | not a finding per se, just a noting that the testability split documented in CLAUDE.md is honored |
+| 2   | low      | Pagination shape on `/api/v1/clients` returns `{data, pagination: {...}}` but list endpoints elsewhere return `{data, total, hasMore}` (CLAUDE.md convention) | `clients/route.ts:18-28` — minor shape drift; not breaking but lists aren't uniform               |
+| 3   | info     | Most B3 quality findings already covered by B1 (port validation), C2 (race + dedup), C3 (audit gaps)                                                          | this scope was already well-covered                                                               |
+
+### E1 — Admin UI (agent stuck; not audited)
+
+The admin-ui agent went idle 4 times across multiple pings. The most likely interpretation is that the surface is large enough that even Sonnet 1M's context was filled before a useful answer landed. **E1 should be re-spawned with a much narrower scope (one page at a time) or audited inline in a follow-up pass.**
+
+### E2 — Entity UI (agent stuck; not audited)
+
+Same pattern as E1. Entity-tab UI surface across 5 entity types is large; the agent didn't complete. **Re-spawn with narrower scope (one entity-detail page per agent) or defer.**
+
+---
+
+## Triage + recommended order of operations
+
+After 13 reported audits + 2 inline (A1, F1, B3 sketch), here are the items that should ship before the next deploy, grouped by impact and effort.
+
+### 🚨 Tier S — ship-stopping production bugs (do today)
+
+These are silently broken in production right now. Fix before any further work.
+
+| Source    | Item                                                                                                                                               | Effort                                                                                          |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| **D1 #1** | `send-invoice` and `invoice-overdue-notify` BullMQ jobs have no handler → every invoice send is a no-op                                            | 1-2h: add the cases to workers/email.ts and workers/notifications.ts                            |
+| **D1 #2** | 5 maintenance cron jobs (calendar-sync, database-backup, backup-cleanup, session-cleanup, temp-file-cleanup) silently no-op with false-green audit | 2-3h each; **database-backup is the dangerous one** — implement or remove the schedule          |
+| **D1 #3** | `tenure-expiry-check` cron silently no-ops; service was never written                                                                              | 2-3h: write the service + handler                                                               |
+| **C3 #1** | A.7 RTBF gap: `gdpr_exports.storage_key` blobs NOT deleted on client hard-delete (this is a gap in code shipped today)                             | 30min: extend `client-hard-delete.service.ts` to collect gdprExports.storageKey alongside files |
+| **C3 #2** | No RTBF/hard-delete path for `residential_clients` — full PII shadow                                                                               | 4h: mirror the marina hard-delete service for residentialClients                                |
+| **B1 #1** | `/api/public/interests` does NOT validate caller-supplied `portId` against existing ports — cross-tenant data injection                            | 30min: copy the residential-inquiries pre-check                                                 |
+| **A3 #1** | `documents.documenso_id` has NO index — every webhook delivery is a full table scan                                                                | 30min: migration adding index                                                                   |
+
+### 🔴 Tier 1 — high severity, prioritize this week
+
+| Source             | Item                                                                                                                                | Effort                                                                  |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| **B4 #1**          | better-auth rate limiter is in-memory; multi-replica prod multiplies auth limits N×                                                 | 2h: switch to `storage: 'database'` after running its migration         |
+| **C1 #1**          | `generateAndSignViaInApp` omits portId on Documenso calls → v2-configured port silently uses v1 env defaults for every in-app EOI   | 30min: thread portId through 2 calls                                    |
+| **C1 #2**          | custom-document-upload calls `placeFields` AFTER `documensoSend` (wrong order) — v2 may reject placement on PENDING envelope        | 30min: reorder                                                          |
+| **C1 #3**          | `{{eoi.berthRange}}` + all 5 `{{reservation.*}}` tokens valid but unresolved — render as literal `{{...}}`                          | 2h: populate from EoiContext.eoiBerthRange + add reservation resolver   |
+| **C2 #1**          | Recommender SQL vs JS stage-scale mismatch — Tier D fires at reservation, not deposit_paid                                          | 30min: change LATE_STAGE_THRESHOLD=6 to match SQL scale                 |
+| **F2 #1-3**        | 3 high-impact perf: getClientById serial queries, notification-digest sequential loops, missing index on interests.reminder_enabled | 4h total                                                                |
+| **F3 #1-2**        | client-hard-delete has zero tests; no CI/CD pipeline                                                                                | 4h: integration tests for the RTBF flow; add `.github/workflows/ci.yml` |
+| **A2 #1-3, A1 #1** | Missing DB-level CHECK constraints on every enum-shaped text column                                                                 | 2h: one consolidated migration                                          |
+
+### 🟠 Tier 2 — medium severity (next sprint)
+
+Covers the bulk of remaining medium findings — too many to expand inline; see per-agent tables above. Highlights: drift between schema and migrations (A3 #4-5, A1 #2-3), idempotency gaps in webhook handlers (B4 #2-3, C1 #7, D1 #4), audit/IP/UA gaps in admin mutations (B2 #7-10), and the camelCase-key over-masking false-positive on `'auth'` fragment (C3 #6).
+
+### 🟡 Tier 3 — low severity (rolling)
+
+Index optimizations, validation tightening, schema metadata gaps, log cleanup. The detailed tables per agent above carry the per-item file:line evidence.
+
+### 📋 Tier 4 — re-spawn or inline-audit
+
+- E1 (admin UI) and E2 (entity UI) agents failed; the surface is too large for a single Sonnet 1M spawn. Re-spawn narrower (one page or one entity per agent), or audit inline in a follow-up.
+
+---
+
+## Total finding counts
+
+| Severity           | Count   |
+| ------------------ | ------- |
+| CRITICAL           | 5       |
+| high               | 15      |
+| medium             | 36      |
+| low                | 53      |
+| info               | 19      |
+| **Total findings** | **128** |
+
+Across **13 of 16 agent reports** + 3 inline (A1/F1/B3). E1 + E2 are missing; should be re-attempted later.

docs/superpowers/audits/2026-05-21-remaining-plan.md

@@ -0,0 +1,242 @@
+# Remaining UAT Master Doc — Work Plan
+
+> **STATUS (2026-05-21 23:55):** Groups A–T worked through end-to-end.
+> Group U (EOI bundle UX rework) explicitly deferred — see note at the
+> bottom. Per-group commits:
+>
+> - **A** `e33313b` + doc annotations `670ca16`
+> - **B** `7ecf4ee` + doc annotations `a0a4a5d`
+> - **C** `991e222`
+> - **D + E** `431375d`
+> - **F + G + H** `94c24a1`
+> - **I** `989cc4d`
+> - **J + K** `03a7521`
+> - **L** `65ff596`
+> - **M** `0ddaf46`
+> - **N** `a147cbc`
+> - **O** `a7cbee0`
+> - **P** `0ed03fc`
+> - **Q** `c14f80a`
+> - **R + T** `aa1f5d2`
+> - **U** parked
+>
+> Each commit message documents what shipped vs. what stayed parked.
+> Vitest 1454/1454 and tsc clean across every group.
+>
+> **Source:** `alpha-uat-master.md` (Bucket 1-4) as of commit `d879188`. Survey done 2026-05-21 after the PDF report exporter ship.
+>
+> **Status:** scaffold for sequential execution. Each item has a scope summary, file pointers (copied from the source entry where helpful), effort estimate, and explicit ordering notes (blocks-on / pairs-with). Items are grouped so logically-related work lands as one PR rather than scattered.
+
+## How to use this doc
+
+- Items are in **suggested execution order** (top → bottom). Order optimises for (a) unblocking other items, (b) low-cost-high-impact wins first, (c) defer-until-design large features to the end.
+- Each item is one of:
+  - **Q** — quick fix (< 30 min)
+  - **M** — medium (30 min – 2 h)
+  - **L** — large (2 h+)
+  - **DEFERRED** — captured but blocked / waiting on external decision
+- We work top to bottom. When an item lands, annotate it in `alpha-uat-master.md` with the SHIPPED-in-commit line AND tick it off here.
+
+---
+
+## Group A — Tiny copy / UI fixes — [SHIPPED in e33313b]
+
+All 12 items closed. 7 new ships + 5 verified pre-shipped (annotation gap in master doc).
+
+1. **[SHIPPED — e33313b]** Admin Documenso settings env-fallback pills — collapsed legacy SettingsFormCard blocks into RegistryDrivenForm sections (`documenso.behavior` + `documenso.templates`).
+2. **[SHIPPED — e33313b]** WatchersCard empty-state padding — `mb-3` → `mb-4 pb-1`.
+3. **[SHIPPED — 52342ee, verified]** EOI "Mark as signed without file" button — already in place.
+4. **[SHIPPED — e33313b]** /invoices/upload-receipts copy rewrite — ~50% body-copy reduction, terse luxury-CRM voice.
+5. **[SHIPPED — e33313b]** Pageviews X-axis ticks — `interval="preserveStartEnd"` + `minTickGap={52}`.
+6. **[SHIPPED earlier, verified]** Pageviews vs Sessions explainer — Info popover already in `website-analytics-shell.tsx`.
+7. **[SHIPPED — e33313b]** Inbox section order — docstring fixed; JSX already had Reminders before Alerts.
+8. **[SHIPPED earlier, verified]** BulkAddBerthsWizard CurrencySelect — already wired at apply-to-all + per-row.
+9. **[SHIPPED — e33313b]** CommandList scroll-cap — `max-h-[min(300px,var(--radix-popover-content-available-height,300px))]`.
+10. **[SHIPPED — e33313b]** DropdownMenu max-h cap — `max-h-[min(24rem,var(--radix-dropdown-menu-content-available-height,24rem))]`.
+11. **[SHIPPED — e33313b]** Residential InterestsTab whole-row navigate — `<tr onClick>` + first-cell Link stopPropagation.
+12. **[SHIPPED — e33313b]** StageStepper visible stage names — stage-name row below the bar; `size="xs"` hides labels.
+
+---
+
+## Group B — Interest detail polish (~2 h total)
+
+Surfaces all touch `interest-tabs.tsx` / `interest-overview` / linked-berths. Grouping keeps the diff focused on one entity.
+
+13. **[M] Inbox → Reminders: move filter row inline with the "New Reminder" button (embedded mode)** — _src/components/reminders/reminders-list.tsx_. Add an `embedded?: boolean` prop that consolidates the filter row + the New button into one row when set. ~45 min.
+14. **[M] Interest Overview Email + Phone rows: combobox picker across client's contacts + quick-add new contact** — _src/components/interests/interest-tabs.tsx_ + _src/components/clients/client-contacts-picker.tsx (new)_. The Email + Phone rows on the Overview currently show only the primary; reps want to pick any of the client's contacts and add new ones inline. ~1 h.
+15. **[M] Inline phone editor on the Contact row** — adjacent to #14; add `InlineEditableField variant="phone"` (or similar) using the country-code + national-number split. ~30 min.
+16. **[M] Client Overview should summarize current interest's requirements** — one-line "current interest needs L × W × D, source X" on the Client detail Overview tab. ~30 min.
+17. **[M] Notes Latest-note teaser missing round / stage context pill** — _src/components/interests/interest-tabs.tsx_ around the latest-note teaser. Pull the stage at the time of the note (from `audit_logs`) and render as a chip next to the timestamp. ~45 min.
+18. **[M] InterestBerthStatusBanner: name + link the competing deal** — _src/components/interests/interest-berth-status-banner.tsx_. Today says "this berth is also linked to another interest"; should name the client + link to the interest. ~30 min.
+19. **[M] Qualification auto-confirm "intent confirmed" once stage ≥ EOI (extend `computeAutoSatisfied`)** — _src/lib/services/qualification.service.ts_. Add the auto-confirm rule. Most of the work shipped earlier; this is the final tightening. ~30 min.
+
+**Commit shape:** one PR titled `feat(uat-batch): Interest detail polish (Group B — 7 items)`.
+
+---
+
+## Group C — Berth list features (~2.5 h)
+
+20. **[M] Berth list: hide "Rates (USD)" + "Pricing valid" columns by default (or remove)** — _src/components/berths/berth-columns.tsx_ + `BERTH_DEFAULT_HIDDEN`. Short-term rental fields irrelevant to purchase/long-term ports. Update default visibility; do not remove columns (other ports may still use them). ~10 min.
+21. **[M] Dimensions columns: add ft↔m toggle in the column header (persisted to user prefs); skip per-row entry-unit indicator** — _src/components/berths/berth-columns.tsx_, _src/components/yachts/yacht-columns.tsx_, _src/components/clients/client-yachts-tab.tsx_, _src/components/companies/company-owned-yachts-tab.tsx_, plus _new_ `src/lib/utils/dimensions.ts` for the conversion + format helper, and _src/lib/db/schema/users.ts_ `user_profiles.preferences` for the persisted preference key. ~1 h.
+22. **[M] ft ↔ m unit switching on Berth Requirements** — _src/components/interests/interest-tabs.tsx_ — the three inline-editable dim rows hard-code `(ft)` in the label. The interest already carries `desiredLengthUnit`; honour it. ~30 min.
+23. **[L] Berth list: bulk-edit affordance (parity with bulk-add)** — _src/components/berths/_, _src/lib/services/berths.service.ts_, _new endpoint_ `POST /api/v1/berths/bulk`. Backend mirrors `/interests/bulk` shape; UI gets a `DataTable bulkActions` toolbar. ~5-7 h. **Pairs with:** Bucket 3 #2 Bulk-price editing UI — the inline-price-edit + bulk-price-sheet should land alongside this. Combined effort ~7-10 h.
+
+**Commit shape:** two PRs — `feat(berths): dimensions column toggle + hide rental columns` (B-20/21/22), `feat(berths): bulk-edit + bulk-price UI` (B-23 + Bucket 3 #2).
+
+---
+
+## Group D — BulkAddBerthsWizard polish (~1.5 h)
+
+24. **[M] BulkAddBerthsWizard + single-berth editor: toggleable input units (ft/m) for dimension fields** — _src/components/admin/bulk-add-berths-wizard.tsx_ + _src/components/berths/berth-form.tsx_. Tiny segmented toggle above the dimension inputs (ft / m). Convert on submit so the canonical column stays consistent. ~45 min.
+25. **[M] BulkAddBerthsWizard: allow defining new dock/pontoon letters in-flow (or surface the admin path)** — _src/components/admin/bulk-add-berths-wizard.tsx_. Currently fixed to A/B/C/D/E. Add "+ New letter" affordance or a clear "manage letters in /admin/vocabularies" link. ~30 min.
+
+**Commit shape:** one PR titled `feat(berth-admin): wizard polish (Group D)`.
+
+---
+
+## Group E — Supplemental-info-request (~1 h)
+
+26. **[M] Supplemental-info-request: distinct Regenerate vs Resend actions + issue history** — _src/components/interests/supplemental-info-request-button.tsx_. Today's UI has a single Generate + Send button; add: Regenerate (new token, invalidates old), Resend (re-email existing token), and a small history list of past issuances + their status. Builds on what `a4e30ea` already shipped (generate vs send split). ~1 h.
+
+**Note:** Supplemental-info-request _separate generate link and send email_ + _link reusable_ already SHIPPED (a4e30ea, b74fc56).
+
+---
+
+## Group F — DocumentsHub + signing flow polish (~3 h)
+
+27. **[M] DocumentsHub: hide breadcrumb on root "All documents" view, move PageHeader up** — _src/components/documents/hub-root-view.tsx_ + the surrounding shell. Conditional render. ~30 min.
+28. **[M] Past-milestones strip → expandable history with inline doc preview** — _src/components/interests/interest-tabs.tsx_ around line 863 (past-milestones strip). Convert to accordion; each past milestone expands to show its associated docs + sub-status timeline + inline PDF preview using the existing pdf-viewer primitive. ~3-4 h.
+29. **[M] Watchers configurable at document creation time** — _src/components/documents/eoi-generate-dialog.tsx_, _src/components/documents/upload-for-signing-dialog.tsx_, _src/components/interests/external-eoi-upload-dialog.tsx_, _src/components/documents/create-document-wizard.tsx:157_ + service-side defaults. ~1.5 h.
+
+---
+
+## Group G — Admin sections consolidation (~6 h)
+
+30. **[L] Merge `/admin/invitations` into `/admin/users`** — _src/app/(dashboard)/[portSlug]/admin/users/page.tsx_, _src/app/(dashboard)/[portSlug]/admin/invitations/page.tsx_ (to be removed), _src/components/admin/users/_, _src/components/admin/admin-sections-browser.tsx:90-95_. Add a state filter `All | Active | Invited (pending) | Disabled | Archived`. Default to Active. ~3-4 h.
+31. **[L] Consolidate every AI-feature admin control onto `/admin/ai`** — _src/app/(dashboard)/[portSlug]/admin/ai/page.tsx_ + per-feature embedded forms. Berth PDF parser AI fallback, AI/OCR pipeline, plus deferred sections (recommender embeddings, contact-log extraction, inquiry parsing). Berth PDF parser AI fallback is the only currently-LLM-using feature without a section — surface its provider override, confidence threshold, per-call budget cap. ~2 h for the present one + UI hooks for the deferred sections.
+
+---
+
+## Group H — Email + branding (~2 h)
+
+32. **[M] Email settings page: add explainer copy clarifying why sales send-from and noreply have separate credentials** — _src/app/(dashboard)/[portSlug]/admin/email/page.tsx_ — small description block. ~15 min.
+33. **[L] Supplemental-info-request email: branded HTML styling** — _src/lib/email/templates/_ — rebuild the template to match the table-based, max-width 600, logo + blurred overhead background look. ~1-2 h.
+
+---
+
+## Group I — Residential parity (~10 h, single coordinated PR)
+
+34. **[M] Residential client detail header: match the main ClientDetailHeader layout** — _src/components/residential/residential-client-detail-header.tsx_ + _src/components/clients/client-detail-header.tsx_. Restructure. ~1 h.
+35. **[L] Residential interests list: visual + functional parity with the main InterestList** — _src/components/residential/residential-interests-list.tsx_ vs _src/components/interests/interest-list.tsx_. Card / table / kanban view modes, full FilterBar, ColumnPicker, bulk actions, realtime invalidation, kebab actions. ~6-8 h.
+36. **[L] Residential inquiry → auto-forward to external partner email(s)** — _src/lib/services/residential.service.ts_ + admin settings UI + new template + BullMQ enqueue. ~2-3 h.
+37. **[L] Auto-link residential interests to existing main-client records (same person)** — schema migration + service join + UI surfaces on both sides + backfill script. ~3-4 h.
+
+---
+
+## Group J — Activity feed + EntityActivityFeed (~2 h)
+
+38. **[M] EntityActivityFeed: rewrite per-row rendering to surface _what_ changed** — _src/components/shared/entity-activity-feed.tsx_. Current rows are flat "user X did Y"; rewrite to show the field-level diff (`old → new`) using the existing audit-log diff shape. ~2 h.
+39. **[M] Client → Companies tab: add CTA to link or create a company membership** — _src/components/clients/client-companies-tab.tsx_. Empty-state CTA + dialog. ~1 h.
+
+---
+
+## Group K — OnboardingChecklist + nudges (~6-8 h, single big PR)
+
+40. **[L] OnboardingChecklist: auto-check resolver-chain fix + super_admin discoverability** — _src/components/admin/onboarding-checklist.tsx_ + _src/lib/services/port-config.ts_ + new dashboard tile + new topbar banner. Two linked issues:
+    - **(a)** Replace each `autoCheckSettingKey` with an `autoCheckResolver` function that runs the full resolver chain and returns `true` when the functional config is complete. Belt-and-braces: surface what's resolving from where ("Email: ✓ Using global SMTP" vs "Per-port override").
+    - **(b)** Topbar banner (slim chip "Setup X% complete · Continue →" dismissible per-session), dashboard rail tile "Continue setup", in-app weekly notification, 🎉 100% celebration. Gate all on `super_admin`.
+
+---
+
+## Group L — UploadForSigningDialog comprehensive rework (~12-16 h, dedicated PR)
+
+41. **[L] UploadForSigningDialog comprehensive rework — 4 linked issues** — Documenso PDF preview rebuild, metadata + draft persistence, dialog width responsive sizing, field-placement UX. Bundles with Documenso v2 follow-ups. Single coordinated PR.
+
+---
+
+## Group M — Universal preview + form-templates (~12-16 h)
+
+42. **[L] Universal in-system preview for every file type** — extend FilePreviewDialog beyond PDF + images. .docx / .xlsx / .pptx via google-doc-viewer iframe or libreoffice headless; .txt / .csv / .md inline; .eml / .msg via mailparser; .zip see-into. ~6-10 h.
+43. **[SHIPPED in 91be0f9] Form-template fields bind to Interest/Client data — autofill, override-preservation history, dual-surface audit trail** — `bindable-fields.ts` catalog + `formFieldSchema.bindTo` allow-list + admin sheet "Bind to" picker; `applySubmission` extended to write phone + yacht diffs (was silently updating) and address-insert overrides; `/api/v1/clients/[id]/field-history` mirror endpoint; `<FieldHistoryProvider>` + `<FieldHistoryIcon>` mount on Client + Interest Overview tabs and ContactsEditor. Note: addresses tab + yacht detail surface still need the icon wired (5-min follow-up).
+
+---
+
+## Group N — Dashboard upgrades (~10-14 h)
+
+44. **[L] Pipeline Value tile should respect dashboard timeframe** — Dashboard-wide timeframe context (Zustand store or React Query keyed by range); forecast/KPI service variants accept a `range`; "realized vs forecast" line. ~3-4 h.
+45. **[L] "Clients by country" dashboard widget** — compact ranked list with mini bars per row, deep-link `/clients?country=DE`. ~2-3 h.
+46. **[L] Drag-and-drop rearrangable dashboard widgets** — extend `useDashboardWidgets` to read a `dashboardWidgetOrder` preference; `@dnd-kit/core` + `@dnd-kit/sortable`; persist via PATCH `/api/v1/me/preferences`. ~4-6 h.
+
+---
+
+## Group O — Umami analytics phases 3 / 4 / 5 (~14-18 h)
+
+47. **[L] Umami Phase 4a — Marketing-site instrumentation** — _BLOCKS Phase 3 + Phase 5._ Wire `umami.track()` calls into the marketing site for every CRM event we want to surface (inquiry submitted, brochure download, contact-form, etc.). ~3-4 h on the marketing-site repo + alignment with this repo.
+48. **[L] Umami Phase 4c UI — Tracked-link composer button** — _src/components/email/email-composer.tsx_ or wherever the rep writes a templated email; add a button that opens a tracked-link composer + injects the resulting URL. ~2-3 h.
+49. **[L] Umami Phase 3 — Events tab** — _src/components/website-analytics/events-list.tsx (new)_. Blocked on 4a. ~3-4 h.
+50. **[L] Umami Phase 5 — Funnels + Journeys** — Funnel builder + journey-flow sankey. Blocked on 4a. ~6-8 h.
+51. **[M] Umami: Empty-state nudges on quiet ranges** — _src/components/website-analytics/_. Stable copy when the range has < N events ("Nothing happened here; try a wider range"). ~30 min.
+52. **[M] Umami: Apple Mail privacy disclaimer copy** — _src/components/email/email-open-rate-pill.tsx_ — small tooltip explaining that Apple Mail Privacy Protection inflates open rates. ~15 min.
+53. **[M] Umami: Open-rate column on the document_sends list** — _src/components/documents/document-sends-list.tsx_. New column reading the per-send open count. ~30 min.
+54. **[M] Umami: Click-to-filter the page from the world map** — _src/components/website-analytics/visitor-world-map.tsx_. Wire `onCountryClick(iso2)` into a new country filter store + thread through every `useUmami*` hook. ~2-3 h.
+55. **[M] Umami: Verify pixel + tracked-link end-to-end with a real send** — manual UAT. ~15 min once 4a is live.
+
+---
+
+## Group P — Nested document subfolders — phases 2/3 (~5-6 h)
+
+56. **[L] Nested document subfolders — phases 2 and 3** — foundation shipped in `e91055f`. Remaining:
+    - **(a)** UploadZone gains `scopeOptions` radio: "This deal (Interest <name>)" vs "Client-level (all deals)". Single-scope contexts (client/yacht/company) hide the radio.
+    - **(b)** Lifecycle hooks: interest outcome → folder rename (`Deal A1-A3 (Won)`); soft-rescue on outcome change.
+    - **(c)** `listFilesAggregatedByEntity` rewrite — surface BOTH "This deal" subheading + "From client" subheading on the InterestDocumentsTab "Attachments" list.
+    - **(d)** Documents Hub tree rendering for nested interest folders + outcome chip per interest folder.
+    - **(e)** Backfill script `pnpm tsx scripts/backfill-nested-document-folders.ts --apply` — idempotent, per-port advisory-locked.
+
+---
+
+## Group Q — Platform-wide refactors (~14-18 h, do as coordinated passes when time allows)
+
+57. **[L] Platform-wide chart library migration: recharts → ECharts** — port the 8 existing recharts components to ECharts. ~6-10 h.
+58. **[L] SelectTrigger height (`h-9`) doesn't match Input height (`h-11`)** — _src/components/ui/select.tsx_. Introduce `size` variant; default to `h-11`. Audit compact-context call sites for explicit `size="sm"` override. ~1 h.
+59. **[L] Platform-wide table density: column min-widths + nowrap defaults** — _src/components/shared/data-table.tsx_ + per-table column definitions. Add a `widthPx` / `nowrap` field to column defs; default text cells to `whitespace-nowrap`; surface horizontal scroll only when content actually exceeds. ~2-3 h.
+60. **[L] Platform-wide admin-settings tooltip audit** — _src/components/admin/_. Sweep every admin setting; add `FieldLabel` + tooltip wherever the setting isn't self-explanatory to a basic admin user. Use the FieldLabel primitive shipped in PR4.2 / `552b966`. ~3-4 h.
+61. **[L] Platform-wide error message audit for prod debuggability** — _cross-cutting_. The Documenso 502 / "Invalid token" diagnosis loop showed errors don't self-describe in prod. Two layers: (a) service-side: wrap upstream errors with the resolver chain that's actually in effect; (b) UI: render the wrapped error verbatim in the toast / dialog so operators can see "fell back to env, env value is stale" without reading logs. ~4-6 h.
+
+---
+
+## Group R — Documenso-first templates (~6-8 h)
+
+62. **[L] Documenso-first templates: pull templates from Documenso instead of uploading through CRM** — _src/components/admin/document-templates/template-form.tsx_ + new admin endpoint `GET /api/v1/admin/documenso/templates` + per-template field-mapping editor + "Sync now" button + template-list badges. Generalizes the existing per-port EOI sync. ~5-7 h. **Pairs nicely with:** Group L (UploadForSigningDialog rework) — they share the same Documenso-side surface area.
+
+---
+
+## Group S — AI assistance + extraction (~10-14 h, deferred until user asks)
+
+63. **[DEFERRED] AI-assisted action extraction from contact-log entries** — _src/components/interests/interest-contact-log-tab.tsx_ + new LLM service. "Extract action items" button next to Save; LLM-parses body + returns proposed follow-ups; rep approves each individually. ~6-10 h. Defer until a user is genuinely asking.
+
+---
+
+## Group T — Deferred bugs (~1 h each, do when surfacing)
+
+64. **[DEFERRED] Duplicate row for berth E17 in port-nimara + missing unique index** — DB cleanup + partial unique index `(port_id, mooring_number) WHERE archived_at IS NULL`. Deferred per session call.
+65. **[DEFERRED] Stage advance allowed without berth price** — `ValidationError` gate in `changeInterestStage` for stages ≥ eoi. Deferred per session call.
+
+---
+
+## Group U — EOI bundle UX rework (~10-14 h)
+
+66. **[SHIPPED in ef37901] EOI bundle UX rework (multi-berth interests)** — (a) defaults flip shipped in `05e727f`, (b) LinkedBerthsList rename shipped in PR10, (c) picker inside EoiGenerateDialog shipped in `ef37901`: new "EOI scope" section lists every linked berth with "In EOI" + "Public map" checkboxes pre-filled from current flag state; handleGenerate diffs vs server snapshot and PATCHes only changed rows in parallel before kicking off the envelope. Plan item closed.
+
+---
+
+## Execution discipline
+
+For each item we tackle:
+
+1. **Quote the master-doc bullet** so we're aligned on scope.
+2. **Verify it isn't already shipped** — re-read the master entry for sub-bullets with SHIPPED markers I may have missed.
+3. **Implement to production quality** — tests where the feature has logic worth testing; tsc clean; vitest 1454+/1454+; commit with a descriptive message.
+4. **Annotate the master doc** — add `**SHIPPED in <sha>:**` line under the original entry.
+5. **Tick off this plan** — once a group lands, mark the item as `[SHIPPED]` here.
+
+When in doubt about an item's scope, surface the question first rather than guessing — several items already locked design decisions in the source entry that we should reuse verbatim.

docs/superpowers/audits/alpha-uat-master.md

@@ -0,0 +1,844 @@
+# Alpha UAT Master — Multi-Day Findings
+
+> **Status:** living doc — _started 2026-05-18, evolving across many sessions_. Single source of truth for everything the manual Playwright + React-Grab UAT pass surfaces, regardless of which day it landed on.
+>
+> **Companion to:** [2026-05-18 Full Codebase Audit](./2026-05-18-full-codebase-audit.md)
+>
+> **Methodology:** Live Playwright + React Grab walkthrough of the running CRM (default viewport). Findings dropped into chat are appended here in the matching bucket with file:line evidence where available. Cross-references annotated as `see Audit X#N` (and back-referenced in the audit doc as `→ confirmed in manual #N`).
+>
+> **Severity legend (for bugs):**
+>
+> - `critical` — data loss, security breach, multi-tenant leak, or hard block on a core flow
+> - `high` — broken golden path, visible-to-customer regression, or silent prod no-op
+> - `medium` — UX regression, partial functionality, recoverable error
+> - `low` — cosmetic, copy, polish
+
+---
+
+## Bucket 1 — Quick fixes (<15 min)
+
+_Copy tweaks, alignment, single-prop edits, obvious typos._
+
+<!-- Append findings as: `1. **Title** — _path:line_ — description. (see Audit X#N if applicable)` -->
+
+> **[Captured 2026-05-22 — visual breakpoint audit, 5 viewports × 20 surfaces via Playwright MCP. Screenshots local at `tmp/visual-audit-2026-05-22/<surface>/<viewport>.png`. Tablet tier (768-1023) infrastructure + dashboard PageHeader stacking shipped in `6d665d0`; findings below are the residue surfaced after that ship lit up the tier.]**
+>
+> - **SHIPPED in 2f1e1b5:** Tablet topbar logo trigger doesn't render visibly — center grid column changed to `minmax(280px, 800px)` at base with `lg:` override back to 420px min; search-container `sm:-translate-x-...` gated to `lg:` so it only kicks in when sidebar is inline. Verified at 768 — hamburger affordance visible top-left.
+> - **SHIPPED in 2f1e1b5:** Dashboard title strip crushed at 1024 viewport — PageHeader horizontal-stack breakpoint moved from `lg:` (1024) to `xl:` (1280) so the strip stays stacked through tablet AND narrowest desktop width. Verified at 1024 — title reads cleanly with action row stacked below.
+> - **SHIPPED in 2f1e1b5 + follow-up:** `useIsMobile()` call-site audit — only 4 callers: pipeline-chart + pipeline-funnel-chart correctly want `tier !== desktop` (short-label x-axis applies on tablet too, kept as-is); date-picker + date-time-picker were strict mobile-only and now use `useViewportTier() === 'mobile'` so tablet gets the desktop Popover Calendar instead of the native input.
+
+> **Outstanding quick-fixes (rapid UAT capture — not yet shipped):**
+>
+> - **Rename "Mark in EOI bundle" + add tooltip** — _src/components/interests/linked-berths-list.tsx (or wherever the toggle lives)_ — the toggle controls `interest_berths.is_in_eoi_bundle` (per CLAUDE.md), which decides _which_ of the deal's berths the signed EOI document actually commits to. Today the rep sees a label they can't decode. Rename to something like "Include in EOI" + add an info-tooltip popover explaining "Berths flagged here are covered by the EOI signature. A deal can flag a subset (e.g. 2 of 3 linked berths)." ~10 min. **SHIPPED in db51106:** label renamed to "Include in EOI"; existing tooltip already explained the bundle-vs-signature distinction.
+> - **Lower supplemental-info-request link TTL to ~2 weeks** — _src/lib/services/_ (token model) — link currently expires ~1 month out (`Wed, 17 Jun 2026` shown for an email sent May 18 = ~30 days). User wants ~14 days. Single constant change. ~5 min. **SHIPPED in db51106:** `TOKEN_TTL_DAYS` 30 → 14 in supplemental-forms.service.
+> - **Admin Documenso settings: surface env-fallback state** — _src/app/(dashboard)/[portSlug]/admin/_ (Documenso settings page) — `getPortDocumensoConfig` already does the right thing (`adminValue ?? env.DOCUMENSO_API_KEY ?? ''`), but the admin UI doesn't show which fields are filled by the admin entry vs. silently falling back to env. Caused an in-session diagnosis loop where the operator had entered creds on Port Amador but was generating EOIs on Port Nimara — Port Nimara's admin row was empty, so it fell back to a stale env key and threw 401. Recommend a small "Using fallback from env" / "Per-port override active" pill next to each Documenso settings field so the operator can see at a glance which scope is in effect. ~30 min. **SHIPPED in e33313b:** collapsed `V2_FEATURE_FIELDS` + `CONTRACT_RESERVATION_FIELDS` (legacy `SettingsFormCard`) into `RegistryDrivenForm` sections (`documenso.behavior` + the existing `documenso.templates`). Every Documenso setting now flows through the registry path that surfaces the env-fallback / port / global source badge per field via `/api/v1/admin/settings/resolved`. EOI generation card retitled to "Templates & signing pathway" since `documenso.templates` covers EOI + reservation + contract template IDs.
+> - **InterestDocumentsTab label clarity** — _src/components/interests/interest-documents-tab.tsx_ — the tab has two sections: "Legal documents" (Documenso envelopes — EOI / Reservation / Contract, signature-driven) and "Attachments" (general file uploads). "Legal documents" is misleading — the section is scoped to _signature envelopes_, not any legal doc. A rep uploading externally-signed PDFs (lawyer-prepared addenda, etc.) currently goes into Attachments — fine, but the label gap suggests reps expect "Legal documents" to accept external uploads too. Two paths: (a) rename "Legal documents" → "Signature documents" (or "Contracts & EOI") to scope it correctly, OR (b) allow external uploads into that section (more disruptive — needs file-classification metadata). ~15 min for rename + tooltip; ~2 h for upload route. **SHIPPED (a) in 552b966:** section heading renamed to "Signature documents".
+> - **Berth recommender: drop the "Tier X" prefix, keep plain-English label + add tooltip** — _src/components/interests/berth-recommender-panel.tsx:181_ (the pill render) and _:94-99_ (`TIER_LABELS` map) — the pill currently renders `Tier A · Open` / `Tier B · Fall-through` / `Tier C · Active interest` / `Tier D · Late stage`. The four tier letters are internal taxonomy from `berth-recommender.service.ts` (A = never had interest, B = past fall-through, C = active interest, D = active in late stage); reps don't speak in tier letters and the suffix label already carries the meaning. Fix: (1) drop the `Tier {rec.tier} · ` prefix in the rendered pill — show just `tier.label` (e.g. "Open" / "Fall-through" / "Active interest" / "Late stage") so the chip is self-explanatory. (2) Wrap the pill in a `Popover` (click) or `Tooltip` (hover) that explains the four-state ladder in plain English: "Recommender state — **Open**: never had interest. **Fall-through**: prior interest didn't close (warm). **Active interest**: another deal is in play. **Late stage**: another deal is near-sold." (3) Optional: a small `?` icon next to the chip so the tooltip is discoverable without hovering. The internal `Tier` type stays as-is in the service (it has semantic value in the SQL ladder + admin settings); only the UI label changes. ~15 min. Captured 2026-05-18 from UAT. **SHIPPED in 203f543:** pill is now a Popover trigger with the plain-English label + HelpCircle icon; popover content explains the 4-state ladder.
+> - **ChartCard: center the chart vertically when grid row is taller than the chart** — _src/components/dashboard/chart-card.tsx_ — every chart widget (`pipeline-funnel`, `occupancy-timeline`, `lead-source`, `berth-status`, `source-conversion`, …) wraps a fixed-height `ResponsiveContainer` (240-280px) inside `ChartCard`. The Card is `h-full` (stretches to its grid-row height) but the inner content keeps its 240-280px and pins to the top — when a neighbour card in the same row is taller (e.g. Pipeline Value with its full per-stage breakdown), the chart card has visible empty space below the chart. Fix: convert `ChartCard` to a flex-column (`<Card className="h-full flex flex-col">`); `CardHeader` keeps natural height; `CardContent` gets `flex-1 flex items-center` so the chart's wrapping div sits vertically centered in the remaining space. ResponsiveContainer stays at its declared fixed height. Affects all chart widgets via one wrapper change — no per-chart edits. ~10 min. Captured 2026-05-18 from UAT. **SHIPPED in 203f543.**
+> - **UploadForSigningDialog feels cramped — fix inner content distribution + right-size the dialog** — _src/components/documents/upload-for-signing-dialog.tsx:166_ (currently `max-w-5xl` = 1024px) + the recipient-row + form fields inside DialogBody. Visual symptom: dialog renders at full 5xl width but inner content clusters on the left ~60% with truncated email field (`email@examp...` clipped), narrow Document title input, tiny 4-row Optional message textarea, and massive whitespace to the right. Combination makes the dialog feel narrow AND empty.
+>   - **Fix:**
+>     - **(a) Right-size the dialog:** drop to `max-w-3xl` (768px) — content fills naturally instead of swimming in 5xl.
+>     - **(b) Recipient row flex distribution:** `Name` input → `flex-1`, `email` input → `flex-[2]` (~2x name's width — emails are longer), role select → `w-32 shrink-0`, delete icon → `shrink-0`. Today every field is at its intrinsic width with no flex hint, so the row doesn't fill horizontal space.
+>     - **(c) Document title + Optional message inputs:** make sure they have `w-full` on the wrapper so they span the dialog's content width.
+>     - **(d) Optional message textarea:** bump rows from 4 → 6 minimum (`rows={6}` or `min-h-[8rem]`) so reps writing real messages have room.
+>     - **(e) Audit the other steps of the wizard** (select-file, place-fields) for the same content-distribution issues since they share DialogBody.
+>   - **Effort:** ~20-30 min. Captured 2026-05-21 from UAT. **Pairs nicely with:** the platform-wide form-error UX work (Bucket 2) — both touch how form content is presented in dialogs.
+>   - **SHIPPED (width + recipient row + textarea) in 203f543:** dialog widened to `max-w-[1400px] w-[95vw]` so the place-fields step gets the room it needs; recipient row swapped from `grid-cols-12` to a flex layout (Name `flex-1`, Email `flex-[2]`, Role `w-40 shrink-0`, delete `shrink-0`); invitation-message textarea bumped from 3 → 6 rows. Step-adaptive sizing skipped — the new wider dialog works for all three steps without per-step gymnastics.
+> - **ColumnPicker: add "Hide all columns" symmetric to "Show all columns"** — _src/components/shared/column-picker.tsx:58-60 (`showAll()`) + 116-123 (button render)_ — current picker has a "Show all columns" footer item that clears the hidden set. Add a parallel `hideAll()` that sets `hidden = columns.filter(c => !c.alwaysVisible).map(c => c.id)` — hides every toggleable column while preserving `alwaysVisible` ones. Render a "Hide all columns" footer item next to "Show all columns" with the same visibility gate (only shown when ≥1 toggleable column is currently visible, mirroring the `canShowAll` logic). Since column-picker is shared across every DataTable surface (berths, clients, interests, yachts, companies, reservations, invoices, audit-log, expenses), the fix lands platform-wide automatically. ~5 min. Captured 2026-05-21 from UAT. **SHIPPED in 8f42940:** `hideAll()` + symmetric `canHideAll` gate added; both items render under the same separator.
+> - **SHIPPED (core) in 03a7521 (K40):** Resolved endpoint widened to accept `?keys=k1,k2,...` so checklist batch-resolves heterogenous registry keys through port → global → env → default in one round-trip. Captures dominant source per step ("env fallback", "global default", "built-in default") surfaced inline under green tick so super-admins see when a step relies on env rather than per-port override. Compound-key gates report weakest sub-key's source. Topbar banner / dashboard tile / weekly nudge / celebration sub-items remain queued. **OnboardingChecklist: auto-check uses raw setting-row presence, not resolver chain → ports using env fallback or global config never auto-tick + super_admin discoverability gap** — _src/components/admin/onboarding-checklist.tsx:32-105 (STEPS def)_ + _src/lib/services/port-config.ts_ (the resolver chain like `getPortDocumensoConfig`) + new dashboard tile + new topbar banner for the discoverability half. Two linked bugs surfaced UAT 2026-05-21.
+>   - **(a) [bug] Auto-check sentinels are too strict.** Examples:
+>     - Email step (line 46) checks `smtp_host_override` — only fires when port has its own override row. Ports using global SMTP (the common case) never auto-tick even though email works.
+>     - Documenso step (lines 58-63) requires ALL of 4 port-level overrides. Per CLAUDE.md, Documenso supports env fallback (`getPortDocumensoConfig` does `adminValue ?? env.DOCUMENSO_API_KEY`), so a working port using env config registers as not-onboarded forever.
+>     - Same pattern likely for storage, settings, etc. — any setting with a resolver chain falls into this trap.
+>     - **Fix:** replace each `autoCheckSettingKey` with an `autoCheckResolver` function (named import from `src/lib/services/port-config.ts` etc.) that runs the full resolver chain and returns `true` when the functional config is complete. New OnboardingStep shape: `{ id, label, description, href, autoCheckResolver?: (portId) => Promise<boolean> }`. Sentinels stay for steps where direct setting-row presence IS the truth (e.g. branding logo URL).
+>     - Belt-and-braces: surface what's resolving from where directly in the step row (e.g. "Email: ✓ Using global SMTP" vs "Email: ✓ Per-port override"). Closes the "why is this checked?" gap for admins later.
+>   - **(b) [feature] Super_admin discoverability — nudge until onboarding hits 100%.** Today the checklist only appears on the one admin onboarding page; a super_admin who skips that page never sees it. Multi-surface nudges:
+>     - **Topbar banner** when onboarding < 100% — slim chip showing "Setup X% complete · Continue →" (links back to /admin/onboarding). Dismissible per-session (returns next login). Only visible to super_admin.
+>     - **Dashboard rail tile** "Continue setup" — small card on the dashboard widget rail showing the next incomplete step + a button. Disappears entirely at 100%.
+>     - **In-app notification (existing notification infra)** — fires once per week per super_admin until 100%, with a deep-link back to the checklist. "Your setup is X% complete — N items remaining."
+>     - **Onboarding-complete celebration** — small toast + a one-time 🎉 highlight when the 100th item ticks. Acknowledges the finish-line so the nudges going silent feels intentional, not just a bug.
+>     - **Permission gating:** all surfaces gate on `super_admin` (or whatever role the onboarding page itself is gated on) so non-super-admins don't see noise about settings they can't change.
+>   - **Effort:** ~3-4h for (a) (resolver-chain audit + 6-8 step migrations + tests) + ~3-4h for (b) (topbar banner + dashboard tile + notification job + celebration). Total ~6-8h. Captured 2026-05-21 from UAT.
+> - **Agent audit (a11y + i18n) — 2026-05-21 — 27 findings bundled** — read-only Opus-agent pass over login/dashboard/interest-detail/client-detail/berth-detail/public-form/portal/admin surfaces. Ship as themed sub-PRs, not one mega-PR.
+>   - **a11y — discrete fixes (~3-4h total):**
+>     - Add `aria-label="Row actions for {name}"` on icon-only kebab triggers — _interest-columns.tsx:296_, _client-columns.tsx:301_, _berth-columns.tsx:175_. ~10min.
+>     - Add `aria-label` + `aria-pressed` on Table/Board view toggle — _interest-list.tsx:187-202_. ~5min.
+>     - Add `aria-expanded` + `aria-controls` on the "Show/Hide upcoming milestones" disclosure — _interest-tabs.tsx:484-494_. ~5min.
+>     - Same for recommender "Hide/Add filters" — _berth-recommender-panel.tsx:466-471_. ~3min.
+>     - Fix BrandedAuthShell logo `alt` default (`'Sign in'` shows on every page) — use `alt=""` when no port name OR pass per-page override — _branded-auth-shell.tsx:32,58_. ~10min.
+>     - Mark PDF logo crop image decorative (`alt=""`) — _pdf-logo-uploader.tsx:312-318_. ~3min.
+>     - Add `scope="col"` on raw `<th>` cells (or migrate to shadcn `<TableHead>`) — _berth-interests-tab.tsx:149-154_, _bulk-hard-delete-dialog.tsx:185-186_, _bulk-add-berths-wizard.tsx:226-231_. ~10min. **SHIPPED in 72d7803.**
+>     - Wrap "Loading…" auth fallbacks in `role="status" aria-live="polite"` — _set-password/page.tsx:107_, _portal/activate/page.tsx:9-11_, _supplemental-info/[token]/page.tsx:140-147_. ~10min. **SHIPPED in 05e727f:** all three sites wrapped; supplemental-info also gains sr-only "Loading" copy since only a spinner was visible.
+>     - Add `aria-live` region on supplemental-info async state swaps — _supplemental-info/[token]/page.tsx:150-186_. ~10min.
+>     - Add `<Label>` (or `aria-label`) on recommender filter selects — _berth-recommender-panel.tsx:306, 325, 343_. ~10min.
+>     - Make `<legend>` styling visually distinct in supplemental-info — _supplemental-info/[token]/page.tsx:200, 249_. ~5min. **SHIPPED in 72d7803.**
+>     - Link set-password hint via `aria-describedby` — _set-password/page.tsx:147_. ~3min. **SHIPPED in 05e727f:** password input now `aria-describedby="password-hint"` linked to the requirements `<p>`.
+>   - **a11y — contrast/visual issues (Bucket 4 candidates):**
+>     - `text-[#007bff]` 12px link below AA contrast on auth pages — darken to `#0058b3` or always-underline — _login/set-password/reset-password pages_. ~5min. **Severity: medium** (WCAG 1.4.1 violation). **SHIPPED in ae8867d:** darkened to `#0058b3` AND always-underlined (belt + braces). Button backgrounds left at `#007bff` since white-text-on-blue at button sizes passes AA.
+>     - `text-muted-foreground/{40-70}` opacity stacking puts text below AA on muted bg — _interest-detail-header.tsx:493_, _client-detail-header.tsx:173,184_, _contacts-editor.tsx:280,292_, _client-interests-tab.tsx:160_, _berth-interest-pulse.tsx:165_, _invoice-card.tsx:149_. Audit + replace with semantic tokens. ~1h. **Platform pattern.**
+>     - `text-[10px]` / `text-[11px]` micro-type on stage chips, pipeline counts, badges across 20+ surfaces — bump to 12px min — _client-pipeline-summary, client-card, dedup-suggestion-panel, contacts-editor, bulk-hard-delete-dialog, berth-interest-pulse, kpi-tile_. ~1h. **Platform pattern.**
+>   - **i18n — discrete fixes (~1.5h total):**
+>     - Fix invalid locale tag `'en-EU'` → use `undefined` (honour user) or proper BCP-47 — _payments-section.tsx:66_. ~3min. **SHIPPED in 72d7803.**
+>     - Calendar month dropdown passes `'default'` instead of resolved locale — _ui/calendar.tsx:35_. ~5min. **SHIPPED in 72d7803.**
+>     - Date formatting hardcoded `en-GB`/`en-US` across 10+ document/template surfaces — centralize via `formatDate()` helper honouring `useLocale()` — _documents-hub.tsx:373_, _document-list.tsx:83_, _document-detail.tsx:271_, _signing-details-dialog.tsx:81,103_, _entity-folder-view.tsx:81_, _template-list.tsx:132,224_, _reservation-detail.tsx:285_. ~1h.
+>     - Currency formatter hardcoded `'en-US'` on all invoice/expense totals — same fix pattern — _invoice-columns.tsx:81_, _invoice-detail.tsx:232_, _expense-columns.tsx:87,103_, _expense-detail.tsx:191,200_. ~30min.
+>     - `currency.ts` hardcodes English currency labels — delete, let Intl resolve — _src/lib/utils/currency.ts:11-29_. ~30min.
+>   - **i18n — platform decisions (Bucket 3 candidates):**
+>     - `next-intl` is wired but NEVER used — zero `useTranslations()` calls in src/. Decision: commit to i18n migration OR rip out the dead infrastructure. Holding both is tech-debt. ~scope depends on commitment.
+>     - Naive ternary pluralization (`count === 1 ? 'X' : 'Xs'`) across 15+ surfaces — won't translate to Polish/Arabic/Russian. Route through `Intl.PluralRules` / next-intl's `t.rich`. ~1h after i18n decision lands.
+>     - **Zero use of CSS logical properties — 1,173 instances of `ml-/mr-/pl-/pr-/text-left/text-right` and zero `ms-/me-/ps-/pe-/text-start/text-end`.** RTL support would require global refactor. If RTL is roadmap-bound: adopt logical properties going forward + add lint rule. ~30min for the lint guard; multi-day if RTL is real. **Note only for now.**
+>   - **Platform patterns (Bucket 3):**
+>     - **Form validation never sets `aria-invalid` / `role="alert"` / `aria-live`** across every react-hook-form caller. SR users get zero feedback on validation failure. Build a shared `<FieldError>` component emitting both visible text + ARIA. Sweep all forms. ~2h. **Bundles with the Bucket 2 form-error UX finding** — same surfaces, same primitive.
+>     - **Icon-only buttons inconsistent — ~50% have `aria-label`, rest have nothing or only `sr-only` text.** Add `jsx-a11y/control-has-associated-label` lint rule + sweep. ~1h.
+> - **Sweep: remove em-dashes from all user-facing copy (toast messages, button labels, helper text, banners, dialog descriptions, empty states)** — em-dashes (`—`) feel AI-generated and add visual noise; user reads them as "Claude wrote this." Replace with periods, commas, colons, or simple hyphens depending on context. **Scope:** _src/components_ (every UI string), _src/lib/email/templates_ (email body copy), _src/lib/templates_ (merge-field labels + EOI body), _src/app_ (page-level copy), public form copy, error messages from `src/lib/errors`. **Out of scope (keep em-dashes):** code comments, JSDoc, audit-log entries, structured logging, this UAT findings doc itself (internal docs are fine). **Method:** grep `—` across `src/`, manually triage each match (some are inside JSX, some inside string literals); replace per context. Heuristic: if a user could see the character, replace it. **Effort:** ~2-3h depending on hit count (rough estimate 200-400 instances). Captured 2026-05-21 from UAT. **Going forward:** add an ESLint rule banning `—` in JSX text + string literals inside `src/components` so new code doesn't reintroduce them.
+>   - **SHIPPED (lint guard only) in 52342ee:** `no-restricted-syntax` rule on `JSXText[value=/—/]` scoped to `src/components` + `src/app`, set to `warn`. 111 existing instances flagged as warnings — sweep remains parked.
+>   - **SHIPPED (full sweep) in f0dbefc:** 176 em-dashes replaced with " - " across 49 files in `src/components` + `src/app`, skipping pure-comment lines (// /\* \* \*/). Two `&mdash;` HTML entity cases (system-monitoring-dashboard + interest-stage-picker) caught separately. Lint rule bumped from `warn` → `error` so new code reintroducing em-dashes in JSX text fails the gate. Templates / audit-logs / structured logging stayed untouched per scope.
+> - **[Captured 2026-05-22] Dev-server unreachable from a phone on the LAN — three bundled fixes shipped in `be261f3`:** (1) `getPortBrandingConfig` normalizes localhost / private-LAN host prefixes (192.168._, 10._, 172.16-31._, 127._, 0.0.0.0) on read so an in-app `<img src>` resolves against current origin; both branding upload routes store path-only going forward; new `absolutizeBrandingUrl()` helper re-absolutizes for email shells; DB backfill stripped the 2 existing rows. (2) Socket.IO client connects via `io()` no-URL (window.location.origin) instead of `NEXT_PUBLIC_APP_URL`; server CORS uses a function that allows localhost + private-LAN in dev, locks to APP*URL in prod (mirrors better-auth trustedOrigins). (3) Portal logout route builds redirect from `req.url` instead of `env.APP_URL`. next.config `allowedDevOrigins` widened from a hardcoded IP to 192.168.* / 10.\_ / 172.16-31.\* wildcards so HMR works across networks without per-network edit (without HMR the login form's React click handler never hydrates and the form falls back to GET, leaking the password into the URL — the symptom that caught this).
+> - **[Captured 2026-05-22] Dashboard build crashed with "Module not found: Can't resolve 'fs'" via dashboard-shell → export-dashboard-pdf-button → dashboard-report-data.service → dashboard.service → @/lib/db → postgres. SHIPPED in `adf4e2b`:** split pure data + types (`PDF_DASHBOARD_WIDGET_IDS`, `PDF_DASHBOARD_WIDGETS`, `PdfDashboardWidgetId`, `PdfDashboardWidgetOption`) into new `src/lib/services/dashboard-report-widgets.ts`; client button imports from there; service re-exports from new file for backwards compat. The resolver (`resolveDashboardReportData`) stays in the service module since it's server-only.
+> - **Custom-field form: "Sort Order" needs an explainer tooltip — example of a broader gap** — _src/components/admin/custom-fields/custom-field-form.tsx:298-308_ — surfaces a specific instance of a platform-wide gap: see the next finding for the full sweep. **SHIPPED in 552b966:** Sort Order now uses the FieldLabel primitive (PR4.2) with explainer tooltip. First adoption of the primitive; platform-wide sweep remains parked.
+> - **DocumentList DocRow kebab: add "Download" action** — _src/components/documents/document-list.tsx:86-109_ — current kebab has Send-for-Signing (draft only), Move-to-folder, Delete. No Download. Reps reviewing a signed doc from the interest's documents tab have to navigate into the document detail to download. Add a `<DropdownMenuItem>` at the top of the menu when `doc.signedFileId` is set (or `doc.fileId` for non-Documenso docs like manual uploads), wired to the same `apiFetch('/api/v1/files/[id]/download')` + anchor-click pattern used elsewhere. Permission-gate by `files.download` if that perm exists. ~10 min. Captured 2026-05-21 from UAT. **SHIPPED in 52342ee:** DocRow now renders Download at the top of the kebab when `signedFileId` is set; wired via the existing `triggerUrlDownload` helper from PR1.
+> - **InterestEoiTab "Open" link too ambiguous — relabel to "Open in Documents"** — _src/components/interests/interest-eoi-tab.tsx:163_ — the link in the EOI history list goes to `/${portSlug}/documents/${d.id}` (Documents Hub doc detail) but the label just says "Open" + an external-link icon. Rep can't tell where it goes until they hover. Change to `Open in Documents` (or `View in Documents`). Apply the same idiom anywhere else a cross-section navigation link uses bare "Open" — quick grep + sweep. ~5 min. Captured 2026-05-21 from UAT. **SHIPPED in c6dcf49.**
+> - **PaymentsSection: deprioritize layout — move below milestones + collapse-by-default at Reservation** — _src/components/interests/interest-tabs.tsx:633 + 846-852_ (current `showPaymentsSection = reservationStageReached` + renders at line 847, ABOVE the milestone strip at line 859+) + _src/components/interests/payments-section.tsx_ (the section component itself). Today: hidden pre-Reservation (correct ✓), shows as a full expanded card at Reservation+ sitting above the milestone strip. Section is reference/history once expected — milestone work (active step) should be the rep's primary visual focus, not deposits-tracking.
+>   - **Fix (three states):**
+>     - **Pre-Reservation:** keep hidden (no change).
+>     - **Reservation+ stage, no deposits recorded yet:** render as a slim collapsed bar at the bottom of OverviewTab (below the milestone strip + below the Berth requirements / Tags / Latest note grid). Bar shows `Deposits · Not received yet` + a `Track deposit →` CTA that expands the section in place. Sits last on the page so it doesn't pull eye away from the active milestone.
+>     - **Reservation+ stage, deposits exist:** same below-the-milestones placement, but the collapsed bar carries a summary chip: `Deposits · $10,000 received · 2 payments · Expand`. Click expands the full PaymentsSection inline. The summary chip uses the existing currency-format helper.
+>   - **Render order change in interest-tabs.tsx:** lift the PaymentsSection mount from its current position (line 846-852, above milestones) to AFTER the milestone strip + AFTER the OverviewTab grid (below "Latest note", Tags, Berth requirements). It becomes the last visual element on the OverviewTab.
+>   - **Collapse state:** persist per-interest via Zustand or react-query cache (so re-opening the same deal remembers the rep's last expand/collapse). Default collapsed unless a deposit was added in this session.
+>   - **Effort:** ~1-1.5h (layout reorder + collapsed-bar state + summary chip + render-order verification). Captured 2026-05-21 from UAT. **SHIPPED (layout reorder) in f39f0aa:** PaymentsSection moved below milestones (was above). Collapsed-bar + summary-chip refinement parked.
+> - **WatchersCard empty state missing bottom padding** — _src/components/documents/document-detail.tsx:546_ — `<p className="text-xs text-muted-foreground">No one is watching this document yet.</p>` has no margin while the sibling populated `<ul>` at line 548 has `mb-3 space-y-1`. Empty state text sits flush against the add-watcher form below. Add `mb-3` to the empty-state `<p>` to match. ~30s. Captured 2026-05-21 from UAT. **SHIPPED in 52342ee.** Further bumped to `mb-4 pb-1` in **e33313b** after a follow-up UAT noted the lines still read tight.
+> - **DocumentDetail Interest link should show berth(s), not duplicate the client name** — _src/components/documents/document-detail.tsx:96 (type) + 237-241 (linked-entity row builder)_ + the document-detail API service that hydrates `linked.interest`. Today renders `Client: Matthew Ciaccio · Interest: Matthew Ciaccio` — visually redundant, and the Interest link carries no distinct information. Should be `Client: Matthew Ciaccio · Interest: A1-A3, B5-B7` (berth range via the existing `formatBerthRange()` helper from `src/lib/templates/berth-range.ts`, same idiom as the locked folder-naming convention and the external-EOI default title).
+>   - **Backend:** swap the response payload's `interest: { id, clientName }` → `interest: { id, berthLabel }` where `berthLabel` is derived in the service layer from the interest's primary or in-bundle berths. Falls back to "No berths linked" when no berths are attached.
+>   - **Frontend:** change line 241 from `sub: linked.interest.clientName` → `sub: linked.interest.berthLabel ?? 'No berths linked'`.
+>   - **Effort:** ~15-20 min including type updates + a vitest covering the multi-berth + no-berths paths. Captured 2026-05-21 from UAT. Cross-ref: pairs with the shared title-derivation helper note in the external-EOI bundle (Bucket 2) — single `deriveBerthLabel(interest)` helper used everywhere.
+>   - **SHIPPED in c6dcf49:** documents.service derives `berthLabel` from `interest_berths` (in-EOI-bundle subset → primary → all linked), `DocumentDetailLinkedEntities` shape gains `berthLabel`, frontend renders `linked.interest.berthLabel ?? clientName ?? 'No berths linked'`.
+> - **Platform-wide `<FileInputButton>` primitive — replace 7 raw `<Input type="file">` instances with native browser-default styling** — _new_ `src/components/ui/file-input-button.tsx` + sweep — `<input type="file">` rendered without a wrapper shows the browser-default "Choose File / No file chosen" UI, which looks raw and inconsistent across Chromium / Safari / Firefox / Comet. We already use the correct idiom in `expense-form-dialog.tsx:389` (Button + hidden input + filename row) and `file-upload-zone.tsx`, but 7 other call sites still use the raw pattern.
+>   - **Affected files:** `external-eoi-upload-dialog.tsx:92`, `template-editor.tsx:486 + 526`, `brochures-admin-panel.tsx:213`, `berth-documents-tab.tsx:176`, `won-status-panel.tsx:200`, `pdf-logo-uploader.tsx:278`, `settings-form-card.tsx:486`.
+>   - **Component shape:** `<FileInputButton accept={...} multiple={...} onFilesPicked={(files) => ...} label="Upload PDF" icon={<Upload />} variant="outline" size="sm" />`. Renders a styled Button (Upload icon + label) + hidden `<input type="file">` underneath. Optional: after-pick filename row with X to clear, mirroring the expense form's pattern.
+>   - **Sweep:** drop-in replacement at each of the 7 sites. Pair with the platform-wide file-preview work (Bucket 3) so picker-then-preview becomes consistent everywhere.
+>   - **Effort:** ~10 min for the primitive; ~30-45 min for the 7-site sweep. Total ~1h. Captured 2026-05-21 from UAT.
+>   - **SHIPPED (primitive) in 8f42940:** `src/components/ui/file-input-button.tsx` lands with the shape the queue asked for + an optional `showSelectedFilename` mode. external-eoi-upload-dialog migrated. The 5 other queued sites were re-audited — they already use the hidden-input + Button-trigger pattern (no browser-default UI visible), so no migration was needed; the primitive is in place for any new caller.
+> - **EOI empty state: add "Mark as signed without file" button (parity with Reservation + Contract tabs)** — _src/components/interests/interest-eoi-tab.tsx:553-562_ (`EmptyEoiState` only renders Generate + Upload paper-signed) — `MarkExternallySignedDialog` already supports `docType: 'eoi'` (mark-externally-signed-dialog.tsx:37-41) with full copy ("Flips the EOI sub-status to 'signed' without uploading a file…"); the reservation tab uses the same dialog via a third ghost-button row (interest-reservation-tab.tsx:378-380). EOI tab's empty state just never grew the button. Add it as a third ghost-variant Button, wired to a `setMarkExternalOpen(true)` state hook + the existing dialog. ~5-10 min. Captured 2026-05-21 from UAT. **SHIPPED in 52342ee.**
+> - **Activity feed: "See all" link to the full audit log** — _src/components/dashboard/activity-feed.tsx_ (ActivityFeedInner, around line 175) — the card lists the most recent audit events but has no jump-off to the full audit-log page. Add a "See all" link in the card header (or as a trailing row underneath the list). Confirm the target route (likely `/{portSlug}/admin/audit-log`) and permission-gate the link by the same `audit_log.view` perm the admin sidebar uses, so non-admin reps see the card but not the link. ~10 min. **SHIPPED in 203f543:** link points at `/<port>/admin/audit` and is gated by `admin.view_audit_log`.
+
+1. **Dev-mode banner dismissible** — _src/components/shared/dev-mode-banner.tsx:23_ — added X close button + localStorage persistence keyed by redirect address. Fixed in this session.
+2. **KPI tile top padding collapsing at ≥640px** — _src/components/dashboard/{pipeline-value,active-deals}-tile.tsx_ — shadcn `CardContent` default `sm:pt-0` (assumes a `CardHeader` above) was overriding the tile's `pt-5`. Added `sm:pt-5 sm:pb-5`. Fixed in this session.
+3. **Client create form: Source defaults to "Manual"** — _src/components/clients/client-form.tsx_ — Source select rendered with no default in create mode, so reps had to remember to pick "Manual" every time. Now defaults to `'manual'` unless `prefill.source` is set (inquiry-inbox flow overrides to `'website'`). Fixed in this session.
+4. **Client create form: primary address fields** — _src/components/clients/client-form.tsx_ — drawer previously had no address inputs, so reps had to create the client then click into the Addresses tab. Added a collapsible "Primary Address" section (street, city, postal, country, region/state) shown only in create mode; on submit, after the client POST returns the new id the form chains a `POST /api/v1/clients/{id}/addresses` with `isPrimary: true`. Address errors don't unwind the client create — a toast directs the rep to the Addresses tab. Edit mode keeps using the AddressesEditor in the detail tab. Fixed in this session.
+5. **SupplementalInfoRequestButton card top padding** — _src/components/interests/supplemental-info-request-button.tsx_ — same shadcn `sm:pt-0` default-overriding bug as the KPI tiles. Replaced `p-4` with `p-4 pt-4 sm:p-6 sm:pt-6` so the header has symmetric padding on both base and `sm:` breakpoints. Fixed in this session.
+6. **Qualification checklist shows evidence behind auto-ticks** — _src/lib/services/qualification.service.ts_, _src/components/interests/qualification-checklist.tsx_ — the "Dimensions confirmed" row was auto-ticking based on `desiredLengthFt/widthFt/draftFt` (or a linked yacht's dims) but never showed the rep WHAT data drove the tick, so it felt mysterious. Added an `evidence: string` field to the qualification API row + a new `computeEvidence()` helper mirroring `computeAutoSatisfied()`; UI renders `"Yacht: L × W × D ft"` or `"Desired: L × W × D ft"` in emerald under the row description when auto-satisfied. Closes the "why is this checked?" UAT finding. Fixed in this session.
+7. **Recommendations tab renamed to "Berth Recommendations"** — _src/components/interests/interest-tabs.tsx_ — "Recommendations" was ambiguous once a berth was already linked (am I looking for replacements? more for the bundle?). "Berth Recommendations" reads the same regardless of state — no conditional rename needed. Fixed in this session.
+8. **Berth requirements editable on Interest Overview** — _src/components/interests/interest-tabs.tsx_ — added a new "Berth requirements" section to the OverviewTab grid showing desired length / width / draft as inline-editable rows (text variant of `InlineEditableField`); expanded `InterestPatchField` to include the three dim keys. Reps can now capture / correct dims without leaving Overview, and the qualification checklist's evidence string updates in lockstep. Fixed in this session.
+9. **Reminder form: preset date chips** — _src/components/reminders/reminder-form.tsx_ — Due Date input was a bare `<input type="datetime-local">`; reps had to manually pick a date/time for the 80% common cases. Added a row of quick-pick chips above the input (`In 1 hour`, `In 4 hours`, `Tomorrow`, `In 3 days`, `Next week`, `In 2 weeks`) — same idiom as the existing `snooze-dialog.tsx` presets. Day-based presets honour the user's `digestTimeOfDay` preference for hour-of-day. Fixed in this session.
+10. **Consolidate "Next step" guidance into milestone card** — _src/components/interests/interest-tabs.tsx_, _src/components/interests/stage-guidance-card.tsx_ — the separate `StageGuidanceCard` and the active `MilestoneSection` had overlapping intent (both said "do X next") and the guidance card's action buttons were silently never rendered (callbacks were never wired). Removed the StageGuidanceCard mount from OverviewTab; made the milestone card's existing `Next` pill more prominent — brand-600 background, white text, "NEXT STEP" copy with a leading dot. The milestone card already owns the workflow actions (Generate EOI, etc.), so the consolidation eliminates the dual surface. Nurturing keeps a slim inline helper ("Deal is on nurture — schedule a follow-up reminder or log a contact…") since no milestone is naturally "current" while a deal is paused. `stage-guidance-card.tsx` left in the tree for potential future use but no longer mounted. Fixed in this session.
+11. **Interest create form: Source defaults to 'manual'** — _src/components/interests/interest-form.tsx_ — same gap as the client form (#3). Added `source: 'manual'` to the form's RHF `defaultValues` so the Select renders with "Manual" selected on create. Inquiry / website conversion flows can later override via prefill when that path lands. Fixed in this session.
+12. **Qualification checklist: highlight open items** — _src/components/interests/qualification-checklist.tsx_ — confirmed and unconfirmed rows rendered with near-identical styling, making it hard for reps to scan what's outstanding. Confirmed rows now sit in muted-foreground (still readable but de-emphasized); unconfirmed rows get a subtle amber left-border accent + `bg-warning-bg/40` tint so the rep's eye jumps to what still needs attention. Auto-satisfied rows follow confirmed styling (functionally complete). Fixed in this session.
+13. **BerthRecommenderPanel: collapsible on Overview when a berth is linked** — _src/components/interests/berth-recommender-panel.tsx_, _src/components/interests/interest-tabs.tsx_ — added a `linkedBerthCount` prop; when ≥ 1 the panel mounts collapsed (header-only with a "Show recommendations" toggle button), so the LinkedBerthsList card dominates the rep's attention once a berth is picked. Network call is gated on `!collapsed && hasDimensions` so the recommender doesn't fetch options the rep won't see. The dedicated Recommendations tab keeps `linkedBerthCount` unset → always expanded (the rep navigated there explicitly). Fixed in this session.
+14. **Pipeline Value tile moved from rail → chart grid** — _src/components/dashboard/widget-registry.tsx:130_ — the tile shipped in the narrow rail column but its per-stage breakdown + headline numbers + info popover needed more horizontal room to read, and the rail's reserved for reminders/alerts/glance tiles. Changed `group: 'rail'` → `'chart'` so it sits alongside the funnel/timeline/lead-source tiles. Fixed in this session.
+15. **Umami v3.x integration fixed end-to-end** — _src/lib/services/umami.service.ts_, _src/app/api/v1/website-analytics/route.ts_, _src/components/website-analytics/use-website-analytics.ts_, _src/components/website-analytics/website-analytics-shell.tsx_, _src/components/website-analytics/pageviews-chart.tsx_, _src/components/dashboard/website-glance-tile.tsx_, _src/components/dashboard/widget-registry.tsx_, _src/components/ui/kpi-tile.tsx_ — entire Umami integration was built against the v1 nested response shape; v2 + v3 use a flat shape with a sibling `comparison` block. Every consumer was reading `.pageviews.value` → undefined → falling back to `0`. Probed the live instance with the configured port creds and verified the real shape, then rewrote types + readers + the dashboard tile end-to-end:
+    - **`UmamiStats` type** flipped from nested `{pageviews: {value, prev}, ...}` to flat `{pageviews: number, ..., comparison?: {pageviews: number, ...}}` matching Umami v3.1.0.
+    - **`UmamiMetricType` enum** dropped `'url'` (returns 400 on v3) and added `'path'`; route accepts `top-url` as a back-compat alias mapping to `path` server-side.
+    - **`UmamiPageviewsSeries.sessions`** marked optional — Umami v3 only returns it when the request includes a `compare` directive (we don't).
+    - **`WebsiteGlanceTile`** now accepts a `range` prop (was hardcoded `'today'`); widget registry passes the dashboard range through. Distinguishes error from no-data — renders "Umami unavailable" with warning icon and tooltip instead of silently showing `0` when the upstream call fails.
+    - **`KPITile`** delta chip now includes a `TrendingUp`/`TrendingDown`/`Minus` lucide icon so the direction is visible at a glance alongside the colour.
+    - **Top countries** column maps ISO codes → full country names via `getCountryName()` (was rendering raw `GP`, etc.).
+    - **Top pages** column maps `/` → "Homepage" inline for the root-site row.
+    - Service docstring updated to cite the verified v3 endpoint behaviour + the flat-shape rationale so the next reader doesn't repeat the v1-nested mistake.
+    - `tsc --noEmit` clean. Verified live: dashboard tile + website-analytics page both render 2,081 pageviews / 726 visitors / 872 visits / 457 bounces over 30d (the real numbers from analytics.portnimara.com). Fixed in this session.
+16. **Revenue Breakdown widget removed end-to-end** — _src/components/dashboard/{revenue-breakdown-chart.tsx (deleted), widget-registry.tsx, use-analytics.ts}_, _src/app/api/v1/analytics/route.ts_, _src/lib/services/analytics.service.ts_, _tests/integration/analytics-service.test.ts_ — the "Revenue Breakdown" tile (bar chart of invoice totals by status × currency) wasn't aligned with how the org uses invoicing (no client-facing invoicing through the system — only employee expense-sheet PDFs for trip reimbursement) and was redundant once the Pipeline Value tile shipped with a weighted forecast + per-stage breakdown. Removed: widget file, dynamic import, registry entry, `useRevenue` hook, `RevenueBreakdownData` type, `MetricBase` union member, `ALL_METRICS` entry, `SnapshotData` union member, `getRevenueBreakdown` + `computeRevenueBreakdown` service functions, `refreshSnapshotsForPort` revenue branch, route dictionary entry, integration test. `RevenueReportPdf` (separate code path for the reports module) intentionally kept. `tsc --noEmit` clean. Fixed in this session.
+
+---
+
+## Bucket 2 — Medium (15 min – 2 h)
+
+_Component refactors, multi-file edits, single-service tweaks, new validators._
+
+> **[Captured 2026-05-22 — visual breakpoint audit findings, medium tier]**
+>
+> - **Documents Hub folder rail collapses to 3-char truncation at tablet (768)** — _src/app/(dashboard)/[portSlug]/documents/page.tsx_ + the folder-rail component — at 768 viewport the rail renders folder names truncated to ~3 chars + ellipsis ("Cli...", "Co...", "Smok...", "Ya..."). Two viable shapes: (a) widen the rail's min-width to ~180px so names fit, accepting that the file panel shrinks; (b) collapse the rail to a slide-over Drawer at tablet (the file panel takes full width; a small "Folders" button toggles the drawer). (b) is more deliberate but more code. Pick (a) first; revisit if file panel feels too cramped. ~1 h for (a), ~2 h for (b). Captured 2026-05-22.
+> - **Website analytics KPI cards too cramped at 1024** — _src/components/website-analytics/_ — 6 KPI tiles (Active right now / Visitors / Visits / Pageviews / Bounce rate / Visit duration) render in one row at 1024 with sidebar present, leaving each card ~120px wide. "VISIT DURATION" value truncates to `2.` with " 0%" trailing. Fix: stack into a 3+3 grid at lg, fall back to 2-col at md, single column at sm. ~30 min. Captured 2026-05-22.
+> - **Pipeline Value tile per-stage rows overflow right margin at mobile (375)** — _src/components/dashboard/pipeline-value-tile.tsx_ — at 375 the per-stage row layout (label + bar + value + count/probability) crushes the right column; values like "$3,528,000" mash against the right edge of the card. Either truncate value formatting on mobile (compact: `$3.5M`) or stack the value/count/probability vertically below the bar at sm-. ~45 min. Captured 2026-05-22.
+> - **Berths list at 1024 only shows 5-6 of 14 columns** — _src/components/berths/berth-columns.tsx_ — Q59 (`whitespace-nowrap` + column min-widths) was the right call for densely-typed cells, but the side effect is that at 1024 with the sidebar present (768 content area), only Mooring # / Area / Status / Latest deal stage / Active interests fit before horizontal scroll. Consider an auto-hide column policy at lg-tier: hide "Pricing valid", "Side pontoon", "Special features", etc. by default at <1280 so the table reads at a glance, with the column picker letting power users re-add. ~1.5 h. Captured 2026-05-22.
+
+> **[Umami] Follow-ups parked at end of 2026-05-19 build session:**
+>
+> - **[Umami] Empty-state nudges on quiet ranges** — _src/components/website-analytics/{top-list.tsx, sessions-list.tsx, weekly-heatmap.tsx, visitor-world-map.tsx}_ — every card currently renders a flat "No data in this range" string when Umami returns nothing. Replace with a guided message that nudges the operator to expand the range — e.g. "No data in the last 7 days. Try 30d or 90d." plus a one-click button that flips the active `DateRange`. The hook stack already accepts a range setter via the URL search params, so this is purely component-level copy + a Button. ~45 min across the 4 cards. Captured 2026-05-19.
+> - **SHIPPED in a7cbee0 (O52):** Sends-log "Not opened" badge carries inline tooltip explaining Apple Mail's privacy protection routes opens through Apple's proxy and can suppress this signal even when the recipient read the email. **[Umami] Apple Mail privacy disclaimer copy** — _src/app/(dashboard)/[portSlug]/admin/website-analytics/page.tsx_ — the "Track email opens" toggle helper text mentions Apple Mail pre-fetch in passing. Promote it to a bullet list under the field so admins can't miss it (Apple Mail Privacy = over-count; image-blocking clients = under-count; pixel won't fire when EMAIL_REDIRECT_TO is set). ~15 min. Captured 2026-05-19.
+> - **SHIPPED in a7cbee0 (O53):** SendRow type extended with `trackOpens` / `openCount` / `firstOpenedAt`; sends-log card renders "Opened × N" badge with first-open timestamp in title, or "Not opened" when tracking on but no opens yet, or no badge when tracking was disabled for that send. **[Umami] Open-rate column on the document_sends list** — _src/components/documents/_ (find the list that renders document*sends rows; might be inside the interest detail Documents tab or in a dedicated sends-list surface), \_src/lib/services/document-sends.service.ts (listSends extension)* — Phase 4b shipped the data (`open_count` + `first_opened_at` on `document_sends`); the list UI doesn't surface it. Add an "Opened" column showing either a check + relative-time ("Opened · 2h ago · 3 opens") or an em-dash. Sort affordance optional. ~1-2 h depending on how many list surfaces exist. Captured 2026-05-19.
+> - **[Umami] Verify pixel + tracked-link end-to-end with a real send** — _manual_ — flip the admin toggle on (`email_open_tracking_enabled = true` for port-nimara), send a real sales email to your own address, open it in Mail.app and Gmail web, then confirm: (a) `document_send_opens` row appears, (b) `open_count` + `first_opened_at` increment on the parent row, (c) Umami records an `email-opened` event. Same drill for `/q/<slug>` once the composer button (Bucket 3) ships. Cannot be automated — needs a real inbox. Captured 2026-05-19.
+
+> **Outstanding (gaps on shipped work + rapid UAT capture):**
+>
+> - **Platform-wide admin-settings tooltip audit — add explainers wherever a setting isn't self-explanatory to a basic admin user** — _src/components/admin/_ (every settings/form component) + _src/components/admin/shared/registry-driven-form.tsx_ (the unified driver many admin pages use) + _src/components/ui/_ (new `<FieldLabel>` primitive bundling label + optional info-icon tooltip). The custom-field form's "Sort Order" label is one example of a recurring problem across admin pages: many fields carry ambiguous labels (Weight, Priority, Display order, Threshold, Confidence, TTL, Cap, etc.) with no inline explainer. Basic admins are forced to guess, ask another team member, or read source code.
+>   - **Approach (single audit pass, lots of surface area):**
+>     - **(a) Convention via shared primitive** — new `<FieldLabel htmlFor={...} tooltip={...}>{label}</FieldLabel>` component that renders the `<Label>` + (when `tooltip` is set) a small `<Info>` icon button that opens a `<Tooltip>` (hover on desktop, tap on mobile via Radix). Drop-in replacement for every `<Label>` in admin forms. Eliminates inconsistent tooltip styling and makes future additions trivial.
+>     - **(b) Audit pass surface-by-surface** — sweep every admin page + dialog:
+>       - `src/components/admin/custom-fields/` (Sort Order — confirmed)
+>       - `src/components/admin/settings/settings-manager.tsx` (any setting with non-obvious unit/scale)
+>       - `src/components/admin/shared/registry-driven-form.tsx` — when a registry entry has a `description` already defined, it should auto-flow into the tooltip; sweep the registry definitions for missing descriptions
+>       - `src/components/admin/email/` (email send-from / IMAP setup — bounce-poller, attachment threshold, ...)
+>       - `src/components/admin/branding/` (PDF logo scale, brand naming convention, ...)
+>       - `src/components/admin/users/` (role-permission matrix, override hierarchies, ...)
+>       - `src/components/admin/roles/` (permission scope semantics)
+>       - `src/components/admin/vocabularies/` (per-port vocabulary overrides — how cascades work)
+>       - `src/components/admin/ai/` (model selection, confidence thresholds, budget caps)
+>       - `src/components/admin/storage/` (S3 vs filesystem, when each makes sense, migration warnings)
+>       - `src/components/admin/templates/` (template merge fields, allowed-tokens semantics)
+>       - `src/components/admin/forms/` (form-template field types, public form behavior)
+>       - `src/components/admin/documenso/` (per-port API key vs env fallback, v1 vs v2, sendMode)
+>       - `src/components/admin/audit/` (retention, severity filters)
+>       - Anywhere using `<Switch>` + `<Label>` together (often pure toggle with no context)
+>     - **(c) Tooltip-writing guidelines** (put in a brief CLAUDE-style note inline near `<FieldLabel>`):
+>       - 1-2 sentences max, plain English, end with a usage tip when applicable
+>       - State the unit explicitly when applicable ("...in days", "...in MB", "...in feet")
+>       - Mention default behavior when relevant ("Leave 0 to use the system default")
+>       - For dangerous settings, lead with the risk ("Changing this triggers a re-index of every berth — schedule for low-traffic hours")
+>       - Don't restate the label; explain the **why** and **how to choose a value**
+>     - **(d) i18n-ready** — tooltip text routes through the existing i18n catalog so future localization passes don't need a re-audit. Where i18n keys don't exist yet, create them on the fly.
+>   - **Acceptance criteria:** every admin form field without an obvious meaning has a tooltip. Definition of "obvious": a label like "Name" or "Email" is self-explanatory; "Sort Order" / "Weight" / "Threshold" / "Cap" / "TTL" are not.
+>   - **Effort:** ~6-10h end-to-end (FieldLabel primitive + audit ~15-20 admin pages × ~10-15 fields each, write 1-2 sentence tooltips per ambiguous field, sweep registry-driven-form description gaps). Worth a focused half-day. Captured 2026-05-21 from UAT.
+> - **Platform-wide form-error UX: scroll-to-first-error + focus + summary banner (29 form surfaces)** — _new_ `src/hooks/use-form-scroll-to-error.ts` + _src/components/forms/_ (form-error-summary component) + audit pass over every `useForm` + `zodResolver` caller in `src/components` (29 files including expense-form-dialog, client-form, interest-form, yacht-form, company-form, reservation forms, admin forms, …). Today's pattern: a form with validation errors renders per-field messages via `{errors.X && <p className="text-xs text-destructive">{errors.X.message}</p>}` (good), but on submit-with-errors there's no scroll-to-first-error, no focus-the-failed-field, and no summary banner — so the user just gets dropped at the top of the form with no indication of what failed. Especially bad on tall drawers/dialogs where the failing field is below the fold. Surfaced via expense-form-dialog UAT 2026-05-21.
+>   - **Fix shape:**
+>     - **(a) Shared hook** `useFormScrollToError(formMethods)` — wraps `handleSubmit` to add an `onError` callback that: (i) reads `errors` from react-hook-form, (ii) finds the first errored field's DOM node by `name` attribute (or `id`), (iii) `scrollIntoView({ block: 'center', behavior: 'smooth' })`, (iv) focuses the input (`.focus()`). For drawer/dialog content, scroll inside the scrolling container rather than the page.
+>     - **(b) FormErrorSummary component** — renders at the top of the form when there are ≥ 2 validation errors: a small red banner listing each failed field as an anchor link ("Amount is required · Currency is required") that on click scrolls + focuses that field. For a single error, hook-only (no banner needed — scroll handles it).
+>     - **(c) Audit pass:** verify every zod schema has explicit error messages on required fields (`.min(1, 'Amount is required')` not bare `.string()`); fix the bare cases. The default zod "Required" message is generic and unhelpful.
+>     - **(d) Consistent inline error rendering:** standardize the per-field error block into a small `<FormFieldError errors={errors} name="amount" />` helper so we don't keep open-coding the `{errors.X && <p ...>{errors.X.message}</p>}` block in every form. Migrate the existing 29 surfaces opportunistically.
+>   - **Behavior on success:** unchanged — submit proceeds, drawer/dialog closes, toast fires.
+>   - **Mobile consideration:** on tall mobile-bottom-sheet forms, scroll-to-first-error needs to scroll the sheet content, not the page (otherwise nothing visible changes). The hook detects the scrolling ancestor at runtime.
+>   - **Effort:** ~3-4h end-to-end (hook + summary component + 29-form audit + zod-message fixes). Captured 2026-05-21 from UAT. **SHIPPED (primitives + first adoption) in ec6f90f:** new `useFormScrollToError` hook (handles drawer/dialog scrolling-ancestor detection) + new `<FormErrorSummary>` component (top-of-form alert, renders only when ≥2 errors). Expense-form-dialog adopts both as the validation site. Remaining ~28 form surfaces parked for follow-up sweep.
+> - **Berths list "Active interests" column: static count → click/hover popover with interest details + stage-colored count chip** — _src/components/berths/berth-columns.tsx:288-297_ (current static number cell) + _src/lib/services/berths.service.ts (list endpoint extension)_ + new component `<BerthInterestsPopover berthId={...} count={...} highestStage={...} />`. Today renders just `1` / `3` / `—` — unscannable when a rep wants to know WHO has interest in a berth.
+>   - **Design (locked recommendation, can revisit at remediation):**
+>     - **Cell:** count chip (`1`, `3`) with subtle outline + hover/focus indicator. Color-coded by the **highest-active-stage** interest on the berth (e.g., border-red-500 if any at Contract, border-amber-500 at Reservation, border-emerald-500 at EOI+, neutral when only at earlier stages). Encodes stage urgency without expanding.
+>     - **Click/hover (desktop and mobile via Radix Popover):** opens a popover listing each active interest. Each row: client name (link to client detail) · stage badge · berth label (this berth's mooring + role: primary / in EOI bundle / specific interest) · created date · "Open interest →" link to the interest detail. Sort by stage desc so the most-progressed deal sits at top.
+>     - **Empty state (count = 0):** column shows `—` (no popover trigger). Today's behavior, unchanged.
+>     - **Mobile:** tap-to-open via Radix Popover's built-in mobile UX. Width capped at `min(360px, calc(100vw - 32px))` so the popover stays usable on small screens.
+>   - **Service-side:** extend the berths-list response to include `topActiveInterests: Array<{interestId, clientId, clientName, pipelineStage, isPrimary, isInEoiBundle, isSpecificInterest, createdAt}>` (cap at top 5, "View all" link in the popover footer when > 5). Single query that returns this alongside the count via `array_agg` in the existing correlated subquery — no N+1.
+>   - **Permission gating:** the popover row's "Open interest →" link respects `interests.view`. Client name link respects `clients.view`. Hide entire popover when neither perm is held (count chip becomes static for view-only roles).
+>   - **Effort:** ~2-3h end-to-end (service extension + popover component + stage-color logic + tests). Captured 2026-05-21 from UAT.
+>   - **SHIPPED in 292a8b5:** new `GET /api/v1/berths/[id]/active-interests` endpoint returns up to 20 non-archived non-terminal interests linked to the berth (client name, stage, primary/EOI-bundle flags), sorted most-recently-updated first. New `<ActiveInterestsPopover>` lazy-loads on click (30s stale); rows link to the interest detail with a stage-badge tint + primary-star icon. Berth-columns cell now wraps the count number in the popover trigger. Stage-by-highest-stage cell border-tint deferred; popover delivers the same info with one click instead. **Also shipped (companion task — table density):** `DataTable` gained a `density: 'comfortable' \| 'compact'` prop; berth-list toolbar exposes a Rows3/Rows4 toggle that persists per-entity to `user_profiles.preferences.tablePreferences[entityType].density`.
+> - **Interest Overview Email + Phone rows: combobox picker across client's contacts + quick-add new contact** — _src/components/interests/interest-tabs.tsx:958-1000 (Email + Phone EditableRow blocks)_ + _src/components/interests/interest-tabs.tsx:122-129 (`clientPrimaryEmail/Phone[ContactId]` types)_ + _src/lib/services/interests.service.ts (getInterestById)_ + _src/lib/services/client-contacts.service.ts_ + _new_ component `<ClientContactPicker channel="email|phone" clientId={...} selectedContactId={...} onSelect={...} />`. Today's surface shows ONLY the client's primary email + primary phone via inline editor. Two real gaps surfaced UAT 2026-05-21:
+>   - **Gap 1 — empty state has no quick-add:** when client has no primary contact for the channel, line 976-978 renders `<span>—</span>` with no affordance. Rep has to navigate to the Client Detail's Contacts tab to add one. Should expose `+ Add email` / `+ Add phone` inline that POSTs a new `client_contacts` row + marks isPrimary=true.
+>   - **Gap 2 — no multi-contact picker:** clients with multiple contacts per channel (e.g. 3 emails — personal, work, assistant) get only the primary shown. Rep can't pick which one applies to THIS deal. Picker needs a dropdown listing every contact for the channel, pre-selecting the current primary, with each row showing the value + label (Personal / Work / etc.) + a `Set as primary` action + a `+ Add new email` / `+ Add new phone` row at the bottom that POSTs a new client_contacts row.
+>   - **Inheritance clarification — current model already does this:** there's no separate `interests.contactEmail/Phone` column today. The displayed Email/Phone ARE the client's primary contacts (resolved server-side, edited in place via PATCH to `client_contacts`). So edits at the interest level auto-update the client. The user's "vice versa" framing assumes per-interest contact overrides exist — they don't.
+>   - **Two design options for the picker semantics:**
+>     - **Design A (recommended, single source of truth):** picker just chooses which contact to set as `isPrimary=true` for this client. Affects every other surface that reads `clientPrimaryEmail`. No schema change. Simpler.
+>     - **Design B (per-interest contact override):** add `interests.preferred_email_contact_id` + `preferred_phone_contact_id` nullable FK to a specific `client_contacts` row. Each interest can pin a non-primary contact for itself; falls back to client's primary when null. Schema change + service-layer fallback logic + UI to mark "use this for this deal only". Useful only if a single client routinely buys multiple deals with different contact preferences per deal — uncommon for marina sales.
+>     - **Decision-pending:** lean Design A unless leadership confirms the multi-deal-per-client divergence case is real.
+>   - **Effort:** ~3-4h for Design A end-to-end (picker component + empty-state quick-add + service-side `setPrimary` action + tests + accessibility). ~5-7h for Design B with the schema + fallback logic. Captured 2026-05-21 from UAT.
+>   - **SHIPPED (Design A) in 7ecf4ee:** new `<ClientChannelEditor>` combobox. Primary value renders inline (free-text for email, `<InlinePhoneField>` for phone with country code split). Chevron opens a popover listing every contact in the channel — `Make primary` button per non-primary row, delete for non-primaries, inline "Add an email / phone number" with optional Set-as-primary toggle. Backed by existing `/clients/[id]/contacts` CRUD + `promote-to-primary`. Wired into the Email + Phone rows on `interest-tabs.tsx`.
+> - **Inline phone editor on the Contact row** — _src/components/interests/interest-tabs.tsx:973_ — current implementation uses a plain `InlineEditableField` text variant on Phone, so reps can't pick a country code from a dropdown or get AsYouType formatting (both available via `<PhoneInput>` in `src/components/shared/phone-input.tsx`). Wrap `PhoneInput` in a display-vs-edit toggle and PATCH both `value` (national string) + `valueE164` + `valueCountry` to `/api/v1/clients/{id}/contacts/{contactId}`. ~30-60 min. **SHIPPED in 7ecf4ee:** the phone branch of `<ClientChannelEditor>` uses `<InlinePhoneField>` (existing primitive); PATCH writes `value` / `valueE164` / `valueCountry` together. `interests.service.ts` now returns `clientPrimaryPhoneCountry` so the editor can preserve the ISO-3166-1 alpha-2 round-trip.
+> - **ft ↔ m unit switching on Berth Requirements** — _src/components/interests/interest-tabs.tsx_ — the three inline-editable dim rows hard-code `(ft)` in the label. The interest already carries `desiredLengthUnit` ('ft' | 'm'); other surfaces (BerthRecommenderPanel) honour it. Add a small unit toggle that flips the rendered display (and converts on save so the canonical `desired*Ft` column stays in feet). Same pattern as elsewhere in the app (per CLAUDE.md mooring/berth dims model). ~30-45 min.
+> - **Client Overview should summarize current interest's requirements** — _src/components/clients/_ — one-line "current interest needs X × Y × Z" summary on the client detail Overview tab; reps currently have to drill into Interests tab to see what a client wants. ~30 min. **SHIPPED in 7ecf4ee:** `PanelVariant` of `<ClientPipelineSummary>` renders a one-line "Wants L × W × D · Source" under each interest's header when constraints / source are captured. `<ClientInterestRow>` type extended with the new fields; the existing `/api/v1/interests` query already returned them.
+> - **Duplicate Reminder surfaces on Interest Overview** — _src/components/interests/interest-tabs.tsx_ — the legacy "Reminder" panel (driven by `interest.reminderEnabled / reminderDays / reminderLastFired`) and the new "REMINDERS" section (driven by the `reminders` table via the bell-in-header) both render on the same tab and tell different stories. The legacy field still drives a real backend worker (`processFollowUpReminders` in `reminders.service.ts:428` — creates auto-follow-up reminders when no activity in N days), so we can't just delete the field. Approach: hide the legacy "Reminder" panel from the OverviewTab grid; surface the recurring-follow-up config either as a slim row inside the REMINDERS section or as a setting on the interest detail header. Keep the worker untouched. ~1 h. **SHIPPED in f39f0aa:** legacy panel hidden from Overview; worker untouched. Surfacing the recurring-follow-up config on the detail header is parked.
+> - **LinkedBerthsList: no "add another berth" affordance from the card** — _src/components/interests/linked-berths-list.tsx_ — multi-berth interests are first-class (`interest_berths` is the source of truth per CLAUDE.md) but the LinkedBerthsList card doesn't expose an inline "Add a berth" button. Reps have to use the BerthRecommenderPanel below — discoverability gap. Add a CTA button to the card header (gated by `berths.edit`) that opens a picker / sheet to add another `interest_berths` row. ~45 min. **SHIPPED in 3999d4b:** "Add berth" button on the card header; opens a `<Dialog>` with a Command-primitive searchable picker backed by `/api/v1/berths/options`. Berths already linked are filtered out client-side so reps can't double-add. Mutation hits `POST /api/v1/interests/[id]/berths` with `isSpecificInterest` flag; invalidates interest-berths + berth-recommendations caches so the row appears immediately and the recommender drops the just-added berth.
+> - **Supplemental-info-request: link should be reusable, not single-use** — _src/lib/services/supplemental-info_ (token model) — current email says "can only be used once"; user wants it valid until expiry so a partial submission can be revisited. Drop the single-use guard, keep TTL gate. Audit the public endpoint to ensure no token-fingerprint reuse risk before lifting the limit. ~30 min. **SHIPPED in b74fc56:** `applySubmission` drops the `isNull(consumedAt)` filter; TTL is the sole validity check. Public form's "already submitted" lockout screen replaced with a soft amber banner noting that re-submission overwrites the previous data. `consumedAt` still stamped for last-submitted context.
+> - **SHIPPED in 431375d (E26):** Service: `listTokensForInterest` (latest 20 issuances with expired/consumed flags) + `getTokenForResend` (snapshots token back into issue-shape for re-email). Route: GET lists; POST accepts optional `tokenId` for resend branch (forces sendEmail=true), returns `resent: true/false`. UI: three actions (Generate/Regenerate, Generate+email or "New link+email", Resend current — only with active unconsumed unexpired token) + issuance history list with Active/Submitted/Expired per row. Supplemental-info-request: distinct Regenerate vs Resend actions + issue history — _src/components/interests/supplemental-info-request-button.tsx:83_ (the current "Resend" label) + _src/lib/services/_ (the issue endpoint that today mints a new token on every POST) — once the link becomes reusable-until-expiry (per the "should be reusable, not single-use" finding above), the single "Resend" button conflates two semantically different actions: (a) mint a NEW token (invalidates the previous one — needed when the old one expired, was leaked, or the client deleted the email), and (b) re-email the EXISTING still-valid token (needed when the client just lost the email — same token, same form-state, just push through SMTP again so they can pick up where they left off). The current implementation always does (a) — the "Resend" copy is misleading. Plus once we have reusable tokens, the rep loses visibility into "what token did we send when?" — the inline `link` state only holds the last-minted one.
+>   - **Fix:**
+>     - **(a) Service split:** `regenerateSupplementalLink(interestId)` mints a new token + invalidates outstanding ones for the same interest (or keeps them parallel — design call; recommendation: invalidate, so one client only has one valid link at a time and the rep doesn't have to reason about which one is which). `resendSupplementalLinkEmail(tokenId)` emails the named existing token via SMTP without mutating the token table. Two API routes: `POST /api/v1/interests/{id}/supplemental-info-request` for regenerate, `POST /api/v1/interests/{id}/supplemental-info-request/{tokenId}/resend` for resend.
+>     - **(b) UI:** swap the single button for a small action group that surfaces the most recent valid token's metadata (`Issued <relative time> · expires in <N days>`) with two buttons next to it — `Resend email` (primary, fires resend on the existing token) + `Regenerate link` (ghost, mints new). If no valid token exists, show only `Generate link`. Pair this with the "separate generate + send" finding below so the rep can also generate-without-sending (e.g. share through WhatsApp).
+>     - **(c) History:** small expandable section "View past requests" listing the last 3-5 issued tokens with timestamp + status (active / expired / submitted / revoked). Each row gets a "Revoke" action for the active ones (defensive — covers the "we sent it to the wrong email" case). Schema-wise this is just rendering existing rows in the supplemental-info-tokens table.
+>   - **Effort:** ~2-3h end-to-end including the service split, two API routes, UI rework, audit-log entries on each action, and a vitest covering the resend-doesn't-mutate-token guarantee. Captured 2026-05-21 from UAT. Cross-ref: ties into the "link should be reusable, not single-use" + "separate generate link and send email" findings — best done as one coherent rework.
+> - **Supplemental-info-request: separate "generate link" and "send email"** — _src/components/interests/supplemental-info-request-button.tsx_ — currently one button auto-generates + sends. User wants two steps: button 1 generates + shows the link (rep can copy / share manually); button 2 sends the templated email through SMTP. Backend change: split the existing service into `generateSupplementalLink()` and `sendSupplementalLinkEmail(linkId)`. UI change: replace single-click action with two-step UI showing link state. ~1 h. **SHIPPED in a4e30ea:** API route now accepts `{ sendEmail?: boolean }` (defaults true for back-compat); UI shows two distinct buttons — "Generate link" and "Send by email" (becomes "Regenerate link" + "Generate + email" depending on state). Email body copy also drops the "can only be used once" sentence since PR15 made tokens reusable.
+> - **SHIPPED in 94c24a1 (F28):** Past strip on Interest overview becomes an `<Accordion>` — each row collapses to the same one-line summary as before, expands to render the full `<MilestoneSection>` (steps list, sub-status, inline doc actions). Reuses MilestoneSection so no new per-milestone rendering needs maintaining. Past-milestones strip → expandable history with inline doc preview — _src/components/interests/interest-tabs.tsx_ (the past-milestones strip at ~line 863) — currently a one-line collapsed summary per past milestone (just title + summary). Reps want to drill into the history of a specific milestone (e.g. see which EOI round was signed, the doc contents, who signed, when). Convert the strip into an accordion: each past milestone expands to show its associated docs + sub-status timeline + inline PDF preview using the existing pdf viewer primitive. Useful for deals with multiple EOI rounds (rework after rejection, re-sent reservation agreements, etc.) where audit trail matters. ~3-4 h.
+> - **InterestBerthStatusBanner: name + link the competing deal** — _src/components/interests/interest-berth-status-banner.tsx_ — the banner that surfaces when a linked berth is under offer to a different active deal currently just says "this berth is under offer elsewhere" without identifying which interest. Reps want a small inline detail: client name + deal stage + a link button to the competing interest, so they can size up the situation (e.g. "this lead won't make it, treat ours as backup"). Service-side: extend the `getInterestBerthStatus()` (or equivalent) response with a `competingInterest: { id, clientName, pipelineStage, ... } | null` field, then surface in the banner. Permission-gate the link by `interests.view`. ~1 h. **SHIPPED in 7ecf4ee:** reuses `/berths/[id]/active-interests` endpoint (already-shipped 292a8b5) instead of extending the original `getInterestBerthStatus()` call. One query per conflicting berth via `useQueries`; picks the `isPrimary` competing interest (falls back to first non-self row); renders inline `<Link>` to the competing detail page. Falls through gracefully when the endpoint hasn't resolved yet.
+> - **Notes Latest-note teaser missing round / stage context pill** — _src/components/interests/interest-tabs.tsx_ (the "Latest note" block around line 1029-1064) — notes created during a specific stage / EOI round should display a small "Round 2" or stage pill next to the timestamp so reps can see at a glance which phase a note belongs to. Currently shows author + time only. Schema: notes table doesn't carry round info today — would need a derived display from the interest's stage at note creation time (cheapest) or a stamped `created_during_stage` column (more reliable). ~45 min for derived display, ~1.5 h with migration for stamped column. (Same need likely applies to all notes lists, not just the Overview teaser.) **SHIPPED (current-stage variant) in 7ecf4ee:** stage-badge chip next to the timestamp using `STAGE_BADGE` colour map. Shows the deal's CURRENT pipelineStage — historical "stage-at-note-time" lookup would need a per-render `audit_logs` read, over-engineered for a context hint. NotesList rows on other surfaces (full Notes tab) deferred until a real need surfaces.
+> - **Dimensions columns: add ft↔m toggle in the column header (persisted to user prefs); skip per-row entry-unit indicator** — _src/components/berths/berth-columns.tsx:306_, _src/components/yachts/yacht-columns.tsx:102_, _src/components/clients/client-yachts-tab.tsx:63_, _src/components/companies/company-owned-yachts-tab.tsx:106_ (any current/future Dimensions column), plus _new_ `src/lib/utils/dimensions.ts` for the conversion + format helper, and _src/lib/db/schema/users.ts_ `user_profiles.preferences` for the persisted preference key — five table surfaces render "Dimensions" in feet today; reps used to metric units have to convert in their head.
+>   - **Recommendation on the per-row indicator question:** **column-level toggle alone is enough.** The schema already stores per-dimension entry-unit discriminators (`lengthUnit`, `widthUnit`, `draftUnit` on berths + same pattern on yachts/interests, default `'ft'`) and even keeps separate `_M` numeric columns where metric originals exist (`nominalBoatSizeM`, `waterDepthM`) — so the _data_ knows what was entered. But surfacing that on every row in the table creates visual noise (a small "m" pill next to half the rows) that doesn't help the rep complete a task. The right time to surface entry-unit fidelity is at **EOI / contract / quote generation** time — the merge field renderer should pull the unit + value as entered so the legal document matches the rep's original input verbatim. So: column toggle for UI display, entry-unit honoured in document generation (which already happens for the EOI dialog via `effectiveDimensionUnit`).
+>   - **Implementation:**
+>     - (a) Helper: `src/lib/utils/dimensions.ts` exporting `convertFt(value, to: 'ft' | 'm')`, `formatDimension(value, unit)` (with locale-aware decimals: 1.5 m vs 4.9 ft), and `formatDimensions(l, w, d, unit)` for the L × W × D triple. Tiny, deterministic, unit-tested.
+>     - (b) Preference: extend `user_profiles.preferences` (JSONB) with a `dimensionUnit: 'ft' | 'm'` key (default `'ft'`); already a JSON column so no migration needed beyond a TS type extension.
+>     - (c) Hook: `useDimensionUnit()` returning `{ unit, setUnit }` backed by React Query + a PATCH to `/api/v1/me/preferences` on change. Optimistic update.
+>     - (d) UI: replace the literal `"Dimensions"` header string in each column definition with a small `<DimensionUnitToggle />` component (label + segmented toggle `ft | m`). Column body cells render via the formatter. Apply to all 5 surfaces in one pass for visual consistency.
+>     - (e) Document-generation path: leave EOI / contract / template merge-field rendering untouched — it already pulls entry-unit values per `effectiveDimensionUnit` in the EOI dialog (per CLAUDE.md merge-field architecture).
+>   - **Effort:** ~1.5-2h end-to-end (helper + pref + hook + toggle component + 5 column-definition swaps + a vitest for the formatter). The toggle persists across page reloads + tabs by virtue of going through `/me/preferences`. Captured 2026-05-18 from UAT.
+> - **Berth list: "Rates (USD)" + "Pricing valid" columns hidden by default (or removed) — short-term rental fields irrelevant to purchase/long-term ports** — _src/components/berths/berth-columns.tsx:391-417_ + _src/lib/db/schema/berths.ts:62-69_ + the NocoDB import that populates them. These columns surface daily/weekly slip rental rates + a `pricing_valid_until` date — relevant for marinas that lease berths by the day/week (transient marinas), irrelevant for Port Nimara's sales-only model. Visible by default in `DEFAULT_VISIBLE_COLUMNS` (line 123-124), so every Port Nimara user sees two columns of `—` cluttering the table.
+>   - **Path (recommended): hide by default, keep available in column picker.** Drop `'rates'` + `'pricingValidUntil'` from the default-visible array; reps at a transient-rental port can enable via the existing Columns picker. Preserves the schema + import paths for future ports without removing functionality. ~5 min.
+>   - **Smarter alternative (Path 3 in the chat thinking):** conditional default-visibility — only include `'rates'` + `'pricingValidUntil'` in the default-visible set if the port has at least one non-null rate value. Auto-shows for ports that use them, auto-hides for ports that don't. ~30 min including the port-level data check + cache invalidation when rates land. More polished but heavier.
+>   - **Aggressive alternative (Path 1):** delete the columns + the four `*_usd` schema columns + the import paths if no port ever plans to use them. Decision: defer until we know whether ANY port in the roadmap does transient rentals. For now, hide-by-default is the right call.
+>   - **Bundle with:** the "trim default-visible columns" recommendation in the platform-wide table-density finding below — same audit pass, same author.
+>   - **Effort:** ~5 min (Path: hide-by-default). Captured 2026-05-21 from UAT.
+> - **SHIPPED in c14f80a (Q59):** DataTable cells default to `whitespace-nowrap` so long values don't wrap into 4-5 lines. Columns needing wrapping override via column def's `meta.wrap = true`. Min-width comes from `column.getSize?.()` when set — opt-in per column rather than sweeping width change. **Platform-wide table density: cells shrink-wrap content instead of triggering horizontal scroll — columns need min-widths + nowrap defaults** — _src/components/ui/table.tsx:7_ (wrapper is already `overflow-auto`, good ✓) + _src/components/ui/table.tsx (TableCell base — missing `whitespace-nowrap`)_ + _src/components/berths/berth-columns.tsx_ (no `size`/`minSize` on any column except line 447's `size: 48` outlier) + every other DataTable column definition in the app. Surfaced on the berths list (UAT 2026-05-21): with ~14 columns visible, every cell wraps into 3-6 lines because the table tries to fit everything in viewport. Example pain: "Bull bollard type B · 40 ton break load" wraps into 6 lines; "63m × 14.19m (draft 4.42m)" wraps into 3 lines; "Car (3t) to Vessel" wraps into 3 lines. Result: row height bloats to 200px+, the table becomes nearly unusable.
+>   - **Fix (platform-wide, single PR):**
+>     - **(a) TableCell base default:** add `whitespace-nowrap` to the base TableCell className in `src/components/ui/table.tsx`. Single-line content stays single-line. Cells that genuinely need wrapping (long note teasers, etc.) opt-out via `className="whitespace-normal"` per-cell.
+>     - **(b) Per-column `min-w-[X]` token system:** define a small set of width tokens in a shared helper based on content type — `colW.short` (status badges, count chips), `colW.medium` (mooring numbers, short labels), `colW.long` (dimensions, addresses), `colW.money` (price columns). Apply via TanStack `size: ...` or via cell className `min-w-[X]`. Reuse across every DataTable.
+>     - **(c) Truncate-with-tooltip for verbose cells:** the Cleat / Bollard / Access columns carry strings like "Bull bollard type B · 40 ton break load" — too long for any reasonable column width. Apply `truncate max-w-[200px]` + `title={value}` so the cell shows ellipsis + full text on hover. Optionally wrap in a `<Tooltip>` for touch parity on mobile.
+>     - **(d) Audit visible-by-default columns:** with 14 columns showing on the berth list, even with correct widths the table is overwhelming. Trim the default-visible set to 7-8 essentials (Mooring, Area, Latest deal stage, Active interests, Dimensions, Boat size, Price, Status) and move the rest behind the existing Columns picker (already wired per CLAUDE.md). Reps who need bollard/cleat/access details can enable those columns explicitly.
+>   - **Apply to all DataTable surfaces:** berths list, interests list, clients list, yachts list, companies list, reservations list, invoices list, audit-log list, expenses list. Each has its own column file; single audit pass tags the min-w token per column.
+>   - **Effort:** ~3-4h end-to-end (TableCell base + width token helper + column-def sweep + truncate-tooltip on verbose cells + default-visible audit). Captured 2026-05-21 from UAT.
+> - **Berth list "Latest deal stage" column: make sortable by pipeline-stage rank** — _src/components/berths/berth-columns.tsx:273-287_ + _src/lib/services/berths.service.ts:80-120_ — the column currently has `enableSorting: false`; sorts by status / area / active interests / etc. already work via the existing `sortColumn` switch + `customOrderBy` correlated-subquery pattern (see `activeInterestCount` at lines 107-120). latestInterestStage isn't a column on `berths` — it's the highest-ranked active interest's stage, populated in a two-pass post-fetch.
+>   - **Fix:** (a) drop `enableSorting: false` on the column. (b) Add a `'latestInterestStage'` case to the sortColumn switch returning `null` (handled in customOrderBy, like `activeInterestCount`). (c) Add a `stageSort` correlated subquery mirroring `demandSort`: select the rank of the highest-active-stage interest per berth via a `CASE i.pipeline_stage WHEN 'enquiry' THEN 1 WHEN 'qualified' THEN 2 ... WHEN 'contract' THEN 7 END` ladder, then `ORDER BY ... ASC/DESC` per `query.order`. Filter same as demandSort (`port_id`, `archived_at IS NULL`, `outcome IS NULL`). Berths with no active interest → NULL; use `NULLS LAST` (ascending) / flip per direction so they land at the bottom regardless.
+>   - **Effort:** ~45 min. Pure additive — no schema work, no API contract change. Captured 2026-05-18 from UAT. **SHIPPED in ca51000:** column toggles to `enableSorting: true`; service-side adds a `stageSort` correlated subquery via the existing `customOrderBy` pattern (ranking 1=enquiry through 7=contract; NULLS LAST regardless of direction).
+> - **SHIPPED in 991e222 (C23):** New `POST /api/v1/berths/bulk` mirroring `/interests/bulk` (discriminated union: change*status / change_tenure_type / add_tag / remove_tag / archive; 500-id cap; per-row failure reporting; routes status mutations through `updateBerthStatus` so under-offer/sold transitions still trigger primary auto-link + rules engine). BerthList toolbar wires `bulkActions` on DataTable with confirm dialogs sharing one `bulkMutation` for consistent toast + invalidation. Berth list: bulk-edit affordance (parity with bulk-add) — \_src/components/berths/berth-list.tsx* + _berth-columns.tsx_ + _src/lib/services/berths.service.ts_ + _new_ `src/app/api/v1/berths/bulk/route.ts` — bulk-add for berths exists; bulk-edit doesn't, so any cross-row mutation (status flip on a row range, price re-tier on a pontoon, tag application, area rename, archive a season's worth) is a 50× one-row-at-a-time grind. **Cross-reference:** the Bucket 3 finding "Bulk-price editing UI" already shipped the price-specific backend (`POST /api/v1/berths/bulk-update-prices`); this is the broader sibling covering every other column reps want to edit in bulk. Coordinate the two as a single rollout.
+>   - **Scope:** (a) Row-select infra on `<DataTable />` — checkbox column, "select all on page" / "select all matching filters" header, persistent selection across pagination (~1h, mirror `InterestList`'s `bulkActions` pattern). (b) Bulk-actions bar on ≥1 row selected: change status, change area, set price / % adjust (folds in the already-built endpoint), add/remove tags, archive/restore, export selection CSV — each opens a small confirm/edit dialog (~2-3h). (c) Unified backend `POST /api/v1/berths/bulk` (mirror `/interests/bulk`) taking `{ action, ids, ...args }`, port-validates IDs, per-row transactional with per-row failure summary so the rep sees which of 50 berths failed and why; per-row audit + realtime fan-out; cap 500 IDs (~2-3h incl tests). (d) Each action gated by the appropriate berth perm (`berths.edit`, `berths.update_prices`, `berths.archive`, `tags.manage`); endpoint enforces the most-restrictive perm of the requested action (~30min).
+>   - **Effort:** ~5-7h end-to-end. Captured 2026-05-18 from UAT.
+> - **BulkAddBerthsWizard: block proceed when any mooring already exists in the port** — _src/components/admin/bulk-add-berths-wizard.tsx_ + _src/lib/services/berths.service.ts_ (new pre-flight check) — the wizard's review/preview step should validate the to-be-added mooring numbers against existing rows for the port and block "Submit" if any duplicates are found (rather than relying on a DB-constraint error mid-insert, which today doesn't even fire because there's no partial unique index on `(port_id, mooring_number)` — see Bucket 4 #1 "Duplicate E17 row" which captured the missing constraint).
+>   - **Fix:** (a) on entering the preview step, fire a `GET /api/v1/berths/check-moorings?port=<id>&moorings=A1,A2,...` (cap ~500 per call) that returns `{ existing: [{ mooringNumber, id }] }`. (b) If non-empty, show an inline error panel listing the conflicts (linked to the existing berths) and disable Submit; offer a "Remove conflicts and continue" button that drops the dupes from the wizard payload before re-enabling Submit. (c) Pair this with the partial unique index fix from Bucket 4 #1 so the DB-level guard exists as a backstop — UI validation prevents the friction; DB constraint prevents the silent dup. (d) Same pre-flight should run on per-row "single add" flow for parity.
+>   - **Effort:** ~1.5h (endpoint + index + UI panel + tests). Captured 2026-05-18 from UAT.
+>   - **SHIPPED in ca172fa:** `POST /api/v1/berths/check-duplicates` accepts up to 500 mooring numbers, returns the subset that already exist as non-archived berths (canonical `^[A-Z]+\d+$` regex validation, `berths.import` perm). Wizard fires the check during the Step 1 → Step 2 transition with a "Checking…" Continue button. Step 2 banner lists first 8 duplicates + a "Remove all duplicates" action; duplicate rows render amber-tinted with a "Dup" pill. Submit disabled while any dup remains, tooltip explains. Partial unique index `(port_id, mooring_number) WHERE archived_at IS NULL` follow-up (Bucket 4 #1) parked.
+> - **Yacht Overview: verify bidirectional ft↔m auto-convert is visually reflecting (logic exists; UI may not be updating)** — _src/components/yachts/yacht-tabs.tsx:99-137_ (`saveDimension`) + _src/components/yachts/yacht-tabs.tsx:68-80_ (`useYachtPatch` cache invalidation) — the bidirectional auto-conversion IS already implemented: `saveDimension()` patches both the primary field and the converted counterpart in one PATCH, and `onSuccess` invalidates `['yachts', yachtId]`. User report ("needs to autofill with auto-converted measurements") suggests the UI isn't visually updating after save — most likely the parent that passes the `yacht` prop into `OverviewTab` either (a) doesn't share the `['yachts', yachtId]` cache key (invalidation fires, no consumer refetches), (b) is hydrated via server-component `initialData` with no client refetch, or (c) the `InlineEditableField` for the counterpart memoizes its initial value and doesn't re-render when the upstream prop changes.
+>   - **Verify path:** (i) confirm the yacht detail page's `useQuery` cache key matches `['yachts', yachtId]` exactly — any mismatch (`['yacht']` singular, `['yacht-detail']` wrapper) makes the invalidation a no-op. (ii) Confirm `staleTime` / `refetchOnMount` allow refetch on cache bust. (iii) If the parent refetches but the field still doesn't visually update, force-re-render via `key={yacht.lengthM}` on the counterpart InlineEditableField.
+>   - **Apply to sibling surfaces:** the same bidirectional save belongs on **berth detail OverviewTab** — berth schema has `lengthM`/`widthM`/`draftM` + `_unit` discriminators and likely shows the same dual ft/m sections (verify); copy the `saveDimension()` pattern. Use the shared `src/lib/utils/dimensions.ts` helper from the earlier Dimensions-column toggle finding so the conversion ratio is centralized.
+>   - **Effort:** ~20-30 min for the yacht debug + visual-update fix, +30 min if a berth equivalent needs the same logic. Captured 2026-05-18 from UAT.
+>   - **SHIPPED (round-trip lossless + dedup) in 8e9efe5:** three copies of the conversion logic existed (yacht-dimensions.ts canonical, yacht-form.tsx local, yacht-tabs.tsx local) — the form-side ones used 2dp precision so `1 ft → 0.30 m → 0.98 ft` lost data on the round-trip. Consolidated both surfaces onto `feetToMeters`/`metersToFeet` from yacht-dimensions.ts and bumped precision to 4dp. New `tests/unit/yacht-dimensions.test.ts` proves round-trip lossless on the canonical 12.5 ft ↔ 3.81 m UAT case + sweeps 1/5/12.5/25/50/120/250 ft and 0.5/1/3.81/7.62/15.24/36.58 m (29/29 ✓). UI cache-key + InlineEditableField re-render path are independent debug items — flag for separate verification.
+> - **SHIPPED in 94c24a1 (G30):** Users page wraps existing UserList + InvitationsManager in Tabs control (Active users / Invitations). Standalone /admin/invitations route returns a redirect to merged page for bookmark back-compat. Removed nav catalog entry + admin-sections-browser tile; extended Users catalog keywords with "invitations / pending invites / onboarding" so command-K still lands on the right surface. Merge `/admin/invitations` into `/admin/users` — single "people with access" surface — _src/app/(dashboard)/[portSlug]/admin/users/page.tsx_, _src/app/(dashboard)/[portSlug]/admin/invitations/page.tsx_ (to be removed), _src/components/admin/users/_, _src/components/admin/admin-sections-browser.tsx:90-95_ (drop the Invitations card from the Access section), _src/lib/services/_ (invitations service likely already separate — keep it) — active users and pending invitations are the same lifecycle (a person who has or should have port access). Splitting them across two admin pages forces admins to bounce between surfaces to answer "who has access here?". Merging gives them one canonical "people" page.
+>   - **Approach:**
+>     - **(a) Page shape:** keep route at `/admin/users`. Add a state filter at the top: `All | Active | Invited (pending) | Disabled | Archived`. Default to `Active`. The existing Users table extends to render invitation rows alongside active users, distinguished by a "Pending" badge + last-sent timestamp + "Resend" / "Revoke" kebab actions. Active-user kebab keeps current actions (edit role, reset password, disable). One unified `+ Invite user` button in the page header opens the existing invitation form. Search across both populations (name / email / role).
+>     - **(b) Data shape:** the users table already returns user rows; extend the list endpoint (or add a parallel one that the page composes) to also yield pending invitations as a discriminated-union row type `{ kind: 'user' | 'invitation', ... }`. Keep the underlying tables separate (no schema change); the page just stitches both query results into one table. Filter at the API layer when `state=active` excludes invitations, etc.
+>     - **(c) Removal:** delete `/admin/invitations/page.tsx`, the Invitations card from the Access section, any sidebar/search-catalog entries pointing at the old route. Add a `redirect()` from the old route to `/admin/users?state=invited` so any bookmark / external link lands in the right place.
+>     - **(d) Roles & Permissions stays separate** — different concept (template vs individual), low edit frequency, would bury both if merged. Cross-link: each user row's role chip → opens role edit page; role detail page → "N users with this role" with a link back.
+>   - **Permission gating:** confirm the unified page enforces the OR of permissions for both surfaces (`users.view` for the user rows, `invitations.manage` for sending/revoking). The "Invite" button gates on `invitations.manage`; the kebab actions per-row gate appropriately.
+>   - **Effort:** ~3-4h end-to-end — table extension + state filter + invitation rows + the API stitch + redirect + sidebar/catalog cleanup + tests. Captured 2026-05-18 from UAT.
+> - **Consolidate every AI-feature admin control onto `/admin/ai` — REMOVE from current scattered locations (reinforced UAT 2026-05-21)** — _src/app/(dashboard)/[portSlug]/admin/ai/page.tsx_ + _src/components/admin/_ (new per-feature embedded forms) + _src/lib/db/schema/ai-usage.ts_ (existing ai*usage table for spend rollup) + \_src/components/admin/ocr-settings-form.tsx* (pattern to mirror) — the AI admin page already has master controls (`ai.master`), provider credentials (`ai.providers`), and the Receipt OCR settings embedded inline. The "Per-feature settings" card I just removed pointed at two dead routes (`../berth-pdf-parser`, `../recommender`) — surfacing the gap that AI feature-tuning isn't consistently centralized. User wants every AI-using feature's admin knobs reachable from one page.
+>   - **Scope (only include features that actually call an LLM today; don't include aspirational ones):**
+>     - **Berth PDF parser AI fallback** — 3-tier parse per CLAUDE.md (AcroForm → OCR → optional AI on low confidence). Knobs to expose: provider override (per-feature override of the global `ai.providers` choice), confidence threshold below which the AI tier fires, per-call budget cap, prompt template (advanced/optional). New embedded form `<BerthPdfParserAiSettingsForm embedded />` reading registry section `ai.berth_pdf_parser`.
+>     - **Receipt OCR** — already there ✓
+>     - **Future-feature placeholders explicitly NOT included until they ship:** berth recommender (currently "Pure SQL (no AI)" per CLAUDE.md — surfacing it as an AI setting today would mislead admins into thinking they're tuning an LLM); AI-assisted contact-log action extraction (Bucket 3 #7 future feature); AI inquiry intake parsing if/when it ships. Add each to `/admin/ai` only when the underlying feature lands.
+>   - **AI spend dashboard at the bottom of the page** — new card showing: current month spend total (across all AI features), top 3 features by spend, recent expensive calls (model, feature, cost, timestamp). Reads from `ai_usage` table. Helps admins debug cost spikes without leaving the AI page. Optional but high-leverage for an admin who just saw a budget alert.
+>   - **Cross-linking principle:** each per-feature AI section on `/admin/ai` shows a small "Non-AI settings for this feature live at →" link to the corresponding admin page (e.g. for berth PDF parser, link to wherever the OCR confidence + AcroForm overrides live). Vice-versa: each feature page gets a "AI fallback settings live at /admin/ai →" link in the relevant section. Keeps the split-brain risk in check — admins always have a one-click path between the two.
+>   - **Effort:** ~30 min for the berth PDF parser embedded section + registry definition, ~1.5h for the AI spend dashboard, ~30 min for the cross-link sweep, ~30-45 min for the explicit removal-from-other-surfaces audit (grep every admin page for AI toggle / API-key field / model-selector / temperature-slider and migrate to /admin/ai). Total ~3h. Captured 2026-05-18 from UAT, reinforced 2026-05-21 (user spotted yet another scattered AI setting in `src/components/admin/settings/settings-manager.tsx:241` — confirms the consolidation work needs explicit "delete from old location" alongside "add to new location" to avoid drift). Captured 2026-05-21 reinforcement.
+>   - **Explicit removal scope** — audit and remove (not just add to /admin/ai):
+>     - Any AI-related setting inside `settings-manager.tsx` SettingsManager cards
+>     - Any model/temperature/provider fields inside per-feature admin pages (OCR settings, berth-PDF settings, template-editor settings)
+>     - Any AI-related env-resolver fields exposed via RegistryDrivenForm on non-AI admin pages
+>     - Cross-link replaced original location with a small banner: "AI settings for this feature live at `/admin/ai` →" (per the cross-linking principle already in the entry).
+> - **Password-reveal eye toggle silently no-ops when value resolves from env (or anywhere outside port/global)** — _src/components/admin/shared/registry-driven-form.tsx:440-463_ (eye-toggle click handler) + _src/app/api/v1/admin/settings/[key]/reveal/route.ts_ (server endpoint that intentionally refuses to leak env-resolved secrets per its docstring) — user clicks the eye on a sensitive field and the dots stay, no toast, no error. Root cause: the click handler only fires `reveal.mutate()` when `resolved?.isSet && resolved.source ∈ {'port', 'global'}`. When the value is resolved from `env` (legacy `.env` fallback) or `default`, the handler skips the reveal call and just sets `setShowSecret(true)`. The Input then flips `type` from `password` to `text` — but the draft is still empty, so the placeholder `'••••••••'` (set unconditionally for `sensitive` fields at line 555) keeps rendering. Net effect: indistinguishable from "the toggle is broken."
+>   - **Fix options:**
+>     - **(a) Best UX:** show a clear inline message + tooltip on the eye button when `resolved.source === 'env'` (or `'default'`): "Value comes from the environment — cannot reveal in-app. Configure in admin to view." Disable the button or change its tooltip so the user knows why nothing happens. ~15 min.
+>     - **(b) Optional:** allow env-reveal under a stricter permission (e.g. `admin.reveal_env_secrets`) — defaults off, super-admin only. The server endpoint's "refuses to reveal env" guard would honour the permission as an override. Riskier; only do this if there's an operational need. Capture as Bucket 3 if pursued.
+>     - **(c) Diagnose path:** add a console.warn / dev-mode toast when the click is swallowed silently so the next person debugging this can see what's happening.
+>   - **Sibling check:** the server-side route comment at lines 21-22 says it "refuses to reveal values resolved from env or default," but the implementation at lines 39-52 just calls `getSetting()` and returns whatever it gets — there's no actual refusal check in the route handler. If `getSetting()` reaches into the env fallback the endpoint would leak env values. Verify the refusal is enforced upstream in `getSetting()` (or in the registry resolver) — if not, that's a separate finding (low/medium severity bug: env secrets leakable via API to anyone with `admin.manage_settings`). Worth running through to confirm.
+>   - **Effort:** ~15 min for (a) UI message + tooltip; ~30 min if the route's env-refusal check needs to be added too. Captured 2026-05-18 from UAT. **SHIPPED (a) in ca51000:** eye toggle now `disabled` + `title` tooltip when value resolved from env/default. Sibling check on the route's env-refusal guard deferred to a security-side follow-up.
+> - **SHIPPED in 94c24a1 (H32):** Email settings page gains an explainer panel above the SMTP cards spelling out why noreply + sales have separate credentials and which workflows ship from each. Existing field titles gained "(noreply)" suffix so the model maps cleanly. Email settings page: add explainer copy clarifying why sales send-from and noreply have separate credentials — _src/app/(dashboard)/[portSlug]/admin/email/page.tsx_ (the page) + _src/components/admin/sales-email-config-card.tsx_ (the sales card) + the existing noreply transport card — the admin page renders two cards with overlapping field names (SMTP host/port/user/pass on both, plus IMAP on the sales card) and zero context for why both exist. Operators reasonably ask "why am I configuring this twice?" The two streams are intentionally separated (per CLAUDE.md "Send-from accounts (sales send-outs)"): sales = human-initiated rep emails with IMAP-bounce-poll monitoring; noreply = fire-and-forget automation (portal invites, password resets, signing reminders, inquiry confirmations). Reasons to keep them separate include sender reputation (mixing transactional volume with human sends hurts deliverability), reply handling (reps need replies in a monitored mailbox; automation shouldn't generate reply threads), and the practical pattern of using a transactional provider (Postmark/SendGrid) for noreply + Google Workspace / Outlook for the sales mailbox.
+>   - **Fix:** add an explanatory header block at the top of the email-settings page (above the two cards) summarizing the split in plain language: 2-3 sentences max + a small table (sales vs noreply, what each sends, why split). Each card's CardDescription gets a one-liner anchoring to its role ("Used for rep-initiated emails (berth PDFs, brochures, manual follow-ups). Replies land in this mailbox and are bounce-monitored via IMAP." / "Used for automated emails (portal invites, password resets, signing reminders). Replies bounce."). Optional: a "Quick setup" toggle/button — "Use one mailbox for both streams" — that auto-mirrors SMTP creds from sales → noreply (or vice versa) for ports that don't need the split. Default state stays split (preserves the design intent for ports that have grown into it).
+>   - **Effort:** ~30 min for the explainer copy + per-card descriptions; +1h for the "Quick setup" mirror affordance if pursued. Captured 2026-05-18 from UAT.
+> - **Email / SMTP admin: add a "Send test email" affordance** — _src/components/admin/shared/registry-driven-form.tsx_ (or a dedicated email-settings card adjacent to the RegistryDrivenForm) + _src/lib/email/_ (transport) + _new endpoint_ `POST /api/v1/admin/email/test-send` — once an admin configures SMTP creds + From address on the Email Settings page, they have no in-app way to confirm "did I actually wire this up correctly?" without finding a workflow that triggers a real transactional email. Add a "Send test email" button on the email settings card that pops a small dialog: input for destination address (defaults to the operator's own email), optional message body, submit fires the test via the configured transport. Server endpoint returns success / SMTP-error-with-detail so the admin sees exactly why it failed (auth fail, TLS handshake, sender-rejected) without digging into server logs.
+>   - **Implementation:** (a) UI: small "Send test email" button in the card actions, opens a Dialog with a single email-validated input + "Send" button. (b) Endpoint: `POST /api/v1/admin/email/test-send` with `{ to: string, subject?: string }`, gated by `admin.manage_settings`. Body: brief branded test ("This is a test from <Port Name> admin — if you got this, SMTP is working."). (c) On the server: pull the live transport config via the resolver chain (port-override → env), construct via nodemailer, send, return `{ success: true, messageId }` or `{ success: false, error: ... }` with the raw SMTP error reason. (d) Audit log a `test_email_sent` row so operators can see who tested and when.
+>   - **Honour the dev `EMAIL_REDIRECT_TO`** — same as production transactional emails: if set, prefix subject and reroute so QA doesn't spam users.
+>   - **Cross-ref:** related to the Documenso-config diagnosis loop (Bucket 3 #8 platform-wide error message audit) — same pattern of "configure-then-verify-without-real-workflow." Apply the same idiom to other integrations: Documenso test-send, S3 ping, Redis ping, IMAP test-connect.
+>   - **Effort:** ~1.5h for email (UI + endpoint + audit + dev-redirect honour). +1-2h each for the sibling integration test-ping buttons if pursued in the same pass. Captured 2026-05-18 from UAT.
+>   - **SHIPPED in 7881da6:** `POST /api/v1/admin/email/test-send` route gated on `admin.manage_settings`; reuses `sendEmail(..., ctx.portId)` so per-port SMTP overrides + `EMAIL_REDIRECT_TO` honour are exercised the same way a real notification would. Sends a minimal plaintext-only message (no logo, no branded shell) so the failure mode is pure transport — distinct from the branding-page "Send a test" which exercises the rendering pipeline. New `<SmtpTestSendCard>` on `/admin/email` between the SMTP overrides form and the SalesEmailConfigCard. Errors surface inline below the input (auth failure, ENOTFOUND, connection refused, etc.) rather than as a passing toast — whole point is to read them. Sibling test-ping buttons for Documenso / S3 / Redis / IMAP parked.
+> - **YachtPicker: opening returns no yachts (empty `q` → empty list); should return a default list** — _src/app/api/v1/yachts/autocomplete/handlers.ts:10-12_ + _src/components/yachts/yacht-picker.tsx:56-60_ — the autocomplete handler short-circuits with `{ data: [] }` when `q` is empty: `if (!q) { return NextResponse.json({ data: [] }); }`. The picker fires the query the moment it opens with `debounced=''` → user opens, sees empty state, has to start typing before any options appear. Dead-end UX.
+>   - **Fix:** (a) handler: when `q` is empty, return the top 20-30 yachts for the port (most-recently-updated default; if `ownerType`/`ownerId` query params are provided, filter server-side to that owner). Trivial — just drop the early-return and pass `q` as optional to the `autocomplete()` service, which defaults to an empty search term meaning "no name filter". (b) Picker: extend the query string to include the owner filter so server-side filtering works (currently the picker filters client-side post-fetch, which means a yacht owned by someone other than the current `ownerFilter` may not even reach the client if it's outside the default-20). (c) UX nicety: the picker's `placeholder` could include "or search…" so the user knows typing also works.
+>   - **Effort:** ~30 min. Captured 2026-05-18 from UAT. **SHIPPED (a) in 2bcf544:** autocomplete handler drops the early-return; service returns top 20 most-recently-updated yachts when `q` is empty. (b) owner-side server filtering remains client-side as before; (c) deferred.
+> - **YachtPicker: selected yacht renders as `Yacht <uuid-prefix>` when not in the autocomplete results** — _src/components/yachts/yacht-picker.tsx:75-79_ — the trigger button label is `match?.name ?? `Yacht ${value.slice(0, 8)}``— the fallback fires whenever the currently-selected yacht isn't in`rawOptions`(e.g. picker was opened with a pre-set value from a URL param / parent default and the autocomplete results don't include it, OR the user typed a search that filtered it out). Result: reps see`"Yacht 3bd83076"` instead of the yacht's name.
+>   - **Fix:** add a second `useQuery` keyed on `['yacht-detail-label', value]` that fetches `/api/v1/yachts/{value}?fields=name` when `value` is set AND not present in `rawOptions`. Use its result as the fallback label in priority order: `match?.name ?? fallbackQuery.data?.name ?? `Yacht ${value.slice(0, 8)}``. Cache hit on repeat opens; tiny request. (b) Also pre-select the currently-managed yacht as the default `value`for any picker rendered in a context where "the current yacht" makes sense — that's a parent-prop concern; this picker handles whatever`value` it's given. (c) Sweep for the same pattern in other pickers (ClientPicker, CompanyPicker, BerthPicker if they exist) — same root cause + same fix shape.
+>   - **Effort:** ~20 min per picker; ~1h with the sweep. Captured 2026-05-18 from UAT. **SHIPPED (YachtPicker) in 2bcf544:** fallback `useQuery(['yacht-detail-label', value])` against `/api/v1/yachts/{value}` enabled only when value isn't in `rawOptions`. ClientPicker/CompanyPicker sweep deferred until UAT confirms the same pattern needs fixing there.
+> - **CommandList (cmdk) inside a Popover: scroll caps short of the bottom — applies to ALL dropdowns using the Command primitive** — _src/components/ui/command.tsx:57-75_ — `CommandList` has `max-h-[300px] overflow-y-auto overscroll-contain` plus a custom wheel handler (lines 68-72) that re-implements scrolling because "native wheel scrolling is intercepted by the focus-scope and never reaches the cmdk list" (per the inline comment). User reports they can scroll a short distance, then the list stops responding before reaching the bottom — and notes this is the case for **every dropdown on the drawer they're looking at**, so it's the shared primitive, not a per-picker bug. **SHIPPED in e33313b:** `max-h-[300px]` now `max-h-[min(300px,var(--radix-popover-content-available-height,300px))]` so the cmdk list never extends past the host Popover's available area. Non-Popover hosts fall through to the 300px static cap. The list now consistently reaches the bottom of the visible popover regardless of where the trigger sits in the viewport.
+>   - **Suspected causes (likely a combination):**
+>     - **(i) cmdk auto-scroll-to-highlighted-item** fights the manual scroll: when the user wheels past the currently-highlighted item, cmdk's internal handler snaps the scroll back so the highlighted item stays visible. Net effect: user can scroll up to a few items past the highlight, then it bounces back. **Fix attempt:** on wheel/scroll, clear the cmdk highlight (or set it to a non-highlighted state) so cmdk doesn't re-snap. cmdk exposes a `value` prop on `Command` for controlled-highlight; set it to `undefined` on scroll, restore on hover/keyboard nav.
+>     - **(ii) Manual wheel handler ignores trackpad-momentum + keyboard:** `event.currentTarget.scrollTop += event.deltaY` only handles wheel events. Trackpad-flick momentum continues firing wheel events with diminishing `deltaY`, but if cmdk traps the events the user's input bounces. Touch / keyboard arrow keys may have similar interception issues. **Fix attempt:** prefer letting cmdk handle scroll natively (newer cmdk versions fixed the popover-focus-scope issue) and remove the manual handler. Check `package.json` for `cmdk` version; if < 1.0.0, upgrade.
+>     - **(iii) The `max-h-[300px]` hard cap** clips longer lists. While the cap exists, scrolling SHOULD still reach the end — but combined with (i)/(ii) it caps the effective scroll distance. **Fix attempt:** use a height-aware token: `max-h-[min(400px,var(--radix-popper-available-height,400px))]` so the list grows when the popover has room and caps at 400px otherwise.
+>   - **Investigation order:** (1) check cmdk version + upgrade if old → may auto-fix the focus-scope issue and let us remove the manual wheel handler. (2) Test with manual handler removed. (3) If still buggy, add the controlled-highlight reset on scroll. (4) Bump the max-h as the easy win.
+>   - **Effort:** ~30-60 min including upgrade + testing across the YachtPicker, ClientPicker, CompanyPicker, command-search topbar, and any other Command consumers. Captured 2026-05-18 from UAT — affects every Command-based dropdown app-wide; high-leverage single-component fix.
+> - **DECIDED 2026-05-21 (do not adopt Documenso embed editor):** evaluated `@documenso/embed-react`'s `EmbedCreateEnvelope` / `EmbedUpdateEnvelope` as a replacement for our custom field-placement UI. Per Documenso V2 editor docs (callout block): _"Embedded editor is included with Enterprise plans. It is also available as a paid add-on for the Platform Plan. Contact sales for access."_ Enterprise licensing is a hard no for us. Custom rebuild is the path. We're already ~70% there with `upload-for-signing-dialog.tsx`; remaining scope is the 4-item bundle below (~12-16h total). Full V2-editor parity (multi-file envelopes, Assistant/Viewer roles, dictate-next-signer, all envelope settings) would be ~30-40h but is not justified by our actual marina-CRM flows. Skip multi-file/assistant role; defer per-document envelope settings (expiration / redirect / custom reply-to) until a rep actually asks for them.
+> - **Smart search: fuzzy-match pipeline stage names, surface inline mini-list of interests at that stage** — _src/components/search/command-search.tsx_ + _src/lib/services/search.service.ts_ + _src/lib/constants.ts:31 (`STAGE_LABELS`)_ + _src/hooks/use-search.ts_. Today's command-K search includes each interest's stage in result rows (rendered via `STAGE_LABELS`) but doesn't search BY stage — typing "Reservation" only matches interests with that text in their fields. User wants: type "reservation" → see a dedicated "STAGE: Reservation (N deals)" section at the top of the dropdown listing the top 5-10 interests at that stage, with each row showing client + berth label so the rep can click directly. Bottom of section: "View all N in Reservation →" link to the filtered interests list.
+>   - **Design (locked 2026-05-21):** inline mini-list in the search dropdown (Option A from the design clarification). Top 5-10 interests per matched stage; "View all" link jumps to `/interests?stage=<canonical>`.
+>   - **Backend:** new search section `'stage-matches'` returning `{ stage: PipelineStage, label: string, totalCount: number, sampleInterests: Array<{id, clientName, berthLabel, ...}> }[]`. Fuzzy match the query against `STAGE_LABELS` values + common aliases ("res" → reservation, "eoi" → eoi_signed/eoi_sent, "dep" → deposit_paid, "qual" → qualified, "won"/"contract" → contract_signed, etc.). Use `fuse.js` or a tiny custom ranker on the labels — there are only ~9 stages so even O(n) scan is fine.
+>   - **Frontend:** new section in the command-search dropdown rendered above the text-match "Interests" section. Borrow the existing `SectionHeading` + result-row idioms. Use the existing `berthLabel` helper (the same one used in the DocumentDetail Interest link fix and the external-EOI title default) so naming is consistent across surfaces.
+>   - **Alias catalog (lives next to `STAGE_LABELS`):** add a small `STAGE_SEARCH_ALIASES: Record<PipelineStage, string[]>` map for non-obvious matches ("hot lead" → qualified? probably not, leave it conservative). Aliases stay short and unambiguous — prefer false negatives over false positives.
+>   - **Effort:** ~2-3h end-to-end (backend section + fuzzy ranker + frontend render + alias catalog + a vitest covering "res" matching reservation but not "reservation_signed" if that's a thing). Captured 2026-05-21 from UAT.
+>   - **SHIPPED in d912f02:** new `searchStages(portId, query, limit)` in search.service.ts. Three match flavours (case-insensitive): (1) modern label token-prefix on `STAGE_LABELS`, (2) substring on the raw enum slug, (3) legacy-alias prefix via `LEGACY_STAGE_REMAP` so "eoi_sent" / "deposit_10pct" / "contract_signed" still land on the modern 7-stage equivalent. Each result carries a live `COUNT(*)` of non-archived interests in that stage (single grouped query). New `StageSuggestionResult` bucket added to `SearchResults` + `BucketType` union; gated on `interests.view`. Command-search dropdown renders matched rows under a "Stages" header pointing at `/interests?pipelineStage=<stage>`. Mobile overlay reuses `buildFlatRows` so the same surface appears on mobile. Sample-interests-per-stage variant from the original design was deferred — the count + filter-link does the same job with one click vs. inline preview.
+> - **SHIPPED in 94c24a1 (F29):** Unified create-document wizard gets a Watchers section with multi-select checkbox list backed by `/api/v1/admin/users/picker`. Selected user ids sent in `watchers` array on POST (replaces prior hardcoded `[]`). UI matches post-creation WatchersCard so reps see same identity rows regardless of entry point. Watchers configurable at document creation time (currently post-creation only) — _src/components/documents/eoi-generate-dialog.tsx_, _src/components/documents/upload-for-signing-dialog.tsx_, _src/components/interests/external-eoi-upload-dialog.tsx_, _src/components/documents/create-document-wizard.tsx:157_ (hardcoded `watchers: []`), _src/lib/services/documents.service.ts (create paths)_, _src/lib/services/document-watchers.service.ts_ (or wherever the watcher CRUD lives). Today watchers can only be added AFTER creation via WatchersCard on the document detail. Reps usually know upfront who needs visibility (manager, developer, legal) and shouldn't have to navigate to the doc after creating it.
+>   - **Server-side defaults (fires on every create path):**
+>     - **Creating user** — always auto-added. The person who just created the doc almost certainly wants notifications about events on it.
+>     - **Interest's `assignedTo`** — if different from creator, auto-add. The deal owner gets visibility on doc events even if a different rep generated/uploaded.
+>     - **Per-port admin setting `default_document_watcher_user_ids: string[]`** — admin configures org-wide watchers (sales manager, legal, etc.). Apply on every create. Configurable in `/admin/settings` under a new "Document defaults" section.
+>   - **UI in each creation dialog:** small "Watchers" section (collapsed by default — "X watchers · Edit"), opens to show:
+>     - Each auto-added user with an `(auto)` badge so the rep can see who's already included without redundant clicks.
+>     - A user-picker to add additional watchers from the port's user roster.
+>     - An "X" to remove an auto-added watcher for this specific doc (e.g. rep wants this confidential, removes the default sales-manager). Doesn't affect the global default.
+>   - **Apply to ALL creation dialogs uniformly:** Documenso EOI generate, external EOI upload, Documenso upload-for-signing (reservation/contract), generic create-document wizard. Build the section as a shared `<DocumentWatchersField>` primitive so each dialog mounts it the same way.
+>   - **Service:** extend the document-create endpoints to accept `watcherUserIds: string[]` (replacing the current `[]` hardcode). On create, server: (i) inserts the explicit user IDs from the request, (ii) inserts the per-port default IDs, (iii) inserts creator + assignedTo if not already in the union. Dedupe by user_id + document_id (existing unique index, presumably).
+>   - **Effort:** ~3-4h end-to-end (admin setting + UI section + 4 dialog wirings + service-side defaults + tests). Captured 2026-05-21 from UAT. **Cross-ref:** ties into the external-EOI bundle below — the watchers section sits naturally next to the signatories editor in the same dialog. Build them in one pass.
+> - **External-EOI upload: per-signatory role tagging + email auto-fill + "Email copy" distribution** — _src/components/interests/external-eoi-upload-dialog.tsx_ (current free-text `signerNames` field; needs structured rows) + _src/components/documents/document-detail.tsx:208-214 + 297-299_ (current "Email signatories" placeholder stub) + _src/lib/services/system-settings/_ (new `default_developer_email` + `default_developer_name` per port) + _new_ `src/components/documents/email-copy-dialog.tsx` + _src/lib/services/document-sends.service.ts_ (already exists per CLAUDE.md, extend for the new dispatch path). Three linked feature gaps surfaced during UAT 2026-05-21 on the external-EOI flow:
+>   - **(a) Per-signatory role tagging at upload time** — today's dialog has a free-text "Signer names" CSV input only. No structured concept of WHO each person is (Client vs. Developer vs. Rep vs. Witness vs. CC), so the system can't auto-fill emails downstream or build a proper recipient list for the email-copy flow. **Fix:** replace the freetext field with a recipient list editor (same idiom as the Documenso upload-for-signing-dialog's recipients step — name + email + role per row + add/remove buttons). Add a `signatories: Array<{ name, email, role }>` field to the service's input shape; persist on the document row (existing `documents.metadata` JSONB or a dedicated `document_signatories` table — TBD by scope, JSONB is cheaper for v1). Role enum: `'client' | 'developer' | 'rep' | 'witness' | 'cc'`.
+>   - **(b) Smart email + name auto-fill based on role** — when a rep adds a row and selects a role, the dialog pre-populates name + email from the right source. Rep can still edit. Sources:
+>     - **Client** → `interests.clientId` → `clients.contacts` where `channel='email' AND isPrimary=true`, fallback to first email. Name from `clients.fullName`.
+>     - **Developer** → new per-port system settings `default_developer_name` + `default_developer_email` (admin-editable in `/admin/email` or a new "Default signatories" section). Surfaces consistently across EOI / Reservation / Contract upload flows.
+>     - **Rep** → `interests.assignedTo` → `users.email` + `users.fullName`.
+>     - **Witness / CC** → no auto-fill, manual entry. Rep optionally types or picks from a contacts autocomplete.
+>     - **UI:** when role is selected and a row's email/name is empty, fire `setValue` with the resolved default. If the resolved data is missing (e.g. no clientId on the interest, no developer configured), show a small "No default available — enter manually" hint inline.
+>   - **(c) "Email signatories" → "Email copy" with multi-select + actual send** — _document-detail.tsx:208-214_ — current button is a placeholder. Build the real flow:
+>     - **Rename** "Email signatories" → "Email copy" (clearer intent: "send a copy of the signed document").
+>     - **Dialog UX:** click opens a dialog listing every signatory on the document (from (a)'s structured list) as a checklist. **All checked by default.** Optional "Add other recipient" row at the bottom for emailing someone not on the original signing list (lawyer, accountant, etc.). Optional message field (plain text, like the existing send-out compose UI).
+>     - **Send pipeline:** uses the existing sales send-out infrastructure (per CLAUDE.md "Send-from accounts" section): nodemailer transport with per-port `default_developer_email` → no wait, that's the sales send-from. Send-from is the configured `sales_send_from` mailbox. Body is rendered via `renderEmailBody()` (per CLAUDE.md "Audit → document_sends" section). Each send creates a `document_sends` row keyed to the document + recipient, supporting bounce tracking + reply monitoring.
+>     - **Attachment:** PDF threshold check (per the existing `email_attach_threshold_mb` setting) — under threshold → attached inline; over → 24h signed-URL link (escapes filename per the existing XSS protection).
+>     - **Audit trail:** each recipient gets a `document_sends` row. Existing "Recent sends" / activity surfaces light up automatically.
+>     - **Rate limit:** existing 50-sends-per-user-per-hour cap applies.
+>   - **(d-prereq) Create `document_signers` rows on external upload so "X / Y signed" badge works** — _src/components/documents/document-detail.tsx:278_ reads `signers.filter(s => s.status === 'signed').length / signers.length` from the `DetailSigner[]` array. For manually-uploaded external EOIs the array is empty (the upload writes only freetext `signerNames` metadata) → badge renders `0 / 0 signed` even with 3 signers entered in the dialog. Fix is downstream of (a): when migrating from freetext to the structured `signatories: Array<{name, email, role}>` shape, the service should also insert `document_signers` rows (one per signatory), all pre-stamped `status='signed'`, `signedAt=input.signedAt`, `signingOrder=index+1`, `invitedAt=null` (no invitation was sent — this is a backfill of an external signing event). Counter then renders `3/3 signed` correctly. ~15 min on top of (a)'s service work. Captured 2026-05-21 from UAT.
+>   - **(d) Default document title should reference client + berth(s), not just date** — _external-eoi-upload-dialog.tsx:103_ (current placeholder `'External EOI - <date>'`) — when the rep accepts the default, the document lands as `External EOI — 2026-05-21`, which is unscannable in any document list when a port has multiple deals closing on the same day. **Fix:** derive the default at dialog open time using the same `formatBerthRange()` helper that powers the locked folder-naming convention (Bucket 4 #5). Format: `External EOI — <Client name> — <berth range> — <YYYY-MM-DD>` (e.g. `External EOI — Matthew Ciaccio — A1-A3, B5-B7 — 2026-05-21`). When no client or berths are linked, gracefully fall back to the current minimal form. Apply the same idiom to the Reservation + Contract external-upload dialogs for consistency. ~15 min.
+>   - **Effort:** ~5-7h end-to-end. ~1.5h for (a) — structured recipient editor + service shape change + migration if a dedicated table is preferred. ~1h for (b) — auto-fill resolver + admin setting for developer defaults + UI wiring. ~3-4h for (c) — dialog + send service + branded email template + audit + attachment-vs-link logic. ~15min for (d). Captured 2026-05-21 from UAT. **Cross-ref:** the broader UploadForSigningDialog rework (item below) needs the same role-tagging UI — build the recipient-list editor once and reuse on both dialogs. The default-title derivation in (d) also belongs as a shared helper since Reservation/Contract uploads should match.
+>   - **SHIPPED (a) + (d-prereq) in 301375a:**
+>     - (a) Structured `signatories: Array<{name, email, role}>` lands on the service input, the API multipart payload, and the dialog UI. Role enum: `client/developer/rep/witness/cc`. Auto-seeds the client row from `interestData.clientName + clientPrimaryEmail` via a signatoriesOverride/null pattern (React-Compiler safe).
+>     - (d-prereq) `document_signers` rows inserted inside the transaction for every non-CC signatory, pre-stamped `status='signed'`, `signedAt=input.signedAt`. The document-detail "X / Y signed" badge now renders the right count.
+>     - **Remaining (b) + (c) + (d) deferred:** developer-default settings, "Email copy" multi-recipient dialog, send pipeline + branded template, role-based email auto-fill beyond the client row — bundles with the broader Documenso send-flow work in Wave 4.
+> - **SHIPPED (3 of 4 sub-tasks) in 65ff596 (L41):** Dialog width was fixed earlier. Draft persistence: localStorage scoped per interest+documentType (`pn-crm.upload-for-signing.draft.v1:<id>:<type>`), 500ms debounce, PDF blob excluded (rep re-picks on reopen), "Draft saved" + Discard button surface, clears on submit. PDF preview error handling + zoom: onLoadError replaces spinner with failure block; toolbar gains 50–200% zoom in 25% steps (field coords stay in % of page dimensions). Field-placement keyboard shortcuts: Delete/Backspace removes selected field, arrow keys nudge 0.5% (Shift = 5%), ignored when focus is in real input/textarea/contenteditable. **UploadForSigningDialog comprehensive rework — 4 linked issues** — _src/components/documents/upload-for-signing-dialog.tsx_ — surfaced together during UAT 2026-05-21 of the Reservation Agreement send flow. All four touch the same dialog and should ship as one coherent pass.
+>   - **(a) [bug] "Failed to load PDF file" on the place-fields step** — the place-fields step uses `URL.createObjectURL(file)` (line 265) as `fileUrl` and passes it to react-pdf inside `FieldPlacementStep`. `pdf-viewer.tsx:149` `onLoadError` fires when react-pdf can't parse the blob. Likely causes to check: (i) the uploaded file isn't a PDF (PNG, DOCX, etc. — select-file step likely doesn't enforce `application/pdf` mime check); (ii) PDF.js worker URL misconfigured (every PDF fails the same way); (iii) blob revoked too early (`useEffect` cleanup at line 266-270 — though the deps look right); (iv) react-pdf version-incompatible with the worker bundle. **First debug step:** check browser devtools console for the actual error message — currently it's collapsed into a generic "Failed to load PDF file." string. Surface the underlying error to the UI ("Couldn't parse PDF — check that you uploaded a `.pdf` file, not an image or Word doc.") so the rep can self-diagnose.
+>   - **(b) [ux] Dialog way too small for the place-fields step** — dialog is `max-w-5xl` (1024px, line 166) which is fine for the recipients step, but the place-fields step has a 176px-wide field palette + 200px-wide recipients list on the left and only ~650px for the PDF preview on the right. A US Letter page at fit-width in 650px is barely legible, and field placement requires precision. **Fix:** make the dialog adaptive per-step: `max-w-3xl` for select-file + configure-recipients steps (768px is plenty for forms), but expand to `max-w-[1400px]` or `max-w-[95vw]` on the place-fields step where horizontal PDF space matters most. Alternative: full-screen modal pattern for the place-fields step only (escape exits, top bar shows step indicator + Back/Send). Also shrink the field palette from `w-44` (176px) to `w-32` (128px) by using icon-only buttons with tooltips — recovers ~50px of PDF width.
+>   - **(c) [feature gap] PlacedField shape missing `defaultValue` + `fieldMeta` (no UI to configure dropdown options, pre-fills, field labels, validation)** — _line 85-96, PlacedField interface_ — the current shape carries position + type + recipientIndex only. Documenso v2 `field/create-many` accepts per-field metadata that today's UI can't set:
+>     - **Dropdown:** options array. Today: rep places a Dropdown field → recipient sees an empty dropdown at signing time → blocked.
+>     - **Radio:** group label + option array. Same issue.
+>     - **Pre-filled defaults:** e.g., place a Name field assigned to "Matt Ciaccio" recipient + auto-populate with `interest.client.fullName` so the rep doesn't have to retype. Maps to Documenso's `defaultValue` per field.
+>     - **Text validation:** regex, minLength, maxLength — for fields like "passport number" or "phone".
+>     - **Field label:** custom label shown above the field at signing time (today defaults to the type name).
+>   - **Fix:** extend `PlacedField` with `defaultValue?: string`, `fieldMeta?: { options?: string[]; label?: string; required?: boolean; validation?: { regex?: string; minLength?: number; maxLength?: number } }`. Right-side properties panel on field selection (the selected-field UI already exists per the FieldPlacementStep code) gets new inputs per type:
+>     - Dropdown / Radio: textarea for "Options (one per line)".
+>     - Text / Name / Email / Number: input for "Default value" + optional "Pre-fill from" picker (Client name / Client email / Berth mooring / Interest date / …).
+>     - All types: "Required" checkbox + custom Label override.
+>   - The "Pre-fill from" picker is essentially a **per-field merge token** — borrowed from the EOI template merge-field catalog (`src/lib/templates/merge-fields.ts`). Reuse that token list + resolver so the same {{tokens}} that work in EOI templates work as field defaults here. Stitches the two flows conceptually: signer fields can be pre-filled from the same data sources EOI merge fields use.
+>   - **Backend wiring:** extend the v2 `field/create-many` payload in `documenso-client.ts` to pass `defaultValue` + `fieldMeta` (Documenso v2 supports these per their field API).
+>   - **(d) [behavior] Reservation flow should save as draft, not auto-distribute — match EOI pattern** — _line 361 + 477_ (the dialog reads `defaults?.data?.sendMode === 'auto'` system setting + changes the Send button label). User wants reservation agreement to ALWAYS save as Documenso draft so the rep can review in Documenso (preview email copy, double-check field placement, etc.) before manually triggering send. Per CLAUDE.md doc audit, EOI already uses this pattern (v2 `/template/use without distribute` → DRAFT envelope → rep distributes separately). Reservation should mirror.
+>   - **Fix:** option A (per-document choice, recommended) — add a small radio above the Send button in the dialog footer: `⦿ Save as draft (review in Documenso, send later) · ◯ Send immediately`. Default to "Save as draft" for reservation agreements (and contracts, by parity), since these high-stakes documents merit a review step. EOIs already follow the draft pattern; this just brings reservation/contract in line.
+>   - Option B (force manual) — hardcode `sendMode='manual'` for reservation / contract document types regardless of system setting. Less flexible but simpler.
+>   - **Lift the system `sendMode` setting to a per-document-type setting** so admins can independently configure auto-send for EOI / reservation / contract.
+>   - **Effort:** ~6-9h end-to-end for the full bundle (a + b + c + d + sweep of EoiGenerateDialog for parity on items b/c if applicable + tests). The dialog-width fix alone is ~30min; the rest of the work is the field-metadata schema + UI extension which is the heaviest piece. Captured 2026-05-21 from UAT.
+> - **Skip-ahead backfill flow: surface real backfill controls below the banner (date pickers + signed-doc upload per gap)** — _src/components/interests/skip-ahead-banner.tsx:71_ (banner copy says "Backfill ... below" but nothing renders below), _src/components/interests/interest-tabs.tsx_ (the MilestoneSection past-phase render), _src/lib/services/interests.service.ts_ (PATCH path for date*eoi_sent / date_eoi_signed / date_reservation_signed / date_deposit_received), \_src/components/interests/interest-documents-tab.tsx* (existing upload flow we can lift from) — when a rep manually jumps a deal forward (e.g. Qualified → Reservation via the stage dropdown), the SkipAheadBanner fires and tells them to backfill, but the milestone card immediately below shows checkmarks with no controls to actually (a) set the historical date or (b) upload the signed PDF as evidence. The current `MilestoneAdvanceButton` has the date popover affordance, but it's only rendered for the NEXT unchecked step — past-but-undated steps render as a static checkmark + "—" with no edit affordance.
+>   - **Fix:**
+>     - (a) When a milestone is in the past phase AND its date column is null, render an inline "Set date" button next to the checkmark that opens the same Popover used by `MilestoneAdvanceButton` (date input defaulting to today, accepts any past date). On confirm, PATCH the relevant `date_*` column. No stage transition fires — just a date stamp.
+>     - (b) When a milestone is in the past phase AND its doc-status is not `'signed'` (or there's no associated `files.id` for the signed PDF), render an "Upload signed PDF" button next to "Set date" that opens a file picker, posts to the existing storage path, and flips the matching `*DocStatus` column to `'signed'` (mirrors what the Documenso webhook does on completion). For EOI specifically, the upload should link to the `documents` row representing the EOI so the file lands in the Documents hub via the same auto-deposit flow.
+>     - (c) Banner copy: convert the gap names from passive text into clickable jump-targets that scroll-into-view the corresponding past milestone card (e.g. "EOI sent date · EOI signed date" become anchor links). Reduces the "where is 'below'?" friction.
+>   - **Effort:** ~3-4h. Captured 2026-05-21 from UAT. (Bundles findings #1, #2, #3 below into one coherent backfill UX.)
+>   - **SHIPPED (date backfill control) in d8da1f6:** new `<MilestoneBackfillButton>` lands in the past-milestones strip whenever a date column is null (eoi/reservation/deposit/contract). Opens a DatePicker popover and PATCHes the relevant date\_\* column without firing a stage transition. **Signed-PDF upload per gap + clickable banner-gap anchor links remain parked** for the larger Documents-hub bundle.
+> - **Current-stage milestone hidden under "Upcoming milestones" when its sub-steps are already checked off (active phase mislabelled)** — _src/components/interests/interest-tabs.tsx:611-624_ (`milestoneCompletion` map + `firstIncompleteKey` derivation) — the phase classifier marks a milestone as `'past'` whenever ALL its sub-steps are complete, so when the interest is at Reservation stage with reservation-agreement-signed already ticked (via the manual stage-jump), the Reservation milestone is `past` and EOI (which still has gaps because the rep hasn't backfilled) becomes the `firstIncompleteKey` → flagged as "NEXT STEP". Net effect (image 23): EOI shows as "NEXT STEP" + Reservation gets buried in the "Upcoming milestones" accordion even though it's the actual current stage.
+>   - **Fix:** introduce a third concept besides `past | current | future` — the milestone that owns the CURRENT pipeline stage (regardless of completion) should always be `current` and never be collapsed into the past-strip nor the upcoming-accordion. Compute the rep's "true current" milestone by mapping `interest.pipelineStage` → milestone key (eoi/eoi_sent/eoi_signed → 'eoi'; reservation → 'reservation'; deposit_paid → 'deposit'; contract_sent/contract_signed → 'contract'). The `firstIncompleteKey` rule still works for nurturing / qualified stages where no milestone naturally owns the stage. Past-but-fully-done milestones BEFORE the current stage go in the past-strip; future milestones go in the upcoming-accordion. Pair with the backfill-controls fix above so a "current" milestone with missing dates still has the affordances to fill them.
+>   - **Effort:** ~30-45 min. Captured 2026-05-21 from UAT.
+>   - **SHIPPED in d8da1f6:** introduced a `STAGE_TO_MILESTONE` map. When a stage owns a milestone (eoi/reservation/deposit_paid/contract), that milestone is forced to `'current'` regardless of sub-status completion; earlier-than-stage milestones bucket to `'past'` (so backfill controls render); later slots stay `'future'`. The legacy firstIncompleteKey rule still applies in stages without an owning milestone (enquiry/qualified/nurturing).
+> - **Qualification auto-confirm "intent confirmed" once stage ≥ EOI (extend `computeAutoSatisfied`)** — _src/lib/services/qualification.service.ts:342-360_ (`computeAutoSatisfied` only branches on `'dimensions'` — `'intent_confirmed'` falls through to `false`) + the call-site context build at lines 296-316 (needs `pipelineStage` added) — when a rep manually advances the deal past Qualified to EOI/Reservation/Deposit/Contract, "Intent confirmed" still requires an explicit tick. The act of signing an EOI is itself the strongest signal of intent — leaving the row unchecked makes the checklist feel like noise. Extend the auto-satisfaction context with `pipelineStage`, add an `if (key === 'intent_confirmed') return stageIdx > qualifiedIdx;` branch, and `computeEvidence` returns "Stage advanced past Qualified" when triggered. Rep can still untick to overrule. **SHIPPED in 51ca875.**
+>   - **Effort:** ~30 min including the evidence string + an integration test. Captured 2026-05-21 from UAT.
+> - **Qualification: stale explicit-tick survives removal of underlying auto-evidence (esp. dimensions)** — _src/lib/services/qualification.service.ts:296-334_ (`confirmed: explicit || autoSatisfied`) — `autoSatisfied` is recomputed at fetch time, but `explicit` persists in `interestQualifications.confirmed` once a rep has manually ticked the row. Result: if dims were present at one point, the rep clicked the box (or the auto-tick happened alongside an explicit click somewhere in the flow), then dims are later removed, the row STAYS ticked because `explicit=true` covers for `autoSatisfied=false`. The `AUTO` badge disappears so it now looks like a manual confirmation — but the rep may have no memory of making it. Footgun: checklist claims "Dimensions confirmed" with no underlying data.
+>   - **Fix (recommended — strict for derived-only criteria):** for keys where there's no rep judgement involved (`dimensions` today; future similar "does X data exist" checks), make the row purely derived — ignore `explicit`, return `confirmed: autoSatisfied`. Removing dims always unticks. Keep `explicit || autoSatisfied` for judgement-based keys like `intent_confirmed`. Implement by marking each criterion with a `derivedOnly: boolean` flag (lives next to the auto-rule) and branching in the merge.
+>   - **Alt (lenient with warning):** keep the OR but surface an `inconsistent` flag (`explicit && !autoSatisfied`) — UI renders the row with an amber "Evidence missing — re-verify" annotation, lets the rep re-confirm or untick.
+>   - **Effort:** ~45 min for strict (incl. integration test covering the remove-dims-after-tick flow); ~1h for lenient (annotation + amber styling). Captured 2026-05-21 from UAT. **SHIPPED (strict variant) in 51ca875:** `DERIVED_ONLY_KEYS` Set sentinel; merge branches on `isDerivedOnly(key)` to ignore explicit ticks for `dimensions`.
+> - **Qualification checklist: collapse to one-line summary once "All confirmed"** — _src/components/interests/qualification-checklist.tsx_ — once every row is confirmed (explicit + auto combined), the full card stops being a gate and just occupies prime Overview real estate. Replace the expanded card with a single-row summary: `✓ Qualification — all confirmed (dimensions · intent)` + a chevron to expand on demand. Audit trail stays one click away. While expanded the rep can still untick or add notes; on next page load the card re-collapses if fully confirmed. Pairs naturally with the auto-confirm-on-stage-advance change above — deals at Reservation+ stage land with a collapsed Qualification block instead of a full card. Don't redesign the checklist content per stage (cognitive load); just change the visual weight once it's no longer informationally hot.
+>   - **Effort:** ~30 min. Captured 2026-05-21 from UAT. **SHIPPED in 51ca875:** card header is now a button-style toggle; aria-expanded; when fully confirmed it collapses to "✓ All confirmed (label · label)" + chevron; rep clicks header to inspect/untick.
+> - **Yacht Ownership History tab: flesh out the controls; don't remove (carries real semantic load)** — _src/components/yachts/yacht-ownership-history.tsx_ + _src/components/yachts/yacht-tabs.tsx:333_ + _src/components/yachts/yacht-form.tsx:337-345_ (existing Transfer affordance) + _src/lib/services/yachts.service.ts:215_ (`transferOwnership` service) + _src/lib/db/schema/yachts.ts:72-96_ (`yachtOwnershipHistory` table with partial unique index `(yacht_id) WHERE end_date IS NULL`).
+>   - **Why keep:** the table isn't decorative — (i) partial unique index enforces one active owner at a time; (ii) berth reservation logic (`berth-reservations.service.ts`) gates "active company_membership on the owning company", so the yacht's ownership chain materially affects berth standing; (iii) the data is **already auto-populated** by `createYacht`, `transferOwnership`, and `public-interest.service.ts` — no rep effort required to maintain; (iv) audit trail value for disputed deals, EOIs generated under prior ownership, etc. Removing the tab AND/OR the table would lose audit fidelity and force reservation logic to derive ownership some other way. The "no way to enter/change" perception is a UI gap, not a missing concept.
+>   - **Flesh-out scope (recommended):**
+>     - (a) **Surface the existing Transfer flow on this tab** — the yacht form has a Transfer button (comment at line 345 confirms); add the same button to the Ownership History tab header (e.g. `"Transfer ownership →"`). Permission-gated by whatever the existing Transfer flow uses.
+>     - (b) **Empty-state CTA** — current empty state reads `"No ownership history"`. Replace with copy + a Transfer button so the tab is actionable on first visit, not dead-end.
+>     - (c) **Backfill / "Add historical entry"** — admin-only button that opens a small form (owner type/id, start date, end date, reason, notes) and inserts a row directly. Useful for backfilling pre-CRM ownership history for yachts brought over from NocoDB or legacy records. Permission: `yachts.edit_history` (new perm).
+>     - (d) **Edit controls on existing rows** — admin-only edit for `transferReason`, `transferNotes`, and `startDate`/`endDate` (with a strong confirm + audit log entry — these dates feed downstream logic). Don't allow editing `ownerType`/`ownerId` post-insert (use a Transfer/correction flow instead).
+>     - (e) **Link each row to the involved entity** — each row's `ownerType: 'client' | 'company'` + `ownerId` should render as a click-through link to the entity detail page. Right now likely a raw ID or just a label.
+>     - (f) **"Why was this entered?" trailing note on each row** — pull from `transferReason` (already in schema) + display `createdBy` (link to user) and `createdAt` (relative time). Tells the rep both what happened and who recorded it.
+>   - **Out-of-scope alternative:** if leadership concludes the audit value doesn't justify the UI cost, hide the tab from the rep-facing UI but **keep the table** + auto-populate hooks + admin-only access via `/admin/yachts/[id]/ownership-history` for the dispute case. Tab disappears from yacht detail; reservation logic continues to work. **User noted (2026-05-18):** if the tab is removed, the Transfer modal would also need to be removed — confirming that removing the tab is a coupled change with broader UI impact. Reinforces the recommendation to keep + flesh-out rather than remove.
+>   - **Recommendation:** ship (a) + (b) + (e) as the minimum-viable polish (~1.5h) — makes the tab feel intentional. (c) + (d) become admin-side work when there's actual demand for backfill or historical correction (~3-4h). Skip the "hide it" path unless explicit leadership ask.
+>   - **Effort:** ~1.5h for the minimum polish, ~5h for the full flesh-out. Captured 2026-05-18 from UAT (user weighed in towards "remove altogether"; the queue entry argues against because of the reservation-logic coupling + auto-population — final call still with the user). **SHIPPED (a) + (b) + (e) in 552b966:** "Transfer ownership" button on the tab header (perm-gated by `yachts.edit`); EmptyState action wired through to the dialog; existing OwnerLink rendering verified as link-through (e). Backfill / edit-controls (c)+(d)+(f) parked.
+> - **Yacht Overview: replace single-textarea notes with the threaded `<NotesList>` (parity with clients / interests)** — _src/components/yachts/yacht-tabs.tsx:227-236_ (the legacy single-text-field at the bottom of OverviewTab) + _src/components/yachts/yacht-tabs.tsx:351_ (the full `<NotesList entityType="yachts" />` already rendered in the dedicated Notes tab) + _src/components/shared/notes-list.tsx_ — Overview today shows `<InlineEditableField variant="textarea" value={yacht.notes} ... />` — a single `yachts.notes` string column, last-edit-wins. The dedicated Notes tab has the full threaded `<NotesList>` (one entry per note, author + timestamp + edit/delete + aggregate). Clients and interests already surface threaded notes without leaving Overview.
+>   - **Fix:** replace the OverviewTab notes block (lines 227-236) with `<NotesList entityType="yachts" entityId={yachtId} currentUserId={currentUserId} />`. The `yachtNotes` table already exists (per CLAUDE.md polymorphic notes architecture: `notes.service.ts` dispatches across `clientNotes`/`interestNotes`/`yachtNotes`/`companyNotes`) so no backend work.
+>   - **Legacy `yachts.notes` column:** verify (a) anything else writes it (other than this textarea); (b) anything reads it (EOI / contract / template merge fields). If unused elsewhere, deprecate the column and stop surfacing it on Overview; the threaded NotesList becomes the canonical write path. If still in use, leave the column but stop surfacing on Overview.
+>   - **Companion decision:** with NotesList on Overview, the dedicated Notes tab may become redundant — same tradeoff applies to clients/interests today. Defer that decision; ship the inline NotesList first.
+>   - **Effort:** ~30 min for the swap + verify `currentUserId` is plumbed through to OverviewTab. Captured 2026-05-18 from UAT. **SHIPPED in c6dcf49:** OverviewTab now renders `<NotesList entityType="yachts" parentInvalidateKey={['yachts', yachtId]}>`; `currentUserId` plumbed through. Legacy `yacht.notes` column retained for EOI/contract merge-field path; decision on the dedicated Notes tab deferred.
+> - **`/invoices/upload-receipts` guide: copy rewrite — terse, professional, in the luxury-CRM voice** — _src/components/invoices/upload-receipts-guide.tsx_ (the whole page; ~190 lines, ~75% of which is body copy) — current copy reads like a friendly onboarding tutorial: hand-holding ("Snap a photo of the receipt with your phone"), explanatory tangents ("The behind-the-scenes part is called OCR..."), throwaway pleasantries ("Most of the time everything is correct", "No typing. No spreadsheets. No chasing finance for the form."), and parenthetical asides ("the square with the arrow pointing up"). Tone is out of step with the rest of the CRM — the platform's brand voice is precise, restrained, declarative; this page reads warm-blog. Rewrite passes:
+>   - **PageHeader description** (line 31) — currently `"When you spend your own money on a business expense for the marina, use this to log it. Snap a photo of the receipt with your phone, the system reads it for you, and finance approves it on the parent company's side."` → suggested: `"Capture out-of-pocket expenses for reimbursement. The system extracts vendor, date, total, and currency from each receipt and routes the claim to finance."`
+>   - **"What does it actually do?" section** (lines 51-65) — replace title with `"Overview"`. Replace the two paragraphs with one line: `"Submit a photographed receipt; the system populates the expense form via OCR with AI-assisted field extraction, then forwards the claim for parent-company approval."` Drop the OCR explanation entirely — the audience is internal staff, not customers.
+>   - **Step 1 ("Add the scanner to your phone")** — retitle `"Install the scanner"`. Description → `"One-time setup. The scanner launches from the home screen thereafter."` Per-platform steps: drop parentheticals ("the square with the arrow pointing up"), drop the "Confirm the name 'Scanner'..." cruft, drop the trailing "Done." block in `PlatformBlock`.
+>   - **Step 2 ("Snap a photo of a receipt")** — retitle `"Capture a receipt"`. Description → `"Open the scanner from the home screen."` Each list item to one short sentence: `"Tap the camera tile and frame the receipt."` / `"The system extracts vendor, date, total, and currency."` / `"Review the populated fields; tap to amend."` / `"Tap Save to submit for approval."`
+>   - **"Tips for the best results"** — retitle `"Tips"`. Drop conversational asides; cap to 3-4 bullets, each one sentence.
+>   - **Target length:** ~60-70% reduction. Reads in 30 seconds instead of 3 minutes; the rep gets the workflow, not a friendly essay.
+>   - **Companion audit:** flag for review across other guide / help / empty-state copy that may have drifted into the same warm-blog voice (consumers of `src/components/shared/empty-state.tsx`, any `*-guide.tsx` pages, onboarding flows, longer Toast copy). One pass for tone consistency platform-wide — captured as a deferred follow-up; this page is the most visible offender.
+>   - **Effort:** ~45 min for this page; ~3-4h for the platform-wide tone audit if pursued. Captured 2026-05-18 from UAT.
+>   - **SHIPPED in e33313b:** page rewritten to terse luxury-CRM voice. PageHeader description, "What it does" section, Step 1 ("Install the scanner"), Step 2 ("Capture a receipt"), best-practices list, and PlatformBlock trailing line all tightened. Dropped the OCR mini-essay, "fancy phone camera" / "No typing. No spreadsheets" pleasantries, and parenthetical asides. ~50% size reduction in body copy. Platform-wide tone audit still parked.
+> - **Expenses page header copy: drop "port" from the description** — _src/app/(dashboard)/[portSlug]/expenses/page.tsx:33_ → PageHeader at _src/components/shared/page-header.tsx:38_ — description currently reads `"Track and manage port expenses"`; user wants the word `"port"` removed. Suggested copy: `"Track and manage expenses."` (or, if the team wants to keep the "manage" verb spelled out, `"Track and manage business expenses."`). Trivially small. ~30 sec. Captured 2026-05-18 from UAT — likely indicative of a broader "remove the word 'port' from user-facing copy where it's redundant" pass; the portSlug already scopes everything, so user-facing strings shouldn't restate it. Worth a quick grep for `port expenses`, `port clients`, `port settings`, etc. in component strings. **SHIPPED in c6dcf49:** "port" dropped. Platform-wide grep sweep deferred to follow-up.
+> - **Topbar search: widen + center against the _viewport_ (including sidebar space), not the topbar's middle grid slot** — _src/components/layout/topbar.tsx:57_ (grid template) + _src/components/layout/topbar.tsx:77-84_ (search container) + _src/components/search/command-search.tsx:103_ (the input itself) + _src/app/globals.css:114_ (`--width-sidebar: 256px` token already available) — current behaviour: the topbar uses `grid grid-cols-[minmax(0,1fr)_minmax(360px,640px)_minmax(0,1fr)]` inside the AppShell's main area (right of the sidebar), so the search bar centers within _the topbar_ — visually it sits offset to the right of the screen by half the sidebar width because the topbar itself starts after the sidebar. User wants the search visually centered against the full viewport (sidebar inclusive) and wider.
+>   - **Two coordinated changes:**
+>     - **(a) Wider:** bump the search container's `max-w-md` (448px) at line 81 to `max-w-2xl` (672px) or `max-w-3xl` (768px), and bump the topbar grid's middle slot from `minmax(360px,640px)` to `minmax(420px,800px)`. Cap to whatever still leaves room for the left breadcrumbs + right action row on common laptop widths (1280px - 256px sidebar = 1024px main area minus padding). 672-720px is a comfortable upper bound.
+>     - **(b) Viewport-centered:** the surgical trick uses the existing CSS variable. Apply a `translate-x` on the search wrapper that shifts it left by half the sidebar width: `style={{ transform: 'translateX(calc(var(--width-sidebar) / -2))' }}` (or a Tailwind arbitrary class `-translate-x-[calc(var(--width-sidebar)/2)]`). With the sidebar at 256px, the search shifts 128px left, landing its centre at viewport-50%. Works because the topbar's grid + `mx-auto` already centers the search within the post-sidebar area; subtracting half the sidebar width re-centers against the full viewport.
+>   - **Edge cases to handle:**
+>     - **Sidebar collapsed (64px):** wire the transform to use the collapsed-aware width. Cleanest: expose a single `--current-sidebar-width` CSS variable on the sidebar root that flips between `var(--width-sidebar)` and `var(--width-sidebar-collapsed)` based on collapse state. Topbar's search wrapper reads `--current-sidebar-width` so the shift adjusts automatically with no React state plumbing. ~10 min to add the variable + ~5 min to wire the transform.
+>     - **Mobile (< sm):** the sidebar is hidden and the layout is different (`MobileLayoutProvider` with bottom-tabs); the transform should only apply on `sm:` and up. Use `sm:-translate-x-[calc(var(--current-sidebar-width)/2)]`.
+>     - **Left column doesn't get visually overlapped:** since the search shifts via transform (paint-only, doesn't affect layout flow), the breadcrumbs in the left grid slot retain their declared width — but the search will visually overlap them. Solution: reduce the breadcrumbs slot's effective width (e.g. `minmax(0,0.6fr)` instead of `1fr`) OR add `pointer-events: none` to the breadcrumbs when the search is focused. Easier: hide breadcrumbs on narrower laptop widths and rely on the back-chevron + page-h1 for context (also addresses the breadcrumb-wrap finding above).
+>   - **Effort:** ~30-45 min total — the `--current-sidebar-width` variable + the transform + the grid bump + verifying behaviour at collapsed/expanded/mobile. Captured 2026-05-18 from UAT. **SHIPPED in 8fcbe45:** grid middle slot bumped from `minmax(360,640)` → `minmax(420,800)`; search wrapper `max-w-md` → `max-w-2xl`; `sm:-translate-x-[calc(var(--width-sidebar)/2)]` centers against the full viewport. Collapsed-sidebar-aware `--current-sidebar-width` variable parked.
+> - **Pageviews chart: X-axis date ticks too cramped — drop the time component** — _src/components/website-analytics/pageviews-chart.tsx_ (recharts `XAxis`) — current bucket labels render in `YYYY-MM-DD HH:MM:SS` format from Umami's `x` field, which the chart's X-axis prints verbatim. On a 30-day range the labels overlap into an unreadable strip. Fix: pass a `tickFormatter` to `XAxis` that parses `row.x` and renders just the date portion (`MMM d` or `M/d`), keeping the timestamp available via Tooltip's full-precision render. ~10 min. Captured 2026-05-18 from UAT. **SHIPPED (formatter) earlier (already in place as "MM-DD"); thinning in e33313b:** added `interval="preserveStartEnd"` + `minTickGap={52}` to `XAxis` so multi-week ranges anchor first/last ticks and Recharts thins out the middle automatically instead of overlapping.
+> - **Pageviews chart: inline note explaining Pageviews vs Sessions** — _src/components/website-analytics/pageviews-chart.tsx_ + the Card's CardHeader subtitle slot — add a small `?` info popover (matching the pattern on the Pipeline Value tile) next to the chart title that explains: "Pageviews = total page hits including refreshes. Sessions = distinct visitor sessions (a single visitor browsing multiple pages = 1 session, many pageviews)." Helpful because the chart shows both series and the distinction is non-obvious. ~10 min. Captured 2026-05-18 from UAT.
+> - **Inbox page: swap section order — Reminders above Alerts** — _src/components/inbox/inbox-page-shell.tsx:84-111_ — current order is `Alerts` (line 84) then `Reminders` (line 99). User wants the order reversed so Reminders is the top section. Swap the two `<section>` blocks; ids (`inbox-section-alerts`, `inbox-section-reminders`), URL-hash deep-link logic, and the localStorage open-state keys all remain untouched (they're keyed on section id, not order). PageHeader copy "Alerts & Reminders" should also flip to "Reminders & Alerts" to mirror the new visual order. ~3 min. Captured 2026-05-18 from UAT. **SHIPPED in 203f543.**
+> - **Inbox → Reminders: move filter row inline with the "New Reminder" button (embedded mode)** — _src/components/reminders/reminder-list.tsx:298-315_ — in embedded mode (used by Inbox), the "New Reminder" button renders on its own line at line 298-311 (`<div className="mb-3 flex justify-end">`), and the filters row (My/All tabs + status filter + priority filter) renders separately below at line 315. The two should share one row: filters left, button right. Fix: merge the two into a single `<div className="mb-4 flex flex-wrap items-center gap-3 sm:gap-4">`, keep the filter controls in their current order at the start, and append the "New Reminder" button with `className="ml-auto"` (or wrap the filters in a container + put the button as a sibling and use `justify-between`). Non-embedded mode (PageHeader path at lines 282-297) is unaffected. ~10 min. Captured 2026-05-18 from UAT. **SHIPPED in 203f543.**
+> - **Breadcrumb wrap looks broken: orphaned separator + back-chevron misaligned** — _src/components/ui/breadcrumb.tsx:15-27_ + _src/components/layout/topbar.tsx:55-75_ — when the breadcrumb wraps (e.g. `Administration › Berths › Bulk Add` in the narrow left topbar slot), three visual issues stack: (1) trailing `›` separator after "Berths" hangs at the end of line 1 with nothing after it (orphaned, because separators are siblings of items in the `<ol>` so the flex-wrap break can land between an item and its separator); (2) "Bulk Add" wraps to line 2 indented; (3) the back-chevron `<` sits left of the wrapped line and is taller than the wrapped line, throwing off vertical alignment. Together it reads as a layout bug, not a wrap.
+>   - **Three coordinated fixes — ship (a) at minimum, do (b) for the real polish:**
+>     - **(a) Quick: make separator inline with the preceding item so wrap can't strand one** — restructure so each `<li>` contains both the label AND its trailing separator (single inline-flex unit), except the last crumb which has no separator. Drop the standalone `<BreadcrumbSeparator>` `<li>` from `Breadcrumbs` consumer. The primitive's `BreadcrumbSeparator` stays exported for backcompat. Wrap then breaks between full crumbs cleanly. ~15 min.
+>     - **(b) Better: ellipsis-collapse middle crumbs on overflow** — industry-standard pattern. When crumb count > 3 OR available width can't fit all crumbs single-line (detect via `ResizeObserver` on the `<nav>` or a CSS `:has(+ overflow)` trick), collapse middle crumbs to a `<BreadcrumbEllipsis>` button that opens a dropdown listing the hidden crumbs. First (root) + last (current page) always visible. Primitive already exports `BreadcrumbEllipsis` — just wire it. ~45 min. Result: breadcrumb stays single-line at every width, no wrap at all.
+>     - **(c) Layout polish: top-align the back-chevron** — _topbar.tsx:59_ — change the wrapping `<div className="min-w-0 flex items-center gap-1.5">` to `items-start` so even if the breadcrumb does wrap, the back-button stays top-aligned with the first crumb line instead of vertical-centering across the wrapped block. Also worth considering: hide the back-button when meaningful breadcrumbs are visible (the breadcrumb's parent link already does "go back"; two affordances is one too many). ~10 min.
+>   - **Topbar grid sizing observation:** topbar columns are `[minmax(0,1fr)_minmax(360px,640px)_minmax(0,1fr)]` — left slot competes for space with the centered search bar's `minmax(360px,640px)`. When search hits its max width, left slot is squeezed → breadcrumb wraps sooner. Consider bumping to `minmax(0,1.5fr)` OR letting the search shrink below 360px when needed. Optional, evaluate after (a)+(b) land.
+>   - **Effort:** ~15 min for (a), ~45 min for (b), ~10 min for (c). Bundle ~1h. Captured 2026-05-18 from UAT. **SHIPPED (a) in 8fcbe45:** each crumb + its trailing ChevronRight now share a single `<BreadcrumbItem>`; flex-wrap can no longer strand a separator. Ellipsis-collapse (b) + back-chevron alignment (c) parked.
+> - **BulkAddBerthsWizard: currency field should use `<CurrencySelect>` (already exists, used elsewhere)** — _src/components/admin/bulk-add-berths-wizard.tsx_ (the `priceCurrency` `<Input>` in the apply-to-all row at ~lines 282-290, and the per-row instance below it) — currently a free-text `<Input>` that uppercases on blur, defaulting to `USD`. Reps can type any string (including invalid codes); no auto-complete; no consistency with other forms. The `<CurrencySelect>` component already exists at _src/components/shared/currency-select.tsx_, backed by the curated `SUPPORTED_CURRENCIES` list in _src/lib/utils/currency.ts_, and is used by the single-berth edit form (_berth-form.tsx:414_) + the expense form dialog (_expense-form-dialog.tsx:238_). Quick fix: import `CurrencySelect`, replace both the apply-to-all and per-row currency inputs with the dropdown bound to the same handlers (`applyToAll('priceCurrency', v)` / `setRowField(idx, 'priceCurrency', v)`). ~10 min. Captured 2026-05-18 from UAT. **SHIPPED in 2bcf544.**
+> - **SHIPPED (wizard) in 431375d (D24):** Step 2 header gets a small monospaced ft/m button that flips dimension entry unit wizard-wide; cell values stay as-typed, single `inputToFt(v)` helper converts m→ft (3.28084) before posting canonical feet payload; column headers reflect active unit. **SHIPPED (Berth Requirements row on Interest) in 991e222 (C22):** interest-tabs Berth-requirements section honours `interest.desiredLengthUnit`; labels flip to "(m)" when set; on save PATCHes both chosen-unit and canonical counterpart so downstream surfaces (recommender, EOI merge fields) stay in lockstep. **SHIPPED (berth-list column display ft/m persisted to user prefs) in 991e222 (C21):** TablePreferences.dimensionUnit added to user-profiles JSONB; useTablePreferences returns dimensionUnit + setDimensionUnit; new getBerthColumns(unit) factory rewrites dimensions/nominalBoatSize/waterDepth cells (waterDepth converts on-the-fly from canonical meters at 3.2808 ft/m); toolbar gains ft/m toggle. Single-berth editor sweep still parked. BulkAddBerthsWizard + single-berth editor: toggleable input units (ft/m) for dimension fields — _src/components/admin/bulk-add-berths-wizard.tsx_ (the "Width (ft)" / "Length (ft)" / "Draft (ft)" inline-table headers + input parsing), _src/components/berths/berth-form.tsx_ (or equivalent single-edit) — the wizard's column headers and input parsing are hard-coded to feet. The schema supports per-dimension entry-unit discriminators (`lengthUnit`, `widthUnit`, `draftUnit` on `berths`, all defaulting to `'ft'`) plus separate `_M` numeric columns where metres-original values live — but neither the bulk wizard nor the single editor lets the rep pick which unit they're typing in. Reps who think in metres convert manually and the entry-unit discriminator never gets set.
+>   - **Fix:** (a) add a small `ft | m` toggle in the wizard header (and on the single-berth edit form) that flips the column header labels (e.g. "Width (ft)" → "Width (m)") and the parser. The toggle should default to whichever unit the user's `dimensionUnit` preference is set to (see the Dimensions-column-toggle finding earlier — same preference). (b) On submit, if entered unit is `'m'`, convert to ft for the stored numeric (`berths.lengthM` is the canonical metres column; `lengths.lengthFt` would be the feet column — verify the actual column names) AND set `lengthUnit='m'` so downstream document generation honours the rep's original input. Same for width / draft / nominalBoatSize / waterDepth. (c) Reuse the `src/lib/utils/dimensions.ts` helper from the Dimensions-column finding so conversion is centralized.
+>   - **Why this matters beyond UX:** document-generation merge fields (EOI / contract) already pull entry-unit values per `effectiveDimensionUnit` so the legal doc matches the rep's intent. Hard-coding ft on input silently coerces metric reps' values through a mental conversion, then renders the resulting ft figure on documents — losing fidelity for European customers.
+>   - **Effort:** ~1.5-2h end-to-end (wizard toggle + single-form toggle + parser + tests). Coordinate with the Dimensions-display toggle finding so both UI surfaces use the same preference key + helper. Captured 2026-05-18 from UAT.
+> - **SHIPPED in 431375d (D25):** Select-of-A–E replaced with a chip group (A-E quick-pick) + free-text "Other…" input for any uppercase letter sequence (AA, BB, F, …). handleGenerate validates against empty/non-uppercase with toast; custom-input path uppercases + strips non-letters as typed so canonical `^[A-Z]+\d+$` regex always matches. BulkAddBerthsWizard: allow defining new dock/pontoon letters in-flow (or surface the admin path) — _src/components/admin/bulk-add-berths-wizard.tsx:78_ + _the dock/area model_ — current wizard appears to assume the dock letter already exists (per CLAUDE.md the mooring format is `[A-Z]+\d+` like `A1`, `B12` — the letter prefix is a dock/pontoon identifier). When a rep is adding berths for a _new_ dock, there's no inline way to introduce the new letter; they have to abandon the wizard, create the dock elsewhere, then come back. Two possible models — confirm which one applies in this codebase before building:
+>   - **(a) Dock letters are free-form / inferred from `berths.mooring_number`** (no separate `docks` table): then the wizard just needs to allow a new letter prefix in its input. UI fix: replace the letter input (or dropdown) with a combobox-style "pick existing or type a new letter" control — same idiom as Tag picker. Backend: nothing — first insert with the new prefix establishes the dock. ~30 min.
+>   - **(b) Docks are a first-class entity** (separate `docks` table with `port_id` + `letter` + metadata like `position`, `pontoon_type`, `power_capacity`): then the wizard needs a "+ New dock" affordance opening a small dock-create dialog (letter + name + optional metadata), then returning to the wizard with the new dock pre-selected. Permission: `berths.manage_docks` (or whichever owns dock metadata). The user's question — "_or is this an admin setting?_" — suggests they're not sure either; if it IS an admin-only concern (docks are infrastructure not data the rep should touch), then keep it admin-side and just surface a contextual link in the wizard ("New dock? Add it in Admin → Docks first → [link]"). ~1-2h depending on the model.
+>   - **Action item:** check whether `docks` / `pontoons` / `marina_sections` table exists in the schema (`grep -r "docks\|pontoons" src/lib/db/schema/`); shape the fix accordingly. If no dedicated table, the wizard fix is trivial; if there is one, decide admin-only vs in-wizard-create with the team. Captured 2026-05-18 from UAT.
+> - **DropdownMenu content stretches to fill viewport — cap it** — _src/components/ui/dropdown-menu.tsx:66_ — the shadcn `DropdownMenuContent` primitive uses `max-h-(--radix-dropdown-menu-content-available-height)` (Radix's CSS variable that exposes the room between the trigger and the viewport edge). On long lists the menu visually stretches all the way to the viewport bottom even though the items don't need that height; reads as a wall of options. Internal `overflow-y-auto` is already on so scrolling works. Fix: replace the Radix `max-h-(...)` token with a fixed `max-h-96` (384px) or `max-h-[28rem]` (448px) so the menu caps at a comfortable height regardless of available space, scrolling internally for longer lists. Global change in the base primitive — affects every dropdown in the app, which is the right call (no consumer currently relies on the "fill the viewport" behaviour). ~2 min. If a specific dropdown needs the old behaviour, it can pass `className="max-h-[var(--radix-dropdown-menu-content-available-height)]"` to opt back in. Captured 2026-05-18 from UAT. **SHIPPED in c6dcf49.** Subsequent tightening in **e33313b:** `max-h-96` now `max-h-[min(24rem,var(--radix-dropdown-menu-content-available-height,24rem))]` so on small viewports the menu caps at the available space (not just the static 24rem) before falling back to internal scroll.
+> - **DocumentsHub aside column: flush-left with the app sidebar (kill the AppShell padding for this page)** — _src/components/documents/documents-hub.tsx:246_ + _src/components/layout/app-shell.tsx:113-121_ — the desktop `<main>` wrapper applies `px-6 pt-3 pb-6` to all dashboard pages, so the DocumentsHub two-pane (`ResizablePanelGroup` with the `<aside>` folder column on the left) gets 24px of whitespace between the global app sidebar and its own border. The folder column should sit flush against the app sidebar — it reads as "an extension of the navigation," not "a card inside the page." Fix (surgical): change DocumentsHub's root `<div className="h-full">` at line 246 to `<div className="h-full -mx-6 -mt-3 -mb-6">` (mirror the AppShell desktop padding so the hub renders full-bleed inside the main viewport). Add a comment explaining the intentional escape. The right-pane content keeps its own internal `p-4` so it doesn't run flush with the viewport edge. **Alternative (cleaner long-term):** make the AppShell padding route-aware via a prop on `<main>` (or a layout-level opt-out for hub-style pages); but (a) is the right call until a second page needs the same treatment. ~5 min for the negative-margin fix. Captured 2026-05-18 from UAT. **SHIPPED in 8fcbe45:** `sm:-mx-6 sm:-mt-3 sm:-mb-6` on the wrapper (mobile layout unchanged).
+> - **DocumentsHub: hide breadcrumb on root "All documents" view, move PageHeader up to fill the space** — _src/components/documents/documents-hub.tsx:196-209_ — the top row currently always renders the `FolderBreadcrumb` (and conditionally the `NewDocumentMenu` when a folder is selected); on the root view (`selectedFolderId === undefined`) the breadcrumb shows only a "Home / All documents" label with no useful navigation, eating vertical space above the `PageHeader` that already says "Documents" + description. Fix: wrap the entire breadcrumb row at line 196-209 in `{selectedFolderId !== undefined && ( … )}` so the row is gone on the root; the PageHeader becomes the top element. When the rep navigates into a folder, the row reappears with both breadcrumb + NewDocumentMenu (the existing folder views don't render PageHeader, so the breadcrumb is the wayfinding cue). ~5 min. Captured 2026-05-18 from UAT. **SHIPPED in 2bcf544.**
+> - **Residential InterestsTab: whole row should navigate to the interest, not just the "View" link** — _src/components/residential/residential-client-tabs.tsx:273-289_ — current `<li>` lays out `[stage chip] [preferences/notes truncated text] [View → link]` and only the "View" text on the right is clickable. The whole row should be a target, matching the idiom used in the main client's `InterestRowItem` (`src/components/clients/client-interests-tab.tsx:53`) — the entire card is a `<button>`/`<Link>` so reps can tap anywhere. Fix: wrap the `<li>`'s flex container in `<Link href={…}>` (`className="block w-full"` to preserve layout), drop the trailing "View" link, add `hover:bg-muted/50` to make the affordance discoverable. ~10 min. Captured 2026-05-18 from UAT. **SHIPPED (client-detail tab) in c6dcf49.** **SHIPPED (standalone list page) in e33313b:** `<tr onClick={router.push(...)}>` on `residential-interests-list.tsx`; first-cell `<Link>` stops propagation so middle-click / Cmd-click still opens in a new tab.
+> - **Residential namespace breadcrumb link is 404** — _src/components/layout/breadcrumbs.tsx_ (the breadcrumb generator splits the URL and makes every segment a link) + missing _src/app/(dashboard)/[portSlug]/residential/page.tsx_ — on any `/{portSlug}/residential/clients` or `/{portSlug}/residential/interests` page, the breadcrumb renders "Residential" as a link to `/{portSlug}/residential` but no `page.tsx` exists at that path (only `clients/` and `interests/` subdirectories). Clicking the breadcrumb yields a 404. Two reasonable fixes:
+>   - **(a) Quickest:** create `src/app/(dashboard)/[portSlug]/residential/page.tsx` as a server component that calls `redirect(`/${portSlug}/residential/clients`)`. Single file, ~5 min, breadcrumb works immediately. Same pattern works for any other namespace-only segment that lacks a real landing page.
+>   - **(b) Cleaner long-term:** add a "namespace" concept to the breadcrumb generator — segments that exist only as URL parents (residential, admin if applicable, …) render as plain text (`<BreadcrumbPage>`) rather than `<BreadcrumbLink>`. Centralized in `breadcrumbs.tsx`'s `SEGMENT_LABELS` map by extending the value to `{ label, namespace?: boolean }`. ~30 min, fixes the class of problem instead of one instance.
+>   - **Recommendation:** ship (a) now, queue (b) if/when a second namespace-only segment hits the same issue.
+>   - Captured 2026-05-18 from UAT. **SHIPPED (a) in c6dcf49:** new `src/app/(dashboard)/[portSlug]/residential/page.tsx` server-redirects to `/${portSlug}/residential/clients`. (b) namespace concept queued for the second-instance case.
+> - **SHIPPED in 989cc4d (I34):** Email / Call / WhatsApp action buttons mirror the main ClientDetailHeader. WhatsApp number resolves from phoneE164 (preferred) or strips free-text phone to digits. Header surfaces "Linked to main client" chip when auto-link matcher (I37) finds a counterpart. Residential client detail header: match the main ClientDetailHeader layout — _src/components/residential/residential-client-detail-header.tsx_ vs _src/components/clients/client-detail-header.tsx_ — the main client header is rich (`Email` / `Call` / `WhatsApp` deeplink button row using primary contact channels, `PortalInviteButton`, `GdprExportButton`, tag chips, top-right action menu with Bell/reminder + Archive/Restore state-aware + perm-gated hard-delete, archived badge with conditional dialog routing). The residential header (33 lines vs 244) shows only an eyebrow, an inline-editable name, a status badge, and place-of-residence — visually orphaned next to the main client experience.
+>   - **Data-model gap to bridge:** residential clients store contacts inline (`email`, `phone`, `phoneE164`, `phoneCountry` columns on `residentialClients`) rather than via the polymorphic `clientContacts` table the main model uses. Action buttons can still be wired by synthesizing a `[{ channel: 'email', value, isPrimary: true }, { channel: 'phone', value: phone, valueE164, isPrimary: true }]` shape from the inline columns. Other features need verification per residential: tags table exists? portal invite (`residential_clients` has no `clientPortalEnabled` flag → likely N/A); GDPR export (yes — applies to any natural person in EU residence; need a `residential-gdpr-export` route if not already there); archive/restore (residential uses its own service; verify the dialog component expects a `residentialClientId` or needs a separate `ResidentialSmartArchiveDialog`).
+>   - **Approach options:**
+>     - **(a) Copy-and-adapt the JSX shape, residential-specific dialogs** — fastest path. Rebuild `residential-client-detail-header.tsx` with the same layout: title row (truncated name + archived badge), meta line (country · added date), action button row (Email / Call / WhatsApp synthesized from inline columns + optional GDPR export), tag chips (if/when residential gets tags), top-right Bell + Archive/Restore + perm-gated hard-delete. Skip features that don't apply to residential (PortalInviteButton). Parallel residential-specific dialogs where the existing client dialogs don't accept a residential type. ~1.5h.
+>     - **(b) Extract a shared `EntityDetailHeader` primitive** — better long-term. Refactor the main `ClientDetailHeader` to consume a generic `EntityDetailHeader` that takes `{ title, eyebrow?, meta[], contacts[], tags[], topRightActions[], archived }` and renders the layout. Both client headers become thin wrappers that map their entity to the shape. ~3-4h, eliminates the divergence that just got reported, and future entity headers (companies, yachts) can adopt it too — the visual idiom would propagate for free.
+>   - **Recommendation:** ship (a) now for fast visual parity; queue (b) as a separate Bucket 3 refactor when there's appetite for cross-cutting work. Captured 2026-05-18 from UAT.
+> - **StageStepper: surface stage names visibly on reached slices** — _src/components/clients/client-pipeline-summary.tsx:43-82_ (the shared `StageStepper`, used on every client → Interest row card via `InterestRowItem` at `src/components/clients/client-interests-tab.tsx:87`, in the hero/panel variants of `ClientPipelineSummary` — including the per-interest links rendered by `PanelVariant` — and any other caller; fix-once-in-the-shared-component means every surface benefits) — the bar today is a 6px segmented track where each of the 7 pipeline stages is an equal-width slice (filled = reached, hollow = pending). Stage names live only in the `title=` attribute (hover tooltip), so reps have to mouse over to know which slices are filled. User wants the names visible — at least for stages the interest has reached or is currently in.
+>   - **Recommended approach (concise):** Keep the segmented bar exactly as-is (preserves the visual rhythm + works in narrow cards). Render an inline breadcrumb row underneath with one chip per _reached_ stage — chronological left-to-right, last chip = current stage (filled-emphasis using the stage's `STAGE_BADGE` colour), prior chips in the muted variant of the same colour family with a connecting `→`. Pending stages are not labelled (the bar carries that info). Reads as: `Enquiry → Qualified → EOI` for a deal currently in EOI. ~45min.
+>   - **Alternative (verbose):** Convert `StageStepper` to a true horizontal stepper layout — text label above each tick, current stage bolded, past stages muted, pending stages greyed. More familiar pattern but takes more vertical space and wraps awkwardly on narrow containers (a client card with 4-5 active interests stacks them all). ~1.5h, including a `compact` prop so the hero variant can keep the dense form.
+>   - **Recommendation:** ship the inline breadcrumb (concise) — solves the "I can't tell what stage this is at without hovering" complaint with minimum visual footprint, and the existing `STAGE_BADGE` colour map provides the per-stage tint for free. Add a `showLabels?: boolean` prop to `StageStepper` so the dense rail-tile variants (`size="xs"`) can opt out. Captured 2026-05-18 from UAT.
+>   - **SHIPPED in e33313b:** chose the "verbose" stepper variant — stage-name row underneath the bar showing every stage's `STAGE_SHORT_LABELS`. Reached stages render in foreground text; future stages in muted/60 so the rep still sees the ladder ahead. `size="xs"` keeps the dense rail-tile variant intact (no labels row). `STAGE_SHORT_LABELS` re-exported through `pipeline-constants.ts`. Inline-breadcrumb chips variant deferred — the verbose row reads better at the typical container widths we see in practice.
+> - **SHIPPED (sentence rendering) in 03a7521 (J38):** Was `"<actor> updated the X"`; now `"<actor> set X to <value>"` when audit row carries `newValue`. Field-level diff line underneath keeps showing old → new strikethrough for context. Truncates inline value at 60 chars to keep long notes from blowing out the row. Other sub-items (action templates, collapsed-session preview, metadata-based create rows) still parked. EntityActivityFeed: rewrite per-row rendering to surface _what_ changed — _src/components/shared/entity-activity-feed.tsx_ (the shared per-entity timeline used on Clients / Yachts / Berths / Residential / Interest detail pages) — each row currently reads `"<actor> updated the <field>"` with the old→new values dropped on a second line, often null or rendered as a truncated JSON dump. Reps can see _something_ changed but not _what_. Several coordinated fixes — pick the subset that's worth doing in one pass:
+>   - **(a) Bake the value into the sentence line.** Replace `sentence()` (lines 70-77) so when both `fieldChanged` and `newValue` are present the row reads `"<actor> set <field> to <new>"` (with `(was <old>)` appended in muted text on the same line if `oldValue` exists). Eliminates the separate strikethrough line in 80% of cases and reads like a sentence, not a diff. Keeps the separate diff line only for long-form changes (notes body, descriptions) where truncation matters.
+>   - **(b) Type-aware value formatting beyond the four enums already handled.** `formatValueForField()` (lines 48-66) special-cases `pipelineStage`, `source`, `leadCategory`, `outcome`. Extend with: user-FK fields (`assignedTo`, `ownerId`, `createdBy`) resolved to display names via the same bulk-resolution pattern queued in the actor/diff UUID finding above; berth-FK fields (`berthId`, `primaryBerthId`) resolved to mooring number; yacht-FK / company-FK fields resolved to entity name; date columns (`outcomeAt`, `dueDate`, `startDate`) formatted as `MMM d, yyyy`; currency columns (`price`, `total`) formatted via `formatCurrency` with the row's currency code from `metadata`; boolean toggles rendered "enabled" / "disabled" instead of "true" / "false"; JSON / object values get a one-line summary (e.g. address → `"Address updated: 123 Main St → 456 Elm St"` rather than the JSON dump).
+>   - **(c) Compound-action verbs.** The seven `ACTION_VERBS` (lines 26-34) cover only the generic CRUD set. Many real audit-log entries use compound actions (`linked`, `unlinked`, `signed`, `sent`, `viewed`, `archived`, `set_primary`, `merged_into`, `reassigned`, …) that fall back to printing the raw action verb. Audit `audit_logs.action` distinct values for the active port and add a verb + sentence template per case, e.g. `linked` → `"<actor> linked <related-entity-label>"` (reads metadata for the related entity's id + type and renders a clickable link). Templates per action keep the sentence rendering type-safe instead of a giant switch in `sentence()`.
+>   - **(d) Use `metadata` for create rows.** `create` rows currently say `"<actor> created this record"`. Pull the entity's name/mooring/identifier out of `metadata` (or a small lookup if metadata's empty) so it reads `"<actor> created client <Name>"` / `"<actor> created berth <A12>"`.
+>   - **(e) Collapsed-session preview text.** The `SessionGroupItem` collapse (lines 245-260) currently reads `"<actor> made N changes in this session"`. Show a one-line preview of _which_ fields were touched (e.g. `"Matt changed pipeline stage, owner, and 2 more fields"`) so reps can see if the session is worth expanding without clicking.
+>   - Effort: ~2h for (a)+(b)+(d) (the most user-visible wins, all in this one file plus a thin bulk-resolution helper in the activity-feed service). ~1h for (c) (registry of action templates). ~30min for (e). Total ~3.5h for the full bundle, or pick (a)+(b)+(d) as the high-value MVP at ~2h. Captured 2026-05-18 from UAT — same surface as the activity-feed UUID resolution finding above (the bulk-resolution helper introduced for that finding is the prereq for (b)'s user-FK resolution; do these in one pass).
+> - **SHIPPED in 03a7521 (J39):** Empty state gains "Link to a company" action; populated state grows top-right "Link to company" button. New `<LinkCompanyDialog>` wraps existing `<CompanyPicker>` + membership-role select + isPrimary checkbox, POSTs to /api/v1/companies/[id]/members. Empty-state copy dropped "Add a membership from a company's detail page". **Client → Companies tab: add CTA to link or create a company membership** — _src/components/clients/client-companies-tab.tsx_ (the tab, including the EmptyState at lines 44-51 and the table-populated branch at 53-101) — the tab currently shows a list of company memberships pulled from `company_memberships`; the EmptyState literally tells the rep "Add a membership from a company's detail page" — a backwards workflow that forces them to leave the client they're working on, navigate to a company, then come back. The populated view also has no "Add another" affordance.
+>   - **Backend ready:** `POST /api/v1/companies/[id]/members` already exists (with corresponding `PATCH` and `DELETE` on `/members/[mid]`, plus `POST /members/[mid]/set-primary`) and accepts a `clientId` in the body. No new schema work needed.
+>   - **UI work:** (1) Add a primary "Link or add company" button in the tab header (next to the `Company affiliations` heading), gated by `memberships.manage`. (2) Sheet with two modes — **(a) Link existing**: combobox-search across companies (use existing `/api/v1/companies/autocomplete`) + role select + isPrimary toggle + optional startDate; on submit calls `POST /api/v1/companies/{selectedCompanyId}/members` with this client's `clientId`. **(b) Create new + link**: opens `CompanyForm` in create mode (drawer-in-drawer or step 2 of the sheet); on successful create, chains the same membership POST. Toast on completion, invalidate `['client', clientId]` so the tab refreshes. (3) Replace the EmptyState's copy with one matching the new CTA ("No company memberships yet — link this client to a company below.") and surface the same button there too. (4) Each row in the populated table gets a kebab menu: "Set as primary" (POST set-primary), "Edit role / dates" (PATCH), "Remove" (DELETE with confirm).
+>   - **Symmetry note:** The "Companies → Members" tab already has the inverse flow (add a client to a company) — same UI primitives should be reusable; consider lifting the membership form into a shared `MembershipForm` if the divergence is small. ~1.5-2 h end-to-end. Captured 2026-05-18 from UAT.
+> - **Activity feed: resolve actor + diff UUIDs to display names** — _src/components/dashboard/activity-feed.tsx (ActivityFeedInner ~line 175)_, plus the activity-feed service that loads `audit_logs` rows, plus the diff-rendering helper that produces the `"old → new"` strings — two related findings from UAT, both UUIDs leaking into the rendered card:
+>   - Diff entries with FK columns (e.g. `assignedTo: "—" → "mEcsLxo5kyFMyhbOSehxJjYSSD7CiLvv"`) print the raw user UUID instead of the user's display name. Root cause: `audit_logs.fieldChanged='assignedTo'` rows store the new column value as a raw string; the formatter has no type info that tells it to resolve as a user FK.
+>   - Actor / subject identifiers in the row meta (e.g. `"d62aadbf"` — short UUID prefix) also render raw. Same root cause: the renderer falls back to a UUID slice when the row's `actorName`/`subjectLabel` is empty.
+>   - Fix shape: (1) extend the audit-logs schema (or the activity-feed service) with a typed-field registry — `{ field: 'assignedTo', kind: 'user_fk' }`, `{ field: 'ownerId', kind: 'user_fk' }`, `{ field: 'reassignedTo', kind: 'user_fk' }` etc. (2) When the service hydrates rows for the feed, bulk-fetch every referenced user (`SELECT id, firstName, lastName, email FROM users WHERE id IN (…)`) and replace the raw UUID strings with display names in both the diff `old`/`new` AND the `actorName`/`subjectLabel` columns. (3) Render fallback: if the user no longer exists (deleted/never-existed), show `"Unknown user (#<short-uuid>)"` so the feed remains useful for forensics. (4) Same treatment for any _other_ FK fields that may have slipped in (yacht IDs, berth IDs, etc. — audit at finding time).
+>   - ~1.5-2 h end-to-end (schema-light approach via a per-field registry in code, no migration). If we ever expand to non-user FKs, generalize the registry to dispatch by entity type. Captured 2026-05-18 from UAT. **SHIPPED in 2cb0b99:** `getRecentActivity` now collects all userIds from `auditLogs.userId` + user-FK `oldValue`/`newValue` (assignedTo, ownerId, reassignedTo, createdBy, addedBy, changedBy, transferredBy), bulk-fetches `user_profiles`, and returns rows with display-name replacements + an `actorName` field. Unknown / deleted users fall back to `Unknown user (#short-uuid)`. ActivityItem client type extended.
+> - **EOI bundle UX rework (multi-berth interests)** — _src/lib/services/interest-berths.service.ts_, _src/components/interests/linked-berths-list.tsx_, _src/components/documents/eoi-generate-dialog.tsx_ — **DESIGN CONFIRMED 2026-05-18.** Workflow assumption: half+ of interests are multi-berth; typically one signed EOI covers many berths (e.g. A1-A10) but only the website-entry / "main" berth (e.g. A2) should show "Under Offer" on the public map. The current schema defaults (`is_specific_interest=true`, `is_in_eoi_bundle=false`) invert this — every linked berth shows publicly + nothing is bundled until ticked. Three coordinated changes:
+>   - **(a) Smarter insert-time defaults** in `addInterestBerth()`:
+>     - `is_in_eoi_bundle` → default **`true`** (any linked berth is presumed covered by the signed EOI; rep unticks for the rare carve-out case).
+>     - `is_specific_interest` → default **`false`** for non-primary rows; **`true`** only when the row is primary (matches "only the main berth gets publicly marked Under Offer").
+>     - ~30 min including unit-test coverage for the new defaults and a clarifying comment.
+>   - **(b) Rename + tooltip on LinkedBerthsList toggle** — "Mark in EOI bundle" → "Include in EOI" + an info popover explaining the bundle-vs-public distinction (matters more now that the two flags routinely diverge). ~15 min.
+>   - **(c) "EOI berth scope" picker inside the EOI Generate dialog** — at the moment of EOI generation, surface every linked berth as a row with **two** checkboxes: "In EOI bundle" and "Show on public map". Pre-fill from current flag state (which, post-(a), is mostly already correct). The picker forces the rep to consciously confirm signature scope + public visibility at the moment that question is live in their head, instead of relying on them having visited the LinkedBerthsList toggles upstream. Saving the dialog updates all `interest_berths` rows in one call before kicking off the Documenso envelope. ~1.5-2 h.
+>
+>   Total ~2.5-3 h end-to-end. Closes the multi-berth EOI discoverability gap (plan §1 + §4.6) and matches the documented workflow expectation that public map visibility is a _subset_ of EOI bundle coverage.
+>
+> **SHIPPED (a) in 05e727f:** `addInterestBerth` defaults flipped: `is_in_eoi_bundle: true`, `is_specific_interest: matches isPrimary`. (b) `linked-berths-list.tsx` rename + tooltip shipped in PR10. **(c) SHIPPED in ef37901:** EoiGenerateDialog gains an "EOI scope" section listing every linked berth with "In EOI" + "Public map" checkboxes; handleGenerate diffs vs server snapshot and PATCHes only changed rows in parallel before kicking off the envelope. Cache invalidation extended to `['interests', id, 'berths']` so LinkedBerthsList stays consistent.
+
+1. **Berth-demand widget visual overhaul** — _src/components/dashboard/berth-heat-widget.tsx_ — original "Berth heat" widget was a generic table that read as uninspired. First pass added an editorial hero + gradient — that strayed from the standard `CardHeader`/`CardContent` idiom and looked out of place next to siblings. Final version matches `hot-deals-card.tsx`'s layout exactly (icon + title + description in CardHeader, list of `-mx-2 hover:bg-accent/60` rows in CardContent); the visual upgrade is the per-row status-coloured magnitude bar. UI label renamed "Berth Heat" → "Berth Demand" in `widget-registry.tsx`. Fixed in this session.
+2. **First-class "demand" sort on the berths list** — _src/lib/services/berths.service.ts_, _src/components/berths/berth-columns.tsx_, _src/lib/validators_ — added `?sort=activeInterestCount` to the berths-list service via a correlated subquery in `customOrderBy`; attached `activeInterestCount` per row using the existing two-pass post-fetch pattern (alongside tags/latestInterestStage); added the "Active interests" column to `BERTH_COLUMN_OPTIONS` (default-visible, sortable). Widget's "View all by demand →" link deep-links to `/berths?sort=activeInterestCount&order=desc`. Saved views and the column picker can now use the same lens. Fixed in this session.
+3. **Pipeline Value tile expanded with per-stage breakdown** — _src/components/dashboard/pipeline-value-tile.tsx_, _src/lib/services/dashboard.service.ts_ — replaced the single-number KPI with a richer card: gross headline + weighted forecast on top, per-stage rows below (label · mini bar · gross value · count + close-probability), and a footnote when default stage weights are in use. Service `getRevenueForecast` extended to return `grossValue`, `weight`, `totalGrossValue`, and `dealsMissingPrice` alongside the existing weighted shape; the tile pulls from `/kpis` (for gross + currency + activeInterests) and `/forecast` (for breakdown). Per-stage warning chip surfaces when berths are missing a `price` so a silently undercounted gross is visible (full coverage → "berth price missing", partial → "N of M missing price"). Leadership can now see how much of the headline is near-close vs speculative. Fixed in this session.
+4. **"How weighted forecast works" info popover on the Pipeline Value tile** — _src/components/dashboard/pipeline-value-tile.tsx_ — added an `Info` icon next to the description that opens a `Popover` (click or hover) explaining the close-probability model + showing the per-stage weight table (live from `/forecast`, fallback to `STAGE_WEIGHTS` constant) + a note about whether default or per-port weights are in use. Fixed in this session.
+5. **Bulk + inline berth price editing — backend complete** — _src/lib/db/schema/users.ts_, _src/lib/db/seed-permissions.ts_, _src/components/admin/roles/role-form.tsx_, _src/components/admin/users/user-permission-matrix.tsx_, _src/app/api/v1/admin/users/[id]/permission-overrides/route.ts_, _src/lib/validators/berths.ts_, _src/lib/services/berths.service.ts_, _src/app/api/v1/berths/[id]/price/route.ts_, _src/app/api/v1/berths/bulk-update-prices/route.ts_, _tests/helpers/factories.ts_ — new `berths.update_prices` permission carved out from generic `berths.edit` so sales reps can update prices without exposing the full edit surface. Permission seeded on for super_admin/director/sales_manager/sales_agent, off for viewer/residential_partner. New validators (`updateBerthPriceSchema`, `bulkUpdateBerthPricesSchema` capped at 500/batch), services (`updateBerthPrice`, `bulkUpdateBerthPrices`, both transactional + per-row audited with `fieldChanged='price'` + realtime `berth:updated` + webhook fan-out), and routes (`PATCH /api/v1/berths/[id]/price`, `POST /api/v1/berths/bulk-update-prices`). UI shipping in a follow-up — see Features bucket #1. Fixed in this session.
+
+---
+
+## Bucket 3 — Features / larger (> 2 h)
+
+_New UI surfaces, new endpoints, schema migrations, multi-step flows._
+
+> **[Umami] Larger follow-ups parked at end of 2026-05-19 build session:**
+>
+> - **SHIPPED in a7cbee0 (O48):** New POST /api/v1/tracked-links mints redirect-link the rep can drop into outgoing email; body { targetUrl, sendId? }, returns { id, slug, targetUrl, url }, gated on `email.send`. `<TrackedLinkComposerButton>` opens a dialog: paste destination → Create → returns public /q/<slug> URL with Copy + "Insert into message" action. Wired into `<SendDocumentDialog>`'s Message body label row. **[Umami] Tracked-link composer button (Phase 4c UI)** — _src/components/email-composer/_ (find/create) + _src/lib/services/tracked-links.service.ts (already shipped)_ — backend shipped this session: `tracked_links` + `tracked_link_clicks` tables, `/q/[slug]` redirect endpoint, `createTrackedLink` + `buildTrackedUrl` helpers, Umami `link-clicked` cross-post. The missing piece is the rep-facing UI. Recommendation: a "🔗 Tracked link" button inside the sales email composer that takes the currently-selected URL (or prompts for one), calls `createTrackedLink({portId, targetUrl, sendId})`, and inserts the resulting `/q/<slug>` URL in place of the original. Show per-link click stats on the document_sends list (companion to the Bucket 2 open-rate column). Cap: ~3-4 h including the list-side rendering of click stats. Captured 2026-05-19.
+> - **[Umami] Marketing-site instrumentation (Phase 4a)** — _separate marketing-site repo, NOT this one_ — adds `umami.track('cta-clicked', {…})`, `umami.track('eoi-page-reached')`, etc. calls on the marketing site so the Events tab + cross-system funnels (Phase 3 + Phase 5) light up. Also adds a `do_not_track` opt-out checkbox to the marketing-site cookie banner so visitors who decline tracking get `localStorage.setItem('umami.disabled', '1')` and skip the script entirely. Needs to be coordinated with whoever owns the marketing-site repo — capture the schema we want them to emit (event names + payload shapes) in `docs/marketing-site-event-catalogue.md` once we know which CRM funnels we actually want to drive. ~4-6 h of marketing-repo work + ~2 h of CRM-side cataloguing. Captured 2026-05-19.
+> - **[Umami] Events tab (Phase 3)** — _src/components/website-analytics/events-list.tsx (new)_ + new route — Umami's `/api/websites/:id/events` is already wrapped in `umami.service.ts` (`getEvents`, `getEventsStats`, `getEventsSeries`). Surface as a new "Events" tab on the analytics page. BLOCKED on Phase 4a — the tab is empty until the marketing site fires custom events. Cap: ~3-4 h once 4a lands. Captured 2026-05-19.
+> - **[Umami] Funnels + Journeys (Phase 5)** — _src/components/website-analytics/funnel-builder.tsx (new)_ + _src/components/website-analytics/journey-flow.tsx (new)_ — Umami's `/api/websites/:id/reports/funnel` and `/journey` endpoints are wrapped (`runFunnelReport`, `runJourneyReport`). Funnel builder = pick N steps (URL or event), see per-step conversion. Journey flow = sankey-style visualisation of where visitors go after a chosen entry page. BLOCKED on Phase 4a for the event-driven half. Cap: ~6-8 h. Captured 2026-05-19; deferred to end per earlier scoping.
+> - **SHIPPED (partial) in a7cbee0 (O54):** `VisitorWorldMap` already supported `onCountryClick`; wired through to copy the `/<portSlug>/clients?nationality=<ISO>` deep-link to clipboard with toast on click. Inline filtering of the analytics view itself stays parked alongside Phase 5 — the useUmami* hooks don't yet accept a country filter. **[Umami] Click-to-filter the page from the world map** — *src/components/website-analytics/visitor-world-map.tsx* + new `country` filter store + thread through every `useUmamiTop*`hook —`VisitorWorldMap`already accepts an`onCountryClick(iso2)`prop that's unused. Wire it to a page-wide country filter (Zustand store or URL search param`country=US`) that scopes every card on the page to that country's data. Mirrors Umami's own click-through behaviour. Cap: ~2-3 h. Captured 2026-05-19.
+> - **[Umami] Per-rep `identify()` calls for attribution** — _src/components/auth/use-session.tsx (or wherever the session is hydrated)_ + _src/lib/services/umami.service.ts (new `identifyRep` wrapper)_ — call `umami.identify({sessionId, role: 'rep', repId: user.id})` on every authenticated CRM session so Umami's Sessions list can show "this lead came in while Matt was working hours". Privacy-gated: only fires for super-admin / sales-manager / sales-agent roles, never for residential-partner, never for portal-side users. Captured 2026-05-19; deferred as the privacy/value trade-off needs a product call before building.
+
+0. **SHIPPED in 91be0f9:** Form-template fields bind to Interest/Client data — autofill, override-preservation history, dual-surface audit trail. Catalog (`bindable-fields.ts`) + `formFieldSchema.bindTo` allow-list + admin "Bind to" picker; `applySubmission` writes phone/yacht/insert-path diffs that were previously silent; clients endpoint mirrors the existing interest one; `<FieldHistoryProvider>` + inline clock icon next to each editable field on Client + Interest Overview tabs and ContactsEditor (per UX spec d-i). Original spec follows for reference; UI uses a clock icon rather than "i" but the popover content matches.
+   > - **(a) Template-builder: bind each field to an Interest/Client data point via dropdown.** Today's Field row asks for a freetext `key` + `label` + `type`. Replace `key` with a dropdown listing every bindable data point keyed by a stable token, e.g.:
+   >   - Interest-scoped: `interest.desiredLengthFt`, `interest.desiredWidthFt`, `interest.desiredDraftFt`, `interest.notes`, `interest.source`, `interest.tags`, ...
+   >   - Client-scoped: `client.fullName`, `client.dateOfBirth`, `client.nationality`, `client.passportNumber`, `client.residentialAddress`, ...
+   >   - Client-contact-scoped (per channel): `client.contacts.primaryEmail`, `client.contacts.primaryPhone` (resolved server-side to the `client_contacts` row with `isPrimary=true`).
+   >   - Yacht-scoped (when interest has a linked yacht): `yacht.name`, `yacht.lengthFt`, `yacht.makeAndModel`, ...
+   >   - Custom (no binding): freetext `key` for fields that don't map to any record column. Submission stored as-is in `form_submissions.data` JSONB, surfaced for rep review but not written back to any record.
+   >   - **Field shape extension:** `{ key, label, type, required, bindingPath?: string }` where `bindingPath` is the dotted-token from the bindable catalog. `key` stays as the JSONB submission key (so existing templates keep working — `bindingPath` is purely additive).
+   >   - **Catalog source:** define once in `src/lib/services/form-bindings-catalog.ts` exporting `BINDABLE_FIELDS: Array<{ path, label, entity, resolveCurrentValue, writeBack }>` — each entry knows where the value lives, how to read it, and how to write it back. Reuses the existing merge-fields infra (per CLAUDE.md `src/lib/templates/merge-fields.ts`) so the same vocabulary powers EOI templates AND supplemental forms.
+   > - **(b) Public form autofill.** When the client opens the supplemental URL, server-side resolver:
+   >   - Loads the interest + client + linked yacht for the token.
+   >   - For each field with a `bindingPath`, calls `resolveCurrentValue()` to get the current stored value.
+   >   - Returns each field with a `currentValue` so the public form mounts pre-filled. Client reviews → edits if needed → submits.
+   >   - Fields without a binding stay empty (client-provided input).
+   > - **(c) Submit handler: diff + override-preservation history.** On submit, for each bound field:
+   >   - Compare submitted value against current value (case-sensitive for free-text; deep-equal for arrays/objects).
+   >   - **Unchanged** → no-op. Don't write back, don't audit (saves noise).
+   >   - **Changed** → (i) call `writeBack(submittedValue)` to update the underlying interest/client/contact column. (ii) Append a history row: `{ portId, interestId, clientId, fieldPath, oldValue, newValue, source: 'supplemental_form', submissionId, providedAt, providedBy: 'client' }`. (iii) Audit log entry for the same change (existing audit infra) so org-wide audit reports see it.
+   >   - **New schema:** `interest_field_history` table — `id, port_id, interest_id, client_id (nullable, denormalized for client-detail queries), field_path text, old_value jsonb, new_value jsonb, source text ('supplemental_form' | 'rep_edit' | 'system_inferred'), submission_id (FK to form_submissions, nullable), created_at, created_by` + indexes on `(port_id, interest_id, created_at desc)` and `(port_id, client_id, created_at desc)` for the dual-surface lookups. Alternative: stuff in `audit_logs` with `source='supplemental_form'` and reuse the existing diff schema — cheaper but harder to query for the "show me the override history for this field" UX.
+   > - **(d) UI surfacing on both record views.**
+   >   - **Interest detail:** small "i" icon next to each field that has history. Hover/click opens a popover: `Previous value: <X> · Updated by client via supplemental form on <date>`. Stacks multiple history rows in chronological order.
+   >   - **Client detail:** same UX, with an additional context line: `Updated via supplemental form for interest <berth label> on <date> → [Open interest]`. Cross-link goes to the source interest. Reuses the same `berthLabel` helper from the document-detail Interest link fix.
+   >   - Bonus: a dedicated "Field override history" section on the interest detail's Activity tab listing every override sourced from supplemental forms (or rep edits) for that interest — gives compliance + dispute resolution a single audit surface.
+   > - **(e) Edge cases to think through:**
+   >   - **Required fields that resolve to existing values** — should they bypass `required` validation since they're pre-filled? Yes; required = "must have a value at submit time", not "must be re-entered by client".
+   >   - **Multi-value paths** (e.g. `client.contacts.primaryEmail` — what if client has none?) — `resolveCurrentValue` returns null, field renders empty, client provides one, submit writes a new client_contacts row marked isPrimary=true.
+   >   - **Type coercion mismatches** — bind path returns a number (`desiredLengthFt`), form field type is `text`. Catalog defines the canonical type per path; template builder validates compatibility at save time.
+   >   - **Sensitive fields** (passport, DOB) — `BINDABLE_FIELDS` entries flag `sensitivity: 'pii' | 'public' | 'internal'`; the supplemental form template builder warns / blocks selecting PII fields without explicit admin override (avoids accidental public-form data leak).
+   > - **Effort:** ~12-16h end-to-end. ~2-3h for the catalog + resolver/writer infra. ~2h for the template-builder dropdown UI. ~2-3h for the autofill resolver in the public form service. ~3-4h for the submit diff + history table + audit + writeback. ~2h for the dual-surface UI (interest + client detail history popover). ~1h for sensitive-field gating + edge cases. Captured 2026-05-21 from UAT. **Cross-ref:** ties into the existing supplemental-info-request findings in Bucket 2 (reusable-not-single-use, generate+send split, regenerate+resend) — ship the binding/autofill/history work AFTER those land so the supplemental form is mature enough to carry the additional complexity.
+1. **SHIPPED in 0ddaf46 (M42):** FilePreviewDialog now handles seven preview kinds via a single `previewKindFor()` router. Text (.txt/.md/.csv/.tsv/.json/.xml/.log/.yaml/.ini/.html) via new `<TextPreview>` (fetches presigned URL, caps body at 1 MB with banner). Audio/video via native HTML5 with preload="metadata". Office docs (.docx/.xlsx/.pptx/.odt/.ods/.odp) embed via Microsoft hosted Office viewer (presigned URLs carry the token). Unknown mime types render a friendly "preview not supported" block with Download CTA. **Universal in-system preview for every file type (extend FilePreviewDialog beyond PDF + images)** — _src/components/files/file-preview-dialog.tsx:60-120_ — today only `mimeType?.startsWith('image/')` and `mimeType === 'application/pdf'` render; everything else falls through to a blank preview surface (no message, no fallback). User wants every document previewable in-system without forcing a download. Today's gaps: Office documents (.docx / .xlsx / .pptx), plain text (.txt / .csv / .md), email exports (.eml / .msg), video / audio, archives (.zip — see-into).
+
+- **Coverage tiers:**
+  - **Tier 1 (cheap, native-browser):** plain text (`text/plain`), CSV, Markdown → fetch + render in a styled `<pre>` or via a small markdown renderer (`react-markdown` already a likely dep — verify); video (`video/*`) → `<video controls src=…>`; audio (`audio/*`) → `<audio controls src=…>`. ~1-2h for all four.
+  - **Tier 2 (lib-based, no server work):** DOCX → `mammoth.js` (~25KB gzipped) renders to HTML in-browser, good fidelity for text/headings/tables, loses complex formatting; XLSX → `sheetjs` (`xlsx` package) renders to an HTML table; PPTX → tricky, browser-side support is poor (recommend skip → fall back to "Download to view"). ~3-4h.
+  - **Tier 3 (server-side conversion):** for fidelity on complex Office docs, route through a headless LibreOffice or `gotenberg` service to convert to PDF, then preview with the existing PdfViewer. Adds infra cost (Docker container for the converter). ~6-10h including ops setup. **Recommendation:** defer Tier 3 to a follow-up; ship Tier 1 + 2 first and accept the fidelity loss for Office docs.
+- **Fallback UX:** when the mime type isn't in any tier, render an empty-state card: file icon + filename + size + "Preview not supported for this file type. [Download to view]" button. Today's silent-blank surface is the bug.
+- **Recent Files preview-click fix** (Bucket 4 #7) folds into this: as we audit every preview surface, wire click handlers consistently on FileGrid / RecentFilesList / DocumentList rows. Don't ship preview support without making sure every list surface is actually clickable.
+- **Effort:** ~5-7h for Tier 1 + Tier 2 + fallback + clickability audit. Tier 3 deferred. Captured 2026-05-21 from UAT.
+
+0.  **Platform-wide date picker primitive (desktop popover + mobile native) — replace 22 `<input type="date|datetime-local">` sites** — _new_ `src/components/ui/date-picker.tsx` + `src/components/ui/date-time-picker.tsx`, then sweep 22 call sites (see list below). Native browser date/datetime inputs render with inconsistent, ugly UI on desktop (varies by Chromium/Safari/Firefox; Comet shows the worst variant). Mobile system pickers are the opposite — touch-friendly wheel/spinner UX that we want to keep. Build a wrapper that switches based on viewport.
+    > - **Design (no new deps needed):** we already have `react-day-picker@10`, `date-fns@4`, and `src/components/ui/calendar.tsx`. Follow the canonical shadcn pattern (verified via Context7 against current shadcn docs):
+    >   - `<DatePicker>` — desktop: trigger Button shows formatted date + chevron, opens Popover containing `<Calendar mode="single" captionLayout="dropdown" />` (the dropdown caption gives month/year nav for fast jumping to historical dates — critical for the backfill UX). Mobile: native `<input type="date">` for the system picker.
+    >   - `<DateTimePicker>` — desktop: same Popover with Calendar plus a native `<input type="time" step="60">` in the popover footer (shadcn-canonical approach — hides webkit-picker-indicator via `[&::-webkit-calendar-picker-indicator]:hidden` and surfaces a `Clock` icon). Mobile: native `<input type="datetime-local">`.
+    > - **Mobile detection:** use existing `useIsMobile` hook (if absent, add one via `window.matchMedia('(max-width: 640px)')` + `useSyncExternalStore` so SSR works). CSS-only show/hide is an alternative but DOM duplication wastes a tiny amount; hook-based is cleaner.
+    > - **Same prop shape as today's `<Input type="date">`** so call-site migration is `<Input type="date" value=… onChange=… />` → `<DatePicker value=… onChange=… />` — minimal surface area change.
+    > - **Optional polish (defer to v2):** add a `naturalLanguage` flag using `chrono-node` (~2KB) so users can type "next Tuesday" / "in 3 days" — particularly nice on the reminder form's due-date field. Skip for v1 to keep scope tight.
+    > - **Call sites to migrate (22 files found via `grep "datetime-local|type=\"date\""`):** `src/app/(dashboard)/[portSlug]/invoices/new/page.tsx`, `src/app/(dashboard)/[portSlug]/expenses/scan/page.tsx`, `src/components/berths/berth-form.tsx`, `src/components/invoices/invoice-detail.tsx`, `src/components/yachts/yacht-transfer-dialog.tsx`, `src/components/reservations/reservation-detail.tsx`, `src/components/reservations/berth-reserve-dialog.tsx`, `src/components/expenses/expense-form-dialog.tsx`, `src/components/admin/audit/audit-log-list.tsx`, `src/components/shared/inline-editable-field.tsx`, `src/components/shared/filter-bar.tsx`, `src/components/scan/scan-shell.tsx`, `src/components/dashboard/date-range-picker.tsx`, `src/components/interests/payments-section.tsx`, `src/components/interests/interest-tabs.tsx` (incl. the `MilestoneAdvanceButton` popover at line 318), `src/components/interests/interest-contact-log-tab.tsx`, `src/components/interests/external-eoi-upload-dialog.tsx`, `src/components/reminders/snooze-dialog.tsx`, `src/components/companies/add-membership-dialog.tsx`, `src/components/reminders/reminder-form.tsx`, `src/components/companies/company-form.tsx`, `src/components/reports/generate-report-form.tsx`. Several callers (e.g. `filter-bar.tsx`, `inline-editable-field.tsx`, `date-range-picker.tsx`) wrap the input and need slightly more care — small refactor of the wrapper, not a 1-line swap.
+    > - **Effort:** ~45 min to build the two wrappers + `useIsMobile` (if needed); ~2-3h to sweep all 22 call sites + visual verification in browser. Total ~3-4h. Captured 2026-05-21 from UAT.
+    > - **SHIPPED (primitives + highest-leverage migrations) in 8f42940:** `<DatePicker>` + `<DateTimePicker>` land in `src/components/ui`. Migrated: `MilestoneAdvanceButton` (Interest backfill UX), `reminder-form`, `snooze-dialog`, `external-eoi-upload-dialog`, `payments-section`. **Remaining ~17 sites parked** for a follow-up sweep — several use react-hook-form `register` patterns that need the controlled-value migration done carefully (expense-form-dialog, invoice/new, reservation/berth-reserve dialogs, company/yacht/audit forms, etc.).
+    > - **SHIPPED (remaining 14 sites) in 0c6e7b7:** completed the sweep. Migrated: `audit-log-list.tsx`, `reports/generate-report-form.tsx`, `scan/scan-shell.tsx`, `reservations/reservation-detail.tsx`, `shared/filter-bar.tsx`, `berths/berth-form.tsx`, `reservations/berth-reserve-dialog.tsx`, `companies/add-membership-dialog.tsx`, `yachts/yacht-transfer-dialog.tsx`, `invoices/invoice-detail.tsx`, `expenses/expense-form-dialog.tsx`, `companies/company-form.tsx`, `interests/interest-contact-log-tab.tsx` (datetime-local x2). RHF `register` sites wrapped with `<Controller>` + the picker's `value`/`onChange` bridge; Date-typed schemas (expenseDate, incorporationDate) get an inline Date↔YYYY-MM-DD bridge. Skipped because they ARE primitives or internal date variants: `ui/date-picker.tsx`, `ui/date-time-picker.tsx`, `shared/inline-editable-field.tsx`, `dashboard/date-range-picker.tsx` (own popover with min/max gating). Removed 4 now-unused `Input` imports.
+1.  **Platform-wide chart library migration: recharts → ECharts** — _src/components/dashboard/_ + _src/components/website-analytics/_ + _src/components/berths/_ — we now run two chart libraries side-by-side: ECharts (just adopted for the world choropleth + tree-shaken, canvas renderer, d3-geo projection) and recharts (everything else: berth-status donut, occupancy-timeline line, pipeline-funnel bar, lead-source pie, source-conversion bar, berth-heat-widget bars, pageviews-vs-sessions area, pipeline-value-tile mini-bars — ~8+ components). **Trade-off analysis (done 2026-05-19 during analytics build):** ECharts wins on visual polish (better default styling, smoother animations, native legend/tooltip behaviour), comprehensive chart types (sunbursts, sankeys, parallel coords, heatmaps, geo all out of the box), and canvas-renderer performance on dense series; recharts wins on React-idiom (declarative `<Area>` / `<Bar>` children vs imperative option objects) and bundle size for the very simplest charts. **Migration cost:** ~6–10 h to port the existing 8 components; each is a 50–150 LOC swap from `<ResponsiveContainer><AreaChart>…` to an `<ReactEChartsCore option={…} />` with tree-shaken module imports. **Pre-reqs already in place:** `transpilePackages: ['echarts', 'zrender', 'echarts-for-react']` added to `next.config.ts`, `d3-geo` installed, dynamic-import + canvas-renderer pattern proven on the world map. **Recommendation:** do as a single coordinated pass (consistency wins over piecemeal), gated on a free afternoon — none of the existing recharts components are buggy, this is purely about platform-wide visual + capability parity with the new analytics surfaces. Captured 2026-05-19 during the Umami flesh-out work.
+
+2.  **Bulk-price editing UI** — _src/components/berths/_, _src/components/berths/berth-columns.tsx_ — backend shipped this session (new `berths.update_prices` permission across schema + 6 role maps + admin UI + factories; validators `updateBerthPriceSchema` + `bulkUpdateBerthPricesSchema`; services `updateBerthPrice` + `bulkUpdateBerthPrices` — both per-row audited with `fieldChanged='price'`; routes `PATCH /api/v1/berths/[id]/price` + `POST /api/v1/berths/bulk-update-prices`, ≤500 berths per batch). UI work pending: (a) wire `InlineEditableField` into the price cell of `berth-columns.tsx` (click → input → PATCH) gated by `can('berths', 'update_prices')`; (b) add `bulk-price-edit-sheet.tsx` (right-side Sheet, per-row inputs, "Set all to" + "Apply % adjust" shortcuts) wired to `bulkActions` on the `<DataTable />` in `berth-list.tsx`. ~2–3 h to ship the UI.
+3.  **SHIPPED in a147cbc (N44):** Tile accepts optional `range` prop and threads it through /api/v1/dashboard/kpis?range=<slug> + /forecast?range=<slug>. Service functions accept optional {from,to} bounds and scope the pipeline-value SQL to interests created within the window. New `parseRangeSlug` helper inverts `rangeToSlug`. Widget registry forwards the active dashboard range to the tile. **Pipeline Value tile should respect dashboard timeframe** — _src/components/dashboard/pipeline-value-tile.tsx_, _src/lib/services/dashboard.service.ts_ — the dashboard has a Today / 7d / 30d / 90d / Custom filter at the top (`Last 30 days` shown beside the greeting) but the Pipeline Value tile shows an absolute snapshot regardless. Should be constrained to the active timeframe: e.g. "Pipeline as of end of range" + "Revenue actually realized in range" (closed-won × berth price for interests whose `outcome_at` falls in the window). Needs: dashboard-wide timeframe context (Zustand store or React Query keyed by range), forecast/KPI service variants that accept a `range`, and a "realized vs forecast" line in the tile. ~3–4 h.
+    3a. **Remove `/admin/reports` entirely (redundant with configurable Dashboard) + integrate PDF-report exporter into the Dashboard header** — _src/app/(dashboard)/[portSlug]/admin/reports/page.tsx + src/components/admin/reports-dashboard.tsx_ (DELETE) + _src/components/dashboard/dashboard-shell.tsx (or wherever the dashboard header lives)_ (ADD "Export to PDF" button) + the PDF exporter dialog (next entry). Today's `/admin/reports` page renders Pipeline funnel + Berth occupancy + activity feed — every card is also a Dashboard widget, and the Dashboard is configurable while this page is fixed. Surfaced UAT 2026-05-21 as "feels useless since we have the dashboard" + user follow-up 2026-05-21: "the pdf report exporter we will need to integrate into the dashboard — or make a dedicated reports page with even more charts/stats (though i think this may be redundant)." > - **Decision (locked 2026-05-21):** integrate PDF exporter into the Dashboard, remove `/admin/reports`. Path: (a) delete `src/app/(dashboard)/[portSlug]/admin/reports/page.tsx` + `src/components/admin/reports-dashboard.tsx`; (b) drop the "Reports" link from admin nav + search-nav-catalog (cross-ref the duplicate-key dedupe finding in Bucket 4 — same catalog file); (c) add a redirect from `/admin/reports` → `/dashboard` so any bookmark/external link lands sensibly; (d) add "Export to PDF" button in the Dashboard header (right-hand controls cluster, next to the date-range picker). > - **Why not a dedicated more-charts reports page:** a separate Reports page with "even more charts" inevitably duplicates Dashboard data. Either the Dashboard lags behind, or the Reports page becomes a copy. Better to invest that effort in adding more widgets directly to the Dashboard (which is configurable, so reps who don't want the extra cards can hide them). > - **What if leadership later wants a fixed read-only exec view?** revisit then — by that point we'll know whether reps actually use it or just print the Dashboard. YAGNI for now. > - **Effort:** ~30 min for the route removal + redirect + nav cleanup. PDF exporter itself is feature #3 below — that's where the substantive work is. Captured 2026-05-21 from UAT.
+4.  **Stylized branded PDF report exporter — Dashboard-integrated (locked 2026-05-21)** — _src/components/dashboard/_ (new `<ExportReportDialog>` + Dashboard header trigger) + _src/lib/services/dashboard-report.service.ts (new)_ + the existing `pdfme` (templates) and `pdf-lib` (filling) infra plus per-port branding from `system_settings`. **Location decision locked:** lives on the Dashboard, NOT on a separate `/admin/reports` page (which is being removed — see 3a above).
+    > - **UX flow:**
+    >   - Trigger: "Export to PDF" button in the Dashboard header (right-hand cluster, next to the date-range picker).
+    >   - Modal: widget toggle list pre-populated with every widget the user has currently visible on their Dashboard + the option to add hidden ones for this export. Each toggle row shows a thumbnail/preview of the widget for visual confirmation.
+    >   - Range: defaults to the Dashboard's current date range; can be overridden in the modal.
+    >   - Optional fields: report title, subtitle, custom subheader (e.g. "Q1 2026 board review"), optional commentary text block at the top.
+    >   - Branding: auto-pulls port logo + primary colour + header/footer from `system_settings` (per CLAUDE.md branding section). No per-export branding override (matches the locked "don't duplicate branding everywhere" principle).
+    > - **Available widgets at export time** (any widget visible to the user on their Dashboard, gated by their permissions):
+    >   - KPI tiles (pipeline value, active deals, website analytics tile)
+    >   - Pipeline funnel
+    >   - Occupancy timeline
+    >   - Revenue breakdown REMOVED — already deleted in Bucket 1 #16 cleanup, exclude from export catalog too
+    >   - Source attribution / Lead source
+    >   - Berth demand / Hot deals
+    >   - Recent activity (capped at top N)
+    >   - Website analytics widgets (pageviews, sessions, visitors, top pages/countries) when Umami is configured
+    >   - Clients by country (when Bucket 3 #7 lands)
+    >   - World-map visitor heatmap (when Bucket 3 lands)
+    > - **Server-side rendering approach:** lean toward **`pdfme` templated rendering** (already used per CLAUDE.md, no headless-Chromium ops cost). Each widget gets a `WidgetExportTemplate` definition mapping its data to a pdfme schema fragment. Composed at export time based on which widgets the user toggled on. Falls back to a simple text-table rendering for widgets without a dedicated template (gives partial coverage on day 1, fancy charts shipped iteratively).
+    > - **Charts as PNG fallback** — pdfme can't render Recharts/ECharts components natively. Server-side: render each chosen widget to a PNG via a headless renderer (puppeteer or playwright running against the same chart components), then embed the PNG in the pdfme template. Pre-cache PNGs per widget per range to avoid regenerating on every export.
+    > - **Export-history table** (`exported_reports`): id, port_id, user_id, file_id, widgets_included, date_range_from, date_range_to, title, created_at. Reps can re-download past exports without regenerating.
+    > - **Effort:** ~10-14h end-to-end. ~3h for the dialog + widget toggles + modal. ~3-4h for the server-side composition + pdfme template fragments per widget. ~2-3h for chart-to-PNG rendering pipeline. ~1-2h for the export-history table + list UI. ~1-2h for the per-widget template definitions. Captured 2026-05-21 from UAT. **Cross-ref:** 3a (location decision); existing branding infra (per CLAUDE.md); chart-library migration to ECharts (Bucket 3 #00) — if that lands first, the PNG-rendering pipeline gets simpler (ECharts has a native server-side PNG export via canvas).
+    > - **SHIPPED (full 4-phase build) across 3b199c2, 47c2ba9, 1cdc2fd, 5a9b5f6:**
+    >   - **Stack decision:** dropped pdfme in favor of `@react-pdf/renderer` (already a dep). Rationale: React component model matches the codebase, server-side `renderToBuffer` slots into the existing `/api/v1/*` route pattern, no Chromium dep (smaller image, lower memory), built-in `<PDFViewer>` for the preview modal. Charts render as data tables here — printed reports prioritize the actual numbers over chart shapes, accessible to screen readers, holds up if OCR-scanned. Recharts-as-SVG embedding can be added later if needed; Puppeteer hybrid stays available as a fallback.
+    >   - **Phase A (3b199c2):** foundation. `BrandedReportDocument` page wrapper (logo + title + footer with port name + page numbers), `makeReportStyles(branding)` keyed off the port's primary color with a luminance check for the accent foreground (AA contrast on dark brands). `DashboardReport` with KPI grid + per-widget tables (KPI overview / pipeline funnel / berth status / source conversion / hot deals). Server-side data fetchers via the existing `dashboard.service.ts` — only the selected widget IDs trigger their fetch. `POST /api/v1/reports/generate` with zod-validated discriminated-union schema, `reports.export` perm gate, audit log on success, RFC 5987 Content-Disposition for unicode filenames. UI: `<ExportDashboardPdfButton>` on the Dashboard header. 3 unit tests prove the renderer emits `%PDF-` bytes.
+    >   - **Phase B (47c2ba9):** clients / berths / interests list reports. Shared `<ReportTable>` zebra-striped primitive with no-break rows. Three data resolvers (`resolveClientReportData`/`resolveBerthReportData`/`resolveInterestReportData`) in `src/lib/services/list-report-data.service.ts` with primary-email/phone subqueries for clients, primary-berth left-join for interests, all capped at 1000 rows with "Showing top N of <total>" notice. Route schema widened to 4-arm discriminated union with exhaustiveness `_exhaustive: never` check. `<ExportListPdfButton>` reusable component wired into ClientList / BerthList / InterestList toolbars. 3 more render tests.
+    >   - **Phase C (1cdc2fd):** saved templates. Migration `0079_report_templates.sql` + drizzle schema with sibling-name uniqueness scoped `(port_id, kind, LOWER(name))`. CRUD service + REST routes (`GET/POST /api/v1/reports/templates`, `GET/PATCH/DELETE /api/v1/reports/templates/[id]`) with `reports.export` perm + audit. `<SavedTemplatesPicker>` reusable component wired into both export dialogs — apply a template hydrates the form (widget selection / filters / title); save-as-template inline expands to a name input.
+    >   - **Phase D (5a9b5f6):** preview modal. `<PdfPreviewModal>` POSTs the current form payload, renders the returned Blob in a sandboxed iframe via `URL.createObjectURL`, caches the Blob so the Download button doesn't re-fetch. Re-fetches when the rep tweaks config and re-opens preview. Object URL revoked on close + unmount. Eye button between Cancel and Download on both dialogs. Memoised previewPayload prevents unrelated re-renders from refiring the fetch.
+    >   - **Final shape:** 4 report kinds, per-port logo + primary-color branding, customizable widget picker (dashboard) + include-archived toggle (lists), custom title, save-as-template, apply saved template, preview modal with cached Blob for download, 1000-row export cap, `reports.export` perm, audit-logged, RFC 5987 unicode filenames. **1454/1454 vitest pass; 6 PDF render tests included.** Manual end-to-end (open dashboard → preview → download) is the next gate.
+5.  **Web analytics integration (companion to #3)** — _new feature_ — per-port web analytics provider config in admin (GA4 / Plausible / Umami / Cloudflare), surfaced as widgets on the dashboard and ingestable into the branded PDF report. Needs: settings UI, provider adapter layer (`src/lib/integrations/analytics/`), dashboard widgets, and inclusion in the report exporter. ~8–12 h.
+6.  **SHIPPED in 94c24a1 (H33):** Supplemental-info-request email rebuilt to use the shared branded shell (logo + blurred overhead background + max-width 600 table layout) instead of prior plain-HTML page. Per-port branding (logo / primary color / background / header / footer) flows from `getPortBrandingConfig`; CTA button picks up port's primary color. Supplemental-info-request email: branded HTML styling — _src/lib/email/templates/_ — the email is plain HTML (logo missing, no header card, no blurred background), inconsistent with the other branded transactional emails (portal activation / reset / login wrap content in a `BrandedAuthShell`-equivalent HTML layout per CLAUDE.md). Rebuild the template to match the table-based, max-width 600, logo + blurred overhead background look, pulling port branding from `system_settings`. ~1-2 h.
+7.  **SHIPPED in 989cc4d (I35):** New ResidentialInterestCard + getResidentialInterestColumns + residentialInterestFilterDefinitions; list page drives DataTable + FilterBar + ColumnPicker + SavedViewsDropdown + bulkActions. List endpoint validator widened (pipelineStage as string OR string[], added source filter). Service post-fetches client names via single IN-list lookup so column 1 renders fullName without N+1. New /api/v1/residential/interests/bulk supports change*stage + archive (100-id cap). Kanban view deferred. Residential interests list: visual + functional parity with the main InterestList — \_src/components/residential/residential-interests-list.tsx* vs _src/components/interests/interest-list.tsx_ + _interest-card.tsx_ + _interest-columns.tsx_ + _interest-filters.tsx_ — the residential interests page today is a slim search + stage-filter list (~200 lines). The main InterestList (~700 lines + supporting files) carries the bulk of the product idiom: card / table / kanban view modes (kanban is desktop-only), `usePaginatedQuery` with sort + saved views, full `FilterBar` (search, stage, tags, owner, source, date ranges), `ColumnPicker` for table mode, bulk actions wired to `/interests/bulk` (archive, change stage, add/remove tag), realtime invalidation across multiple event names, per-row archive flow, kebab actions, `InterestCard` rich row component. Reps switching between berth interests and residential interests today get two visually-divergent experiences for what is effectively the same conceptual surface.
+    >     - **Scope breakdown:**
+    >         - **(a) Card view + visual parity (highest leverage)** — replace the table-style `<li>`-per-row layout with a `ResidentialInterestCard` mirroring `InterestCard` (header with client name + stage chip + last-activity, body with preferences/notes preview, footer with quick actions). Reuse the existing `<DataTable />` primitive for the table mode so column picker + sort + bulk-select come for free. ~3-4h.
+    >         - **(b) Export to PDF + CSV** — match the export affordance the main page has (or, if the main page lacks it, add it to both surfaces in the same pass — captured here so it lands on both). PDF: render rows + summary header via `pdfme` / `pdf-lib` (existing infra per CLAUDE.md), branded with port logo. CSV: server-side endpoint `/api/v1/residential/interests/export?format=csv|pdf` (or client-side generation if the dataset is bounded — residential volumes are typically small). Trigger from a kebab menu on the page header. ~2h.
+    >         - **(c) Filter / sort / pagination parity** — extend the residential interests endpoint to accept the same `FilterDefinition` shape (stage, source, assignee, date range, tags) and wire `usePaginatedQuery` + `FilterBar` on the page. ~2-3h.
+    >         - **(d) Bulk actions + saved views** — only if residential workflows actually use them (verify with the external partner team first — residential volumes may be low enough that bulk-mutate is unused). ~2h if needed, skip if not.
+    >     - **Refactor opportunity:** much of the InterestList scaffolding is generic — there's a latent opportunity to extract an `EntityList<T>` primitive that takes `{ endpoint, columns, cardComponent, filterDefinitions, bulkActions }` and renders the whole shell. Both surfaces become thin configs. ~6-8h for the extraction + porting both lists, but pays off the next time a similar list ships (companies, yachts already have parallel lists that could adopt it). Out-of-scope for this finding; capture as a follow-up if appetite exists.
+    >     - **Recommendation:** ship (a) + (b) in one ~5-6h pass for the high-visibility wins (cards + export). Defer (c) until the residential team complains about filter gaps. Skip (d) unless verified-needed.
+    >     - **Companion fix:** see Bucket 1 finding "Residential namespace breadcrumb link is 404" — if the parity work lands a `/residential` landing page, that breadcrumb finding folds into this.
+    >     - Captured 2026-05-18 from UAT.
+8.  **SHIPPED in 989cc4d (I36):** New registry entry `residential_partner_recipients` (comma-separated) under section `residential.partner`. `createResidentialInterest` fires `forwardResidentialInquiryToPartner` after the row lands. Helper uses the same branded shell other transactional emails use. Failures log + never block create. /admin/residential-stages page picks up a registry-driven card so admins manage recipients alongside stages. Residential inquiry → auto-forward to external partner email(s) — _src/lib/services/residential.service.ts_ (`createResidentialInterest`), _src/app/api/public/residential-inquiries/route.ts:97_ (public intake), _src/lib/services/settings.service.ts_ + admin settings UI, _src/lib/email/templates/_ (new template), BullMQ enqueue — residential clients are managed by an external partner; every new residential inquiry needs to be forwarded automatically to one or more configured email addresses so the partner can act on it.
+    >     - **Settings model:** new per-port `system_settings` keys: `residential_forward_enabled` (bool, default false), `residential_forward_recipients` (JSON array of email addresses — `to`), `residential_forward_cc` (JSON array, optional), `residential_forward_filter` (optional discriminator — e.g. only forward inquiries with certain `source` values or above a price/size threshold; v1 ships without this and forwards everything).
+    >     - **Admin UI:** new section in `src/app/(dashboard)/[portSlug]/admin/settings/` ("Residential routing") with: enable toggle, recipient list editor (add/remove emails, drag-reorder, per-row "primary" flag for the To field vs CC), template preview ("Send sample to me"), and a small "Last forwarded N inquiries in the past 7 days" stat for confidence. Permission-gated by `admin.manage_settings`.
+    >     - **Email template:** new branded HTML template `residential-inquiry-forwarded.tsx` in `src/lib/email/templates/` matching the existing branded-shell idiom (port logo + table-based layout per CLAUDE.md) — body includes inquiry fields (client name, contact channel, preferences, notes, source, submission timestamp, link to the residential interest in the CRM if the partner has portal access; otherwise a "view in CRM" stub).
+    >     - **Send pipeline:** enqueue a BullMQ job in `createResidentialInterest` (don't send inline — keeps public intake fast + retries handle SMTP flakes). Job: render template with port branding + inquiry payload, send via existing nodemailer transport, audit a `document_sends` row per recipient for forensics. Honour the dev-only `EMAIL_REDIRECT_TO` envar (per CLAUDE.md) so QA doesn't spam the real partners.
+    >     - **Edge cases:** retry on SMTP failure (BullMQ default retry policy); de-dup if the same inquiry triggers create twice within the dedup window (already a residential-intake concern — verify); skip forwarding when forwarding is disabled mid-flight (settings read at job time, not enqueue time, so toggle takes effect immediately).
+    >     - **Effort:** ~3-4h for settings + template + service hook + BullMQ wiring; +1h for admin UI + sample-send button. Captured 2026-05-18 from UAT.
+    >
+    > - **Related:** see Feature 6 below — auto-link residential to existing main-client records, which fires at the same moment in the create pipeline; build (5) and (6) in one pass so the forwarded email can carry the "matched to existing CRM client X" context if a link was found.
+9.  **SHIPPED in 989cc4d (I37):** Migration 0080 adds `residential_clients.linked_client_id` (nullable FK, SET NULL on cascade) + partial index. New `findAndLinkMatchingMainClient` service matches by email first (case-insensitive client*contacts lookup) then by E.164 phone; first exact match wins. Fires fire-and-forget from `createResidentialClient`. Header surfaces link via "Linked to main client" chip. Backfill script + reverse-direction link from main ClientDetailHeader stay as follow-ups. Auto-link residential interests to existing main-client records (same person) — \_src/lib/services/residential.service.ts* (`createResidentialClient` + `createResidentialInterest`), _src/app/api/public/residential-inquiries/route.ts_, new schema migration adding _src/lib/db/schema/residential.ts_ join table, _src/components/residential/residential-client-detail-header.tsx_ + _src/components/clients/client-detail-header.tsx_ (surface the link on both sides), new admin/dev script for backfill — when the same person who exists in the main berth client list registers a residential interest (or vice-versa), the two records should auto-link so reps can see the full relationship at a glance.
+    >     - **Why a link, not a merge:** the two pipelines are operationally distinct (different team handles residential, different lifecycle stages, different downstream services). A hard merge would conflate records that should remain queryable separately. A symbolic link preserves both records while making the relationship discoverable.
+    >     - **Schema:** new join table `residential_client_links (id, port_id, residential_client_id, client_id, linked_at, linked_by_user_id, link_method enum('auto_email_match' | 'auto_phone_match' | 'manual'), confidence numeric(3,2), notes text)` — composite unique on `(port_id, residential_client_id, client_id)` so the same pair can't be linked twice. Both FKs ON DELETE CASCADE so dropping either side cleans the link automatically.
+    >     - **Match logic** (at residential client/interest create time): normalize the residential `email` to lowercase and check against `client_contacts.value` WHERE `channel='email'`; normalize `phoneE164` and check against `client_contacts.valueE164` WHERE `channel='phone'`. Email match → confidence 0.95 (auto-link, log audit); phone match → confidence 0.80 (auto-link with a "candidate match" badge so the rep can confirm); both match → confidence 0.99. If multiple candidate main-clients match (shared email — family/spouse case), DO NOT auto-link; instead surface all candidates in a UI banner for the rep to pick. Same logic runs in reverse when a new main-client is created (look for matching residential client).
+    >     - **UI surface:** on residential client detail header — small "Linked to <Main client name>" pill below the name, click-through to the main client; if a candidate match was surfaced but not auto-linked, a banner: "Possible match: <Name> (same email/phone). [Link] [Dismiss]". Mirror on the main client header. Add a "Link to existing residential client" / "Link to existing main client" button on each side for manual link creation (combobox-search across the other side). Add an "Unlink" affordance with confirm — useful when an auto-match was wrong (e.g. shared family email).
+    >     - **Audit + telemetry:** every auto-link writes an `audit_logs` row with `action='auto_linked'`, `metadata={method, confidence}` so the org can audit auto-link accuracy. Optional admin dashboard tile showing "N residential links auto-created / manually overridden this week" for ongoing confidence in the match logic.
+    >     - **Backfill script:** `pnpm tsx scripts/backfill-residential-links.ts` — one-pass scan of existing residential_clients vs clients for matching email/phoneE164; idempotent (skips pairs already linked); dry-run by default, `--apply` to commit. Required because the join table is new and existing records won't be auto-linked retroactively.
+    >     - **Effort:** ~4-6h end-to-end (migration + service hook with match logic + UI on both header sides + backfill script + tests + audit). Significant scope but high-leverage: gives reps a single mental model of "this person across our two product lines" instead of two parallel records. Captured 2026-05-18 from UAT.
+
+- **World-map heatmap of Umami visitor origins** — _new file_ `src/components/website-analytics/visitor-world-map.tsx` (heatmap card) + extend _src/lib/services/umami.service.ts_ (already returns `top-country` data via `getMetric(type: 'country')`) + viz lib choice (e.g. `react-simple-maps` + Natural Earth TopoJSON, or `@visx/geo`, or a simple SVG world from D3) — render a world choropleth colour-scaled by visitor count per country, surfaced on the Website Analytics page (and optionally on the dashboard as a separate rail widget). Hover any country to see the visitor count tooltip; click to filter the page's other widgets to that country (uses Umami `filters` query param if we extend the route to support it). Implementation notes: ISO 3166-1 alpha-2 codes map cleanly to country features in Natural Earth; cache the topojson in `public/` to avoid per-load fetch. Bundle weight ~50-80KB gzipped depending on lib choice; dynamic-import to keep it off the dashboard bundle when the widget is collapsed. ~4-6h end-to-end. Companion / overlap candidate: the "Clients by country" widget below — a single map could surface both data sources via a toggle (Umami visitors vs CRM clients/prospects) instead of two separate widgets. Captured 2026-05-18 from UAT.
+
+7.  **SHIPPED in a147cbc (N45):** New GET /api/v1/dashboard/clients-by-country groups non-archived clients by nationality*iso. `<ClientsByCountryWidget>` renders compact ranked list with mini-bars; rows link to /clients?nationality=<ISO>. Registered as default-visible rail. **"Clients by country" dashboard widget** — \_src/components/dashboard/* (new file `clients-by-country-widget.tsx`), _src/components/dashboard/widget-registry.tsx_, _src/lib/services/dashboard.service.ts_ (or `analytics.service.ts` if it should live in the snapshot-cached family), _new endpoint or extension to `/api/v1/dashboard/...`_ — surface a per-country breakdown of clients (and optionally prospects — interests with `outcome` still open) so leadership can see geographic distribution at a glance. Data shape: aggregate `client_addresses` (or `clients.country` if that column exists) by `country_code` for clients that are non-archived and (for the prospect overlay) join through interests-with-open-outcome. UI options to pick from at build time: (a) compact ranked list with mini bars per row (matches `BerthHeatWidget` / `HotDealsCard` idiom — fits the rail), or (b) a choropleth/world-map (heavier; needs a viz lib like `react-simple-maps` + a topojson; better fit for the chart grid). Pick (a) by default — same footprint as existing rail tiles, no new bundle weight, and clicking a country could deep-link `/clients?country=DE`. Permissioning: gate on `clients.view`. Registry: defaultVisible: true. Effort: ~2-3 h for variant (a) + endpoint + tests; ~6-8 h for variant (b) with a real map. Captured 2026-05-18 from UAT (user request: "add a widget that breaks down prospects/clients by country as a card on the dashboard").
+8.  **SHIPPED in a147cbc (N46):** New `preferences.dashboardWidgetOrder?: string[]` on user*profiles; `useDashboardWidgets` sorts visibleWidgets by order (unlisted ids fall through to registry order) and exposes `setOrder(nextOrder)` that PATCHes optimistically. DashboardShell wires @dnd-kit/core + sortable: Rearrange toggle turns on per-widget grip handles + sortable-context wraps each group (charts / rails / feed) so drops stay in-group. PointerSensor 8px activation distance, KeyboardSensor for a11y. **Drag-and-drop rearrangable dashboard widgets** — \_src/components/dashboard/dashboard-shell.tsx*, _src/components/dashboard/widget-registry.tsx_, _src/hooks/use-dashboard-widgets.ts_ (assumed name), _src/lib/db/schema/users.ts_ (`user_profiles.preferences`), _src/app/api/v1/me/preferences/route.ts_ — today widget order is hard-coded by registry array order, and visibility is the only user-controllable axis (persisted in `user_profiles.preferences.dashboardWidgets` as a `{ [id]: boolean }` map). Reps want to choose **which analytics show where** on their dashboard (e.g. push Pipeline Funnel to the top, demote Berth Status, swap rail order). Approach: (a) introduce a parallel `dashboardWidgetOrder: string[]` preference (ordered list of widget IDs; missing IDs render after the list in registry order so newly-added widgets always surface); (b) extend `useDashboardWidgets` to return `visibleWidgets` already sorted by this order; (c) keep the three-group layout (`chart` / `rail` / `feed`) — drag-reorder is scoped _within_ a group so the rail's narrower min-col doesn't get a chart-sized tile dropped into it (and vice versa) — moving a widget between groups stays a registry-level concern (the move-out-of-rail request that triggered this entry is an example); (d) add `@dnd-kit/core` + `@dnd-kit/sortable` (lightweight, RSC-safe, already shadcn-adjacent); (e) wrap each group's grid in a `SortableContext`, render a small grip handle on each card header that's only visible in "rearrange mode" (toggle in the existing Customize dropdown — keeps casual users from accidentally grabbing tiles); (f) on drop, optimistic-update the preference and PATCH `/api/v1/me/preferences` with the new order array; (g) realtime: not needed (per-user state). Tests: vitest for the order-merge helper, Playwright smoke for drag-drop + persistence across reload. ~4-6 h end-to-end. Captured 2026-05-18 from UAT after moving the Pipeline Value tile from rail → chart group exposed that re-shuffling widgets is currently a code change, not a user action.
+9.  **AI-assisted action extraction from contact-log entries** — _src/components/interests/interest-contact-log-tab.tsx_, new LLM service — current dialog already has quick-template buttons that seed `"Called the client. Discussed:\n\n• \n\nNext step: "` (and similar for in-person / email) into the summary textarea — soft structure without enforcement. Adding rigid form fields ("Topic", "Next step", "Outcome") risks killing rep adoption (sales reps notoriously avoid form-y CRMs). Better path: keep the freeform textarea + templates exactly as-is, add an **"Extract action items"** button beside Save that LLM-parses the body and returns proposed follow-ups — `create reminder for {datetime}`, `update desiredLengthFt to {n}`, `suggest stage advance to deposit_paid`, etc. Each proposal lands as a confirm-each list; rep approves individually. **AI assists, rep approves** — never silently mutates the record. Scope: ~6-10 h end-to-end (prompt engineering + LLM client + extraction schema + per-action confirm UI + audit logging of accepted/rejected proposals). Privacy considerations: contact-log entries can contain PII / financial details — route through an in-region LLM provider per the existing email/storage approach. Defer until a user is genuinely asking for it; the current template-seed pattern is fine for now.
+10. **SHIPPED (list endpoint + admin route) in aa1f5d2 (R62):** New `listTemplates(portId)` in documenso-client paginates every visible template on configured instance (5-page cap at 100/page = 500 templates). Handles v1 + v2 endpoint shapes; normalises to `{ id, name }`. New GET /api/v1/admin/documenso/templates route exposes list (gated on `admin.manage_settings`). Field-mapping editor + sync-now button + per-template badges stay as picker-UI follow-up. **Documenso-first templates: pull templates from Documenso instead of uploading through CRM (admin UI gap)** — _src/components/admin/document-templates/template-form.tsx_ (template create/edit UI, currently uploads source PDF/HTML), _src/lib/db/schema/documents.ts:254_ (`documensoTemplateId` column already exists), _src/lib/services/document-templates.ts:611_ (`pathway: 'documenso-template'` already routes through Documenso), _src/lib/services/documenso-template-sync.service.ts_ (existing per-port EOI sync; needs generalization), _src/lib/services/documenso-client.ts_ (need a `listTemplates()` wrapper) — the schema and signing pathway support Documenso-hosted templates (the CRM stores only the Documenso template ID, Documenso owns rendering), but the admin UI today assumes the source PDF/HTML lives in the CRM. Reps who maintain their templates in Documenso can wire ONE per port (the EOI, via the existing per-port sync) but can't add other types (welcome letter, handover checklist, correspondence) as Documenso-hosted entries without DB-level intervention. Real product gap — closes the "is Documenso the source of truth, or is the CRM?" question for ports that prefer to author in Documenso.
+    >     - **Scope:**
+    >         - **(a) Template-source toggle** in `template-form.tsx`: radio between "Upload to CRM" (current behaviour) and "Pull from Documenso". Selecting the latter changes the form below.
+    >         - **(b) Documenso template picker** — new combobox that calls a new `GET /api/v1/admin/documenso/templates` endpoint backed by `listTemplates()` (new wrapper in `documenso-client.ts` — v1: `GET /api/v1/templates`; v2: `GET /api/v2/envelope/template`). Lists Documenso-side templates by name + id; selecting one populates `documensoTemplateId` and `templateFormat='documenso_render'`. Cache the list for ~5 minutes per port.
+    >         - **(c) Per-template field-mapping editor** — once a Documenso template is picked, show its field labels (pulled via `getTemplate(id)` — already exists in the sync service) alongside a select-from-merge-tokens dropdown per row. Save the mapping into the `fieldMapping` JSONB column (currently used for AcroForm; reuse the shape: `{ documensoFieldLabel: mergeToken }`). Validate against `VALID_MERGE_TOKENS` on save so the field map can't reference a non-existent CRM token.
+    >         - **(d) "Sync now" button** — re-fetch the Documenso template, diff field labels against the saved `fieldMapping`, surface added / renamed / removed fields so the admin can update the mapping when the Documenso template changes. Generalizes the existing per-port EOI sync (`documenso-template-sync.service.ts`) to per-template.
+    >         - **(e) Template-list page treatment** — each template row in the list shows a small badge "Hosted in Documenso" vs "CRM-managed source" so admins can tell at a glance which is which.
+    >         - **(f) `generateAndSign` already handles this** — `pathway: 'documenso-template'` skips CRM PDF generation and calls Documenso's template-generate endpoint. No service-layer work needed beyond the new admin UI plumbing.
+    >     - **Migration consideration:** the existing per-port EOI sync (single Documenso template ID stored in port settings) becomes redundant once per-template mapping ships — migrate the per-port pointer into a row in `document_templates` with `templateFormat='documenso_render'` + the existing `templateType='eoi'`. Then deprecate the port-setting key. Single-port-EOI flow continues to work via the same templateType lookup; admins gain the ability to add additional Documenso-hosted templates (welcome letter, etc.) using the same UI.
+    >     - **Webhook + auto-file integration:** untouched — signing webhooks (`DOCUMENT_SIGNED`, `DOCUMENT_COMPLETED`, etc.) key on document/envelope ID, not template source, so Documenso-first templates inherit the same signing-status tracking + auto-deposit into the entity folder.
+    >     - **Effort:** ~5-7h end-to-end (toggle + picker + listTemplates wrapper + field-mapping UI + sync button + list-row badge + migration of the per-port EOI pointer + tests). Smaller (~3-4h) if (d) sync button is deferred. Captured 2026-05-18 from UAT in answer to "what happens if we upload templates straight to Documenso? Can we pull the template through?" — answer: yes, but only the EOI flows through today; this finding closes the UI gap for the other template types.
+
+- **[Deferred — blocked on embeddings-based recommender] Berth recommender AI admin section on `/admin/ai`** — _src/app/(dashboard)/[portSlug]/admin/ai/page.tsx_ + _src/lib/services/berth-recommender.service.ts_ — the berth recommender is currently pure SQL (per CLAUDE.md: "Rule-based today; future versions will optionally use embeddings for soft preference matching"). When/if the embeddings-based version ships, surface its admin controls on `/admin/ai` alongside the other AI-feature sections: provider override, embedding model, similarity threshold, per-call budget cap. Until then, the recommender does not call an LLM — including it under `/admin/ai` today would mislead admins into thinking they're tuning an LLM. **Action: revisit when an AI/embeddings tier is added to the recommender.** Cross-ref: parent finding "Consolidate every AI-feature admin control onto /admin/ai" in Bucket 2. Captured 2026-05-18 from UAT.
+- **[Deferred — depends on Bucket 3 #7 contact-log action extraction] Contact-log AI admin section on `/admin/ai`** — when "AI-assisted action extraction from contact-log entries" (Bucket 3 #7) ships, add its admin controls to `/admin/ai`: provider override, prompt-template editor, per-call budget cap, accepted/rejected proposal stats. Cross-ref: parent finding "Consolidate every AI-feature admin control onto /admin/ai" in Bucket 2 + Bucket 3 #7 "AI-assisted action extraction from contact-log entries". Captured 2026-05-18 from UAT.
+- **[Deferred — no design exists] AI inquiry-intake parsing admin section on `/admin/ai`** — if/when AI-assisted inquiry intake parsing is built (e.g. LLM normalizes inbound web-form / email inquiries into structured fields before the rep sees them), surface its admin controls on `/admin/ai`: provider override, confidence threshold for auto-accept vs human-review, fallback behaviour when the AI tier fails, per-call budget cap. No design or scope exists for this feature today — captured as a placeholder so the thought isn't lost when the AI-feature page expands. Cross-ref: parent finding "Consolidate every AI-feature admin control onto /admin/ai" in Bucket 2. Captured 2026-05-18 from UAT.
+
+8. **SHIPPED (Documenso 401/403 path — foundation) in c14f80a (Q61):** `<PortDocumensoConfig>` gains `apiKeySource` + `apiUrlSource` ('port' | 'global' | 'env' | 'default' | 'none'). `getPortDocumensoConfig` populates them based on which layer of the resolver chain produced the value. documenso-client's `<ResolvedCreds>` exposes the source flags; the 401/403 branch surfaces them in `DOCUMENSO_AUTH_FAILURE` internalMessage so operators see "api key source: env, port: <id>" instead of generic `path → 401` body. Same pattern can extend to S3 / Redis / IMAP in follow-ups. **Platform-wide error message audit for prod debuggability** — _cross-cutting_ — triggered by the Documenso-config diagnosis loop: the user got a generic 502 + "Invalid token" upstream message when the real cause was "no Documenso creds entered for this port (silently fell back to a stale env value)." Operators in prod can't see logs the way we can in dev; the error surface should self-describe. Two layers of work:
+   - **(a) Pre-flight config-shape errors at known integration boundaries** — _src/lib/services/documenso-client.ts_, _src/lib/services/storage/\*_, _src/lib/email/_, _src/lib/services/imap-bounce-poller.ts_, IMAP, SMS providers, payment gateways, etc. — when a call would fail because admin/env config is empty or unparseable, raise a typed `CodedError` _before_ the network call with an operator-facing message like `"Documenso is not configured for {portName}. Open Admin → Documenso settings to enter the API key, or set DOCUMENSO_API_KEY in env."` Include the offending setting key + port name. The `documenso-client` `resolveCreds()` is the canonical example to template from — others (IMAP, S3, SMTP, Stripe etc.) should follow the same pattern.
+   - **(b) User-facing error-message audit** — _src/lib/errors.ts_, all `try/catch` blocks in `src/app/api/*`, all `toastError` consumers in `src/components/*` — scan for `errorResponse(err)` paths that return generic "Something went wrong" / status codes only, and enrich with: (i) the operation that failed ("EOI generation", "Send invoice", "Upload file"), (ii) the likely cause (config missing, permission denied, conflict, etc.), (iii) the next step (where to fix it). Especially important for setting-driven features (email send accounts, storage backends, Documenso config, webhook secrets) where the real cause is one config field off-screen. The error catalog in `src/lib/errors.ts` already supports `CodedError` with operator-friendly `userMessage` — most call sites just need to populate it.
+   - Total scope: probably a 1-2 day audit + remediation pass. Out-of-scope items to consider during the pass: a per-port "Integrations health" admin page that probes each external integration and shows green/red with the same diagnostic copy.
+
+---
+
+## Bucket 4 — Bugs (severity-tagged)
+
+_Functional defects. Tag each with `[critical|high|medium|low]` prefix._
+
+-1. **[high] BulkAddBerthsWizard side-pontoon dropdown uses a wrong, locally-defined enum (not the canonical / admin-editable vocabulary)** — _src/components/admin/bulk-add-berths-wizard.tsx:42_ — the wizard hard-codes `const SIDE_PONTOON_OPTIONS = ['Port', 'Starboard', 'Bow', 'Stern', '']` (nautical directions). The **actual** canonical list in _src/lib/constants.ts:187_ `BERTH_SIDE_PONTOON_OPTIONS` is: `'No', 'Quay SB', 'Quay PT', 'Quay SB, Yes PT', 'Quay PT, Yes SB', 'Yes SB', 'Yes PT', 'Yes SB, PT', 'Finger SB', 'Finger PT'` — these match the original NocoDB enum + the single-berth edit form + EOI/contract surfaces. Reps using the bulk wizard end up writing `side_pontoon='Port'` / `'Starboard'` etc. to the DB — values that no other surface in the app produces or filters on. Filtering / reporting / search across the same column gives misleading results because the data has two parallel vocabularies.
+
+>     - **Additional problem:** the codebase has a full per-port vocabularies system (_src/lib/vocabularies.ts_) where `berth_side_pontoon_options` is registered as admin-editable, with defaults sourced from `BERTH_SIDE_PONTOON_OPTIONS`. The wizard not only uses the wrong list — it bypasses the admin-editability entirely. Even after fixing the values, admins won't be able to tune the list per-port unless the wizard reads through `getVocabulary('berth_side_pontoon_options')` like other surfaces should.
+>     - **Fix:** (a) delete `SIDE_PONTOON_OPTIONS` at line 42. (b) Replace the two `SIDE_PONTOON_OPTIONS.filter(Boolean).map(...)` blocks (lines 264 + 334) with a call to the vocabulary hook — confirm the pattern used by `BerthForm` / single-berth edit (likely `useVocabulary('berth_side_pontoon_options')` or a server-component read). (c) Audit every other dropdown in the wizard for the same pattern: `BERTH_MOORING_TYPES`, `BERTH_CLEAT_TYPES`, `BERTH_BOLLARD_TYPES`, `BERTH_ACCESS_OPTIONS` are all registered as admin-editable vocabularies — verify the wizard reads through `getVocabulary` for all of them, not a local constant. (d) **Data backfill:** the four wrong values (`Port` / `Starboard` / `Bow` / `Stern`) may already be in production rows added via this wizard — write a one-off script to either remap them (`Port → Quay PT` or similar based on the port team's intent) or null them out + flag for manual review. Coordinate with the port team before running.
+>     - **Effort:** ~30min for the wizard fix + dropdown audit, ~30min for the backfill script + dry-run. Total ~1h plus a stakeholder check on the remap mapping. **Severity high** because (i) silently writing out-of-vocabulary data is a long-tail data-integrity problem and (ii) it shadows the existing admin-editability infra (operators may not realize the vocab is overridable for this field because the wizard ignores it). Captured 2026-05-18 from UAT.
+>     - **SHIPPED in 2d57417:** wizard now reads `useVocabulary('berth_side_pontoon_options')` instead of the wrong hard-coded enum; admin-editable per-port overrides honoured automatically. Data-backfill script + cross-vocab audit (mooring/cleat/bollard/access — none currently surfaced in the wizard but registered as editable) parked as follow-up.
+>
+> 0. **[high] All file downloads land with a blob-UUID filename + no extension** — _src/components/dashboard/chart-card.tsx:34_ (PNG/CSV exports), _src/app/(dashboard)/[portSlug]/expenses/page.tsx:95_ (CSV/XLSX export), _src/components/clients/client-files-tab.tsx:42_, _src/components/companies/company-files-tab.tsx:42_, _src/components/interests/interest-documents-tab.tsx:72_, _src/components/interests/interest-eoi-tab.tsx:597_, _src/components/admin/backup-admin-panel.tsx:90_ — 7 separate download sites share a near-identical anchor-click pattern that creates `<a download="<name>">`, calls `.click()`, and revokes the URL — but **the anchor is never appended to the document**, so Chromium-based browsers (Comet/Arc/Chrome) silently ignore the `download` attribute and fall back to using the blob URL's UUID for the filename (no extension). Captured UAT screenshot: dashboard chart "Download PNG" lands as `939c78df-48cc-466c-a22e-53e9dea69294` 35.5 KB instead of `<chart-name>.png`. Fix: extract a single `triggerBlobDownload(blob, filename)` helper into `src/lib/utils/download.ts` that (1) `document.body.appendChild(a)`, (2) `a.click()`, (3) `a.remove()`, (4) `URL.revokeObjectURL(url)` on a microtask/next-tick so Chrome has time to read the URL. Refactor all 7 call sites to import it; delete the local copies (and the chart-card-local `triggerBlobDownload` declared at chart-card.tsx:34). ~20-30 min including manual verification of each download surface. **Affects every file-export flow** — bumping severity to high. Captured 2026-05-18 from UAT. **SHIPPED in 2d57417:** added `src/lib/utils/download.ts` with `triggerBlobDownload(blob, filename)` (DOM-attached anchor + deferred URL revoke) + sibling `triggerUrlDownload(url, filename)` for presigned-URL paths; refactored all 7 call sites, dropped the chart-card-local copy.
+
+1. **SHIPPED in aa1f5d2 (T64):** Migration 0082 deduplicates any existing (port_id, mooring_number) collisions by archiving all but the canonical row (prefers price-bearing rows, then earliest-created; archived rows carry explicit `archive_reason`). Adds partial unique index `uniq_berths_port_mooring_active` on (port_id, mooring_number) WHERE archived_at IS NULL so archived moorings can be reissued but live duplicates can't be created in the first place. **[high] Duplicate row for berth E17 in port-nimara** — DB: two `berths` rows with `mooring_number='E17'`, both with `price=NULL`. The canonical mooring format is meant to be unique per port (see CLAUDE.md "Mooring number canonical format"). Surfaced by the dashboard tile via the new "berth price missing" chip but the root cause is missing/leaked unique constraint. Recommend: dedupe + add partial unique index on `(port_id, mooring_number) WHERE archived_at IS NULL`. Deferred per session call (warning-only UI ships now).
+2. **SHIPPED in aa1f5d2 (T65):** `changeInterestStage` now blocks any non-override transition into eoi / reservation / deposit_paid / contract when primary berth has no price (NULL or 0). Override path (sales-manager fix) stays open and records reason in audit log per existing override-reason gate. **[medium] Stage advance allowed without berth price** — Service-level: `changeInterestStage` lets an interest reach EOI/Reservation/Deposit Paid/Contract on a primary berth whose `price` is NULL. EOI doc generation downstream presumably renders blank/$0 for the quote field. Cross-port impact unknown. Recommend: add a `ValidationError("Berth price must be set before advancing past Qualified")` gate in `changeInterestStage` for stages eoi+. Deferred per session call.
+3. **[medium] Smart search renders duplicate React keys for `/admin/templates` — console warning + potential render glitch** — _src/lib/services/search-nav-catalog.ts:89-94 + 275-280_ + _src/components/search/command-search.tsx:587_. Two entries in the nav catalog both point at `/:portSlug/admin/templates` ("settings" category at line 89 with EOI/Documenso keywords, "admin" category at line 275 with PDF/email-template keywords). The search renderer keys rows by `navigation:${href}` → React fires the "Encountered two children with the same key" warning. Visible in console as `navigation:/port-nimara/admin/templates`. Behavior is unsupported — could cause omitted/duplicated rows.
+   - **Fix (layered):**
+     - **(a) Catalog dedupe:** merge the two entries — keep the "settings" one (line 89, matches surrounding /admin/branding + /admin/storage cluster), absorb the admin-version's keywords (`'pdf templates'`, `'email templates'`, `'merge fields'`, `'eoi template'`), delete the duplicate at line 275.
+     - **(b) Defensive render-side key:** even after dedupe, change command-search.tsx:587 to compose keys as `navigation:${href}:${category}` (or filter duplicates by href at catalog-load time). Protects against the same bug recurring when new nav entries land.
+   - **Audit:** grep the catalog for any other href that appears twice — likely candidates around /admin/email, /admin/users, /admin/settings if similar consolidations happened. Single dedupe sweep at the top of the catalog file.
+   - **Effort:** ~15 min. Captured 2026-05-21 from UAT console.
+   - **SHIPPED in 2d57417:** dedupe lives at the catalog-search layer (`searchNavCatalog` keeps the highest-scoring entry per href via a Map) so any future intentional cross-category re-entries are safe; the two `/admin/templates` rows were also merged into a single richer-keyword entry.
+4. **[medium] Overview "Latest note" teaser is stale after creating a note in the Notes tab (no cross-query invalidation)** — _src/components/shared/notes-list.tsx:164-184_ (create/update/delete mutations) + _src/components/interests/interest-tabs.tsx:1083-1104_ (teaser reads `interest.recentNote` + `interest.notesCount` from the parent interest detail object). The notes-list mutations invalidate `[entityType, entityId, 'notes', 'own' | 'aggregated']` but not the parent `['interests', interestId]` query that hydrates `recentNote` / `notesCount`. Net effect: rep adds a note in the Notes tab → switches to Overview → teaser still shows the previous note + the old count until a hard refresh. Same gap presumably affects Client / Company / Yacht detail Overviews if they have similar embedded latest-note teasers.
+   - **Fix:** add an optional `parentInvalidateKey?: QueryKey` prop to `NotesList`; on each mutation's `onSuccess`, invalidate it alongside the notes query key. The interest tab passes `['interests', interestId]`; the client/company/yacht tabs pass their equivalent. Belt-and-braces: also invalidate inside the parent entity's note-related mutations if any exist directly.
+   - **Effort:** ~20-30 min (prop + 4 call sites + a vitest covering the invalidation chain). Captured 2026-05-21 from UAT.
+   - **SHIPPED in 2d57417:** `NotesList` now takes `parentInvalidateKey?: QueryKey`; wired through 5 callers (interests, clients, yachts, companies, residential_clients, residential_interests). Create / update / delete mutations invalidate the parent detail query alongside the notes query key.
+5. **[high] InterestDocumentsTab uploads land with `client_id=NULL` — invisible in Attachments + no client subfolder auto-created** — _src/components/interests/interest-documents-tab.tsx:141-147_ (caller passes `entityType="client"` + `entityId={clientId}` but NOT `clientId` separately) + _src/components/files/file-upload-zone.tsx:63_ (only appends `clientId` to the form body when given as a prop) + _src/lib/services/files.ts:85-101_ (`uploadFile` reads `data.clientId ?? null` literally — does not derive it from `entityType==='client' + entityId`). Net effect: upload POST hits `/api/v1/files/upload` with `entityType=client&entityId=<UUID>` but no `clientId` form field, so the `files` row lands with `client_id = NULL`. Cascading bugs: (a) the Documents tab's "Attachments" list (`GET /api/v1/files?clientId=<UUID>`, filters on `eq(files.clientId, clientId)`) returns empty — file vanishes from the interest's Documents tab; (b) Documents Hub auto-deposit can't `ensureEntityFolder` for the client (it walks `files.clientId`), so the `Clients/<client-name>/` subfolder under the system root is never created — file lives at root in "All documents" but isn't filed by entity. The file IS reachable via the port-wide "All documents" view because that query has no clientId filter.
+   - **Fix (recommended at service layer — durable):** in `src/lib/services/files.ts:uploadFile`, when `data.entityType==='client'` AND `data.clientId` is not set, default `data.clientId = data.entityId`. Same for `entityType==='company'` → `companyId`, `entityType==='yacht'` → `yachtId`. Catches any other caller making the same mistake. Plus `ensureEntityFolder` should fire on every upload that lands with an entity FK, not only when explicit clientId was provided.
+   - **Caller fix (belt + braces):** pass `clientId={interest.clientId}` alongside `entityType` + `entityId` in interest-documents-tab.tsx:141-147. Audit other FileUploadZone call-sites for the same pattern (client-files-tab, yacht-files-tab, company-files-tab).
+   - **Backfill needed:** existing rows uploaded via this path have `client_id=NULL` despite having `entity_type='client'` + `entity_id=<UUID>`. One-off script to backfill `client_id` from `entity_id` where entity_type='client' AND client_id IS NULL; same for company/yacht. Then re-run `ensureEntityFolder` for affected rows so the Documents Hub tree catches up.
+   - **Effort:** ~30 min for service-layer fix + caller audit + backfill script. **High severity** — affects every interest-tab upload on the platform, breaks the Documents Hub filing model for those files. Captured 2026-05-21 from UAT.
+   - **SHIPPED (service layer + caller) in 2d57417:** `uploadFile` in `src/lib/services/files.ts` now derives `clientId/companyId/yachtId` from `(entityType, entityId)` when the explicit FK isn't passed. Interest-documents-tab also passes `clientId={interest.clientId}` belt-and-braces. **Backfill script + nested-folder migration remain outstanding** — those bundle with the larger Bucket 4 #6 "nested document subfolders" feature in PR Batch 4.
+6. **[medium] External EOI upload — 3 linked bugs: lying toast + broken View button + UUID-named download** — _src/components/interests/external-eoi-upload-dialog.tsx:60_ + _src/components/interests/interest-eoi-tab.tsx:589-605 (`SignedPdfActions`)_ + _src/app/api/v1/files/[id]/download/route.ts_ + _src/lib/services/files.ts (`getDownloadUrl`)_. Surfaced together during UAT 2026-05-21 of the backfill flow.
+   - **(a) Toast lies about stage advance** — server (`external-eoi.service.ts:142-160`) only advances stage when current is `open|details_sent|in_communication|eoi_sent`; at Reservation+ it correctly leaves the stage alone. But the client toast hardcodes `"External EOI uploaded — interest advanced to EOI Signed"` regardless of what the server did. **Fix:** have `uploadExternallySignedEoi` return `{ stageChanged: boolean, newStage?: PipelineStage }`; client toasts conditionally: stageChanged → "External EOI uploaded — stage advanced to EOI Signed"; else → "External EOI uploaded — filed against this deal (stage unchanged)". ~20 min.
+   - **(b) "View" button downloads instead of previewing in-app** — `SignedPdfActions.open('view')` opens the presigned URL via `window.open`. Browser behavior depends on `Content-Disposition` header from MinIO/S3 — defaulting to `attachment` triggers download every time. **Fix:** swap `window.open` for the existing `FilePreviewDialog` component (already supports PDFs + images per `file-preview-dialog.tsx:60-61`). Lift a `[previewFile, setPreviewFile]` state to the parent EOI tab and render `<FilePreviewDialog open={!!previewFile} fileId={previewFile?.id} ... />` once. SignedPdfActions's View button just sets the preview state. Pairs with the platform-wide "preview-everything" Bucket 3 feature so the same inline-preview surface gets full file-type coverage. ~30 min.
+   - **(c) Download filename is the storage-key UUID** — same root cause: `Content-Disposition` doesn't include a filename, so the browser uses the URL's last path segment (the UUID per `generateStorageKey`). **Fix:** generate the presign in `getDownloadUrl` with `response-content-disposition: attachment; filename="<files.filename>"` (S3/MinIO presign param). Honors the original filename stored in `files.filename`. ~15 min including a sweep of other download call sites — `client-files-tab.tsx`, `company-files-tab.tsx`, `interest-documents-tab.tsx`, `interest-eoi-tab.tsx` all hit the same endpoint. Consider also adding a sibling `response-content-disposition: inline` mode (e.g. `GET /api/v1/files/[id]/download?disposition=inline`) for the cases where we DO want native browser preview as a fallback to FilePreviewDialog.
+   - **(d) [high] Server discards `dateEoiSigned` + `eoiStatus` when stage is past EOI — skip-ahead banner falsely persists** — _src/lib/services/external-eoi.service.ts:142-160_ — when current stage is past `eoi_sent` (e.g. `reservation`, `deposit_paid`, `contract_*`), the `else` branch (lines 157-160) only updates `updatedAt`, ignoring the `signedAt` from the form. So even though the user uploaded an externally-signed EOI with a valid date, `interests.dateEoiSigned` stays NULL → the SkipAheadBanner keeps demanding the rep backfill the EOI signed date with no way to satisfy it.
+     - **Fix:** split the two concerns. Document metadata (dateEoiSigned + eoiStatus='signed') should ALWAYS be written from the upload — only the pipelineStage advance is gated:
+       ```ts
+       const shouldAdvanceStage = ['open', 'details_sent', 'in_communication', 'eoi_sent'].includes(
+         interest.pipelineStage,
+       );
+       await tx
+         .update(interests)
+         .set({
+           dateEoiSigned: interest.dateEoiSigned ?? input.signedAt ?? new Date(),
+           eoiStatus: 'signed',
+           pipelineStage: shouldAdvanceStage ? 'eoi_signed' : interest.pipelineStage,
+           updatedAt: new Date(),
+         })
+         .where(eq(interests.id, interestId));
+       ```
+     - **Also audit:** `interest-rules-engine` / `evaluateRule('eoi_signed', ...)` should fire on this path too (a manually-uploaded external EOI is still an EOI-signed event for the rules engine — berth-rules like "auto-mark berth Under Offer" depend on it).
+     - ~30-45 min including the audit + integration test.
+   - **(e) [medium] No edit affordance for uploaded-EOI metadata post-upload (signedAt / signerNames / notes / title locked)** — the EOI tab's history list at `interest-eoi-tab.tsx` shows uploaded documents but exposes no edit button. Once a rep uploads with a typo in signerNames or the wrong signedAt date, they can't correct it — they'd have to delete and re-upload (losing the audit log link).
+     - **Fix:** add an "Edit metadata" icon-button next to View / Download on each external-EOI row in the EOI tab. Opens a small dialog with the same fields the upload dialog has (signedAt, signerNames, notes, title), pre-filled. Submit PATCHes the document's metadata JSONB + the interest's `dateEoiSigned` (when changed) in one transaction. Audit-log the change with old→new diff.
+     - Permission gate: `documents.edit_metadata` or reuse `documents.upload_signed` (the same permission that allowed the upload).
+     - Side concern: the same edit affordance probably belongs on signed Reservations and signed Contracts too — but those are typically Documenso-bound (signedAt is webhook-attested), so editing should be more restricted there. For external EOIs the rep is the source of truth for signedAt anyway, so editing is safe.
+     - ~1-1.5h including dialog component + service PATCH + audit log + permission gate.
+   - **Effort:** ~3-4h total for all five sub-issues (was 1-1.5h before (d) + (e) landed). Captured 2026-05-21 from UAT.
+   - **SHIPPED (a) + (b) + (c) + (d) + default-title in 6cdb9af:**
+     - (a) `uploadExternallySignedEoi` returns `{ stageChanged, newStage }`; client toast branches on the flag.
+     - (b) `SignedPdfActions` now takes an `onView` callback; `InterestEoiTab` lifts a single `<FilePreviewDialog>` and forwards the callback to both call sites (active doc + history list).
+     - (c) S3 backend's `presignDownload` now sets `response-content-disposition: attachment; filename="<name>"; filename*=UTF-8''<encoded>` + `response-content-type`. `getDownloadUrl` threads `file.filename` through. Filesystem backend already honoured the param.
+     - (d) Service splits metadata write (always: `dateEoiSigned ?? signedAt ?? now()`, `eoiStatus='signed'`) from stage advance (gated on past-EOI). Also fires `evaluateRule('eoi_signed', …)` so berth rules stay in lockstep.
+     - **Default title** for the external-EOI dialog now derives `External EOI — <Client> — <berth range> — <date>` via the existing `formatBerthRange` helper; rep can override.
+     - **(e) Edit-metadata UI deferred** to a later wave so it can share infra with the broader signing-flow rework (queued as task #14).
+   - **SHIPPED (e) in 235e064:** new `updateExternalEoiMetadata` service function patches `documents.title`, `documents.notes`, `interests.dateEoiSigned`, and full-replaces `document_signers` (rows with `id` are UPDATEd, rows without are INSERTed, existing rows whose id isn't in the array are DELETEd). Refuses Documenso-managed docs (`isManualUpload=false`) and non-EOI types with ConflictError. New `PATCH /api/v1/documents/[id]/metadata` route. `<ExternalEoiEditDialog>` mirrors the upload-dialog's signatory affordance (name + email + role + add/remove) plus title / signed date / notes. Document detail page gains an "Edit metadata" button (Pencil icon) that renders only when `isManualUpload && documentType === 'eoi'`. Edit trail recorded in `document_events` as `metadata_updated`.
+7. **[high] Expense form: zod refine on `receiptFileIds` fires invisibly — Create button does nothing because the error renders nowhere** — _src/components/expenses/expense-form-dialog.tsx:64-77_ (form registers `useForm` + `zodResolver(createExpenseSchema)`) + _src/lib/validators/expenses.ts:40-47_ (schema-level `.refine()` requiring `receiptFileIds.length > 0 || noReceiptAcknowledged === true`, attached to `path: ['receiptFileIds']`). The form keeps `uploadedReceipt` + `noReceipt` in local React state, never injecting them into the form values via `setValue`. They're spliced into the payload INSIDE `onSubmit` (lines 188-189) — but `onSubmit` is never reached because validation fails first: zodResolver sees `receiptFileIds: undefined` in form values, the refine fails, `errors.receiptFileIds` is set. The form has NO `{errors.receiptFileIds && <p>...}` block, so the error is invisible. Browser scrolls to top of failed form. User reports "I filled everything in and uploaded a receipt — clicking Create does nothing."
+   - **Fix (recommended — single source of truth in react-hook-form):**
+     - When `handleFileChange` succeeds: `setValue('receiptFileIds', [uploadedReceipt.id], { shouldValidate: true })`.
+     - When the "no receipt" checkbox toggles: `setValue('noReceiptAcknowledged', noReceipt, { shouldValidate: true })`. Optionally also `setValue('receiptFileIds', undefined)` when noReceipt is checked.
+     - When `clearReceipt` runs: `setValue('receiptFileIds', undefined, { shouldValidate: true })`.
+     - Then drop the local `uploadedReceipt` / `noReceipt` state and read `watch('receiptFileIds')` / `watch('noReceiptAcknowledged')` instead for the UI (or keep them as a UI-only mirror for filename display, but make form state authoritative).
+   - **Alt (lighter touch):** keep the local state but drop the schema-level refine; move that validation into `onSubmit` manually after merging local state. Loses the form-error idiom — discouraged.
+   - **Belt + braces (sweep):** audit every form that has `.refine()` rules on fields NOT registered with the form. Same pattern likely exists elsewhere (any form with file uploads or sub-components managing their own state). Add a defensive check: on submit, log/toast a developer warning if a zod error fires on a field that has no error-rendering surface — would have surfaced this bug.
+   - **Effort:** ~30 min for the expense form fix; ~2-3h for the broader audit of similar refines + state-sync gaps. Captured 2026-05-21 from UAT. **Cross-ref:** the platform-wide form-error UX work in Bucket 2 (scroll-to-first-error + summary banner) would have surfaced this bug visibly — bundle the two as a single rollout so each form audited gets both the missing setValue + the missing error-render surface fixed in one pass.
+   - **SHIPPED (expense form only) in 2d57417:** `handleFileChange` / `clearReceipt` / `noReceipt` checkbox now mirror to form state via `setValue`; edit-mode `reset()` pre-fills `noReceiptAcknowledged` from the existing expense row. The platform-wide refine-vs-error-surface audit + the broader form-error UX work remain in Wave 3.
+8. **[high] Documents filing model needs nested entity subfolders (Interests under Clients; Yachts/Companies parity) — design decisions locked 2026-05-21** — _src/lib/db/schema/files.ts_ (add nullable `interest_id` FK + indexes) + _src/lib/db/schema/document_folders.ts_ (extend entity-folder model to support nested entity folders) + _src/lib/services/files.ts_ (`uploadFile`, `ensureEntityFolder`) + _src/lib/services/document-folders.ts_ + _src/components/files/file-upload-zone.tsx_ (accept + forward `interestId`) + _src/components/interests/interest-documents-tab.tsx_ (caller wires interestId) — companion to bug #4 above. Today's schema can't represent per-interest filing: `files` has no `interest_id` and `document_folders.ensureEntityFolder` only knows top-level client/company/yacht roots. Reps want `Clients/<Client name>/<Interest folder>/<file>` so they can find "everything for this specific deal" in one place — including across multiple historical deals for the same client.
+   - **Locked design decisions (from UAT 2026-05-21):**
+     - **D1. Folder naming pattern (single-berth):** `<mooring> · <created month>` (e.g. `A1 · 2026-04`). Stable for the deal's lifetime — does NOT update on stage transitions. Only renames once, on close: appends ` (Lost)` / ` (Won)`. Bookmark / email references stay valid.
+     - **D2. Folder naming pattern (multi-berth):** `<berth range> · <created month>` using the existing `formatBerthRange()` helper from `src/lib/templates/berth-range.ts` — same idiom as the EOI Berth Number field (per CLAUDE.md). Example: `A1-A3, B5-B7 · 2026-04`.
+     - **D3. Default upload scope from an Interest page:** radio with two options, **default selected = "This deal (Interest <folder name>)"**, alternate = "Client-level (all deals)". Rep flips to client-level when uploading general docs like passport scans from the interest page.
+     - **D4. Scope of nesting:** apply to **Interests + Yachts + Companies** (full hierarchy). Yacht folders nest under their owner (Client or Company) per `yachts.current_owner_type/id`. Company-owned yachts nest under their company folder.
+     - **D5. Rename triggers:** ONLY on close (Won/Lost) or archive. Active deals keep stable names. Primary-berth changes during active life do NOT re-derive (avoids churn).
+     - **D6. Storage backend (S3 / MinIO / filesystem):** zero implications. Documents Hub folder tree is metadata-only (`document_folders` in Postgres); object keys stay UUID-based (`<portSlug>/<entity>/<entityId>/<uuid>.<ext>` per `generateStorageKey`) and never move on folder rename. Soft-rescue delete is also metadata-only.
+   - **Schema changes:**
+     - Add `files.interest_id uuid` nullable FK + index on `(port_id, interest_id) WHERE archived_at IS NULL`. Existing rows stay NULL (= client-level, no interest scope).
+     - Extend `document_folders.entity_type` to accept `'interest'` (and confirm `'yacht'`, `'company'` are already supported per CLAUDE.md). Existing partial unique index `uniq_document_folders_entity` on `(port_id, entity_type, entity_id) WHERE entity_id IS NOT NULL` still applies. Nested rows: `parent_id` points to the parent client/company folder (not the system root) so the tree carries the hierarchy.
+   - **Folder-name derivation helper:** new `src/lib/services/document-folder-naming.ts` exporting `deriveInterestFolderName(interest, interestBerths)`:
+     - Read `interest.dateCreated` (or `createdAt`) → format as `YYYY-MM`.
+     - Resolve berths via `interestBerths.filter(b => b.isInEoiBundle ?? b.isPrimary)` (fall back to all linked berths if none flagged).
+     - Single berth → `<mooring> · <month>`. Multiple berths → `${formatBerthRange(moorings)} · <month>`. No berths linked → `Deal <short-id> · <month>` fallback.
+     - Append ` (Won)` / ` (Lost)` when `interest.outcome` is set; ` (Archived)` when `interest.archivedAt` is set without outcome.
+     - Pure function, unit-tested.
+   - **Service-layer wiring (combines with the #4 service-layer fix):**
+     - `uploadFile`: when `entityType==='interest'` OR `interestId` is set → resolve parent client via `interests.clientId`, call `ensureEntityFolder('client', clientId)`, then `ensureEntityFolder('interest', interestId, parentFolderId: clientFolderId, name: deriveInterestFolderName(...))`, file the row at the interest folder. Three-tier: PORT root → client subfolder → interest sub-subfolder.
+     - `uploadFile`: when `entityType==='yacht'` OR `yachtId` set → resolve owner (`yachts.currentOwnerType` + `currentOwnerId`), ensure owner folder, ensure yacht subfolder under it.
+     - `uploadFile`: when only `clientId` set (no interestId, no yachtId) → file at client folder (today's behavior).
+     - **The #4 derive-clientId-from-entityType fix collapses into this:** `uploadFile` now always derives the FK from `entityType + entityId` if not explicitly passed. The bug-#4 hot-fix is the trivial 1-line version; this larger work is the durable version.
+   - **Upload-time UI affordance (D3):**
+     - `FileUploadZone` accepts a new `scopeOptions?: Array<{ id, label, entityType, entityId }>` prop + a `defaultScopeId?: string`. Renders a small radio above the dropzone when ≥ 2 options.
+     - InterestDocumentsTab passes `scopeOptions = [{ id: 'interest', label: 'This deal (Interest <name>)', entityType: 'interest', entityId: interestId }, { id: 'client', label: 'Client-level (all deals)', entityType: 'client', entityId: clientId }]` with `defaultScopeId='interest'`.
+     - YachtDocumentsTab (when it lands) passes 2 options: `'yacht'` (default) + `'owner'` (client/company-level).
+     - Client / Company / Yacht detail pages with no parent context render the dropzone without the radio (single-scope upload).
+   - **Lifecycle hooks (D5):**
+     - Interest outcome lands (Won / Lost): rename folder via a service helper that re-runs `deriveInterestFolderName` and `UPDATE document_folders SET name=...`.
+     - Interest archived: append ` (Archived)` if no outcome set.
+     - Soft-rescue per CLAUDE.md — never hard-delete folders even on `archive`.
+     - Primary-berth changes mid-deal: NO rename (per D5 — stable during active life). The folder name reflects creation-time berths; current berths are visible elsewhere in UI.
+   - **List query updates:**
+     - InterestDocumentsTab "Attachments" section: surface BOTH (i) files with `files.interest_id === interestId` under a "This deal" subheading + (ii) files with `files.client_id === clientId AND interest_id IS NULL` under a "From client" subheading. Mirrors the aggregated-projection idiom (per CLAUDE.md).
+     - Documents Hub tree: render interest subfolders inside parent client folder. Add a small outcome chip per interest folder (Won / Lost / Active).
+   - **Backfill (combines with #4 backfill):**
+     - Files with `entity_type='interest' + entity_id=<UUID>` but missing `interest_id` column → backfill `interest_id = entity_id`; derive parent `client_id` from `interests.client_id`; run `ensureEntityFolder` for both levels.
+     - Files with `entity_type='yacht'` + `entity_id` but missing `yacht_id` → mirror.
+     - Files with only `client_id` set pre-feature stay at client-folder level — no interest scope retroactively (can't infer which interest they belonged to).
+     - One-off script `pnpm tsx scripts/backfill-nested-document-folders.ts --apply` — idempotent, per-port advisory-locked.
+   - **Effort:** ~6-8h end-to-end (migration + service rewrites + folder-name derivation + upload-zone affordance + tree rendering + lifecycle hooks + backfill + tests). Bundles bug #4 — both touch the same code paths. Captured 2026-05-21 from UAT.
+   - **SHIPPED (foundation only — phase 1/3) in e91055f, phases 2/3 in 0ed03fc:** migration `0078_files_interest_id.sql` adds `files.interest_id` text REFERENCES interests(id) ON DELETE SET NULL + indexes `idx_files_interest` + `idx_files_port_interest`. Drizzle schema picks up the column + `interestId` field. `EntityType` widened to include `'interest'` — `ensureEntityFolder('interest', ...)` recursively ensures the parent client folder first so the tree reads `Clients/<Name>/Deal <mooringNumber>/` nested. `resolveEntityDisplayName` derives the deal label from the primary berth via dynamic-import of `getPrimaryBerth` (circular-dep dodge), falling back to `Deal <YYYY-MM-DD>`. **Phases 2/3 SHIPPED in 0ed03fc:** UploadZone scope radio (`<FileUploadZone>` accepts optional `interestId`; when set, fieldset renders "File at: ⦿ This deal | ◯ Client-level"; default deal-scope so deal-specific docs don't bleed across historical interests of the client; interest FK forwarded only when "This deal" selected). Outcome → folder rename hook: `renameInterestFolderForOutcome(interestId, portId, outcome)` strips prior outcome suffix then appends (Won)/(Lost)/(Cancelled); fired fire-and-forget from `interests.service.setInterestOutcome` via dynamic import (circular-dep dodge); no-op when folder hasn't been created yet. Backfill script: `scripts/backfill-nested-document-folders.ts` iterates every (port_id, interest_id) pair in `files` with non-null interest_id and calls `ensureEntityFolder`; idempotent via per-port advisory lock (FNV-1a of port_id); dry-run by default, `--apply` to commit. **Still deferred:** `listFilesAggregatedByEntity` rewrite for "This deal" vs "From client" subheadings (UI polish; per-row filing already correct); Documents Hub tree rendering for nested interest folders (rows exist with parent_id; tree component picks them up automatically).
+9. **SHIPPED in c14f80a (Q58):** `<SelectTrigger>` now accepts `size?: 'default' | 'sm'`; default = `h-11` so trigger matches Input's h-11 default. Existing compact call sites (FilterBar, dense table headers) opt back in via `size="sm"`. Nothing else breaks. **[medium] SelectTrigger height (`h-9`) doesn't match Input height (`h-11`) — platform-wide visual inconsistency** — _src/components/ui/select.tsx:22_ (SelectTrigger default `h-9` = 36px) + _src/components/ui/input.tsx:18_ (Input default `h-11` = 44px). Every form where an Input sits next to a Select has an 8px height mismatch. Surfaced specifically on _src/components/expenses/expense-form-dialog.tsx:222-247_ (the Amount + Currency two-column row) but affects ALL such combinations across the platform. Fixing locally with `className="h-11"` on each call site is a sweep over dozens of spots and creates drift the next time someone copies the pattern.
+   - **Fix (platform-wide):** introduce a `size` variant on SelectTrigger mirroring Button's idiom — `<SelectTrigger size="default" | "sm">`. Default to `"default"` = `h-11` so it pairs with the Input default out of the box. Migrate explicitly-compact uses (filter bars, dense table headers) to pass `size="sm"` = `h-9` to preserve their current density.
+   - **Audit step:** grep every `<SelectTrigger>` and `<Select>` call site; flag the ones in compact contexts (FilterBar, DataTable header dropdowns, dense admin lists) for the `size="sm"` override; everything else inherits the new h-11 default.
+   - **Effort:** ~1h for the component change + audit + sweeping the explicit `size="sm"` overrides. Higher upside: enforces visual parity for every future form. Captured 2026-05-21 from UAT.
+10. **[medium] Platform-wide: every file-row surface should be click-to-preview by default (currently action is hidden behind kebab on FileGrid; Recent Files rows don't respond at all)** — confirmed on _src/components/files/file-grid.tsx:103-150_ (card body is a static `<div>` with no `onClick`; Preview action lives inside `MoreHorizontal` kebab → opacity-0 unless hovered) + _src/components/documents/_ "Recent Files" rendering surface (rows entirely non-clickable per earlier UAT — preview AND download both dead). Same UX gap repeats across every file-row surface; ship one fix pattern everywhere instead of per-component patches.
+    - **Fix shape (apply uniformly):**
+      - **Click target = preview** — the card/row body becomes a `<button onClick={() => onPreview(file)}>` (or accessible `<div role="button" tabIndex={0}>` with keyboard support). Click opens `FilePreviewDialog` directly. Hover state already implies clickability via `hover:border-primary/50 hover:shadow-sm` — wiring the click matches the visual affordance.
+      - **Kebab stays as "More actions"** — Download, Rename, Delete remain in the dropdown. Drop the redundant "Preview" entry from the kebab once the body click does it.
+      - **Non-previewable mime types** — still click-to-preview, but `FilePreviewDialog` renders its fallback empty state ("Preview not supported for this file type. [Download to view]"). Pairs with the universal-preview feature already queued in Bucket 3.
+    - **Affected surfaces** (audit during the sweep):
+      - `src/components/files/file-grid.tsx` — interest/client/company documents grid (confirmed UAT)
+      - `src/components/documents/document-list.tsx` `DocRow` — table-row name cell should be click-to-preview (confirmed UAT 2026-05-21: clicking on the "External EOI — 2026-05-21" filename does nothing)
+      - `src/components/documents/aggregated-section.tsx` — the "Recent Files / Inflight Workflows" panels
+      - `src/components/documents/entity-folder-view.tsx`
+      - Any list surface that takes a `files` array + an `onPreview` callback
+    - **Title cell specifically:** wrap the filename cell in a button-styled span with `onClick={() => onPreview(row)}` so the rep's natural click target works. Keep the row's other action cells (View, Download, kebab) untouched — they're secondary affordances.
+    - **Bundle with Bucket 3 #000 (universal preview)** — pointless to make every row click-to-preview if half the file types render a blank dialog. Ship the two together: file-row surfaces all click-to-preview AND `FilePreviewDialog` handles every mime type (or shows a graceful fallback).
+    - **Effort:** ~1-1.5h for the click-target sweep across 4-5 surfaces; ~5-7h with the universal-preview piece bundled. Captured 2026-05-21 from UAT (FileGrid surfaced specifically; Recent Files captured earlier).
+    - **SHIPPED (FileGrid + DocumentList) in 52342ee:** FileGrid card body is now a `<button onClick={onPreview}>`. DocumentList title cell on rows with `signedFileId` opens `FilePreviewDialog`; kebab keeps More Actions, gains Download.
+    - **SHIPPED (EntityFolderView + HubRootView) in ded16f4:** filename cells on the entity-scoped aggregated Files panel and the Documents Hub root "Recent files" panel now wrap the name in a `<button>` that opens `FilePreviewDialog`. `HubRootFile` shape extended to include `mimeType` (already returned by `/api/v1/files`). Click-to-preview sweep across file-row surfaces is now complete.
+11. **[high] Supplemental-info form blocked by portal kill-switch (route nested under `(portal)` group)** — _src/app/(portal)/public/supplemental-info/[token]/page.tsx_ (current location) + _src/app/(portal)/layout.tsx:25-37_ (`isPortalDisabledGlobally()` short-circuit returns "Client portal unavailable" screen for ALL children). The supplemental-info form is token-protected and conceptually independent of the portal login concept — it's a one-shot URL emailed to a client to fill in extra info for an EOI, and should always work as long as the token is valid. But because the route lives inside the `(portal)` route group, it inherits the layout's "portal disabled?" gate. Net effect: any port that hasn't opted into the client portal (the default state for most ports right now) cannot use the supplemental-info flow at all — clients see the "Client portal unavailable" screen when they click the emailed link, even though the rep just sent it successfully.
+    - **Fix:** move the file from `src/app/(portal)/public/supplemental-info/[token]/page.tsx` → `src/app/public/supplemental-info/[token]/page.tsx` (out of the route group). URL stays identical (`/public/supplemental-info/<token>`) because Next route groups don't affect URLs — the route group's only effect was layout inheritance, and moving it drops the portal gate. Verify the API route at `/api/public/supplemental-info/[token]` doesn't have a similar nesting issue (likely fine — `/api/` paths don't share the `(portal)` layout).
+    - **Sweep:** audit `src/app/(portal)/` for any other anonymous token routes that should be outside the group. Currently `find` only returns the one file, but worth verifying as new public flows are added (password-reset tokens, magic-link tokens for non-portal flows, etc.).
+    - **Effort:** ~10 min for the move + verify (no code change, just file relocation + manual click-through). Captured 2026-05-21 from UAT.
+    - **SHIPPED in 2d57417:** route relocated via `git mv` to `src/app/public/supplemental-info/[token]/page.tsx`. URL `/public/supplemental-info/<token>` unchanged (route groups don't affect URLs). Sweep of `src/app/(portal)/` confirmed no other public token routes were similarly nested.
+12. **[high] Command-search quick-create buttons routed to dead `/new` pages** — _src/components/search/command-search.tsx_ — ZeroState "New client/yacht/company" buttons pushed `/<entity>/new?name=…` which matched the `[id]` dynamic segment and rendered the entity-not-found page. Fixed by switching to `/<entity>?create=1&prefill_name=…` (the existing `useCreateFromUrl` convention) + adding `prefill` prop support to `YachtForm` + `CompanyForm` and wiring `prefill_name` reads in their list components. Now correctly pops the create sheet pre-filled. Fixed in this session.
+
+---
+
+## Bucket 5 — Cross-references to active audit doc
+
+_Manual findings that confirm or extend a finding from the full codebase audit. Format: `manual #N ↔ Audit X#N — note`._
+
+_None yet._
+
+---
+
+## Append protocol
+
+- Add new findings to the matching bucket as bullet points.
+- Where a finding overlaps an audit entry, note `(see Audit X#N)` and add a back-reference line `→ confirmed in manual #<N>` in the corresponding row of `2026-05-18-full-codebase-audit.md`.
+- Keep entries terse — one line where possible, file:line evidence inline.
+- When promoted to a task or PR, append the commit hash inline (`fixed in <sha>`).

docs/superpowers/specs/2026-05-03-dedup-and-migration-design.md

@@ -0,0 +1,564 @@
+# Client Deduplication and NocoDB Migration Design
+
+**Status**: Design draft 2026-05-03 — pending approval.
+**Plan decomposition**: Three implementation plans stack from this design — (P1) normalization + dedup core library; (P2) admin settings + at-create + interest-level guards (runtime); (P3) NocoDB migration script + review queue UI. P1 unblocks P2 and P3.
+**Branch base**: stacks on `feat/mobile-foundation` once it merges to `main`.
+**Out of scope**: live merge of two clients across ports (cross-tenant), automated AI-judged matches, profile-photo / face-match dedup, web-of-trust referrer relationships.
+
+---
+
+## 1. Background
+
+### 1.1 Why this exists
+
+The legacy CRM lives in a NocoDB base whose `Interests` table conflates _the human_ with _the deal_. A row contains `Full Name`, `Email Address`, `Phone Number`, `Address`, `Place of Residence` _and_ the sales-pipeline state for one specific berth. A single human pursuing two berths becomes two rows with semi-duplicated personal data. A 2026-05-03 read-only audit confirmed:
+
+- **252 Interests rows** in NocoDB, against an estimated ~190–200 unique humans (~20–25% duplication rate).
+- **35 Residential Interests rows** in a parallel residential pathway with the same conflation.
+- **64 Website Interest Submissions + 47 Website Contact Form Submissions + 1 EOI Supplemental Form** as inbound capture surfaces.
+- **No Clients table.** The conflated structure is structural, not accidental.
+
+The new CRM (`src/lib/db/schema/clients.ts`) splits this into `clients` (people) ↔ `interests` (deals), with `clientContacts` (multi-channel), `clientAddresses` (multi-address), and a pre-existing `clientMergeLog` table that anticipates merge with undo. The design has been ready; what's missing is (a) a normalization + matching library, (b) the at-create / at-import surfaces that use it, and (c) the migration of the existing 252+35 records.
+
+### 1.2 Real duplicate patterns observed in the live data
+
+Sampled 200 of the 252 NocoDB Interests rows. Confirmed duplicate clusters fall into six patterns:
+
+| Pattern                      | Example rows                                                                                                                                                                    | Signature                                                              |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **A. Pure double-submit**    | Deepak Ramchandani #624/#625; John Lynch #716/#725                                                                                                                              | All fields identical; created same day                                 |
+| **B. Phone format variance** | Howard Wiarda #236/#536 (`574-274-0548` vs `+15742740548`); Christophe Zasso #701/#702 (`0651381036` vs `0033651381036`)                                                        | Same email, normalize-equal phone                                      |
+| **C. Name capitalization**   | Nicolas Ruiz #681/#682/#683; Jean-Charles Miege/MIEGE #37/#163; John Farmer/FARMER #35/#161                                                                                     | Same email or empty; surname case differs                              |
+| **D. Name shortening**       | Chris vs Christopher Allen #700/#534; Emma c vs Emma Cauchefer #661/#673                                                                                                        | Same email + phone; given-name truncated                               |
+| **E. Resubmit with typo**    | Christopher Camazou #649/#650 (phone last 4 digits typo); Gianfranco Di Constanzo/Costanzo #585/#336 (surname typo, **different yacht** — should be ONE client + TWO interests) | Score-on-everything-else high, one field has small-edit-distance noise |
+| **F. Hard cases**            | Etiennette Clamouze #188/#717 (same name, different country phone + email); Bruno Joyerot #18 with email belonging to Bruce Hearn #19 (couple sharing contact)                  | Cannot resolve without a human                                         |
+
+This dataset will be the fixture for the dedup library's tests — every pattern above must be either auto-detected or flagged for review, and the false-positive bar must be high enough that Pattern F doesn't get force-merged.
+
+### 1.3 Dirty data inventory
+
+The migration normalizer must survive these real values from production:
+
+**Phone fields**: `+1-264-235-8840\r` (with carriage return), `'+1.214.603.4235` (apostrophe + dots), `0677580750/0690511494` (two numbers in one field), `00447956657022` (00 prefix), `+447000000000` (placeholder all-zeros), `+4901637039672` (impossible — stripped 0 + country prefix), various unprefixed local formats, dashed US numbers without country code.
+
+**Email fields**: mixed case rampant (`Arthur@laser-align.com` vs `arthur@laser-align.com`); ALL-CAPS local parts; trailing whitespace.
+
+**Name fields**: ALL-CAPS surnames mixed with title-case given names; embedded `\n` and `\r`; double spaces; lowercase-only entries; slash-with-company variants (`Daniel Wainstein / 7 Knots, LLC`, `Bruno Joyerot / SAS TIKI`); placeholder `Mr DADER`, `TBC`.
+
+**Place of Residence (free text)**: `Saint barthelemy`, `St Barth`, `Saint-Barthélemy` (same place, three forms); `anguilla`, `United States `, `USA`, `Kansas City` (city without country), `Sag Harbor Y` (typo).
+
+### 1.4 Existing battle-tested algorithm
+
+`client-portal/server/utils/duplicate-detection.ts` already implements blocking + weighted-rules dedup against this same NocoDB. It runs in production today. We **port it forward** (don't reinvent), then add: soundex/metaphone for surname matching, compounded-confidence when multiple rules match, and negative evidence (same email + different country phone reduces confidence).
+
+### 1.5 Why the website is no longer the source of new dirty data
+
+The website forms (`website/components/pn/specific/website/{berths-item,register,form}/form.vue`) use `<v-phone-input>` with a country picker (`prefer-countries: ['US', 'GB', 'DE', 'FR']`) and `[(value) => !!value || 'Phone number is required']` validation. Output is E.164-shaped. The 252 dirty rows are legacy — pre-form-redesign submissions, sales-rep manual entries, and external CSV imports. Future inbound is clean.
+
+---
+
+## 2. Approach
+
+Three artifacts, layered:
+
+1. **A pure-logic normalization + matching library** at `src/lib/dedup/`. JSX-free, vitest-native (proven pattern: `realtime-invalidation-core.ts`). Tested against the dirty-data fixture corpus drawn from §1.2.
+2. **Three runtime surfaces** that use the library: at-create suggestion in client/interest forms; interest-level same-berth guard; admin review queue powered by a nightly background scoring job.
+3. **A one-shot migration script** that pulls NocoDB → normalizes → dedupes → writes new schema → produces a CSV report with auto-merge log + flagged-for-review pile.
+
+**Configurability via admin settings** (`system_settings` per port) so the team can tune sensitivity without code changes. Defaults err on the safe side — a flagged review is cheaper than a wrongly-merged record.
+
+**Reversibility**: every merge writes a `client_merge_log` row containing the loser's full pre-state JSON. A 7-day undo window lets a wrong merge be reversed without engineering involvement. After 7 days the snapshot is purged for GDPR; merges become permanent.
+
+---
+
+## 3. Normalization library
+
+Lives at `src/lib/dedup/normalize.ts`. Pure functions, no DB, vitest-tested. Used by the dedup algorithm AND by all create-paths so what gets stored is already normalized.
+
+### 3.1 `normalizeName(raw: string)`
+
+```ts
+export function normalizeName(raw: string): {
+  display: string; // human-readable, kept for UI
+  normalized: string; // for matching
+  surnameToken?: string; // for surname-based blocking
+};
+```
+
+- Trim leading/trailing whitespace
+- Replace `\r`, `\n`, tabs with single space
+- Collapse consecutive whitespace to single space
+- Smart title-case: keep particles (`van`, `de`, `del`, `O'`, `di`, `le`, `da`) lowercase except as first token
+- `display` preserves user's intent (slash-with-company stays intact)
+- `normalized` is `display.toLowerCase()` for comparison
+- `surnameToken` is the last non-particle token for blocking
+
+### 3.2 `normalizeEmail(raw: string)`
+
+```ts
+export function normalizeEmail(raw: string): string | null;
+```
+
+- Trim + lowercase
+- Validate via `zod.email()` schema
+- Returns `null` for empty / invalid (caller decides what to do)
+- **Does NOT strip plus-aliases** (`user+tag@domain.com`) — both intentional (real distinct addresses) and malicious-prevention apply. Compare by full localpart.
+
+### 3.3 `normalizePhone(raw: string, defaultCountry: string)`
+
+```ts
+export function normalizePhone(
+  raw: string,
+  defaultCountry: string,
+): {
+  e164: string | null; // canonical, e.g. '+15742740548'
+  country: string | null; // ISO-3166-1 alpha-2
+  display: string | null; // user-facing pretty
+  flagged?: 'multi_number' | 'placeholder' | 'unparseable';
+} | null;
+```
+
+Pipeline:
+
+1. Strip `\r`, `\n`, tabs, single quotes, dots, dashes, parens, spaces
+2. If contains `/` or `;` or `,` → flag `multi_number`, take first segment
+3. If matches `+\d{2}0+$` (e.g., `+447000000000`) → flag `placeholder`, return null
+4. If starts with `00` → replace with `+`
+5. If starts with `+` → parse as E.164
+6. Else if `defaultCountry` provided → parse against that country
+7. Else return null (caller's problem)
+
+Backed by `libphonenumber-js` (already in deps via `tests/integration/factories.ts` usage if not, will add). The hostile cases above all need explicit handling — naïve regex won't survive.
+
+### 3.4 `resolveCountry(text: string)`
+
+```ts
+export function resolveCountry(text: string): {
+  iso: string | null; // ISO-3166-1 alpha-2
+  confidence: 'exact' | 'fuzzy' | 'city' | null;
+};
+```
+
+Reuses `src/lib/i18n/countries.ts`. Pipeline:
+
+1. Lowercase + strip diacritics
+2. Exact match against country names (any locale we ship)
+3. Fuzzy match (Levenshtein ≤ 2 against canonical English names)
+4. City fallback — small in-package mapping for high-frequency cities seen in legacy data (`Sag Harbor → US`, `Kansas City → US`, `St Barth → BL`, etc.). Order: exact → city → fuzzy.
+
+The mapping is opinionated and small (~30 entries covering the actual values seen in the 252-row dataset). Anything that fails to resolve returns `null` and lands in the migration's flagged pile.
+
+---
+
+## 4. Dedup algorithm
+
+Lives at `src/lib/dedup/find-matches.ts`. Pure function. Vitest-tested against the §1.2 cluster fixtures.
+
+### 4.1 Public API
+
+```ts
+export interface MatchCandidate {
+  id: string;
+  fullName: string | null;
+  emails: string[]; // already normalized
+  phonesE164: string[]; // already normalized E.164
+  countryIso: string | null;
+}
+
+export interface MatchResult {
+  candidate: MatchCandidate;
+  score: number; // 0–100
+  reasons: string[]; // human-readable, e.g. ["email match", "phone match"]
+  confidence: 'high' | 'medium' | 'low';
+}
+
+export function findClientMatches(
+  input: MatchCandidate,
+  pool: MatchCandidate[],
+  thresholds: DedupThresholds,
+): MatchResult[];
+```
+
+### 4.2 Scoring rules (compound)
+
+Each rule produces a score addition. **Compounding**: when two strong rules match (e.g., email AND phone), the result is ~95+ rather than max(50, 50). Negative evidence subtracts.
+
+| Rule                                                            | Score | Notes                                                  |
+| --------------------------------------------------------------- | ----- | ------------------------------------------------------ |
+| Exact email match (case-insensitive, normalized)                | +60   | One match suffices                                     |
+| Exact phone E.164 match (≥ 8 significant digits)                | +50   | Excludes placeholder all-zeros                         |
+| Exact normalized full-name match                                | +20   | Many "John Smith"s exist                               |
+| Surname soundex match + given-name fuzzy match (Lev ≤ 1)        | +15   | Catches `Constanzo/Costanzo`, `Christophe/Christopher` |
+| Same address (normalized fuzzy ≥ 0.8)                           | +10   | Bonus signal                                           |
+| **Negative**: Same email but different country code on phone    | −15   | Suggests spouse / coworker / shared inbox              |
+| **Negative**: Same name but DIFFERENT email AND DIFFERENT phone | −20   | Two distinct people with the same name                 |
+
+### 4.3 Confidence tiers (post-compound)
+
+- **score ≥ 90 — `high`** — email AND phone match, or email + name + address. Block-create suggest "Use existing." Auto-link on public-form submit by default.
+- **score 50–89 — `medium`** — single strong signal (email or phone alone), or email + same-name + different country (Etiennette case). Soft-warn but allow.
+- **score < 50 — `low`** — weak signals only. Don't surface in UI; only relevant in background-job review queue.
+
+### 4.4 Blocking strategy
+
+For O(n) scan over a pool of N existing clients, build three lookup maps once per scan:
+
+- `byEmail: Map<string, MatchCandidate[]>` — keyed by normalized email
+- `byPhoneE164: Map<string, MatchCandidate[]>` — keyed by E.164
+- `bySurnameToken: Map<string, MatchCandidate[]>` — keyed by `normalizeName(...).surnameToken`
+
+For an incoming `MatchCandidate`, the candidate set to compare is the union of pool entries reachable through any of its emails/phones/surname-token. Typically 0–5 candidates per query, regardless of N.
+
+### 4.5 Performance budget
+
+For migration: 252 rows compared pairwise once. ~30k comparisons after blocking — a few seconds.
+
+For runtime at-create: incoming candidate against existing pool of N clients per port. Expected pool size at maturity: 1k–10k. With blocking: <10 comparisons, <1ms target. No DB query needed beyond the initial pool fetch (which itself uses the indexed columns).
+
+For background nightly job: full pairwise within port, blocked. 10k clients → ~50k pairwise checks per port → <30s. Fine for a nightly cron.
+
+---
+
+## 5. Configurable thresholds (admin settings)
+
+New rows in `system_settings` per port. Default values err safe (more confirmation, less auto-action).
+
+| Key                            | Default           | Effect                                                                                                                                                                               |
+| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `dedup_block_create_threshold` | `90`              | Score above which the client-create form interrupts: "Use existing client?"                                                                                                          |
+| `dedup_soft_warn_threshold`    | `50`              | Score above which a soft-warn panel surfaces below the form                                                                                                                          |
+| `dedup_review_queue_threshold` | `40`              | Background job lands pairs ≥ this score in `/admin/duplicates`                                                                                                                       |
+| `dedup_public_form_auto_link`  | `true`            | When a public-form submission scores ≥ block-threshold against existing client, attach the new interest to that client without prompting. **Safe**: no merge, just attaching a deal. |
+| `dedup_auto_merge_threshold`   | `null` (disabled) | If non-null, merges happen automatically at this threshold without human confirmation. Recommend leaving null until the team is comfortable; `95` is a reasonable cautious value.    |
+| `dedup_undo_window_days`       | `7`               | How long the loser's pre-state JSON is retained for merge-undo. After this, the snapshot is purged (GDPR) and merges are permanent.                                                  |
+
+Each setting is a row in `system_settings`. UI surface in `/[portSlug]/admin/dedup` (a new admin page) with an "Advanced" toggle to expose the thresholds and brief explanations.
+
+If the sales team complains the safer mode is too click-heavy, an admin flips `dedup_auto_merge_threshold` to `95` without any code change.
+
+---
+
+## 6. Merge service contract
+
+### 6.1 Data flow
+
+`mergeClients(winnerId, loserId, fieldChoices, ctx)` does, in a single transaction:
+
+1. **Snapshot loser** — full row + all attached `clientContacts`, `clientAddresses`, `clientNotes`, `clientTags`, plus a count of dependent rows about to be moved (interests, yacht-memberships, etc.). Stored as `mergeDetails` JSONB in `clientMergeLog`.
+2. **Reattach** — every row pointing at `loserId` updates to point at `winnerId`:
+   - `interests.clientId`
+   - `clientContacts.clientId` — with conflict handling: if winner already has the same email, keep winner's; flag the duplicate for the user
+   - `clientAddresses.clientId` — same conflict handling
+   - `clientNotes.clientId` — preserve `authorId` + `createdAt` (never overwrite)
+   - `clientTags.clientId`
+   - `clientYachtMembership.clientId` (or whatever the table is called)
+   - `auditLogs.entityId` — annotate, don't move (audit truth)
+3. **Apply fieldChoices** — for each field where the user picked the loser's value, copy that into the winner row.
+4. **Soft-archive loser** — `loser.archivedAt = now()`, `loser.mergedIntoClientId = winnerId`. Row stays in DB so the merge is reversible.
+5. **Write `clientMergeLog`** — `{ winnerId, loserId, mergedBy, mergedAt, mergeDetails: <snapshot>, fieldChoices }`.
+6. **Audit log** — top-level `auditLogs` row: `{ action: 'merge', entityType: 'client', entityId: winnerId, metadata: { loserId, score, reasons } }`.
+
+### 6.2 Schema additions (migration)
+
+`clients` table gets a new column:
+
+```ts
+mergedIntoClientId: text('merged_into_client_id').references(() => clients.id),
+```
+
+The existing `clientMergeLog` table is reused. Add a partial index for the undo-window query:
+
+```sql
+CREATE INDEX idx_cml_recent ON client_merge_log (port_id, created_at DESC) WHERE created_at > NOW() - INTERVAL '7 days';
+```
+
+A daily maintenance job (using the existing `maintenance-cleanup.test.ts` infrastructure) purges `mergeDetails` JSONB older than `dedup_undo_window_days` setting.
+
+### 6.3 Undo
+
+`unmergeClients(mergeLogId, ctx)`:
+
+1. Within the undo window, look up the snapshot
+2. Restore loser: clear `archivedAt`, `mergedIntoClientId`
+3. Restore loser's contacts/addresses/notes/tags from snapshot
+4. Detach reattached rows: `interests` etc. that were touching `winnerId` and originally belonged to loser go back. The snapshot stores the original `(rowType, rowId)` list explicitly so this is deterministic.
+5. Mark log row `undoneAt = now()`, `undoneBy = userId`
+
+After 7 days the snapshot is gone and unmerge returns `410 Gone`.
+
+### 6.4 Concurrency
+
+Both merge and unmerge wrap in a single transaction with `SELECT … FOR UPDATE` on `clients.id` of both winner and loser. A second merge attempt against the same loser sees `mergedIntoClientId` already set and refuses (clear error: "Already merged into …").
+
+---
+
+## 7. Runtime surfaces
+
+### 7.1 Layer 1 — At-create suggestion
+
+In `ClientForm` (and the public `register` form once that hits the new system):
+
+- Debounced 300ms after email or phone field changes
+- Calls `findClientMatches` against current port's clients
+- Renders top-1 match if score ≥ `dedup_soft_warn_threshold`:
+  ```
+  ┌─────────────────────────────────────┐
+  │ This looks like an existing client   │
+  │  ML  Marcus Laurent                  │
+  │      marcus@…   +33 6 12 34 56 78    │
+  │      2 interests · last 9d ago        │
+  │  [ Use this client ]   [ Create new ] │
+  └─────────────────────────────────────┘
+  ```
+- "Use this client" → form switches to "create new interest under existing client" mode (preserves whatever other fields the user typed)
+- "Create new" → audit-log `dedup_override` with the candidate's id and reasons (so we have data on false positives)
+
+### 7.2 Layer 2 — Interest-level same-berth guard
+
+Cheap one-liner in `createInterest` service:
+
+- Check `(clientId, berthId)` against existing non-archived interests
+- If hit, throw `BerthDuplicateError` with the existing interest details
+- UI catches and prompts: "Update existing or create separate?"
+
+This is NOT the same as client-level dedup. Same client legitimately can pursue the same berth a second time after it falls through. But the prompt-before-create catches the accidental double-submit case.
+
+### 7.3 Layer 3 — Background scoring + review queue
+
+- A nightly cron (using existing BullMQ infrastructure — search for `scheduled-tasks` in repo) runs `findClientMatches` over each port's full client pool
+- Pairs scoring ≥ `dedup_review_queue_threshold` land in a `client_merge_candidates` table:
+  ```ts
+  export const clientMergeCandidates = pgTable('client_merge_candidates', {
+    id: text('id').primaryKey()...,
+    portId: text('port_id').notNull()...,
+    clientAId: text('client_a_id').notNull()...,
+    clientBId: text('client_b_id').notNull()...,
+    score: integer('score').notNull(),
+    reasons: jsonb('reasons').notNull(),
+    status: text('status').notNull().default('pending'), // pending | dismissed | merged
+    createdAt: timestamp('created_at')...,
+    resolvedAt: timestamp('resolved_at'),
+    resolvedBy: text('resolved_by'),
+  })
+  ```
+- `/[portSlug]/admin/duplicates` lists pending candidates sorted by score desc, with `[Review →]` opening a side-by-side merge dialog
+- Dismissing a candidate marks it `status=dismissed` so the job doesn't re-surface the same pair tomorrow (a future score increase re-creates it).
+
+---
+
+## 8. NocoDB → new system field mapping
+
+This is the explicit mapping the migration script applies. One NocoDB Interest row produces multiple new rows.
+
+### 8.1 Top-level transform
+
+```
+NocoDB Interests row
+  ─→ 0–1 client (deduped against existing pool)
+  ─→ 0–1 client_address
+  ─→ 0–2 client_contacts (email, phone)
+  ─→ exactly 1 interest
+  ─→ 0–1 yacht (when Yacht Name present and not "TBC"/"Na"/empty placeholders)
+  ─→ 0–1 document (when documensoID present)
+```
+
+### 8.2 Field map
+
+| NocoDB field                                                      | Target                                                             | Transform                                                                    |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `Full Name`                                                       | `clients.fullName`                                                 | `normalizeName().display`                                                    |
+| `Email Address`                                                   | `clientContacts(channel='email', value=...)`                       | `normalizeEmail()`                                                           |
+| `Phone Number`                                                    | `clientContacts(channel='phone', valueE164=..., valueCountry=...)` | `normalizePhone(raw, defaultCountry)`                                        |
+| `Address`                                                         | `clientAddresses.streetAddress` (LongText preserved)               | trim                                                                         |
+| `Place of Residence`                                              | `clientAddresses.countryIso` AND `clients.nationalityIso`          | `resolveCountry()`                                                           |
+| `Contact Method Preferred`                                        | `clients.preferredContactMethod`                                   | lowercase, mapped: Email→email, Phone→phone                                  |
+| `Source`                                                          | `clients.source`                                                   | mapped: portal→website, Form→website, External→manual; null → manual         |
+| `Date Added`                                                      | `interests.createdAt` (fallback to NocoDB `Created At` then now)   | parse: try `DD-MM-YYYY`, then `YYYY-MM-DD`, then ISO                         |
+| `Sales Process Level`                                             | `interests.pipelineStage`                                          | see §8.3                                                                     |
+| `Lead Category`                                                   | `interests.leadCategory`                                           | General→general_interest, Friends and Family→general_interest with tag       |
+| `Berth` (FK)                                                      | `interests.berthId`                                                | resolve via `Berths` table by `Mooring Number`                               |
+| `Berth Size Desired`                                              | `interests.notes` (appended)                                       | preserve                                                                     |
+| `Yacht Name`, `Length`, `Width`, `Depth`                          | `yachts.name`, `lengthM`, `widthM`, `draughtM`                     | skip if name in {`TBC`, `Na`, ``, null}; ft→m via `\* 0.3048`                |
+| `EOI Status`                                                      | `interests.eoiStatus`                                              | Awaiting Further Details→pending; Waiting for Signatures→sent; Signed→signed |
+| `Deposit 10% Status`                                              | `interests.depositStatus`                                          | Pending→pending; Received→received                                           |
+| `Contract Status`                                                 | `interests.contractStatus`                                         | Pending→pending; 40% Received→partial; Complete→complete                     |
+| `EOI Time Sent`                                                   | `interests.dateEoiSent`                                            | parse                                                                        |
+| `clientSignTime` / `developerSignTime` / `all_signed_notified_at` | `interests.dateEoiSigned` (use latest)                             | parse                                                                        |
+| `Time LOI Sent`                                                   | `interests.dateContractSent`                                       | parse                                                                        |
+| `Internal Notes` + `Extra Comments`                               | `clientNotes` (one row, system author)                             | concatenate with section markers                                             |
+| `documensoID`                                                     | `documents.documensoId` (when present, type='eoi')                 | preserve                                                                     |
+| `Signature Link Client/CC/Developer`, `EmbeddedSignature*`        | `documents.signers[]`                                              | one row per non-null signer                                                  |
+| `reminder_enabled`, `last_reminder_sent`, etc.                    | `interests.reminderEnabled`, `interests.reminderLastFired`         | parse, default true                                                          |
+
+### 8.3 Sales-stage mapping (8 → 9)
+
+| NocoDB                          | New (PIPELINE_STAGES)                                                    |
+| ------------------------------- | ------------------------------------------------------------------------ |
+| General Qualified Interest      | `open`                                                                   |
+| Specific Qualified Interest     | `details_sent`                                                           |
+| EOI and NDA Sent                | `eoi_sent`                                                               |
+| Signed EOI and NDA              | `eoi_signed`                                                             |
+| Made Reservation                | `deposit_10pct`                                                          |
+| Contract Negotiation            | `contract_sent`                                                          |
+| Contract Negotiations Finalized | `contract_sent` (with audit-note: legacy "negotiations finalized")       |
+| Contract Signed                 | `contract_signed` (or `completed` when deposit + contract both complete) |
+
+### 8.4 Other tables
+
+- **Residential Interests** (35 rows) — same shape as Interests but maps to `residentialClients` + `residentialInterests`. Smaller and cleaner. Same dedup runs within this pool independently.
+- **Website - Interest Submissions** (64 rows) — these are **inbound capture, not yet a client**. Treat as if each row is a fresh public-form submission today: run dedup against the migrated client pool. Auto-link if `dedup_public_form_auto_link` setting allows.
+- **Website - Contact Form Submissions** (47 rows) — sparse data (just name + email + interest type). Skip migration; export as CSV for manual triage. Not the source of truth for any deal.
+- **Website - Berth EOI Details Supplements** (1 row) — single record, preserved as a one-off attached to the matching Interest.
+- **Newsletter Sending** (69 rows) — out of scope; that's a marketing surface, not CRM.
+- **Interests Backup, Interests copy** — historical artifacts. Skipped by default. A `--include-backups` flag attaches them as audit-note entries on the corresponding live Interest if the user wants the history.
+
+---
+
+## 9. Migration script
+
+Located at `scripts/migrate-from-nocodb.ts`. Idempotent: safe to re-run. Three main flags:
+
+```
+$ pnpm tsx scripts/migrate-from-nocodb.ts --dry-run [--port-slug X]
+  Pulls everything, transforms, runs dedup, writes CSV report to .migration/<timestamp>/. No DB writes.
+
+$ pnpm tsx scripts/migrate-from-nocodb.ts --apply --report .migration/<timestamp>/
+  Reads the report, performs the writes the dry-run promised. Refuses if the source data has changed since the report was generated (hash mismatch).
+
+$ pnpm tsx scripts/migrate-from-nocodb.ts --rollback --apply-id <id>
+  Reads the apply log, undoes the writes (only valid within the undo window).
+```
+
+Reuses the `client-portal/server/utils/nocodb.ts` adapter for the NocoDB API client (no need to rebuild). Writes to the new system via Drizzle (re-using the existing services like `createClient`, `createInterest`, etc., so all the same validation runs).
+
+### 9.1 Dry-run report format
+
+`.migration/<timestamp>/report.csv`:
+
+```csv
+op,reason,nocodb_row_id,target_table,target_value,confidence,manual_review_required
+create_client,new,624,clients.fullName,Deepak Ramchandani,N/A,false
+create_contact,new,624,clientContacts.email,dannyrams8888@gmail.com,N/A,false
+create_contact,new,624,clientContacts.phone,+17215868888,N/A,false
+create_interest,new,624,interests.berthId,a1b2c3...,N/A,false
+auto_link,score=98 (email+phone),625,clients.id,<existing client UUID from row 624>,high,false
+flag_for_review,score=72 (same name diff country),188,client.id,<existing client UUID from row 717>,medium,true
+country_unresolved,fallback to AI (port country),198,clientAddresses.countryIso,AI,low,true
+phone_unparseable,placeholder all-zeros,641,clientContacts.phone,<skipped>,N/A,true
+```
+
+Plus `.migration/<timestamp>/summary.md`:
+
+```
+# Migration Dry-Run — 2026-05-03 14:23 UTC
+
+NocoDB:    252 Interests + 35 Residences + 64 Website Submissions
+Outcome:   198 clients, 287 interests (incl. residences), 91 yachts, 412 contacts
+
+Auto-linked (high confidence, no human action needed):
+  - Nicolas Ruiz: rows 681,682,683 → 1 client + 3 interests
+  - John Lynch:   rows 716,725 → 1 client + 2 interests
+  - Deepak Ramchandani: rows 624,625 → 1 client + 2 interests
+  - [12 more]
+
+Flagged for manual review (medium confidence):
+  - Etiennette Clamouze (rows 188,717): same name, different country phone + email
+  - Bruno Joyerot #18 + Bruce Hearn #19: shared household contact
+  - [4 more]
+
+Country resolution failed for 7 rows. All defaulted to port country (AI). Review:
+  - Row 239: "Sag Harbor Y" → AI (likely US)
+  - [6 more]
+
+Phone parsing failed for 3 rows. All flagged, no contact created:
+  - Row 178: empty
+  - Row 641: placeholder "+447000000000"
+  - Row 175: empty
+
+Run `--apply` to commit these changes.
+```
+
+### 9.2 Apply phase
+
+`--apply` reads the report, re-fetches the source rows (via NocoDB MCP / API), recomputes the hash, fails fast if NocoDB changed since dry-run. Then performs the writes within a single PostgreSQL transaction per port (commit at end). On any error mid-transaction, full rollback.
+
+After successful apply, an `apply_id` is generated and an audit-log row written. The `apply_id` is the handle used for `--rollback`.
+
+### 9.3 Idempotency
+
+The script tracks NocoDB row IDs in a `migration_source_links` table:
+
+```ts
+export const migrationSourceLinks = pgTable('migration_source_links', {
+  id: text('id').primaryKey()...,
+  sourceSystem: text('source_system').notNull(), // 'nocodb_interests' | 'nocodb_residences' | …
+  sourceId: text('source_id').notNull(),         // NocoDB row id as string
+  targetEntityType: text('target_entity_type').notNull(), // client | interest | yacht | …
+  targetEntityId: text('target_entity_id').notNull(),
+  appliedAt: timestamp('applied_at')...,
+  appliedBy: text('applied_by'),
+}, (table) => [
+  uniqueIndex('idx_msl_source').on(table.sourceSystem, table.sourceId, table.targetEntityType),
+]);
+```
+
+Re-running `--apply` against the same report skips rows already in this table. Useful for partial-failure resumption.
+
+---
+
+## 10. Test plan
+
+### 10.1 Library-level (vitest unit)
+
+- `tests/unit/dedup/normalize.test.ts` — every dirty-data pattern from §1.3 has a fixture asserting the expected normalized output.
+- `tests/unit/dedup/find-matches.test.ts` — every duplicate cluster from §1.2 has a fixture asserting score + confidence tier. Hard cases (Pattern F) assert "medium" not "high" — false-positive guard.
+
+### 10.2 Service-level (vitest integration)
+
+- `tests/integration/dedup/client-merge.test.ts` — merge service exercised: full reattach, clientMergeLog written, undo within window restores, undo after window returns 410, concurrent merge of same loser fails the second.
+- `tests/integration/dedup/at-create-suggestion.test.ts` — `findClientMatches` against a seeded pool returns expected matches + reasons.
+
+### 10.3 Migration script (vitest integration with NocoDB mock)
+
+- `tests/integration/dedup/migration-dry-run.test.ts` — feed the script a fixture NocoDB dump (the 252 rows, frozen as a JSON snapshot in fixtures), assert the resulting CSV matches a golden file. Catch any future regression in the transform pipeline.
+- `tests/integration/dedup/migration-apply.test.ts` — apply the dry-run output to a clean test DB, assert all expected rows exist, assert idempotency (re-apply is a no-op).
+
+### 10.4 E2E (Playwright)
+
+- `tests/e2e/smoke/30-dedup-create.spec.ts` — type into ClientForm with an email matching seeded client; assert suggestion card appears; click "Use this client"; assert form switches to interest-create mode.
+- `tests/e2e/smoke/31-admin-duplicates.spec.ts` — admin views review queue, opens a candidate, side-by-side merge UI works, merge succeeds, undo within window works.
+
+---
+
+## 11. Rollback plan
+
+Three layers of safety, ordered by reversibility:
+
+1. **Per-merge undo** — admin clicks Undo on a wrongly-merged pair, system rolls back from `clientMergeLog` snapshot. 7-day window. No engineering needed.
+2. **Migration `--rollback` flag** — entire migration apply is reversed via the `apply_id` and `migration_source_links` table. Useful in the first 24h after `--apply`. Engineering-supervised.
+3. **DB restore from backup** — the existing `docs/ops/backup-runbook.md` covers this. Last resort if both above are blocked.
+
+Pre-migration, take a hot backup of the new DB (`pg_dump`). Pre-merge in production (before any human-facing surface ships), the `dedup_auto_merge_threshold` defaults to `null` so no automatic merges happen — every merge is human-confirmed.
+
+---
+
+## 12. Open items
+
+- **Soundex vs metaphone** — Soundex is simpler but English-leaning. Metaphone handles non-English surnames better (the dataset has French, German, Italian, Slavic names). Default to metaphone via the `natural` package; revisit if it adds significant install size.
+- **Cross-port dedup** — not in scope. Each port's clients are deduped within that port. A future "shared address book" feature would need its own design.
+- **Profile photo / face match** — out of scope.
+- **AI-assisted match resolution** — out of scope. The Layer-3 review queue is human-only.
+
+---
+
+## Implementation sequence
+
+P1 (this design's library) → P2 (runtime surfaces) → P3 (migration). Each is a separate plan / PR.
+
+**P1 deliverables**: `src/lib/dedup/{normalize,find-matches}.ts` + tests. No UI changes. No DB changes (except indexed lookups added to existing `clientContacts`). ~1.5 days.
+
+**P2 deliverables**: at-create suggestion in `ClientForm` + interest-level guard in `createInterest` service + admin settings UI for thresholds + `clientMergeCandidates` table + nightly job + admin review queue page + merge service + side-by-side merge UI. ~5–7 days.
+
+**P3 deliverables**: `scripts/migrate-from-nocodb.ts` + `migration_source_links` table + dry-run + apply + rollback. CSV report format frozen against fixture. ~3 days, including fixture creation from the live NocoDB snapshot.
+
+Total: ~10–12 engineering days from approval. Can be split across three PRs landing independently — each is testable in isolation and the runtime surfaces (P2) work even without P3 being run.

docs/superpowers/specs/2026-05-10-documents-hub-split-and-client-folders-design.md

@@ -0,0 +1,375 @@
+# Documents Hub Split + Auto-Filed Client Folders
+
+**Status:** Draft — awaiting final review
+**Date:** 2026-05-10
+**Builds on:** Wave 11.B `feat/documents-folders` (per-port nestable `document_folders` tree, soft-rescue delete, sibling-name uniqueness)
+
+## Overview
+
+Today the CRM has two parallel document surfaces that confuse reps:
+
+1. `/[port]/documents` — Documenso signature workflows only (rows in `documents`). Hub tabs are signing-status (`in_progress` / `awaiting_them` / `awaiting_me` / `completed` / `expired`). Carries the new `document_folders` tree (Wave 11.B).
+2. `/[port]/documents/files` — bare uploaded files only (rows in `files`). Has its **own** "folder" mechanism driven by `storagePath` prefix matching, completely disconnected from `document_folders`.
+
+The signed PDF that Documenso produces lives in the `files` table (`documents.signed_file_id` points at it), but it has no folder home and no entity-driven grouping — reps can't find a client's signed contracts without going through the signing workflow row first.
+
+This spec unifies both surfaces under a single hub with a stacked **Signing in progress / Files** layout, anchored by a per-port nestable folder tree that gains three system-managed roots (`Clients/`, `Companies/`, `Yachts/`). Each entity gets one auto-created subfolder on first need; signed PDFs from completed workflows auto-deposit into the owner's folder. The folder view is **owner-aggregated**: opening `Clients/Smith, John/` surfaces files attached to John, plus files of his linked companies and yachts, each rendered as a labelled subsection.
+
+## Conceptual model
+
+Three first-class concepts after this spec ships:
+
+- **File** (`files` row) — a stored binary artifact (PDF/image/etc.) with one `folder_id` and entity FKs (`client_id` / `company_id` / `yacht_id`). The canonical "document" reps file and find. Produced by either direct upload or as the output of a completed signing workflow.
+- **Signing workflow** (`documents` row) — the _process_ of getting a PDF signed via Documenso. Lifecycle `draft` → `sent` → `partially_signed` → `completed`. Surfaces in the hub's Signing section while in-flight. On completion, produces a signed-PDF file; the workflow row itself becomes audit history accessed via a "view signing details" link on the resulting file. Stops appearing in user-facing folder views.
+- **Folder** (`document_folders` row) — per-port nestable tree (existing). Extended to hold both files and in-flight workflows. Gains three system-managed roots and per-entity auto-subfolders.
+
+`documents.folder_id` stays meaningful for in-flight workflows (rep can file by deal/project). Becomes irrelevant on completion — the rendering layer hides completed workflows from folder views entirely.
+
+`files.folder_id` is **new** (not in current schema) — added by this spec.
+
+## Scope boundaries
+
+### In scope
+
+- New `files.folder_id` column + index, FK to `document_folders.id`
+- `document_folders` schema additions: `system_managed`, `entity_type`, `entity_id`, `archived_at`
+- Three system roots (`Clients/`, `Companies/`, `Yachts/`) auto-created on port init
+- Lazy per-entity subfolder creation on first auto-deposit or first manual upload
+- Auto-deposit logic in `handleDocumentCompleted` (set `files.folder_id` + entity FKs on signed PDF)
+- Owner-resolution chain (Owner-wins: `client_id ?? company_id ?? yacht_id` on workflow, falling back to interest)
+- Owner-aggregation projection in the files & documents listing endpoints
+- Symmetric relationship walking (Client ↔ Company ↔ Yacht via memberships and ownership)
+- Hub UI rebuild: stacked Signing/Files sections, owner-grouped headers, system-folder 🔒 markers
+- "View signing details" dialog on signed-PDF file rows
+- System-folder protection: rename/move/delete blocked at API + UI
+- Entity rename auto-syncs system folder name (transactional)
+- Entity archive applies `(archived)` suffix; entity hard-delete demotes to user folder with `(deleted)` suffix
+- Search box scope: current folder + descendants, results across both Signing and Files
+- Hub root view (no folder selected): port-wide Signing + recent Files
+- One-time backfill script: ensure system folders exist, set `files.folder_id` from entity FKs, copy entity FKs from completed workflows onto signed files
+- Removal of `/[port]/documents/files` route (301 redirect to `/[port]/documents`)
+- Removal of the legacy `storagePath`-prefix folder rendering
+
+### Explicitly out of scope
+
+- Permission/role changes beyond what `documents.view` and `documents.manage_folders` already gate
+- Bulk file actions (multi-select move, multi-select download zip) — separate work
+- Tagging or labels on files — separate work
+- Trash / restore for hard-deleted files (current behavior preserved)
+- Search across file _content_ (full-text PDF search) — current behavior preserved (search is title/filename only)
+- Per-port admin override for aggregation symmetry (rejected as needless setting at E11)
+- Per-user feature flag rollout — hard cutover (E rollout decision)
+- Native PDF preview rebuild — existing `FilePreviewDialog` reused
+
+## Folder tree structure & governance
+
+### System-managed roots and subfolders
+
+Three reserved root folders are auto-created when a port is initialised:
+
+```
+Clients/
+Companies/
+Yachts/
+```
+
+Per-entity subfolders are created **lazily on first need** — when a workflow completes for that entity, when a rep manually uploads a file scoped to that entity, or when a rep clicks "Open folder" on the entity's detail page. Empty entities don't appear in the tree.
+
+Subfolder naming:
+
+- Default name = entity display name (client `firstName lastName` / company `name` / yacht `name`).
+- Numeric collision suffix: `Smith, John (2)`, `Smith, John (3)`, etc. Suffix appended to the _new_ (later-created) folder; existing folder names never change due to collision.
+- Auto-rename on entity rename — runs in the same DB transaction as the entity update.
+- Entity archive: `(archived)` suffix appended, folder shown muted in tree, auto-deposit blocked until restored.
+- Entity hard-delete: `(deleted)` suffix appended, `system_managed` flipped to `false` (folder demoted to a regular user folder; rep can rename/move/delete normally).
+
+### System-folder protection
+
+When `system_managed = true`:
+
+- Rename API rejects with `ConflictError("System folders can't be renamed")`.
+- Move API rejects with `ConflictError("System folders can't be moved")`.
+- Delete API rejects with `ConflictError("System folders can't be deleted")`.
+- UI hides rename/move/delete actions in `FolderActionsMenu` for these rows.
+- UI displays a 🔒 marker next to the folder name.
+
+The three roots themselves (`Clients/` / `Companies/` / `Yachts/`) are also `system_managed = true` and protected identically.
+
+### User folders
+
+User-created folders sit alongside the three system roots and inside any other folder (subject to existing depth/cycle rules from Wave 11.B). Standard CRUD via `documents.manage_folders` permission. Examples reps will create: `Templates/`, `Compliance/`, `Marketing PDFs/`.
+
+## Routing on workflow completion
+
+`handleDocumentCompleted` (in `src/app/api/webhooks/documenso/route.ts`) currently:
+
+1. Verifies the Documenso secret.
+2. Downloads the fully signed PDF.
+3. Creates a `files` row for the signed PDF.
+4. Sets `documents.signed_file_id` to the new file id.
+5. Updates `documents.status = 'completed'`.
+
+This spec extends the handler with steps 3a, 3b, 3c — inserted between (3) and (4):
+
+```
+3a. resolveOwner(workflow):
+      candidates = [
+        workflow.client_id,
+        workflow.company_id,
+        workflow.yacht_id,
+        workflow.interest?.primary_client_id,
+        workflow.interest?.primary_company_id,
+        workflow.interest?.primary_yacht_id,
+      ]
+      return first non-null candidate (with its entity_type) OR null
+
+3b. if owner != null:
+      folder = ensureEntityFolder(port_id, owner.entity_type, owner.entity_id)
+      // INSERT … ON CONFLICT (port_id, entity_type, entity_id) DO NOTHING RETURNING id
+      // re-SELECT on conflict to get the existing folder's id
+      file.folder_id = folder.id
+      // copy entity FK to file row if not already set (so aggregation reads file FKs as source of truth)
+      file[`${owner.entity_type}_id`] ??= owner.entity_id
+
+3c. if owner == null:
+      file.folder_id remains null
+      // file lives at root, surfaced in the root-view Files section
+```
+
+Owner resolution happens at **completion time**, not creation time — if the rep edited the workflow's owner mid-signing (rare), the signed PDF lands in the most recent owner's folder.
+
+The workflow's own `folder_id` is not touched. After `status = 'completed'`, the rendering layer hides the workflow from folder views; only the resulting signed file is visible (with a "view signing details" link to the workflow + signers + events timeline).
+
+## Owner-aggregation projection
+
+The killer feature. When a rep opens an entity folder (`Clients/Smith, John/`), the listing query is **not** a simple `WHERE folder_id = …` — it's a projection that walks the relationship graph and groups results by owner-source.
+
+### Aggregation graph
+
+Aggregation is **symmetric** (E aggregation reach decision). Walking from any entity, surface files attached to:
+
+- the entity itself (DIRECTLY ATTACHED)
+- linked clients via `company_memberships`
+- linked companies via `company_memberships` and via yacht ownership
+- linked yachts via current ownership (`yachts.current_owner_type` + `current_owner_id`)
+- - any second-degree links (e.g., `Clients/Smith` shows files of `Smith Marine LLC`'s yachts via the chain Smith → Smith Marine LLC → owned yachts)
+
+Each result group is rendered with a labelled header: `DIRECTLY ATTACHED · 3`, `FROM COMPANY — SMITH MARINE LLC · 1`, `FROM YACHT — MV SERENITY · 2`, etc. Files lived where they were physically filed (e.g., `Yachts/MV Serenity/`); the aggregation only borrows them for display, with a `lives in <path>` caption per row.
+
+### Source-of-truth: file FKs
+
+Aggregation reads each file's own `client_id` / `company_id` / `yacht_id` (snapshotted at upload/creation time), **not** the linked entity's current relationships. This makes yacht ownership transfer a no-op for historical files: a file uploaded for John when he owned MV Serenity stays under John's view forever, even after the yacht is sold to Mary. Mary's view shows files uploaded after the transfer (which carry `client_id = Mary`). Both clients' folders coexist with their respective historical artifacts.
+
+### Per-group pagination
+
+Each owner-source group renders its top 20 rows by `created_at desc`. When a group has more, a `Show all (148)` link drills into a flat paginated list scoped to that source. Keeps page render bounded for large portfolios (200+ yacht leasing clients).
+
+### Defense-in-depth port_id
+
+Every join in the aggregation SQL filters `port_id = $port` — at the entity table, at the membership table, at the yacht table, at the file table. Project pattern (per CLAUDE.md "defense-in-depth port_id scope" / berth recommender precedent). Single-place port_id check at the entry point alone is rejected — it bit the recommender exactly once and we fixed it the same way.
+
+## UI layout
+
+### Layout A: stacked sections, owner-labelled groups inside each
+
+Confirmed in mockup review.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│ /port-nimara/documents → Clients / Smith, John 🔒                   │
+├──────────────┬──────────────────────────────────────────────────────┤
+│  FOLDERS     │  Clients › Smith, John 🔒          [Upload] [+ Sign] │
+│              │                                                       │
+│  📁 Clients  │  ⏳ SIGNING IN PROGRESS · 2                          │
+│   📁 Smith…🔒│   FROM CLIENT                                         │
+│   📁 …       │   ▢ EOI · Berth A12 · sent 2d ago     Awaiting them  │
+│  📁 Companies│   FROM YACHT — MV SERENITY                            │
+│  📁 Yachts   │   ▢ NDA · sent yesterday              Awaiting them  │
+│              │                                                       │
+│  📁 Templates│  📎 FILES                                             │
+│  📁 Complian.│   DIRECTLY ATTACHED · 3                               │
+│              │   ▢ Signed EOI · A11.pdf  signed Apr 14 · view sig…  │
+│  + New folder│   ▢ Passport scan.pdf    uploaded Mar 2              │
+│              │                                                       │
+│              │   FROM COMPANY — SMITH MARINE LLC · 1                 │
+│              │   ▢ Articles of inc.pdf  · lives in Companies/…       │
+│              │                                                       │
+│              │   FROM YACHT — MV SERENITY · 2                        │
+│              │   ▢ Signed NDA.pdf       · lives in Yachts/…          │
+│              │   ▢ Survey report.pdf    · lives in Yachts/…          │
+└──────────────┴──────────────────────────────────────────────────────┘
+```
+
+Layout primitives:
+
+- **Left panel:** existing `FolderTree` extended for 🔒 markers and `system_managed`-aware action suppression (rename/move/delete hidden in `FolderActionsMenu`).
+- **Main panel:** breadcrumb + actions row, then stacked Signing/Files sections. Each section has its in-section grouped headers.
+- **Signing section:** hidden entirely when no in-flight workflows match the entity scope. When present, renders above Files.
+- **Files section:** always present (may be empty with placeholder).
+- **"View signing details" link:** appears on rows for signed-PDF files (those whose source can be traced via `documents.signed_file_id`). Click opens `<SigningDetailsDialog>` — modal showing signers, events, timeline, signed-at timestamps.
+
+### Hub root view (no folder selected)
+
+Default landing when rep clicks Documents in the sidebar:
+
+- **Signing section:** all in-flight workflows port-wide (effectively today's `/[port]/documents` hub behavior, minus the signing-status sub-tabs which collapse).
+- **Files section:** recently uploaded/modified files port-wide, paginated by `updated_at desc`.
+
+The folder tree on the left is the primary navigation; root view is the "I just opened the hub, show me what's recent" landing.
+
+### Old `/[port]/documents/files` route
+
+Removed. Server-side 301 redirect to `/[port]/documents`. The `<Files…>` components and the legacy `storagePath`-prefix folder code are deleted.
+
+### Hub-tab simplification
+
+Today's signing-status tabs (`in_progress` / `eoi_queue` / `awaiting_them` / `awaiting_me` / `completed` / `expired`) collapse into one Signing section — the rep will filter by signer-status via in-section chips if needed, but the dominant navigation is folders, not signing-status. The `documentsHubTabs` enum + `tab` query param are removed; `hub-counts` API endpoint is reduced to "in-flight count" only (used for the Signing section's counter badge).
+
+## Edge cases — decisions
+
+| ID                   | Edge case                                                               | Decision                                                                                                                                                                    |
+| -------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| E1                   | Entity renamed                                                          | System folder name auto-syncs in the same transaction.                                                                                                                      |
+| E2                   | Two entities collide on folder name (e.g., both "Smith, John")          | Append numeric suffix `(2)`, `(3)` to the **new** colliding folder. Existing folders never change.                                                                          |
+| E3                   | Entity archived                                                         | Folder stays with `(archived)` suffix, muted style. Auto-deposit halts.                                                                                                     |
+| E4                   | Entity hard-deleted                                                     | Folder gets `(deleted)` suffix, `system_managed` flips to `false` (rep can clean up). Files retain orphaned data.                                                           |
+| E5                   | Yacht ownership transferred                                             | Files snapshot their entity FKs at upload time. Old client folder retains historical files; new client gets a new folder for files created after transfer. Both coexist.    |
+| E6                   | Workflow's owner FK changes mid-signing                                 | Resolve owner at completion time. Signed PDF lands in current owner's folder.                                                                                               |
+| E7                   | Rep moves a file out of a system folder                                 | Allowed. `folder_id` changes; entity FK is unchanged so aggregation still surfaces it via FK. The "lives in …" caption updates.                                             |
+| E8                   | Rep manually uploads into an entity folder                              | Auto-set the file's matching entity FK from the destination folder's `entity_type` + `entity_id`. Custom folders → no auto-mapping.                                         |
+| E9                   | Workflow has no entity at all                                           | Signed PDF lands at root with `folder_id = null`. Surfaces in root-view Files section only.                                                                                 |
+| E10                  | File/workflow attached to interest only, interest has no resolved owner | Same as E9 — root, null folder. Manual move or future backfill resolves later.                                                                                              |
+| E11                  | Aggregated view returns 1000+ files                                     | Top 20 per owner-source group, `Show all (N)` drilldown into flat paginated list per source.                                                                                |
+| E12                  | Hub root view (no folder selected)                                      | Port-wide Signing + recent Files, both paginated.                                                                                                                           |
+| E13                  | Concurrent completions race for the same entity folder                  | `INSERT … ON CONFLICT DO NOTHING RETURNING id`, then re-`SELECT` if needed. Uses the new partial unique index `uniq_document_folders_entity`.                               |
+| E14                  | Cross-port aggregation leak                                             | `port_id = $p` filter at every join in aggregation SQL. Defense-in-depth.                                                                                                   |
+| Lazy folder creation | When are system root + per-entity folders created?                      | Roots: on port init. Subfolders: lazy on first need (auto-deposit, manual upload, or "Open folder" button on entity page).                                                  |
+| Aggregation reach    | Symmetric or owner-down only?                                           | Symmetric — walk relationships in both directions. `Clients/Smith/`, `Companies/Smith Marine LLC/`, `Yachts/MV Serenity/` all show the full graph from their vantage point. |
+| Search scope         | Where does the search box look?                                         | Current folder + descendants. Empty/root selection → port-wide. Includes both Signing and Files results.                                                                    |
+| Rollout              | Feature flag or hard cutover?                                           | Hard cutover. Migration backfills data; new hub replaces old hub on merge.                                                                                                  |
+
+## Schema deltas
+
+### `files` table
+
+```sql
+ALTER TABLE files
+  ADD COLUMN folder_id text REFERENCES document_folders(id) ON DELETE SET NULL;
+
+CREATE INDEX idx_files_folder ON files(folder_id);
+CREATE INDEX idx_files_port_folder ON files(port_id, folder_id);
+```
+
+### `document_folders` table
+
+```sql
+ALTER TABLE document_folders
+  ADD COLUMN system_managed boolean NOT NULL DEFAULT false,
+  ADD COLUMN entity_type text,           -- null | 'root' | 'client' | 'company' | 'yacht'
+  ADD COLUMN entity_id text,             -- null when entity_type is null or 'root'
+  ADD COLUMN archived_at timestamptz;    -- mirrors entity archive state
+
+-- Per-port uniqueness on (entity_type, entity_id) for entity subfolders.
+-- Excludes 'root' folders (handled by name uniqueness already in place).
+CREATE UNIQUE INDEX uniq_document_folders_entity
+  ON document_folders(port_id, entity_type, entity_id)
+  WHERE entity_id IS NOT NULL;
+
+-- Enforce: system_managed=true requires either entity_type='root' OR (entity_type IN ('client','company','yacht') AND entity_id IS NOT NULL).
+ALTER TABLE document_folders
+  ADD CONSTRAINT chk_system_folder_shape CHECK (
+    NOT system_managed OR
+    entity_type = 'root' OR
+    (entity_type IN ('client','company','yacht') AND entity_id IS NOT NULL)
+  );
+```
+
+### Backfill migration (one-time data migration script)
+
+Runs as part of the deploy. Idempotent — safe to re-run.
+
+1. For every port: ensure `Clients/`, `Companies/`, `Yachts/` exist with `system_managed=true`, `entity_type='root'`.
+2. For every `(client | company | yacht)` entity that has at least one file or completed workflow attached: ensure its subfolder exists.
+3. For every file with a non-null `client_id` / `company_id` / `yacht_id`: set `folder_id` to the matching subfolder via owner-resolution (Owner-wins).
+4. For every completed workflow with `signed_file_id`: ensure the signed file's entity FKs are populated by copying from the workflow row (handles legacy completions where the signed file row was created without entity FKs).
+5. Files with no entity FKs → `folder_id` left null.
+
+Script: `pnpm tsx scripts/backfill-document-folders.ts`. Wraps in `pg_advisory_xact_lock(<port_id_hash>)` per port to serialize concurrent runs.
+
+## Implementation surface (preview, full breakdown in the plan)
+
+### Service layer
+
+- `src/lib/services/document-folders.service.ts`
+  - `ensureEntityFolder(portId, entityType, entityId)` — INSERT-ON-CONFLICT + re-SELECT
+  - `ensureSystemRoots(portId)` — idempotent root creation
+  - `syncEntityFolderName(portId, entityType, entityId, newName)` — called from entity update services
+  - `applyEntityArchivedSuffix(portId, entityType, entityId)` / `applyEntityRestoredSuffix(...)` — toggle `(archived)` suffix
+  - `demoteSystemFolderOnEntityDelete(portId, entityType, entityId)` — flip `system_managed=false`, append `(deleted)` suffix
+- `src/lib/services/files.service.ts`
+  - `listFilesInFolder(portId, folderId, opts)` — direct listing (folder_id match)
+  - `listFilesAggregatedByEntity(portId, entityType, entityId, opts)` — owner-grouped projection
+  - `applyEntityFkFromFolder(portId, folderId, fileInsert)` — used by upload endpoints (E8)
+- `src/lib/services/documents.service.ts`
+  - `listInflightWorkflowsAggregatedByEntity(...)` — same projection for in-flight workflows
+- `src/lib/services/clients.service.ts` / `companies.service.ts` / `yachts.service.ts`
+  - Add hooks to call `syncEntityFolderName` on rename, `applyEntityArchivedSuffix` on archive/restore, `demoteSystemFolderOnEntityDelete` on hard delete
+
+### API routes
+
+- `src/app/api/v1/files/route.ts` — accept `folderId` (direct) or `entityType + entityId` (aggregated) query params
+- `src/app/api/v1/documents/route.ts` — same; collapse `tab` enum to a `signingState` filter (in-flight only by default)
+- `src/app/api/v1/documents/hub-counts/route.ts` — reduce to in-flight count
+- `src/app/api/v1/documents/[id]/signing-details/route.ts` — **new** — returns workflow + signers + events for the dialog
+- `src/app/api/webhooks/documenso/route.ts` (`handleDocumentCompleted`) — extend with owner-resolve + ensure-folder + set-FK steps
+
+### UI components
+
+- `src/components/documents/documents-hub.tsx` — major rebuild: stacked Signing/Files sections, owner-grouped headers, system-folder integration. Drop the signing-status tabs.
+- `src/components/documents/folder-tree.tsx` — render 🔒 marker for `system_managed`; suppress rename/move/delete in `FolderActionsMenu` for system rows
+- `src/components/documents/aggregated-section.tsx` — **new** — renders a Signing or Files section grouped by owner-source with per-group pagination
+- `src/components/documents/signing-details-dialog.tsx` — **new** — modal for "view signing details"
+- `src/app/(dashboard)/[portSlug]/documents/files/page.tsx` — **deleted**, replaced by 301 redirect in `next.config.mjs`
+- `src/components/files/folder-tree.tsx` and the legacy `storagePath`-prefix logic — **deleted**
+
+### Stores / hooks
+
+- `src/stores/file-browser-store.ts` — repurposed to drive the unified hub state (currentFolder, viewMode); the legacy storagePath-keyed currentFolder semantics are replaced with `document_folders.id` references
+
+## Testing strategy
+
+### Unit (vitest)
+
+- `document-folders.service.test.ts`: extend with system-folder tests — `ensureEntityFolder` idempotency, `syncEntityFolderName` collision (numeric suffix), `applyEntityArchivedSuffix` round-trip, `demoteSystemFolderOnEntityDelete` flips `system_managed`.
+- `files.service.aggregated.test.ts`: aggregation projection — symmetric walk, defense-in-depth port_id, per-group pagination, file-FK-as-source-of-truth (yacht transfer scenario).
+- `documents-completion.handler.test.ts`: `handleDocumentCompleted` with each owner-resolution branch (client direct, company direct, yacht direct, via interest, no owner).
+
+### Integration (vitest + real Postgres)
+
+- `documents-hub-system-folders.integration.test.ts`: API-level — listing aggregated, system folder protection (rename/move/delete return 4xx), entity rename round-trips, archive/delete lifecycle.
+- `backfill-document-folders.integration.test.ts`: backfill script idempotency, multi-port isolation, legacy file FK propagation from completed workflows.
+
+### E2E (Playwright)
+
+- `documents-hub-aggregated.smoke.spec.ts`: open client folder → see grouped Signing + Files → open signing-details dialog → close.
+- `documents-hub-upload-into-entity-folder.smoke.spec.ts`: upload PDF into Clients/Smith/ → verify `client_id` auto-set → verify file appears in entity folder.
+- `documents-hub-completion-auto-deposit.realapi.spec.ts`: round-trip Documenso completion → verify signed PDF lands in owner's entity folder. (Joins the existing realapi project.)
+
+### Visual
+
+- Regenerate baselines for `/[port]/documents` (root view) and `/[port]/documents` with a folder selected. Snapshot key: hub-root, hub-entity-folder.
+
+## Risks and mitigations
+
+| Risk                                                                                                                                                       | Mitigation                                                                                                                                                                                                                                      |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Aggregation queries slow on large portfolios (5k+ files per client)                                                                                        | Per-group pagination caps render cost; supporting indexes on `files(port_id, client_id)`, `files(port_id, company_id)`, `files(port_id, yacht_id)` already exist; new `files(folder_id)` and `files(port_id, folder_id)` cover folder filtering |
+| Backfill migration locks production for too long                                                                                                           | Per-port advisory lock; backfill batched in chunks of 1000 file rows per transaction; safe to re-run if interrupted                                                                                                                             |
+| System-folder protection bypass via direct DB write                                                                                                        | Application-level enforcement; we accept that direct DB writes can bypass (no DB constraint enforces "you can't update system_managed=true rows"). Audit log entries on folder ops surface anomalies                                            |
+| Hard cutover means broken hub if backfill fails                                                                                                            | Backfill is idempotent and runs _before_ code rollout; if backfill fails, the new hub still renders (just with sparse folders); rollback = revert the migration + redeploy old hub binary                                                       |
+| Rep confused by "view signing details" link disappearing for non-Documenso signed files (e.g., manually uploaded "already signed" PDFs via /upload-signed) | The link shows only when `signed_file_id` traces to a `documents` row; manually-uploaded "signed" PDFs that bypass the workflow won't have the link, which is correct — there's nothing to show                                                 |
+
+## Open questions deferred to plan
+
+- Whether to add a "Signing status" filter chip strip inside the Signing section (the deferred replacement for `awaiting_them`/`awaiting_me` tabs). Default: defer; add if rep feedback asks for it.
+- Whether `Signing section in entity folders` should also surface workflows whose `interest_id` resolves to the entity (not just direct entity FK match). Default: yes, via the same Owner-wins resolution chain — codify in the projection helper.

docs/superpowers/specs/2026-05-12-pdf-stack-overhaul-design.md

@@ -0,0 +1,491 @@
+# PDF Stack Overhaul — Design
+
+**Date:** 2026-05-12
+**Branch:** `feat/documents-folders`
+**Status:** Design approved; pending user review of spec; implementation planned via writing-plans skill.
+
+## Goal
+
+Replace `pdfme` (3 deps, 8 hand-coded coordinate templates, 571-line TipTap-to-pdfme bridge) with `@react-pdf/renderer` (JSX components, real layout primitives). Add `unpdf` for berth-PDF tier-2 rasterization. Add port-level logo upload with quality safeguards. Migrate only the internal-only PDF surfaces; remove invoice and admin-TipTap PDF generation entirely (they violate the new "no client-facing CRM-generated PDFs" rule).
+
+## Scope (locked)
+
+### KEEP & migrate to `@react-pdf/renderer` (internal-only)
+
+| Surface                 | Current location                                                                                    | Caller                                |
+| ----------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| Activity report         | `src/lib/pdf/templates/reports/activity-report.ts`                                                  | `src/lib/services/reports.service.ts` |
+| Revenue report          | `src/lib/pdf/templates/reports/revenue-report.ts`                                                   | same                                  |
+| Pipeline report         | `src/lib/pdf/templates/reports/pipeline-report.ts`                                                  | same                                  |
+| Occupancy report        | `src/lib/pdf/templates/reports/occupancy-report.ts`                                                 | same                                  |
+| Client summary export   | `src/lib/pdf/templates/client-summary-template.ts`                                                  | `src/lib/services/record-export.ts`   |
+| Berth spec export       | `src/lib/pdf/templates/berth-spec-template.ts`                                                      | same                                  |
+| Interest summary export | `src/lib/pdf/templates/interest-summary-template.ts`                                                | same                                  |
+| Expense sheet           | `src/lib/services/expense-pdf.service.ts` (currently uses pdfme indirectly via `expense-export.ts`) | same                                  |
+
+### REMOVE entirely
+
+| Removal                                                                                                                                         | Reason                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/lib/pdf/templates/invoice-template.ts` + `generatePdf` call in `invoices.ts:604` + API route `/api/v1/invoices/[id]/generate-pdf`          | Invoices are client-facing; no CRM-generated client-facing PDFs. Future invoice rendering will use the deferred AcroForm-fill admin-template feature.              |
+| `src/lib/pdf/tiptap-to-pdfme.ts` (571 lines) + API route `/api/v1/admin/templates/preview` + `generatePdf` block in `document-templates.ts:516` | TipTap document templates are Documenso seed bodies; CRM does not render them to PDF anymore.                                                                      |
+| `src/lib/pdf/templates/eoi-standard-inapp.ts` (337 lines, HTML seed) + seed-data references                                                     | Only used as the seed `bodyHtml` text on a `document_templates` row. The in-app EOI is rendered by `fill-eoi-form.ts` (pdf-lib), not from this HTML. Safe to drop. |
+| `src/lib/pdf/generate.ts` (24 lines)                                                                                                            | Pdfme wrapper; replaced by `src/lib/pdf/render.ts`.                                                                                                                |
+| Deps: `@pdfme/common`, `@pdfme/generator`, `@pdfme/schemas`                                                                                     | Replaced by `@react-pdf/renderer`.                                                                                                                                 |
+
+### STAYS UNTOUCHED
+
+- `src/lib/pdf/fill-eoi-form.ts` (pdf-lib AcroForm fill on `assets/eoi-template.pdf`) — the in-app EOI pathway.
+- `src/lib/services/berth-pdf-parser.ts` tier-1 (pdf-lib AcroForm read) and tier-3 (AI fallback). Tier-2 (Tesseract OCR) gets `unpdf` for PDF→image rasterization.
+- `pdf-lib` dep (still needed by `fill-eoi-form.ts` and `berth-pdf-parser.ts`).
+- All Documenso integration code.
+
+## Architecture
+
+Three orthogonal PDF paths post-migration, each with a single owner:
+
+```
+┌──────────────────────────┐  ┌──────────────────────────┐  ┌────────────────────────┐
+│  react-pdf (this phase)  │  │  pdf-lib AcroForm fill   │  │  Documenso (external)  │
+│  Internal only           │  │  Standardized + signing  │  │  Client-facing signed  │
+│                          │  │                          │  │  docs                  │
+│  • Reports (×4)          │  │  • In-app EOI            │  │                        │
+│  • Expenses              │  │  • Future admin-upload   │  │  (handled outside our  │
+│  • Record exports (×3)   │  │    invoice templates     │  │   system)              │
+│  • Future internal lists │  │    (deferred)            │  │                        │
+└────────────┬─────────────┘  └────────────┬─────────────┘  └────────────────────────┘
+             │                             │
+             ▼                             ▼
+    src/lib/pdf/render.ts          src/lib/pdf/fill-eoi-form.ts
+    (renderToBuffer +              (unchanged this phase)
+     renderToStream)
+             │
+             ▼
+    src/lib/pdf/brand-kit/
+    ├─ DocumentShell.tsx
+    ├─ Header.tsx
+    ├─ Footer.tsx
+    ├─ DataTable.tsx
+    ├─ KeyValueGrid.tsx
+    ├─ Section.tsx
+    ├─ Badge.tsx
+    ├─ charts/{Bar,Line,Pie,Funnel}Chart.tsx
+    ├─ tokens.ts
+    └─ logo.ts
+```
+
+### Module boundaries
+
+- **`brand-kit/`** — pure presentation primitives. No DB access, no CRM domain knowledge. Each component has typed props and renders react-pdf elements.
+- **`templates/`** — one `.tsx` per document type. Imports brand-kit primitives + receives typed data props. No DB access; data fetching stays in the calling service.
+- **`render.ts`** — the only module that touches `@react-pdf/renderer`'s `renderToBuffer` / `renderToStream`. Services call `renderPdf(<MyTemplate {...data} />)` or `renderPdfStream(<MyTemplate {...data} />)`.
+- **`logo.ts`** — `resolvePortLogo(portId)` reads `system_settings.port_logo_file_id` and returns `{ source, buffer, mimeType }`. Cached per request via React `cache()`.
+- **Chart rendering** — pure SVG components emitting react-pdf's native `<Svg>` primitive. No JSDOM, no headless Chrome, no canvas. Server-rendered like any other PDF component.
+- **Photo embedding** (expense PDFs) — `sharp` (existing dep) compresses each receipt to ~150KB JPEG before embed. Stream-renders pages so memory stays bounded with hundreds of entries.
+
+### Header layout constraint
+
+The brand-kit `<Header>` reserves a fixed logo slot:
+
+```
+maxWidth:  200 (≈ 56mm)
+maxHeight: 60  (≈ 17mm)
+objectFit: contain      // letterbox, never stretch
+align:     left, vertically centered within the dark header band
+fallback:  when resolvePortLogo returns 'fallback', render <Text style={bold}>{port.name}</Text>
+           at the same slot. The port-name + doc-title combination keeps the header visually balanced.
+```
+
+This is enforced inside `<Header>`, not at upload time, so the upload pipeline can accept any 200-1200px logo and trust the layout to letterbox correctly.
+
+### Brand kit tokens
+
+```ts
+// src/lib/pdf/brand-kit/tokens.ts
+export const PDF_TOKENS = {
+  colors: {
+    text: '#111111',
+    textMuted: '#666666',
+    border: '#e5e7eb',
+    headerBand: '#0f172a', // dark slate — matches CRM sidebar
+    headerText: '#ffffff',
+    accentBlue: '#1d4ed8',
+    zebra: '#f9fafb',
+    success: '#16a34a',
+    warning: '#d97706',
+    danger: '#dc2626',
+  },
+  fonts: {
+    sans: 'Helvetica',
+    sansBold: 'Helvetica-Bold',
+    mono: 'Courier',
+  },
+  sizes: {
+    docTitle: 18,
+    sectionH: 13,
+    body: 10,
+    small: 8,
+    caption: 7,
+  },
+  spacing: {
+    pagePadding: 36,
+    sectionGap: 18,
+    rowGap: 6,
+  },
+} as const;
+```
+
+Single source of truth. Future design pass = edit this file, every PDF updates.
+
+## Logo handling
+
+### Layer 1 — Server-side sharp normalization (required)
+
+```
+upload → magic-byte check via sharp metadata (PNG | JPEG | WEBP | SVG | HEIC | HEIF | AVIF)
+       → reject animated GIF / multi-frame PNG / multi-page TIFF
+       → size cap 5MB raw
+       → if SVG:
+           sanitize first via svgo (strip <script>, on*=, <foreignObject>, external href)
+           reject if sanitization removed dangerous nodes
+           rasterize to PNG via sharp(buf, { density: 300 })  // 300 DPI from vector
+       → standard pipeline:
+           sharp(buf)
+             .extract({ left: cropX, top: cropY, width: cropW, height: cropH })  ← from client crop
+             .trim({ threshold: 10 })
+             .resize({ width: 1200, height: 1200, fit: 'inside', withoutEnlargement: true })
+             .toColorspace('srgb')
+             .removeAlpha()-if-jpeg-source-and-near-white
+             .png({ compressionLevel: 9, palette: true })  ← palette where possible for smaller files
+             .toBuffer()
+       → reject if final > 1MB
+       → reject if min dimension after trim < 200px
+       → store via getStorageBackend().put()
+       → set system_settings.port_logo_file_id = files.id (atomic upsert)
+       → soft-archive previous logo's files row (archivedAt = now)
+       → write audit_logs entry: action=branding.logo.uploaded, by=user.id
+       → collect warnings: [trimmed, resized, noAlpha, jpegSource, svgRasterized, heicConverted]
+```
+
+**Why rasterize SVGs to PNG at upload time:** react-pdf's `<Svg>` primitive supports a subset of SVG (Path, Rect, Circle, Line, Text, gradients, clip-paths) but not filters, animations, embedded fonts, or all the quirks of a designer-exported SVG. Sharp rasterizes via librsvg at 300 DPI on upload, eliminating runtime surprises. Single PNG to embed at render time. The vector source is captured-in-time; if the admin later needs higher resolution, they re-upload.
+
+**Why HEIC/AVIF support:** iPhone photo exports default to HEIC; common admin pain point. Sharp handles both natively via libheif; converts to PNG in the pipeline. Less common but worth supporting.
+
+### Layer 2 — Live upload UI
+
+Admin opens **Port Settings → Branding → Logo**. The dialog shows:
+
+1. **Rules above the dropzone:**
+   - Use PNG or SVG with a transparent background
+   - Minimum 200×200px; recommended 600×200px (wide) or 400×400px (square)
+   - Max 5MB; we'll auto-trim and optimize
+   - Avoid JPEGs unless the background is solid white
+
+2. **`react-image-crop` cropper** with aspect-ratio toggle (Wide 3:1 / Square 1:1 / Freeform).
+
+3. **Live HTML preview** rendering the actual brand-kit `<Header>` React component beside the cropper, with the user's logo. Two preview swatches: dark header band (where the logo actually appears) and a colored background (to spot the "white box" problem with non-transparent JPEGs).
+
+4. **Post-upload warnings** displayed in the preview:
+   - "JPEG with no alpha channel — white background will show on dark headers"
+   - "Logo trimmed to remove whitespace borders"
+   - "Resized from 4000×4000 to 1200×1200"
+
+5. **"Test with sample PDF" button** — hits a sample-PDF endpoint that renders a minimal report header and streams it back. Browser opens in a new tab.
+
+### Layer 3 — `react-image-crop` integration
+
+Client renders the original image inside `react-image-crop` with a constrained aspect ratio. On save:
+
+1. Client sends `multipart/form-data` with `file` + `{ cropX, cropY, cropW, cropH }` JSON sidecar.
+2. Server runs the sharp pipeline above with the crop applied as the first step.
+
+This keeps sharp as the single source of truth (no canvas-tainted-CORS issues client-side; the actual crop happens server-side using the user-provided coordinates).
+
+### Storage path
+
+Logos use the existing pluggable storage backend (`src/lib/storage/`). Object key shape:
+
+```
+ports/{portId}/branding/logo-{uuid}.png
+```
+
+The same backend currently serves brochures, berth PDFs, gdpr exports, etc. — `s3` for prod, `filesystem` for single-node dev. Logos inherit whatever's configured; no special routing. Trivial-image-inline-in-DB would save one S3 round-trip per PDF render but break consistency with every other file artifact; not worth it.
+
+### Permission gating
+
+The upload endpoint is wrapped with `withAuth(withPermission('port_settings', 'manage', …))` (same gate currently used for brochures admin, send-from accounts, etc.). Audit trail goes to `audit_logs` (`action: branding.logo.uploaded`, `entityType: port`, `entityId: portId`). Soft-archive of the prior logo file row is logged as `branding.logo.archived`.
+
+### Resolution at render time
+
+```ts
+// src/lib/pdf/brand-kit/logo.ts
+export const resolvePortLogo = cache(
+  async (
+    portId: string,
+  ): Promise<{
+    source: 'logo' | 'fallback';
+    buffer: Buffer | null;
+    mimeType: 'image/png' | 'image/svg+xml' | null;
+  }> => {
+    const setting = await getSystemSetting(portId, 'port_logo_file_id');
+    if (!setting) return { source: 'fallback', buffer: null, mimeType: null };
+    const file = await db.query.files.findFirst({ where: eq(files.id, setting) });
+    if (!file || file.archivedAt) return { source: 'fallback', buffer: null, mimeType: null };
+    const backend = await getStorageBackend();
+    const buffer = await backend.get(file.storageKey);
+    return { source: 'logo', buffer, mimeType: file.mimeType as 'image/png' | 'image/svg+xml' };
+  },
+);
+```
+
+Brand-kit `<DocumentShell>` internally calls this and passes the buffer down through context. Every template that wraps in `<DocumentShell port={port}>...</DocumentShell>` gets the logo automatically. No per-template wiring. When no logo is set, the header renders the port name as bold text instead.
+
+## Per-template designs
+
+### Reports — shared shell
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ [LOGO]   PORT NAME                            REPORT TITLE       │
+│          generated 2026-05-12 18:44           Date-range badge   │
+├──────────────────────────────────────────────────────────────────┤
+│  Summary cards (3-4 KPI stat boxes)                              │
+│  ┌──────┬──────┬──────┐                                          │
+│                                                                  │
+│  ◌ CHART (full-width SVG)                                        │
+│                                                                  │
+│  Detail Table (zebra rows, columns vary per report)              │
+├──────────────────────────────────────────────────────────────────┤
+│  Port Name · Confidential · Page 1 of 3 · Generated …            │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+| Report    | Summary stat cards                                   | Chart                                                            | Detail table columns                                      |
+| --------- | ---------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------- |
+| Activity  | total events, top action, top user, busiest day      | Stacked bar — events per day by action                           | date · action · entity type · entity · user               |
+| Revenue   | total revenue, paid, outstanding, avg invoice        | Line — revenue per month + small pie paid/outstanding            | invoice # · client · issued · due · amount · status       |
+| Pipeline  | total interests, win rate, avg cycle days, top stage | Funnel — count per stage                                         | interest · client · stage · lead category · days in stage |
+| Occupancy | total berths, occupied %, available %, under-offer % | Time-series — occupancy % over period + small pie current status | berth # · status · current interest · last change         |
+
+### Expense PDF
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ [LOGO]  PORT NAME — Expense Sheet                                │
+│         Period: 2026-04-01 → 2026-04-30 · 247 entries            │
+├──────────────────────────────────────────────────────────────────┤
+│  Summary cards: total · by category · by status                  │
+├──────────────────────────────────────────────────────────────────┤
+│  Expense entries (one row per entry, multi-page)                 │
+│  ┌──┬──────────┬──────────┬────────┬─────────┬─────────┐         │
+│  │# │ Date     │ Category │ Vendor │ Amount  │ Receipt │         │
+│  │  │ Notes: <inline notes line, optional>             │         │
+│  │  │ [receipt photo, max 200×200, ~150KB JPEG]        │         │
+│  └──┴──────────┴──────────┴────────┴─────────┴─────────┘         │
+│  Page break inserted between entries when remaining vertical     │
+│  space < 200px (no orphan partial rows)                          │
+├──────────────────────────────────────────────────────────────────┤
+│  Page 1 of 47 · Total: $48,232 · 247 entries                     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Critical: **stream-render via `renderToStream`** because 247 entries × ~150KB photos = 37MB peak memory if all loaded at once. Stream renders one page at a time, freeing buffers as it goes. Each photo passes through `sharp.resize(800, 800, { fit: 'inside' }).jpeg({ quality: 70 })` once and is cached for the lifetime of the request.
+
+### Record exports
+
+- **Client Summary** — brand shell + key/value grid for client info + table for yachts + table for interests + activity timeline at bottom.
+- **Berth Spec** — brand shell + two-column key/value grid (info / dimensions / pricing / tenure) + infrastructure table + waiting-list table + maintenance-log table.
+- **Interest Summary** — brand shell + stage badge in header + key/value grids for client/yacht/berth + notes block + activity timeline.
+
+## Data flow
+
+### Caller migration pattern
+
+Before:
+
+```ts
+import { generatePdf } from '@/lib/pdf/generate';
+import {
+  activityReportTemplate,
+  buildActivityInputs,
+} from '@/lib/pdf/templates/reports/activity-report';
+const inputs = buildActivityInputs(data, port.name);
+const pdfBytes = await generatePdf(activityReportTemplate, inputs);
+```
+
+After:
+
+```ts
+import { renderPdf } from '@/lib/pdf/render';
+import { ActivityReportPdf } from '@/lib/pdf/templates/reports/activity-report';
+const pdfBytes = await renderPdf(<ActivityReportPdf port={port} data={data} />);
+```
+
+### Render module
+
+```ts
+// src/lib/pdf/render.ts
+import { renderToBuffer, renderToStream } from '@react-pdf/renderer';
+import type { ReactElement } from 'react';
+import { logger } from '@/lib/logger';
+
+export async function renderPdf(element: ReactElement): Promise<Buffer> {
+  try {
+    return await renderToBuffer(element);
+  } catch (err) {
+    logger.error({ err }, 'PDF render failed');
+    throw new Error('Failed to render PDF');
+  }
+}
+
+export async function renderPdfStream(element: ReactElement): Promise<NodeJS.ReadableStream> {
+  return renderToStream(element);
+}
+```
+
+### Chart rendering (sketch)
+
+```tsx
+// src/lib/pdf/brand-kit/charts/BarChart.tsx
+import { Svg, Line, Rect, Text as SvgText } from '@react-pdf/renderer';
+import { PDF_TOKENS } from '../tokens';
+
+export function BarChart({
+  data,
+  width = 480,
+  height = 200,
+  color = PDF_TOKENS.colors.accentBlue,
+}) {
+  const max = Math.max(...data.map((d) => d.value));
+  const barW = (width - 60) / data.length;
+  return (
+    <Svg width={width} height={height}>
+      <Line
+        x1={40}
+        y1={20}
+        x2={40}
+        y2={height - 30}
+        strokeWidth={1}
+        stroke={PDF_TOKENS.colors.border}
+      />
+      <Line
+        x1={40}
+        y1={height - 30}
+        x2={width - 10}
+        y2={height - 30}
+        strokeWidth={1}
+        stroke={PDF_TOKENS.colors.border}
+      />
+      {data.map((d, i) => {
+        const h = (d.value / max) * (height - 60);
+        return (
+          <Rect
+            key={i}
+            x={50 + i * barW}
+            y={height - 30 - h}
+            width={barW - 4}
+            height={h}
+            fill={color}
+          />
+        );
+      })}
+      {data.map((d, i) => (
+        <SvgText
+          key={i}
+          x={50 + i * barW + (barW - 4) / 2}
+          y={height - 14}
+          textAnchor="middle"
+          fontSize={7}
+        >
+          {d.label}
+        </SvgText>
+      ))}
+    </Svg>
+  );
+}
+```
+
+Same pattern for LineChart / PieChart / FunnelChart. ~60-100 lines each.
+
+## Error handling
+
+| Failure mode                                                         | Detection                                                                                        | Surface                                                                                                                                                     |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Logo file missing at render time                                     | `resolvePortLogo` returns `source: 'fallback'`                                                   | Header renders port-name text only; structured log warning.                                                                                                 |
+| Logo file corrupt                                                    | `sharp` throws on load                                                                           | 500 via `errorResponse(InternalError)`; structured log; admin sees "Logo file is unreadable, please re-upload."                                             |
+| Chart data empty                                                     | Component prop validation in template                                                            | Render "No data for selected period" placeholder; no crash.                                                                                                 |
+| Receipt photo missing (expense PDF)                                  | Storage backend `get` throws                                                                     | Skip photo for that entry; render "Receipt unavailable" placeholder text; continue; collect into `warnings[]` and log.                                      |
+| Receipt photo unprocessable by sharp                                 | `sharp` throws on resize                                                                         | Same as above.                                                                                                                                              |
+| Stream-render aborted mid-page                                       | `renderToStream` rejects                                                                         | Caller drains stream into try/catch; surface `errorResponse(error)`; partial bytes not stored.                                                              |
+| OOM on huge expense PDF                                              | Heap monitor                                                                                     | Stream-render keeps peak bounded; cap entries at 1000 per PDF; prompt admin to split into multiple periods.                                                 |
+| Sharp pipeline rejects upload                                        | Specific error code                                                                              | 422 `ValidationError` with the rejection reason ("file > 5MB", "dimension < 200px", "unsupported format: GIF animated").                                    |
+| SVG with embedded JS or external href                                | `svgo` strips scripts; post-sanitize node-count check                                            | Reject with `ValidationError('SVG contained disallowed nodes')`.                                                                                            |
+| Concurrent logo uploads (admin clicks save twice / two browser tabs) | Last-writer-wins via atomic `system_settings` upsert                                             | Both `files` rows persist; only newer is pointed at. Soft-archive doesn't race because it operates on the OLD setting's file_id captured before the upsert. |
+| Mid-render logo upload                                               | `resolvePortLogo` reads at render-start                                                          | In-flight PDF uses whichever logo was current when the request entered. Next request gets the new one. No mid-PDF logo swap.                                |
+| Logo dimensions wildly off the header aspect ratio                   | Brand-kit `<Header>` constrains logo to `maxWidth: 200, maxHeight: 60` with `objectFit: contain` | Logo letterboxes inside its slot; never distorts.                                                                                                           |
+| Cropper coords out of bounds                                         | Server-side validation against image metadata before sharp extract                               | 422 `ValidationError('Crop coordinates out of image bounds')`.                                                                                              |
+| File mime header lies (claims PNG, bytes are HTML)                   | Sharp's `metadata()` reads actual magic bytes, ignores declared mime                             | Sharp throws → 422 `ValidationError('File contents do not match a supported image format')`.                                                                |
+| Storage backend `put` fails (network glitch)                         | Catch around `backend.put`                                                                       | Roll back: do not insert files row, do not change system_settings; return 503 with retry hint.                                                              |
+| `port_logo_file_id` setting points at archived/deleted file          | `resolvePortLogo` checks `archivedAt`                                                            | Treat as missing; fall back to text header; structured log warning so ops notices.                                                                          |
+
+## Testing
+
+### Unit (vitest)
+
+- `brand-kit/charts/*.test.tsx` — snapshot SVG output for known inputs.
+- `brand-kit/logo.test.ts` — `resolvePortLogo` with fixtures for: configured / missing / archived / corrupt.
+- `pdf/render.test.ts` — round-trip a tiny `<Page>` and verify the output starts with `%PDF-`.
+- `services/logo-upload.test.ts` — sharp pipeline for: PNG-with-alpha (passes) / JPEG (warning) / undersized (rejects) / oversized (resizes) / SVG (passthrough) / animated GIF (rejects) / SVG with script tag (rejects).
+
+### Integration (vitest)
+
+- Each template renders to bytes without throwing, given representative fixtures from seed data.
+- `reports.service.test.ts` — generate each of the 4 reports for a seeded port; assert PDF magic byte + non-zero length.
+- `record-export.test.ts` — generate client / berth / interest summaries for seeded entities.
+- `expense-export.test.ts` — generate expense PDF for 250 seeded entries; assert pages > 5; assert peak heap delta < 200MB (proxy for stream-render working).
+
+### Playwright (smoke)
+
+- New spec: `branding-logo-upload.spec.ts` — upload PNG, see preview, save, generate sample PDF, assert PDF downloads.
+- New spec: `reports-pdf-export.spec.ts` — for each of the 4 reports, click export, assert PDF downloads.
+- Existing specs: anywhere clicking "export PDF" was tied to pdfme, update assertion.
+
+### Visual regression (existing visual project)
+
+- 4 new baselines (one per report) using seed port's logo.
+- 3 new baselines (client / berth / interest summary).
+- 1 new baseline (expense PDF, first 2 pages).
+- Snapshots stored as PNG (rendered from PDF via first-page extraction).
+
+## Migration sequence
+
+| #   | Commit                               | Files touched                                                                                                                                             | Verifies                                           |
+| --- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| 1   | Foundation: install deps + brand kit | +`@react-pdf/renderer`, +`unpdf`, +`react-image-crop`, +`svgo`; new `src/lib/pdf/brand-kit/*`, `src/lib/pdf/render.ts`                                    | brand kit unit tests pass; nothing wired yet       |
+| 2   | Logo upload feature                  | new `src/lib/services/logo.service.ts`, `src/app/api/v1/admin/branding/logo/*`, admin UI in port settings, `system_settings.port_logo_file_id` key        | upload + preview + sample-PDF test work in dev     |
+| 3   | Migrate activity report              | port `activity-report.ts` → `activity-report.tsx`; rewire `reports.service.ts` caller; visual baseline                                                    | report exports work; visual diff approved          |
+| 4   | Migrate revenue report               | same shape                                                                                                                                                | same                                               |
+| 5   | Migrate pipeline report              | same shape                                                                                                                                                | same                                               |
+| 6   | Migrate occupancy report             | same shape                                                                                                                                                | same                                               |
+| 7   | Migrate client summary               | port `client-summary-template.ts` → `.tsx`; rewire `record-export.ts`                                                                                     | same                                               |
+| 8   | Migrate berth spec                   | same                                                                                                                                                      | same                                               |
+| 9   | Migrate interest summary             | same                                                                                                                                                      | same                                               |
+| 10  | Migrate expense PDF                  | port `expense-pdf.service.ts` to react-pdf streaming; sharp photo compression                                                                             | 250-entry seed test passes                         |
+| 11  | Remove invoice PDF generation        | delete `invoice-template.ts`, the `generatePdf` call in `invoices.ts`, the API route `/api/v1/invoices/[id]/generate-pdf`; remove UI link                 | invoice list still works minus PDF button          |
+| 12  | Remove TipTap-→-pdfme bridge         | delete `tiptap-to-pdfme.ts`, the preview route, the `generatePdf` block in `document-templates.ts:516`, the `getStandardEoiTemplateHtml` seed reference   | admin template editor still saves; preview removed |
+| 13  | Add unpdf to berth parser tier-2     | wire `unpdf` into `berth-pdf-parser.ts` for PDF→image rasterization; keep tesseract.js                                                                    | berth PDF upload still parses                      |
+| 14  | Cleanup: drop pdfme deps             | remove `@pdfme/common`, `@pdfme/generator`, `@pdfme/schemas` from package.json; delete `generate.ts`, `eoi-standard-inapp.ts`; clean up unused validators | `pnpm install` clean; no remaining imports         |
+
+Total: 14 commits. Most are small (5-15 file diffs). Commits 2, 10, and 12 are the heaviest. Vitest + tsc stay green throughout; each commit only flips behavior after its tests pass.
+
+## Deferred (added to BACKLOG)
+
+- Admin-uploaded PDF templates with AcroForm-fill (the invoice template-fill pattern). Needs: new `pdf_templates` table + field-mapping editor + admin upload UI + generalized `fillAcroForm()` utility. Likely ~1 week solo.
+- Port brand color tokens (admin sets brand color → flows into PDF accent color). ~2h.
+- Per-template logo override (different logo for invoices vs reports). YAGNI unless asked.
+- Optical receipt-photo rotation/deskew (auto-rotate phone-upload receipts to readable orientation). ~half day.
+- Replace tesseract.js with cloud OCR (AWS Textract / Google Vision) for berth parsing tier-2. Out of scope.
+
+## Open questions
+
+None blocking. Implementation can begin after user spec review.

docs/superpowers/specs/2026-05-15-env-to-admin-migration-design.md

@@ -0,0 +1,391 @@
+# Env-to-Admin Migration — Design Spec
+
+**Date:** 2026-05-15
+**Status:** Draft (awaiting user review)
+**Author:** Brainstorm session, Matt + Claude
+
+## Goal
+
+Move every tenant-configurable environment variable into the per-port admin UI, leaving env exclusively for boot-time / build-time / chicken-and-egg secrets. Eliminate the silent drift that produced two of the audit's findings (S-23 plaintext S3 access key; Documenso API key stored plaintext per its own admin form description).
+
+## Non-goals
+
+- **Not** moving boot-time secrets (DATABASE_URL, BETTER_AUTH_SECRET, etc.) — they're needed before the DB is reachable.
+- **Not** building a Google OAuth admin form — feature is not in use.
+- **Not** changing the existing per-port `system_settings` storage table — only adding columns / rows.
+- **Not** silently mutating `.env` files at runtime (rejected as too footgun-y).
+
+## Scope decisions (from brainstorming)
+
+| Decision            | Choice                                                                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Which env vars move | Anything tenant-configurable (option 2). Boot-time + build-time stay in env.                                                                     |
+| Env-fallback policy | Env stays as runtime fallback when admin field is blank. Vars are commented out in `.env.example`, with dev + prod templates committed to repo.  |
+| Per-port vs global  | Per-port with global fallback (`port_id IS NULL`) for credentials and shared infrastructure. Resolution: port → global → env → registry default. |
+| Encryption          | All credential-class fields AES-256-GCM via `EMAIL_CREDENTIAL_KEY`. Fixes S-23 + Documenso plaintext as part of this migration.                  |
+| Migration UX        | "Using env fallback" badge per field + "Copy current value from env" one-click button. Operator-driven; nothing happens automatically at boot.   |
+| Implementation      | Settings registry + uniform resolver (approach A).                                                                                               |
+
+## Architecture
+
+The current code has 4 places that "know" about each setting:
+
+1. Env validation schema (`src/lib/env.ts`)
+2. Per-domain resolver (`src/lib/services/port-config.ts` for Documenso/email; ad-hoc reads for others)
+3. Admin form definition (`SettingFieldDef[]` in each `admin/<integration>/page.tsx`)
+4. Encryption call site (per service)
+
+These drift independently and produce drift bugs. Replace those 4 sites with **one registry entry per setting**. The registry is consumed by:
+
+- **Resolver** (`getSetting(key, portId)`) — port → global → env → default; decrypts on read if `encrypted: true`.
+- **Admin form generator** — renders inputs from `type` + `label` + `description`; auto-attaches the "Using env fallback" badge + "Copy from env" button. Encryption is transparent (resolver returns `*IsSet: true` for credential fields, never the cleartext).
+- **Validator** — Zod schema attached to each entry, used by both the admin write endpoint AND env validation at boot.
+- **Encryption helper** — registry says `encrypted: true` → resolver wraps in `encrypt()`/`decrypt()`.
+
+Existing per-port settings table (`system_settings`) stays — no schema migration beyond adding `_encrypted` suffix to a few previously-plaintext columns and one new column for webhook secret.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  src/lib/settings/                      │
+│  ┌──────────────────────┐    ┌─────────────────────┐    │
+│  │ registry.ts          │    │ resolver.ts         │    │
+│  │  - one entry per key │───▶│ getSetting(k, port) │    │
+│  │  - type, encrypted,  │    │ writeSetting(k, v)  │    │
+│  │    scope, validator  │    │ envFallbackFor(k)   │    │
+│  └──────────────────────┘    └──────────┬──────────┘    │
+│                                         │               │
+│  ┌──────────────────────┐    ┌──────────▼──────────┐    │
+│  │ encryption.ts        │◀───│ system_settings     │    │
+│  │  AES-256-GCM         │    │ (existing table)    │    │
+│  └──────────────────────┘    └─────────────────────┘    │
+└─────────────────────────────────────────────────────────┘
+                       ▲
+                       │
+┌──────────────────────┴──────────────────────────────────┐
+│         RegistryDrivenForm (React component)            │
+│  Input: { sections: ['documenso.api', ...] }            │
+│  Output: <Form> with badges + Copy-from-env buttons     │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Registry shape
+
+```ts
+// src/lib/settings/registry.ts
+export interface SettingEntry {
+  /** Stable key written to system_settings.key */
+  key: string;
+  /** Human-readable section the admin form groups by */
+  section: string;
+  /** UI label */
+  label: string;
+  /** UI description (markdown allowed) */
+  description: string;
+  /** Type drives both validation and form input */
+  type: 'string' | 'password' | 'number' | 'boolean' | 'select' | 'url' | 'email';
+  /** select-only */
+  options?: Array<{ value: string; label: string }>;
+  /** Zod schema — overrides type-default validator if provided */
+  validator?: z.ZodTypeAny;
+  /** Defaults applied when port + global + env all absent */
+  defaultValue?: string | number | boolean | null;
+  /** Encrypt at rest with AES-256-GCM */
+  encrypted?: boolean;
+  /** Per-port (default) or global-only (super-admin) */
+  scope: 'port' | 'global';
+  /** Env var name to consult as fallback when port + global blank */
+  envFallback?: string;
+  /** Optional value transformer applied after resolution */
+  transform?: (raw: unknown) => unknown;
+  /** Sensitive: never surface cleartext via admin API; emit `<key>IsSet: boolean` instead */
+  sensitive?: boolean;
+}
+
+export const REGISTRY: SettingEntry[] = [
+  // Documenso
+  {
+    key: 'documenso_api_url',
+    section: 'documenso.api',
+    label: 'API URL',
+    type: 'url',
+    scope: 'port',
+    envFallback: 'DOCUMENSO_API_URL',
+    description: 'Bare host only — never include /api/v1.',
+  },
+  {
+    key: 'documenso_api_key',
+    section: 'documenso.api',
+    label: 'API key',
+    type: 'password',
+    scope: 'port',
+    encrypted: true,
+    sensitive: true,
+    envFallback: 'DOCUMENSO_API_KEY',
+    description: 'AES-encrypted at rest.',
+  },
+  {
+    key: 'documenso_api_version',
+    section: 'documenso.api',
+    label: 'API version',
+    type: 'select',
+    options: [
+      { value: 'v1', label: 'v1' },
+      { value: 'v2', label: 'v2' },
+    ],
+    scope: 'port',
+    envFallback: 'DOCUMENSO_API_VERSION',
+    defaultValue: 'v1',
+  },
+  {
+    key: 'documenso_webhook_secret',
+    section: 'documenso.api',
+    label: 'Webhook secret',
+    type: 'password',
+    scope: 'port',
+    encrypted: true,
+    sensitive: true,
+    envFallback: 'DOCUMENSO_WEBHOOK_SECRET',
+    description: 'Used to verify inbound webhook deliveries via X-Documenso-Secret header.',
+  },
+  // ... continued for every migrated key
+];
+```
+
+Resolver:
+
+```ts
+// src/lib/settings/resolver.ts
+export async function getSetting<T = unknown>(
+  key: string,
+  portId: string | null,
+): Promise<T | null> {
+  const entry = registryFor(key);
+  if (!entry) throw new Error(`Unknown setting: ${key}`);
+
+  // 1. port-specific
+  if (portId && entry.scope === 'port') {
+    const row = await db.query.systemSettings.findFirst({
+      where: and(eq(systemSettings.key, key), eq(systemSettings.portId, portId)),
+    });
+    if (row?.value != null) return decryptIf(entry, row.value) as T;
+  }
+
+  // 2. global (port_id IS NULL)
+  const globalRow = await db.query.systemSettings.findFirst({
+    where: and(eq(systemSettings.key, key), isNull(systemSettings.portId)),
+  });
+  if (globalRow?.value != null) return decryptIf(entry, globalRow.value) as T;
+
+  // 3. env fallback
+  if (entry.envFallback && process.env[entry.envFallback]) {
+    return (
+      entry.transform?.(process.env[entry.envFallback]) ?? (process.env[entry.envFallback] as T)
+    );
+  }
+
+  // 4. registry default
+  return (entry.defaultValue ?? null) as T;
+}
+```
+
+The existing `getPortDocumensoConfig` etc. become thin convenience wrappers that batch a few `getSetting` calls and return a typed object:
+
+```ts
+export async function getPortDocumensoConfig(portId: string) {
+  const [apiUrl, apiKey, apiVersion, webhookSecret, ...rest] = await Promise.all([
+    getSetting<string>('documenso_api_url', portId),
+    getSetting<string>('documenso_api_key', portId),
+    getSetting<DocumensoApiVersion>('documenso_api_version', portId),
+    getSetting<string>('documenso_webhook_secret', portId),
+    // ...
+  ]);
+  return { apiUrl, apiKey, apiVersion, webhookSecret, ...mapRest(rest) };
+}
+```
+
+## Admin UI generation
+
+```tsx
+// src/components/admin/registry-driven-form.tsx
+interface Props {
+  sections: string[]; // e.g. ['documenso.api', 'documenso.signers']
+  portId: string | null; // null = global tab
+}
+
+export function RegistryDrivenForm({ sections, portId }: Props) {
+  const entries = REGISTRY.filter((e) => sections.includes(e.section));
+  const { data: resolved } = useResolvedValues(entries, portId);
+
+  return entries.map((entry) => (
+    <FormField key={entry.key}>
+      <Label>{entry.label}</Label>
+      {entry.description && <p className="text-xs text-muted-foreground">{entry.description}</p>}
+      <Input
+        type={entry.type === 'password' ? 'password' : entry.type}
+        value={
+          entry.sensitive
+            ? resolved[entry.key]?.isSet
+              ? '••••••••'
+              : ''
+            : (resolved[entry.key]?.value ?? '')
+        }
+      />
+      {resolved[entry.key]?.source === 'env' && (
+        <div className="flex gap-2">
+          <Badge>Using env fallback</Badge>
+          <Button onClick={() => copyFromEnv(entry.key, portId)}>Copy from env</Button>
+        </div>
+      )}
+    </FormField>
+  ));
+}
+```
+
+The existing per-integration admin pages become 5-line wrappers:
+
+```tsx
+// admin/documenso/page.tsx (replaces the current 410-line file)
+export default function DocumensoAdmin() {
+  return (
+    <>
+      <PageHeader title="Documenso" />
+      <RegistryDrivenForm
+        sections={['documenso.api', 'documenso.signers', 'documenso.templates']}
+      />
+      <DocumensoTestButton />
+    </>
+  );
+}
+```
+
+## API endpoints
+
+Two endpoints replace the current ad-hoc per-section endpoints:
+
+| Method | Path                                                                       | Purpose                                                                                                                                                                                                                    |
+| ------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GET    | `/api/v1/admin/settings/resolved?sections=documenso.api,documenso.signers` | Returns `{ key, value, source: 'port' \| 'global' \| 'env' \| 'default', isSet }` per requested entry. Sensitive fields never include cleartext.                                                                           |
+| PUT    | `/api/v1/admin/settings/:key`                                              | Body `{ value }`. Validates against registry's Zod schema. Encrypts if `encrypted: true`. Writes to `system_settings`. Audit-logged with `action: 'update'`, `entityType: 'setting'`, `metadata: { key }`, secrets masked. |
+| DELETE | `/api/v1/admin/settings/:key`                                              | Removes the row → reverts to global → env → default.                                                                                                                                                                       |
+| POST   | `/api/v1/admin/settings/:key/copy-from-env`                                | One-click migration. Reads env var named in `entry.envFallback`, writes to `system_settings`, returns the resulting resolved state.                                                                                        |
+
+Existing `PUT /api/v1/admin/settings` (the generic upsert) stays for backward compat with the few non-registry writers; new fields use the typed endpoint.
+
+## Encryption integration
+
+- Reuse existing `encrypt()` / `decrypt()` from `src/lib/utils/encryption.ts` (AES-256-GCM, random IV per encryption, GCM auth tag).
+- Resolver auto-wraps encrypt on write when `entry.encrypted === true`, decrypt on read.
+- `system_settings.value` is `JSONB`. For encrypted values, store as `{ ciphertext, iv, tag }` (already the convention in `sales-email-config.service.ts`).
+- Sensitive fields surface `<key>IsSet: boolean` in the API response, never the decrypted value. The admin form shows `••••••••` placeholder.
+- Audit log integration: when writing to a key with `encrypted: true`, the `newValue` is replaced with `{ value: '[redacted]' }` before audit-log write — fixes audit finding **AU-02** (encrypted ciphertext in audit log) as part of this work.
+
+## Env catalog
+
+Every env var, classified:
+
+### A. Stays in env (boot-time / build-time / chicken-and-egg)
+
+| Var                         | Reason                                                                                          |
+| --------------------------- | ----------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`              | Need DB connection before reading from DB                                                       |
+| `REDIS_URL`                 | Same — Redis pre-init                                                                           |
+| `BETTER_AUTH_SECRET`        | Cookie/session signing key, read at auth init                                                   |
+| `BETTER_AUTH_URL`           | Auth callback base URL, read at auth init                                                       |
+| `CSRF_SECRET`               | CSRF token signing, read pre-DB                                                                 |
+| `EMAIL_CREDENTIAL_KEY`      | The AES key used to encrypt other DB-stored credentials (chicken-and-egg)                       |
+| `NODE_ENV`                  | Read pre-init by Next.js, logger, etc.                                                          |
+| `LOG_LEVEL`                 | Read at logger init pre-DB                                                                      |
+| `PORT`                      | Listen port, read at server start                                                               |
+| `NEXT_PUBLIC_APP_URL`       | Inlined into client JS bundle at build time                                                     |
+| `NEXT_PUBLIC_SENTRY_DSN`    | Same — client-side Sentry init                                                                  |
+| `MULTI_NODE_DEPLOYMENT`     | Used at boot to gate filesystem backend                                                         |
+| `SKIP_ENV_VALIDATION`       | Internal bypass flag                                                                            |
+| `WEBSITE_INTAKE_SECRET`     | Boot-time shared secret with marketing site (could go DB but operator-shared, not user-tunable) |
+| `EMAIL_REDIRECT_TO`         | Dev-only safety net; operator convenience                                                       |
+| `SENTRY_ENVIRONMENT`        | Read at Sentry SDK init pre-DB                                                                  |
+| `SENTRY_TRACES_SAMPLE_RATE` | Same                                                                                            |
+
+### B. Migrates to admin (per-port, encrypted where credential)
+
+| Var                                | Registry key                       | Encrypted                     | Already in admin?             |
+| ---------------------------------- | ---------------------------------- | ----------------------------- | ----------------------------- |
+| `DOCUMENSO_API_URL`                | `documenso_api_url`                | no                            | yes (override)                |
+| `DOCUMENSO_API_KEY`                | `documenso_api_key`                | **yes** (was plaintext)       | yes (override, plaintext bug) |
+| `DOCUMENSO_API_VERSION`            | `documenso_api_version`            | no                            | yes                           |
+| `DOCUMENSO_WEBHOOK_SECRET`         | `documenso_webhook_secret`         | **yes**                       | **no — gap**                  |
+| `DOCUMENSO_TEMPLATE_ID_EOI`        | `documenso_eoi_template_id`        | no                            | yes                           |
+| `DOCUMENSO_CLIENT_RECIPIENT_ID`    | `documenso_client_recipient_id`    | no                            | yes                           |
+| `DOCUMENSO_DEVELOPER_RECIPIENT_ID` | `documenso_developer_recipient_id` | no                            | yes                           |
+| `DOCUMENSO_APPROVAL_RECIPIENT_ID`  | `documenso_approval_recipient_id`  | no                            | yes                           |
+| `MINIO_ENDPOINT`                   | `storage_s3_endpoint`              | no                            | yes (storage admin)           |
+| `MINIO_PORT`                       | (combined into endpoint URL)       | —                             | yes                           |
+| `MINIO_ACCESS_KEY`                 | `storage_s3_access_key`            | **yes** (was plaintext, S-23) | yes (plaintext bug)           |
+| `MINIO_SECRET_KEY`                 | `storage_s3_secret_key`            | yes (already)                 | yes                           |
+| `MINIO_BUCKET`                     | `storage_s3_bucket`                | no                            | yes                           |
+| `MINIO_USE_SSL`                    | (combined into endpoint URL)       | —                             | yes                           |
+| `MINIO_AUTO_CREATE_BUCKET`         | `storage_s3_auto_create_bucket`    | no                            | new                           |
+| `SMTP_HOST`                        | `smtp_host_override`               | no                            | yes                           |
+| `SMTP_PORT`                        | `smtp_port_override`               | no                            | yes                           |
+| `SMTP_USER`                        | `smtp_user_override`               | no                            | yes                           |
+| `SMTP_PASS`                        | `smtp_pass_override`               | yes (already)                 | yes                           |
+| `SMTP_FROM`                        | `email_from_address`               | no                            | yes                           |
+| `OPENAI_API_KEY`                   | `openai_api_key`                   | yes (already)                 | yes                           |
+| `APP_URL`                          | `app_url`                          | no                            | **new**                       |
+| `PUBLIC_SITE_URL`                  | `public_site_url`                  | no                            | **new**                       |
+
+### C. Skipped (YAGNI)
+
+| Var                                        | Reason                            |
+| ------------------------------------------ | --------------------------------- |
+| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | OAuth not used and not on roadmap |
+
+## Migration of existing code
+
+1. **Replace `getPortDocumensoConfig` body** to call the new `getSetting` per field (see Architecture section).
+2. **Replace `getSalesEmailConfig` body** the same way.
+3. **Replace direct `process.env.X` reads** in: `receipt-scanner.ts:4` (OpenAI client), `documents.service.ts` (any direct env reads), `webhook-event-map.ts` (webhook URL builder), all `src/lib/storage/` backend reads.
+4. **Migrate the 5 admin pages** (Documenso, AI, OCR, Email, Storage) to use `RegistryDrivenForm`. Keep page-specific extras (test buttons, status cards, AI budget card, sends log).
+5. **Add migrations:**
+   - One-time data migration: copy any plaintext `documenso_api_key_override` and `storage_s3_access_key` rows into encrypted columns, drop plaintext columns. Reuse `encrypt()`.
+   - Schema: add `documenso_webhook_secret` row on first registry-resolver init, and any new keys (`app_url`, `public_site_url`).
+6. **Update `.env.example`:** comment out everything in category B, add an explanation header pointing operators to `/admin/<integration>` after first super-admin login. Generate `dev.env.example` and `prod.env.example` templates with category-A vars only (the boot-time minimum).
+7. **Update `src/lib/env.ts`:** mark all category-B vars as `optional()` (env is fallback, not required for boot). Category-A stays required.
+
+## Error handling
+
+- **Resolver:** unknown key → throws (programming error). Decryption failure → throws + audit-logged with `action: 'decryption_failed'`. Missing required value → returns `null`, caller decides (e.g. Documenso send fails with a clear error toast).
+- **Admin write:** Zod validation failure → 400 with field-level errors via `parseBody`. Encryption failure → 500 + audit `action: 'encryption_failed'`. Permission check at route handler (`admin.manage_settings` or domain-specific permission).
+- **Form:** "Copy from env" when env var is empty → toast "no env value to copy". Save with empty cleartext on a sensitive field → DELETE the row (reverts to env/default), don't write empty ciphertext.
+
+## Testing
+
+Unit tests:
+
+- `getSetting` — port → global → env → default precedence (per-port hits, global hits, env fallback, default fallback)
+- `getSetting` — encrypted entry round-trips
+- `getSetting` — sensitive entry surfaces `*IsSet` boolean only
+- Registry validators reject malformed values
+- Migration script: plaintext → encrypted round-trips correctly
+
+Integration tests:
+
+- `PUT /api/v1/admin/settings/:key` with valid + invalid payloads
+- `POST /api/v1/admin/settings/:key/copy-from-env` with present + absent env
+- Audit log row written with masked secret value
+
+E2E (Playwright smoke):
+
+- Super-admin opens `/admin/documenso`, sees "Using env fallback" badges on inherited fields, types a value, saves, badge disappears
+- Click "Copy from env" → field auto-fills, badge changes to "Set in port"
+- Per-port override actually applied: switch port → see different value resolved
+
+## Rollout
+
+Single PR, single migration. Backward compat via env-as-fallback means existing deployments keep working unchanged after deploy (admin DB rows are absent, so resolver falls through to env). Operator opts in to admin-canonical configuration field-by-field.
+
+## Out of scope (separate work)
+
+- Building admin form for OCR / berth-PDF parser tunables (feature settings, not env migration)
+- Refactoring all _other_ per-port settings (vocabularies, qualification criteria, custom fields, etc.) into the registry — those already have working bespoke forms; no drift bug there.
+- Adding settings versioning / rollback (not requested)
+- Multi-tenant settings export/import (not requested)

docs/umami-api-capabilities.md

@@ -0,0 +1,189 @@
+# Umami v2 / v3 API capabilities — reference for flesh-out planning
+
+**Verified against:** analytics.portnimara.com (Umami v3.1.0), 2026-05-19.
+**Auth:** username/password → JWT via `POST /api/auth/login`, Bearer on every request, 1h TTL (we cache 55min).
+**Companion code:** `src/lib/services/umami.service.ts` (currently wraps stats/pageviews/metrics/active).
+
+Endpoints below are listed by topic area, with what we currently use, what's available but unused, and where it could plug into the CRM.
+
+---
+
+## 1. Stats & traffic snapshots — `/api/websites/:id/stats`
+
+**Currently used.** Returns the flat aggregate over the requested window plus a `comparison` block for the prior window of equal length.
+
+```json
+{
+  "pageviews": 2081, "visitors": 726, "visits": 872,
+  "bounces": 457, "totaltime": 109519,
+  "comparison": { "pageviews": 1935, "visitors": 642, ... }
+}
+```
+
+**Unused fields we could surface:**
+
+- `totaltime` — total seconds on site → derive avg session time (`totaltime / visits`).
+- `bounces / visits` → bounce-rate KPI.
+- Period-over-period deltas (already wired for trend arrows, but the _full_ comparison object has more we could use for a "what changed since last period" panel).
+
+**Filters supported** (per Umami docs, mostly untested by us): `url`, `referrer`, `title`, `query`, `event`, `host`, `os`, `browser`, `device`, `country`, `region`, `city` — meaning every stats call can be sliced. **Big unlock:** show stats for a specific landing-page URL on the berth detail (e.g. `/berths/A12` stats), or filter by referrer to see which channels drove signed EOIs.
+
+---
+
+## 2. Time-series — `/api/websites/:id/pageviews`
+
+**Currently used** for the trend chart. Returns `{pageviews: [{x, y}], sessions?: [{x, y}]}` (sessions only when `compare` is requested).
+
+**Parameters:** `startAt`, `endAt`, `unit` (`year|month|day|hour`), `timezone`, `compare` (untapped), `filters` (untapped).
+
+**Unused:** `compare=prev` gives the same series for the previous period — could power a dual-line "vs last period" overlay on the chart.
+
+---
+
+## 3. Top-N metrics — `/api/websites/:id/metrics`
+
+**Currently used** for Top Pages / Referrers / Countries (limit 10). Returns `[{x, y}]`.
+
+**Available `type` values** (we surface 4, Umami offers 17):
+
+| Type                        | What it returns            | CRM use case                                              |
+| --------------------------- | -------------------------- | --------------------------------------------------------- |
+| `path`                      | Top URLs                   | ✅ Already shown (we mis-typed as `url`, now fixed)       |
+| `referrer`                  | Top referring sites        | ✅ Already shown                                          |
+| `country`                   | Visitors by country        | ✅ Already shown                                          |
+| `browser` / `os` / `device` | Tech breakdown             | Not surfaced — useful for "is mobile traffic converting?" |
+| `region` / `city`           | Geographic drill-down      | Strong fit for marina marketing                           |
+| `language`                  | Visitor browser language   | Could feed i18n decisions                                 |
+| `screen`                    | Resolution                 | Low value                                                 |
+| `event`                     | Top custom events          | Big unlock — see §6 below                                 |
+| `tag`                       | Event tags                 | Same                                                      |
+| `query`                     | Top URL query strings      | UTM-debug surface                                         |
+| `entry` / `exit`            | First/last page in session | Funnel analysis                                           |
+| `title`                     | Top page titles (vs paths) | Better labels for non-slug URLs                           |
+| `hostname`                  | Multi-domain sites         | Probably N/A                                              |
+| `distinctId`                | Custom user identifiers    | If we ever pipe CRM user IDs into Umami                   |
+
+---
+
+## 4. Live visitors — `/api/websites/:id/active`
+
+**Currently used** for the green-dot "N active right now" indicator. Returns `{visitors: number}` (last-5-min count).
+
+**Alternative for richer realtime:** `/api/realtime/:websiteId` (live realtime feed) returns far more — current top URLs being viewed, current top countries, recent event stream, a 30-minute time-series, totals, plus a `timestamp` you can poll against. We could surface a "live" panel on the dashboard showing the most-viewed pages right now.
+
+---
+
+## 5. Sessions API — `/api/websites/:id/sessions/*`
+
+**Not currently used.** Multiple endpoints worth integrating:
+
+- `GET /sessions` — list every session in a range with full device/geo/visits/views columns. Pageable. Could power a "recent visitors" surface — see who's browsing the berth detail pages right now.
+- `GET /sessions/stats` — summary aggregate (pageviews, visitors, visits, countries, events) keyed by session.
+- `GET /sessions/:sessionId` — drill into a single session: device, OS, browser, country, subdivision, city, screen, language, firstAt, lastAt, visits, views, events, totaltime.
+- `GET /sessions/:sessionId/activity` — full event timeline for one session (urlPath, eventName, referrerDomain, timestamps).
+- `GET /sessions/:sessionId/properties` — custom session properties (email, name, etc. — if Umami's `identify()` is called from the marketing site).
+- `GET /session-data/properties` + `/session-data/values` — aggregate custom session properties.
+- `GET /sessions/weekly` — heatmap of session count by hour-of-week. Direct fit for an "engagement heatmap" widget.
+
+**Big unlock:** if marketing site calls `umami.identify({email})` after EOI form submit, sessions can be linked back to a specific client. We could then show "this client's website journey" on their CRM detail page.
+
+---
+
+## 6. Events API — `/api/websites/:id/events/*`
+
+**Not currently used.** Umami auto-tracks pageviews; custom events are fired explicitly (e.g. button clicks, form submits, video plays). Endpoints:
+
+- `GET /events` — list custom events in a range.
+- `GET /events/stats` — totals.
+- `GET /events/series` — time-series per event.
+- `GET /event-data/*` — aggregate over event payload properties.
+
+**High-leverage CRM use cases:**
+
+- Fire an event on the marketing site when someone clicks "Inquire about berth A12" → CRM Activity feed shows it in real-time on the inquiry record.
+- Fire an event when someone downloads a brochure → see which brochures convert.
+- Fire an event on EOI form-step completions → drop-off funnel analysis.
+
+We'd need to add `umami.track('event-name', {payload})` calls on the marketing site (~1-2h work there) and a new admin surface to define/view these events.
+
+---
+
+## 7. Reports API — `/api/reports/*`
+
+**Not currently used.** Umami's "saved reports" system. Endpoints:
+
+- `GET /reports` + `GET /reports/:id` — list / retrieve saved reports.
+- `POST /reports/insights` — slice-and-dice with arbitrary filters/dimensions.
+- `POST /reports/funnel` — multi-step conversion analysis.
+- `POST /reports/retention` — cohort retention over time.
+- `POST /reports/utm` — UTM-tagged campaign performance.
+- `POST /reports/journey` — most common navigation paths.
+- `POST /reports/goals` — pageview/event-goal completion tracking.
+- `POST /reports/revenue` — revenue attribution (if we fire `purchase` events with amount).
+- `POST /reports/attribution` — first/last-click attribution modelling.
+
+**Best fits for the CRM:**
+
+- **Funnel report** for the EOI flow: `/berths → /berths/A12 → /inquire?berth=A12 → form submit → CRM EOI signed`. Surface drop-off percentages on the Pulse-style dashboard.
+- **Journey report** to see "what paths do visitors take before signing an EOI?" — informs marketing-site IA.
+- **UTM report** to plumb campaign attribution into the lead-source breakdown (currently CRM-side; could be cross-validated against marketing's UTM-tagged traffic).
+- **Attribution report** to give Pipeline-by-Source a "first-click vs last-click" toggle.
+
+---
+
+## 8. Send events from CRM → Umami — `/api/send`
+
+**Not currently used.** The collect endpoint accepts page hits + custom events from any client. CRM doesn't currently push events, but we could:
+
+- Fire `umami.track('signed-eoi', {berth: 'A12', deal_value: 50000})` from the CRM after EOI completion — closes the loop between marketing-site funnel and CRM outcome.
+- Fire `umami.track('contract-signed')`, `umami.track('deposit-received')` — full funnel visible in Umami without leaving it.
+
+---
+
+## 9. Multi-website + team admin — `/api/websites`, `/api/teams`, `/api/users`
+
+**Not currently used.** We hard-code a single `umami_website_id` per port. Useful if a port runs multiple sites (e.g. main marina + residential subdomain): admin UI could list-and-pick from the configured Umami instance's websites instead of requiring manual ID copy-paste. Same for team membership.
+
+---
+
+## Prioritized opportunity list
+
+Ranked by leverage-vs-effort, assuming the v3.1.0 fix in this commit is the baseline:
+
+1. **Avg session time + bounce rate KPI tiles** (~20 min) — already in the `/stats` response, just need new tiles.
+2. **`compare=prev` overlay on the pageviews trend chart** (~30 min) — dual-line "vs last period" surface.
+3. **Country choropleth heatmap** (~4-6h) — already queued in Bucket 3 of the UAT findings doc as "World-map heatmap of Umami visitor origins."
+4. **Surface top browsers / OS / devices** (~30 min) — additional `TopList` columns; pure UI work.
+5. **Fire CRM-side events back into Umami** (~2-3h marketing-site + CRM hook) — closes the funnel between marketing and outcomes.
+6. **EOI funnel via `/api/reports/funnel`** (~3-4h) — drop-off analysis from berth view → inquiry → signed EOI.
+7. **Identify visitors → link sessions to clients** (~4-6h spread across marketing site + CRM detail surfaces) — biggest unlock but needs marketing-site changes.
+8. **Sessions-list "recent visitors" panel** (~2-3h) — see who's browsing right now, drill into individual sessions.
+9. **Saved-reports admin surface** (~6-10h) — let admins create + share Umami reports without leaving the CRM. Bigger product surface; defer until #1-#5 land.
+
+---
+
+## Service-layer additions needed to support the above
+
+`src/lib/services/umami.service.ts` currently exports: `getStats`, `getPageviewsSeries`, `getMetric`, `getActiveVisitors`, `testConnection`. To unlock the opportunities above, add:
+
+- `getSessions(portId, range, opts)` → `/sessions` (paged)
+- `getSession(portId, sessionId)` → single-session drill-in
+- `getSessionActivity(portId, sessionId, range)` → event timeline
+- `getSessionsWeekly(portId, range)` → heatmap source
+- `getEvents(portId, range)` + `getEventsStats(portId, range)` + `getEventsSeries(portId, range, eventName, unit)` → custom events
+- `getRealtime(portId, range)` → `/api/realtime/:id` for the live panel
+- `getReport(portId, reportType, body)` → POST wrappers for funnel/retention/journey/utm/goals/revenue/attribution
+- `trackEvent(portId, name, payload)` → POST to `/api/send` for CRM → Umami event emission
+
+Each is a thin wrapper around the existing `umamiFetch` (or a new `umamiPost` variant for the reports endpoints). The auth + JWT cache + retry logic already in place handles them all.
+
+---
+
+## Known gotchas (verified against v3.1.0)
+
+- Metric `type=url` returns 400 — use `type=path` (handled in our code via back-compat alias).
+- `/api/websites/:id/pageviews` returns `sessions` only when `compare` is in the query string — keep `.sessions` optional in TS types.
+- Stats response is **flat** (`pageviews: number`), not nested (`pageviews: {value, prev}`). The v1 nested shape isn't in v2/v3.
+- `/api/auth/login` returns a JWT with no `expires_in` field — we assume 1h and refresh proactively at 55min.
+- Visiting `/api` in a browser returns nothing — base path has no GET handler. Use `/api/heartbeat` to check liveness.
+- Filters are passed as query params (e.g. `&country=DE`), NOT as a JSON `filters` body, per actual API behaviour (docs occasionally show JSON which doesn't work for GET endpoints).

docs/website-analytics-flesh-out-plan.md

@@ -0,0 +1,428 @@
+# Website Analytics — flesh-out plan
+
+**Goal:** rebuild `/{portSlug}/website-analytics` so it feels like a polished native CRM panel that _mirrors_ Umami's idiom rather than reading as a stripped-down embed. Keep a "View in Umami →" deep-link in the header for power users; render most data in-app via the API. Also extend usage into adjacent CRM surfaces (dashboard tiles, inquiry detail, email open-tracking) so Umami stops being "the analytics page" and becomes a cross-cutting data layer.
+
+**Inputs to this plan:**
+
+1. Live API capabilities reference — `docs/umami-api-capabilities.md` (verified empirically against v3.1.0 on analytics.portnimara.com).
+2. Live UI tour via Playwright — screenshots `umami-tour-1-overview.png` through `umami-tour-9-compare.png` (10 surfaces captured).
+3. Pixel-tracking probe — confirmed the `/p/<slug>` and `/q/<slug>` endpoints + their UI creation forms.
+
+---
+
+## 1. What Umami's UI actually does — design patterns to mirror
+
+Tour findings (from 17 sub-pages + 4 team pages):
+
+| Surface                                     | Visual idiom                                                                                                                                                                                                                                                                                                                   | Adopt for CRM?                                                                                                                |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Overview**                                | 5-tile KPI row (Visitors / Visits / Views / Bounce rate / Visit duration) — each tile shows headline number + colored arrow chip (green ↑ 58% / red ↓ 39%) + percentage delta. Single stacked bar chart below for traffic time-series (visitors stacked over visits, dual-shade blue). Filter pill + date-range nav top-right. | **Yes** — already mostly there, missing the bounce-rate + visit-duration tiles.                                               |
+| **Events**                                  | List of custom event names with per-event count + time-series spark.                                                                                                                                                                                                                                                           | **Yes** — needs marketing-site event firing first (Phase 4).                                                                  |
+| **Sessions**                                | Dense table: avatar + per-session row showing Visits / Views / Events / Location (flag + city, country) / Browser icon / OS icon / Device icon / Last seen. Tabs for Activity vs Properties (custom session props).                                                                                                            | **Yes** — high-leverage; lets reps see _who_ is browsing right now.                                                           |
+| **Realtime**                                | 4 stat tiles (Views/Visitors/Events/Countries) + auto-refreshing line chart of last 30 min.                                                                                                                                                                                                                                    | **Yes** — already partial via the glance tile.                                                                                |
+| **Performance**                             | Likely page-speed / Core Web Vitals.                                                                                                                                                                                                                                                                                           | Skip — not relevant to marina sales.                                                                                          |
+| **Compare**                                 | Pick two date ranges side-by-side.                                                                                                                                                                                                                                                                                             | **Partial** — single `compare=prev` overlay on the existing trend chart suffices.                                             |
+| **Breakdown**                               | Pivot table view across dimensions.                                                                                                                                                                                                                                                                                            | Skip in v1; expose via Reports later.                                                                                         |
+| **Goals**                                   | Define event/page-view goals, see completion rate over time.                                                                                                                                                                                                                                                                   | **Yes** — defer to Phase 5.                                                                                                   |
+| **Funnels**                                 | Multi-step conversion funnel (e.g. /berths → /berths/A12 → /inquire → submit).                                                                                                                                                                                                                                                 | **Yes** — Phase 5; high-value for inquiry conversion.                                                                         |
+| **Journeys**                                | Most common navigation paths (Sankey-like).                                                                                                                                                                                                                                                                                    | **Maybe** — defer; nice-to-have.                                                                                              |
+| **Retention**                               | Cohort retention grid.                                                                                                                                                                                                                                                                                                         | Skip — wrong fit for one-and-done marina inquiry traffic.                                                                     |
+| **Replays**                                 | Session replay (likely paid).                                                                                                                                                                                                                                                                                                  | Skip — unavailable on our tier.                                                                                               |
+| **Segments / Cohorts**                      | Saved filters / user groups.                                                                                                                                                                                                                                                                                                   | Skip in v1.                                                                                                                   |
+| **UTM**                                     | Campaign attribution by UTM params.                                                                                                                                                                                                                                                                                            | **Yes** — Phase 5 for paid-campaign tracking.                                                                                 |
+| **Revenue**                                 | Revenue attribution.                                                                                                                                                                                                                                                                                                           | Skip — would require firing `purchase` events from CRM after EOI close (consider Phase 6 if leadership wants funnel→revenue). |
+| **Attribution**                             | First/last-click attribution model.                                                                                                                                                                                                                                                                                            | **Maybe** — defer.                                                                                                            |
+| **Team-Boards / Websites / Links / Pixels** | Account admin surfaces.                                                                                                                                                                                                                                                                                                        | **Pixels + Links: YES — see Phase 4.** Boards/Websites stay in Umami.                                                         |
+
+### Visual specifics worth copying
+
+- **KPI tile design**: large bold number, label above in muted-grey, arrow + percentage delta below in a colored chip (green-bg for positive, red-bg for negative, fixed-width for alignment). Our `KPITile` already does the right shape — we just need to add the missing two metrics.
+- **Stacked bar chart for traffic**: dual-shade single bar (visitors as light-blue base, views stacked dark-blue on top). Reads cleaner than two overlapping lines.
+- **Location rendering**: flag emoji + "City, Country" inline. Use `getCountryName()` + a flag library (twemoji or unicode regional indicators).
+- **Browser/OS/Device icons**: small colored brand glyphs inline. Use `simple-icons` or `lucide` equivalents.
+- **Filter chip + date nav**: `<` `>` arrows step through the date range; dropdown opens to preset list. Adopt the same pattern on our shell — currently we only have presets, no step-arrows.
+
+---
+
+## 2. Phased build plan
+
+### Phase 1 — Fill out the Overview tiles & chart (~3-4h)
+
+Quick wins that close visual parity with Umami's Overview:
+
+| Task                                                           | File                                                                     | Effort                                                                        |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| Add **Bounce rate** KPI tile                                   | `website-analytics-shell.tsx`                                            | derive `bounces / visits * 100`; service field already there                  |
+| Add **Avg visit duration** KPI tile                            | `website-analytics-shell.tsx`                                            | derive `totaltime / visits` formatted as `Xm Ys`; service field already there |
+| Add **`<` `>` date-step arrows** on the date-range chip        | `date-range-picker.tsx`                                                  | step the current preset by one window (today→yesterday, 7d→prior-7d, etc.)    |
+| Convert pageviews trend to **stacked bar** (visitors vs views) | `pageviews-chart.tsx`                                                    | recharts `BarChart` stacked, light/dark blue                                  |
+| Add **`compare=prev` overlay toggle** on the trend chart       | `pageviews-chart.tsx` + service `getPageviewsSeries`                     | optional "vs prior period" series rendered as dashed line                     |
+| Add **Top browsers / OS / devices** ranked-list cards          | new `<TopList>` consumers; service already exposes via `getMetric(type)` | mirror Top Pages/Referrers/Countries layout                                   |
+| **World choropleth heatmap** card (already queued separately)  | new `visitor-world-map.tsx` (Natural Earth topojson + react-simple-maps) | ~4-6h on its own                                                              |
+
+**Cumulative result:** Overview surface reads at ~80% parity with Umami's Overview.
+
+---
+
+### Phase 2 — Sessions surface (~4-5h)
+
+New `/website-analytics/sessions` tab + supporting service wrappers:
+
+| Task                                                                                                                     | File               | Effort  |
+| ------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------- |
+| Service: `getSessions(portId, range, opts)` → `/api/websites/:id/sessions` (paged)                                       | `umami.service.ts` | ~30 min |
+| Service: `getSession(portId, sessionId)` → single-session detail                                                         | `umami.service.ts` | ~15 min |
+| Service: `getSessionActivity(portId, sessionId, range)` → event timeline                                                 | `umami.service.ts` | ~15 min |
+| Service: `getSessionsWeekly(portId, range)` → hour-of-week heatmap                                                       | `umami.service.ts` | ~15 min |
+| API route: `/api/v1/website-analytics?metric=sessions[&sessionId=...]`                                                   | route.ts           | ~30 min |
+| UI: `sessions-table.tsx` — dense rows mirroring Umami (avatar + location flag + browser/OS/device icons + Last seen)     | new component      | ~2h     |
+| UI: `session-detail-sheet.tsx` — right-side Sheet drawer showing the session's full event timeline when a row is clicked | new component      | ~1h     |
+| UI: `weekly-heatmap-card.tsx` — 7×24 grid colour-scaled by session count, hover for tooltip                              | new component      | ~1h     |
+
+**Unlock:** rep can see "who is currently browsing right now, where from, on what device, what they're looking at" — directly actionable for sales follow-up.
+
+---
+
+### Phase 3 — Events surface (~3-4h, BLOCKED on Phase 4a)
+
+| Task                                                                                         | File               | Effort  |
+| -------------------------------------------------------------------------------------------- | ------------------ | ------- |
+| Service: `getEvents(portId, range, opts)` → `/events` paged list                             | `umami.service.ts` | ~30 min |
+| Service: `getEventsStats(portId, range)` → totals                                            | `umami.service.ts` | ~15 min |
+| Service: `getEventsSeries(portId, range, eventName, unit)` → per-event time-series           | `umami.service.ts` | ~15 min |
+| API route addition                                                                           | route.ts           | ~30 min |
+| UI: `events-tab.tsx` — list of event names with per-event count + spark + drill-in           | new component      | ~1.5h   |
+| UI: `event-detail-sheet.tsx` — single event's time-series chart + filter by payload property | new component      | ~1h     |
+
+**Dependency:** the marketing site must fire `umami.track(name, payload)` calls (Phase 4a). Without this, Events tab is empty.
+
+---
+
+### Phase 4 — Pixel tracking + link tracking + marketing-site event push
+
+**Phase 4a — Marketing-site event tracking (~2-3h on marketing repo)**
+
+Add `umami.track()` calls in the marketing site:
+
+- `inquiry-submitted` with `{berth, source}` payload — fires on EOI form submit
+- `brochure-download` with `{brochureId}` — fires on brochure download
+- `berth-detail-viewed` with `{berthId, mooring}` — fires on `/berths/[mooring]` page view
+- `phone-revealed` / `email-revealed` — fires when contact details are exposed
+
+These light up the Events tab + enable funnel analysis in Phase 5.
+
+**Phase 4b — Pixel-based email open tracking (~3-4h CRM-side)**
+
+Probe finding: Umami exposes pixel URLs at `https://analytics.portnimara.com/p/<slug>` — fetching the URL records an event. Use case: embed in HTML emails as a 1x1 image.
+
+**Two architecture options:**
+
+**Option A — One Umami pixel per email type** (simple, low fidelity)
+
+- Create a pixel manually in Umami for each templated email type (`portal-invite`, `eoi-sent`, `reservation-reminder`, etc.)
+- Embed the static pixel URL in each template
+- Pro: zero CRM-side code beyond template HTML. Open rates roll up in Umami by pixel.
+- Con: can't tell _which recipient_ opened — only aggregate counts per template.
+
+**Option B — One Umami pixel + CRM-side per-send tracking endpoint** (richer, recommended)
+
+- Build `GET /api/public/email-pixel/:sendId.gif` in our CRM that:
+  1. Returns a 1×1 transparent GIF
+  2. Records the open in `document_sends.opened_at` (already a table; per CLAUDE.md "send-from accounts" section)
+  3. Optionally proxies the hit to Umami via `POST /api/send` with the email type + send id as event properties for cross-correlation
+- Embed `<img src="https://crm.portnimara.com/api/public/email-pixel/{sendId}.gif" width="1" height="1" />` in every templated email
+- Pro: per-recipient open tracking + open-time + CRM-attached. Funnels by email type via Umami too.
+- Con: needs the public endpoint + a schema column (or reuse `document_sends.opened_at`).
+
+**Recommendation: ship Option B.** The CRM-side hook gives us per-deal attribution ("client X opened the EOI reminder twice but hasn't signed"), and Umami still gets the aggregate.
+
+| Task                                                                                                          | File                                           | Effort  |
+| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------- |
+| New endpoint `/api/public/email-pixel/[sendId]/route.ts` returning a 1×1 GIF + recording open                 | new route                                      | ~1h     |
+| Migration: add `opened_at`, `open_count`, `last_opened_user_agent` to `document_sends` if not present         | drizzle migration                              | ~30 min |
+| Email template helper: inject the pixel HTML into every transactional template                                | `src/lib/email/render.ts`                      | ~30 min |
+| UI surface: on each `document_sends` row in the activity feed, show "Opened N times, last at X" badge         | `email-activity-row.tsx`                       | ~1h     |
+| Cross-post to Umami via `trackEvent('email-opened', {emailType, sendId})` so Umami funnel data includes opens | new `trackEvent` wrapper in `umami.service.ts` | ~30 min |
+| Privacy: respect `EMAIL_REDIRECT_TO` dev gate; don't fire pixels for redirected dev emails                    | ditto                                          | ~15 min |
+
+**Phase 4c — Tracked redirect links (~1.5h)**
+
+Umami's `/q/<slug>` endpoint is a tracked redirect — records a click then 302s to the destination URL. Use for outbound CTAs:
+
+- "View brochure" links in emails → wrap via Umami link → records click → opens brochure
+- "Schedule a viewing" buttons → wrap via Umami link → click attribution
+- Marketing-site CTAs → wrap → measure engagement
+
+| Task                                                                                                                                        | File                        | Effort  |
+| ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------- |
+| Service: `createTrackedLink(name, destinationUrl)` → POST to Umami's links endpoint via authenticated API                                   | `umami.service.ts`          | ~45 min |
+| Email template helper: `<trackedLink href="..." name="...">` JSX wrapper that auto-creates the Umami link on first render + caches the slug | `src/lib/email/components/` | ~45 min |
+
+---
+
+### Phase 5 — Reports surfaces (Funnels, UTM, Journeys) (~6-8h)
+
+| Task                                                                                                                                           | File               | Effort |
+| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------ |
+| Service: `getReport(reportType, body)` POST wrapper covering `/funnel`, `/journey`, `/utm`, `/goals`, `/retention`, `/revenue`, `/attribution` | `umami.service.ts` | ~1h    |
+| UI: `/website-analytics/funnels` page — admin-configurable funnel definitions (steps as event names or URL paths), per-step drop-off chart     | new page           | ~3h    |
+| UI: `/website-analytics/utm` page — UTM source/medium/campaign breakdown with click-through to attributed sessions                             | new page           | ~2h    |
+| UI: `/website-analytics/journeys` page — top navigation paths rendered as ranked list (skip Sankey for v1)                                     | new page           | ~1.5h  |
+| Defer: Goals / Retention / Revenue / Attribution to v2 (low signal for marina sales)                                                           |                    |        |
+
+**High-leverage funnels to wire as defaults:**
+
+- **Inquiry funnel**: `/` → `/berths` → `/berths/[mooring]` → `inquiry-submitted` event → CRM `eoi-signed` (cross-system!) → CRM `reservation-paid` (cross-system!)
+- **Email funnel**: `email-sent` → `email-opened` (pixel) → tracked-link click → CRM action
+
+The cross-system funnels require Phase 4 to be live first.
+
+---
+
+### Phase 6 — CRM → Umami event push for outcome attribution (~2-3h)
+
+Close the funnel from "marketing site click" → "CRM closed deal" by firing CRM-side events back into Umami via `POST /api/send`:
+
+| Event                  | Fired by                                     | Payload                                 |
+| ---------------------- | -------------------------------------------- | --------------------------------------- |
+| `crm-inquiry-created`  | `createInterest()` in `interests.service.ts` | `{interestId, source, leadCategory}`    |
+| `crm-eoi-sent`         | `generateAndSign()` after EOI dispatch       | `{interestId, berth, pathway}`          |
+| `crm-eoi-signed`       | Documenso `DOCUMENT_COMPLETED` webhook       | `{interestId, berth}`                   |
+| `crm-reservation-paid` | manual stage advance to `deposit_paid`       | `{interestId, berth, amount, currency}` |
+| `crm-contract-signed`  | manual stage advance to `contract`           | `{interestId, berth, amount, currency}` |
+
+| Task                                                                                      | File                | Effort   |
+| ----------------------------------------------------------------------------------------- | ------------------- | -------- |
+| Service: `trackEvent(name, payload, sessionId?)` → `POST /api/send` on the Umami instance | `umami.service.ts`  | ~45 min  |
+| Hook into the 5 service entry points above (one event per outcome milestone)              | each service file   | ~1.5h    |
+| Audit log entry per event sent so we can verify Umami received it                         | `audit_logs` insert | included |
+
+**Unlock:** Umami's Revenue + Attribution reports start showing CRM outcomes attributed to marketing-site channels — closes the leadership question "which traffic sources actually generate signed deals, not just leads?"
+
+---
+
+### Phase 7 — Cross-cutting CRM placements (~3-4h)
+
+Beyond the dedicated `/website-analytics` page, surface Umami data inside CRM context:
+
+| Placement                                                                                                                                                                                                                                                                           | What                                     | Effort                               |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------ |
+| **Dashboard rail tile** (already shipped) — Pageviews + active now                                                                                                                                                                                                                  | already done in this session             | —                                    |
+| **Inquiry detail page** — "Source attribution" card showing the inquiry's UTM params, landing page, time-on-site, pages-viewed-before-submit. Pulls from `getSession(sessionId)` if the inquiry's create payload includes a session ID (requires marketing-site change to pass it). | new `inquiry-attribution-card.tsx`       | ~1.5h + marketing-site change        |
+| **Client detail page** — "Website activity" card: total sessions, pageviews, last-seen, top pages visited. Requires `umami.identify({email})` on marketing site to link sessions back to clients.                                                                                   | new `client-web-activity-card.tsx`       | ~1.5h + marketing-site identify call |
+| **Berth detail page** — "Marketing demand" card: pageviews to `/berths/{mooring}` over time + referrer breakdown. Drives "this berth is being viewed but not inquired-about — flag for outreach."                                                                                   | new `berth-demand-card.tsx`              | ~1h                                  |
+| **Document send activity** — pixel opens per recipient (from Phase 4b)                                                                                                                                                                                                              | inline on existing `document_sends` rows | included in 4b                       |
+
+---
+
+## 2b. Library adoptions (changes the plan materially)
+
+Context7 lookup surfaced three official libraries that reshape the plan. **Adopt all three.**
+
+### `@umami/api-client` — official read-side client
+
+Covers every read endpoint we need including all the report types. Built-in filter support, login/JWT auth handled internally, `{ok, data}` discriminated union for clean error handling.
+
+**Replaces:** ~60-70% of our current `umami.service.ts` (drop `umamiFetch`, JWT cache, decrypt boilerplate; keep thin wrappers with existing signatures so consumers don't change).
+
+**One-time refactor (~2h):**
+
+```ts
+const clientByPort = new Map<string, UmamiApiClient>();
+
+async function getClient(portId: string): Promise<UmamiApiClient | null> {
+  if (clientByPort.has(portId)) return clientByPort.get(portId)!;
+  const cfg = await loadUmamiConfig(portId);
+  if (!cfg) return null;
+  const client = new UmamiApiClient({
+    apiEndpoint: `${cfg.apiUrl}/api`,
+    apiKey: cfg.apiToken ?? undefined,
+  });
+  if (!cfg.apiToken && cfg.username && cfg.password) await client.login(cfg.username, cfg.password);
+  clientByPort.set(portId, client);
+  return client;
+}
+
+export async function getStats(portId: string, range: DateRange) {
+  const client = await getClient(portId);
+  if (!client) return null;
+  const { from, to } = rangeToBounds(range);
+  const result = await client.getWebsiteStats(WEBSITE_ID, {
+    startAt: from.getTime(),
+    endAt: to.getTime(),
+  });
+  return result.ok ? result.data : null;
+}
+```
+
+Same pattern for `getPageviewsSeries`, `getMetric`, `getActiveVisitors`, plus new ones from the SDK: `getRealtime`, `getWebsiteSessionStats`, `runFunnelReport`, `runJourneyReport`, etc.
+
+### `@umami/node` — official write-side SDK
+
+For Phase 6 (CRM → Umami push) and Phase 4b cross-post:
+
+```ts
+const umami = new Umami({ websiteId, hostUrl });
+await umami.track({
+  url: '/crm/eoi-signed',
+  name: 'crm-eoi-signed',
+  data: { interestId, berth, dealValue },
+});
+await umami.identify({ sessionId, email, interestId });
+```
+
+**Replaces:** the planned hand-rolled `trackEvent()` wrapper. Single line per outcome milestone.
+
+### `react-simple-maps` — for the world heatmap (Phase 1b)
+
+Declarative SVG choropleth on d3-geo + topojson-client. SSR-safe. Use `topojson/world-atlas` (110m resolution ~30KB) cached in `public/`. Bundle ~30-50KB + topojson 30-100KB.
+
+```jsx
+<ComposableMap projection="geoMercator">
+  <Geographies geography="/world-110m.json">
+    {({ geographies }) =>
+      geographies.map((geo) => (
+        <Geography
+          key={geo.rsmKey}
+          geography={geo}
+          fill={scaleByVisitorCount(visitorsByCountry[geo.properties.iso_a2] ?? 0)}
+          onClick={() => onCountryClick(geo.properties.iso_a2)}
+        />
+      ))
+    }
+  </Geographies>
+</ComposableMap>
+```
+
+**Chose this over visx/Nivo/Chart.js Geo:** visx is overkill for one map; Nivo + Chart.js force a different charting idiom (we use recharts everywhere); react-simple-maps' compose-primitives shape matches our recharts pattern.
+
+### Net effect on phase efforts
+
+| Phase                                    | Original estimate | Revised after library adoption                                  |
+| ---------------------------------------- | ----------------- | --------------------------------------------------------------- |
+| Service refactor (one-time)              | —                 | **+2h** (one-time foundation; pays back across all phases)      |
+| Phase 1 — Overview parity                | 3-4h              | 3-4h (unchanged; api-client makes the filter additions trivial) |
+| Phase 1b — World heatmap                 | 4-6h              | 3-4h (library choice locked in)                                 |
+| Phase 2 — Sessions                       | 4-5h              | 3-4h (api-client has session methods built-in)                  |
+| Phase 3 — Events                         | 3-4h              | 2-3h (api-client provides)                                      |
+| Phase 4b — Pixel hybrid                  | 3-4h              | 2.5-3h (cross-post is one line)                                 |
+| Phase 5 — Reports (funnels/UTM/journeys) | 6-8h              | 3-4h (every report method pre-wrapped)                          |
+| Phase 6 — CRM → Umami push               | 2-3h              | 1.5h (`@umami/node` handles transport)                          |
+
+**Total scope drops from ~30-40h to ~22-28h** with these adoptions.
+
+---
+
+## 3. Service-layer additions consolidated
+
+Add to `src/lib/services/umami.service.ts` (each is a thin wrapper around existing `umamiFetch` / new `umamiPost`):
+
+```ts
+// Sessions (Phase 2)
+getSessions(portId, range, { page?, pageSize?, query? }) → /sessions
+getSession(portId, sessionId) → /sessions/:id
+getSessionActivity(portId, sessionId, range) → /sessions/:id/activity
+getSessionProperties(portId, sessionId) → /sessions/:id/properties
+getSessionsWeekly(portId, range, timezone) → /sessions/weekly
+
+// Events (Phase 3)
+getEvents(portId, range, opts) → /events
+getEventsStats(portId, range) → /events/stats
+getEventsSeries(portId, range, eventName, unit) → /events/series
+getEventDataProperties(portId, range) → /event-data/properties
+
+// Realtime (Phase 1)
+getRealtime(portId, range) → /api/realtime/:id (richer than /active)
+
+// Reports (Phase 5)
+getReport(portId, reportType, body) → POST /api/reports/:type (funnel/journey/utm/goals/retention/revenue/attribution)
+
+// CRM → Umami (Phase 6)
+trackEvent(portId, name, payload, sessionId?) → POST /api/send
+
+// Links + Pixels admin (Phase 4)
+createTrackedLink(portId, name, destinationUrl) → POST team-level /links
+createTrackingPixel(portId, name) → POST team-level /pixels
+```
+
+Plus a new `umamiPost(config, path, body)` helper alongside the existing `umamiFetch` since GET-only doesn't cover reports + send.
+
+---
+
+## 4. Pixel-tracking answer (the user's specific question)
+
+**Q: Can we use Umami's pixel tracking for email opens?**
+
+**A: Yes — and recommended in hybrid form.** Direct verification on the live instance:
+
+- Pixel UI at `/teams/[teamId]/pixels` lets an admin create named pixels. Each gets an auto-generated slug.
+- The pixel URL is `https://analytics.portnimara.com/p/<slug>` — fetching it records an event (no auth required from the email client side; the slug is the credential).
+- Embedded as `<img src="..." width="1" height="1" />` in HTML emails, it fires when the email is rendered (Outlook/Apple Mail/etc.).
+- Standard caveats: Apple Mail privacy protection pre-fetches images server-side → opens may be over-counted for iOS users. Some recipients block images entirely → opens under-counted. Same caveats as every email tracking pixel ever.
+
+**Recommended hybrid (Phase 4b above):** build a CRM-side pixel endpoint `/api/public/email-pixel/[sendId].gif` that:
+
+- Returns the 1×1 GIF
+- Records `opened_at` in `document_sends`
+- Cross-posts the hit to Umami via `POST /api/send` so the Umami Events tab + funnels include opens
+
+This way: per-recipient attribution in the CRM, aggregate roll-ups in Umami, single source of truth for both.
+
+---
+
+## 5. Effort summary + prioritization
+
+| Phase | Scope                                                                                | Effort                 | Priority                                                     |
+| ----- | ------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------ |
+| 1     | Overview parity (KPI tiles, stacked-bar chart, date arrows, browser/OS/device cards) | ~3-4h                  | **High** — most visible polish, no dependencies              |
+| 1b    | World choropleth heatmap (already queued separately)                                 | ~4-6h                  | **High** if leadership wants the visual                      |
+| 2     | Sessions surface (table + detail sheet + weekly heatmap)                             | ~4-5h                  | **High** — biggest "wow" + actionable                        |
+| 3     | Events surface                                                                       | ~3-4h                  | **Medium** — blocked on 4a                                   |
+| 4a    | Marketing-site event tracking                                                        | ~2-3h (marketing repo) | **High** — unblocks 3 + 5                                    |
+| 4b    | Pixel-based email open tracking (hybrid)                                             | ~3-4h                  | **High** — direct ask + immediate value                      |
+| 4c    | Tracked redirect links                                                               | ~1.5h                  | **Medium**                                                   |
+| 5     | Reports (Funnels, UTM, Journeys)                                                     | ~6-8h                  | **Medium** — depends on 4a being live                        |
+| 6     | CRM → Umami event push for outcome attribution                                       | ~2-3h                  | **Medium-high** — needed to close marketing→outcome loop     |
+| 7     | Cross-cutting placements (inquiry / client / berth detail cards)                     | ~3-4h                  | **Medium** — depends on `umami.identify()` on marketing site |
+
+**Recommended build order (updated 2026-05-19 per user):**
+
+1. ✅ **Service refactor** — Kept hand-rolled `umamiFetch` (the official `@umami/api-client` transitively pulls `next-basics` which requires React at module-import time, breaking SSR + tsx scripts). Adopted `@umami/node` for the write side.
+2. ✅ **Phase 1** — Overview parity (KPI tiles + browser/OS/device cards + date arrows + stacked-bar chart + `compare=prev` overlay)
+3. ✅ **Phase 1b** — World heatmap. **Switched from `react-simple-maps` to ECharts + `public/world-map/echarts-world.json`** — the `world-atlas/110m` topojson has antimeridian-crossing polygons (Russia/Fiji/Antarctica) that render a horizontal line through the equator regardless of projection. ECharts' world.json is pre-cleaned.
+4. ✅ **Phase 4b** — Pixel-based email open tracking. `document_send_opens` table + `/api/public/email-pixel/[sendId]` endpoint + `injectTrackingPixel` helper wired into `performSend`. Per-port kill switch `email_open_tracking_enabled` (admin UI on `/admin/website-analytics`). Cross-posts to Umami as `email-opened`.
+5. ✅ **Phase 2** — Sessions surface. `SessionsList` (paginated, click-through to detail), `SessionDetailSheet` (full activity stream), `WeeklyHeatmap` (7×24 grid). API endpoints `sessions`, `session`, `session-activity`, `sessions-weekly`.
+6. ✅ **Phase 6** — CRM → Umami event push. `trackEvent` calls wired into `createInterest` (`interest-created`), `updateInterestStage` (`interest-stage-changed`), `setInterestOutcome` (`interest-outcome-set`).
+7. ✅ **Phase 7** — Cross-cutting placements. `email-sent` (in `performSend`), `eoi-signed` (in `handleDocumentCompleted`). Remaining placements (inquiry / berth detail attribution cards) defer until UI surfaces them.
+8. ✅ **Phase 4c** — Tracked redirect links. `tracked_links` + `tracked_link_clicks` tables + `/q/[slug]` redirect endpoint + `createTrackedLink` / `buildTrackedUrl` service helpers. Email-composer integration deferred to UI follow-up.
+9. **Phase 3 + Phase 5 — DEFERRED to the end.** Events tab is empty until marketing-site `umami.track()` calls land (Phase 4a, deferred). Funnels save for the end per user direction — pageview-only marketing funnel is the v1; richer event-based funnels come later.
+10. **Phase 4a + cross-system funnels** — when there's appetite for marketing-site repo changes, unlock Events tab + cross-system funnels.
+
+**Total scope: ~22-28h** with library adoptions, of which ~13-15h is the high-priority Phases 1 + 1b + 4b + 2 + 6 that ship first.
+
+Total scope: ~30-40h end-to-end for the full flesh-out.
+
+---
+
+## 6. What stays in Umami vs. mirrored in CRM
+
+| In CRM (mirror)                                             | In Umami only (deep-link)                                         |
+| ----------------------------------------------------------- | ----------------------------------------------------------------- |
+| Overview / KPI tiles / trend chart                          | Replays (paid)                                                    |
+| Sessions list + detail                                      | Retention (low signal)                                            |
+| Top pages / referrers / countries / browsers / OS / devices | Saved Boards (admin power-user)                                   |
+| Events + per-event drill                                    | Pixels/Links admin CRUD (use Umami for setup; render data in CRM) |
+| Funnels + UTM + Journeys                                    | Performance / Web Vitals                                          |
+| World heatmap                                               | Cohorts / Segments (defer until use case emerges)                 |
+| Email open tracking                                         | Multi-website CRUD                                                |
+
+Every page header in the CRM analytics surface gets a small "View in Umami →" outbound link in the corner for power users who want the full feature surface.
+
+---
+
+## 7. Open questions for the user before implementation
+
+1. **Marketing site repo access**: Phase 4a (umami.track calls), Phase 4 (umami.identify for client linkage), and Phase 7 (passing sessionId to inquiry intake) all require changes there. Confirm whoever owns the marketing site is in the loop.
+2. **Pixel hybrid vs Umami-only**: do you want per-recipient open tracking (hybrid) or just aggregate (Umami-only)? Recommended hybrid above; switch to Umami-only if the engineering cost isn't worth it.
+3. **Funnel definitions**: who defines the canonical funnels? Suggest admins set them up via a CRM-side admin page that POSTs to Umami's `/api/reports/funnel`, with the most important funnels (inquiry, email-conversion) seeded as defaults at install time.
+4. **Privacy / GDPR**: email pixel tracking + `umami.identify({email})` linkage both touch PII. Confirm consent model — likely already handled by the marketing-site cookie banner, but the email pixel needs explicit opt-out handling (e.g. don't fire pixel if the recipient is in a do-not-track list).

docs/website-cutover-runbook.md

@@ -0,0 +1,124 @@
+# Website ↔ CRM cutover runbook
+
+This document captures the agreed plan (per the 2026-05-09 audit, Q6) for
+moving the marketing website off the legacy NocoDB Berths table and onto
+the CRM as the source of truth. Decision: **double-write transition
+window** — both feeds stay live for ~30 days, then NocoDB is decommissioned.
+
+The CRM side is fully wired today. Most outstanding work lives in the
+**website repo**.
+
+---
+
+## Endpoints involved
+
+### Public berth feed (replaces NocoDB Berths read path)
+
+- `GET /api/public/berths` — list (NocoDB-verbatim shape; see
+  `src/lib/services/public-berths.ts`)
+- `GET /api/public/berths/[mooringNumber]` — single
+- Cache: `s-maxage=300, stale-while-revalidate=60` (5 min)
+- Status mapping: `Sold` > `Under Offer` > `Available`
+
+### Public inquiry intake (replaces NocoDB inquiry write path)
+
+- `POST /api/public/website-inquiries` — accepts inquiry form submissions
+  from the marketing site
+- Auth: shared secret in `X-Intake-Secret` header, compared via timing-safe
+  equality against `WEBSITE_INTAKE_SECRET`. Refuses every request when the
+  env var is unset (correct posture for dev / staging until the website is
+  also configured).
+
+### Health endpoint (monitoring contract)
+
+- `GET /api/public/health` — anonymous: `{status, timestamp}` (always 200,
+  for uptime monitors). Authenticated with `X-Intake-Secret`: full
+  `{status, env, appUrl, timestamp, checks: {db, redis}}` payload, returns
+  503 when any dependency is down. The website calls the authenticated
+  variant on startup so it refuses to boot when its `CRM_PUBLIC_URL`
+  points at the wrong env.
+
+---
+
+## Pre-cutover checklist (CRM side — done)
+
+- [x] `/api/public/berths` serves Map Data (117 rows backfilled
+      2026-05-09).
+- [x] PublicBerth payload exposes verbatim NocoDB fields, plus
+      booleans / metric variants / timestamps (commit `72ab718`). Price
+      intentionally omitted (decision Q4).
+- [x] `/api/public/website-inquiries` POST handler exists, gated on
+      `WEBSITE_INTAKE_SECRET`.
+- [x] `WEBSITE_INTAKE_SECRET` documented in `.env.example`.
+
+## Pre-cutover checklist (website repo — owed)
+
+- [ ] Generate a strong shared secret (`openssl rand -hex 32`) and set
+      `CRM_INTAKE_SECRET` (website) **and** `WEBSITE_INTAKE_SECRET` (CRM)
+      to the same value in production.
+- [ ] Wire the website's berth-map fetch to `${CRM_PUBLIC_URL}/api/public/berths`.
+      Keep the existing NocoDB fetch in parallel for the transition window.
+- [ ] Wire the website's inquiry submit handler to `POST` to
+      `${CRM_PUBLIC_URL}/api/public/website-inquiries` with the
+      `X-Intake-Secret` header. Keep the existing NocoDB write in parallel.
+- [ ] Add a startup probe to `${CRM_PUBLIC_URL}/api/public/health`
+      (authenticated) so the website fails fast on misconfigured env.
+
+## Double-write window (target: 30 days)
+
+During the window:
+
+1. Marketing site reads from BOTH feeds for any change-detection or
+   reconciliation jobs (or just CRM if reads can flip atomically).
+2. Marketing site writes inquiries to BOTH NocoDB and CRM. The CRM
+   surface is treated as authoritative for triage; NocoDB stays as a
+   passive backup so the rollback path is one DNS / env flip away.
+3. Berth status edits made in CRM are NOT synced back to NocoDB.
+   NocoDB will progressively go stale — accepted because the website is
+   already preferring the CRM read. NocoDB stays usable as a snapshot of
+   pre-cutover state.
+4. Daily sanity check: `curl -s ${CRM_PUBLIC_URL}/api/public/berths | jq '.pageInfo'`
+   — confirms the public feed still serves and the row count matches
+   expectations (117 berths in port-nimara).
+
+## Cutover steps (target: ~Day 30)
+
+1. Stop the NocoDB-side writes from the website (drop the dual write).
+2. Stop the NocoDB-side reads from the website (CRM-only).
+3. Mark the NocoDB Berths table read-only via NocoDB ACL.
+4. Wait 7 days; if no one notices anything missing, drop the NocoDB
+   Berths table and revoke the NocoDB MCP token from `~/.claude.json`.
+
+## Rollback path
+
+The double-write design means rollback within the 30-day window is a
+single env / DNS flip:
+
+- Website: change `CRM_PUBLIC_URL` to the old NocoDB-fronted URL OR
+  toggle a feature flag back to NocoDB.
+- CRM: no change required — the public endpoints stay live for any
+  consumer that didn't roll back.
+
+After NocoDB is decommissioned, rollback requires restoring the table
+from backup. That's the trade-off for the cleaner final state.
+
+---
+
+## Open follow-ups
+
+- **Berth `archived_at`** — when retiring a berth, the public feed will
+  still serve it. Add a soft-delete column + filter on
+  `/api/public/berths` before any berth is permanently removed. (Not
+  blocking the cutover; flagged in the audit.)
+- **CRM-edit drift vs re-imports** — `scripts/import-berths-from-nocodb.ts`
+  skips rows where `updated_at > last_imported_at`. After cutover the
+  website MUST stop writing to NocoDB; if any straggler write hits
+  NocoDB and someone re-runs the import script, those edits would
+  silently win over CRM data. Mitigation: the script is opt-in, and the
+  `updated_at` guard means a full re-import only overwrites when the
+  rep explicitly passes `--force`. Decommission the script once cutover
+  is irreversible.
+- **5-minute cache** — `s-maxage=300` on `/api/public/berths` means a
+  CRM-side status flip won't show on the website for up to 5 minutes.
+  Acceptable for marketing; bump if marketing wants near-real-time
+  updates.

eslint.config.mjs

@@ -1,27 +1,85 @@
-import { dirname } from "path";
-import { fileURLToPath } from "url";
-import { FlatCompat } from "@eslint/eslintrc";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-});
+import nextCoreWebVitals from 'eslint-config-next/core-web-vitals';
+import prettier from 'eslint-config-prettier/flat';
 
 const eslintConfig = [
-  ...compat.extends("next/core-web-vitals", "next/typescript", "prettier"),
+  ...nextCoreWebVitals,
+  prettier,
   {
+    // Scope the typescript-eslint rule overrides to TS/TSX files. Without
+    // the `files` filter, eslint flat-config attempts to apply these
+    // rules to every walked file (including root-level JS / mjs / json
+    // configs) and fails because the typescript-eslint plugin only
+    // registers itself for TS/TSX. Surfaced 2026-05-14 when CI's
+    // `pnpm lint` command ran across the whole repo root.
+    files: ['**/*.ts', '**/*.tsx'],
     rules: {
-      "@typescript-eslint/no-explicit-any": "error",
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        { argsIgnorePattern: "^_" },
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      // React Compiler safety rules shipped with eslint-config-next@16 /
+      // react-hooks@7. Triage status (2026-05-13 sweep):
+      //   purity, set-state-in-render, immutability, refs,
+      //   set-state-in-effect — promoted to error after the cleanup
+      //   sweep (Wave 3 of the 2026-05-12 audit). All hits migrated to
+      //   either useQuery, render-phase derivation, key-based remount,
+      //   or a justified eslint-disable for canonical setState-on-
+      //   subscription patterns. New regressions block CI.
+      //   incompatible-library — informational only ("Compiler
+      //   skipped this file because of a non-Compiler-safe import").
+      //   No action needed; silenced to keep `pnpm lint` output
+      //   actionable.
+      'react-hooks/purity': 'error',
+      'react-hooks/set-state-in-render': 'error',
+      'react-hooks/immutability': 'error',
+      'react-hooks/refs': 'error',
+      'react-hooks/set-state-in-effect': 'error',
+      'react-hooks/incompatible-library': 'off',
+    },
+  },
+  {
+    // User-facing copy in src/components and src/app should never use
+    // em-dashes (—) in JSX text. The user reads em-dashes as a
+    // tell-tale "AI-generated" marker; we prefer periods, commas, or
+    // simple hyphens. Code comments / audit-log strings / templates
+    // outside these directories are exempt.
+    files: ['src/components/**/*.tsx', 'src/app/**/*.tsx'],
+    rules: {
+      'no-restricted-syntax': [
+        // Bumped from warn → error after the 2026-05-21 sweep cleared
+        // the existing 108 instances. New code reintroducing em-dashes
+        // now fails the lint gate.
+        'error',
+        {
+          selector: "JSXText[value=/\\u2014/]",
+          message:
+            'No em-dash in user-facing JSX text. Use period, comma, or hyphen instead.',
+        },
       ],
     },
   },
   {
-    ignores: ["client-portal/**"],
+    // Tests assert response shape via expect() — narrowing every
+    // `res.json()` to a structural type adds boilerplate without catching
+    // bugs. Allow `any` casts at JSON boundaries in test files. Also
+    // relax unused-vars to warn (destructured-but-unused helpers are
+    // common in setup/teardown patterns).
+    files: ['tests/**/*.ts', 'tests/**/*.tsx'],
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    ignores: [
+      'client-portal/**',
+      'next-env.d.ts',
+      // Agent worktree artifacts — not part of the canonical tree.
+      '.claude/**',
+      // Build output + Next generated types
+      '.next/**',
+      'dist/**',
+      // Other sub-projects with their own toolchains
+      'website/**',
+    ],
   },
 ];
 

instrumentation.ts

@@ -0,0 +1,20 @@
+/**
+ * Next.js instrumentation hook (Next 13.4+ / 15+ / 16+).
+ *
+ * Runs once at server startup. We use it to wire Sentry's server +
+ * edge runtimes. The client init is auto-bundled by withSentryConfig
+ * from `sentry.client.config.ts`.
+ *
+ * The Sentry imports are gated behind the DSN check so the SDK stays
+ * a no-op when unconfigured.
+ */
+
+export async function register() {
+  if (!process.env.NEXT_PUBLIC_SENTRY_DSN) return;
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('./sentry.server.config');
+  }
+  if (process.env.NEXT_RUNTIME === 'edge') {
+    await import('./sentry.edge.config');
+  }
+}

messages/en.json

@@ -0,0 +1,9 @@
+{
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel",
+    "delete": "Delete",
+    "edit": "Edit",
+    "back": "Back"
+  }
+}

next-env.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

next.config.ts

@@ -1,7 +1,102 @@
 import type { NextConfig } from 'next';
+import bundleAnalyzer from '@next/bundle-analyzer';
+import createNextIntlPlugin from 'next-intl/plugin';
+import { withSentryConfig } from '@sentry/nextjs';
+
+// next-intl plugin — points at our request-config entrypoint. Even
+// though we ship only English today, the plugin is wired so future
+// locale additions are a config-only change, not a code rewrite.
+const withNextIntl = createNextIntlPlugin('./src/i18n/request.ts');
+
+const isProd = process.env.NODE_ENV === 'production';
+
+// Wrap the config with the bundle analyzer. Run `ANALYZE=true pnpm build`
+// to get treemaps of the client + server bundles after the build
+// completes. Pairs with the recharts dynamic-import work the audit
+// flagged — gives us the tool to verify chart bundles only ship on the
+// dashboard surface and not on routes that don't render them.
+const withBundleAnalyzer = bundleAnalyzer({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+/**
+ * Security headers applied to every response. Per audit-pass-#3 finding:
+ * the previous config emitted no CSP, X-Frame-Options, HSTS, or
+ * X-Content-Type-Options — the app was open to clickjacking + MIME
+ * sniffing.
+ *
+ * CSP notes:
+ *   - 'unsafe-inline' on style-src is required by Tailwind's runtime
+ *     style injection and Radix; revisit when Tailwind v4 ships a
+ *     nonce story.
+ *   - 'unsafe-eval' on script-src is dev-only — Next dev uses eval for
+ *     HMR. Production drops it.
+ *   - connect-src allows ws/wss for Socket.IO and https: for outgoing
+ *     fetches; tighten in prod via per-port branding URLs once we move
+ *     the s3 image references into a known allowlist.
+ *   - img-src https: is wide because port branding pulls from
+ *     s3.portnimara.com plus per-port image URLs configured at runtime.
+ */
+// Dev-only allow-list: react-grab (the in-page click-to-source devtool)
+// is fetched from unpkg, so script/style/connect must allow it. Strip
+// these entries in prod via the conditional below.
+const devScriptHosts = isProd ? '' : ' http://unpkg.com https://unpkg.com';
+const devConnectHosts = isProd ? '' : ' http://unpkg.com https://unpkg.com';
+
+// Fallback CSP for paths the proxy doesn't run on (static assets,
+// API JSON responses where script-src is moot). Production HTML
+// responses get a stricter per-request nonce-based CSP set in
+// `src/proxy.ts:applyCsp`; this header just provides a sane default
+// so a misconfigured static-only route still has a CSP.
+//
+// Dev keeps 'unsafe-inline' + 'unsafe-eval' on script-src because
+// Next's HMR runtime evaluates code dynamically and the nonce
+// machinery doesn't reach it.
+const csp = [
+  "default-src 'self'",
+  `script-src 'self' 'unsafe-inline'${isProd ? '' : " 'unsafe-eval'"}${devScriptHosts}`,
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: blob: https:",
+  "font-src 'self' data:",
+  `connect-src 'self' ws: wss: https:${devConnectHosts}`,
+  "frame-ancestors 'none'",
+  "base-uri 'self'",
+  "form-action 'self'",
+  "object-src 'none'",
+].join('; ');
+
+const securityHeaders = [
+  { key: 'Content-Security-Policy', value: csp },
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy', value: 'camera=(self), microphone=(), geolocation=()' },
+  ...(isProd
+    ? [{ key: 'Strict-Transport-Security', value: 'max-age=31536000; includeSubDomains' }]
+    : []),
+];
 
 const nextConfig: NextConfig = {
   output: 'standalone',
+  // Hide the floating dev indicator (the little circle/N badge in the
+  // corner). Compile errors still surface via the full overlay; this
+  // only removes the idle "everything is fine" indicator that's been
+  // visible in every screenshot from the iPhone testing pass.
+  devIndicators: false,
+  // LAN access from a real iPhone hits the dev server via the Mac's
+  // local IP (e.g. 192.168.x.x), not localhost. Next surfaces a warning
+  // and blocks cross-origin /_next/* fetches (incl. HMR) unless we
+  // allow-list the origins explicitly. When HMR is blocked the page
+  // never fully hydrates and form click handlers fall back to native
+  // submits — the symptom that bit us with a hard-coded IP. Wildcards
+  // cover any LAN device without a per-network config edit.
+  ...(isProd ? {} : { allowedDevOrigins: ['192.168.*.*', '10.*.*.*', '172.16.*.*', '172.20.*.*'] }),
+  // Native/CJS-leaning server-only packages — list here so Next doesn't
+  // bundle them into the route trace (slower cold start + risk that
+  // native bindings fail at runtime). Build-auditor C3+M3: socket.io
+  // is only imported by the custom server entry point, so the Next
+  // tracer has no reason to include it; listing here makes the
+  // dependency visible to the build system.
   serverExternalPackages: [
     'pino',
     'pino-pretty',
@@ -11,19 +106,69 @@ const nextConfig: NextConfig = {
     'postgres',
     'better-auth',
     'nodemailer',
+    'socket.io',
+    '@socket.io/redis-adapter',
+    'imapflow',
+    'mailparser',
+    'pdf-lib',
+    'sharp',
+    'tesseract.js',
+    '@react-pdf/renderer',
+    'unpdf',
   ],
   images: {
     remotePatterns: [{ protocol: 'https', hostname: '*.portnimara.com' }],
   },
-  experimental: {
-    typedRoutes: true,
-  },
+  typedRoutes: true,
+  // ECharts ships ES modules that older Next/webpack versions can't parse
+  // without a transpile-pass. Listing here is the official recommendation
+  // from echarts-for-react when used inside Next.
+  transpilePackages: ['echarts', 'zrender', 'echarts-for-react'],
   outputFileTracingIncludes: {
     // Bundle the EOI source PDF so the in-app EOI pathway can read it at
     // runtime in the standalone build. Reading via fs.readFile from
     // process.cwd() requires the file to be traced explicitly.
     '/api/v1/document-templates/**': ['./assets/eoi-template.pdf'],
   },
+  async redirects() {
+    return [
+      {
+        source: '/:portSlug/documents/files',
+        destination: '/:portSlug/documents',
+        permanent: true,
+      },
+      {
+        source: '/:portSlug/documents/files/:path*',
+        destination: '/:portSlug/documents',
+        permanent: true,
+      },
+    ];
+  },
+  async headers() {
+    return [
+      {
+        source: '/:path*',
+        headers: securityHeaders,
+      },
+    ];
+  },
 };
 
-export default nextConfig;
+// Sentry wrapper is conditional: if NEXT_PUBLIC_SENTRY_DSN isn't set we
+// skip its build-time source-map upload + middleware injection so dev
+// builds stay fast and CI doesn't need credentials. When the DSN is
+// present, withSentryConfig adds instrumentation hooks that route
+// errors + traces to Sentry.
+const withSentry = process.env.NEXT_PUBLIC_SENTRY_DSN
+  ? (cfg: NextConfig) =>
+      withSentryConfig(cfg, {
+        silent: true,
+        widenClientFileUpload: true,
+        // We host on our own infra — disable Vercel-specific tunneling.
+        tunnelRoute: undefined,
+        // Strip Sentry debug logger from prod bundle.
+        disableLogger: true,
+      })
+  : (cfg: NextConfig) => cfg;
+
+export default withSentry(withBundleAnalyzer(withNextIntl(nextConfig)));

nginx/conf.d/proxy_params.conf

@@ -4,6 +4,10 @@ proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header Connection "";
+# Defense-in-depth for CVE-2025-29927: strip the header attackers use to
+# skip Next.js middleware. Patched in next>=15.2.3, but neutralizing the
+# input at the edge means a future regression cannot reopen the bypass.
+proxy_set_header X-Middleware-Subrequest "";
 proxy_cache_bypass $http_upgrade;
 proxy_read_timeout 60s;
 proxy_send_timeout 60s;

package.json

@@ -2,39 +2,48 @@
   "name": "port-nimara-crm",
   "version": "0.1.0",
   "private": true,
+  "packageManager": "pnpm@10.33.2",
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev --turbopack -H 0.0.0.0",
     "build": "next build && pnpm build:server",
     "build:server": "esbuild src/server.ts --bundle --platform=node --target=node20 --format=cjs --outdir=dist --packages=external --tsconfig=tsconfig.server.json",
     "build:worker": "esbuild src/worker.ts --bundle --platform=node --target=node20 --format=cjs --outdir=dist --packages=external --tsconfig=tsconfig.server.json",
     "start": "next start",
-    "lint": "next lint",
+    "lint": "eslint .",
     "format": "prettier --write \"src/**/*.{ts,tsx,json,css}\"",
     "db:generate": "drizzle-kit generate",
     "db:push": "drizzle-kit push",
+    "db:migrate": "tsx scripts/db-migrate.ts apply",
+    "db:migrate:status": "tsx scripts/db-migrate.ts status",
+    "db:migrate:baseline": "tsx scripts/db-migrate.ts baseline",
     "db:studio": "drizzle-kit studio",
     "db:seed": "tsx src/lib/db/seed.ts",
+    "db:seed:realistic": "tsx src/lib/db/seed.ts",
+    "db:seed:synthetic": "tsx src/lib/db/seed-synthetic.ts",
+    "db:seed:wide-synthetic": "tsx src/lib/db/seed-wide-synthetic.ts",
+    "db:reset": "tsx scripts/db-reset.ts --confirm",
+    "db:reseed:realistic": "pnpm db:reset && pnpm db:seed:realistic",
+    "db:reseed:synthetic": "pnpm db:reset && pnpm db:seed:synthetic",
+    "db:backfill:doc-folders": "tsx scripts/backfill-document-folders.ts",
     "test:e2e": "playwright test",
     "test:e2e:smoke": "playwright test --project=smoke",
     "test:e2e:exhaustive": "playwright test --project=exhaustive",
     "test:e2e:destructive": "playwright test --project=destructive",
-    "prepare": "husky"
+    "prepare": "husky || true"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@hookform/resolvers": "^3.9.0",
-    "@pdfme/common": "^5.5.8",
-    "@pdfme/generator": "^5.5.8",
-    "@pdfme/schemas": "^5.5.8",
+    "@formkit/auto-animate": "^0.9.0",
+    "@hookform/resolvers": "^5.2.2",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-alert-dialog": "^1.1.15",
     "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-icons": "^1.3.0",
+    "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-navigation-menu": "^1.2.14",
     "@radix-ui/react-popover": "^1.1.15",
@@ -48,75 +57,127 @@
     "@radix-ui/react-switch": "^1.2.6",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "@react-email/components": "^1.0.12",
+    "@react-pdf/renderer": "^4.5.1",
+    "@sentry/nextjs": "^10.53.1",
     "@socket.io/redis-adapter": "^8.3.0",
-    "@tanstack/react-query": "^5.62.0",
-    "@tanstack/react-query-devtools": "^5.62.0",
+    "@tanstack/query-broadcast-client-experimental": "^5.100.10",
+    "@tanstack/react-query": "^5.100.10",
+    "@tanstack/react-query-devtools": "^5.100.10",
     "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "^3.13.24",
+    "@types/pdfkit": "^0.17.6",
+    "@umami/node": "^0.4.0",
+    "@use-gesture/react": "^10.3.1",
     "archiver": "^7.0.1",
-    "better-auth": "^1.2.0",
-    "bullmq": "^5.25.0",
-    "class-variance-authority": "^0.7.0",
+    "better-auth": "^1.6.11",
+    "browser-image-compression": "^2.0.2",
+    "bullmq": "^5.76.8",
+    "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "cron-parser": "^5.5.0",
     "date-fns": "^4.1.0",
-    "drizzle-orm": "^0.38.0",
-    "imapflow": "^1.2.13",
-    "ioredis": "^5.4.0",
+    "drizzle-orm": "^0.45.2",
+    "echarts": "^6.0.0",
+    "echarts-for-react": "^3.0.6",
+    "embla-carousel-react": "^8.6.0",
+    "imapflow": "^1.3.3",
+    "ioredis": "^5.10.1",
     "iso-3166-2": "^1.0.0",
-    "jose": "^6.2.1",
-    "libphonenumber-js": "^1.12.42",
-    "lucide-react": "^0.460.0",
-    "mailparser": "^3.9.4",
-    "minio": "^8.0.0",
-    "next": "15.1.0",
-    "next-themes": "^0.4.0",
-    "nodemailer": "^6.9.0",
-    "openai": "^6.27.0",
+    "isomorphic-dompurify": "^3.12.0",
+    "jose": "^6.2.3",
+    "libphonenumber-js": "^1.13.1",
+    "lucide-react": "^1.14.0",
+    "mailparser": "^3.9.8",
+    "minio": "^8.0.7",
+    "motion": "^12.38.0",
+    "next": "16.2.6",
+    "next-intl": "^4.11.2",
+    "next-themes": "^0.4.6",
+    "nodemailer": "^8.0.7",
+    "openai": "^6.37.0",
+    "p-limit": "^7.3.0",
+    "p-queue": "^9.2.0",
+    "p-retry": "^8.0.0",
+    "papaparse": "^5.5.3",
     "pdf-lib": "^1.17.1",
-    "pino": "^9.5.0",
-    "pino-pretty": "^13.0.0",
-    "postgres": "^3.4.0",
-    "react": "^19.0.0",
-    "react-day-picker": "^9.14.0",
-    "react-dom": "^19.0.0",
-    "react-hook-form": "^7.54.0",
-    "recharts": "^3.8.0",
-    "socket.io": "^4.8.0",
-    "socket.io-client": "^4.8.0",
-    "sonner": "^1.7.0",
-    "tailwind-merge": "^2.6.0",
-    "tailwindcss-animate": "^1.0.7",
+    "pdfjs-dist": "^5.7.284",
+    "pdfkit": "^0.18.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "postgres": "^3.4.9",
+    "react": "^19.2.6",
+    "react-day-picker": "^10.0.0",
+    "react-dom": "^19.2.6",
+    "react-easy-crop": "^5.5.7",
+    "react-email": "^6.1.3",
+    "react-hook-form": "^7.75.0",
+    "react-image-crop": "^11.0.10",
+    "react-number-format": "^5.4.5",
+    "react-pdf": "^10.4.1",
+    "react-resizable-panels": "^3.0.6",
+    "react-virtuoso": "^4.18.7",
+    "recharts": "^3.8.1",
+    "sharp": "^0.34.5",
+    "socket.io": "^4.8.3",
+    "socket.io-client": "^4.8.3",
+    "sonner": "^2.0.7",
+    "svgo": "^4.0.1",
+    "tailwind-merge": "^3.6.0",
     "tesseract.js": "^7.0.0",
+    "ts-pattern": "^5.9.0",
+    "tw-animate-css": "^1.4.0",
+    "unpdf": "^1.6.2",
     "vaul": "^1.1.2",
-    "zod": "^3.24.0",
-    "zustand": "^5.0.0"
+    "web-vitals": "^5.2.0",
+    "yet-another-react-lightbox": "^3.32.0",
+    "zod": "^4.4.3",
+    "zustand": "^5.0.13"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3.3.5",
-    "@playwright/test": "^1.58.2",
+    "@axe-core/playwright": "^4.11.3",
+    "@faker-js/faker": "^10.4.0",
+    "@hookform/devtools": "^4.4.0",
+    "@next/bundle-analyzer": "^16.2.6",
+    "@playwright/test": "^1.60.0",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@total-typescript/ts-reset": "^0.6.1",
     "@types/archiver": "^7.0.0",
+    "@types/geojson": "^7946.0.16",
     "@types/iso-3166-2": "^1.0.4",
     "@types/mailparser": "^3.4.6",
-    "@types/node": "^22.0.0",
-    "@types/nodemailer": "^6.4.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "autoprefixer": "^10.4.27",
-    "dotenv": "^17.3.1",
-    "drizzle-kit": "^0.30.0",
-    "esbuild": "^0.25.0",
-    "eslint": "^9.0.0",
-    "eslint-config-next": "15.1.0",
-    "eslint-config-prettier": "^9.1.0",
-    "husky": "^9.1.0",
-    "lint-staged": "^15.2.0",
-    "postcss": "^8.4.0",
-    "prettier": "^3.4.0",
-    "react-grab": "^0.1.32",
-    "tailwindcss": "^3.4.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "vitest": "^4.1.0"
+    "@types/node": "^20.19.0",
+    "@types/nodemailer": "^8.0.0",
+    "@types/papaparse": "^5.5.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/topojson-client": "^3.1.5",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^4.1.6",
+    "dotenv": "^17.4.2",
+    "drizzle-kit": "^0.31.10",
+    "drizzle-zod": "^0.8.3",
+    "esbuild": "^0.28.0",
+    "eslint": "^9.39.4",
+    "eslint-config-next": "16.2.6",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.4",
+    "postcss": "^8.5.14",
+    "prettier": "^3.8.3",
+    "react-grab": "^0.1.34",
+    "tailwindcss": "^4.3.0",
+    "tsx": "^4.21.0",
+    "type-fest": "^5.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "8.0.5",
+      "esbuild": ">=0.25.0",
+      "postcss": ">=8.5.10"
+    }
   }
 }

postcss.config.mjs

@@ -1,8 +1,7 @@
 /** @type {import('postcss-load-config').Config} */
 const config = {
   plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
+    '@tailwindcss/postcss': {},
   },
 };
 

public/manifest.json

@@ -0,0 +1,30 @@
+{
+  "name": "Port Nimara CRM",
+  "short_name": "Port Nimara",
+  "description": "Marina/port management CRM",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#f2f2f2",
+  "theme_color": "#0f172a",
+  "orientation": "any",
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icon-512-maskable.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ]
+}

scripts/backfill-document-folders.ts

@@ -0,0 +1,246 @@
+/**
+ * Idempotent backfill: ensure every port has the three system roots
+ * (Clients / Companies / Yachts), every entity with attached files
+ * has a per-entity subfolder, every file with entity FKs has
+ * `folder_id` set, and every signed file from a completed workflow
+ * has the workflow's entity FKs propagated onto it.
+ *
+ * Safe to re-run: all writes target only rows where the relevant
+ * column is NULL. Per-port `pg_advisory_xact_lock` serializes
+ * concurrent runs.
+ *
+ * Usage:
+ *   pnpm tsx scripts/backfill-document-folders.ts
+ *   pnpm tsx scripts/backfill-document-folders.ts --port <portId>
+ */
+
+import 'dotenv/config';
+import { and, eq, isNotNull, isNull, sql } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { files, documents } from '@/lib/db/schema/documents';
+import {
+  ensureSystemRoots,
+  ensureEntityFolder,
+  type EntityType,
+} from '@/lib/services/document-folders.service';
+import { logger } from '@/lib/logger';
+
+export interface BackfillOptions {
+  /** When provided, only backfill this port. Otherwise all ports. */
+  portId?: string;
+  /** User ID recorded in `created_by` for any folders created. */
+  systemUserId?: string;
+}
+
+/**
+ * Per-port counters surfaced through the return value so the CLI can
+ * print them and operators (or follow-up scripts) can sanity-check that
+ * a re-run shrinks each number toward zero.
+ */
+export interface PortBackfillStats {
+  portId: string;
+  /** Total files inspected at Step 3 (with `folderId IS NULL`). */
+  filesProcessed: number;
+  /** Files updated with `folder_id` set in Step 3. */
+  filesWithFolderIdSet: number;
+  /** New folder rows created via `ensureEntityFolder` during Step 3. */
+  foldersCreated: number;
+  /** Completed-doc rows whose signed file got an entity FK propagated in Step 2. */
+  fksPropagated: number;
+}
+
+/**
+ * One-time idempotent backfill. See module-level JSDoc for full
+ * description of what each step does.
+ */
+export async function runBackfill(opts: BackfillOptions = {}): Promise<PortBackfillStats[]> {
+  const portRows = opts.portId
+    ? [{ id: opts.portId }]
+    : await db.select({ id: ports.id }).from(ports);
+
+  const systemUser = opts.systemUserId ?? 'system-backfill';
+  const allStats: PortBackfillStats[] = [];
+
+  for (const { id: portId } of portRows) {
+    const stats: PortBackfillStats = {
+      portId,
+      filesProcessed: 0,
+      filesWithFolderIdSet: 0,
+      foldersCreated: 0,
+      fksPropagated: 0,
+    };
+    await db.transaction(async (tx) => {
+      // Serialize concurrent runs on a per-port lock so two simultaneous
+      // backfills can't race on folder inserts.
+      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${portId})::bigint)`);
+
+      // ── Step 1: Ensure system roots exist for this port ──────────────────
+      await ensureSystemRoots(portId, systemUser);
+
+      // ── Step 2: Propagate entity FKs from completed workflows onto their
+      //            signed file rows (pre-auto-deposit legacy completions). ──
+      const completedDocs = await tx
+        .select({
+          id: documents.id,
+          signedFileId: documents.signedFileId,
+          clientId: documents.clientId,
+          companyId: documents.companyId,
+          yachtId: documents.yachtId,
+        })
+        .from(documents)
+        .where(
+          and(
+            eq(documents.portId, portId),
+            eq(documents.status, 'completed'),
+            isNotNull(documents.signedFileId),
+          ),
+        );
+
+      for (const d of completedDocs) {
+        if (!d.signedFileId) continue;
+
+        const owner: { type: EntityType; id: string } | null = d.clientId
+          ? { type: 'client', id: d.clientId }
+          : d.companyId
+            ? { type: 'company', id: d.companyId }
+            : d.yachtId
+              ? { type: 'yacht', id: d.yachtId }
+              : null;
+
+        if (!owner) continue;
+
+        // Build the update object with ONLY the matching FK column so we
+        // never pass column references to .set() (Drizzle syntax bug fix).
+        const update =
+          owner.type === 'client'
+            ? { clientId: owner.id }
+            : owner.type === 'company'
+              ? { companyId: owner.id }
+              : { yachtId: owner.id };
+
+        const matchingFkColumn =
+          owner.type === 'client'
+            ? files.clientId
+            : owner.type === 'company'
+              ? files.companyId
+              : files.yachtId;
+
+        const propagated = await tx
+          .update(files)
+          .set(update)
+          .where(
+            and(eq(files.id, d.signedFileId), eq(files.portId, portId), isNull(matchingFkColumn)),
+          )
+          .returning({ id: files.id });
+        stats.fksPropagated += propagated.length;
+      }
+
+      // ── Step 3: For every file with entity FKs but no folder_id,
+      //            create the entity subfolder and set folder_id. ──────────
+      const fileRows = await tx
+        .select()
+        .from(files)
+        .where(and(eq(files.portId, portId), isNull(files.folderId)));
+      stats.filesProcessed = fileRows.length;
+
+      const folderIdsCreatedThisRun = new Set<string>();
+      const folderIdsSeenThisRun = new Set<string>();
+      for (const f of fileRows) {
+        const owner: { type: EntityType; id: string } | null = f.clientId
+          ? { type: 'client', id: f.clientId }
+          : f.companyId
+            ? { type: 'company', id: f.companyId }
+            : f.yachtId
+              ? { type: 'yacht', id: f.yachtId }
+              : null;
+
+        if (!owner) continue;
+
+        try {
+          const beforeExisted = folderIdsSeenThisRun.has(`${owner.type}:${owner.id}`);
+          const folder = await ensureEntityFolder(portId, owner.type, owner.id, systemUser);
+          folderIdsSeenThisRun.add(`${owner.type}:${owner.id}`);
+          if (!beforeExisted && !folderIdsCreatedThisRun.has(folder.id)) {
+            // Heuristic: first time we encountered this entity in this
+            // backfill run + the folder is freshly returned ⇒ assume the
+            // folder was created (or existed already but we're double-
+            // counting at most once per entity, which is fine).
+            folderIdsCreatedThisRun.add(folder.id);
+          }
+          await tx
+            .update(files)
+            .set({ folderId: folder.id })
+            .where(and(eq(files.id, f.id), eq(files.portId, portId)));
+          stats.filesWithFolderIdSet += 1;
+        } catch (err) {
+          // Best-effort: log and skip rather than abort the whole port.
+          logger.warn({ err, fileId: f.id, portId }, 'backfill: ensureEntityFolder failed');
+        }
+      }
+      stats.foldersCreated = folderIdsCreatedThisRun.size;
+    });
+
+    logger.info(
+      {
+        portId,
+        filesProcessed: stats.filesProcessed,
+        filesWithFolderIdSet: stats.filesWithFolderIdSet,
+        foldersCreated: stats.foldersCreated,
+        fksPropagated: stats.fksPropagated,
+      },
+      'backfill: port complete',
+    );
+    allStats.push(stats);
+  }
+  return allStats;
+}
+
+// ── CLI entry point ────────────────────────────────────────────────────────────
+// tsx compiles TypeScript to CJS at runtime, so `require.main === module`
+// is the standard guard. The test suite imports `runBackfill` as a named
+// export; the CLI invocation hits this block and runs main().
+
+if (require.main === module) {
+  const portIdArg = process.argv.indexOf('--port');
+  let portId: string | undefined;
+  if (portIdArg !== -1) {
+    const next = process.argv[portIdArg + 1];
+    if (!next || next.startsWith('--')) {
+      logger.error('--port requires a value');
+      process.exit(1);
+    }
+    portId = next;
+  }
+  runBackfill({ portId })
+    .then((stats) => {
+      console.log('\nBackfill complete.');
+      console.log('Per-port summary:');
+      let totalFiles = 0;
+      let totalFilesSet = 0;
+      let totalFolders = 0;
+      let totalFks = 0;
+      for (const s of stats) {
+        totalFiles += s.filesProcessed;
+        totalFilesSet += s.filesWithFolderIdSet;
+        totalFolders += s.foldersCreated;
+        totalFks += s.fksPropagated;
+        console.log(
+          `  port=${s.portId}: filesProcessed=${s.filesProcessed} ` +
+            `filesWithFolderIdSet=${s.filesWithFolderIdSet} ` +
+            `foldersCreated=${s.foldersCreated} fksPropagated=${s.fksPropagated}`,
+        );
+      }
+      console.log(
+        `Totals: ports=${stats.length} filesProcessed=${totalFiles} ` +
+          `filesWithFolderIdSet=${totalFilesSet} foldersCreated=${totalFolders} ` +
+          `fksPropagated=${totalFks}`,
+      );
+      process.exit(0);
+    })
+    .catch((err) => {
+      logger.error({ err }, 'Backfill failed');
+      process.exit(1);
+    });
+}

scripts/backfill-eoi-signers.ts

@@ -0,0 +1,158 @@
+/**
+ * Backfill `document_signers` rows for EOI documents that were generated
+ * before the per-recipient signer-row insert landed (pre-2026-05-15).
+ *
+ * Symptom on the affected docs: the EOI tab's "Signing progress" panel
+ * reads "No signers loaded" forever because the webhook handler updates
+ * existing rows (by token / email) and never inserts new ones.
+ *
+ * This script walks every documents row that has a documensoId, status
+ * in ('sent', 'partially_signed', 'completed'), and zero signer rows.
+ * For each, it pulls the envelope from Documenso and recreates the
+ * signer rows from the recipients array. Idempotent — safe to re-run.
+ *
+ * Usage:
+ *   pnpm tsx scripts/backfill-eoi-signers.ts            # dry-run, lists candidates
+ *   pnpm tsx scripts/backfill-eoi-signers.ts --apply    # actually inserts
+ */
+
+import 'dotenv/config';
+import { and, inArray, isNotNull, sql } from 'drizzle-orm';
+
+import { db, closeDb } from '@/lib/db';
+import { documents, documentSigners } from '@/lib/db/schema/documents';
+import { getDocument as getDocumensoDoc } from '@/lib/services/documenso-client';
+import { logger } from '@/lib/logger';
+
+interface BackfillStats {
+  scanned: number;
+  withZeroSigners: number;
+  inserted: number;
+  failed: number;
+  skipped: number;
+}
+
+async function main() {
+  const apply = process.argv.includes('--apply');
+
+  // 1. Find candidate documents: in-flight or completed EOIs with a
+  //    documensoId and no signer rows.
+  const candidates = await db
+    .select({
+      id: documents.id,
+      portId: documents.portId,
+      documensoId: documents.documensoId,
+      status: documents.status,
+      documentType: documents.documentType,
+      title: documents.title,
+      signerCount: sql<number>`(
+        SELECT COUNT(*)::int FROM ${documentSigners}
+        WHERE ${documentSigners.documentId} = ${documents.id}
+      )`,
+    })
+    .from(documents)
+    .where(
+      and(
+        inArray(documents.status, ['sent', 'partially_signed', 'completed']),
+        isNotNull(documents.documensoId),
+      ),
+    );
+
+  const stats: BackfillStats = {
+    scanned: candidates.length,
+    withZeroSigners: 0,
+    inserted: 0,
+    failed: 0,
+    skipped: 0,
+  };
+
+  const needsBackfill = candidates.filter((c) => c.signerCount === 0);
+  stats.withZeroSigners = needsBackfill.length;
+
+  console.log(
+    `Scanned ${stats.scanned} document${stats.scanned === 1 ? '' : 's'}; ${stats.withZeroSigners} need backfill.`,
+  );
+  if (!apply) {
+    console.log('\nDRY RUN (pass --apply to insert):');
+    for (const doc of needsBackfill) {
+      console.log(`  - ${doc.id} (${doc.title}) — port=${doc.portId}, status=${doc.status}`);
+    }
+    await closeDb();
+    return;
+  }
+
+  // 2. For each candidate, fetch the envelope from Documenso and insert
+  //    the signer rows. Failures are logged + counted; processing
+  //    continues so one broken doc doesn't halt the run.
+  for (const doc of needsBackfill) {
+    if (!doc.documensoId) {
+      stats.skipped++;
+      continue;
+    }
+    try {
+      const envelope = await getDocumensoDoc(doc.documensoId, doc.portId);
+      if (envelope.recipients.length === 0) {
+        logger.warn({ documentId: doc.id }, 'Backfill: envelope has no recipients — skipping');
+        stats.skipped++;
+        continue;
+      }
+
+      // Use the same role-mapping logic as the create-time flow:
+      //   - signingOrder=1 + role SIGNER  →  'client' (positional)
+      //   - SIGNER otherwise              →  'signer'
+      //   - APPROVER                      →  'approver'
+      //   - CC / VIEWER                   →  pass-through
+      const rows = envelope.recipients.map((r) => {
+        const cleanName = (r.name || r.email)
+          .replace(/\s*\(was:[^)]*\)/i, '')
+          .replace(/\s*\(placeholder\)/i, '')
+          .trim();
+        const upRole = r.role.toUpperCase();
+        const role =
+          upRole === 'SIGNER' && r.signingOrder === 1
+            ? 'client'
+            : upRole === 'APPROVER'
+              ? 'approver'
+              : upRole === 'CC'
+                ? 'cc'
+                : upRole === 'VIEWER'
+                  ? 'viewer'
+                  : 'signer';
+        return {
+          documentId: doc.id,
+          signerName: cleanName || r.email,
+          signerEmail: r.email,
+          signerRole: role,
+          signingOrder: r.signingOrder,
+          status: (r.status === 'SIGNED' ? 'signed' : 'pending') as 'signed' | 'pending',
+          signingUrl: r.signingUrl ?? null,
+          embeddedUrl: r.embeddedUrl ?? null,
+          signingToken: r.token ?? null,
+          // No invitedAt — the backfill can't reconstruct the original
+          // dispatch timestamp. Reps see the card as "Not yet invited"
+          // for any pending signer; clicking Send invitation re-stamps.
+          invitedAt: null,
+        };
+      });
+
+      await db.insert(documentSigners).values(rows);
+      stats.inserted += rows.length;
+      console.log(`  ✓ ${doc.id} (${doc.title}) — inserted ${rows.length} signer row(s)`);
+    } catch (err) {
+      stats.failed++;
+      logger.error(
+        { err: err instanceof Error ? err.message : err, documentId: doc.id },
+        'Backfill failed for document',
+      );
+      console.log(`  ✗ ${doc.id} — ${err instanceof Error ? err.message : 'unknown error'}`);
+    }
+  }
+
+  console.log(`\nDone. inserted=${stats.inserted} failed=${stats.failed} skipped=${stats.skipped}`);
+  await closeDb();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

scripts/backfill-legacy-lead-source.ts

@@ -0,0 +1,135 @@
+/**
+ * One-shot: backfill `interests.source` for legacy NocoDB-imported rows.
+ *
+ * Why this exists: the legacy NocoDB Interests table left the `Source`
+ * column null for ~95 % of rows. The migration mapped null → null, so the
+ * Lead Source Attribution chart shows them as "Unspecified". Per the
+ * operator's best knowledge, almost all of those legacy rows came in
+ * through the website (web form / portal) — the few that didn't are the
+ * ones that already carry an explicit `Source` value (Form / portal /
+ * External). Defaulting null → 'website' is therefore the closest
+ * truth we can reconstruct without per-row sales notes review.
+ *
+ * Idempotent: only updates rows where `source IS NULL` AND the row has a
+ * `migration_source_links` entry tying it back to the legacy NocoDB import,
+ * so net-new manually-created interests with null source aren't touched.
+ *
+ * Usage:
+ *   pnpm tsx scripts/backfill-legacy-lead-source.ts --port-slug port-nimara [--dry-run]
+ */
+import 'dotenv/config';
+import { eq, and, isNull, inArray } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { interests } from '@/lib/db/schema/interests';
+import { migrationSourceLinks } from '@/lib/db/schema/migration';
+
+interface CliArgs {
+  portSlug: string | null;
+  dryRun: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = { portSlug: null, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--port-slug') args.portSlug = argv[++i] ?? null;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '-h' || a === '--help') {
+      console.log(
+        'Usage: pnpm tsx scripts/backfill-legacy-lead-source.ts --port-slug <slug> [--dry-run]',
+      );
+      process.exit(0);
+    }
+  }
+  if (!args.portSlug) {
+    console.error('Missing required --port-slug');
+    process.exit(1);
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const [port] = await db
+    .select({ id: ports.id, name: ports.name })
+    .from(ports)
+    .where(eq(ports.slug, args.portSlug!))
+    .limit(1);
+  if (!port) {
+    console.error(`No port found with slug "${args.portSlug}"`);
+    process.exit(1);
+  }
+  console.log(`[backfill] target: ${port.name} (${port.id})`);
+
+  // Pull every interest id this port owns that has a NULL source.
+  const candidateInterests = await db
+    .select({ id: interests.id })
+    .from(interests)
+    .where(and(eq(interests.portId, port.id), isNull(interests.source)));
+
+  console.log(`[backfill] interests with NULL source in this port: ${candidateInterests.length}`);
+
+  if (candidateInterests.length === 0) {
+    console.log('Nothing to backfill.');
+    return;
+  }
+
+  // Filter to ONLY those that came in via the legacy migration — preserves
+  // null on net-new rows where the operator hasn't picked a source yet.
+  const candidateIds = candidateInterests.map((r) => r.id);
+  const legacyLinks = await db
+    .select({ targetEntityId: migrationSourceLinks.targetEntityId })
+    .from(migrationSourceLinks)
+    .where(
+      and(
+        eq(migrationSourceLinks.sourceSystem, 'nocodb_interests'),
+        eq(migrationSourceLinks.targetEntityType, 'interest'),
+        inArray(migrationSourceLinks.targetEntityId, candidateIds),
+      ),
+    );
+
+  const legacyIds = new Set(legacyLinks.map((l) => l.targetEntityId));
+  const toUpdate = candidateIds.filter((id) => legacyIds.has(id));
+
+  console.log(
+    `[backfill] of those, ${toUpdate.length} are legacy migration rows (will set source='website')`,
+  );
+  console.log(
+    `[backfill] ${candidateInterests.length - toUpdate.length} are net-new rows (left untouched)`,
+  );
+
+  if (args.dryRun) {
+    console.log('[backfill] --dry-run set; no writes.');
+    return;
+  }
+
+  if (toUpdate.length === 0) {
+    console.log('Nothing to write.');
+    return;
+  }
+
+  // Update in chunks of 500 to keep query size sane.
+  const CHUNK = 500;
+  let updated = 0;
+  for (let i = 0; i < toUpdate.length; i += CHUNK) {
+    const chunk = toUpdate.slice(i, i + CHUNK);
+    // Belt-and-suspenders: re-assert `source IS NULL` in the WHERE so
+    // a concurrent process that set source on one of these rows
+    // between SELECT and UPDATE doesn't get its value clobbered.
+    const result = await db
+      .update(interests)
+      .set({ source: 'website' })
+      .where(and(inArray(interests.id, chunk), isNull(interests.source)))
+      .returning({ id: interests.id });
+    updated += result.length;
+  }
+  console.log(`[backfill] updated ${updated} rows.`);
+}
+
+main().catch((err) => {
+  console.error('FATAL', err);
+  process.exit(1);
+});

scripts/backfill-nested-document-folders.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env tsx
+/**
+ * Phase 2 nested-subfolders backfill.
+ *
+ * Re-files every existing `files` row that has `entity_type='interest'`
+ * (or a non-null `interest_id`) under a nested
+ * `Clients/<Name>/<Interest folder>/` subfolder. Idempotent — already-
+ * filed rows are skipped.
+ *
+ * Run dry-first to confirm the row count:
+ *   pnpm tsx scripts/backfill-nested-document-folders.ts
+ *
+ * Apply for real:
+ *   pnpm tsx scripts/backfill-nested-document-folders.ts --apply
+ *
+ * Per-port advisory lock so two operators can't race a backfill on the
+ * same port. Lock id is the FNV-1a hash of `port_id` so concurrent
+ * backfills against different ports don't block each other.
+ */
+
+import { sql } from 'drizzle-orm';
+
+import { db } from '../src/lib/db';
+import { ensureEntityFolder } from '../src/lib/services/document-folders.service';
+
+const APPLY = process.argv.includes('--apply');
+
+function fnv1a(input: string): number {
+  // Simple deterministic 32-bit hash — used as the advisory-lock id so
+  // the lock is stable across runs. PostgreSQL accepts a bigint here.
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+async function main() {
+  console.log(`[backfill-nested-folders] dry-run=${!APPLY}`);
+
+  // 1. Gather every (port_id, interest_id) pair whose files need to be
+  //    nested. We only need to ensure the folder exists — the
+  //    `files.interest_id` column is populated separately by Phase 1.
+  const rows = await db.execute<{ port_id: string; interest_id: string; row_count: number }>(
+    sql`
+      SELECT f.port_id, f.interest_id, COUNT(*)::int AS row_count
+      FROM files f
+      WHERE f.interest_id IS NOT NULL
+        AND f.archived_at IS NULL
+      GROUP BY f.port_id, f.interest_id
+      ORDER BY f.port_id, f.interest_id
+    `,
+  );
+
+  // postgres-js returns the raw result iterable; the `.rows` property is
+  // pgnative-only — iterate the result directly.
+  const list = Array.isArray(rows) ? rows : ((rows as { rows?: typeof rows }).rows ?? rows);
+  console.log(`[backfill-nested-folders] ${list.length} (port, interest) pairs to process`);
+  for (const row of list as Array<{ port_id: string; interest_id: string; row_count: number }>) {
+    const lockId = fnv1a(row.port_id);
+    if (APPLY) {
+      await db.execute(sql`SELECT pg_advisory_xact_lock(${lockId}::bigint)`);
+      // ensureEntityFolder is idempotent — running it for a pair that
+      // already has its folder is a cheap select.
+      await ensureEntityFolder(row.port_id, 'interest', row.interest_id, 'system');
+    }
+    console.log(
+      `  ${APPLY ? '✓' : '·'} port=${row.port_id.slice(0, 8)} interest=${row.interest_id.slice(
+        0,
+        8,
+      )} files=${row.row_count}`,
+    );
+  }
+
+  console.log(`[backfill-nested-folders] done.`);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('[backfill-nested-folders] failed', err);
+  process.exit(1);
+});

scripts/backfill-phone-e164.ts

@@ -0,0 +1,144 @@
+/**
+ * Backfill `client_contacts.value_e164` from `value` for phone / whatsapp
+ * contacts where it's null or empty.
+ *
+ * The legacy seed (and pre-normalization production data) stored phone
+ * numbers in `value` as free text — "+33 4 93 00 0002" — but `value_e164`
+ * is what every UI surface and dedup matcher reads. This script runs the
+ * raw `value` through libphonenumber-js (via the script-safe wrapper to
+ * avoid the Node 25 metadata-loader bug) and writes the canonical E.164
+ * form back.
+ *
+ * Usage:
+ *   pnpm tsx scripts/backfill-phone-e164.ts            # dry-run report
+ *   pnpm tsx scripts/backfill-phone-e164.ts --apply    # actually write
+ *
+ * The dry-run report prints, for each unparseable row, the contact id +
+ * raw value so you can hand-clean before re-running.
+ */
+import 'dotenv/config';
+import { and, eq, inArray, isNull, or, sql } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { clientContacts } from '@/lib/db/schema/clients';
+import { parsePhoneScriptSafe } from '@/lib/dedup/phone-parse';
+import type { CountryCode } from '@/lib/i18n/countries';
+
+const APPLY = process.argv.includes('--apply');
+
+interface PhoneRow {
+  id: string;
+  channel: string;
+  value: string | null;
+  valueCountry: string | null;
+}
+
+async function main() {
+  console.log(`Phone E.164 backfill — ${APPLY ? 'APPLY MODE' : 'dry-run'}`);
+  console.log('');
+
+  // Find candidate rows: phone or whatsapp contacts with a `value` set but
+  // `value_e164` null/empty.
+  const rows: PhoneRow[] = await db
+    .select({
+      id: clientContacts.id,
+      channel: clientContacts.channel,
+      value: clientContacts.value,
+      valueCountry: clientContacts.valueCountry,
+    })
+    .from(clientContacts)
+    .where(
+      and(
+        inArray(clientContacts.channel, ['phone', 'whatsapp']),
+        or(isNull(clientContacts.valueE164), eq(clientContacts.valueE164, '')),
+        sql`${clientContacts.value} IS NOT NULL AND ${clientContacts.value} <> ''`,
+      ),
+    );
+
+  console.log(`  found ${rows.length} candidate rows`);
+
+  let parsedFull = 0;
+  let parsedE164Only = 0;
+  let unparseable = 0;
+  const updates: Array<{
+    id: string;
+    valueE164: string;
+    valueCountry: CountryCode | null;
+  }> = [];
+  const fails: Array<{ id: string; value: string; reason: string }> = [];
+
+  for (const row of rows) {
+    if (!row.value) continue;
+    const defaultCountry = (row.valueCountry as CountryCode | null) ?? undefined;
+    const parsed1 = parsePhoneScriptSafe(row.value, defaultCountry);
+
+    if (parsed1.e164 && parsed1.country) {
+      // Both e164 + country resolved — best case.
+      updates.push({ id: row.id, valueE164: parsed1.e164, valueCountry: parsed1.country });
+      parsedFull++;
+    } else if (parsed1.e164) {
+      // E.164 came back but country didn't (e.g. UK +44 7700 900xxx
+      // fictional/reserved range — libphonenumber returns the e164 form
+      // but refuses to assign a country). Still safe to write — the e164
+      // is canonical. Country stays null.
+      updates.push({
+        id: row.id,
+        valueE164: parsed1.e164,
+        valueCountry: (row.valueCountry as CountryCode | null) ?? null,
+      });
+      parsedE164Only++;
+    } else {
+      fails.push({
+        id: row.id,
+        value: row.value,
+        reason: row.value.trim().startsWith('+')
+          ? 'has + prefix but parse failed'
+          : 'no leading + and no country hint',
+      });
+      unparseable++;
+    }
+  }
+
+  console.log('');
+  console.log('  ✓ parsed cleanly (e164 + country)', parsedFull);
+  console.log('  ✓ parsed e164 only (no country) ', parsedE164Only);
+  console.log('  ✗ unparseable                   ', unparseable);
+  console.log('');
+
+  if (fails.length > 0) {
+    console.log('Failures (first 10):');
+    for (const f of fails.slice(0, 10)) {
+      console.log(`  [${f.id}] "${f.value}" — ${f.reason}`);
+    }
+    console.log('');
+  }
+
+  if (!APPLY) {
+    console.log('Dry-run only. Re-run with --apply to write the updates.');
+    return;
+  }
+
+  if (updates.length === 0) {
+    console.log('No updates to write.');
+    return;
+  }
+
+  console.log(`Writing ${updates.length} updates...`);
+
+  for (const u of updates) {
+    await db
+      .update(clientContacts)
+      .set({
+        valueE164: u.valueE164,
+        valueCountry: u.valueCountry,
+      })
+      .where(eq(clientContacts.id, u.id));
+  }
+
+  console.log(`  ✓ wrote ${updates.length} rows`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

scripts/db-migrate.ts

@@ -0,0 +1,275 @@
+/**
+ * Production migration runner.
+ *
+ * Why this exists (and why `drizzle-kit migrate` isn't enough):
+ *
+ *   - Drizzle's bundled `migrate()` wraps every migration in a single
+ *     transaction. Postgres forbids `CREATE INDEX CONCURRENTLY` inside
+ *     a transaction (raises 25001) — so any migration containing
+ *     CONCURRENTLY silently aborts or, worse, leaves the migration
+ *     marked applied with the index missing. `0052_audit_critical_fixes.sql`
+ *     ships six CONCURRENTLY composite indexes today and they never
+ *     landed in prod.
+ *
+ *   - `drizzle-kit push` skips DDL the kit can't infer from the schema —
+ *     e.g. CHECK constraints, partial unique indexes, the berth-pdf
+ *     circular FK. push-only deployments diverge from migration-tracked
+ *     truth.
+ *
+ * This script:
+ *   1. Reads migrations in journal order from `src/lib/db/migrations`.
+ *   2. Tracks applied state in `drizzle.__drizzle_migrations` (matching
+ *      Drizzle's schema so other tooling sees the same source of truth).
+ *   3. For each pending migration: splits on `--> statement-breakpoint`,
+ *      classifies each statement as concurrency-safe (CREATE INDEX
+ *      CONCURRENTLY / REINDEX CONCURRENTLY → outside tx) or
+ *      transactional (everything else → batched in one tx per migration).
+ *   4. Records hash + when-applied so re-runs are no-ops.
+ *
+ * Modes:
+ *   `pnpm db:migrate`           — apply pending migrations
+ *   `pnpm db:migrate:status`    — show pending vs applied without applying
+ *   `pnpm db:migrate:baseline`  — mark every migration as applied without
+ *                                 running it. Use ONCE per environment when
+ *                                 the schema was bootstrapped via `db:push`
+ *                                 (dev + the original prod cutover). After
+ *                                 baseline, all future migrations go through
+ *                                 `db:migrate` and are tracked in
+ *                                 `__drizzle_migrations`.
+ */
+
+import 'dotenv/config';
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import postgres from 'postgres';
+
+const STATEMENT_BREAKPOINT = '--> statement-breakpoint';
+const MIGRATIONS_DIR = join(process.cwd(), 'src/lib/db/migrations');
+const SCHEMA_NAME = 'drizzle';
+const TABLE_NAME = '__drizzle_migrations';
+
+interface JournalEntry {
+  idx: number;
+  version: string;
+  when: number;
+  tag: string;
+  breakpoints: boolean;
+}
+
+interface Journal {
+  version: string;
+  dialect: string;
+  entries: JournalEntry[];
+}
+
+interface MigrationFile {
+  tag: string;
+  /** Folder millis from journal `when` — Drizzle uses this as the
+   *  primary key in `__drizzle_migrations`. */
+  folderMillis: number;
+  /** Full file contents. */
+  sql: string;
+  /** SHA-256 hex of the raw file for re-application detection. */
+  hash: string;
+}
+
+interface Statement {
+  /** Raw SQL text (trimmed). */
+  sql: string;
+  /** True when the statement must execute outside a transaction. */
+  needsAutocommit: boolean;
+}
+
+function isConcurrencyDDL(sql: string): boolean {
+  const head = sql
+    .replace(/^\s*--.*$/gm, '')
+    .trim()
+    .toUpperCase();
+  return (
+    /\bCREATE\s+INDEX\s+CONCURRENTLY\b/.test(head) ||
+    /\bREINDEX\s+\w*\s*CONCURRENTLY\b/.test(head) ||
+    /\bDROP\s+INDEX\s+CONCURRENTLY\b/.test(head)
+  );
+}
+
+function readMigrations(): MigrationFile[] {
+  const journal = JSON.parse(
+    readFileSync(join(MIGRATIONS_DIR, 'meta', '_journal.json'), 'utf8'),
+  ) as Journal;
+
+  const files = readdirSync(MIGRATIONS_DIR).filter((f) => f.endsWith('.sql'));
+  const byTag = new Map(files.map((f) => [f.replace(/\.sql$/, ''), f]));
+
+  return journal.entries.map((entry) => {
+    const filename = byTag.get(entry.tag);
+    if (!filename) {
+      throw new Error(`Migration ${entry.tag} in journal but ${entry.tag}.sql not on disk`);
+    }
+    const sql = readFileSync(join(MIGRATIONS_DIR, filename), 'utf8');
+    const hash = createHash('sha256').update(sql).digest('hex');
+    return { tag: entry.tag, folderMillis: entry.when, sql, hash };
+  });
+}
+
+function splitStatements(sql: string): Statement[] {
+  // Drizzle inserts `--> statement-breakpoint` between every statement
+  // when `breakpoints: true` in drizzle.config. We split on those AND
+  // strip trailing semicolons. Anything before the first breakpoint
+  // counts too.
+  const parts = sql.split(STATEMENT_BREAKPOINT);
+  const out: Statement[] = [];
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed || trimmed.startsWith('--')) {
+      // Comment-only chunks (pre-breakpoint header etc.) — skip if
+      // they have no executable SQL.
+      const nonComment = trimmed
+        .split('\n')
+        .filter((line) => !line.trim().startsWith('--') && line.trim().length > 0);
+      if (nonComment.length === 0) continue;
+    }
+    out.push({ sql: trimmed, needsAutocommit: isConcurrencyDDL(trimmed) });
+  }
+  return out;
+}
+
+async function ensureMigrationsTable(sql: postgres.Sql): Promise<void> {
+  await sql.unsafe(`CREATE SCHEMA IF NOT EXISTS "${SCHEMA_NAME}"`);
+  await sql.unsafe(`
+    CREATE TABLE IF NOT EXISTS "${SCHEMA_NAME}"."${TABLE_NAME}" (
+      id SERIAL PRIMARY KEY,
+      hash text NOT NULL,
+      created_at bigint
+    )
+  `);
+}
+
+async function getAppliedHashes(sql: postgres.Sql): Promise<Set<string>> {
+  const rows = await sql.unsafe<{ hash: string }[]>(
+    `SELECT hash FROM "${SCHEMA_NAME}"."${TABLE_NAME}"`,
+  );
+  return new Set(rows.map((r) => r.hash));
+}
+
+async function applyMigration(sql: postgres.Sql, migration: MigrationFile): Promise<void> {
+  const statements = splitStatements(migration.sql);
+  if (statements.length === 0) {
+    console.log(`  [${migration.tag}] no executable statements, skipping`);
+    return;
+  }
+
+  const autocommit = statements.filter((s) => s.needsAutocommit);
+  const transactional = statements.filter((s) => !s.needsAutocommit);
+
+  // Transactional batch first — schema changes that CONCURRENTLY ops
+  // depend on (e.g. column adds before CREATE INDEX) need to exist
+  // before the index build runs. Drizzle migrations are written in
+  // this order; we preserve it within each phase.
+  if (transactional.length > 0) {
+    await sql.begin(async (tx) => {
+      for (const stmt of transactional) {
+        await tx.unsafe(stmt.sql);
+      }
+    });
+  }
+
+  // CONCURRENTLY ops run one at a time, each as its own implicit tx.
+  // No `BEGIN`/`COMMIT` wrapping — postgres-js's `sql.unsafe` runs
+  // each call as an independent transaction.
+  for (const stmt of autocommit) {
+    await sql.unsafe(stmt.sql);
+  }
+
+  // Record the migration as applied. created_at mirrors Drizzle's own
+  // schema so `drizzle-kit migrate` (if ever invoked) sees the same
+  // state we wrote.
+  await sql.unsafe(
+    `INSERT INTO "${SCHEMA_NAME}"."${TABLE_NAME}" (hash, created_at) VALUES ($1, $2)`,
+    [migration.hash, migration.folderMillis],
+  );
+}
+
+async function main(): Promise<void> {
+  const url = process.env.DATABASE_URL;
+  if (!url) {
+    console.error('DATABASE_URL must be set');
+    process.exit(1);
+  }
+
+  const mode = process.argv[2] ?? 'apply';
+  if (!['apply', 'status', 'baseline'].includes(mode)) {
+    console.error(`Unknown mode: ${mode}. Use 'apply' (default), 'status', or 'baseline'.`);
+    process.exit(1);
+  }
+
+  const sql = postgres(url, { max: 1, prepare: false });
+
+  try {
+    await ensureMigrationsTable(sql);
+    const applied = await getAppliedHashes(sql);
+    const migrations = readMigrations();
+    const pending = migrations.filter((m) => !applied.has(m.hash));
+
+    if (mode === 'status') {
+      console.log(`Applied: ${applied.size}`);
+      console.log(`Pending: ${pending.length}`);
+      if (pending.length > 0) {
+        console.log('');
+        console.log('Pending migrations:');
+        for (const m of pending) {
+          const statements = splitStatements(m.sql);
+          const conc = statements.filter((s) => s.needsAutocommit).length;
+          const tx = statements.length - conc;
+          console.log(`  ${m.tag} — ${tx} transactional + ${conc} concurrency-safe`);
+        }
+      }
+      return;
+    }
+
+    if (mode === 'baseline') {
+      if (pending.length === 0) {
+        console.log('All migrations already tracked. Nothing to baseline.');
+        return;
+      }
+      console.log(
+        `Baselining ${pending.length} migration${
+          pending.length === 1 ? '' : 's'
+        } as applied without running them.`,
+      );
+      console.log(
+        'This is correct ONLY when the schema is already in place (e.g. created via db:push).',
+      );
+      for (const m of pending) {
+        await sql.unsafe(
+          `INSERT INTO "${SCHEMA_NAME}"."${TABLE_NAME}" (hash, created_at) VALUES ($1, $2)`,
+          [m.hash, m.folderMillis],
+        );
+        console.log(`  → ${m.tag} marked as applied`);
+      }
+      console.log(`Done. ${pending.length} baselined.`);
+      return;
+    }
+
+    if (pending.length === 0) {
+      console.log('No pending migrations.');
+      return;
+    }
+
+    console.log(`Applying ${pending.length} migration${pending.length === 1 ? '' : 's'}...`);
+    for (const m of pending) {
+      const statements = splitStatements(m.sql);
+      const conc = statements.filter((s) => s.needsAutocommit).length;
+      console.log(`  → ${m.tag} (${statements.length} statements, ${conc} CONCURRENTLY)`);
+      await applyMigration(sql, m);
+    }
+    console.log(`Done. ${pending.length} applied.`);
+  } finally {
+    await sql.end({ timeout: 5 });
+  }
+}
+
+main().catch((err) => {
+  console.error('Migration failed:', err);
+  process.exit(1);
+});

scripts/db-reset.ts

@@ -0,0 +1,97 @@
+/**
+ * Wipe all data from the database, preserving schema + drizzle migration
+ * history. Run before swapping seed fixtures.
+ *
+ *   pnpm tsx scripts/db-reset.ts          (refuses without --confirm)
+ *   pnpm tsx scripts/db-reset.ts --confirm
+ *
+ * Truncates every table in the `public` schema except the drizzle
+ * migration tracker, then resets sequences. Wraps the loop in a single
+ * transaction so a mid-wipe failure rolls back cleanly.
+ *
+ * Refuses to run when DATABASE_URL points at anything that doesn't look
+ * like a local/dev host. Override with --i-know-what-im-doing.
+ */
+
+import 'dotenv/config';
+import postgres from 'postgres';
+
+const url: string = process.env.DATABASE_URL ?? '';
+if (!url) {
+  console.error('DATABASE_URL is not set; aborting.');
+  process.exit(1);
+}
+
+const args = new Set(process.argv.slice(2));
+if (!args.has('--confirm')) {
+  console.error('Refusing to wipe without --confirm');
+  console.error('Run again as: pnpm tsx scripts/db-reset.ts --confirm');
+  process.exit(1);
+}
+
+// Best-effort safety: refuse for anything that doesn't look like a local DB.
+function looksLocal(u: string): boolean {
+  try {
+    const parsed = new URL(u);
+    return (
+      parsed.hostname === 'localhost' ||
+      parsed.hostname === '127.0.0.1' ||
+      parsed.hostname === '::1' ||
+      parsed.hostname.endsWith('.local') ||
+      parsed.hostname.endsWith('.internal') ||
+      parsed.hostname === 'host.docker.internal' ||
+      // Docker compose service names commonly used here
+      parsed.hostname === 'postgres' ||
+      parsed.hostname === 'db'
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (!looksLocal(url) && !args.has('--i-know-what-im-doing')) {
+  console.error(
+    `DATABASE_URL host doesn't look local. Refusing to wipe a remote DB without --i-know-what-im-doing.`,
+  );
+  process.exit(1);
+}
+
+const sql = postgres(url, { max: 1 });
+
+async function main() {
+  console.log('Resetting database...');
+  console.log(`  url: ${url.replace(/:[^:@]*@/, ':***@')}`);
+
+  const tables = await sql<{ tablename: string }[]>`
+    SELECT tablename FROM pg_tables
+    WHERE schemaname = 'public'
+      AND tablename NOT LIKE 'drizzle_%'
+      AND tablename != '__drizzle_migrations'
+  `;
+
+  if (tables.length === 0) {
+    console.log('  no user tables found, nothing to do.');
+    await sql.end();
+    return;
+  }
+
+  // Single TRUNCATE … CASCADE is faster than per-table loops and handles
+  // FK ordering for us. Quote table names defensively.
+  const tableList = tables.map((t) => `"public"."${t.tablename}"`).join(', ');
+
+  console.log(`  truncating ${tables.length} tables...`);
+  await sql.unsafe(`TRUNCATE ${tableList} RESTART IDENTITY CASCADE`);
+  console.log('  done.');
+
+  await sql.end();
+  console.log('');
+  console.log('Database reset complete. Run a seed script next:');
+  console.log('  pnpm db:seed              # realistic NocoDB-shaped fixture');
+  console.log('  pnpm db:seed:synthetic    # one client per pipeline stage');
+}
+
+main().catch(async (err) => {
+  console.error('Reset failed:', err);
+  await sql.end().catch(() => undefined);
+  process.exit(1);
+});

scripts/dev-open-browser.ts

@@ -0,0 +1,83 @@
+/**
+ * Launch a headed Chromium with NO viewport override so it adopts the
+ * host monitor's natural size — useful when you want to drive the CRM
+ * manually and have full-screen real estate.
+ *
+ * Pre-fills the login form for the synthetic admin (admin@portnimara.test
+ * / SuperAdmin12345!) but does not submit; press Enter when ready.
+ *
+ * The script keeps running until the browser window is closed by the
+ * user or until you Ctrl-C.
+ *
+ *   pnpm tsx scripts/dev-open-browser.ts             # super_admin
+ *   pnpm tsx scripts/dev-open-browser.ts sales_agent
+ *   pnpm tsx scripts/dev-open-browser.ts viewer
+ *   pnpm tsx scripts/dev-open-browser.ts --no-prefill
+ */
+
+import 'dotenv/config';
+// @playwright/test re-exports the same chromium driver and is already
+// installed as a dev dep; using it avoids needing to add the standalone
+// `playwright` package as a separate dependency.
+import { chromium } from '@playwright/test';
+
+const USERS: Record<string, { email: string; password: string }> = {
+  super_admin: { email: 'admin@portnimara.test', password: 'SuperAdmin12345!' },
+  sales_agent: { email: 'agent@portnimara.test', password: 'SalesAgent12345!' },
+  viewer: { email: 'viewer@portnimara.test', password: 'ViewerUser12345!' },
+};
+
+const BASE_URL = process.env.DEV_BASE_URL ?? 'http://localhost:3000';
+
+async function main() {
+  const args = process.argv.slice(2);
+  const noPrefill = args.includes('--no-prefill');
+  const role =
+    args.find((a) => !a.startsWith('--')) && USERS[args.find((a) => !a.startsWith('--'))!]
+      ? args.find((a) => !a.startsWith('--'))!
+      : 'super_admin';
+  const user = USERS[role]!;
+
+  console.log(`Launching headed Chromium → ${BASE_URL}`);
+  console.log(`  role: ${role}  (${user.email})`);
+
+  const browser = await chromium.launch({
+    headless: false,
+    args: ['--start-maximized'],
+  });
+
+  // viewport: null lets the page fill the OS window. Combined with
+  // --start-maximized this matches the host monitor's natural size.
+  const context = await browser.newContext({ viewport: null });
+  const page = await context.newPage();
+
+  await page.goto(`${BASE_URL}/login`);
+
+  if (!noPrefill) {
+    try {
+      await page.waitForSelector('#email', { timeout: 5000 });
+      await page.fill('#email', user.email);
+      await page.fill('#password', user.password);
+      console.log('  Login form pre-filled — press Enter in the browser to submit.');
+    } catch {
+      console.log('  Could not find login form (page may have redirected).');
+    }
+  }
+
+  console.log('');
+  console.log("Browser is open. Close it when you're done; the script will exit.");
+  console.log('Or Ctrl-C here to force-quit.');
+
+  // Keep the process alive until the browser window is closed.
+  await new Promise<void>((resolve) => {
+    browser.on('disconnected', () => resolve());
+  });
+
+  await browser.close().catch(() => undefined);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Open-browser failed:', err);
+  process.exit(1);
+});

scripts/dev-recommender-smoke.ts

@@ -0,0 +1,52 @@
+/**
+ * Dev-only smoke check for the berth recommender. Resolves the first
+ * port-nimara interest (with desired dims set) and prints the top-N
+ * recommendations.
+ *
+ *   pnpm tsx scripts/dev-recommender-smoke.ts
+ */
+import 'dotenv/config';
+import { eq, isNotNull, and } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { interests } from '@/lib/db/schema/interests';
+import { recommendBerths } from '@/lib/services/berth-recommender.service';
+
+async function main() {
+  const [port] = await db
+    .select({ id: ports.id })
+    .from(ports)
+    .where(eq(ports.slug, 'port-nimara'))
+    .limit(1);
+  if (!port) throw new Error('port-nimara not found');
+
+  const [interest] = await db
+    .select({ id: interests.id })
+    .from(interests)
+    .where(and(eq(interests.portId, port.id), isNotNull(interests.desiredLengthFt)))
+    .limit(1);
+  if (!interest) throw new Error('No interest with desired dims set');
+
+  console.log(`> Recommending berths for interest ${interest.id} on port ${port.id}…`);
+  const recs = await recommendBerths({
+    interestId: interest.id,
+    portId: port.id,
+  });
+
+  console.log(`> ${recs.length} recommendations:`);
+  for (const r of recs) {
+    console.log(
+      `  ${r.mooringNumber.padEnd(5)} tier=${r.tier} fit=${r.fitScore}  ` +
+        `${r.lengthFt}×${r.widthFt}×${r.draftFt} ft  buf=${r.sizeBufferPct}%  ` +
+        `${r.reasons.dimensional}; ${r.reasons.pipeline}`,
+    );
+  }
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

scripts/encrypt-plaintext-credentials.ts

@@ -0,0 +1,138 @@
+/**
+ * One-time migration: encrypt any plaintext credential rows in
+ * `system_settings` that should now be AES-256-GCM encrypted per the
+ * settings registry. Safe to re-run (idempotent — only touches plaintext
+ * rows, skips rows that are already encrypted envelopes).
+ *
+ * Currently handles:
+ *   - `documenso_api_key_override`            → in-place encrypt
+ *   - `storage_s3_access_key` (legacy)        → encrypt + move to
+ *                                                `storage_s3_access_key_encrypted`
+ *   - `documenso_webhook_secret` (if string)  → in-place encrypt
+ *
+ * Run: `pnpm tsx scripts/encrypt-plaintext-credentials.ts`
+ */
+import { and, eq, isNull } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { systemSettings } from '@/lib/db/schema';
+import { encrypt } from '@/lib/utils/encryption';
+
+const KEYS_TO_ENCRYPT_IN_PLACE = ['documenso_api_key_override', 'documenso_webhook_secret'];
+
+function isEncryptedEnvelope(value: unknown): boolean {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { iv?: unknown }).iv === 'string' &&
+    typeof (value as { tag?: unknown }).tag === 'string' &&
+    typeof (value as { data?: unknown }).data === 'string'
+  );
+}
+
+async function encryptInPlace(key: string): Promise<{ touched: number; skipped: number }> {
+  const rows = await db
+    .select({ key: systemSettings.key, portId: systemSettings.portId, value: systemSettings.value })
+    .from(systemSettings)
+    .where(eq(systemSettings.key, key));
+
+  let touched = 0;
+  let skipped = 0;
+  for (const row of rows) {
+    if (isEncryptedEnvelope(row.value)) {
+      skipped++;
+      continue;
+    }
+    if (typeof row.value !== 'string' || row.value === '') {
+      skipped++;
+      continue;
+    }
+    const envelope = JSON.parse(encrypt(row.value)) as {
+      iv: string;
+      tag: string;
+      data: string;
+    };
+    if (row.portId) {
+      await db
+        .update(systemSettings)
+        .set({ value: envelope, updatedAt: new Date() })
+        .where(and(eq(systemSettings.key, key), eq(systemSettings.portId, row.portId)));
+    } else {
+      await db
+        .update(systemSettings)
+        .set({ value: envelope, updatedAt: new Date() })
+        .where(and(eq(systemSettings.key, key), isNull(systemSettings.portId)));
+    }
+    touched++;
+  }
+  return { touched, skipped };
+}
+
+async function moveS3AccessKeyToEncrypted(): Promise<{
+  moved: number;
+  alreadyMigrated: number;
+}> {
+  // Move global rows only — s3 storage settings are global by design.
+  const legacyRows = await db
+    .select({ value: systemSettings.value })
+    .from(systemSettings)
+    .where(and(eq(systemSettings.key, 'storage_s3_access_key'), isNull(systemSettings.portId)));
+
+  if (legacyRows.length === 0) {
+    return { moved: 0, alreadyMigrated: 0 };
+  }
+
+  // Check if the encrypted form already exists.
+  const existingEncrypted = await db
+    .select({ key: systemSettings.key })
+    .from(systemSettings)
+    .where(
+      and(eq(systemSettings.key, 'storage_s3_access_key_encrypted'), isNull(systemSettings.portId)),
+    );
+
+  if (existingEncrypted.length > 0) {
+    // Encrypted form wins; leave the legacy row in place so reads still
+    // tolerate it (the storage layer reads both and prefers encrypted).
+    return { moved: 0, alreadyMigrated: legacyRows.length };
+  }
+
+  const plaintext = legacyRows[0]!.value;
+  if (typeof plaintext !== 'string' || plaintext === '') {
+    return { moved: 0, alreadyMigrated: 0 };
+  }
+  const envelope = JSON.parse(encrypt(plaintext)) as { iv: string; tag: string; data: string };
+  await db.insert(systemSettings).values({
+    key: 'storage_s3_access_key_encrypted',
+    portId: null,
+    value: envelope,
+  });
+  // Drop the legacy plaintext row so it doesn't show up in admin
+  // settings dumps anymore. The storage layer's backward-compat path
+  // continues to handle older rows on other deployments.
+  await db
+    .delete(systemSettings)
+    .where(and(eq(systemSettings.key, 'storage_s3_access_key'), isNull(systemSettings.portId)));
+  return { moved: 1, alreadyMigrated: 0 };
+}
+
+async function main(): Promise<void> {
+  console.log('Encrypting plaintext credentials...');
+
+  for (const key of KEYS_TO_ENCRYPT_IN_PLACE) {
+    const { touched, skipped } = await encryptInPlace(key);
+    console.log(`  ${key}: ${touched} encrypted, ${skipped} skipped`);
+  }
+
+  const s3 = await moveS3AccessKeyToEncrypted();
+  console.log(
+    `  storage_s3_access_key → _encrypted: ${s3.moved} moved, ${s3.alreadyMigrated} already migrated`,
+  );
+
+  console.log('Done.');
+  process.exit(0);
+}
+
+main().catch((err: unknown) => {
+  console.error('Migration failed:', err);
+  process.exit(1);
+});

scripts/import-berths-from-nocodb.ts

@@ -0,0 +1,409 @@
+/**
+ * Idempotent NocoDB Berths → CRM `berths` import.
+ *
+ * Re-running picks up NocoDB additions/edits without clobbering CRM-side
+ * overrides: rows where `updated_at > last_imported_at` are treated as
+ * human-edited and skipped (use `--force` to override). Map Data JSON
+ * is validated and upserted into `berth_map_data` as a separate step.
+ *
+ * Usage:
+ *   pnpm tsx scripts/import-berths-from-nocodb.ts --dry-run [--port-slug port-nimara]
+ *   pnpm tsx scripts/import-berths-from-nocodb.ts --apply  [--port-slug port-nimara]
+ *   pnpm tsx scripts/import-berths-from-nocodb.ts --apply  --force
+ *   pnpm tsx scripts/import-berths-from-nocodb.ts --apply  --update-snapshot
+ *
+ * Edge cases mitigated (see plan §14.1):
+ *   - Mooring collisions   : unique (port_id, mooring_number) on the table.
+ *   - Concurrent runs      : pg_advisory_xact_lock on a stable key.
+ *   - Numeric-with-units   : parseDecimalWithUnit() strips trailing units.
+ *   - Metric drift         : NocoDB metric formula columns are ignored;
+ *                            metric values are recomputed from imperial.
+ *   - Map Data shape       : zod-validated; failures are skipped silently
+ *                            rather than aborting the whole import.
+ *   - Status enum          : NocoDB display strings → CRM snake_case.
+ *   - NocoDB row deleted   : reported as "orphaned in CRM"; not auto-deleted.
+ */
+
+import 'dotenv/config';
+import { eq, sql } from 'drizzle-orm';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { berths, berthMapData } from '@/lib/db/schema/berths';
+import { fetchAllRows, loadNocoDbConfig, NOCO_TABLES } from '@/lib/dedup/nocodb-source';
+import {
+  buildPlan,
+  mapRow,
+  type Action,
+  type ImportedBerth,
+  type PlanEntry,
+  type ExistingBerthRow,
+} from '@/lib/services/berth-import';
+
+// ─── CLI ────────────────────────────────────────────────────────────────────
+
+interface CliArgs {
+  dryRun: boolean;
+  apply: boolean;
+  portSlug: string;
+  force: boolean;
+  updateSnapshot: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    dryRun: false,
+    apply: false,
+    portSlug: 'port-nimara',
+    force: false,
+    updateSnapshot: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--apply') args.apply = true;
+    else if (a === '--port-slug') args.portSlug = argv[++i] ?? 'port-nimara';
+    else if (a === '--force') args.force = true;
+    else if (a === '--update-snapshot') args.updateSnapshot = true;
+    else if (a === '-h' || a === '--help') {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+  if (!args.dryRun && !args.apply) {
+    console.error('Must specify either --dry-run or --apply.');
+    printHelp();
+    process.exit(1);
+  }
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage:
+  pnpm tsx scripts/import-berths-from-nocodb.ts --dry-run [--port-slug <slug>]
+  pnpm tsx scripts/import-berths-from-nocodb.ts --apply   [--port-slug <slug>] [--force] [--update-snapshot]
+
+Flags:
+  --dry-run             Read NocoDB + diff vs CRM. No writes.
+  --apply               Apply the plan to the DB.
+  --port-slug <slug>    Target port slug (default: port-nimara).
+  --force               Overwrite rows where CRM updated_at > last_imported_at.
+  --update-snapshot     Rewrite src/lib/db/seed-data/berths.json after apply.
+  -h, --help            Show this help.
+`);
+}
+
+// ─── Stable advisory lock key ───────────────────────────────────────────────
+// 64-bit BIGINT - first 4 bytes spell "BRTH" so it's grep-able in pg_locks.
+const BERTH_IMPORT_LOCK_KEY = 0x4252544800000001n;
+
+// ─── Apply ──────────────────────────────────────────────────────────────────
+
+interface ApplyResult {
+  inserted: number;
+  updated: number;
+  skipped: number;
+  mapDataWritten: number;
+  warnings: string[];
+}
+
+async function apply(
+  portId: string,
+  plan: PlanEntry[],
+  orphans: ExistingBerthRow[],
+  importedAt: Date,
+): Promise<ApplyResult> {
+  const result: ApplyResult = {
+    inserted: 0,
+    updated: 0,
+    skipped: 0,
+    mapDataWritten: 0,
+    warnings: [],
+  };
+  for (const orphan of orphans) {
+    result.warnings.push(
+      `Orphan: CRM has mooring="${orphan.mooringNumber}" but NocoDB no longer does (id=${orphan.id})`,
+    );
+  }
+
+  await db.transaction(async (tx) => {
+    // Stable lock so two simultaneous --apply runs serialize.
+    await tx.execute(sql`SELECT pg_advisory_xact_lock(${BERTH_IMPORT_LOCK_KEY})`);
+
+    for (const entry of plan) {
+      if (entry.action === 'skip-edited' || entry.action === 'noop') {
+        result.skipped += 1;
+        result.warnings.push(`Skipped ${entry.imported.mooringNumber}: ${entry.reason ?? 'no-op'}`);
+        continue;
+      }
+      const i = entry.imported;
+      const n = i.numerics;
+      const baseValues = {
+        portId,
+        mooringNumber: i.mooringNumber,
+        area: i.area,
+        status: i.status,
+        lengthFt: n.lengthFt != null ? String(n.lengthFt) : null,
+        widthFt: n.widthFt != null ? String(n.widthFt) : null,
+        draftFt: n.draftFt != null ? String(n.draftFt) : null,
+        lengthM: n.lengthM != null ? String(n.lengthM) : null,
+        widthM: n.widthM != null ? String(n.widthM) : null,
+        draftM: n.draftM != null ? String(n.draftM) : null,
+        widthIsMinimum: i.widthIsMinimum,
+        nominalBoatSize: n.nominalBoatSize != null ? String(n.nominalBoatSize) : null,
+        nominalBoatSizeM: n.nominalBoatSizeM != null ? String(n.nominalBoatSizeM) : null,
+        waterDepth: n.waterDepth != null ? String(n.waterDepth) : null,
+        waterDepthM: n.waterDepthM != null ? String(n.waterDepthM) : null,
+        waterDepthIsMinimum: i.waterDepthIsMinimum,
+        sidePontoon: i.sidePontoon,
+        powerCapacity: n.powerCapacity != null ? String(n.powerCapacity) : null,
+        voltage: n.voltage != null ? String(n.voltage) : null,
+        mooringType: i.mooringType,
+        cleatType: i.cleatType,
+        cleatCapacity: i.cleatCapacity,
+        bollardType: i.bollardType,
+        bollardCapacity: i.bollardCapacity,
+        access: i.access,
+        price: n.price != null ? String(n.price) : null,
+        priceCurrency: 'USD' as const,
+        bowFacing: i.bowFacing,
+        berthApproved: i.berthApproved,
+        statusOverrideMode: i.statusOverrideMode,
+        lastImportedAt: importedAt,
+        updatedAt: importedAt,
+      };
+
+      let berthId: string;
+      if (entry.action === 'insert') {
+        const [inserted] = await tx
+          .insert(berths)
+          .values({ ...baseValues, tenureType: 'permanent' })
+          .returning({ id: berths.id });
+        berthId = inserted!.id;
+        result.inserted += 1;
+      } else {
+        await tx.update(berths).set(baseValues).where(eq(berths.id, entry.existing!.id));
+        berthId = entry.existing!.id;
+        result.updated += 1;
+      }
+
+      if (i.mapData) {
+        const mapValues = {
+          berthId,
+          svgPath: i.mapData.path ?? null,
+          x: i.mapData.x != null ? String(i.mapData.x) : null,
+          y: i.mapData.y != null ? String(i.mapData.y) : null,
+          transform: i.mapData.transform ?? null,
+          fontSize: i.mapData.fontSize != null ? String(i.mapData.fontSize) : null,
+          updatedAt: importedAt,
+        };
+        await tx
+          .insert(berthMapData)
+          .values(mapValues)
+          .onConflictDoUpdate({
+            target: berthMapData.berthId,
+            set: {
+              svgPath: mapValues.svgPath,
+              x: mapValues.x,
+              y: mapValues.y,
+              transform: mapValues.transform,
+              fontSize: mapValues.fontSize,
+              updatedAt: importedAt,
+            },
+          });
+        result.mapDataWritten += 1;
+      }
+    }
+  });
+  return result;
+}
+
+// ─── Snapshot writer (for seed-data refresh) ────────────────────────────────
+
+async function writeSnapshot(imported: ImportedBerth[]): Promise<string> {
+  // Ordering: idx 0..4 available (small), 5..9 under_offer (medium),
+  // 10..11 sold (large), then everything else by mooring number. The
+  // first 12 indexes feed `seed-data.ts` interest/reservation stubs.
+  const sortByLength = (a: ImportedBerth, b: ImportedBerth) =>
+    (a.numerics.lengthFt ?? 0) - (b.numerics.lengthFt ?? 0);
+  const available = imported
+    .filter((b) => b.status === 'available')
+    .sort(sortByLength)
+    .slice(0, 5);
+  const underOffer = imported
+    .filter((b) => b.status === 'under_offer')
+    .sort(sortByLength)
+    .slice(0, 5);
+  const sold = imported
+    .filter((b) => b.status === 'sold')
+    .sort((a, b) => -sortByLength(a, b))
+    .slice(0, 2);
+  const featured = new Set([...available, ...underOffer, ...sold].map((b) => b.mooringNumber));
+  const rest = imported
+    .filter((b) => !featured.has(b.mooringNumber))
+    .sort((a, b) => a.mooringNumber.localeCompare(b.mooringNumber, 'en', { numeric: true }));
+  const ordered = [...available, ...underOffer, ...sold, ...rest];
+
+  const payload = ordered.map((b) => ({
+    legacyId: b.legacyId,
+    mooringNumber: b.mooringNumber,
+    area: b.area,
+    status: b.status,
+    lengthFt: b.numerics.lengthFt,
+    widthFt: b.numerics.widthFt,
+    draftFt: b.numerics.draftFt,
+    lengthM: b.numerics.lengthM,
+    widthM: b.numerics.widthM,
+    draftM: b.numerics.draftM,
+    widthIsMinimum: b.widthIsMinimum,
+    nominalBoatSize: b.numerics.nominalBoatSize,
+    nominalBoatSizeM: b.numerics.nominalBoatSizeM,
+    waterDepth: b.numerics.waterDepth,
+    waterDepthM: b.numerics.waterDepthM,
+    waterDepthIsMinimum: b.waterDepthIsMinimum,
+    sidePontoon: b.sidePontoon,
+    powerCapacity: b.numerics.powerCapacity,
+    voltage: b.numerics.voltage,
+    mooringType: b.mooringType,
+    cleatType: b.cleatType,
+    cleatCapacity: b.cleatCapacity,
+    bollardType: b.bollardType,
+    bollardCapacity: b.bollardCapacity,
+    access: b.access,
+    price: b.numerics.price,
+    bowFacing: b.bowFacing,
+    berthApproved: b.berthApproved,
+    statusOverrideMode: b.statusOverrideMode,
+  }));
+
+  const target = path.resolve(process.cwd(), 'src/lib/db/seed-data/berths.json');
+  await fs.writeFile(target, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  return target;
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const config = loadNocoDbConfig();
+
+  const [port] = await db
+    .select({ id: ports.id, slug: ports.slug })
+    .from(ports)
+    .where(eq(ports.slug, args.portSlug))
+    .limit(1);
+  if (!port) {
+    console.error(`No port found with slug "${args.portSlug}".`);
+    process.exit(1);
+  }
+
+  console.log(`> Fetching NocoDB Berths…`);
+  const rows = await fetchAllRows(NOCO_TABLES.berths, config);
+  console.log(`  fetched ${rows.length} rows from NocoDB`);
+
+  const imported: ImportedBerth[] = [];
+  let skippedMalformed = 0;
+  for (const r of rows) {
+    const m = mapRow(r);
+    if (m) imported.push(m);
+    else skippedMalformed += 1;
+  }
+  if (skippedMalformed > 0) {
+    console.warn(`  ${skippedMalformed} rows skipped (missing Mooring Number)`);
+  }
+
+  // De-dup against any same-mooring twins surfacing from NocoDB
+  // (defensive — the Berths table is keyed on Mooring Number in NocoDB).
+  const seen = new Set<string>();
+  const dedup: ImportedBerth[] = [];
+  for (const b of imported) {
+    if (seen.has(b.mooringNumber)) {
+      console.warn(`  duplicate mooring "${b.mooringNumber}" in NocoDB — keeping first`);
+      continue;
+    }
+    seen.add(b.mooringNumber);
+    dedup.push(b);
+  }
+
+  console.log(`> Reading current CRM berths for port "${port.slug}"…`);
+  const existingRows = await db
+    .select({
+      id: berths.id,
+      mooringNumber: berths.mooringNumber,
+      updatedAt: berths.updatedAt,
+      lastImportedAt: berths.lastImportedAt,
+    })
+    .from(berths)
+    .where(eq(berths.portId, port.id));
+  console.log(`  ${existingRows.length} existing rows`);
+
+  const existingByMooring = new Map(existingRows.map((r) => [r.mooringNumber, r]));
+  const { plan, orphans } = buildPlan(dedup, existingByMooring, args.force);
+
+  const counts = plan.reduce(
+    (acc, e) => {
+      acc[e.action] += 1;
+      return acc;
+    },
+    { insert: 0, update: 0, 'skip-edited': 0, noop: 0 } as Record<Action, number>,
+  );
+
+  console.log(`> Plan:`);
+  console.log(`    insert       : ${counts.insert}`);
+  console.log(`    update       : ${counts.update}`);
+  console.log(`    skip-edited  : ${counts['skip-edited']}`);
+  console.log(`    no-op        : ${counts.noop}`);
+  console.log(`    orphans (CRM): ${orphans.length}`);
+
+  if (counts['skip-edited'] > 0) {
+    console.log(`  ↳ Skipped (CRM-edited; pass --force to overwrite):`);
+    for (const e of plan.filter((p) => p.action === 'skip-edited').slice(0, 10)) {
+      console.log(`      - ${e.imported.mooringNumber}  ${e.reason}`);
+    }
+    if (counts['skip-edited'] > 10) console.log(`      …and ${counts['skip-edited'] - 10} more`);
+  }
+  if (orphans.length > 0) {
+    console.log(`  ↳ Orphans (in CRM but missing from NocoDB):`);
+    for (const o of orphans.slice(0, 10)) console.log(`      - ${o.mooringNumber}`);
+    if (orphans.length > 10) console.log(`      …and ${orphans.length - 10} more`);
+  }
+
+  // Snapshot write is independent of DB writes — even in --dry-run mode
+  // a rep may want to refresh the seed JSON to capture the latest NocoDB
+  // shape without committing to the DB import. The original gate dropped
+  // this silently when --dry-run was passed; audit caught it.
+  if (args.updateSnapshot) {
+    const written = await writeSnapshot(dedup);
+    console.log(`> Wrote ${dedup.length} rows to ${path.relative(process.cwd(), written)}`);
+  }
+
+  if (args.dryRun) {
+    console.log(`\n[dry-run] no DB writes performed.`);
+    return;
+  }
+
+  console.log(`> Applying…`);
+  const result = await apply(port.id, plan, orphans, new Date());
+  console.log(`  inserted        : ${result.inserted}`);
+  console.log(`  updated         : ${result.updated}`);
+  console.log(`  skipped         : ${result.skipped}`);
+  console.log(`  map data writes : ${result.mapDataWritten}`);
+  if (result.warnings.length) {
+    console.log(`  warnings        :`);
+    for (const w of result.warnings.slice(0, 20)) console.log(`    - ${w}`);
+    if (result.warnings.length > 20) console.log(`    …and ${result.warnings.length - 20} more`);
+  }
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err: unknown) => {
+    console.error(err);
+    process.exit(1);
+  });

scripts/import-organized-documents.ts

@@ -0,0 +1,326 @@
+/**
+ * Importer for an organized S3 / filesystem bucket whose folder structure
+ * already represents real organisation. Walks every key under `--bucket-prefix`,
+ * builds matching `document_folders` rows mirroring the path, then inserts
+ * `documents` + `files` rows pointing at the existing storage keys verbatim
+ * — no path rewrite. Use when migrating from a legacy MinIO bucket whose
+ * tree is the source of truth.
+ *
+ * Usage:
+ *   pnpm tsx scripts/import-organized-documents.ts --port-slug <slug> \
+ *       --bucket-prefix "legacy-imports/" --dry-run
+ *   pnpm tsx scripts/import-organized-documents.ts --port-slug <slug> \
+ *       --bucket-prefix "legacy-imports/" --apply
+ *
+ * Idempotency:
+ *   - Folders: sibling-name unique index swallows duplicate creates and we
+ *     reuse the existing row.
+ *   - Documents: skipped when a row with `(port_id, fileStoragePath)` already
+ *     exists — the storage key is the natural identity for this importer.
+ */
+
+import 'dotenv/config';
+import path from 'node:path';
+import { and, eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { documents, documentFolders, files } from '@/lib/db/schema/documents';
+import { user } from '@/lib/db/schema/users';
+import { createAuditLog } from '@/lib/audit';
+import { ConflictError } from '@/lib/errors';
+import { createFolder } from '@/lib/services/document-folders.service';
+import { parseImportPath } from '@/lib/services/document-import';
+import { getStorageBackend } from '@/lib/storage';
+
+interface CliArgs {
+  portSlug: string;
+  bucketPrefix: string;
+  dryRun: boolean;
+  apply: boolean;
+  uploadedByUserId: string | null;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    portSlug: '',
+    bucketPrefix: '',
+    dryRun: false,
+    apply: false,
+    uploadedByUserId: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--port-slug') args.portSlug = argv[++i] ?? '';
+    else if (a === '--bucket-prefix') args.bucketPrefix = argv[++i] ?? '';
+    else if (a === '--uploaded-by') args.uploadedByUserId = argv[++i] ?? null;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--apply') args.apply = true;
+    else if (a === '-h' || a === '--help') {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+  if (!args.portSlug) {
+    console.error('Missing required --port-slug');
+    process.exit(1);
+  }
+  if (!args.dryRun && !args.apply) {
+    console.error('Must specify either --dry-run or --apply.');
+    process.exit(1);
+  }
+  if (args.dryRun && args.apply) {
+    console.error('--dry-run and --apply are mutually exclusive.');
+    process.exit(1);
+  }
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage:
+  pnpm tsx scripts/import-organized-documents.ts \\
+      --port-slug <slug> \\
+      --bucket-prefix <prefix> \\
+      (--dry-run | --apply) \\
+      [--uploaded-by <userId>]
+`);
+}
+
+interface PlannedDoc {
+  key: string;
+  folderSegments: string[];
+  filename: string;
+  bytes: number | null;
+  contentType: string;
+  alreadyImported: boolean;
+}
+
+const CONTENT_TYPE_BY_EXT: Record<string, string> = {
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.txt': 'text/plain',
+  '.csv': 'text/csv',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
+
+function guessContentType(filename: string): string {
+  const ext = path.extname(filename).toLowerCase();
+  return CONTENT_TYPE_BY_EXT[ext] ?? 'application/octet-stream';
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  const port = await db.query.ports.findFirst({ where: eq(ports.slug, args.portSlug) });
+  if (!port) {
+    console.error(`Port not found: ${args.portSlug}`);
+    process.exit(1);
+  }
+
+  let uploadedById = args.uploadedByUserId;
+  if (!uploadedById) {
+    const [u] = await db.select({ id: user.id }).from(user).limit(1);
+    if (!u) {
+      console.error(
+        'No user rows exist; pass --uploaded-by <userId> or seed at least one user before running.',
+      );
+      process.exit(1);
+    }
+    uploadedById = u.id;
+    console.log(`No --uploaded-by provided; falling back to first user: ${uploadedById}`);
+  }
+
+  const backend = await getStorageBackend();
+  console.log(`Listing keys under prefix "${args.bucketPrefix}" via ${backend.name} backend …`);
+  const keys = await backend.listByPrefix(args.bucketPrefix);
+  console.log(`Found ${keys.length} candidate keys.`);
+
+  const plan: PlannedDoc[] = [];
+  for (const key of keys) {
+    const parsed = parseImportPath(args.bucketPrefix, key);
+    if (!parsed.filename) continue;
+
+    const head = await backend.head(key);
+    const existing = await db.query.files.findFirst({
+      where: and(eq(files.portId, port.id), eq(files.storagePath, key)),
+      columns: { id: true },
+    });
+
+    plan.push({
+      key,
+      folderSegments: parsed.folderSegments,
+      filename: parsed.filename,
+      bytes: head?.sizeBytes ?? null,
+      contentType: head?.contentType ?? guessContentType(parsed.filename),
+      alreadyImported: !!existing,
+    });
+  }
+
+  printPlan(plan);
+
+  if (args.dryRun) {
+    console.log('\nDry-run complete. No changes written.');
+    return;
+  }
+
+  const folderIdByPath = new Map<string, string | null>();
+  folderIdByPath.set('', null);
+  let createdCount = 0;
+  let skippedCount = 0;
+
+  for (const entry of plan) {
+    if (entry.alreadyImported) {
+      skippedCount += 1;
+      continue;
+    }
+
+    const folderId = await ensureFolderChain(
+      port.id,
+      uploadedById,
+      entry.folderSegments,
+      folderIdByPath,
+    );
+
+    await db.transaction(async (tx) => {
+      const [fileRow] = await tx
+        .insert(files)
+        .values({
+          portId: port.id,
+          filename: entry.filename,
+          originalName: entry.filename,
+          mimeType: entry.contentType,
+          sizeBytes: entry.bytes !== null ? String(entry.bytes) : null,
+          storagePath: entry.key,
+          uploadedBy: uploadedById,
+          category: 'misc',
+          folderId,
+        })
+        .returning();
+      const [docRow] = await tx
+        .insert(documents)
+        .values({
+          portId: port.id,
+          documentType: 'other',
+          title: entry.filename,
+          createdBy: uploadedById,
+          folderId,
+          fileId: fileRow!.id,
+          status: 'completed',
+          isManualUpload: true,
+        })
+        .returning();
+
+      void createAuditLog({
+        userId: uploadedById,
+        portId: port.id,
+        action: 'create',
+        entityType: 'document',
+        entityId: docRow!.id,
+        metadata: {
+          source: 'organized-bucket-importer',
+          storageKey: entry.key,
+          folderSegments: entry.folderSegments,
+        },
+      });
+    });
+    createdCount += 1;
+    console.log(`✓ Imported ${entry.key}`);
+  }
+
+  console.log(
+    `\nDone. Created ${createdCount} documents, skipped ${skippedCount} (already imported).`,
+  );
+}
+
+async function ensureFolderChain(
+  portId: string,
+  userId: string,
+  segments: string[],
+  cache: Map<string, string | null>,
+): Promise<string | null> {
+  if (segments.length === 0) return null;
+
+  let parentId: string | null = null;
+  for (let i = 0; i < segments.length; i += 1) {
+    const pathKey = segments.slice(0, i + 1).join('/');
+    const cached = cache.get(pathKey);
+    if (cached !== undefined) {
+      parentId = cached;
+      continue;
+    }
+
+    const name = segments[i]!;
+    parentId = await createOrFindFolder(portId, userId, name, parentId);
+    cache.set(pathKey, parentId);
+  }
+  return parentId;
+}
+
+async function createOrFindFolder(
+  portId: string,
+  userId: string,
+  name: string,
+  parentId: string | null,
+): Promise<string> {
+  try {
+    const created = await createFolder(portId, userId, { name, parentId });
+    return created.id;
+  } catch (err) {
+    if (!(err instanceof ConflictError)) throw err;
+    // Sibling-name unique index hit — fetch the existing row so the import
+    // remains idempotent across re-runs.
+    const trimmed = name.trim();
+    const candidates = await db.query.documentFolders.findMany({
+      where: parentId
+        ? and(eq(documentFolders.portId, portId), eq(documentFolders.parentId, parentId))
+        : eq(documentFolders.portId, portId),
+    });
+    const existing = candidates.find(
+      (row) =>
+        (parentId ? row.parentId === parentId : row.parentId === null) &&
+        row.name.toLowerCase() === trimmed.toLowerCase(),
+    );
+    if (!existing) throw err;
+    return existing.id;
+  }
+}
+
+function printPlan(plan: PlannedDoc[]): void {
+  const grouped = new Map<string, PlannedDoc[]>();
+  for (const entry of plan) {
+    const folder = entry.folderSegments.join('/') || '(root)';
+    if (!grouped.has(folder)) grouped.set(folder, []);
+    grouped.get(folder)!.push(entry);
+  }
+  const folderNames = Array.from(grouped.keys()).sort();
+  console.log('\nPlan:');
+  for (const folder of folderNames) {
+    console.log(`  ${folder}/`);
+    for (const entry of grouped.get(folder)!) {
+      const flag = entry.alreadyImported ? '·' : '+';
+      const size = entry.bytes !== null ? ` (${entry.bytes}B)` : '';
+      console.log(`    ${flag} ${entry.filename}${size}`);
+    }
+  }
+  const newCount = plan.filter((p) => !p.alreadyImported).length;
+  const dupCount = plan.length - newCount;
+  console.log(`\nTotal: ${plan.length} keys → ${newCount} new, ${dupCount} already imported.`);
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

scripts/migrate-from-nocodb.ts

@@ -0,0 +1,251 @@
+/**
+ * One-shot migration: legacy NocoDB Interests → new client/interest split.
+ *
+ * Usage:
+ *
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --dry-run
+ *     Pulls the live NocoDB base, runs the transform + dedup pipeline,
+ *     writes a report to .migration/<timestamp>/. NO database writes.
+ *
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --dry-run --port-slug port-nimara
+ *     Same, but tags the planned writes with the named port (matters for
+ *     the apply phase — every client/interest belongs to one port).
+ *
+ *   pnpm tsx scripts/migrate-from-nocodb.ts --apply --port-slug port-nimara
+ *     Re-fetches NocoDB, re-transforms, then writes the planned rows
+ *     into the target port via the idempotent `migration_source_links`
+ *     ledger. Re-runs are safe — already-imported source IDs are skipped.
+ *     REQUIRES `EMAIL_REDIRECT_TO` to be set in env (safety net) unless
+ *     `--unsafe-skip-redirect-check` is also passed.
+ *
+ * Design reference: docs/superpowers/specs/2026-05-03-dedup-and-migration-design.md §9.
+ */
+
+import 'dotenv/config';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { applyPlan } from '@/lib/dedup/migration-apply';
+import { fetchSnapshot, loadNocoDbConfig } from '@/lib/dedup/nocodb-source';
+import { transformSnapshot } from '@/lib/dedup/migration-transform';
+import { resolveReportPaths, writeReport } from '@/lib/dedup/migration-report';
+
+interface CliArgs {
+  dryRun: boolean;
+  apply: boolean;
+  portSlug: string | null;
+  reportDir: string | null;
+  unsafeSkipRedirectCheck: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    dryRun: false,
+    apply: false,
+    portSlug: null,
+    reportDir: null,
+    unsafeSkipRedirectCheck: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--apply') args.apply = true;
+    else if (a === '--port-slug') args.portSlug = argv[++i] ?? null;
+    else if (a === '--report') args.reportDir = argv[++i] ?? null;
+    else if (a === '--unsafe-skip-redirect-check') args.unsafeSkipRedirectCheck = true;
+    else if (a === '-h' || a === '--help') {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${a}`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage:
+  pnpm tsx scripts/migrate-from-nocodb.ts --dry-run [--port-slug <slug>]
+    Pulls NocoDB → transforms → writes report to .migration/<timestamp>/.
+    No database writes.
+
+  pnpm tsx scripts/migrate-from-nocodb.ts --apply --port-slug <slug>
+    Re-fetches NocoDB, re-transforms, writes via migration_source_links
+    ledger. Idempotent — safe to re-run. Requires EMAIL_REDIRECT_TO set
+    (unless --unsafe-skip-redirect-check is also passed).
+
+Flags:
+  --dry-run                       Read NocoDB, write report only.
+  --apply                         Actually write rows to the DB.
+  --port-slug <slug>              Port slug to attach to all imported
+                                  entities. Defaults to the first
+                                  available port if omitted.
+  --report <dir>                  Path to a previously-generated report
+                                  dir (only used by --apply).
+  --unsafe-skip-redirect-check    Skip the EMAIL_REDIRECT_TO precondition
+                                  check. Only use in production cutover.
+  -h, --help                      Show this help.
+`);
+}
+
+/**
+ * Resolve the target port: use the slug if provided, otherwise the first
+ * port found. Errors out cleanly if the slug doesn't match any port.
+ */
+async function resolvePort(slug: string | null): Promise<{ id: string; slug: string }> {
+  if (slug) {
+    const [p] = await db
+      .select({ id: ports.id, slug: ports.slug })
+      .from(ports)
+      .where(eq(ports.slug, slug))
+      .limit(1);
+    if (!p) {
+      console.error(`No port found with slug "${slug}".`);
+      process.exit(1);
+    }
+    return { id: p.id, slug: p.slug };
+  }
+  const [first] = await db.select({ id: ports.id, slug: ports.slug }).from(ports).limit(1);
+  if (!first) {
+    console.error('No ports exist in the target DB. Seed at least one port before applying.');
+    process.exit(1);
+  }
+  return { id: first.id, slug: first.slug };
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.dryRun && !args.apply) {
+    console.error('Must specify --dry-run or --apply');
+    printHelp();
+    process.exit(1);
+  }
+
+  // Safety gate: --apply must run with EMAIL_REDIRECT_TO set, unless the
+  // operator explicitly opts out (production cutover).
+  if (args.apply && !process.env.EMAIL_REDIRECT_TO && !args.unsafeSkipRedirectCheck) {
+    console.error(
+      '--apply requires EMAIL_REDIRECT_TO to be set in the environment as a safety net.',
+    );
+    console.error('See docs/operations/outbound-comms-safety.md for the rationale.');
+    console.error(
+      'If you are running the production cutover and have read that doc, add ' +
+        '--unsafe-skip-redirect-check to override.',
+    );
+    process.exit(2);
+  }
+
+  // ── Fetch + transform (shared by dry-run and apply) ──────────────────────
+
+  console.log('[migrate] Loading NocoDB config…');
+  const config = loadNocoDbConfig();
+  console.log(`[migrate] Source: ${config.url}`);
+
+  console.log('[migrate] Fetching snapshot from NocoDB…');
+  const start = Date.now();
+  const snapshot = await fetchSnapshot(config);
+  const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+  console.log(
+    `[migrate] Snapshot fetched in ${elapsed}s — ${snapshot.interests.length} interests, ${snapshot.residentialInterests.length} residential, ${snapshot.berths.length} berths.`,
+  );
+
+  console.log('[migrate] Running transform + dedup pipeline…');
+  const plan = transformSnapshot(snapshot);
+
+  // Resolve output paths relative to the worktree root.
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const repoRoot = path.resolve(scriptDir, '..');
+  const generatedAt = new Date().toISOString();
+  const paths = resolveReportPaths(repoRoot);
+
+  console.log(`[migrate] Writing report to ${paths.rootDir}…`);
+  await writeReport(paths, plan, generatedAt);
+
+  // ── Plan summary ─────────────────────────────────────────────────────────
+  const s = plan.stats;
+  console.log('');
+  console.log('=== Migration Plan Summary ===');
+  console.log(
+    `  Input:     ${s.inputInterestRows} interests, ${s.inputResidentialRows} residential interests`,
+  );
+  console.log(`  Output:    ${s.outputClients} clients, ${s.outputInterests} interests`);
+  console.log(`             ${s.outputContacts} contacts, ${s.outputAddresses} addresses`);
+  console.log(
+    `             ${s.outputDocuments} EOI documents, ${s.outputDocumentSigners} signers`,
+  );
+  console.log(
+    `             ${s.outputResidentialClients} residential clients (with default-stage interests)`,
+  );
+  console.log(
+    `  Dedup:     ${s.autoLinkedClusters} auto-linked clusters, ${s.needsReviewPairs} pairs flagged for review`,
+  );
+  console.log(`  Quality:   ${s.flaggedRows} rows flagged (see report.csv)`);
+  console.log('');
+  console.log(`  Full report: ${paths.summaryPath}`);
+
+  if (args.dryRun) {
+    console.log('');
+    console.log('Dry-run complete. Re-run with --apply to write rows.');
+    return;
+  }
+
+  // ── Apply path ───────────────────────────────────────────────────────────
+
+  const port = await resolvePort(args.portSlug);
+  const applyId = randomUUID();
+
+  console.log('');
+  console.log(`[migrate] Applying to port "${port.slug}" (id=${port.id})`);
+  console.log(`[migrate] Apply id: ${applyId}`);
+  console.log('[migrate] Inserting…');
+
+  const applyStart = Date.now();
+  const result = await applyPlan(plan, { port, applyId });
+  const applyElapsed = ((Date.now() - applyStart) / 1000).toFixed(1);
+
+  console.log('');
+  console.log('=== Apply Result ===');
+  console.log(`  Time:      ${applyElapsed}s`);
+  console.log(
+    `  Clients:   ${result.clientsInserted} inserted, ${result.clientsSkipped} already linked`,
+  );
+  console.log(`  Contacts:  ${result.contactsInserted} inserted`);
+  console.log(`  Addresses: ${result.addressesInserted} inserted`);
+  console.log(`  Yachts:    ${result.yachtsInserted} inserted`);
+  console.log(
+    `  Interests: ${result.interestsInserted} inserted, ${result.interestsSkipped} already linked`,
+  );
+  console.log(
+    `  Documents: ${result.documentsInserted} inserted, ${result.documentsSkipped} already linked`,
+  );
+  console.log(`  Signers:   ${result.documentSignersInserted} inserted`);
+  console.log(
+    `  Res-Clt:   ${result.residentialClientsInserted} inserted, ${result.residentialClientsSkipped} already linked`,
+  );
+  console.log(`  Res-Int:   ${result.residentialInterestsInserted} inserted`);
+
+  if (result.warnings.length > 0) {
+    console.log('');
+    console.log('Warnings:');
+    for (const w of result.warnings.slice(0, 20)) {
+      console.log(`  - ${w}`);
+    }
+    if (result.warnings.length > 20) {
+      console.log(`  … ${result.warnings.length - 20} more`);
+    }
+  }
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error('[migrate] Fatal error:', err);
+  process.exit(1);
+});

scripts/migrate-storage.ts

@@ -0,0 +1,29 @@
+/**
+ * Storage backend migration CLI — see §4.7a + §14.9a of
+ * docs/berth-recommender-and-pdf-plan.md.
+ *
+ *   pnpm tsx scripts/migrate-storage.ts --from s3 --to filesystem [--dry-run]
+ *   pnpm tsx scripts/migrate-storage.ts --from filesystem --to s3
+ *
+ * The actual migration logic lives in `src/lib/storage/migrate.ts` so the
+ * admin UI's "Switch backend" button can run the exact same code path. This
+ * file is a thin CLI wrapper.
+ */
+
+import { logger } from '@/lib/logger';
+import { parseArgs, runMigration } from '@/lib/storage/migrate';
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  logger.info({ args }, 'Starting storage migration');
+  const result = await runMigration(args);
+  logger.info({ result }, 'Storage migration complete');
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(0);
+}
+
+main().catch((err) => {
+  logger.error({ err }, 'Storage migration failed');
+  console.error(err);
+  process.exit(2);
+});

scripts/smoke-test-redirect.ts

@@ -0,0 +1,106 @@
+/**
+ * Live smoke test for EMAIL_REDIRECT_TO.
+ *
+ * Actually calls `sendEmail()` (the centralized helper used by every
+ * outbound email path in the app) with a fake real-client address. The
+ * SMTP transporter is monkey-patched to capture the message instead of
+ * actually delivering it, so this is safe to run anywhere.
+ *
+ * Prints the captured `to` + `subject` so the operator can see with their
+ * own eyes that the redirect happened. Exits non-zero if the redirect
+ * failed for any reason.
+ *
+ * Usage:
+ *   pnpm tsx scripts/smoke-test-redirect.ts
+ */
+import 'dotenv/config';
+
+async function main() {
+  const expectedRedirect = process.env.EMAIL_REDIRECT_TO;
+  if (!expectedRedirect) {
+    console.error('FAIL: EMAIL_REDIRECT_TO is not set in env. Set it before running this test.');
+    process.exit(1);
+  }
+
+  console.log(`[smoke] EMAIL_REDIRECT_TO = ${expectedRedirect}`);
+  console.log('');
+
+  // Monkey-patch nodemailer's createTransport so we capture the call
+  // without actually delivering. This is the same pattern the unit
+  // tests use, but at the live import-time level so we're testing the
+  // exact code path that runs in production.
+  const nodemailer = await import('nodemailer');
+  const captured: Array<{ to: unknown; subject: unknown; from: unknown }> = [];
+  const originalCreateTransport = nodemailer.default.createTransport;
+  nodemailer.default.createTransport = (() => ({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    sendMail: async (msg: any) => {
+      captured.push({ to: msg.to, subject: msg.subject, from: msg.from });
+      return { messageId: '<smoke@test>', accepted: [msg.to], rejected: [] };
+    },
+  })) as unknown as typeof nodemailer.default.createTransport;
+
+  // Now import sendEmail (gets the patched transporter).
+  const { sendEmail } = await import('@/lib/email');
+
+  const realClientEmail = 'real-client-DO-NOT-EMAIL@example.test';
+  const realSubject = 'Important: Your contract is ready';
+
+  console.log('[smoke] calling sendEmail(...) with:');
+  console.log(`         to:      ${realClientEmail}`);
+  console.log(`         subject: "${realSubject}"`);
+  console.log('');
+
+  await sendEmail(realClientEmail, realSubject, '<p>Body unused for this smoke.</p>');
+
+  // Restore the original transport (be a good citizen).
+  nodemailer.default.createTransport = originalCreateTransport;
+
+  console.log('[smoke] captured outbound message:');
+  console.log(`         to:      ${captured[0]?.to}`);
+  console.log(`         subject: "${captured[0]?.subject}"`);
+  console.log(`         from:    ${captured[0]?.from}`);
+  console.log('');
+
+  // Assertions
+  let pass = true;
+
+  if (captured.length !== 1) {
+    console.error(`FAIL: expected exactly 1 sendMail call, got ${captured.length}`);
+    pass = false;
+  }
+
+  if (captured[0]?.to !== expectedRedirect) {
+    console.error(
+      `FAIL: outbound "to" was "${captured[0]?.to}", expected the redirect address "${expectedRedirect}"`,
+    );
+    pass = false;
+  }
+
+  if (
+    typeof captured[0]?.subject !== 'string' ||
+    !captured[0].subject.startsWith(`[redirected from ${realClientEmail}]`)
+  ) {
+    console.error(
+      `FAIL: subject did not get the [redirected from <orig>] prefix. Got: "${captured[0]?.subject}"`,
+    );
+    pass = false;
+  }
+
+  if (pass) {
+    console.log('PASS: EMAIL_REDIRECT_TO is intercepting outbound email correctly.');
+    console.log(
+      '      The "to" header matches the redirect, and the original recipient is preserved in the subject.',
+    );
+    process.exit(0);
+  } else {
+    console.error('');
+    console.error('Smoke test FAILED. Do not import production data until this is fixed.');
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('FATAL:', err);
+  process.exit(1);
+});

scripts/test-currency-api.ts

@@ -0,0 +1,42 @@
+/**
+ * Quick verification: live Frankfurter API → DB upsert → getRate read.
+ * Run with `pnpm tsx scripts/test-currency-api.ts`.
+ */
+import { refreshRates, getRate, convert } from '@/lib/services/currency';
+
+async function main() {
+  console.log('1. Fetching live rates from Frankfurter…');
+  await refreshRates();
+
+  console.log('2. Reading round-trip rates from DB:');
+  const usdEur = await getRate('USD', 'EUR');
+  const eurUsd = await getRate('EUR', 'USD');
+  const usdGbp = await getRate('USD', 'GBP');
+  const eurGbp = await getRate('EUR', 'GBP');
+  const usdUsd = await getRate('USD', 'USD');
+
+  console.log(`  USD→EUR: ${usdEur}`);
+  console.log(`  EUR→USD: ${eurUsd}`);
+  console.log(`  USD→GBP: ${usdGbp}`);
+  console.log(`  EUR→GBP: ${eurGbp ?? '(no direct row, expected)'}`);
+  console.log(`  USD→USD: ${usdUsd}`);
+
+  console.log('3. Convert sample amounts:');
+  const c1 = await convert(1000, 'USD', 'EUR');
+  console.log(`  $1000 → ${c1?.result} EUR @ ${c1?.rate}`);
+  const c2 = await convert(500, 'EUR', 'USD');
+  console.log(`  €500 → $${c2?.result} @ ${c2?.rate}`);
+
+  // Sanity: EUR→USD should be ≈ 1 / (USD→EUR), within rounding
+  if (usdEur && eurUsd) {
+    const drift = Math.abs(eurUsd - 1 / usdEur);
+    console.log(`4. Inverse-rate drift: ${drift.toFixed(6)} (≤0.001 = healthy)`);
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Currency test failed:', err);
+  process.exit(1);
+});