feat(gemini): add Gemini CLI as supported target with integration tests

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - PGS project board sync: `scripts/project/sync_item.py` and `.github/workflows/project-sync.yml` keep https://github.com/orgs/microsoft/projects/2304 in lockstep with `theme/*`, `area/*`, `type/*`, `priority/*` labels and milestones. Backfill helper at `scripts/project/backfill.sh`. (#919)
 
+- **Gemini CLI** as a supported APM target (`--target gemini`). APM auto-detects `.gemini/` directories and writes MCP server configuration to `.gemini/settings.json`. Includes `apm runtime setup gemini` / `apm runtime remove gemini` support. (#917)
 - New `pr-description-skill` skill bundle: enforces a 10-section PR body shape (TL;DR / Problem / Approach / Implementation / Diagrams / Trade-offs / Benefits / Validation / How to test, plus the `Co-authored-by` trailer) with a cite-or-omit rule for every WHY-claim, GFM-rendered output, ASCII-only template source, and validated mermaid diagrams. Captures the meta-pattern from PR #882 as a reusable scaffold so future PR bodies meet the same bar without per-PR specialist subagent intervention. (#884)
 - `apm experimental` command group -- a feature-flag registry with `list` / `enable` / `disable` / `reset` subcommands. Opt in to new behaviour before it graduates to default. Ships with one built-in flag (`verbose-version`) and a contributor recipe for proposing new flags. (#849)
 - `includes:` manifest field (auto | list) for explicit governance of local `.apm/` content. Closes audit-blindness gap (#887).

README.md

@@ -4,7 +4,7 @@
 
 Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.
 
-GitHub Copilot · Claude Code · Cursor · OpenCode · Codex
+GitHub Copilot · Claude Code · Cursor · OpenCode · Codex · Gemini
 
 **[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304)**
 
@@ -50,7 +50,7 @@ apm install    # every agent is configured
 
 One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
 
-- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — declared once, deployed across Copilot, Claude, Cursor, OpenCode, Codex
+- **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** — declared once, deployed across Copilot, Claude, Cursor, OpenCode, Codex, Gemini
 - **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, any git host
 - **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
 - **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
@@ -128,7 +128,7 @@ apm marketplace add github/awesome-copilot
 apm install azure-cloud-development@awesome-copilot
 ```
 
-Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, and OpenCode):
+Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, OpenCode, and Gemini):
 
 ```bash
 apm install --mcp io.github.github/github-mcp-server --transport http   # connects over HTTPS

docs/src/content/docs/enterprise/making-the-case.md

@@ -11,7 +11,7 @@ An internal advocacy toolkit. The lead section frames the problem; the rest is d
 
 ## The problem at scale
 
-Consider a mid-to-large engineering organization: 50 repositories, 200 developers, four AI coding tools (Copilot, Claude, Cursor, OpenCode).
+Consider a mid-to-large engineering organization: 50 repositories, 200 developers, five AI coding tools (Copilot, Claude, Cursor, OpenCode, Gemini).
 
 Without centralized configuration management, a predictable set of problems emerges:
 
@@ -49,7 +49,7 @@ Running `apm install` resolves every dependency and writes `apm.lock.yaml`, whic
 
 ### Install
 
-`apm install` reads the lock file and deploys configuration into the native formats expected by each tool -- `.github/` for Copilot, `.claude/` for Claude, `.cursor/` for Cursor, `.opencode/` for OpenCode. APM generates static files and then gets out of the way. There is no runtime, no daemon, no background process.
+`apm install` reads the lock file and deploys configuration into the native formats expected by each tool -- `.github/` for Copilot, `.claude/` for Claude, `.cursor/` for Cursor, `.opencode/` for OpenCode, `.gemini/` for Gemini. APM generates static files and then gets out of the way. There is no runtime, no daemon, no background process.
 
 ### Audit
 
@@ -109,7 +109,7 @@ For the full forensic and compliance recipes, see the [Lock File Specification](
 
 Plugins handle single-tool installation for a single AI platform. APM adds capabilities that plugins do not provide:
 
-- **Cross-tool composition.** One manifest manages configuration for Copilot, Claude, Cursor, OpenCode, and any other agent runtime simultaneously.
+- **Cross-tool composition.** One manifest manages configuration for Copilot, Claude, Cursor, OpenCode, Gemini, and any other agent runtime simultaneously.
 - **Consumer-side lock files.** Plugins install the latest version. APM pins exact versions so your team stays synchronized.
 - **CI enforcement.** Content scanning is built into `apm install` -- no plugin equivalent exists. `apm audit --ci` adds lockfile consistency checks and `--policy org` enforces organizational rules.
 - **Multi-source dependency resolution.** APM resolves transitive dependencies across packages from multiple git hosts.

docs/src/content/docs/getting-started/first-package.md

@@ -194,14 +194,15 @@ team-skills/
 
 `apm install` auto-detects which runtimes you have. The example above shows
 `.github/` because Copilot is the default fallback. If `.claude/`, `.cursor/`,
-or `.opencode/` exists in the project, they get populated too. To target
+`.opencode/`, or `.gemini/` exists in the project, they get populated too. To target
 explicitly, see the [Compilation guide](/apm/guides/compilation/).
 
 > **What about `apm compile`?** Compile is a different concern: it
-> generates merged `AGENTS.md` / `CLAUDE.md` files for tools that read a
-> single top-level context document (Codex, Gemini, plain `agents`-protocol
-> hosts). Copilot, Claude Code, and Cursor read the per-skill directories
-> directly -- no compile step needed.
+> generates merged `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` files for tools
+> that read a top-level context document for instructions (Codex, Gemini,
+> plain `agents`-protocol hosts). Gemini also receives commands, skills,
+> hooks, and MCP via `apm install`. Copilot, Claude Code, and Cursor read
+> the per-skill directories directly -- no compile step needed.
 
 Now open Copilot or Claude in this project. Ask "draft a PR description for
 my last commit". The `pr-description` skill activates on its own. To get the

docs/src/content/docs/getting-started/quick-start.md

@@ -92,12 +92,15 @@ my-project/
       design-reviewer.md
     commands/
       design-review.md
+  .gemini/
+    commands/
+      design-review.toml
 ```
 
 Three things happened:
 
 1. The package was downloaded into `apm_modules/` (like `node_modules/`).
-2. Instructions, agents, and skills were deployed to `.github/`, `.claude/`, `.cursor/`, and `.opencode/` (when present) -- the native directories that GitHub Copilot, Claude, Cursor, and OpenCode read from. If the project has its own `.apm/` content, that is deployed too (local content takes priority over dependencies on collision).
+2. Agents, commands, skills, and hooks were deployed to `.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, and `.gemini/` (when present). If the project has its own `.apm/` content, that is deployed too (local content takes priority over dependencies on collision).
 3. A lockfile (`apm.lock.yaml`) was created, pinning the exact commit so every team member gets identical configuration.
 
 Your `apm.yml` now tracks the dependency:
@@ -138,15 +141,16 @@ apm install github/awesome-copilot/skills/review-and-refactor
 - `apm.yml` and `apm.lock.yaml` — version-controlled, shared with the team.
 - `.github/` deployed files (`prompts/`, `agents/`, `instructions/`, `skills/`, `hooks/`) — commit them so every contributor (and [Copilot on github.com](https://docs.github.com/en/copilot)) gets agent context immediately after cloning, before they run `apm install` to sync and regenerate files.
 - `.claude/` deployed files (`agents/`, `commands/`, `skills/`, `hooks/`) — same rationale for Claude Code users: committed files give instant context on clone, while `apm install` remains the way to refresh them from `apm.yml`.
-- `.cursor/` deployed files (`rules/`, `agents/`, `skills/`, `hooks/`) — same rationale for Cursor users.
-- `apm_modules/` — add to `.gitignore`. Rebuilt from the lockfile on install.
+- `.cursor/` deployed files (`rules/`, `agents/`, `skills/`, `hooks/`) -- same rationale for Cursor users.
+- `.gemini/` deployed files (`commands/`, `skills/`, `settings.json`) -- same rationale for Gemini CLI users.
+- `apm_modules/` -- add to `.gitignore`. Rebuilt from the lockfile on install.
 
 :::tip[Keeping deployed files in sync]
-When you update `apm.yml`, re-run `apm install` and commit the changed `.github/`, `.claude/`, and `.cursor/` files. A [CI drift check](../../integrations/ci-cd/#verify-deployed-primitives) catches stale files automatically.
+When you update `apm.yml`, re-run `apm install` and commit the changed `.github/`, `.claude/`, `.cursor/`, and `.gemini/` files. A [CI drift check](../../integrations/ci-cd/#verify-deployed-primitives) catches stale files automatically.
 :::
 
 :::note[Using Codex or Gemini?]
-These tools use different configuration formats. Run `apm compile` after installing to generate their native files. See the [Compilation guide](../../guides/compilation/) for details.
+Gemini and Codex need `apm compile` for instructions (`GEMINI.md` / `AGENTS.md`). Gemini receives commands, skills, hooks, and MCP via `apm install`. See the [Compilation guide](../../guides/compilation/) for details.
 :::
 
 ## Add MCP servers
@@ -157,7 +161,7 @@ APM also manages MCP servers -- the tools your AI agent calls at runtime.
 apm install --mcp io.github.github/github-mcp-server
 ```
 
-This wires the server into every detected client (Copilot, Claude, Cursor, Codex, OpenCode). See the [MCP Servers guide](../../guides/mcp-servers/) for stdio and remote shapes.
+This wires the server into every detected client (Copilot, Claude, Cursor, Codex, OpenCode, Gemini). See the [MCP Servers guide](../../guides/mcp-servers/) for stdio and remote shapes.
 
 ## Next steps
 

docs/src/content/docs/guides/compilation.md

@@ -4,7 +4,7 @@ sidebar:
   order: 1
 ---
 
-Compilation is **optional for most users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. For OpenCode, `apm install` deploys agents, commands, skills, and MCP, but instructions require `apm compile` to generate the `AGENTS.md` that OpenCode reads. For Codex, `apm install` deploys skills, agents, and hooks natively, but instructions require `apm compile`. `apm compile` is also needed for Gemini or other tools that read single-root-file formats.
+Compilation is **optional for some users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. For Gemini, `apm install` deploys commands, skills, and hooks, but instructions require `apm compile` to generate `GEMINI.md`. For OpenCode and Codex, `apm install` deploys agents, commands, skills, and hooks, but instructions require `apm compile` to generate `AGENTS.md`.
 
 **Solving the AI agent scalability problem through constraint satisfaction optimization**
 
@@ -23,14 +23,16 @@ When you run `apm compile` without specifying a target, APM automatically detect
 | `.github/` folder only | `copilot` | AGENTS.md (instructions only) |
 | `.claude/` folder only | `claude` | CLAUDE.md (instructions only) |
 | `.codex/` folder exists | `codex` | AGENTS.md (instructions only) |
-| Both folders exist | `all` | Both AGENTS.md and CLAUDE.md |
+| `.gemini/` folder exists | `gemini` | GEMINI.md (instructions only) |
+| Multiple folders exist | `all` | AGENTS.md + CLAUDE.md + GEMINI.md |
 | Neither folder exists | `minimal` | AGENTS.md only (universal format) |
 
 ```bash
 apm compile                    # Auto-detects target from project structure
-apm compile --target copilot   # Force GitHub Copilot, Cursor, Gemini
-apm compile --target codex     # Force Codex CLI
+apm compile --target copilot   # Force GitHub Copilot, Cursor
 apm compile --target claude    # Force Claude Code, Claude Desktop
+apm compile --target gemini    # Force Gemini CLI
+apm compile --target codex     # Force Codex CLI
 apm compile -t claude,copilot  # Multiple targets (comma-separated)
 ```
 
@@ -51,15 +53,16 @@ target: [claude, copilot]  # multiple targets -- only these are compiled
 
 | Target | Files Generated | Consumers |
 |--------|-----------------|-----------|
-| `copilot` | `AGENTS.md` | GitHub Copilot, Cursor, OpenCode, Gemini |
-| `codex` | `AGENTS.md` | Codex CLI |
+| `copilot` | `AGENTS.md` | GitHub Copilot, Cursor, OpenCode |
 | `claude` | `CLAUDE.md` | Claude Code, Claude Desktop |
-| `all` | Both `AGENTS.md` and `CLAUDE.md` | Universal compatibility |
+| `gemini` | `GEMINI.md` | Gemini CLI |
+| `codex` | `AGENTS.md` | Codex CLI |
+| `all` | `AGENTS.md` + `CLAUDE.md` + `GEMINI.md` | Universal compatibility |
 | `minimal` | `AGENTS.md` only | Works everywhere, no folder integration |
 
 > **Aliases**: `vscode` and `agents` are accepted as aliases for `copilot`.
 
-> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](../../integrations/ide-tool-integration/) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, `.claude/commands/`, `.cursor/rules/`, `.cursor/agents/`, `.opencode/agents/`, `.opencode/commands/`, `.codex/agents/`, and `.agents/skills/`.
+> **Note**: `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](../../integrations/ide-tool-integration/) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, `.claude/commands/`, `.cursor/rules/`, `.cursor/agents/`, `.opencode/agents/`, `.opencode/commands/`, `.codex/agents/`, `.gemini/commands/`, and `.agents/skills/`.
 
 ### How It Works
 
@@ -447,9 +450,9 @@ Different AI tools get different levels of support from `apm install` vs `apm co
 | Cursor | `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json` | `AGENTS.md` (optional) | **Full** |
 | OpenCode | `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`, `opencode.json` (MCP) | Via `AGENTS.md` | **Full** |
 | Codex CLI | `.agents/skills/`, `.codex/agents/`, `.codex/hooks.json` | `AGENTS.md` (instructions) | **Full** |
-| Gemini | -- | `GEMINI.md` | Instructions via compile |
+| Gemini | `.gemini/commands/`, `.gemini/skills/`, `.gemini/settings.json` (MCP, hooks) | `GEMINI.md` (instructions) | **Full** |
 
-For Copilot, Claude, and Cursor users, `apm install` handles everything natively. OpenCode and Codex users should also run `apm compile` to generate `AGENTS.md` for instructions. Compilation is the bridge that brings instruction support to tools that do not yet have first-class APM integration.
+For Copilot, Claude, and Cursor users, `apm install` handles everything natively. Gemini, OpenCode, and Codex users should also run `apm compile` to generate their instruction roll-up (`GEMINI.md` or `AGENTS.md`).
 
 ## Theoretical Foundations
 

docs/src/content/docs/guides/mcp-servers.md

@@ -1,13 +1,13 @@
 ---
 title: "MCP Servers"
-description: "Add MCP servers to your project with apm install --mcp. Supports stdio, registry, and remote HTTP servers across Copilot, Claude, Cursor, Codex, and OpenCode."
+description: "Add MCP servers to your project with apm install --mcp. Supports stdio, registry, and remote HTTP servers across Copilot, Claude, Cursor, Codex, OpenCode, and Gemini."
 sidebar:
   order: 6
 ---
 
 APM manages your agent configuration in `apm.yml` -- think `package.json` for AI. MCP servers are dependencies in that manifest.
 
-`apm install --mcp` adds a server to `apm.yml` and wires it into every detected client (Copilot, Claude, Cursor, Codex, OpenCode) in one step.
+`apm install --mcp` adds a server to `apm.yml` and wires it into every detected client (Copilot, Claude, Cursor, Codex, OpenCode, Gemini) in one step.
 
 ## Quick Start
 

docs/src/content/docs/index.mdx

@@ -26,7 +26,7 @@ APM fixes this. You declare your project's agent configuration once in `apm.yml`
 
 <CardGrid>
   <Card title="Portable by manifest" icon="document">
-    One `apm.yml` declares skills, instructions, prompts, agents, hooks, plugins, and MCP servers. Transitive dependencies resolve like npm or pip; `apm.lock.yaml` pins exact versions for reproducible installs across Copilot, Claude Code, Cursor, OpenCode, and Codex.
+    One `apm.yml` declares skills, instructions, prompts, agents, hooks, plugins, and MCP servers. Transitive dependencies resolve like npm or pip; `apm.lock.yaml` pins exact versions for reproducible installs across Copilot, Claude Code, Cursor, OpenCode, Codex, and Gemini.
   </Card>
   <Card title="Secure by default" icon="approve-check-circle">
     Skills, prompts, instructions, hooks — everything agents execute is an attack surface. `apm install` scans packages for hidden Unicode and other tampering before they reach your agents; `apm audit` reports the full chain of trust.
@@ -92,7 +92,7 @@ New developer joins the team:
 git clone <org/repo> && cd <repo> && apm install
 ```
 
-**That's it.** Copilot, Claude, Cursor, OpenCode, Codex — every harness is configured with the right context and capabilities. The manifest defines the project's custom and portable Agentic SDLC setup installable in a single command.
+**That's it.** Copilot, Claude, Cursor, OpenCode, Codex, Gemini — every harness is configured with the right context and capabilities. The manifest defines the project's custom and portable Agentic SDLC setup installable in a single command.
 
 ## Open Source & Community