docs: distribute package-specific GEMINI.md context to each package (#22734)

GEMINI.md

@@ -22,9 +22,10 @@ powerful tool for developers.
     rendering.
   - `packages/core`: Backend logic, Gemini API orchestration, prompt
     construction, and tool execution.
-  - `packages/core/src/tools/`: Built-in tools for file system, shell, and web
-    operations.
   - `packages/a2a-server`: Experimental Agent-to-Agent server.
+  - `packages/sdk`: Programmatic SDK for embedding Gemini CLI capabilities.
+  - `packages/devtools`: Integrated developer tools (Network/Console inspector).
+  - `packages/test-utils`: Shared test utilities and test rig.
   - `packages/vscode-ide-companion`: VS Code extension pairing with the CLI.
 
 ## Building and Running
@@ -58,10 +59,6 @@ powerful tool for developers.
 
 ## Development Conventions
 
-- **Legacy Snippets:** `packages/core/src/prompts/snippets.legacy.ts` is a
-  snapshot of an older system prompt. Avoid changing the prompting verbiage to
-  preserve its historical behavior; however, structural changes to ensure
-  compilation or simplify the code are permitted.
 - **Contributions:** Follow the process outlined in `CONTRIBUTING.md`. Requires
   signing the Google CLA.
 - **Pull Requests:** Keep PRs small, focused, and linked to an existing issue.
@@ -69,8 +66,6 @@ powerful tool for developers.
   `gh` CLI.
 - **Commit Messages:** Follow the
   [Conventional Commits](https://www.conventionalcommits.org/) standard.
-- **Coding Style:** Adhere to existing patterns in `packages/cli` (React/Ink)
-  and `packages/core` (Backend logic).
 - **Imports:** Use specific imports and avoid restricted relative imports
   between packages (enforced by ESLint).
 - **License Headers:** For all new source code files (`.ts`, `.tsx`, `.js`),

packages/a2a-server/GEMINI.md

@@ -0,0 +1,22 @@
+# Gemini CLI A2A Server (`@google/gemini-cli-a2a-server`)
+
+Experimental Agent-to-Agent (A2A) server that exposes Gemini CLI capabilities
+over HTTP for inter-agent communication.
+
+## Architecture
+
+- `src/agent/`: Agent session management for A2A interactions.
+- `src/commands/`: CLI command definitions for the A2A server binary.
+- `src/config/`: Server configuration.
+- `src/http/`: HTTP server and route handlers.
+- `src/persistence/`: Session and state persistence.
+- `src/utils/`: Shared utility functions.
+- `src/types.ts`: Shared type definitions.
+
+## Running
+
+- Binary entry point: `gemini-cli-a2a-server`
+
+## Testing
+
+- Run tests: `npm test -w @google/gemini-cli-a2a-server`

packages/cli/GEMINI.md

@@ -5,7 +5,7 @@
 - Always fix react-hooks/exhaustive-deps lint errors by adding the missing
   dependencies.
 - **Shortcuts**: only define keyboard shortcuts in
-  `packages/cli/src/config/keyBindings.ts`
+  `packages/cli/src/ui/key/keyBindings.ts`
 - Do not implement any logic performing custom string measurement or string
   truncation. Use Ink layout instead leveraging ResizeObserver as needed.
 - Avoid prop drilling when at all possible.

packages/core/GEMINI.md

@@ -0,0 +1,47 @@
+# Gemini CLI Core (`@google/gemini-cli-core`)
+
+Backend logic for Gemini CLI: API orchestration, prompt construction, tool
+execution, and agent management.
+
+## Architecture
+
+- `src/agent/` & `src/agents/`: Agent lifecycle and sub-agent management.
+- `src/availability/`: Model availability checks.
+- `src/billing/`: Billing and usage tracking.
+- `src/code_assist/`: Code assistance features.
+- `src/commands/`: Built-in CLI command implementations.
+- `src/config/`: Configuration management.
+- `src/confirmation-bus/`: User confirmation flow for tool execution.
+- `src/core/`: Core types and shared logic.
+- `src/fallback/`: Fallback and retry strategies.
+- `src/hooks/`: Hook system for extensibility.
+- `src/ide/`: IDE integration interfaces.
+- `src/mcp/`: MCP (Model Context Protocol) client and server integration.
+- `src/output/`: Output formatting and rendering.
+- `src/policy/`: Policy enforcement (e.g., tool confirmation policies).
+- `src/prompts/`: System prompt construction and prompt snippets.
+- `src/resources/`: Resource management.
+- `src/routing/`: Model routing and selection logic.
+- `src/safety/`: Safety filtering and guardrails.
+- `src/scheduler/`: Task scheduling.
+- `src/services/`: Shared service layer.
+- `src/skills/`: Skill discovery and activation.
+- `src/telemetry/`: Usage telemetry and logging.
+- `src/tools/`: Built-in tool implementations (file system, shell, web, MCP).
+- `src/utils/`: Shared utility functions.
+- `src/voice/`: Voice input/output support.
+
+## Coding Conventions
+
+- **Legacy Snippets:** `src/prompts/snippets.legacy.ts` is a snapshot of an
+  older system prompt. Avoid changing the prompting verbiage to preserve its
+  historical behavior; however, structural changes to ensure compilation or
+  simplify the code are permitted.
+- **Style:** Follow existing backend logic patterns. This package has no UI
+  dependencies — keep it framework-agnostic.
+
+## Testing
+
+- Run tests: `npm test -w @google/gemini-cli-core`
+- Run a specific test:
+  `npm test -w @google/gemini-cli-core -- src/path/to/file.test.ts`

packages/sdk/GEMINI.md

@@ -0,0 +1,18 @@
+# Gemini CLI SDK (`@google/gemini-cli-sdk`)
+
+Programmatic SDK for embedding Gemini CLI agent capabilities into other
+applications.
+
+## Architecture
+
+- `src/agent.ts`: Agent creation and management.
+- `src/session.ts`: Session lifecycle and state management.
+- `src/tool.ts`: Tool definition and execution interface.
+- `src/skills.ts`: Skill integration.
+- `src/fs.ts` & `src/shell.ts`: File system and shell utilities.
+- `src/types.ts`: Public type definitions.
+
+## Testing
+
+- Run tests: `npm test -w @google/gemini-cli-sdk`
+- Integration tests use `*.integration.test.ts` naming convention.

packages/test-utils/GEMINI.md

@@ -0,0 +1,16 @@
+# Gemini CLI Test Utils (`@google/gemini-cli-test-utils`)
+
+Shared test utilities used across the monorepo. This is a private package — not
+published to npm.
+
+## Key Modules
+
+- `src/test-rig.ts`: The primary test rig for spinning up end-to-end CLI
+  sessions with mock responses.
+- `src/file-system-test-helpers.ts`: Helpers for creating temporary file system
+  fixtures.
+- `src/mock-utils.ts`: Common mock utilities.
+
+## Usage
+
+Import from `@google/gemini-cli-test-utils` in test files across the monorepo.

packages/vscode-ide-companion/GEMINI.md

@@ -0,0 +1,23 @@
+# Gemini CLI VS Code Companion (`gemini-cli-vscode-ide-companion`)
+
+VS Code extension that pairs with Gemini CLI, providing direct IDE workspace
+access to the CLI agent.
+
+## Architecture
+
+- `src/extension.ts`: Extension activation and lifecycle.
+- `src/ide-server.ts`: Local server exposing IDE capabilities to the CLI.
+- `src/diff-manager.ts`: Diff viewing and application.
+- `src/open-files-manager.ts`: Tracks and exposes open editor files.
+- `src/utils/`: Shared utility functions.
+
+## Development
+
+- Requires VS Code `^1.99.0`.
+- Build: `npm run build` (uses esbuild).
+- Launch via VS Code's "Run Extension" debug configuration.
+
+## Testing
+
+- Run tests: `npm test -w gemini-cli-vscode-ide-companion`
+- Tests use standard Vitest patterns alongside VS Code test APIs.