diff --git a/packages/@uppy/core/src/Uppy.ts b/packages/@uppy/core/src/Uppy.ts
index 6f13065b2..f434894ae 100644
--- a/packages/@uppy/core/src/Uppy.ts
+++ b/packages/@uppy/core/src/Uppy.ts
@@ -1181,9 +1181,13 @@ export class Uppy<
   }
 
   /**
-   * Add a new file to `state.files`. This will run `onBeforeFileAdded`,
-   * try to guess file type in a clever way, check file against restrictions,
-   * and start an upload if `autoProceed === true`.
+   * Add a new file to `state.files`. Runs `onBeforeFileAdded`, guesses the
+   * file type, checks the file against restrictions, and starts an upload if
+   * `autoProceed === true`.
+   *
+   * Emits `file-added` and `files-added` with a single-element array. Throws
+   * on the first error, including restriction errors. Use `addFiles` for
+   * multi-file adds — see its documentation for batch semantics.
    */
   addFile(file: File | MinimalRequiredUppyFile<M, B>): UppyFile<M, B>['id'] {
     const { nextFilesState, validFilesToAdd, errors } =
@@ -1210,11 +1214,20 @@ export class Uppy<
   }
 
   /**
-   * Add multiple files to `state.files`. See the `addFile()` documentation.
+   * Add multiple files to `state.files`.
    *
-   * If an error occurs while adding a file, it is logged and the user is notified.
-   * This is good for UI plugins, but not for programmatic use.
-   * Programmatic users should usually still use `addFile()` on individual files.
+   * Emits `file-added` per accepted file and `files-added` once for the batch.
+   * Restriction failures emit `restriction-failed` and show an info message
+   * without throwing — valid files in the same batch are still added. Any
+   * non-restriction error (for example, an exception from `onBeforeFileAdded`)
+   * is aggregated into an `AggregateError` (with `.errors`) and thrown
+   * *before* state is updated — when this happens, no files from the batch
+   * are added and `files-added` is not emitted.
+   *
+   * Prefer this over calling `addFile` in a loop when adding multiple files:
+   * batch listeners on `files-added` fire exactly once, and restriction
+   * failures on individual files do not abort the batch. Non-restriction
+   * errors still abort the batch before any files are added.
    */
   addFiles(fileDescriptors: MinimalRequiredUppyFile<M, B>[]): void {
     const { nextFilesState, validFilesToAdd, errors } =