Merge main into feat/bulk-rating and rebuild dist

docs/API_REFERENCE.md

@@ -1226,6 +1226,51 @@ POST /mjr/am/db/force-delete
 
 ---
 
+### Trash Status
+```http
+GET /mjr/am/trash
+```
+
+**Purpose**: Report how many freedesktop trash entries came from Majoor's folders (output, input, custom roots). Linux/BSD only; the response never contains file paths. Rate-limited to 20 requests per 60 seconds.
+
+**Response**:
+```json
+{
+  "ok": true,
+  "data": {
+    "supported": true,
+    "count": 3,
+    "bytes": 1048576
+  }
+}
+```
+
+---
+
+### Empty Trash
+```http
+POST /mjr/am/trash/empty
+```
+
+**Purpose**: Permanently remove the freedesktop trash entries whose original location was inside a Majoor folder. Entries from outside Majoor's folders, orphans, and symlink-reachable payloads are never touched; a trash directory is only used when it belongs to the current user and is not group/world-writable. Directories inside the trash are never removed (reported in `skipped_dirs`). Requires the same permission as asset deletion (`allow_delete` / `MAJOOR_ALLOW_DELETE=1`); rate-limited to 3 requests per 60 seconds.
+
+**Response**:
+```json
+{
+  "ok": true,
+  "data": {
+    "removed": 3,
+    "bytes": 1048576,
+    "failed": [],
+    "skipped_dirs": 0
+  }
+}
+```
+
+`failed` lists entries that could not be removed (`name` + `error`); the remaining entries are still removed. `skipped_dirs` counts directory payloads, which are left in place.
+
+---
+
 ## Utilities
 
 ### Date Histogram

docs/DB_MAINTENANCE.md

@@ -88,6 +88,25 @@ Open the Assets Manager panel and expand the **Index Status** section. Maintenan
 | **Memory purge** | Unloads Majoor AI models, asks ComfyUI to unload loaded models, and clears torch cache when the queue is idle. |
 | **Reset index** | Clears cached data inside the existing database and triggers a background rescan. Requires the database to be readable. |
 | **Delete DB** | Force-deletes the database files from disk (bypassing all DB-dependent checks) and rebuilds from scratch. Works even when the database is corrupted. |
+| **Empty trash** | Permanently removes the files Majoor sent to the freedesktop trash. Linux/BSD only; requires the delete permission (`allow_delete` / `MAJOOR_ALLOW_DELETE=1`). |
+
+## Empty Trash
+
+Majoor deletes files through the system trash (`send2trash`). On Linux and the BSDs those files land in the freedesktop trash (`~/.local/share/Trash` or `<mount>/.Trash-<uid>`), and on a headless server nothing ever clears it — so deleting assets never actually frees disk space.
+
+The **Empty trash** button in the Status panel fixes that:
+
+1. It counts only trash entries whose original location (recorded in each `.trashinfo` file) was inside one of Majoor's folders (output, input, or a custom root).
+2. It asks for confirmation showing the count and total size.
+3. On confirm it permanently deletes those entries — payload **and** metadata — via `POST /mjr/am/trash/empty`.
+
+Notes:
+
+- Selection is by original location, so files you trashed from those same folders with **other tools are included** and will be permanently deleted too.
+- Entries from outside Majoor's folders, orphans without trash metadata, and anything reachable only through a symlink are never touched.
+- **Directories in the trash are never removed.** Majoor only ever trashes files; a trashed directory (and its contents) is left in place and reported as skipped. Clear those by hand if needed.
+- **Ownership requirement:** a trash directory is only used when it belongs to the user running ComfyUI and is not group- or world-writable. Trash state planted by another user on a shared mount is ignored.
+- The button is hidden on non-freedesktop platforms (Windows/macOS) and disabled when deletion is disabled, because emptying shares the `allow_delete` gate with asset deletion.
 
 ## Reset Index
 

docs/SECURITY_ENV_VARS.md

@@ -110,6 +110,7 @@ Safe Mode adds an explicit opt-in layer for operations that modify files or user
   - Allows rating/tags writes while Safe Mode is enabled.
 - `MAJOOR_ALLOW_DELETE=1`
   - Enables asset deletion (disabled by default).
+  - Also gates emptying the freedesktop trash (`POST /mjr/am/trash/empty`), which permanently removes trashed files.
 - `MAJOOR_ALLOW_RENAME=1`
   - Enables asset rename (disabled by default).
 - `MAJOOR_ALLOW_OPEN_IN_FOLDER=1`