docs: update and reorganize documentation (#806)

8 files changed, 101 insertions, 34 deletions

diff --git a/docs/tools/file-system.md b/docs/tools/file-system.md
index 4a6b3734..585db0f8 100644
--- a/docs/tools/file-system.md
+++ b/docs/tools/file-system.md
@@ -13,6 +13,7 @@ All file system tools operate within a `rootDirectory` (usually the current work
 - **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"]`).
+  - `respect_git_ignore` (boolean, optional): Whether to respect .gitignore patterns when listing files. Defaults to true.
 - **Behavior:**
   - Returns a list of file and directory names.
   - Indicates whether each entry is a directory.
@@ -39,9 +40,24 @@ All file system tools operate within a `rootDirectory` (usually the current work
   - For image/PDF files: An object containing `inlineData` with `mimeType` and base64 `data` (e.g., `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`).
   - For other binary files: A message like `Cannot display content of binary file: /path/to/data.bin`.
 - **Confirmation:** No.
-- **Confirmation:** No.
 
-## 3. `glob` (FindFiles)
+## 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.
+  - **Self-correction:** Before writing, the tool may use the Gemini model to correct the provided content to ensure it is valid and well-formed.
+- **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
@@ -50,6 +66,8 @@ All file system tools operate within a `rootDirectory` (usually the current work
 - **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.
+  - `case_sensitive` (boolean, optional): Whether the search should be case-sensitive. Defaults to false.
+  - `respect_git_ignore` (boolean, optional): Whether to respect .gitignore patterns when finding files. Defaults to true.
 - **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.
@@ -57,7 +75,7 @@ All file system tools operate within a `rootDirectory` (usually the current work
 - **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.
 
-## 4. `search_file_content` (SearchText)
+## 5. `search_file_content` (SearchText)
 
 - **Tool Name:** `search_file_content`
 - **Display Name:** SearchText
@@ -84,16 +102,17 @@ All file system tools operate within a `rootDirectory` (usually the current work
   ```
 - **Confirmation:** No.
 
-## 5. `edit_file` (EditFile)
+## 6. `edit_file` (EditFile)
 
 - **Tool Name:** `edit_file`
 - **Display Name:** EditFile
 - **File:** `edit.ts`
-- **Description:** Modifies files with precise text replacements or creates new files. Supports batch operations for making multiple edits to the same file efficiently. This tool is designed for precise, targeted changes.
+- **Description:** Replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when `expected_replacements` is specified. 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.
-  - `edits` (array, required): Array of edit operations. Each edit contains `old_string` and `new_string`.
-  - `expected_replacements` (number, optional): Number of replacements expected. Defaults to 1 if not specified. Use when you want to replace multiple occurrences.
+  - `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.
+  - `expected_replacements` (number, optional): The number of occurrences to replace. Defaults to 1.
 - **Behavior:**
   - **Modifying existing files**: Replaces exact text matches. File must exist unless the first edit has an empty `old_string` (indicating file creation).
   - **Creating new files**: Use an empty `old_string` in the first edit to create a new file with `new_string` as the content.
diff --git a/docs/tools/index.md b/docs/tools/index.md
index 9e815f08..614dc16a 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -43,7 +43,9 @@ 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.
+- **[Web Fetch Tool](./web-fetch.md):** For retrieving content from URLs.
+- **[Web Search Tool](./web-search.md):** For searching the web.
 - **[Multi-File Read Tool](./multi-file.md):** A specialized tool for reading content from multiple files or directories, often used by the `@` command.
+- **[Memory Tool](./memory.md):** For saving and recalling information across sessions.
 
 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/memory.md b/docs/tools/memory.md
new file mode 100644
index 00000000..b134b948
--- /dev/null
+++ b/docs/tools/memory.md
@@ -0,0 +1,25 @@
+# Memory Tool
+
+This document provides details on the `save_memory` tool.
+
+## `save_memory`
+
+- **Purpose:** Saves a specific piece of information or fact to your long-term memory. This allows the CLI to remember key details across sessions, providing more personalized and effective assistance.
+- **Arguments:**
+  - `fact` (string, required): The specific fact or piece of information to remember. This should be a clear, self-contained statement.
+- **Behavior:**
+  - The tool appends the provided `fact` to a special `GEMINI.md` file located in the user's home directory (`~/.gemini/GEMINI.md`). This file can be configured to have a different name.
+  - The facts are stored under a `## Gemini Added Memories` section.
+  - This file is loaded as context in subsequent sessions, allowing the CLI to recall the saved information.
+- **Examples:**
+  - Remembering a user preference:
+    ```
+    save_memory(fact="My preferred programming language is Python.")
+    ```
+  - Storing a project-specific detail:
+    ```
+    save_memory(fact="The project I'm currently working on is called 'gemini-cli'.")
+    ```
+- **Important Notes:**
+  - This tool should be used for concise, important facts. It is not intended for storing large amounts of data or conversational history.
+  - The memory file is a plain text Markdown file, so you can view and edit it manually if needed.
diff --git a/docs/tools/multi-file.md b/docs/tools/multi-file.md
index 6347a374..9ee66ab7 100644
--- a/docs/tools/multi-file.md
+++ b/docs/tools/multi-file.md
@@ -11,6 +11,7 @@ This document provides details on the `read_many_files` tool.
   - `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, or `["images/*.jpg"]` to include specific image types).
   - `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`, non image/pdf binary files). Defaults to `true`.
+  - `respect_git_ignore` (boolean, optional): Whether to respect .gitignore patterns when finding 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).
   - For text files: it reads the content of each matched file (attempting to skip binary files not explicitly requested as image/PDF) and concatenates it into a single string, with a separator `--- {filePath} ---` between the content of each file. Uses UTF-8 encoding by default.
diff --git a/docs/tools/shell.md b/docs/tools/shell.md
index 5b8e8c9d..3c14c657 100644
--- a/docs/tools/shell.md
+++ b/docs/tools/shell.md
@@ -38,3 +38,4 @@ This document provides details on the shell tool.
   - **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.
+  - **Background Processes:** When a command is run in the background with `&`, the tool will return immediately and the process will continue to run in the background. The `Background PIDs` field will contain the process ID of the background process.
diff --git a/docs/tools/web-fetch.md b/docs/tools/web-fetch.md
new file mode 100644
index 00000000..70dbb70f
--- /dev/null
+++ b/docs/tools/web-fetch.md
@@ -0,0 +1,25 @@
+# Web Fetch Tool
+
+This document describes the `web_fetch` tool.
+
+## `web_fetch`
+
+- **Purpose:** Processes content from one or more URLs (up to 20) embedded in a prompt. This tool is ideal for tasks that require summarizing, comparing, or extracting specific information from web pages.
+- **Arguments:**
+  - `prompt` (string, required): A comprehensive prompt that includes the URL(s) (up to 20) to fetch and specific instructions on how to process their content. For example: `"Summarize https://example.com/article and extract key points from https://another.com/data"`. The prompt must contain at least one URL starting with `http://` or `https://`.
+- **Behavior:**
+  - The tool sends the prompt and the specified URLs to the Gemini API.
+  - The API fetches the content of the URLs, processes it according to the instructions in the prompt, and returns a consolidated response.
+  - The tool formats the response, including source attribution with citations, and returns it to the user.
+- **Examples:**
+  - Summarizing a single article:
+    ```
+    web_fetch(prompt="Can you summarize the main points of https://example.com/news/latest")
+    ```
+  - Comparing two articles:
+    ```
+    web_fetch(prompt="What are the differences in the conclusions of these two papers: https://arxiv.org/abs/2401.0001 and https://arxiv.org/abs/2401.0002?")
+    ```
+- **Important Notes:**
+  - This tool relies on the Gemini API's ability to access and process the given URLs.
+  - The quality of the output depends on the clarity of the instructions in the prompt.
diff --git a/docs/tools/web-search.md b/docs/tools/web-search.md
new file mode 100644
index 00000000..da2e3315
--- /dev/null
+++ b/docs/tools/web-search.md
@@ -0,0 +1,20 @@
+# Google Web Search Tool
+
+This document describes the `google_web_search` tool.
+
+## `google_web_search`
+
+- **Purpose:** Performs a web search using Google Search (via the Gemini API) and returns a summary of the results with sources. This tool is useful for finding up-to-date information on the internet.
+- **Arguments:**
+  - `query` (string, required): The search query.
+- **Behavior:**
+  - The tool sends the query to the Gemini API, which performs a Google Search.
+  - It returns a generated response based on the search results, complete with citations and a list of sources.
+- **Examples:**
+  - Getting information on a topic:
+    ```
+    google_web_search(query="latest advancements in AI-powered code generation")
+    ```
+- **Important Notes:**
+  - The tool returns a processed summary, not a raw list of search results.
+  - The response includes citations to the sources used to generate the summary.
diff --git a/docs/tools/web.md b/docs/tools/web.md
deleted file mode 100644
index 5832fab4..00000000
--- a/docs/tools/web.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# 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.