Immutable Extracts

README.md

@@ -304,6 +304,36 @@ setting remains as a module-only compatibility alias when `consume_archives` is
 not set. Stale cleanup is scoped to roots actually touched by extracted
 resources, so the default module-only extraction does not prune assets.
 
+GFF JSON extraction can merge selected fields and lists from the existing source
+file instead of replacing the whole extracted document. Rules are matched by
+`target` relative to `paths.source`; files without a matching rule keep the
+default overwrite behavior. For example:
+
+```yaml
+extract:
+  merge:
+    gff_json:
+      - target: module/module.ifo.json
+        preserve_fields:
+          - Mod_Entry_Area
+          - Mod_Entry_X
+          - Mod_Entry_Y
+          - Mod_Entry_Z
+          - Mod_Entry_Dir_X
+          - Mod_Entry_Dir_Y
+        merge_lists:
+          - field: Mod_Area_list
+            key_field: Area_Name
+            strategy: preserve_existing_order_append_new
+```
+
+`preserve_fields` copies matching root fields from the existing source document
+into the extracted document before writing. The
+`preserve_existing_order_append_new` list strategy keeps existing keyed list
+order for entries still present in the extracted archive, uses extracted entries
+as the value source, appends archive-only entries in archive order, and removes
+existing entries that are no longer present in the archive.
+
 Music defaults (used when not explicitly configured):
 
 ```yaml