diff --git a/docs/gemini.md b/docs/gemini.md
index 797cba99..b335bd11 100644
--- a/docs/gemini.md
+++ b/docs/gemini.md
@@ -25,6 +25,26 @@ 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`, `Unexpected end of JSON input`, or a `ProjectRegistry` startup failure during the first run.
+
+This is a workaround for the upstream Gemini CLI issue: [google-gemini/gemini-cli#25509](https://github.com/google-gemini/gemini-cli/issues/25509).
+
+If you control the Gemini container startup command, seed the directory before launching `openab`:
+
+```json
+{"projects":{}}
+```
+
+```bash
+mkdir -p /home/node/.gemini && printf '{"projects":{}}\n' > /home/node/.gemini/projects.json && exec openab /etc/openab/config.toml
+```
+
+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`, or wait for the Gemini CLI fix upstream.
+
 ## Manual config.toml
 
 ```toml