docs: update and reorganize documentation (#806)

3 files changed, 35 insertions, 118 deletions

diff --git a/docs/core/configuration.md b/docs/core/configuration.md
deleted file mode 100644
index 5b8184bc..00000000
--- a/docs/core/configuration.md
+++ /dev/null
@@ -1,111 +0,0 @@
-# Gemini CLI Core: Configuration
-
-Configuration for the Gemini CLI core component (`packages/core`) is critical for its operation, dictating how it connects to the Gemini API, which model it uses, how tools are executed, and more. Many of these settings are shared with or derived from the main CLI configuration when the CLI initializes the core backend.
-
-## Primary Configuration Sources
-
-The core's configuration is primarily established when the `Config` object (from `packages/core/src/config/config.ts`) is instantiated. The values come from a combination of:
-
-1.  **Hardcoded Defaults:** Fallback values defined within the core and CLI packages.
-2.  **Settings Files (`settings.json` via CLI):** Persistent settings that the CLI reads (User settings `~/.gemini/settings.json`, then Workspace settings `.gemini/settings.json`) and then passes relevant parts to the core configuration.
-3.  **Environment Variables (potentially from `.env` files):** System-wide or session-specific variables. The CLI loads `.env` files (checking current directory, then ancestors, then `~/.env`) and these variables influence the core config.
-4.  **Command-Line Arguments (passed from CLI):** Settings chosen by the user at launch time, which have the highest precedence for many options.
-
-## Key Configuration Parameters for the Core
-
-These are the main pieces of information the core `Config` object holds and uses:
-
-- **`apiKey` (string):**
-
-  - **Source:** Primarily `process.env.GEMINI_API_KEY` (loaded from the environment or `.env` files).
-  - **Importance:** Absolutely essential for connecting to the Gemini API. (If using Vertex AI, authentication is handled differently, typically via Application Default Credentials - see README.md).
-
-- **`model` (string):**
-
-  - **Source:** Command-line argument (`--model`), environment variable (`GEMINI_MODEL`), or a default value (e.g., `gemini-2.5-pro-preview-06-05`).
-  - **Purpose:** Specifies which Gemini model the core should use. (For Vertex AI model names and usage, refer to the main README.md).
-
-- **`sandbox` (boolean | string):**
-
-  - **Source:** Command-line argument (`--sandbox`), environment variable (`GEMINI_SANDBOX`), or `settings.json` (`sandbox` key).
-  - **Purpose:** Determines if and how tools (especially `execute_bash_command`) are sandboxed. This is crucial for security.
-    - `true`: Use a default sandboxing method.
-    - `false`: No sandboxing (less secure).
-    - `"docker"`, `"podman"`, or a custom command string: Specific sandboxing method.
-
-- **`targetDir` (string):**
-
-  - **Source:** Typically `process.cwd()` (the current working directory from which the CLI was launched).
-  - **Purpose:** Provides a base directory context for tools that operate on the file system (e.g., `read_file`, `list_directory`). Paths used in tool calls are often resolved relative to this directory.
-
-- **`debugMode` (boolean):**
-
-  - **Source:** Command-line argument (`--debug_mode`) or environment variables (e.g., `DEBUG=true`, `DEBUG_MODE=true`).
-  - **Purpose:** Enables verbose logging within the core and its tools, which is helpful for development and troubleshooting.
-
-- **`question` (string | undefined):**
-
-  - **Source:** Command-line argument (`--question`), usually when input is piped to the CLI.
-  - **Purpose:** Allows a direct question to be passed to the core for processing without interactive input.
-
-- **`fullContext` (boolean):**
-
-  - **Source:** Command-line argument (`--all_files`).
-  - **Purpose:** If true, instructs relevant tools (like `read_many_files` when used implicitly by the model) to gather a broad context from the `targetDir`.
-
-- **`toolDiscoveryCommand` (string | undefined):** see under [CLI settings](../cli/configuration.md#available-settings-in-settingsjson).
-
-- **`toolCallCommand` (string | undefined)**: see under [CLI settings](../cli/configuration.md#available-settings-in-settingsjson).
-
-- `mcpServers` (object | undefined):
-  - **Source:** `settings.json` (`mcpServers` key), passed from the CLI.
-  - **Purpose:** Advanced setting for configuring connections to one or more Model-Context Protocol (MCP) servers. This allows the Gemini CLI to discover and utilize tools exposed by these external servers.
-  - **Structure:** An object where each key is a unique server name (alias) and the value is an object containing:
-    - `command` (string, required): The command to execute to start the MCP server.
-    - `args` (array of strings, optional): Arguments for the command.
-    - `env` (object, optional): Environment variables for the server process.
-    - `cwd` (string, optional): Working directory for the server.
-    - `timeout` (number, optional): Request timeout in milliseconds.
-  - **Behavior:** The core will attempt to connect to each configured MCP server. Tool names from these servers might be prefixed with the server alias to prevent naming collisions. The core may also adapt tool schemas from MCP servers for internal compatibility.
-- `mcpServerCommand` (string | undefined, **deprecated**):
-
-  - **Source:** `settings.json` (`mcpServerCommand` key).
-  - **Purpose:** Legacy setting for a single MCP server. Superseded by `mcpServers`.
-
-- **`userAgent` (string):**
-
-  - **Source:** Automatically generated by the CLI, often including CLI package name, version, and Node.js environment details.
-  - **Purpose:** Sent with API requests to help identify the client making requests to the Gemini API.
-
-- **`userMemory` (string):**
-
-  - **Source:** Loaded from the hierarchical `GEMINI.md` files by the CLI (Global, Project Root/Ancestors, Sub-directory) and passed to the core config.
-  - **Purpose:** Contains the combined instructional context provided to the Gemini model.
-  - **Mutability:** This can be updated if the memory is refreshed by the user (e.g., via the `/memory refresh` command in the CLI).
-
-- **`geminiMdFileCount` (number):**
-  - **Source:** Count of all `GEMINI.md` files successfully loaded by the CLI.
-  - **Purpose:** Metadata about the loaded instructional context, visible in the CLI footer.
-
-## Environment File (`.env`) Loading
-
-The CLI configuration logic, which precedes core initialization, includes loading an `.env` file. The search order is:
-
-1.  `.env` in the current working directory.
-2.  `.env` in parent directories, up to the project root (containing `.git`) or home directory.
-3.  `~/.env` (in the user's home directory).
-
-This file is a common place to store the `GEMINI_API_KEY` and other environment-specific settings like `GEMINI_MODEL` or `DEBUG` flags.
-
-```
-# Example .env file
-GEMINI_API_KEY="YOUR_ACTUAL_API_KEY_HERE"
-GEMINI_MODEL="gemini-1.5-flash-latest"
-# DEBUG=true
-```
-
-## Tool Registry Initialization
-
-Upon initialization, the core's `Config` object is also used to create and populate a `ToolRegistry`. This registry is then aware of the `targetDir` and `sandbox` settings, which are vital for the correct and secure operation of tools like `ReadFileTool`, `ShellTool`, etc. The `ToolRegistry` is responsible for making tool schemas available to the Gemini model and for executing tool calls.
-
-Proper core configuration, derived from these various sources, is essential for the Gemini CLI to function correctly, securely, and according to the user's intent.
diff --git a/docs/core/index.md b/docs/core/index.md
index 0a3b9d9e..da7e8c3c 100644
--- a/docs/core/index.md
+++ b/docs/core/index.md
@@ -1,6 +1,11 @@
 # 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.
+The Gemini CLI Core (`packages/core`) acts as the backend engine for the Gemini CLI, handling communication with the Gemini API, managing tools, and processing requests from the CLI client. For a general overview of the Gemini CLI, see the [main documentation page](../index.md).
+
+## Navigating this Section
+
+- **[Core Configuration](../cli/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.
 
 ## Role of the Core
 
@@ -44,9 +49,28 @@ 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
+## Chat History Compression
 
-- **[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.
+To ensure that long conversations don't exceed the token limits of the Gemini model, the CLI includes a chat history compression feature.
+
+When a conversation approaches the token limit for the configured model, the CLI will automatically compress the conversation history before sending it to the model. This compression is designed to be lossless in terms of the information conveyed, but it reduces the overall number of tokens used.
+
+You can find the token limits for each model in the [Google AI documentation](https://ai.google.dev/gemini-api/docs/models).
+
+## Model Fallback
+
+The Gemini CLI includes a model fallback mechanism to ensure that you can continue to use the CLI even if the default "pro" model is rate-limited.
+
+If you are using the default "pro" model and the CLI detects that you are being rate-limited, it will automatically switch to the "flash" model for the current session. This allows you to continue working without interruption.
+
+## File Discovery Service
+
+The file discovery service is responsible for finding files in the project that are relevant to the current context. It is used by the `@` command and other tools that need to access files.
+
+## Memory Discovery Service
+
+The memory discovery service is responsible for finding and loading the `GEMINI.md` files that provide context to the model. It searches for these files in a hierarchical manner, starting from the current working directory and moving up to the project root and the user's home directory. It also searches in subdirectories.
+
+This allows you to have global, project-level, and component-level context files, which are all combined to provide the model with the most relevant information.
 
-Understanding the core's role and architecture is key to comprehending the full capabilities and operational flow of the Gemini CLI.
+You can use the `/memory show` command to see the combined content of all loaded `GEMINI.md` files, and the `/memory refresh` command to reload them.
diff --git a/docs/core/telemetry.md b/docs/core/telemetry.md
index be80cd6f..09f4c0e7 100644
--- a/docs/core/telemetry.md
+++ b/docs/core/telemetry.md
@@ -21,13 +21,17 @@ Add this line to enable telemetry by in workspace (`.gemini/settings.json`) or u
 
 ```json
 {
-  "telemetry": true
+  "telemetry": {
+    "enabled": true
+  }
 }
 ```
 
+You can also control telemetry with the `GEMINI_TELEMETRY_ENABLED` environment variable.
+
 #### Mode 1: Console Output (Default)
 
-If you only set `"telemetry": true` and do nothing else, the CLI will output all telemetry data directly to your console. This is the simplest way to inspect events, metrics, and traces without any external tools.
+If you only set `"enabled": true` and do nothing else, the CLI will output all telemetry data directly to your console. This is the simplest way to inspect events, metrics, and traces without any external tools.
 
 #### Mode 2: Sending to a Collector