1 files changed, 52 insertions, 0 deletions
diff --git a/docs/core/index.md b/docs/core/index.md
new file mode 100644
index 00000000..0a3b9d9e
--- /dev/null
+++ b/docs/core/index.md
@@ -0,0 +1,52 @@
+# Gemini CLI Core
+
+This section delves into the core component of the Gemini CLI (`packages/core`). The core acts as the backend engine, handling communication with the Gemini API, managing tools, and processing requests from the CLI client.
+
+## Role of the Core
+
+The core package is a crucial part of the Gemini CLI ecosystem. While the CLI (`packages/cli`) provides the user interface, the core is responsible for:
+
+- **API Interaction:** Securely communicating with the Google Gemini API, sending user prompts, and receiving model responses.
+- **Prompt Engineering:** Constructing effective prompts for the Gemini model, potentially incorporating conversation history, tool definitions, and instructional context from `GEMINI.md` files.
+- **Tool Management & Orchestration:**
+  - Registering available tools (e.g., file system tools, shell command execution).
+  - Interpreting tool use requests from the Gemini model.
+  - Executing the requested tools with the provided arguments.
+  - Returning tool execution results to the Gemini model for further processing.
+- **Session and State Management:** Keeping track of the conversation state, including history and any relevant context required for coherent interactions.
+- **Configuration:** Managing core-specific configurations, such as API key access, model selection, and tool settings.
+
+## Key Components and Functionality
+
+While the exact implementation details are within the `packages/core/src/` directory, key conceptual components include:
+
+- **API Client** (`client.ts`): A module responsible for making HTTP requests to the Gemini API, handling authentication, and parsing responses.
+- **Prompt Management** (`prompts.ts`): Logic for creating and formatting the prompts sent to the Gemini model. This includes integrating user queries, historical context, and tool specifications.
+- **Tool Registry and Execution** (`tool-registry.ts`, `tools.ts`, individual tool files like `read-file.ts`, `shell.ts`):
+  - A system for discovering, registering, and describing available tools to the Gemini model.
+  - Code for executing each tool safely and effectively, often involving interaction with the operating system or external services.
+- **Configuration (`config.ts`):** Handles loading and providing access to core-side configurations, including API keys, model choices, and potentially tool-specific settings.
+- **Turn Management (`turn.ts`):** Manages the flow of a single conversational turn, from receiving user input to generating a final response, potentially involving multiple tool calls.
+
+## Interaction with the CLI
+
+The CLI and Core typically communicate over a local interface (e.g., standard input/output, or a local network connection if designed for broader use, though the current structure suggests a tightly coupled Node.js application).
+
+1.  The CLI captures user input and forwards it to the Core.
+2.  The Core processes the input, interacts with the Gemini API and tools as needed.
+3.  The Core sends responses (text, tool calls, errors) back to the CLI.
+4.  The CLI formats and displays these responses to the user.
+
+## Security Considerations
+
+The core plays a vital role in security:
+
+- **API Key Management:** It handles the `GEMINI_API_KEY` and ensures it is used securely when communicating with the Gemini API.
+- **Tool Execution:** When tools interact with the local system (e.g., `execute_bash_command`), the core (and its underlying tool implementations) must do so with appropriate caution, often involving sandboxing mechanisms to prevent unintended side effects.
+
+## Navigating this Section
+
+- **[Core Configuration](./configuration.md):** Details on how to configure the core component, including environment variables and specific settings.
+- **[Core Tools API](./tools-api.md):** Information on how tools are defined, registered, and used by the core.
+
+Understanding the core's role and architecture is key to comprehending the full capabilities and operational flow of the Gemini CLI.