docs(documents): source instance in the workflow recipe and the key rules; token and removal rules for the picker

docs/integrations/document-import.md

@@ -43,12 +43,13 @@ This needs Paperless-ngx 3.0 or later, the first release with the
   - **Use parameters for webhook body:** on. **Send webhook payload as
     JSON:** off. **Webhook params:**
 
-    | Name           | Value                                                |
-    | -------------- | ---------------------------------------------------- |
-    | `title`        | `{{doc_title}}`                                      |
-    | `documentDate` | `{{created_year}}-{{created_month}}-{{created_day}}` |
-    | `sourceSystem` | `PAPERLESS`                                          |
-    | `sourceId`     | `{{doc_id}}`                                         |
+    | Name             | Value                                                    |
+    | ---------------- | -------------------------------------------------------- |
+    | `title`          | `{{doc_title}}`                                          |
+    | `documentDate`   | `{{created_year}}-{{created_month}}-{{created_day}}`     |
+    | `sourceSystem`   | `PAPERLESS`                                              |
+    | `sourceId`       | `{{doc_id}}`                                             |
+    | `sourceInstance` | `https://paperless.example.com` (your Paperless address) |
 
   - **Include document:** on. Paperless then sends the original file along
     with the parameters, which is exactly what HealthLog expects.
@@ -231,6 +232,15 @@ per account: if you push documents from two other systems, make sure their
 ids cannot collide, for example by prefixing them (`nextcloud-123`,
 `scanner-123`).
 
+Since v1.39.3 a key can also name its instance: `sourceInstance`, the
+address of the Paperless-ngx or Papra it came from (only its origin,
+`scheme://host[:port]`, counts). With it, document 123 on one Paperless and
+document 123 on another are two documents. The import script sends it
+automatically; add it to a Paperless workflow as shown above. A key sent or
+stored without an instance (everything imported with v1.39.2, or a workflow
+without the parameter) matches that id on any instance of its system, so
+nothing imported earlier is stored twice or brought back after a deletion.
+
 The same file sent under a different id is stored once, and HealthLog
 remembers the extra id for it, up to 20 extra ids per document. A 21st is
 refused with `409` (`documents.inbound.sourceAliasLimit`) and nothing is

docs/self-hosting/document-sources.md

@@ -51,7 +51,9 @@ Settings → Integrations → Document archives:
 - **Papra:** the base address, the organization id (from the Papra address
   bar) and an API key with `documents:read` and `tags:read`.
 
-HealthLog tests the connection before saving it. The token is stored
+HealthLog tests the connection before saving it. A saved token is only ever
+sent to the address it was saved for: changing the address to another origin
+asks for the token again. The token is stored
 encrypted (AES-256-GCM, rotated with the other keys by
 `scripts/rotate-encryption-key.ts`) and is never shown again, not even in
 part.
@@ -70,7 +72,10 @@ limit for a document).
 - Imports count against the person's normal upload allowance (60 an hour) and
   storage quota.
 - A document that is already in HealthLog is not stored twice, and one the
-  person deleted in HealthLog is not brought back by picking it again. These
+  person deleted in HealthLog is not brought back by picking it again. Each
+  import is keyed by system, instance (the archive's origin) and document id,
+  so the same id on two Paperless-ngx instances is two documents; a key
+  imported before v1.39.3 carries no instance and matches any instance. These
   are the same rules the document token and `scripts/import-documents.mjs`
   follow.
 - A picked document follows the person's own automatic AI reading setting.
@@ -80,3 +85,6 @@ limit for a document).
   each person reconnects (one form); the imported documents themselves are in
   the backup with the rest of the vault.
 - Delete all data and account deletion remove the connection and its token.
+- A stored connection stays visible under Settings, read-only, when this
+  variable is unset or the person switched Documents off, so it can still be
+  removed.