diff --git a/content/pages/api/gm.mdx b/content/pages/api/gm.mdx
index a67d6d87..61c47fcc 100644
--- a/content/pages/api/gm.mdx
+++ b/content/pages/api/gm.mdx
@@ -626,6 +626,13 @@ The response object is passed to each event handler with the following propertie
 
 Downloads a URL to a local file.
 
+By default the download is performed via XMLHttpRequest (like `GM_xmlhttpRequest`).
+
+When the **"Use browser download API"** option is enabled in Violentmonkey's Advanced
+settings, the download is delegated to the browser's native download manager
+(`browser.downloads.download`) instead, skipping XHR. This mode allows
+filenames with subfolders and to show progress in the browser's download bar.
+
 1. using an object:
 
     ```js
@@ -640,10 +647,31 @@ Downloads a URL to a local file.
 
         - <Field name="name" type="string" />
 
-            The filename to save to. Folders/subpaths aren't supported yet.
+            The filename to save to. When using the browser download API, subfolder
+            paths (e.g. `"sub/file.txt"`) are supported if using the browser download api.
 
         Most [GM_xmlhttpRequest](#gm_xmlhttprequest) options are supported.
 
+        When using the browser download API, the following additional options
+        are also available:
+
+        - <Field name="saveAs?" type="boolean" />
+
+            Show a "Save As" dialog regardless of the browser's download preferences.
+
+        - <Field name="conflictAction?" type="string" />
+
+            Action when a file with the same name already exists:
+            `"uniquify"` (default), `"overwrite"`, or `"prompt"`.
+
+        - <Field name="method?" type="string" />
+
+            HTTP method for the download request (e.g. `"GET"`, `"POST"`).
+
+        - <Field name="body?" type="string" />
+
+            Request body to send with the download request.
+
         - <Field name="headers?" type="object" />
         - <Field name="timeout?" type="number" comment="since VM2.9.5" />
         - <Field name="context?" type="any" comment="since VM2.13.4" />
@@ -659,7 +687,8 @@ Downloads a URL to a local file.
         - <Field name="onreadystatechange?" type="() => void" comment="since VM2.13.4" />
         - <Field name="ontimeout?" type="() => void" />
 
-       The `onload` event handler is called after the data is downloaded from URL, before writing the file.
+       The `onload` event handler is called after the data is downloaded from URL,
+       before writing the file (XHR path only; ignored when using the browser API).
 
 2. using separate parameters:
 
@@ -673,13 +702,15 @@ Downloads a URL to a local file.
 
     - <Field name="name" type="string" />
 
-      The filename to save to. Folders/subpaths aren't supported yet.
+      The filename to save to.
 
 Returns a control object with the following properties, same as [GM_xmlhttpRequest](#gm_xmlhttprequest):
 
 - <Field name="abort" type="() => void" />
 
-  A function to abort the request.
+  A function to abort the request (XHR path only; no-op when using the browser API).
+
+When using `GM.download`, the returned Promise resolves when the download completes.
 
 ## GM.*