feat: add file-manager right-click action for PDFsHEADmaster

pput.desktop is a DES-EMA action exposing "Upload to Paperless" on the
context menu for application/pdf, using %F so a whole selection uploads
in one click, not just a single file.

It runs pput-gui rather than pput directly: a click has no terminal, so
the wrapper reports the outcome through notify-send, falling back to
zenity. It also sets PINENTRY_USER_DATA, since pass(1) needs a GUI
pinentry when there is no controlling terminal.

Exec= calls pput-gui by name rather than by absolute path, matching the
other actions in this format and keeping a user's home out of the file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

3 files changed, 83 insertions, 0 deletions

diff --git a/README.md b/README.md
index 5ada7b2..cc45e7d 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,23 @@ pput scan.pdf && rm scan.pdf
 Paperless rejects re-uploads of identical content, reported as
 `duplicate of doc N`.
 
+## File manager integration
+
+`pput.desktop` adds an "Upload to Paperless" entry to the right-click menu for
+PDFs, for file managers that read the DES-EMA actions format (pcmanfm-qt,
+Caja, Nemo). It runs `pput-gui`, a wrapper that reports the result as a
+desktop notification, since a click has no terminal to print to. One file or a
+whole selection both work.
+
+```bash
+ln -s "$PWD/pput-gui" ~/bin/pput-gui
+ln -s "$PWD/pput.desktop" ~/.local/share/file-manager/actions/pput.desktop
+```
+
+`Exec=` calls `pput-gui` by name, so it must be on the `PATH` your desktop
+session exports; use an absolute path there instead if it is not. Restart the
+file manager to pick up a new action.
+
 ## Requirements
 
 - `bash`, `curl`, `python3` (stdlib only)
diff --git a/pput-gui b/pput-gui
new file mode 100755
index 0000000..31d9e53
--- /dev/null
+++ b/pput-gui
@@ -0,0 +1,50 @@
+#!/bin/bash
+#
+# pput-gui - pput wrapper for file-manager right-click actions
+#
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; version 2 of the License.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# Usage: pput-gui FILE [FILE...]
+#
+# Runs pput on the selection and reports the result as a desktop
+# notification, since a file-manager click has no terminal to print to.
+
+set -uo pipefail
+
+notify() {  # notify(urgency, title, body)
+    notify-send -a pput -u "$1" "$2" "$3" 2>/dev/null \
+        || zenity --info --title="$2" --text="$3" 2>/dev/null \
+        || true
+}
+
+[ $# -gt 0 ] || { notify critical "pput" "No files selected."; exit 2; }
+
+# ponytail: pass(1) needs a gpg-agent with a usable pinentry. From a file
+# manager there is no controlling terminal, so point at the GUI pinentry.
+export GPG_TTY=""
+export PINENTRY_USER_DATA="${PINENTRY_USER_DATA:-gui}"
+
+out=$(pput "$@" 2>&1); rc=$?
+
+ok=$(printf '%s\n' "$out" | grep -c '^OK ')
+bad=$(printf '%s\n' "$out" | grep -cE '^(FAIL|TIMEOUT|skip) ')
+
+if [ "$rc" -eq 0 ]; then
+    notify normal "Paperless: $ok uploaded" "$out"
+else
+    notify critical "Paperless: $ok uploaded, $bad failed" "$out"
+fi
+exit $rc
diff --git a/pput.desktop b/pput.desktop
new file mode 100644
index 0000000..3f8aa60
--- /dev/null
+++ b/pput.desktop
@@ -0,0 +1,16 @@
+[Desktop Entry]
+Type=Action
+
+Name=Upload to Paperless
+Name[it]=Carica su Paperless
+ToolbarLabel=Upload to Paperless
+ToolbarLabel[it]=Carica su Paperless
+
+Icon=document-send
+Profiles=profile-zero;
+
+[X-Action-Profile profile-zero]
+MimeTypes=application/pdf;
+Exec=pput-gui %F
+Name=Default profile
+Name[it]=Profilo predefinito