fix(helm): retain chart PVCs on uninstall

charts/openab/templates/NOTES.txt

@@ -46,5 +46,16 @@ Agents deployed:
 
     Restart after auth:
     kubectl rollout restart deployment/{{ include "openab.agentFullname" (dict "ctx" $ "agent" $name) }}
+{{- if not (eq (include "openab.persistenceEnabled" $cfg) "false") }}
+
+    Persistence:
+{{- if and $cfg.persistence $cfg.persistence.existingClaim }}
+    using existing PVC {{ $cfg.persistence.existingClaim }} (not managed by this chart)
+{{- else }}
+    PVC {{ include "openab.agentFullname" (dict "ctx" $ "agent" $name) }} is kept on helm uninstall.
+    To delete stored auth/session data, delete the PVC manually:
+    kubectl delete pvc {{ include "openab.agentFullname" (dict "ctx" $ "agent" $name) }}
+{{- end }}
+{{- end }}
 {{- end }}
 {{- end }}

charts/openab/templates/deployment.yaml

@@ -137,7 +137,7 @@ spec:
         {{- if $pvcEnabled }}
         - name: data
           persistentVolumeClaim:
-            claimName: {{ include "openab.agentFullname" $d }}
+            claimName: {{ (and $cfg.persistence $cfg.persistence.existingClaim) | default (include "openab.agentFullname" $d) }}
         {{- end }}
         - name: tmp
           emptyDir: {}

charts/openab/templates/pvc.yaml

@@ -1,6 +1,6 @@
 {{- range $name, $cfg := .Values.agents }}
 {{- if ne (include "openab.agentEnabled" $cfg) "false" }}
-{{- if not (eq (include "openab.persistenceEnabled" $cfg) "false") }}
+{{- if and (not (eq (include "openab.persistenceEnabled" $cfg) "false")) (not (and $cfg.persistence $cfg.persistence.existingClaim)) }}
 {{- $d := dict "ctx" $ "agent" $name "cfg" $cfg }}
 ---
 apiVersion: v1
@@ -9,6 +9,8 @@ metadata:
   name: {{ include "openab.agentFullname" $d }}
   labels:
     {{- include "openab.labels" $d | nindent 4 }}
+  annotations:
+    "helm.sh/resource-policy": keep
 spec:
   accessModes:
     - ReadWriteOnce

charts/openab/tests/persistence_test.yaml

@@ -0,0 +1,51 @@
+suite: persistence PVC rendering
+templates:
+  - templates/pvc.yaml
+  - templates/deployment.yaml
+tests:
+  - it: keeps chart-created PVCs on helm uninstall
+    template: templates/pvc.yaml
+    asserts:
+      - equal:
+          path: metadata.annotations["helm.sh/resource-policy"]
+          value: keep
+
+  - it: mounts the chart-created PVC by default
+    template: templates/deployment.yaml
+    asserts:
+      - equal:
+          path: spec.template.spec.volumes[1].persistentVolumeClaim.claimName
+          value: RELEASE-NAME-openab-kiro
+
+  - it: skips PVC creation when existingClaim is set
+    template: templates/pvc.yaml
+    set:
+      agents.kiro.persistence.existingClaim: openab-existing-kiro
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: mounts existingClaim when set
+    template: templates/deployment.yaml
+    set:
+      agents.kiro.persistence.existingClaim: openab-existing-kiro
+    asserts:
+      - equal:
+          path: spec.template.spec.volumes[1].persistentVolumeClaim.claimName
+          value: openab-existing-kiro
+
+  - it: skips PVC when persistence is disabled
+    template: templates/pvc.yaml
+    set:
+      agents.kiro.persistence.enabled: false
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: skips data volume mount when persistence is disabled
+    template: templates/deployment.yaml
+    set:
+      agents.kiro.persistence.enabled: false
+    asserts:
+      - notExists:
+          path: spec.template.spec.volumes[1].persistentVolumeClaim

charts/openab/values.yaml

@@ -50,6 +50,7 @@ agents:
     #     removeAfterReply: false
     #   persistence:
     #     enabled: true
+    #     existingClaim: ""  # set to reuse an existing PVC (skips PVC creation)
     #     storageClass: ""
     #     size: 1Gi
     #   # ⚠️ When set, this ConfigMap mount shadows any file at the same path on the PVC.
@@ -82,6 +83,7 @@ agents:
     #     removeAfterReply: false
     #   persistence:
     #     enabled: true
+    #     existingClaim: ""  # set to reuse an existing PVC (skips PVC creation)
     #     storageClass: ""
     #     size: 1Gi
     #   agentsMd: ""
@@ -111,6 +113,7 @@ agents:
     #     removeAfterReply: false
     #   persistence:
     #     enabled: true
+    #     existingClaim: ""  # set to reuse an existing PVC (skips PVC creation)
     #     storageClass: ""
     #     size: 1Gi
     #   image: "ghcr.io/openabdev/openab-cursor:latest"
@@ -193,6 +196,7 @@ agents:
     cronjobs: []
     persistence:
       enabled: true
+      existingClaim: ""  # set to reuse an existing PVC (skips PVC creation)
       storageClass: ""
       size: 1Gi  # defaults to 1Gi if not set
     # ⚠️ When set, this ConfigMap mount shadows any file at the same path on the PVC.

docs/ai-install-upgrade.md

@@ -156,7 +156,7 @@ rollback openab per the upgrade SOP — the upgrade to v0.7.7 failed
   Step ①  Uninstall failed deployment
   ┌──────────┐
   │ helm     │──► release gone
-  │ uninstall│──► delete leftover PVC/secrets
+  │ uninstall│──► chart PVCs are retained
   └────┬─────┘
        ▼
   Step ②  Reinstall previous version
@@ -182,6 +182,10 @@ rollback openab per the upgrade SOP — the upgrade to v0.7.7 failed
   └──────────────────────────────────────────────
 ```
 
+> **PVC retention:** OpenAB chart-created PVCs are kept on `helm uninstall` to protect auth/session data. Delete a retained PVC manually only when you intentionally want to discard that state. `persistence.existingClaim` PVCs are owned outside the chart and are never created or deleted by OpenAB.
+>
+> **Upgrade path:** Existing installations will gain the `helm.sh/resource-policy: keep` annotation on their PVCs upon the next `helm upgrade`. This is an additive-only change — it does not alter runtime behavior and only takes effect on a subsequent `helm uninstall`.
+
 ---
 
 ## Quick Reference