diff --git a/charts/openab/values.yaml b/charts/openab/values.yaml
index f8956715..b553323b 100644
--- a/charts/openab/values.yaml
+++ b/charts/openab/values.yaml
@@ -47,7 +47,7 @@ agents:
     #     enabled: true
     #     storageClass: ""
     #     size: 1Gi
-    #   agentsMd: ""
+    #   agentsMd: ""  # when set, shadows any existing file at the same path on the PVC
     #   resources: {}
     #   nodeSelector: {}
     #   tolerations: []
@@ -77,7 +77,7 @@ agents:
     #     enabled: true
     #     storageClass: ""
     #     size: 1Gi
-    #   agentsMd: ""
+    #   agentsMd: ""  # when set, shadows any existing file at the same path on the PVC
     #   resources: {}
     #   image: "ghcr.io/openabdev/openab-opencode:latest"
     image: ""
@@ -115,6 +115,9 @@ agents:
       enabled: true
       storageClass: ""
       size: 1Gi  # defaults to 1Gi if not set
+    # agentsMd: when set, the ConfigMap volumeMount takes precedence over any existing file
+    # at the same path on the PVC (e.g. AGENTS.md, CLAUDE.md, GEMINI.md). The PVC file is
+    # not deleted but becomes invisible to the agent. Remove agentsMd to restore PVC files.
     agentsMd: ""
     resources: {}
     nodeSelector: {}
diff --git a/docs/openab-upgrade-sop.md b/docs/openab-upgrade-sop.md
index e9ea81b7..7891ff80 100644
--- a/docs/openab-upgrade-sop.md
+++ b/docs/openab-upgrade-sop.md
@@ -264,6 +264,12 @@ Pay special attention to:
 - Added or deprecated environment variables
 - Any migration steps
 
+> ⚠️ **`agentsMd` takes precedence over PVC files:** If you have `agentsMd` set in your Helm
+> values, the ConfigMap volumeMount will shadow any existing file at the same path on the PVC
+> (e.g. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`). The PVC file is not deleted but becomes
+> invisible to the agent. If you rely on PVC-managed agent instruction files, either leave
+> `agentsMd` empty or migrate its content to the PVC file before upgrading.
+
 ### 3. Check Node Resources
 
 ```bash