docs: record safe legacy migration data contract

.gitea/workflows/managed-validation.yml

@@ -55,33 +55,6 @@ jobs:
             exit 1
           fi
 
-          # MANAGED_FAST_PATH: documentation and this baseline workflow cannot
-          # affect the shipped runtime. Keep the required status check, but do
-          # not install toolchains or execute the full product suite.
-          if [[ -n "${GITHUB_BASE_REF:-}" ]]; then
-            git fetch --no-tags --depth=1 origin "${GITHUB_BASE_REF}"
-            managed_base="origin/${GITHUB_BASE_REF}"
-            git diff --check "${managed_base}..HEAD"
-            mapfile -t managed_changed_files < <(
-              git diff --name-only --diff-filter=ACMR "${managed_base}..HEAD"
-            )
-            managed_runtime_change=0
-            for managed_path in "${managed_changed_files[@]}"; do
-              case "${managed_path}" in
-                *.md|*.mdx|docs/*|.github/ISSUE_TEMPLATE/*|.gitea/ISSUE_TEMPLATE/*|.gitea/runner-scope.sh|.gitea/workflows/managed-validation.yml)
-                  ;;
-                *)
-                  managed_runtime_change=1
-                  break
-                  ;;
-              esac
-            done
-            if [[ "${#managed_changed_files[@]}" -gt 0 && "${managed_runtime_change}" -eq 0 ]]; then
-              printf 'Managed validation fast path: %s non-runtime file(s); full product suite skipped.\n' \
-                "${#managed_changed_files[@]}"
-              exit 0
-            fi
-          fi
           if [[ -f pyproject.toml || -f requirements.txt ]]; then
             # Compile only tracked Python sources. Running compileall after a
             # Node install would otherwise traverse node_modules and turn a

docker-compose.migration.yml

@@ -0,0 +1,34 @@
+# Append after docker-compose.unraid.yml. Operator-only migration prerequisite;
+# every path must be a verified cold clone, never the original live data.
+# Also pass MIGRATION_ENV_FILE as Compose --env-file for interpolation parity.
+name: vacatureradar-managed
+services:
+  app:
+    labels:
+      io.itworx.migration-attempt: ${MIGRATION_ATTEMPT:?journaled migration attempt required}
+    image: ${MIGRATION_IMAGE:?set an attempt-specific candidate image}
+    env_file:
+      - ${VACATURERADAR_ENV_FILE:?set the protected external runtime env file}
+    build:
+      labels:
+        org.opencontainers.image.source: jens/vacatureradar
+        org.opencontainers.image.revision: ${MIGRATION_SOURCE_REVISION:?full verified Git commit required}
+        org.opencontainers.image.source-tree: ${MIGRATION_SOURCE_TREE:?verified Git tree required}
+        org.opencontainers.image.version: ${MIGRATION_BUILD_ID:?broker build ID required}
+        org.opencontainers.image.created: ${MIGRATION_BUILD_DATE:?broker UTC build date required}
+    volumes:
+      - type: bind
+        source: ${MIGRATION_LOCAL_ROOT:?verified cold clone of the complete local tree required}/media
+        target: /app/media
+        bind:
+          create_host_path: false
+      - type: bind
+        source: ${MIGRATION_LOCAL_ROOT:?verified cold clone of the complete local tree required}/logs
+        target: /app/logs
+        bind:
+          create_host_path: false
+      - type: bind
+        source: ${MIGRATION_LOCAL_ROOT:?verified cold clone of the complete local tree required}
+        target: /app/local
+        bind:
+          create_host_path: false

docs/LEGACY_DEPLOYMENT_MIGRATION.md

@@ -0,0 +1,19 @@
+# Gecontroleerde migratie van legacy deployments
+
+`docker-compose.migration.yml` is een optionele operatoroverride, geen wijziging
+aan de standaarddeployment. Gebruik deze alleen na de expliciete migratieprocedure
+in ProjectBrain `scripts/legacy-deployment-migration/`.
+
+De operator valideert de exacte Git-revisie en imageprovenance, stopt de oude
+container en maakt een gecontroleerde koude kopie van de volledige `local`-map.
+`MIGRATION_LOCAL_ROOT` verwijst uitsluitend naar die kopie. Media, logs en de
+PostgreSQL-data houden hun geneste mountrelatie. De originele data, image en
+container blijven bewaard voor rollback; startupmigraties mogen ze niet wijzigen.
+
+Alle migratievariabelen zijn verplicht, paden worden niet automatisch aangemaakt,
+en een attemptlabel bindt de nieuwe container aan precies één hersteltransactie.
+De operator controleert gemergde Compose-mounts, gezondheid, HTTP en de echte
+brokerreceipt voordat de configuratie definitief wordt overgezet.
+
+De override is offline getest met echte Compose-rendering en ontbrekende
+invoervariabelen. Toevoeging van dit bestand bewijst geen uitgevoerde productiemigratie.