From 3d7bbeb7fc9c4a3cde61c7f3ac46ddc85659e121 Mon Sep 17 00:00:00 2001
From: Joseph19820124 <164839249+Joseph19820124@users.noreply.github.com>
Date: Wed, 15 Apr 2026 23:59:07 +0800
Subject: [PATCH] docs: warn that agentsMd shadows PVC files at the same path

When agentsMd is set, the ConfigMap volumeMount takes precedence over
any existing file at the same path on the PVC (AGENTS.md, CLAUDE.md,
GEMINI.md, etc.). The PVC file is not deleted but becomes invisible to
the agent with no warning emitted.

- Add inline comment in values.yaml next to agentsMd explaining the
  shadowing behaviour (active block + both commented-out examples)
- Add a callout in the upgrade SOP (Section I, step 2) so operators
  are reminded to check agentsMd before upgrading

Fixes #360
---
 charts/openab/values.yaml  | 7 +++++--
 docs/openab-upgrade-sop.md | 6 ++++++
 2 files changed, 11 insertions(+), 2 deletions(-)

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