[docs] Update runtime-compatibility docs for Gemini CLI (#917)

[danielmeppiel]

Documentation Updates - 2026-04-26

This PR updates runtime-compatibility.md to document the Gemini CLI runtime added in #917.

Features Documented

• Google Gemini CLI runtime (apm runtime setup gemini) — from feat(gemini): add Gemini CLI as supported target with integration tests #917

Changes Made

• Updated docs/src/content/docs/integrations/runtime-compatibility.md:
  • Overview: updated "three runtimes" -> "four runtimes"; added Gemini CLI row to the support table
  • Quick Setup: added apm runtime setup gemini to the runtime management example block
  • New Google Gemini CLI Runtime section covering:
    • Install via APM (apm runtime setup gemini)
    • Three authentication options (browser login / GOOGLE_API_KEY / Vertex AI)
    • Usage examples and apm.yml script configuration
    • MCP integration note (.gemini/settings.json)
  • Troubleshooting: added gemini to the "Runtime not found" install list; added "Command not found: gemini" entry

Merged PRs Referenced

• feat(gemini): add Gemini CLI as supported target with integration tests #917 — feat(gemini): add Gemini CLI as supported target with integration tests

Notes

The other documentation files updated as part of #917 (ide-tool-integration.md, compilation.md, quick-start.md, how-it-works.md, cli-commands.md, CHANGELOG) already included Gemini. This PR closes the remaining gap in runtime-compatibility.md.

Generated by Daily Documentation Updater · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/daily-doc-updater.md@b87234850bf9664d198f28a02df0f937d0447295

• expires on Apr 28, 2026, 3:58 AM UTC

[Copilot]

Pull request overview

Updates the runtime compatibility documentation to include the newly supported Google Gemini CLI runtime (apm runtime setup gemini) and its setup/usage/troubleshooting guidance.

Changes:

• Expand the overview/support table from three to four runtimes by adding Google Gemini CLI.
• Add Gemini CLI quick setup and a new section documenting installation, authentication, usage, and MCP integration behavior.
• Extend troubleshooting guidance to include Gemini runtime installation and a dedicated "Command not found: gemini" entry.

Show a summary per file

File	Description
docs/src/content/docs/integrations/runtime-compatibility.md	Documents Gemini CLI runtime support, including setup/auth/usage/MCP integration and troubleshooting updates.

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 2

[Copilot]

The Gemini row in the overview table says "Browser login or API key", but the Gemini section below documents three auth modes (browser login, GOOGLE_API_KEY, and Vertex AI). Consider updating the table cell to include Vertex AI as well to keep the page consistent.

Suggested change

	| [**Google Gemini CLI**](https://github.com/google-gemini/gemini-cli) | Google's Gemini CLI | Gemini models, sandboxed agentic tasks | Browser login or API key |
	| [**Google Gemini CLI**](https://github.com/google-gemini/gemini-cli) | Google's Gemini CLI | Gemini models, sandboxed agentic tasks | Browser login, API key, or Vertex AI |

[Copilot]

The example model name here (gemini-2.5-pro-preview) is inconsistent with the model example printed by the runtime setup script (setup-gemini.sh shows gemini-3.1-pro-preview). To avoid confusion and doc drift, align this example with the setup output or make it a generic placeholder (e.g., "gemini -m ").

Suggested change

	gemini -m gemini-2.5-pro-preview
	gemini -m <model>

[github-actions]

APM Review Panel Verdict

Disposition: APPROVE (one minor optional cleanup noted below)

---

Per-persona findings

Python Architect: Documentation-only PR -- no Python code changes. The diff documents the Gemini CLI runtime that shipped in #917 and is fully implemented. Technical accuracy was verified against the live implementation.

OO / class diagram -- Gemini runtime problem space:

classDiagram
    direction LR
    class RuntimeManager {
        <<Service>>
        +supported_runtimes dict
        +setup_runtime(name) bool
        +remove_runtime(name) bool
    }
    class GeminiClientAdapter {
        <<Adapter>>
        +supports_user_scope bool
        +get_config_path() str
        +update_config(updates) void
        +get_current_config() dict
        +_format_server_config(info) dict
    }
    class CopilotClientAdapter {
        <<Adapter>>
        +_select_package(info) str
        +_resolve_env_vars(info) dict
    }
    class TargetProfile {
        <<ValueObject>>
        +name str
        +root_dir str
        +primitives dict
        +auto_create bool
        +detect_by_dir bool
    }
    RuntimeManager ..> GeminiClientAdapter : uses for MCP config
    GeminiClientAdapter --|> CopilotClientAdapter : extends
    TargetProfile ..> GeminiClientAdapter : configured by

Loading

Execution-flow diagram -- documented flows:

flowchart TD
    A[apm runtime setup gemini] --> B[RuntimeManager.setup_runtime]
    B --> C[setup-gemini.sh]
    C --> D[npm install -g `@google/gemini-cli`]
    C --> E[Create ~/.gemini/settings.json with empty mcpServers]
    F[apm install] --> G{.gemini/ dir exists?}
    G -- Yes --> H[GeminiClientAdapter.update_config]
    H --> I[.gemini/settings.json updated with mcpServers]
    G -- No --> J[Skip silently -- opt-in behavior]

Loading

Design patterns: Adapter pattern (GeminiClientAdapter extends CopilotClientAdapter); opt-in integration gated by directory detection (detect_by_dir=True in TargetProfile).

Accuracy findings:

• "Installs @google/gemini-cli from npm" -- CORRECT (manager.py + setup-gemini.sh)
• "Requires Node.js v20+ and npm v10+" -- CORRECT (NODE_MIN_VERSION="20", NPM_MIN_VERSION="10" in setup script)
• "Creates ~/.gemini/settings.json with empty mcpServers" -- CORRECT (setup script creates {"mcpServers": {}})
• "APM writes MCP config when .gemini/ dir exists" -- CORRECT (GeminiClientAdapter.update_config() guards on gemini_dir.is_dir())
• Auth options (browser login, GOOGLE_API_KEY, Vertex AI env vars) -- CORRECT (matches setup script next-steps)
• Minor: doc says gemini -m gemini-2.5-pro-preview; setup-gemini.sh next-steps output says gemini-3.1-pro-preview -- minor inconsistency (see optional follow-ups).

---

CLI Logging Expert: Documentation-only PR. No CommandLogger, _rich_*, or STATUS_SYMBOLS changes. The documented commands (apm runtime setup gemini, apm run start, apm install) all use established output paths. Script examples use Gemini's own flags (-y, -s, -p) which are correct. No logging or output concerns.

---

DevX UX Expert: Documentation is well-structured and consistent with the Copilot CLI and Codex sections. Command surface (apm runtime setup gemini) follows the established pattern. Three authentication methods are clearly presented with concrete env var names and the free-tier rate limit (60 req/min) noted. Troubleshooting entry "Command not found: gemini" is actionable with a clear fix sequence. The opt-in .gemini/ directory requirement for MCP integration is clearly explained. Cross-reference to the IDE and Tool Integration guide is appropriate. No UX concerns.

---

Supply Chain Security Expert: Documentation-only PR. No changes to dependency resolution, lockfile integrity, package downloads, or authentication code. The doc accurately states that @google/gemini-cli is installed "from the public npm registry," consistent with the Copilot CLI pattern. The opt-in behavior (mkdir .gemini before MCP config is written) is accurately documented and is security-positive: APM does not write to Gemini's config unless the user explicitly creates the directory. No security concerns.

---

Auth Expert: Not activated -- PR touches only docs/src/content/docs/integrations/runtime-compatibility.md; no auth code files changed. The authentication methods described (browser login, GOOGLE_API_KEY, Vertex AI env vars) are Gemini CLI's own authentication surface and do not affect APM's AuthResolver, token management, host classification, or credential resolution.

---

OSS Growth Hacker: Positive growth signal. Gemini CLI is Google's fast-growing entry into agentic coding; first-class docs for it reinforce APM's "universal AI tool manager" positioning. Updating the overview table to "four runtimes" is a concrete, quotable capability claim. The MCP integration note and the cross-link to the IDE integration guide create a clear adoption path for Gemini CLI users discovering APM.

Side-channel to CEO: The four-runtime milestone (Copilot, Codex, Gemini, LLM) is worth a brief release-note callout and a WIP/growth-strategy.md entry -- "APM is the first tool to manage packages across all four major open AI runtimes." This framing differentiates APM cleanly from single-runtime wrappers.

---

CEO arbitration

All specialists agreed: this is a clean, accurate, well-structured documentation follow-up to the Gemini CLI feature shipped in #917. There are no disagreements to resolve. The single minor inconsistency (model name in docs vs. setup script) is cosmetic and does not block merge. Strategically, shipping this doc promptly after the feature lands is the right call -- docs lag is a silent conversion killer. The four-runtime positioning is a useful growth asset worth amplifying in the next release note. Disposition ratified: APPROVE.

---

Required actions before merge

None.

---

Optional follow-ups

• docs/.../runtime-compatibility.md line using gemini -m gemini-2.5-pro-preview vs. setup-gemini.sh next-steps output using gemini-3.1-pro-preview -- align to whichever model name is more current upstream to avoid user confusion. Neither is authoritative in APM; the fix belongs in whichever source drifted.
• Consider adding a CHANGELOG.md entry under [Unreleased] if the team convention covers docs additions for newly documented features (the Gemini feature itself may already have an entry from feat(gemini): add Gemini CLI as supported target with integration tests #917; this docs PR could be combined into the same entry as (#917, #945)).
• The "four runtimes" milestone could be highlighted in the next release note and WIP/growth-strategy.md as a concrete multi-runtime positioning claim.

Generated by PR Review Panel for issue #945 · ● 858.3K · ◷