feat(docs): nested-entity 'This deal' / 'From client' split (B4 #8 phase 4)

Finishes B4 #8 by completing the UI half of the per-interest filing
model. Backend foundations (files.interest_id column, ensureEntityFolder
for 'interest', upload-zone scope radio, outcome rename hook, backfill)
shipped earlier in this audit cycle.

- listFiles validator + service: optional interestId filter
- listFilesAggregatedByEntity: routes entityType='interest' to a new
  helper that returns "THIS DEAL" + "FROM CLIENT" + symmetric-reach
  company/yacht groups
- InterestDocumentsTab: Attachments section now renders two cohorts
  via two paginated queries, with client-side de-duplication so files
  filed under this deal don't double-count under "From client"
- FileRow type exposes the optional interestId so the de-dupe filter
  doesn't need a re-fetch

src/components/files/file-grid.tsx

@@ -32,6 +32,10 @@ export interface FileRow {
   category: string | null;
   createdAt: string | Date;
   uploadedBy: string;
+  /** Optional — present when the file is scoped to a sales deal.
+   *  Consumers like InterestDocumentsTab filter on this to split the
+   *  "This deal" vs "From client" cohorts. */
+  interestId?: string | null;
 }
 
 interface FileGridProps {

src/components/interests/interest-documents-tab.tsx

@@ -45,24 +45,34 @@ export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps)
       apiFetch<{ data: InterestData }>(`/api/v1/interests/${interestId}`).then((r) => r.data),
   });
 
-  // Files attach at the client level (the schema has no interest_id
-  // FK on `files`). For an interest, surface every file that belongs
-  // to its parent client - covers the realistic case where a rep
-  // uploaded a passport / scan / photo while working a deal.
-  // Until the interest record loads we pass a sentinel clientId so the
-  // server returns empty rather than the unscoped port-wide file list.
+  // Two cohorts: files tagged with this interestId ("This deal") +
+  // files belonging to the parent client without an interestId, or
+  // tagged to another interest of the same client ("From client").
+  // Until the interest record loads we pass a sentinel clientId so
+  // the server returns empty rather than the unscoped port-wide list.
   const clientId = interest?.clientId ?? '__pending__';
-  const filesQueryKey = ['files', { clientId }] as const;
-  const { data: files, isLoading: filesLoading } = usePaginatedQuery<FileRow>({
-    queryKey: filesQueryKey,
+  const thisDealQueryKey = ['files', { interestId }] as const;
+  const fromClientQueryKey = ['files', { clientId }] as const;
+
+  const { data: thisDealFiles, isLoading: thisDealLoading } = usePaginatedQuery<FileRow>({
+    queryKey: thisDealQueryKey,
+    endpoint: `/api/v1/files?interestId=${encodeURIComponent(interestId)}`,
+    filterDefinitions: [],
+  });
+
+  const { data: clientFiles, isLoading: clientFilesLoading } = usePaginatedQuery<FileRow>({
+    queryKey: fromClientQueryKey,
     endpoint: `/api/v1/files?clientId=${encodeURIComponent(clientId)}`,
     filterDefinitions: [],
   });
 
+  // "From client" excludes anything we already surface under "This deal".
+  const fromClientFiles = clientFiles.filter((f) => !f.interestId || f.interestId !== interestId);
+
   useRealtimeInvalidation({
-    'file:uploaded': [filesQueryKey],
-    'file:updated': [filesQueryKey],
-    'file:deleted': [filesQueryKey],
+    'file:uploaded': [thisDealQueryKey, fromClientQueryKey],
+    'file:updated': [thisDealQueryKey, fromClientQueryKey],
+    'file:deleted': [thisDealQueryKey, fromClientQueryKey],
   });
 
   const handleDownload = async (file: FileRow) => {
@@ -85,13 +95,16 @@ export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps)
     if (!ok) return;
     try {
       await apiFetch(`/api/v1/files/${file.id}`, { method: 'DELETE' });
-      queryClient.invalidateQueries({ queryKey: filesQueryKey });
+      queryClient.invalidateQueries({ queryKey: thisDealQueryKey });
+      queryClient.invalidateQueries({ queryKey: fromClientQueryKey });
     } catch {
       // silent
     }
   };
 
-  const hasAttachments = files.length > 0;
+  const hasThisDeal = thisDealFiles.length > 0;
+  const hasFromClient = fromClientFiles.length > 0;
+  const hasAttachments = hasThisDeal || hasFromClient;
 
   return (
     <div className="space-y-8">
@@ -129,7 +142,8 @@ export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps)
           <h3 className="text-sm font-medium text-muted-foreground">Attachments</h3>
           {hasAttachments ? (
             <span className="text-xs text-muted-foreground">
-              {files.length} file{files.length === 1 ? '' : 's'}
+              {thisDealFiles.length + fromClientFiles.length} file
+              {thisDealFiles.length + fromClientFiles.length === 1 ? '' : 's'}
             </span>
           ) : null}
         </div>
@@ -148,22 +162,44 @@ export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps)
               // client-level.
               interestId={interestId}
               onUploadComplete={() => {
-                queryClient.invalidateQueries({ queryKey: filesQueryKey });
+                queryClient.invalidateQueries({ queryKey: thisDealQueryKey });
+                queryClient.invalidateQueries({ queryKey: fromClientQueryKey });
               }}
             />
           ) : null}
         </PermissionGate>
 
-        {hasAttachments ? (
-          <FileGrid
-            files={files}
-            onDownload={handleDownload}
-            onPreview={setPreviewFile}
-            onRename={() => {}}
-            onDelete={handleDelete}
-            isLoading={filesLoading}
-          />
-        ) : null}
+        {(hasThisDeal || thisDealLoading) && (
+          <div className="space-y-2">
+            <h4 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+              This deal
+            </h4>
+            <FileGrid
+              files={thisDealFiles}
+              onDownload={handleDownload}
+              onPreview={setPreviewFile}
+              onRename={() => {}}
+              onDelete={handleDelete}
+              isLoading={thisDealLoading}
+            />
+          </div>
+        )}
+
+        {(hasFromClient || clientFilesLoading) && (
+          <div className="space-y-2">
+            <h4 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+              From client
+            </h4>
+            <FileGrid
+              files={fromClientFiles}
+              onDownload={handleDownload}
+              onPreview={setPreviewFile}
+              onRename={() => {}}
+              onDelete={handleDelete}
+              isLoading={clientFilesLoading}
+            />
+          </div>
+        )}
       </section>
 
       <EoiGenerateDialog