Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <[email protected]>

3 files changed, 297 insertions, 0 deletions

diff --git a/docs/cli/commands.md b/docs/cli/commands.md
new file mode 100644
index 00000000..c3460e63
--- /dev/null
+++ b/docs/cli/commands.md
@@ -0,0 +1,80 @@
+# CLI Commands
+
+The Gemini CLI supports several built-in commands to help you manage your session, customize the interface, and control its behavior. These commands are typically prefixed with a forward slash (`/`), an at symbol (`@`), or an exclamation mark (`!`).
+
+## Slash Commands (`/`)
+
+Slash commands provide meta-level control over the CLI itself. They can typically be executed by typing the command and pressing `Enter`.
+
+- **`/help`** (or **`/?`**)
+
+  - **Description:** Displays help information about the Gemini CLI, including available commands and their usage.
+  - **Action:** Opens a help dialog or section within the CLI.
+
+- **`/clear`** (Shortcut: **Ctrl+L**)
+
+  - **Description:** Clears the entire terminal screen, including the visible session history and scrollback within the CLI.
+  - **Action:** Wipes the terminal display. The underlying session data (for history recall) might be preserved depending on the exact implementation, but the visual display is cleared.
+
+- **`/theme`**
+
+  - **Description:** Allows you to change the visual theme of the Gemini CLI.
+  - **Action:** Opens a dialog or prompt to select from available themes.
+
+- **`/refreshmemory`**
+
+  - **Description:** Reloads instructional context from all `GEMINI.md` files found in the current directory hierarchy (project, user, and global).
+  - **Action:** The CLI re-scans for `GEMINI.md` files and updates its instructional memory with their content.
+
+- **`/showmemory`**
+
+  - **Description:** Displays the current hierarchical memory content that has been loaded from `GEMINI.md` files.
+  - **Action:** Outputs the combined content of all loaded `GEMINI.md` files, showing the context being provided to the Gemini model.
+
+- **`/quit`** (or **`/exit`**)
+  - **Description:** Exits the Gemini CLI application.
+  - **Action:** Terminates the CLI process.
+
+## At Commands (`@`)
+
+At commands are used to quickly include the content of files or directories as part of your prompt to Gemini.
+
+- **`@<path_to_file_or_directory>`**
+
+  - **Description:** Injects the content of the specified file or files within a directory into your current prompt. This is useful for asking questions about specific code, text, or collections of files.
+  - **Usage:**
+    - `@path/to/your/file.txt Explain this text.`
+    - `@src/my_project/ Summarize the code in this directory.`
+    - `What is this file about? @README.md`
+  - **Details:**
+    - If a path to a single file is provided, the content of that file is read.
+    - If a path to a directory is provided, the command attempts to read the content of files within that directory (often recursively, like `directory/**`).
+    - Spaces in paths should be escaped with a backslash (e.g., `@My\ Documents/file.txt`).
+    - The command uses the `read_many_files` tool internally. The content is fetched and then prepended or inserted into your query before being sent to the Gemini model.
+    - The text before and after the `@<path>` part of your query is preserved and sent along with the file content.
+    - **File Types:** The command is intended for text-based files. While it might attempt to read any file, binary files or very large files might be skipped or truncated by the underlying `read_many_files` tool to ensure performance and relevance. The tool will typically indicate if files were skipped.
+  - **Output:** The CLI will show a tool call message indicating that `read_many_files` was used, along with an improved display message detailing the status (e.g., number of files read, total size) and the path(s) that were processed.
+
+- **`@` (Lone At Symbol)**
+  - **Description:** If you type a lone `@` symbol without a path, the entire query (including the `@`) is passed directly to the Gemini model. This might be useful if you are specifically talking _about_ the `@` symbol itself in your prompt.
+
+### Error Handling for `@` Commands
+
+- If the path specified after `@` is not found or is invalid, an error message will be displayed, and the query might not be sent to the Gemini model, or it will be sent without the file content.
+- If the `read_many_files` tool encounters an error (e.g., permission issues), this will also be reported.
+
+## Shell Passthrough Commands (`!`)
+
+Shell passthrough commands allow you to execute arbitrary shell commands directly from the Gemini CLI. This can be useful for quickly performing system tasks, listing files, or running scripts without leaving the CLI environment.
+
+- **`!<shell_command>`**
+
+  - **Description:** Executes the given command in your system's default shell.
+  - **Usage:**
+    - `!ls -la`
+    - `!git status`
+    - `!echo "Hello from the shell"`
+  - **Action:** The command following the `!` is passed to the system shell for execution. The standard output and standard error from the command are then displayed directly within the Gemini CLI.
+  - **Caution:** Be mindful of the commands you execute, as they have the same permissions and impact as if you ran them directly in your terminal.
+
+These commands provide a powerful way to interact with the Gemini CLI and integrate local file content seamlessly into your conversations with the AI.
diff --git a/docs/cli/configuration.md b/docs/cli/configuration.md
new file mode 100644
index 00000000..e3965caa
--- /dev/null
+++ b/docs/cli/configuration.md
@@ -0,0 +1,179 @@
+# Gemini CLI Configuration
+
+The Gemini CLI offers several ways to configure its behavior, from environment variables and command-line arguments to dedicated settings files. This document outlines the different configuration methods and available settings.
+
+## Configuration Layers
+
+Configuration is typically applied in the following order of precedence (lower numbers are overridden by higher numbers):
+
+1.  **Default Values:** Hardcoded defaults within the application.
+2.  **User Settings File:** Global settings for the current user.
+3.  **Project Settings File:** Project-specific settings.
+4.  **Environment Variables:** System-wide or session-specific variables, potentially loaded from `.env` files.
+5.  **Command-line Arguments:** Values passed when launching the CLI.
+
+## 1. Settings Files (`settings.json`)
+
+The Gemini CLI uses `settings.json` files for persistent configuration. There are two main locations for these files:
+
+- **User Settings:**
+  - **Location:** `~/.gemini/settings.json` (where `~` is your home directory).
+  - **Scope:** Applies globally to all Gemini CLI sessions for the current user.
+- **Project Settings:**
+  - **Location:** `.gemini/settings.json` within your project's root directory.
+  - **Scope:** Applies only when running Gemini CLI from that specific project. Project settings override User settings.
+
+### The `.gemini` Directory in Your Project
+
+When you create a `.gemini/settings.json` file for project-specific settings, or when the system needs to store project-specific information (like custom Seatbelt profiles, e.g., `.gemini/sandbox-macos-custom.sb`), this `.gemini` directory is used.
+
+**Purpose:**
+
+- Stores project-specific configuration for the Gemini CLI (in `settings.json`).
+- Can hold other project-specific files related to Gemini CLI's operation, such as custom sandbox profiles.
+
+**Version Control (`.gitignore`):**
+
+- **Generally, it's recommended to add `.gemini/` to your project's `.gitignore` file.**
+  - **Reasoning:** This directory often contains user-specific preferences (like themes) or local sandbox configurations that might not be relevant or applicable to all collaborators on the project. Keeping it out of version control avoids imposing one user's local setup on others.
+- **Exception:** If your team decides that certain project-specific configurations within `.gemini/` (e.g., a carefully crafted `sandbox-macos-custom.sb` profile that _all_ macOS users on the project should use) are essential for consistent project behavior, you might choose to commit specific files within `.gemini/` (e.g., `!.gemini/sandbox-macos-custom.sb`) or the entire directory. However, this should be a deliberate decision by the team.
+- User-specific `settings.json` often contains local paths or preferences that should not be committed.
+
+Always consider the nature of the files within `.gemini/` before deciding to include them in version control. For most common use cases, ignoring the entire directory is the safest approach.
+
+### Available Settings in `settings.json`:
+
+- **`theme`** (string):
+  - Specifies the visual theme for the CLI.
+  - Example: `"theme": "VS2015"`
+  - See the [UI Guide](./ui-guide.md#themes) for available theme names.
+- **`sandbox`** (boolean or string):
+  - Controls whether and how to use sandboxing for tool execution.
+  - `true`: Enable default sandbox (e.g., Docker or Podman if configured, otherwise OS-level like Seatbelt on macOS).
+  - `false`: Disable sandboxing (less secure).
+  - `"docker"` or `"podman"`: Explicitly choose container-based sandboxing.
+  - `<command>`: Specify a custom command for sandboxing.
+  - Example: `"sandbox": true`
+- **`toolDiscoveryCommand`** (string, advanced):
+  - Custom command for tool discovery (if applicable to your setup).
+- **`toolCallCommand`** (string, advanced):
+  - Custom command for executing tool calls (if applicable to your setup).
+- **`mcpServerCommand`** (string, advanced):
+  - Custom command for the MCP (Multi-Context Prompt) server (if applicable).
+
+### Example `settings.json`:
+
+```json
+{
+  "theme": "VS2015",
+  "sandbox": "docker",
+  "toolDiscoveryCommand": "/usr/local/bin/my-custom-tool-discovery --json",
+  "toolCallCommand": "/usr/local/bin/my-custom-tool-executor",
+  "mcpServerCommand": "node /opt/mcp-server/dist/server.js --port 8080"
+}
+```
+
+## 2. Environment Variables & `.env` Files
+
+Environment variables are a common way to configure applications, especially for sensitive information like API keys or for settings that might change between environments.
+
+The CLI automatically loads environment variables from an `.env` file. The loading order is:
+
+1.  `.env` file in the current working directory.
+2.  If not found, it searches upwards in parent directories until it finds an `.env` file or reaches the project root (identified by a `.git` folder) or the home directory.
+3.  If still not found, it looks for `~/.env` (in the user's home directory).
+
+- **`GEMINI_API_KEY`** (Required):
+  - Your API key for the Gemini API.
+  - **Crucial for operation.** The CLI will not function without it.
+  - Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env` file.
+- **`GEMINI_CODE_MODEL`**:
+  - Specifies the default Gemini model to use.
+  - Overrides the hardcoded default, which is currently `gemini-2.5-pro-preview-05-06`.
+  - Example: `export GEMINI_CODE_MODEL="gemini-1.5-flash-latest"`
+- **`GEMINI_CODE_SANDBOX`**:
+  - Alternative to the `sandbox` setting in `settings.json`.
+  - Accepts `true`, `false`, `docker`, `podman`, or a custom command string.
+- **`SEATBELT_PROFILE`** (macOS specific):
+  - Switches the Seatbelt (`sandbox-exec`) profile on macOS.
+  - `minimal`: (Default) Restricts writes to the project folder but allows other operations.
+  - `strict`: Uses a more restrictive profile that declines operations by default.
+  - `<profile_name>`: Uses a custom profile. To define a custom profile, create a file named `sandbox-macos-<profile_name>.sb` in your project's `.gemini/` directory (e.g., `my-project/.gemini/sandbox-macos-custom.sb`).
+- **`DEBUG` or `DEBUG_MODE`** (often used by underlying libraries or the CLI itself):
+  - Set to `true` or `1` to enable verbose debug logging, which can be helpful for troubleshooting.
+
+## 3. Command-Line Arguments
+
+Arguments passed directly when running the CLI can override other configurations for that specific session.
+
+- **`--model <model_name>`** (or **`-m <model_name>`**):
+  - Specifies the Gemini model to use for this session.
+  - Example: `npm start -- --model gemini-1.5-pro-latest`
+- **`--sandbox`** (or **`-s`**):
+  - Enables sandbox mode for this session. The exact behavior might depend on other sandbox configurations (environment variables, settings files).
+- **`--debug_mode`** (or **`-d`**):
+  - Enables debug mode for this session, providing more verbose output.
+- **`--question <your_question>`** (or **`-q <your_question>`**):
+  - Used to pass a question directly to the command, especially when piping input to the CLI.
+- **`--all_files`** (or **`-a`**):
+  - If set, recursively includes all files within the current directory as context for the prompt.
+- **`--help`** (or **`-h`**):
+  - Displays help information about command-line arguments.
+
+## 4. `GEMINI.md` Files (Hierarchical Instructional Context)
+
+While not strictly configuration for the CLI's _behavior_, `GEMINI.md` files are crucial for configuring the _instructional context_ provided to the Gemini model. This allows you to give project-specific instructions, coding style guides, or any relevant background information to the AI.
+
+- **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the Gemini model to be aware of during your interactions.
+
+### Example `GEMINI.md` Content
+
+Here's a conceptual example of what a `GEMINI.md` file at the root of a TypeScript project might contain:
+
+```markdown
+# Project: My Awesome TypeScript Library
+
+## General Instructions:
+
+- When generating new TypeScript code, please follow the existing coding style.
+- Ensure all new functions and classes have JSDoc comments.
+- Prefer functional programming paradigms where appropriate.
+- All code should be compatible with TypeScript 5.0 and Node.js 18+.
+
+## Coding Style:
+
+- Use 2 spaces for indentation.
+- Interface names should be prefixed with `I` (e.g., `IUserService`).
+- Private class members should be prefixed with an underscore (`_`).
+- Always use strict equality (`===` and `!==`).
+
+## Specific Component: `src/api/client.ts`
+
+- This file handles all outbound API requests.
+- When adding new API call functions, ensure they include robust error handling and logging.
+- Use the existing `fetchWithRetry` utility for all GET requests.
+
+## Regarding Dependencies:
+
+- Avoid introducing new external dependencies unless absolutely necessary.
+- If a new dependency is required, please state the reason.
+```
+
+This example demonstrates how you can provide general project context, specific coding conventions, and even notes about particular files or components. The more relevant and precise your `GEMINI.md` files are, the better the AI can assist you.
+
+- **Hierarchical Loading and Precedence:** The CLI loads `GEMINI.md` files from several locations, forming a hierarchy. Content from files lower in this list (more specific) typically overrides or supplements content from files higher up (more general), though the exact concatenation order should be verified with `/showmemory`:
+  1.  **Global `GEMINI.md`:**
+      - Location: `~/.gemini/GEMINI.md` (in your user home directory).
+      - Scope: Provides default instructions for all your projects.
+  2.  **Project Root & Ancestors `GEMINI.md`:**
+      - Location: The CLI searches for `GEMINI.md` in the current working directory and then in each parent directory up to either the project root (identified by a `.git` folder) or your home directory.
+      - Scope: Provides context relevant to the entire project or a significant portion of it.
+  3.  **Sub-directory `GEMINI.md` (Contextual/Local):**
+      - Location: The CLI also scans for `GEMINI.md` files in subdirectories _below_ the current working directory (respecting common ignore patterns like `node_modules`, `.git`, etc.).
+      - Scope: Allows for highly specific instructions relevant to a particular component, module, or sub-section of your project.
+- **Concatenation:** The contents of all found `GEMINI.md` files are concatenated (with separators indicating their origin and path) and provided as part of the system prompt to the Gemini model. You can see the exact combined content and loading order using the `/showmemory` command.
+- **Commands:**
+  - Use `/refreshmemory` to force a re-scan and reload of all `GEMINI.md` files.
+  - Use `/showmemory` to display the combined instructional context currently loaded.
+
+By understanding these configuration layers and the hierarchical nature of `GEMINI.md` files, you can effectively tailor the Gemini CLI and the AI's responses to your specific needs and projects.
diff --git a/docs/cli/index.md b/docs/cli/index.md
new file mode 100644
index 00000000..d5ab6461
--- /dev/null
+++ b/docs/cli/index.md
@@ -0,0 +1,38 @@
+# Gemini CLI
+
+Welcome to the documentation for the Gemini CLI. This section provides an overview of the CLI's features, how to interact with it, and how to customize your experience.
+
+## What is the Gemini CLI?
+
+The Gemini CLI (`packages/cli`) is the primary way users interact with the Gemini AI model and its associated tools directly from their terminal. It offers an interactive Read-Eval-Print Loop (REPL) environment where you can send prompts to Gemini, receive responses, and see the results of any tools Gemini uses to fulfill your requests.
+
+## Core Features
+
+- **Interactive Prompt:** A familiar command-line prompt for entering your queries and commands.
+- **Rich Output Display:**
+  - Formatted Markdown rendering for clear and readable text responses.
+  - Syntax highlighting for code blocks in various languages.
+  - Clear display of tool calls, inputs, and outputs.
+- **Command History:** Easily access and re-run previous commands and prompts.
+- **Suggestions:** (If applicable, describe suggestion features)
+- **Theming:** Customize the look and feel of the CLI to your preference. See the [Theming section in README.md](../../README.md#theming).
+- **Configuration:** Tailor the CLI's behavior through configuration files. See [CLI Configuration](./configuration.md).
+- **Special Commands:** Utilize built-in commands for tasks like managing history, memory, or display. See [Commands](./commands.md).
+
+## Basic Interaction
+
+1.  **Start the CLI:** Run `npm start` from the project root (or execute the installed CLI command directly). Refer to the main [README.md](../../README.md) for setup and running instructions.
+2.  **Enter a Prompt:** Type your question or instruction at the `>` prompt and press Enter.
+    ```
+    > Explain quantum computing in simple terms.
+    ```
+3.  **View Response:** Gemini's response will be displayed in the terminal. If Gemini needs to use a tool (e.g., to read a file you mentioned), you will see messages indicating the tool usage.
+4.  **Continue Conversation:** You can continue the conversation by asking follow-up questions or giving new instructions.
+
+## Navigating this Section
+
+- **[Commands](./commands.md):** A detailed reference for all built-in CLI commands (e.g., `/help`, `/history`, `/theme`).
+- **[UI Guide](./ui-guide.md):** Learn more about the different parts of the CLI's user interface, including themes and display elements.
+- **[Configuration](./configuration.md):** Understand how to configure various aspects of the CLI.
+
+This documentation will help you become proficient in using the Gemini CLI for a wide range of tasks.