From 598ed4657153cb5e32ab7aae6739f89b3ae07f2c Mon Sep 17 00:00:00 2001
From: Joseph19820124 <164839249+Joseph19820124@users.noreply.github.com>
Date: Tue, 14 Apr 2026 22:42:49 +0000
Subject: [PATCH 1/2] docs: add gemini first-run workaround

---
 docs/gemini.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/gemini.md b/docs/gemini.md
index 797cba99..d4e64d32 100644
--- a/docs/gemini.md
+++ b/docs/gemini.md
@@ -25,6 +25,20 @@ helm install openab openab/openab \
 
 > Set `agents.kiro.enabled=false` to disable the default Kiro agent.
 
+## First-Run Workaround
+
+Gemini CLI needs `~/.gemini/projects.json` to exist before the first ACP session starts. In ephemeral containers, the file may not be created yet, which can surface as `ENOENT` or `Unexpected end of JSON input` during the first run.
+
+If you control the container startup command, seed the directory before launching `openab`:
+
+```bash
+mkdir -p /home/node/.gemini && echo '{}' > /home/node/.gemini/projects.json && exec openab /etc/openab/config.toml
+```
+
+For Kubernetes or Helm deployments, use the same idea with an init container and a shared volume mounted at `/home/node/.gemini`.
+
+The current chart does not expose `extraInitContainers`, `extraVolumes`, or `extraVolumeMounts`, so the workaround is easiest to apply in a custom manifest or wrapper image until those values are added.
+
 ## Manual config.toml
 
 ```toml

From b44d02740f1ed5fc4acedbfc477733caa23e94d3 Mon Sep 17 00:00:00 2001
From: Joseph19820124 <164839249+Joseph19820124@users.noreply.github.com>
Date: Tue, 14 Apr 2026 22:58:48 +0000
Subject: [PATCH 2/2] docs: expand gemini workaround guidance

---
 docs/gemini.md | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/docs/gemini.md b/docs/gemini.md
index d4e64d32..e22d5029 100644
--- a/docs/gemini.md
+++ b/docs/gemini.md
@@ -29,15 +29,29 @@ helm install openab openab/openab \
 
 Gemini CLI needs `~/.gemini/projects.json` to exist before the first ACP session starts. In ephemeral containers, the file may not be created yet, which can surface as `ENOENT` or `Unexpected end of JSON input` during the first run.
 
+This is a workaround for the upstream Gemini CLI issue `google-gemini/gemini-cli#22583`.
+
 If you control the container startup command, seed the directory before launching `openab`:
 
 ```bash
 mkdir -p /home/node/.gemini && echo '{}' > /home/node/.gemini/projects.json && exec openab /etc/openab/config.toml
 ```
 
-For Kubernetes or Helm deployments, use the same idea with an init container and a shared volume mounted at `/home/node/.gemini`.
+The `exec openab /etc/openab/config.toml` part assumes the Docker image default config path.
+
+For Kubernetes or Helm deployments, use the same idea with an init container and a shared volume mounted at `/home/node/.gemini`. A minimal pattern looks like this:
+
+```yaml
+extraInitContainers:
+  - name: seed-gemini-home
+    image: busybox:1.36
+    command: ["sh", "-c", "mkdir -p /home/node/.gemini && echo '{}' > /home/node/.gemini/projects.json"]
+    volumeMounts:
+      - name: gemini-home
+        mountPath: /home/node/.gemini
+```
 
-The current chart does not expose `extraInitContainers`, `extraVolumes`, or `extraVolumeMounts`, so the workaround is easiest to apply in a custom manifest or wrapper image until those values are added.
+The current chart does not expose `extraInitContainers`, `extraVolumes`, or `extraVolumeMounts`, so the workaround is easiest to apply in a custom manifest or wrapper image until those values are added. Chart support for those passthrough fields is tracked in #344.
 
 ## Manual config.toml