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

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

5 files changed, 285 insertions, 0 deletions

diff --git a/docs/tools/file-system.md b/docs/tools/file-system.md
new file mode 100644
index 00000000..3c158eb9
--- /dev/null
+++ b/docs/tools/file-system.md
@@ -0,0 +1,125 @@
+# Gemini CLI: File System Tools
+
+The Gemini CLI provides a comprehensive suite of tools for interacting with the local file system. These tools allow the Gemini model to read from, write to, list, search, and modify files and directories, all under your control and typically with confirmation for sensitive operations.
+
+All file system tools operate within a `rootDirectory` (usually the current working directory where you launched the CLI) for security, preventing unintended access to other parts of your system. Paths provided to these tools are generally expected to be absolute or are resolved relative to this root directory.
+
+## 1. `list_directory` (ReadFolder)
+
+- **Tool Name:** `list_directory`
+- **Display Name:** ReadFolder
+- **File:** `ls.ts`
+- **Description:** Lists the names of files and subdirectories directly within a specified directory path. It can optionally ignore entries matching provided glob patterns.
+- **Parameters:**
+  - `path` (string, required): The absolute path to the directory to list.
+  - `ignore` (array of strings, optional): A list of glob patterns to exclude from the listing (e.g., `["*.log", ".git"]`).
+- **Behavior:**
+  - Returns a list of file and directory names.
+  - Indicates whether each entry is a directory.
+  - Sorts entries with directories first, then alphabetically.
+- **Output (`llmContent`):** A string like: `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png`
+- **Confirmation:** No.
+
+## 2. `read_file` (ReadFile)
+
+- **Tool Name:** `read_file`
+- **Display Name:** ReadFile
+- **File:** `read-file.ts`
+- **Description:** Reads and returns the content of a specified file. It can handle large files by allowing reading of specific line ranges and will attempt to detect and skip binary files.
+- **Parameters:**
+  - `path` (string, required): The absolute path to the file to read.
+  - `offset` (number, optional): The 0-based line number to start reading from. Requires `limit` to be set.
+  - `limit` (number, optional): The maximum number of lines to read. If omitted, reads a default maximum (e.g., 2000 lines).
+- **Behavior:**
+  - Returns the content of the specified text file.
+  - If `offset` and `limit` are used, returns only that slice of lines.
+  - Indicates if the content was truncated due to line limits or line length limits.
+  - Attempts to identify binary files (images, executables) and returns a message indicating it's a binary file instead of its content.
+- **Output (`llmContent`):** The file content, potentially prefixed with a truncation message (e.g., `[File truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`). For binary files: `Binary file: /path/to/image.png (image)`.
+- **Confirmation:** No.
+
+## 3. `write_file` (WriteFile)
+
+- **Tool Name:** `write_file`
+- **Display Name:** WriteFile
+- **File:** `write-file.ts`
+- **Description:** Writes content to a specified file. If the file exists, it will be overwritten. If it doesn't exist, it (and any necessary parent directories) will be created.
+- **Parameters:**
+  - `file_path` (string, required): The absolute path to the file to write to.
+  - `content` (string, required): The content to write into the file.
+- **Behavior:**
+  - Writes the provided `content` to the `file_path`.
+  - Creates parent directories if they don't exist.
+- **Output (`llmContent`):** A success message, e.g., `Successfully overwrote file: /path/to/your/file.txt` or `Successfully created and wrote to new file: /path/to/new/file.txt`.
+- **Confirmation:** Yes. Shows a diff of changes and asks for user approval before writing.
+
+## 4. `glob` (FindFiles)
+
+- **Tool Name:** `glob`
+- **Display Name:** FindFiles
+- **File:** `glob.ts`
+- **Description:** Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `*.md`), returning absolute paths sorted by modification time (newest first).
+- **Parameters:**
+  - `pattern` (string, required): The glob pattern to match against (e.g., `"*.py"`, `"src/**/*.js"`).
+  - `path` (string, optional): The absolute path to the directory to search within. If omitted, searches the tool's root directory.
+- **Behavior:**
+  - Searches for files matching the glob pattern within the specified directory.
+  - Returns a list of absolute paths, sorted with the most recently modified files first.
+  - Ignores common nuisance directories like `node_modules` and `.git` by default.
+- **Output (`llmContent`):** A message like: `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...`
+- **Confirmation:** No.
+
+## 5. `search_file_content` (SearchText)
+
+- **Tool Name:** `search_file_content`
+- **Display Name:** SearchText
+- **File:** `grep.ts`
+- **Description:** Searches for a regular expression pattern within the content of files in a specified directory. Can filter files by a glob pattern. Returns the lines containing matches, along with their file paths and line numbers.
+- **Parameters:**
+  - `pattern` (string, required): The regular expression (regex) to search for (e.g., `"function\s+myFunction"`).
+  - `path` (string, optional): The absolute path to the directory to search within. Defaults to the current working directory.
+  - `include` (string, optional): A glob pattern to filter which files are searched (e.g., `"*.js"`, `"src/**/*.{ts,tsx}"`). If omitted, searches most files (respecting common ignores).
+- **Behavior:**
+  - Uses `git grep` if available in a Git repository for speed, otherwise falls back to system `grep` or a JavaScript-based search.
+  - Returns a list of matching lines, each prefixed with its file path (relative to the search directory) and line number.
+- **Output (`llmContent`):** A formatted string of matches, e.g.:
+  ```
+  Found 3 match(es) for pattern "myFunction" in path "." (filter: "*.ts"):
+  ---
+  File: src/utils.ts
+  L15: export function myFunction() {
+  L22:   myFunction.call();
+  ---
+  File: src/index.ts
+  L5: import { myFunction } from './utils';
+  ---
+  ```
+- **Confirmation:** No.
+
+## 6. `replace` (Edit)
+
+- **Tool Name:** `replace`
+- **Display Name:** Edit
+- **File:** `edit.ts`
+- **Description:** Replaces a single, unique occurrence of text within a file. This tool is designed for precise, targeted changes and requires significant context around the `old_string` to ensure it modifies the correct location. It can also be used to create new files if `old_string` is empty and the `file_path` does not exist.
+- **Parameters:**
+  - `file_path` (string, required): The absolute path to the file to modify.
+  - `old_string` (string, required): The exact literal text to replace. **CRITICAL:** This string must uniquely identify the single instance to change. It should include at least 3 lines of context _before_ and _after_ the target text, matching whitespace and indentation precisely. If `old_string` is empty, the tool attempts to create a new file at `file_path` with `new_string` as content.
+  - `new_string` (string, required): The exact literal text to replace `old_string` with.
+- **Behavior:**
+  - If `old_string` is empty and `file_path` does not exist, creates a new file with `new_string` as content.
+  - If `old_string` is provided, it reads the `file_path` and attempts to find exactly one occurrence of `old_string`.
+  - If one occurrence is found, it replaces it with `new_string`.
+  - **Enhanced Reliability:** The tool incorporates a multi-stage edit correction mechanism. If the initial `old_string` provided by the model doesn't perfectly match a unique segment in the file (e.g., it's not found, or matches multiple times), the tool can leverage the Gemini model to attempt to refine `old_string` (and potentially `new_string`). This iterative process aims to identify the correct unique segment for modification, significantly improving the reliability of edits even if the initial context isn't perfectly precise.
+  - **Failure Conditions:** Despite the correction mechanism, the tool will fail if:
+    - `file_path` is not absolute or is outside the root directory.
+    - `old_string` is not empty, but the `file_path` does not exist.
+    - `old_string` is empty, but the `file_path` already exists.
+    - `old_string` is not found in the file.
+    - `old_string` is found multiple times (and self-correction doesn't resolve it to a single match).
+- **Output (`llmContent`):**
+  - On success: `Successfully modified file: /path/to/file.txt (1 replacements).` or `Created new file: /path/to/new_file.txt with provided content.`
+  - On failure: An error message explaining the reason (e.g., `Failed to edit, 0 occurrences found...`, `Failed to edit, expected 1 occurrences but found 2...`).
+- **Confirmation:** Yes. Shows a diff of the proposed changes and asks for user approval before writing to the file.
+
+These file system tools provide a robust foundation for the Gemini CLI to understand and interact with your local project context.
diff --git a/docs/tools/index.md b/docs/tools/index.md
new file mode 100644
index 00000000..f10477bd
--- /dev/null
+++ b/docs/tools/index.md
@@ -0,0 +1,58 @@
+# Gemini CLI Tools: Overview
+
+The Gemini CLI is equipped with a powerful set of built-in tools that the Gemini model can utilize to interact with your local environment, access information, and perform actions. These tools significantly enhance the CLI's capabilities, allowing it to go beyond text generation and assist with a wide range of tasks.
+
+## What are Tools?
+
+In the context of the Gemini CLI, tools are specific functions or modules that the Gemini model can request to be executed. For example, if you ask Gemini to "Summarize the contents of `my_document.txt`," the model will likely identify the need to read that file and will request the execution of the `read_file` tool.
+
+The server component (`packages/server`) manages these tools, presents their definitions (schemas) to the Gemini model, executes them when requested, and returns the results to the model for further processing into a user-facing response.
+
+## Why are Tools Important?
+
+- **Access to Local Information:** Tools allow Gemini to access your local file system, read file contents, list directories, etc.
+- **Execution of Commands:** With tools like `execute_bash_command`, Gemini can run shell commands (with appropriate safety measures and user confirmation).
+- **Interaction with the Web:** Tools can fetch content from URLs.
+- **Action Taking:** Tools can modify files, write new files, or perform other actions on your system (again, typically with safeguards).
+- **Grounding Responses:** By using tools to fetch real-time or specific local data, Gemini's responses can be more accurate, relevant, and grounded in your actual context.
+
+## How Tools are Used
+
+1.  You provide a prompt to the Gemini CLI.
+2.  The CLI sends the prompt to the server.
+3.  The server, along with your prompt and conversation history, sends a list of available tools and their descriptions/schemas to the Gemini API.
+4.  The Gemini model analyzes your request. If it determines that a tool is needed, its response will include a request to execute a specific tool with certain parameters.
+5.  The server receives this tool request, validates it, and (often after user confirmation for sensitive operations) executes the tool.
+6.  The output from the tool is sent back to the Gemini model.
+7.  The Gemini model uses the tool's output to formulate its final answer, which is then sent back through the server to the CLI and displayed to you.
+
+You will typically see messages in the CLI indicating when a tool is being called and whether it succeeded or failed.
+
+## Categories of Built-in Tools
+
+The built-in tools can be broadly categorized as follows:
+
+- **[File System Tools](./file-system.md):** For interacting with files and directories (reading, writing, listing, searching, etc.).
+- **[Shell Tool](./shell.md):** For executing shell commands.
+- **[Web Fetch Tool](./web.md):** For retrieving content from URLs.
+- **[Multi-File Read Tool](./multi-file.md):** A specialized tool for reading content from multiple files or directories, often used by the `@` command.
+
+## Security and Confirmation
+
+Many tools, especially those that can modify your file system or execute commands (`write_file`, `edit`, `execute_bash_command`), are designed with safety in mind. The Gemini CLI will typically:
+
+- **Require Confirmation:** Prompt you before executing potentially sensitive operations, showing you what action is about to be taken.
+- **Utilize Sandboxing:** For tools like `execute_bash_command`, sandboxing mechanisms (configurable via settings) are employed to limit the potential impact of the command.
+
+It's important to always review confirmation prompts carefully before allowing a tool to proceed.
+
+## Detailed Tool Documentation
+
+For detailed information on each specific tool, including its parameters and behavior, please refer to the individual pages in this section:
+
+- **[File System Tools](./file-system.md)**
+- **[Shell Tool (execute_bash_command)](./shell.md)**
+- **[Web Fetch Tool](./web.md)**
+- **[Multi-File Read Tool](./multi-file.md)**
+
+Understanding the available tools and how they work will help you make the most effective use of the Gemini CLI.
diff --git a/docs/tools/multi-file.md b/docs/tools/multi-file.md
new file mode 100644
index 00000000..7eaad714
--- /dev/null
+++ b/docs/tools/multi-file.md
@@ -0,0 +1,36 @@
+# Multi-File Read Tool
+
+This document provides details on the `read_many_files` tool.
+
+## `read_many_files`
+
+- **Purpose:** Reads content from multiple text files specified by paths or glob patterns and concatenates them into a single string. This is useful for getting an overview of a codebase, finding where specific functionality is implemented, reviewing documentation, or gathering context from multiple configuration files.
+- **Arguments:**
+  - `paths` (list[string], required): An array of glob patterns or paths relative to the tool's target directory (e.g., `["src/**/*.ts"]`, `["README.md", "docs/"]`).
+  - `exclude` (list[string], optional): Glob patterns for files/directories to exclude (e.g., `["**/*.log", "temp/"]`). These are added to default excludes if `useDefaultExcludes` is true.
+  - `include` (list[string], optional): Additional glob patterns to include. These are merged with `paths` (e.g., `["*.test.ts"]` to specifically add test files if they were broadly excluded).
+  - `recursive` (boolean, optional): Whether to search recursively. This is primarily controlled by `**` in glob patterns. Defaults to `true`.
+  - `useDefaultExcludes` (boolean, optional): Whether to apply a list of default exclusion patterns (e.g., `node_modules`, `.git`, binary files). Defaults to `true`.
+- **Behavior:**
+  - The tool searches for files matching the provided `paths` and `include` patterns, while respecting `exclude` patterns and default excludes (if enabled).
+  - It reads the content of each matched text file (attempting to skip binary files).
+  - The content of all successfully read files is concatenated into a single string, with a separator `--- {filePath} ---` between the content of each file.
+  - Uses UTF-8 encoding by default.
+- **Examples:**
+  - Reading all TypeScript files in the `src` directory:
+    ```
+    read_many_files(paths=["src/**/*.ts"])
+    ```
+  - Reading the main README and all Markdown files in the `docs` directory, excluding a specific file:
+    ```
+    read_many_files(paths=["README.md", "docs/**/*.md"], exclude=["docs/OLD_README.md"])
+    ```
+  - Reading all JavaScript files but explicitly including test files that might otherwise be excluded by a global pattern:
+    ```
+    read_many_files(paths=["**/*.js"], include=["**/*.test.js"], useDefaultExcludes=False)
+    ```
+- **Important Notes:**
+  - **Binary Files:** This tool is designed for text files and attempts to skip binary files. Its behavior with binary content is not guaranteed.
+  - **Performance:** Reading a very large number of files or very large individual files can be resource-intensive.
+  - **Path Specificity:** Ensure paths and glob patterns are correctly specified relative to the tool's target directory.
+  - **Default Excludes:** Be aware of the default exclusion patterns (like `node_modules`, `.git`) and use `useDefaultExcludes=False` if you need to override them, but do so cautiously.
diff --git a/docs/tools/shell.md b/docs/tools/shell.md
new file mode 100644
index 00000000..6715cfa9
--- /dev/null
+++ b/docs/tools/shell.md
@@ -0,0 +1,40 @@
+# Shell Tool
+
+This document provides details on the shell tool available.
+
+## `execute_bash_command`
+
+- **Purpose:** Executes a given shell command using `bash -c <command>`. This tool is essential for interacting with the underlying operating system, running scripts, or performing command-line operations.
+- **Arguments:**
+  - `command` (string, required): The exact bash command to execute.
+  - `description` (string, optional): A brief description of the command's purpose, which will be shown to the user.
+  - `directory` (string, optional): The directory (relative to the project root) in which to execute the command. If not provided, the command runs in the project root.
+- **Behavior:**
+  - The command is executed as a subprocess.
+  - It can start background processes using `&`.
+  - The tool returns detailed information about the execution, including:
+    - `Command`: The command that was executed.
+    - `Directory`: The directory where the command was run.
+    - `Stdout`: Output from the standard output stream.
+    - `Stderr`: Output from the standard error stream.
+    - `Error`: Any error message reported by the subprocess.
+    - `Exit Code`: The exit code of the command.
+    - `Signal`: The signal number if the command was terminated by a signal.
+    - `Background PIDs`: A list of PIDs for any background processes started.
+- **Examples:**
+  - Listing files in the current directory:
+    ```
+    execute_bash_command(command="ls -la")
+    ```
+  - Running a script in a specific directory:
+    ```
+    execute_bash_command(command="./my_script.sh", directory="scripts", description="Run my custom script")
+    ```
+  - Starting a background server:
+    ```
+    execute_bash_command(command="npm run dev &", description="Start development server in background")
+    ```
+- **Important Notes:**
+  - **Security:** Be cautious when executing commands, especially those constructed from user input, to prevent security vulnerabilities.
+  - **Interactive Commands:** Avoid commands that require interactive user input, as this can cause the tool to hang. Use non-interactive flags if available (e.g., `npm init -y`).
+  - **Error Handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to determine if a command executed successfully.
diff --git a/docs/tools/web.md b/docs/tools/web.md
new file mode 100644
index 00000000..5832fab4
--- /dev/null
+++ b/docs/tools/web.md
@@ -0,0 +1,26 @@
+# Web Fetch Tool
+
+This document describes the `web_fetch` tool.
+
+## `web_fetch`
+
+- **Purpose:** Fetches text content from a given URL. This is useful for retrieving data from web pages, APIs, or other online resources.
+- **Arguments:**
+  - `url` (string, required): The absolute URL to fetch (e.g., `https://example.com/data.txt`).
+- **Behavior:**
+  - The tool attempts to retrieve the content from the specified URL.
+  - It handles potential network errors (e.g., DNS resolution failure, connection timeout) and non-success HTTP status codes (e.g., 404 Not Found, 500 Internal Server Error).
+  - The returned content is expected to be text-based. For binary files, the behavior might be undefined or result in garbled text.
+- **Examples:**
+  - Fetching a plain text file:
+    ```
+    web_fetch(url="https://example.com/robots.txt")
+    ```
+  - Retrieving data from a simple API endpoint:
+    ```
+    web_fetch(url="https://api.example.com/items/123")
+    ```
+- **Important Notes:**
+  - **Content Type:** This tool is primarily designed for text-based content. It may not be suitable for fetching binary files like images or executables.
+  - **Error Handling:** Always check the tool's output for error messages or status indicators to ensure the fetch was successful and the content is as expected.
+  - **Rate Limiting/Authentication:** Be mindful of website terms of service, rate limits, and authentication requirements. This tool does not inherently handle complex authentication mechanisms.