feat: upload documents to paperless-ngx from the CLI

Single bash script over the paperless REST API. Posts each file to
/api/documents/post_document/, then polls /api/tasks/ until the document
is consumed, so each file gets a real outcome instead of a task id.

The task response needed care: it is a paginated object rather than a
bare list, statuses are lowercase, and the outcome lives in result_data
as a dict, carrying duplicate_of when paperless rejects re-uploaded
content. test_status.sh covers those shapes.

Token is read from pass, never passed as an argument. Host, pass entry
and timeout are environment-overridable.

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

1 files changed, 94 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5ada7b2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,94 @@
+# pput
+
+Upload documents to a [paperless-ngx](https://docs.paperless-ngx.com) instance
+from the command line.
+
+A single bash script over the paperless REST API. It posts each file, then
+polls the task queue until the document is consumed, so you get a real result
+per file instead of a fire-and-forget task id.
+
+## Usage
+
+```
+pput FILE [FILE...]
+```
+
+```console
+$ pput fattura.pdf
+OK   fattura.pdf -> doc 48
+
+$ pput *.pdf
+OK   bolletta.pdf -> doc 49
+FAIL vecchia.pdf: duplicate of doc 12
+```
+
+Exit status is 0 when every file was consumed, 1 if any failed, timed out, or
+was unreadable. That makes it safe to chain:
+
+```bash
+pput scan.pdf && rm scan.pdf
+```
+
+Paperless rejects re-uploads of identical content, reported as
+`duplicate of doc N`.
+
+## Requirements
+
+- `bash`, `curl`, `python3` (stdlib only)
+- [`pass`](https://www.passwordstore.org/) holding a paperless API token
+
+## Configuration
+
+The API token is read from `pass`, never passed on the command line. Create an
+entry with a token from the paperless web UI, under Settings, My Profile,
+API Token:
+
+```bash
+pass insert proxmox/paperless/api
+```
+
+Everything else is environment, with defaults baked in for the author's setup:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `PAPERLESS_URL` | `http://paperless.lan:8000` | base URL of the instance |
+| `PAPERLESS_PASS_ENTRY` | `proxmox/paperless/api` | `pass` entry with the API token |
+| `PAPERLESS_TIMEOUT` | `120` | seconds to wait per document |
+
+```bash
+PAPERLESS_URL=https://paperless.example.org pput scan.pdf
+```
+
+Raise `PAPERLESS_TIMEOUT` if OCR of large scans outruns the default; the upload
+still succeeds server-side, only the wait gives up.
+
+Note the API token is sent as a header, so an `http://` instance transmits it
+in cleartext. Use it on a trusted network, or put the instance behind TLS.
+
+## Install
+
+```bash
+git clone <repo> ~/Programming/GIT/pput
+ln -s ~/Programming/GIT/pput/pput ~/bin/pput
+```
+
+## Tests
+
+```bash
+./test_status.sh
+```
+
+Checks the task-response parser against the shapes the paperless API returns:
+pending, success, duplicate, and other failures.
+
+## License
+
+GPLv2. See `LICENSE`.
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.