docs(n8n): version school intake workflow artifacts

docs/operations/SCHOOL_PAPERLESS_INTAKE.md

@@ -1,13 +1,22 @@
 # School Paperless Intake Workflow
 
-Workflows:
+Current workflow versions:
-- `n8n-workflows/18-school-paperless-intake.json`
+- `n8n-workflows/18-school-paperless-intake-v1.0.json`
-- `n8n-workflows/19-paperless-school-metadata-enrichment.json`
+- `n8n-workflows/19-paperless-school-metadata-enrichment-v1.0.json`
 
-This workflow is meant for a Telegram chat-driven upload pipeline that sends schoolwork into Paperless-NGX while recording intake metadata in shared Postgres.
+This workflow set is meant for a Telegram chat-driven upload pipeline that sends schoolwork into Paperless-NGX while recording intake metadata in shared Postgres.
+
+## Versioning rule
+
+When these workflow artifacts change, the version must change too:
+- the filename keeps a `-vX.Y` suffix
+- the internal n8n workflow `name` also carries the same version
+- docs and testing notes should reference the current version explicitly
 
 ## What it does
 
+### Workflow 18 — v1.0
+
 1. Accepts a multipart upload at `POST /webhook/school/intake/upload`
 2. Requires form fields:
    - `class_name`
@@ -46,6 +55,10 @@ PAPERLESS_DOCUMENT_TYPE_SCHOOL=
 PAPERLESS_TAG_SCHOOL=
 PAPERLESS_TAG_ASSIGNMENTS=
 PAPERLESS_TAG_TELEGRAM=
+PAPERLESS_TAG_CLASS_MAP_JSON={}
+PAPERLESS_TAG_SUBMISSION_KIND_MAP_JSON={}
+PAPERLESS_DOCUMENT_TYPE_PAPER_KIND_MAP_JSON={}
+PAPERLESS_CORRESPONDENT_CLASS_MAP_JSON={}
 NODE_FUNCTION_ALLOW_BUILTIN=crypto
 ```
 
@@ -59,12 +72,17 @@ Add to the `n8n` service `environment:` block in `automation/docker-compose.yaml
       PAPERLESS_TAG_SCHOOL: ${PAPERLESS_TAG_SCHOOL}
       PAPERLESS_TAG_ASSIGNMENTS: ${PAPERLESS_TAG_ASSIGNMENTS}
       PAPERLESS_TAG_TELEGRAM: ${PAPERLESS_TAG_TELEGRAM}
