diff --git a/charts/openab/values.yaml b/charts/openab/values.yaml
index f8956715..23359c5b 100644
--- a/charts/openab/values.yaml
+++ b/charts/openab/values.yaml
@@ -47,6 +47,8 @@ agents:
     #     enabled: true
     #     storageClass: ""
     #     size: 1Gi
+    #   # ⚠️ When set, this ConfigMap mount shadows any file at the same path on the PVC.
+    #   # The PVC file is NOT deleted but becomes invisible to the agent. Remove agentsMd to restore.
     #   agentsMd: ""
     #   resources: {}
     #   nodeSelector: {}
@@ -77,6 +79,8 @@ agents:
     #     enabled: true
     #     storageClass: ""
     #     size: 1Gi
+    #   # ⚠️ When set, this ConfigMap mount shadows any file at the same path on the PVC.
+    #   # The PVC file is NOT deleted but becomes invisible to the agent. Remove agentsMd to restore.
     #   agentsMd: ""
     #   resources: {}
     #   image: "ghcr.io/openabdev/openab-opencode:latest"
@@ -115,6 +119,8 @@ agents:
       enabled: true
       storageClass: ""
       size: 1Gi  # defaults to 1Gi if not set
+    # ⚠️ When set, this ConfigMap mount shadows any file at the same path on the PVC.
+    # The PVC file is NOT deleted but becomes invisible to the agent. Remove agentsMd to restore.
     agentsMd: ""
     resources: {}
     nodeSelector: {}
diff --git a/docs/openab-upgrade-sop.md b/docs/openab-upgrade-sop.md
index e9ea81b7..ae9949ac 100644
--- a/docs/openab-upgrade-sop.md
+++ b/docs/openab-upgrade-sop.md
@@ -48,6 +48,8 @@
 
 > ⚠️ **Data loss warning:** `helm uninstall` **deletes the PVC** and all persistent data (steering files, auth database, agent config) unless the chart has an explicit resource policy annotation. Always use `helm rollback` instead of uninstall + reinstall. If you need to uninstall, back up the PVC data first.
 
+> ⚠️ **`agentsMd` shadows PVC files:** When `agentsMd` is set in Helm values, the resulting ConfigMap volumeMount shadows 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` from your values to restore PVC files. See [#360](https://github.com/openabdev/openab/issues/360).
+
 ---
 
 ## Upgrade Process Overview