From 0320b713151982eb7a11653675d584e339baabae Mon Sep 17 00:00:00 2001
From: "molecule-ai[bot]" <276602405+molecule-ai[bot]@users.noreply.github.com>
Date: Thu, 16 Apr 2026 20:22:26 +0000
Subject: [PATCH] docs(devrel): gemini-cli runtime tutorial for PR #379

---
 docs/tutorials/gemini-cli-runtime.md | 66 ++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 docs/tutorials/gemini-cli-runtime.md

diff --git a/docs/tutorials/gemini-cli-runtime.md b/docs/tutorials/gemini-cli-runtime.md
new file mode 100644
index 00000000..d2802635
--- /dev/null
+++ b/docs/tutorials/gemini-cli-runtime.md
@@ -0,0 +1,66 @@
+# Running a Gemini CLI Workspace on Molecule AI
+
+Molecule AI now ships a `gemini-cli` runtime adapter alongside the existing `claude-code` adapter. This tutorial walks you from zero to a running Gemini agent workspace in under five minutes.
+
+## What you'll need
+
+- A Molecule AI account with at least one provisioned tenant
+- A Google `GEMINI_API_KEY` (get one at [aistudio.google.com](https://aistudio.google.com))
+- The Molecule AI CLI (`pip install molecule-ai`)
+
+## Setup (10 steps)
+
+```bash
+# 1. Install / upgrade the CLI
+pip install --upgrade molecule-ai
+
+# 2. Authenticate
+molecule auth login
+
+# 3. Store your Gemini API key as a global secret
+molecule secrets set GEMINI_API_KEY="YOUR_KEY_HERE" --global
+
+# 4. Create a gemini-cli workspace
+molecule workspace create my-gemini-agent --runtime gemini-cli
+
+# 5. Confirm it's running (status → "ready" within ~30 s)
+molecule workspace status my-gemini-agent
+
+# 6. Send your first task
+molecule workspace run my-gemini-agent "Summarise the last 5 git commits in this repo"
+
+# 7. View the streamed response
+molecule workspace logs my-gemini-agent --follow
+
+# 8. Check the agent's memory file (GEMINI.md)
+molecule workspace exec my-gemini-agent cat GEMINI.md
+
+# 9. Delegate a cross-workspace task to your new Gemini peer
+molecule workspace run orchestrator "delegate_task my-gemini-agent 'Draft release notes for v1.4'"
+
+# 10. Tear down when done
+molecule workspace delete my-gemini-agent
+```
+
+## Expected output
+
+After step 5 you should see:
+```
+my-gemini-agent  gemini-cli  ready   ord   2026-04-16T06:30:00Z
+```
+
+After step 6, Gemini CLI streams its reasoning and final answer directly to stdout. The agent uses `GEMINI.md` (seeded from your workspace's `system-prompt.md`) as persistent context — equivalent to `CLAUDE.md` for Claude Code workspaces.
+
+## How it works
+
+Molecule AI's `gemini-cli` adapter mirrors the battle-tested `claude-code` pattern: a Docker image installs `@google/gemini-cli` globally, and `CLIAgentExecutor` drives the subprocess. Because Gemini CLI reads MCP config from `~/.gemini/settings.json` rather than accepting a `--mcp-config` flag, the adapter's `setup()` method merges the A2A MCP server definition into that file at boot — preserving any user-defined tools.
+
+## Multi-provider teams
+
+The real power surfaces when you mix runtimes on the same Molecule AI tenant. Your orchestrator workspace can delegate tasks to both `claude-code` and `gemini-cli` workers simultaneously using `delegate_task_async`, then synthesize results — all through the same A2A protocol. This is provider diversity at the infrastructure layer, not at the application layer.
+
+## Related
+
+- PR #379: [feat(adapters): add gemini-cli runtime adapter](https://github.com/Molecule-AI/molecule-core/pull/379)
+- [Multi-provider Hermes docs](../architecture/hermes.md)
+- [Workspace runtimes reference](../reference/runtimes.md)