+      PAPERLESS_TAG_CLASS_MAP_JSON: ${PAPERLESS_TAG_CLASS_MAP_JSON}
+      PAPERLESS_TAG_SUBMISSION_KIND_MAP_JSON: ${PAPERLESS_TAG_SUBMISSION_KIND_MAP_JSON}
+      PAPERLESS_DOCUMENT_TYPE_PAPER_KIND_MAP_JSON: ${PAPERLESS_DOCUMENT_TYPE_PAPER_KIND_MAP_JSON}
+      PAPERLESS_CORRESPONDENT_CLASS_MAP_JSON: ${PAPERLESS_CORRESPONDENT_CLASS_MAP_JSON}
       NODE_FUNCTION_ALLOW_BUILTIN: crypto
 ```
 
 Notes:
 - `PAPERLESS_CORRESPONDENT_SCHOOL` and `PAPERLESS_DOCUMENT_TYPE_SCHOOL` should be numeric IDs if you want those fields auto-assigned.
-- Leave optional Paperless IDs blank if you prefer Paperless rules to classify later.
+- `PAPERLESS_TAG_CLASS_MAP_JSON`, `PAPERLESS_TAG_SUBMISSION_KIND_MAP_JSON`, `PAPERLESS_DOCUMENT_TYPE_PAPER_KIND_MAP_JSON`, and `PAPERLESS_CORRESPONDENT_CLASS_MAP_JSON` are optional JSON maps used by workflow 19.
+- Leave optional Paperless IDs and JSON maps blank/default if you prefer to start with deterministic title + generic tags only.
 - `NODE_FUNCTION_ALLOW_BUILTIN=crypto` is required because the Code node hashes the uploaded file.
 - `N8N_BLOCK_ENV_ACCESS_IN_NODE` must remain `false`.
 
@@ -80,6 +98,8 @@ Workflow 18 deliberately keeps the Paperless upload minimal and safe:
 
 The deterministic filename/title preserve the `intake_id` for later correlation.
 
+### Workflow 19 — v1.0
+
 Workflow 19 handles the follow-up metadata pass after Paperless finishes processing:
 - fetch Paperless document by webhook document id
 - resolve `intake_id` from the stored filename

n8n-workflows/18-school-paperless-intake-v1.0.json

@@ -1,5 +1,5 @@
 {
-  "name": "Telegram School Intake → Postgres → Paperless",
+  "name": "Telegram School Intake → Postgres → Paperless v1.0",
   "active": false,
   "isArchived": false,
   "nodes": [
@@ -217,7 +217,8 @@
   },
   "staticData": null,
   "meta": {
-    "templateCredsSetupCompleted": false
+    "templateCredsSetupCompleted": false,
+    "artifactVersion": "v1.0"
   },
   "pinData": {},
   "tags": [

n8n-workflows/19-paperless-school-metadata-enrichment-v1.0.json

@@ -1,5 +1,5 @@
 {
-  "name": "Paperless School Intake Metadata Enrichment",
+  "name": "Paperless School Intake Metadata Enrichment v1.0",
   "active": false,
   "isArchived": false,
   "nodes": [
@@ -274,7 +274,8 @@
   },
   "staticData": null,
   "meta": {
-    "templateCredsSetupCompleted": false
+    "templateCredsSetupCompleted": false,
+    "artifactVersion": "v1.0"
   },
   "pinData": {},
   "tags": [

n8n-workflows/README.md

@@ -15,8 +15,8 @@
 | 14 | Paperless Inbox Reminder | Scheduled (Monday 9 AM) | Queries Paperless for untagged documents; sends Gotify reminder with oldest items listed, or a ✅ clear if inbox is empty |
 | 15 | n8n Self-Health Monitor | Scheduled (every 15 min) | Checks n8n execution history for failures in the past hour; deduplicates via Postgres; pushes Gotify alert with workflow name and error summary |
 | 16 | NFS Mount Watchdog | Scheduled (every 5 min) | Probes NFS mount points on PD; if missing: runs mount script, re-probes, restarts affected containers (Plex, Audiobookshelf, Immich); notifies via Gotify on heal or escalation |
-| 18 | Telegram School Intake → Postgres → Paperless | `POST /webhook/school/intake/upload` | Accepts multipart schoolwork uploads plus class/assignment metadata, writes an intake record to shared Postgres, then uploads into Paperless with deterministic `intake_id` in the filename/title |
+| 18 | Telegram School Intake → Postgres → Paperless v1.0 | `POST /webhook/school/intake/upload` | Accepts multipart schoolwork uploads plus class/assignment metadata, writes an intake record to shared Postgres, then uploads into Paperless with deterministic `intake_id` in the filename/title |
-| 19 | Paperless School Intake Metadata Enrichment | `POST /webhook/school/intake/paperless-enrich` | Handles Paperless post-consumption webhooks, looks up the intake record by deterministic filename, then applies deterministic title/tags and optional document-type/correspondent mapping |
+| 19 | Paperless School Intake Metadata Enrichment v1.0 | `POST /webhook/school/intake/paperless-enrich` | Handles Paperless post-consumption webhooks, looks up the intake record by deterministic filename, then applies deterministic title/tags and optional document-type/correspondent mapping |
 
 ## How to Import
 
@@ -289,9 +289,9 @@ curl -X POST https://n8n.paccoco.com/webhook/git/push \
   }'
 ```
 
-## Workflow 18 — Telegram School Intake → Postgres → Paperless
+## Workflow 18 — Telegram School Intake → Postgres → Paperless v1.0
 
-Import `18-school-paperless-intake.json` for a chat-driven schoolwork intake flow. Supporting notes live at `docs/operations/SCHOOL_PAPERLESS_INTAKE.md` and the tracked schema lives at `docs/reference/SCHOOL_INTAKE_POSTGRES_SCHEMA.sql`.
+Import `18-school-paperless-intake-v1.0.json` for a chat-driven schoolwork intake flow. Supporting notes live at `docs/operations/SCHOOL_PAPERLESS_INTAKE.md` and the tracked schema lives at `docs/reference/SCHOOL_INTAKE_POSTGRES_SCHEMA.sql`.
 
 Highlights:
 - multipart upload endpoint: `POST /webhook/school/intake/upload`
@@ -303,6 +303,16 @@ Highlights:
 Testing fixture:
 - `fixtures/school-paperless-intake-webhook.curl.example.txt`
 
+## Workflow Versioning Convention
+
+For n8n workflow artifacts in this repo:
+- include the version in the **filename** (example: `18-school-paperless-intake-v1.0.json`)
+- include the version in the workflow's internal **`name`** field
+- bump the version whenever behavior, schema expectations, webhook payload handling, or env requirements change
+- update `n8n-workflows/README.md` and `n8n-workflows/TESTING-STATUS.md` when introducing a new workflow version
+
+Do not overwrite a workflow artifact with silent behavior changes and no version bump. That way lies confusion and sweaty guesswork. Ha ha.
+
 ## Customizing RSS Feeds (Workflow 06)
 
 Edit the "Define RSS Feeds" Code node to add/remove feeds. Default feeds: