Getting ready for 4.0 (#390)

Co-authored-by: roomote[bot] <219738659+roomote[bot]@users.noreply.github.com>
Co-authored-by: Bruno Bergher <[email protected]>
Co-authored-by: Bruno Bergher <[email protected]>

Author: 3 people

docs/advanced-usage/available-tools/read-file.md

@@ -74,6 +74,9 @@ This tool reads the content of a specified file and returns it with line numbers
 - Can read specific portions of files by specifying line ranges
 - Extracts readable text from PDF and DOCX files
 - **Image support**: Displays images in multiple formats (PNG, JPG, JPEG, GIF, WebP, SVG, BMP, ICO, TIFF)
+- **Intelligent reading**: Token-budget aware reading that auto-truncates to fit remaining budget instead of failing
+- **Large file preview**: Returns a 100KB preview for very large files to enable quick inspection
+- **Graceful error recovery**: Recovers from stream errors and guides you to use line_range for targeted reads
 - Automatically truncates large text files when no line range is specified, showing the beginning of the file
 - Provides method summaries with line ranges for truncated large code files
 - Efficiently streams only requested line ranges for better performance
@@ -113,12 +116,13 @@ When the `maxConcurrentFileReads` setting is greater than 1, the `read_file` too
 
 ## Limitations
 
-- May not handle extremely large files efficiently without using line range parameters
+- **Large files**: For extremely large files, the tool provides a preview and guides you to use line_range for targeted reading
 - For binary files (except PDF, DOCX, and supported image formats), may return content that isn't human-readable
 - **Multi-file mode**: Requires `maxConcurrentFileReads` > 1 in settings
 - **Image files**: Returns base64-encoded data URLs which may be large for high-resolution images
   - Default max single image size: 20MB
   - Default max total image size: 20MB
+- **Token budget**: Automatically truncates content to fit remaining token budget to prevent context overruns
 
 ---
 
@@ -148,7 +152,14 @@ The tool uses a clear decision hierarchy to determine how to read a file:
    - The implementation efficiently streams only the requested lines, making it suitable for processing large files
    - This takes precedence over all other options
 
-2. **Second Priority: Automatic Truncation for Large Text Files**
+2. **Second Priority: Token Budget Management**
+   - The tool respects the remaining token budget to prevent context overruns
+   - If a file would exceed the remaining budget, it automatically truncates to fit
+   - For very large files (exceeding practical limits), returns a 100KB preview for quick inspection
+   - Provides guidance to use `line_range` for targeted reading of specific sections
+   - Recovers gracefully from stream errors and suggests alternative approaches
+
+3. **Third Priority: Automatic Truncation for Large Text Files**
    - This applies only when **all** of the following conditions are met:
      - Neither `start_line` nor `end_line` is specified.
      - The file is identified as a text-based file (not binary like PDF/DOCX).
@@ -159,7 +170,7 @@ The tool uses a clear decision hierarchy to determine how to read a file:
      - For code files, it may also append a summary of source code definitions found within the truncated portion.
    - **Special Case - Definitions Only Mode**: When `maxReadFileLine` is set to `0`, the tool returns only source code definitions without any file content.
 
-3. **Default Behavior: Read Entire File**
+4. **Default Behavior: Read Entire File**
     - If neither an explicit range is given nor automatic truncation applies (e.g., the file is within the line limit, or it's a supported binary type), the tool reads the entire content.
     - For supported formats like PDF and DOCX, it attempts to extract the full text content.
     - For image formats, it returns a base64-encoded data URL that can be displayed in the chat interface.
@@ -291,6 +302,44 @@ If the file is excluded by rules in a `.rooignore` file:
 <read_file>
 <path>.env</path>
 </read_file>
+### Intelligent Reading with Token Budget Management
+
+When reading large files, the tool automatically manages token budgets to prevent context overruns:
+
+**Scenario:** Reading a very large file without specifying a line range.
+
+**Input:**
+```xml
+<read_file>
+<path>logs/massive-debug.log</path>
+</read_file>
+```
+
+**Simulated Output (for a file exceeding token budget):**
+```
+[First 100KB of file content shown as preview...]
+
+[File exceeds remaining token budget. Showing 100KB preview. Use line_range to read specific sections.]
+```
+
+This intelligent behavior ensures that:
+- Small files read completely with zero overhead
+- Large files auto-truncate to fit remaining token budget
+- Very large files provide a quick preview
+- You receive guidance to use `line_range` for targeted reads
+- Stream errors are recovered gracefully
+
+**Example with line_range for targeted reading:**
+```xml
+<read_file>
+<path>logs/massive-debug.log</path>
+<start_line>1000</start_line>
+<end_line>1100</end_line>
+</read_file>
+```
+
+---
+
 ```
 
 **Simulated Output (Error):**

docs/advanced-usage/available-tools/search-files.md

@@ -26,6 +26,7 @@ The tool accepts these parameters:
 - `path` (required): The path of the directory to search in, relative to the current workspace directory. The search is confined to the workspace.
 - `regex` (required): The regular expression pattern to search for (uses Rust regex syntax)
 - `file_pattern` (optional): Glob pattern to filter files (e.g., '*.ts' for TypeScript files)
+- `respect_gitignore` (optional): Whether to respect `.gitignore` patterns (default: `true`). Set to `false` to search all files including those in `.gitignore`.
 
 ---
 
@@ -47,6 +48,7 @@ This tool searches across files in a specified directory using regular expressio
 ## Key Features
 
 - Searches across multiple files in a single operation using high-performance Ripgrep
+- **Respects .gitignore**: Automatically excludes files and directories listed in `.gitignore` (including nested `.gitignore` files)
 - Shows context around each match (1 line before and after)
 - Filters files by type using glob patterns (e.g., only TypeScript files)
 - Provides line numbers for easy reference
@@ -66,6 +68,7 @@ This tool searches across files in a specified directory using regular expressio
 - Default context size is fixed (1 line before and after)
 - May display varying context sizes when matches are close together due to result grouping
 - For security, searches are strictly limited to the current workspace and cannot access parent directories or other locations on the file system.
+- **Respects .gitignore by default**: Files listed in `.gitignore` are excluded from searches unless explicitly overridden with `respect_gitignore: false`
 
 ---
 
@@ -153,9 +156,47 @@ Finding all usages of a specific function:
 ```
 
 Searching for a specific import pattern across the entire project:
-```
+```xml
 <search_files>
 <path>.</path>
 <regex>import\s+.*\s+from\s+['"]@components/</regex>
 </search_files>
 ```
+## Respecting .gitignore
+
+By default, `search_files` respects `.gitignore` patterns in your workspace, including nested `.gitignore` files. This prevents searches in excluded directories like `node_modules/`, `dist/`, or other ignored paths.
+
+### Default Behavior (Respecting .gitignore)
+
+**Input:**
+```xml
+<search_files>
+<path>.</path>
+<regex>TODO</regex>
+</search_files>
+```
+
+This search will **exclude** files and directories listed in `.gitignore`, ensuring focused results on tracked code.
+
+### Overriding .gitignore (Search All Files)
+
+To search **all files** including those in `.gitignore`, explicitly set `respect_gitignore` to `false`:
+
+**Input:**
+```xml
+<search_files>
+<path>.</path>
+<regex>TODO</regex>
+<respect_gitignore>false</respect_gitignore>
+</search_files>
+```
+
+This searches **everything**, including `node_modules/`, build artifacts, and other ignored paths.
+
+**When to override:**
+- Debugging issues in dependencies or build output
+- Searching through generated code
+- Comprehensive audits that need to check all files
+- Investigating ignored configuration files
+
+---

docs/features/browser-use.mdx

@@ -35,7 +35,7 @@ Roo Code provides sophisticated browser automation capabilities that let you int
 <div style={{ marginTop: '20px' }}></div>
 
 :::caution Model Support Required
-Browser Use within Roo Code requires the use of Claude Sonnet 3.5 or 3.7
+Browser Use within Roo Code requires models that support images. Some models may not navigate pages well. 
 :::
 
 ---
@@ -56,7 +56,7 @@ All of this happens directly within VS Code, with no setup required.
 
 A typical browser interaction follows this pattern:
 
-**Important:** Browser Use requires Claude Sonnet 3.5 or 3.7 model.
+**Important:** Browser Use requires models that support images (vision-capable models).
 
 1. Ask Roo to visit a website
 2. Roo launches the browser and shows you a screenshot

docs/features/checkpoints.mdx

@@ -53,10 +53,21 @@ Checkpoints let you:
 Access checkpoint settings in Roo Code settings under the "Checkpoints" section:
 
 1. Open Settings by clicking the gear icon <Codicon name="gear" /> → Checkpoints
-2. Check or uncheck the "Enable automatic checkpoints" checkbox
+2. Configure checkpoint behavior:
+   - Check or uncheck the "Enable automatic checkpoints" checkbox
+   - Adjust the "Checkpoint initialization timeout" (10-60 seconds, default: 30s)
 
    <img src="/img/checkpoints/checkpoints.png" alt="Checkpoint settings in Roo Code configuration" width="500" />
 
+#### Checkpoint Initialization Timeout
+
+Controls how long the system waits for checkpoint initialization to complete before showing a warning. If your project has many files or is on slower storage, increasing this timeout can prevent premature warnings.
+
+- **Range**: 10-60 seconds
+- **Default**: 30 seconds
+- **When to increase**: Large projects, slow disk I/O, or network-mounted directories
+- **Location**: Settings → Checkpoints → "Checkpoint initialization timeout"
+
 ---
 
 ## How Checkpoints Work
@@ -85,13 +96,13 @@ Checkpoints appear directly in your chat history:
 - **Regular checkpoints** are created before file modifications, allowing easy undo of any changes
    <img src="/img/checkpoints/checkpoints-2.png" alt="Regular checkpoint indicator in chat" width="500" />
 
-Each checkpoint provides two primary functions:
+Each checkpoint provides two primary functions that are always available in both the chat history and checkpoint menu:
 
 ### Viewing Differences
 
 To compare your current workspace with a previous checkpoint:
 
-1. Locate the checkpoint in your chat history
+1. Locate the checkpoint in your chat history or open the checkpoint menu
 2. Click the checkpoint's `View Differences` button
 
    <img src="/img/checkpoints/checkpoints-6.png" alt="View Differences button interface" width="100" />
@@ -107,10 +118,12 @@ To compare your current workspace with a previous checkpoint:
 
 ### Restoring Checkpoints
 
+Restore options are always visible in checkpoint buttons and dialogs, regardless of whether changes are detected. This ensures you can always revert to any checkpoint state.
+
 To restore a project to a previous checkpoint state:
 
-1. Locate the checkpoint in your chat history
-2. Click the checkpoint's `Restore Checkpoint` button
+1. Locate the checkpoint in your chat history or checkpoint menu
+2. Click the checkpoint's `Restore Checkpoint` button (always visible)
    <img src="/img/checkpoints/checkpoints-7.png" alt="Restore checkpoint button interface" width="100" />
 3. Choose one of these restoration options:
 

docs/providers/openrouter.md

@@ -58,6 +58,11 @@ OpenRouter provides an [optional "middle-out" message transform](https://openrou
 *   **Prompt Caching:**
     *   OpenRouter passes caching requests to underlying models that support it. Check the [OpenRouter Models page](https://openrouter.ai/models) to see which models offer caching.
     *   For most models, caching should activate automatically if supported by the model itself (similar to how Requesty works).
+    *   **Models with prompt caching support include:**
+        *   Anthropic Claude Sonnet 3.5, 3.7
+        *   Anthropic Claude Haiku 3.5
+        *   **Anthropic Claude Haiku 4.5** (newly added)
+        *   Google Gemini models (with manual activation - see below)
     *   **Exception for Gemini Models via OpenRouter:** Due to potential response delays sometimes observed with Google's caching mechanism when accessed via OpenRouter, a manual activation step is required *specifically for Gemini models*.
     *   If using a **Gemini model** via OpenRouter, you **must manually check** the "Enable Prompt Caching" box in the provider settings to activate caching for that model. This checkbox serves as a temporary workaround. For non-Gemini models on OpenRouter, this checkbox is not necessary for caching.
 *   **Bring Your Own Key (BYOK):** If you use your own key for the underlying service, OpenRouter charges 5% of what it normally would. Roo Code automatically adjusts the cost calculation to reflect this.

docs/providers/zai.md

@@ -45,10 +45,18 @@ Z AI (Zhipu AI) provides advanced language models with the GLM-4.5 series. The p
 Z AI provides different model catalogs based on your selected region:
 
 ### International Models
+* **GLM-4.6** - Context: 200K tokens
+* **GLM-4.5-X** - Enhanced reasoning and analysis capabilities
+* **GLM-4.5-AirX** - Balanced performance and efficiency
+* **GLM-4.5-Flash** - Optimized for speed with lower latency
 * GLM-4.5 series models
 * GLM-4.5-Air models
 
 ### China Mainland Models
+* **GLM-4.6** - Context: 200K tokens
+* **GLM-4.5-X** - Enhanced reasoning and analysis capabilities
+* **GLM-4.5-AirX** - Balanced performance and efficiency
+* **GLM-4.5-Flash** - Optimized for speed with lower latency
 * GLM-4.5 series models
 * GLM-4.5-Air models
 

docs/roo-code-cloud/analytics.mdx

@@ -0,0 +1,28 @@
+---
+description: Track usage and credits in Roo Code Cloud. View tokens, tasks, estimated cost, and credit consumption over time; learn where to check spend for Cloud Agents.
+keywords:
+  - Roo Code Cloud
+  - analytics
+  - usage
+  - tokens
+  - credits
+  - cost
+image: /img/social-share.jpg
+redirect_from:
+  - /roo-code-cloud/dashboard
+  - /roo-code-cloud/dashboard/
+  - /roo-code-cloud/dashboard#usage-analytics-page
+---
+
+# Analytics
+
+Analytics lets you track tokens, tasks, inference cost, and Cloud Agent credits usage in aggregate or according to a range of filters, defined by you. It's all free.
+
+## Access
+
+- Just go to the [Analytics](https://app.roocode.com/usage) tab
+
+## What's tracked
+
+- For Cloud Agents, all tasks are tracked and considered for analytics
+- For the extension, only tasks you run while logged in get reported for analytics. You can turn off [task sync](/roo-code-cloud/task-sync) so the contents of tasks aren't sent to Cloud, but usage numbers are always reported while you're logged into the extension. That allows you to keep certain tasks away from Cloud while still benefiting from usage analytics.