From 8c804c31aabd897fe77723c92e91bf6994ca98b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Oct=C3=A1vio=20Pereira?=
 <joaopereira@criticalmanufacturing.com>
Date: Fri, 7 Aug 2026 09:30:20 +0000
Subject: [PATCH] docs: enhance documentation for Pack and Transform actions in
 cmfpackage.json

---
 .../config-files/cmfpackage.json/index.md     | 25 +++++++++++++++++++
 .../cmfpackage.json/packaction.md             | 12 +++++++--
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/docs/src/03-explore/config-files/cmfpackage.json/index.md b/docs/src/03-explore/config-files/cmfpackage.json/index.md
index 0a1f7f2ee..fd936c3d0 100644
--- a/docs/src/03-explore/config-files/cmfpackage.json/index.md
+++ b/docs/src/03-explore/config-files/cmfpackage.json/index.md
@@ -91,6 +91,31 @@ Properties:
 
 The properties **source** and **target** have support for token replacement of any property of the cmfpackage.
 
+Use `Pack` for regular file inclusion. Use `Transform` when you need to add custom properties to the UI `config.json` during packing, without replacing the out-of-the-box file. In this case, the `source` is the transform file, such as `my-transforms.json`, and the `target` value is ignored by the packer. At the moment, this action is only supported for `config.json`.
+
+Example: add custom properties to the ui `config.json`.
+
+```json
+{
+    "contentToPack": [
+        {
+            "source": "my-transforms.json",
+            "action": "Transform"
+        }
+    ]
+}
+```
+
+If `my-transforms.json` contains:
+
+```json
+{
+    "advancedCustomization": true
+}
+```
+
+the generated package will apply that transformation to the ui `config.json`, preserving the existing product-managed settings and variables.
+
 Example:
 
 ```json
diff --git a/docs/src/03-explore/config-files/cmfpackage.json/packaction.md b/docs/src/03-explore/config-files/cmfpackage.json/packaction.md
index c2ab13769..148cada51 100644
--- a/docs/src/03-explore/config-files/cmfpackage.json/packaction.md
+++ b/docs/src/03-explore/config-files/cmfpackage.json/packaction.md
@@ -3,9 +3,17 @@
 * Pack *(default)*
 * Transform
 
-    ```
     Use the source content to apply a transformation to another file.
-    This currently doesn't use the Target property, as it is handler dependent.
+    This is typically used to inject custom properties into a packed JSON file, such as the UI `config.json`, without overwriting the out-of-the-box file.
+    This currently doesn't use the `Target` property, as it is handler dependent.
+
+    Example:
+
+    ```json
+    {
+      "source": "my-transforms.json",
+      "action": "Transform"
+    }
     ```
 
 * Untar