fix(audit): non-Documenso backlog sweep — port-binding, NULLS NOT DISTINCT, custom merge tokens, company docs

Wave through the remaining audit-final-deferred items that aren't blocked
on the back-burnered Documenso work.

Multi-tenant isolation:
- Storage proxy ProxyTokenPayload gains optional `p` (port slug) claim;
  verifier asserts `key.startsWith(${p}/)`. Defense-in-depth against a
  buggy issuer in some future code path that mixes port scopes — every
  storage key generated by generateStorageKey() already prefixes the
  slug. document-sends opts in for 24h emailed download links; other
  callers continue working unchanged via the optional field.

DB schema reconciliation:
- Migration 0047 rebuilds system_settings unique index with NULLS NOT
  DISTINCT (Postgres 15+) so global settings (port_id IS NULL) are
  uniquely keyed by `key` alone. Surfaced + dedupe'd 65 duplicate
  (storage_backend, NULL) rows that had accumulated from race-prone
  delete-then-insert patterns in ocr-config / settings / residential-
  stages / ai-budget services. All four services converted to true
  onConflictDoUpdate upserts so the race window is closed.

API uniformity:
- Response shape standardization: 16 routes converted from
  `{ success: true }` to 204 No Content. CLAUDE.md documents the
  convention (`{ data: <T> }` for content, 204 for empty mutations,
  portal-auth retains `{ success: true }` for the frontend's auth chain).
- req.json() → parseBody() migration across 9 admin/CRM routes
  (custom-fields, expenses/export ×3, currency convert,
  search/recently-viewed, admin/duplicates, berths/pdf-{upload-url,
  versions, parse-results}). Uniform 400 error shapes for
  ZodError-flagged bodies.

Custom-fields merge tokens (shipped end-to-end):
- merge-fields.ts gains CUSTOM_MERGE_TOKEN_RE + helpers for the
  `{{custom.<fieldName>}}` shape.
- document-templates validator accepts the dynamic shape alongside
  the static catalog tokens.
- document-sends.service mergeCustomFieldValues resolver fetches
  per-port custom_field_definitions for client/interest/berth contexts
  and substitutes stored values keyed by `{{custom.fieldName}}`.
- custom-fields-manager amber banner updated to reflect that merge
  tokens now expand (search index + entity-diff remain documented
  design limitations).

/api/v1/files cross-entity filtering:
- Validator + listFiles + uploadFile accept companyId AND yachtId
  alongside clientId. file-upload-zone propagates both.
- New CompanyFilesTab component mirrors ClientFilesTab; restored as a
  visible Documents tab in company-tabs.tsx (was a hidden stub).

Inline TODOs:
- Reviewed remaining two TODOs (per-user reminder schedule, import
  worker handlers). Both are placeholders for future feature surfaces,
  not bugs — per-port digest works for every customer; nothing
  currently enqueues import jobs (verified). Annotated in BACKLOG.

BACKLOG.md updated to reflect what landed and what's still pending
(Documenso-related items still bundled with the back-burnered phases).

Tests: 1185/1185 vitest, tsc clean.

src/components/admin/custom-fields/custom-fields-manager.tsx

@@ -169,11 +169,12 @@ export function CustomFieldsManager() {
 
       <div className="rounded-md border border-amber-300 bg-amber-50 px-3 py-2.5 text-xs text-amber-900">
         <strong>Heads up:</strong> custom fields render in detail-page sidebars and the entity
-        export, but they don&rsquo;t plug into core platform behaviour: search doesn&rsquo;t index
-        them, the recommender doesn&rsquo;t score on them, audit logs don&rsquo;t diff them, and
-        merge-tokens won&rsquo;t expand them in EOI/contract templates. Use them for rep-only
-        annotations (e.g. &ldquo;Berth visit notes&rdquo;, &ldquo;Referral source&rdquo;) — anything
-        load-bearing for the deal flow needs a first-class column.
+        export, and merge-tokens of the form{' '}
+        <code className="rounded bg-amber-100 px-1">{`{{custom.fieldName}}`}</code> now expand in
+        EOI/contract/email templates for client/interest/berth contexts. They still don&rsquo;t plug
+        into the global search index, the berth recommender, or the entity-diff audit log — use them
+        for rep-only annotations and template-merge values, but anything load-bearing for the deal
+        flow still needs a first-class column.
       </div>
 
       <Tabs value={activeTab} onValueChange={(v) => setActiveTab(v as EntityTab)}>

src/components/companies/company-files-tab.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+
+import { FileGrid } from '@/components/files/file-grid';
+import { FileUploadZone } from '@/components/files/file-upload-zone';
+import { FilePreviewDialog } from '@/components/files/file-preview-dialog';
+import { PermissionGate } from '@/components/shared/permission-gate';
+import { usePaginatedQuery } from '@/hooks/use-paginated-query';
+import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { apiFetch } from '@/lib/api/client';
+import type { FileRow } from '@/components/files/file-grid';
+
+interface CompanyFilesTabProps {
+  companyId: string;
+}
+
+export function CompanyFilesTab({ companyId }: CompanyFilesTabProps) {
+  const queryClient = useQueryClient();
+  const [previewFile, setPreviewFile] = useState<FileRow | null>(null);
+
+  const { data, isLoading } = usePaginatedQuery<FileRow>({
+    queryKey: ['files', { companyId }],
+    endpoint: `/api/v1/files?companyId=${encodeURIComponent(companyId)}`,
+    filterDefinitions: [],
+  });
+
+  useRealtimeInvalidation({
+    'file:uploaded': [['files', { companyId }]],
+    'file:updated': [['files', { companyId }]],
+    'file:deleted': [['files', { companyId }]],
+  });
+
+  const handleDownload = async (file: FileRow) => {
+    try {
+      const res = await apiFetch<{ data: { url: string; filename: string } }>(
+        `/api/v1/files/${file.id}/download`,
+      );
+      const a = document.createElement('a');
+      a.href = res.data.url;
+      a.download = res.data.filename;
+      a.click();
+    } catch {
+      // silent
+    }
+  };
+
+  const handleDelete = async (file: FileRow) => {
+    if (!confirm(`Delete "${file.filename}"? This cannot be undone.`)) return;
+    try {
+      await apiFetch(`/api/v1/files/${file.id}`, { method: 'DELETE' });
+      queryClient.invalidateQueries({ queryKey: ['files', { companyId }] });
+    } catch {
+      // silent
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <PermissionGate resource="files" action="upload">
+        <FileUploadZone
+          companyId={companyId}
+          onUploadComplete={() => {
+            queryClient.invalidateQueries({ queryKey: ['files', { companyId }] });
+          }}
+        />
+      </PermissionGate>
+
+      <FileGrid
+        files={data}
+        onDownload={handleDownload}
+        onPreview={setPreviewFile}
+        onRename={() => {}}
+        onDelete={handleDelete}
+        isLoading={isLoading}
+      />
+
+      <FilePreviewDialog
+        open={!!previewFile}
+        onOpenChange={(open) => !open && setPreviewFile(null)}
+        fileId={previewFile?.id}
+        fileName={previewFile?.filename}
+        mimeType={previewFile?.mimeType ?? undefined}
+      />
+    </div>
+  );
+}

src/components/companies/company-tabs.tsx

@@ -11,6 +11,7 @@ import { NotesList } from '@/components/shared/notes-list';
 import { EntityActivityFeed } from '@/components/shared/entity-activity-feed';
 import { CompanyMembersTab } from '@/components/companies/company-members-tab';
 import { CompanyOwnedYachtsTab } from '@/components/companies/company-owned-yachts-tab';
+import { CompanyFilesTab } from '@/components/companies/company-files-tab';
 import { AddressesEditor, type Address } from '@/components/shared/addresses-editor';
 import { apiFetch } from '@/lib/api/client';
 import type { CountryCode } from '@/lib/i18n/countries';
@@ -226,9 +227,11 @@ export function getCompanyTabs({
         />
       ),
     },
-    // The Documents tab was a "Coming soon" stub. Hidden until the
-    // /api/v1/files endpoint accepts a companyId filter (the schema
-    // supports it; the validator doesn't).
+    {
+      id: 'documents',
+      label: 'Documents',
+      content: <CompanyFilesTab companyId={companyId} />,
+    },
     {
       id: 'notes',
       label: 'Notes',

src/components/files/file-upload-zone.tsx

@@ -16,6 +16,8 @@ interface FileUploadZoneProps {
   entityType?: string;
   entityId?: string;
   clientId?: string;
+  yachtId?: string;
+  companyId?: string;
   onUploadComplete?: () => void;
 }
 
@@ -23,6 +25,8 @@ export function FileUploadZone({
   entityType,
   entityId,
   clientId,
+  yachtId,
+  companyId,
   onUploadComplete,
 }: FileUploadZoneProps) {
   const [isDragOver, setIsDragOver] = useState(false);
@@ -46,6 +50,8 @@ export function FileUploadZone({
             formData.append('file', file);
             formData.append('filename', file.name);
             if (clientId) formData.append('clientId', clientId);
+            if (yachtId) formData.append('yachtId', yachtId);
+            if (companyId) formData.append('companyId', companyId);
             if (entityType) formData.append('entityType', entityType);
             if (entityId) formData.append('entityId', entityId);
 
@@ -54,8 +60,7 @@ export function FileUploadZone({
             );
 
             // Use fetch directly for FormData (apiFetch JSON-encodes body)
-            const portId = (await import('@/stores/ui-store'))
-              .useUIStore.getState().currentPortId;
+            const portId = (await import('@/stores/ui-store')).useUIStore.getState().currentPortId;
             const headers = new Headers();
             if (portId) headers.set('X-Port-Id', portId);
             const uploadRes = await fetch('/api/v1/files/upload', {
@@ -73,9 +78,7 @@ export function FileUploadZone({
             );
           } catch {
             setUploading((prev) =>
-              prev.map((u) =>
-                u.id === uploadId ? { ...u, error: 'Upload failed' } : u,
-              ),
+              prev.map((u) => (u.id === uploadId ? { ...u, error: 'Upload failed' } : u)),
             );
           }
         }),
@@ -87,7 +90,7 @@ export function FileUploadZone({
         onUploadComplete?.();
       }, 1500);
     },
-    [clientId, entityType, entityId, onUploadComplete],
+    [clientId, yachtId, companyId, entityType, entityId, onUploadComplete],
   );
 
   const handleDrop = useCallback(
@@ -135,9 +138,7 @@ export function FileUploadZone({
       >
         <Upload className="h-8 w-8 text-muted-foreground mb-2" />
         <p className="text-sm font-medium">Drop files here or click to upload</p>
-        <p className="text-xs text-muted-foreground mt-1">
-          PDF, Word, Excel, images up to 50MB
-        </p>
+        <p className="text-xs text-muted-foreground mt-1">PDF, Word, Excel, images up to 50MB</p>
         <input
           ref={inputRef}
           type="file"
@@ -169,9 +170,7 @@ export function FileUploadZone({
               {u.error && (
                 <button
                   type="button"
-                  onClick={() =>
-                    setUploading((prev) => prev.filter((x) => x.id !== u.id))
-                  }
+                  onClick={() => setUploading((prev) => prev.filter((x) => x.id !== u.id))}
                 >
                   <X className="h-3.5 w-3.5 text-muted-foreground" />
                 </button>