feat(documents-hub): NewDocumentMenu dropdown + FolderDropZone drag-drop

Replaces the bare "+ New document" Button on the documents hub with a
NewDocumentMenu dropdown so reps explicitly pick between:
- "Upload file" → opens a Dialog with FileUploadZone scoped to the
  current folder + entity context. No signing flow attached.
- "Generate document for signing" → navigates to /documents/new wizard.

Avoids the prior ambiguity where reps clicked "+ New document" intending
to attach a file and were dropped into the Documenso signer wizard.

Also adds FolderDropZone wrapping FlatFolderListing and EntityFolderView.
Dragging files from the OS over the current folder shows a drop overlay;
drop fires N parallel uploads carrying the folder + entity context.
Mirrors the per-entity Files tab UX but works in-place on the hub.

Both surfaces hit /api/v1/files/upload with folderId + entityType/Id +
the legacy clientId/companyId/yachtId FKs so files land on the right
entity AND inside the correct folder.

Also includes the in-flight prettier reformat from lint-staged on a
few previously-touched files (create-document-wizard, file-upload-zone,
admin/documenso/page) and adds the standalone prod-readiness audit
report to docs/superpowers/audits/ for permanent reference.

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

src/components/documents/create-document-wizard.tsx

@@ -265,8 +265,8 @@ export function CreateDocumentWizard({ portSlug }: CreateDocumentWizardProps) {
                   />
                 )}
                 <p className="text-xs text-muted-foreground">
-                  Drop a PDF or click to browse. The file is stored, then the wizard wires it as
-                  the source for signing.
+                  Drop a PDF or click to browse. The file is stored, then the wizard wires it as the
+                  source for signing.
                 </p>
               </div>
             )}

src/components/documents/documents-hub.tsx

@@ -1,8 +1,9 @@
 'use client';
 
