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/app/(dashboard)/[portSlug]/admin/documenso/page.tsx

@@ -250,11 +250,12 @@ export default function DocumensoSettingsPage() {
                 />
                 <span>
                   <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>/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 — see the deferred-roadmap below).
+                  <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>/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 —
+                  see the deferred-roadmap below).
                 </span>
               </li>
               <li className="flex items-start gap-2">
@@ -263,8 +264,8 @@ export default function DocumensoSettingsPage() {
                   aria-hidden="true"
                 />
                 <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
+                  <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
                   separate GET to fetch them. Faster send flow on the rep side.
                 </span>
               </li>
@@ -288,10 +289,9 @@ export default function DocumensoSettingsPage() {
                 <span>
                   <strong>Post-signing redirect URL.</strong> Set in the &quot;v2 signing
                   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.)
+                  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.)
                 </span>
               </li>
             </ul>
@@ -320,14 +320,14 @@ export default function DocumensoSettingsPage() {
                 re-generating.
               </li>
               <li>
-                <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.
+                <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 the new &quot;v2 signing behaviour&quot; card below to configure them.
+              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>

src/components/dashboard/dashboard-shell.tsx

@@ -73,9 +73,7 @@ export function DashboardShell() {
   const firstName = me.data?.data?.firstName?.trim();
   // Time-aware greeting line, falls back to a generic "Welcome back" when
   // we don't know the user's first name yet (e.g. profile not filled out).
-  const greeting = firstName
-    ? `${timeOfDayGreeting()}, ${firstName}`
-    : 'Welcome back';
+  const greeting = firstName ? `${timeOfDayGreeting()}, ${firstName}` : 'Welcome back';
 
   // Use a partial query-key prefix (no range segment) for invalidations.
   // Reading: "any cached analytics result, regardless of range, please

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>
+    </>
+  );
+}

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

@@ -85,9 +85,9 @@ export function FileUploadZone({
               throw new Error('Upload failed');
             }
 
-            const uploadJson = (await uploadRes
-              .json()
-              .catch(() => null)) as { data?: { id?: string; filename?: string } } | null;
+            const uploadJson = (await uploadRes.json().catch(() => null)) as {
+              data?: { id?: string; filename?: string };
+            } | null;
             if (uploadJson?.data?.id) {
               onUploadComplete?.({
                 id: uploadJson.data.id,