-import { useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import Link from 'next/link';
-import { ChevronDown, ChevronRight, FileText, Plus } from 'lucide-react';
+import { useQueryClient } from '@tanstack/react-query';
+import { ChevronDown, ChevronRight, FileText, Plus, Upload } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
@@ -15,11 +16,13 @@ import { usePaginatedQuery } from '@/hooks/use-paginated-query';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { useDocumentFolders, type FolderNode } from '@/hooks/use-document-folders';
 import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';
+import { useUIStore } from '@/stores/ui-store';
 import { FolderActionsMenu } from './folder-actions-menu';
 import { FolderBreadcrumb } from './folder-breadcrumb';
 import { FolderTreeSidebar } from './folder-tree-sidebar';
 import { HubRootView } from './hub-root-view';
 import { EntityFolderView } from './entity-folder-view';
+import { NewDocumentMenu } from './new-document-menu';
 
 interface HubDoc {
   id: string;
@@ -154,12 +157,15 @@ export function DocumentsHub({ portSlug }: DocumentsHubProps) {
         <div className="flex items-center justify-between gap-3">
           <FolderBreadcrumb selectedFolderId={selectedFolderId} onSelect={handleFolderSelect} />
           {selectedFolderId !== undefined && (
-            <Button asChild size="sm">
-              <Link href={`/${portSlug}/documents/new`}>
-                <Plus className="mr-1.5 h-4 w-4" />
-                New document
-              </Link>
-            </Button>
+            <NewDocumentMenu
+              portSlug={portSlug}
+              folderId={selectedFolderId}
+              entityType={
+                isEntityFolder && isEntityType(folderEntityType) ? folderEntityType : undefined
+              }
+              entityId={isEntityFolder ? (selectedFolder!.entityId ?? undefined) : undefined}
+              size="sm"
+            />
           )}
         </div>
 
@@ -168,30 +174,31 @@ export function DocumentsHub({ portSlug }: DocumentsHubProps) {
             <PageHeader
               title="Documents"
               description="Track signing status, chase pending signers, and audit completion."
-              actions={
-                <Button asChild>
-                  <Link href={`/${portSlug}/documents/new`}>
-                    <Plus className="mr-1.5 h-4 w-4" />
-                    New document
-                  </Link>
-                </Button>
-              }
+              actions={<NewDocumentMenu portSlug={portSlug} />}
               variant="gradient"
             />
             <HubRootView portSlug={portSlug} />
           </>
         ) : isEntityFolder && isEntityType(folderEntityType) ? (
-          <EntityFolderView
-            portSlug={portSlug}
+          <FolderDropZone
+            folderId={selectedFolderId}
             entityType={folderEntityType}
             entityId={selectedFolder!.entityId!}
-          />
+          >
+            <EntityFolderView
+              portSlug={portSlug}
+              entityType={folderEntityType}
+              entityId={selectedFolder!.entityId!}
+            />
+          </FolderDropZone>
         ) : (
-          <FlatFolderListing
-            key={selectedFolderId ?? 'root'}
-            portSlug={portSlug}
-            folderId={selectedFolderId}
-          />
+          <FolderDropZone folderId={selectedFolderId}>
+            <FlatFolderListing
+              key={selectedFolderId ?? 'root'}
+              portSlug={portSlug}
+              folderId={selectedFolderId}
+            />
+          </FolderDropZone>
         )}
       </div>
     </div>
@@ -373,3 +380,119 @@ function FlatFolderListing({ portSlug, folderId }: FlatFolderListingProps) {
     </>
   );
 }
+
+// ---------------------------------------------------------------------------
+// FolderDropZone — wraps the main content panel and accepts file drops onto
+// the currently-viewed folder. Files dropped here upload with folder_id +
+// entity FKs set so they land where the rep expects.
+//
+// Renders an overlay while a drag is in progress; the underlying content
+// stays interactive. Multiple files at once are supported (Promise.all
+// inside the upload loop). Errors surface inline; the toast layer picks
+// them up via React Query / fetch error responses.
+// ---------------------------------------------------------------------------
+
+interface FolderDropZoneProps {
+  folderId: string | null;
+  entityType?: 'client' | 'company' | 'yacht';
+  entityId?: string;
+  children: React.ReactNode;
+}
+
+function FolderDropZone({ folderId, entityType, entityId, children }: FolderDropZoneProps) {
+  const [dragActive, setDragActive] = useState(false);
+  const [uploading, setUploading] = useState(false);
+  const dragCounter = useMemo(() => ({ count: 0 }), []);
+  const queryClient = useQueryClient();
+  const portId = useUIStore((s) => s.currentPortId);
+
+  const onDragEnter = useCallback(
+    (e: React.DragEvent<HTMLDivElement>) => {
+      // Only react to drags that carry files. Avoids fighting with
+      // text-selection / element drags inside the listing.
+      if (!Array.from(e.dataTransfer.types).includes('Files')) return;
+      e.preventDefault();
+      dragCounter.count += 1;
+      if (dragCounter.count === 1) setDragActive(true);
+    },
+    [dragCounter],
+  );
+
+  const onDragLeave = useCallback(
+    (e: React.DragEvent<HTMLDivElement>) => {
+      if (!Array.from(e.dataTransfer.types).includes('Files')) return;
+      dragCounter.count -= 1;
+      if (dragCounter.count <= 0) {
+        dragCounter.count = 0;
+        setDragActive(false);
+      }
+    },
+    [dragCounter],
+  );
+
+  const onDragOver = useCallback((e: React.DragEvent<HTMLDivElement>) => {
+    if (!Array.from(e.dataTransfer.types).includes('Files')) return;
+    e.preventDefault();
+    e.dataTransfer.dropEffect = 'copy';
+  }, []);
+
+  const onDrop = useCallback(
+    async (e: React.DragEvent<HTMLDivElement>) => {
+      if (!Array.from(e.dataTransfer.types).includes('Files')) return;
+      e.preventDefault();
+      dragCounter.count = 0;
+      setDragActive(false);
+      const files = Array.from(e.dataTransfer.files);
+      if (files.length === 0) return;
+      setUploading(true);
+      try {
+        await Promise.all(
+          files.map(async (file) => {
+            const fd = new FormData();
+            fd.append('file', file);
+            fd.append('filename', file.name);
+            if (folderId) fd.append('folderId', folderId);
+            if (entityType) fd.append('entityType', entityType);
+            if (entityId) fd.append('entityId', entityId);
+            if (entityType === 'client' && entityId) fd.append('clientId', entityId);
+            if (entityType === 'company' && entityId) fd.append('companyId', entityId);
+            if (entityType === 'yacht' && entityId) fd.append('yachtId', entityId);
+            const headers = new Headers();
+            if (portId) headers.set('X-Port-Id', portId);
+            await fetch('/api/v1/files/upload', {
+              method: 'POST',
+              headers,
+              credentials: 'include',
+              body: fd,
+            });
+          }),
+        );
+        queryClient.invalidateQueries({ queryKey: ['files'] });
+        queryClient.invalidateQueries({ queryKey: ['documents'] });
+      } finally {
+        setUploading(false);
+      }
+    },
+    [dragCounter, folderId, entityType, entityId, portId, queryClient],
+  );
+
+  return (
+    <div
+      onDragEnter={onDragEnter}
+      onDragLeave={onDragLeave}
+      onDragOver={onDragOver}
+      onDrop={onDrop}
+      className="relative"
+    >
+      {children}
+      {(dragActive || uploading) && (
+        <div className="pointer-events-none absolute inset-0 flex items-center justify-center rounded-md border-2 border-dashed border-primary bg-primary/5 backdrop-blur-[1px] z-10">
+          <div className="flex flex-col items-center gap-2 text-sm font-medium text-primary">
+            <Upload className="h-8 w-8" />
+            {uploading ? 'Uploading…' : 'Drop to upload to this folder'}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

src/components/documents/new-document-menu.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import { useState } from 'react';
+import Link from 'next/link';
+import { useQueryClient } from '@tanstack/react-query';
+import { ChevronDown, FileSignature, Plus, Upload } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { FileUploadZone } from '@/components/files/file-upload-zone';
+
+/**
+ * Dropdown that replaces the bare "+ New document" button on the documents
+ * hub. Splits the action into the two real flows so reps know which one
+ * they want before they click:
+ *   - "Upload file" → opens a dialog with FileUploadZone scoped to the
+ *     current folder + entity context. No signing flow attached.
+ *   - "Generate document for signing" → links to /documents/new wizard.
+ *
+ * Folder/entity context is passed through so uploaded files land in the
+ * right place (entity FK + folder_id). Drops do the same via FileUploadZone's
+ * existing folderId / entity props.
+ */
+interface NewDocumentMenuProps {
+  portSlug: string;
+  /** Selected folderId, or null for the root folder, or undefined when the
+   *  user is on the hub landing page (no folder selected). */
+  folderId?: string | null;
+  /** Entity context for system-managed entity folders. When set, uploaded
+   *  files are wired to the right FK column on the files table. */
+  entityType?: 'client' | 'company' | 'yacht';
+  entityId?: string;
+  /** Visual variant: "default" for big banner placement, "sm" for the
+   *  inline-with-breadcrumb placement on folder views. */
+  size?: 'default' | 'sm';
+}
+
+export function NewDocumentMenu({
+  portSlug,
+  folderId,
+  entityType,
+  entityId,
+  size = 'default',
+}: NewDocumentMenuProps) {
+  const [uploadOpen, setUploadOpen] = useState(false);
+  const queryClient = useQueryClient();
+
+  return (
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button size={size}>
+            <Plus className="mr-1.5 h-4 w-4" />
+            New document
+            <ChevronDown className="ml-1.5 h-4 w-4 opacity-80" />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-64">
+          <DropdownMenuItem onSelect={() => setUploadOpen(true)} className="gap-2 py-2.5">
+            <Upload className="h-4 w-4" />
+            <div className="flex flex-col">
+              <span>Upload file</span>
+              <span className="text-xs text-muted-foreground">
+                Drop or browse — stored in the current folder
+              </span>
+            </div>
+          </DropdownMenuItem>
+          <DropdownMenuItem asChild className="gap-2 py-2.5">
+            <Link href={`/${portSlug}/documents/new`}>
+              <FileSignature className="h-4 w-4" />
+              <div className="flex flex-col">
+                <span>Generate document for signing</span>
+                <span className="text-xs text-muted-foreground">
+                  EOI, contract, or custom — sent via Documenso
+                </span>
+              </div>
+            </Link>
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+
+      <Dialog open={uploadOpen} onOpenChange={setUploadOpen}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Upload file</DialogTitle>
+            <DialogDescription>
+              {folderId === undefined
+                ? 'File will be added to the root.'
+                : entityType && entityId
+                  ? `File will be filed under this ${entityType}.`
+                  : 'File will be added to the current folder.'}
+            </DialogDescription>
+          </DialogHeader>
+          <FileUploadZone
+            folderId={folderId ?? null}
+            entityType={entityType}
+            entityId={entityId}
+            clientId={entityType === 'client' ? entityId : undefined}
+            companyId={entityType === 'company' ? entityId : undefined}
+            yachtId={entityType === 'yacht' ? entityId : undefined}
+            onUploadComplete={(file) => {
+              if (!file) {
+                // Trailing "batch done" call — invalidate hub caches so the
+                // newly-uploaded file appears in the Recent files / folder
+                // listings without a manual reload.
+                queryClient.invalidateQueries({ queryKey: ['files'] });
+                queryClient.invalidateQueries({ queryKey: ['documents'] });
+                setUploadOpen(false);
+              }
+            }}
+          />
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}