fix: docs audit corrections — remove phantom features & fix 15 factual errors (#543)

Author: SannidhyaSah

docs/advanced-usage/available-tools/apply-diff.md

@@ -118,69 +118,3 @@ Example format for the `<diff>` block:
 ```
 
 ---
-
-## Experimental: Multi-File Edits (`MULTI_FILE_APPLY_DIFF`)
-
-An experimental version of `apply_diff` allows for applying changes to multiple files within a single tool call. This feature is activated by the `MULTI_FILE_APPLY_DIFF` experiment flag.
-
-### Key Features of Experimental Mode
-
-- **Multi-File Operations**: Edit multiple files in one request, streamlining complex refactoring tasks.
-- **Batch Approval UI**: When multiple files are targeted, a single UI appears for the user to approve or deny all changes at once, or manage permissions for each file individually.
-- **New XML Format**: Introduces a new, more structured XML format using `<args>` and `<file>` tags to handle multiple operations.
-- **Backward Compatibility**: The experimental tool remains compatible with the legacy single-file `path` and `diff` parameter format.
-
-### How It Works (Experimental)
-
-1.  **Experiment Check**: The tool first checks if the `MULTI_FILE_APPLY_DIFF` experiment is enabled. If not, it falls back to the legacy `apply_diff` implementation.
-2.  **Parameter Parsing**: It parses the new `<args>` XML format to identify all target files and their corresponding diff operations. It can also handle the legacy `path`/`diff` parameters.
-3.  **Validation and Approval**:
-    *   It validates that all target files exist and are accessible (not blocked by `.rooignore`).
-    *   If multiple files are being modified, it presents a **batch approval** dialog to the user.
-4.  **Diff Application**: For each approved file, it applies the specified diffs using the `MultiFileSearchReplaceDiffStrategy`. This strategy can apply multiple, non-overlapping changes to a single file.
-5.  **Results**: It returns a consolidated result message summarizing the outcome for all attempted operations.
-
-### New Diff Format (Experimental)
-
-The experimental mode uses a new XML structure within the `<apply_diff>` tool call.
-
-- **`<args>`**: A container for all file operations.
-- **`<file>`**: A block for each file to be modified. Contains `<path>` and one or more `<diff>` tags.
-- **`<path>`**: The relative path to the file.
-- **`<diff>`**: A block containing the change.
-    - **`<content>`**: The `SEARCH/REPLACE` block.
-    - **`<start_line>`**: (Optional) A line number hint.
-
-**Example: Modifying two files in one call**
-
-```xml
-<apply_diff>
-  <args>
-    <file>
-      <path>src/services/auth.service.ts</path>
-      <diff>
-        <content>
-<<<<<<< SEARCH
-:start_line:50
--------
-    const token_expiration = '15m';
->>>>>>> REPLACE
-        </content>
-      </diff>
-    </file>
-    <file>
-      <path>src/config/auth.config.ts</path>
-      <diff>
-        <content>
-<<<<<<< SEARCH
-:start_line:12
--------
-    rateLimit: 5,
-=======
-    rateLimit: 10,
->>>>>>> REPLACE
-        </content>
-      </diff>
-    </file>
-  </args>
-</apply_diff>

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

@@ -1,5 +1,5 @@
 ---
-description: Replace all occurrences of text in files using the edit_file search-and-replace tool in Roo Code.
+description: Replace a uniquely-identified occurrence of text in files using the edit_file search-and-replace tool in Roo Code.
 keywords:
   - edit_file
   - search and replace
@@ -11,7 +11,7 @@ keywords:
 
 # edit_file
 
-The `edit_file` tool performs search-and-replace operations on files, replacing **all occurrences** of specified text. It provides a straightforward way to make consistent changes across a file when you need to update every instance of a pattern.
+The `edit_file` tool performs targeted search-and-replace operations on files. By default it replaces **exactly one** uniquely-identified occurrence and errors if multiple matches are found. It also supports a special file-creation mode when `old_string` is empty.
 
 ---
 
@@ -20,43 +20,46 @@ The `edit_file` tool performs search-and-replace operations on files, replacing
 The tool accepts these parameters:
 
 - `file_path` (required): The path of the file to modify relative to the current working directory.
-- `old_string` (required): The exact text to search for and replace.
-- `new_string` (required): The text to replace all occurrences with.
-- `expected_replacements` (optional): Expected number of replacements. If specified, the operation fails if the actual count doesn't match.
+- `old_string` (required): The exact text to search for and replace. Pass an empty string (`""`) to create a new file or append to an existing file.
+- `new_string` (required): The replacement text.
+- `expected_replacements` (optional): Expected number of replacements (defaults to 1). The operation fails if the actual count doesn't match. Use this only when intentionally replacing more than one occurrence.
 
 ---
 
 ## What It Does
 
-This tool searches for an exact string in a file and replaces **all occurrences** with new text. The replacement is performed globally across the entire file, making it ideal for consistent updates like renaming variables, updating API endpoints, or fixing repeated patterns.
+This tool searches for an exact string in a file and replaces **exactly one** occurrence with new text. The search string must uniquely identify the target location. If multiple matches are found, the tool returns an error unless `expected_replacements` is explicitly set to match. When `old_string` is empty, the tool creates a new file or appends `new_string` to an existing file.
 
 ---
 
 ## When is it used?
 
-- When renaming variables, functions, or identifiers throughout a file
-- When updating repeated string literals or configuration values
-- When fixing consistent typos or outdated terminology
-- When replacing all instances of a deprecated API or import path
+- When making a targeted change to a specific, uniquely identifiable location in a file
+- When updating a specific string literal or configuration value at a known location
+- When fixing a specific instance of a typo or outdated terminology
+- When replacing a uniquely-identified occurrence of a deprecated API or import path
+- When creating a new file or appending content to an existing file (`old_string=""`)
 - When you need to ensure exact match replacement without fuzzy logic
 
 ---
 
 ## Key Features
 
-- Replaces **all occurrences** by default (global replacement)
+- Replaces **exactly one** uniquely-identified occurrence by default
+- Errors if multiple matches are found (unless `expected_replacements` is explicitly set)
+- `old_string=""` mode: creates a new file or appends content to an existing file
 - Exact string matching (no regex or fuzzy matching)
-- Optional validation via `expected_replacements` parameter
+- Optional `expected_replacements` for intentional multi-occurrence replacements
 - Shows preview of changes before applying
-- Fails safely if expected replacement count doesn't match actual
+- Fails safely if actual replacement count doesn't match `expected_replacements`
 - Preserves file formatting and structure
 
 ---
 
 ## Limitations
 
 - Requires exact string matches (case-sensitive, whitespace-sensitive)
-- Always replaces all occurrences (cannot target specific instances)
+- Errors if the search string matches more than one location (unless `expected_replacements` is set)
 - Cannot use regular expressions or patterns
 - Not suitable for context-dependent replacements
 - Less precise than [`apply_diff`](/advanced-usage/available-tools/apply-diff) for complex edits
@@ -68,10 +71,10 @@ This tool searches for an exact string in a file and replaces **all occurrences*
 When the `edit_file` tool is invoked, it follows this process:
 
 1. **Parameter Validation**: Validates required `file_path`, `old_string`, and `new_string` parameters.
-2. **File Loading**: Reads the target file content.
-3. **Search Operation**: Searches for all occurrences of `old_string` in the file.
-4. **Count Validation**: If `expected_replacements` is specified, validates the actual occurrence count matches.
-5. **Replacement**: Replaces all found occurrences with `new_string`.
+2. **File Creation Mode**: If `old_string` is empty (`""`), creates the file with `new_string` as content (or appends if the file already exists), then stops.
+3. **File Loading**: Reads the target file content.
+4. **Uniqueness Check**: Counts occurrences of `old_string`. If the count doesn't match `expected_replacements` (default: 1), returns an error.
+5. **Replacement**: Replaces the matched occurrence(s) with `new_string`.
 6. **User Review**: Shows a preview of changes for user approval.
 7. **Application**: Applies changes to the file if approved.
 8. **Feedback**: Reports the number of replacements made.
@@ -80,9 +83,9 @@ When the `edit_file` tool is invoked, it follows this process:
 
 ## Relation to Other Tools
 
-- `edit_file`: Replaces **all occurrences** (this tool)
+- `edit_file`: Replaces **exactly one** uniquely-identified occurrence by default; supports `old_string=""` file creation (this tool)
 - [`edit`](/advanced-usage/available-tools/edit): Replaces **first occurrence** only (unless `replace_all: true`)
-- [`search_replace`](/advanced-usage/available-tools/search-replace): Also replaces **all occurrences**
+- [`search_replace`](/advanced-usage/available-tools/search-replace): Also replaces **exactly one** uniquely-identified occurrence
 - [`apply_diff`](/advanced-usage/available-tools/apply-diff): Use for precise, context-aware edits with fuzzy matching
 
-These are different implementations of search-and-replace with varying default behaviors.
+These are different implementations of search-and-replace with varying capabilities.

docs/advanced-usage/available-tools/generate-image.md

@@ -12,7 +12,7 @@ keywords:
 
 # generate_image
 
-The `generate_image` tool creates new images from text prompts or modifies existing images using AI models through the OpenRouter API. This experimental feature enables visual content generation and transformation within your development workflow.
+The `generate_image` tool creates new images from text prompts or modifies existing images using AI models. It supports two providers: **OpenRouter** and the **Roo provider**. This experimental feature enables visual content generation and transformation within your development workflow.
 
 ---
 
@@ -48,14 +48,14 @@ This tool generates images from text descriptions or applies transformations to
 - **Image-to-image transformation**: Edit or transform existing images
 - Supports multiple input formats (PNG, JPG, JPEG, GIF, WEBP)
 - Automatic file extension handling
-- Powered by OpenRouter API for access to various AI models
+- Powered by **OpenRouter** or the **Roo provider** for access to various AI models
 - Experimental feature with ongoing improvements
 
 ---
 
 ## Limitations
 
-- Requires OpenRouter API configuration
+- Requires OpenRouter or Roo provider API configuration
 - Image quality depends on the AI model and prompt quality
 - Generation time varies based on complexity and model
 - Experimental feature: behavior may change in future releases
@@ -72,7 +72,7 @@ When the `generate_image` tool is invoked, it follows this process:
 2. **Mode Selection**:
    - If `image` parameter is provided: operates in **edit mode** (transform existing image)
    - Otherwise: operates in **generation mode** (create new image from prompt)
-3. **API Request**: Sends request to OpenRouter API with prompt and optional input image.
+3. **API Request**: Sends request to the configured provider (OpenRouter or Roo) with prompt and optional input image.
 4. **Image Processing**: Receives generated/edited image from the API.
 5. **File Saving**: Saves the image to the specified `path` with appropriate extension.
 6. **Feedback**: Reports success and the location of the generated image.

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

@@ -28,16 +28,25 @@ The `read_file` tool accepts multiple files via the `args` format. Concurrency a
 
 ## Parameters
 
-The tool accepts parameters in two formats depending on your configuration:
+The tool accepts parameters in two formats:
 
 ### Standard Format (Single File)
 
 - `path` (required): The path of the file to read relative to the current working directory
-- `start_line` (optional): The starting line number to read from (1-based indexing)
-- `end_line` (optional): The ending line number to read to (1-based, inclusive)
-
-:::note Legacy Format
-While the single-file parameters (`path`, `start_line`, `end_line`) are still supported for backward compatibility, we recommend using the newer `args` format for consistency and future compatibility.
+- `mode` (optional): Reading mode — `"slice"` (default) or `"indentation"`
+- `offset` (optional): 1-based line offset to start reading from (slice mode only, default: `1`)
+- `limit` (optional): Maximum number of lines to return (slice mode only, default: `2000`)
+- `indentation` (optional): Indentation-mode options — only used when `mode="indentation"`:
+  - `anchor_line` (required): 1-based line number to anchor the extraction. The tool extracts the complete semantic code block (function, class, method) containing this line.
+  - `max_levels` (optional): Maximum indentation levels to include above the anchor.
+  - `include_siblings` (optional): Whether to include sibling blocks at the same indentation level.
+  - `include_header` (optional): Whether to include file header content (imports, module-level comments) at the top of output.
+  - `max_lines` (optional): Hard cap on lines returned in indentation mode.
+
+:::note Mode Summary
+- **Slice mode** (default): Reads lines sequentially from `offset` up to `limit` lines. Use for initial file exploration or reading a specific line range.
+- **Indentation mode**: Extracts complete, syntactically valid code blocks around `anchor_line` based on indentation hierarchy. Preferred when you have a target line number (e.g., from search results or error messages) and need the entire function/class without mid-function truncation.
+- **`start_line` and `end_line` do not exist** as parameters. Use `offset` and `limit` for range reads in slice mode.
 :::
 
 ### Enhanced Format (Multi-File)
@@ -147,7 +156,7 @@ When the `read_file` tool is invoked, it follows this process:
 The tool uses a clear decision hierarchy to determine how to read a file:
 
 1. **First Priority: Explicit Line Range**
-   - Legacy single‑file format: both `start_line` and `end_line` must be provided for a range read; otherwise it reads normally.
+   - Single‑file format: specify `offset` and `limit` for a range read in slice mode, or use `anchor_line` in indentation mode.
    - Multi‑file `args` format: specify one or more `line_range` entries per file.
    - Range reads stream only the requested lines and bypass `maxReadFileLine`, taking precedence over other options.
 
@@ -160,7 +169,7 @@ The tool uses a clear decision hierarchy to determine how to read a file:
 
 3. **Third Priority: Automatic Truncation for Large Text Files**
    - Applies only when all of the following are true:
-     - Neither `start_line` nor `end_line` is specified.
+     - No `offset`/`limit` range is specified (slice mode) and no `anchor_line` is provided (indentation mode).
      - The file is identified as a text‑based file (not binary like PDF/DOCX/XLSX/IPYNB).
      - The file's total line count exceeds the `maxReadFileLine` setting (configurable; UI default may be 500; backend uses `-1`—no line limit—when unset).
    - When automatic truncation occurs:
@@ -208,14 +217,14 @@ To read the complete content of a file:
 
 ### Reading Specific Lines
 
-To read only a specific range of lines (e.g., 46-68):
+To read only a specific range of lines (e.g., lines 46-68), use `offset` and `limit` in slice mode:
 
 **Input:**
 ```xml
 <read_file>
 <path>src/app.js</path>
-<start_line>46</start_line>
-<end_line>68</end_line>
+<offset>46</offset>
+<limit>23</limit>
 </read_file>
 ```
 
@@ -337,12 +346,12 @@ This behavior ensures that:
 - You receive guidance to use `line_range` for targeted reads
 - Stream errors are handled gracefully
 
-**Example with line_range for targeted reading:**
+**Example with offset/limit for targeted reading:**
 ```xml
 <read_file>
 <path>logs/massive-debug.log</path>
-<start_line>1000</start_line>
-<end_line>1100</end_line>
+<offset>1000</offset>
+<limit>101</limit>
 </read_file>
 ```
 
@@ -639,9 +648,9 @@ This allows Roo to analyze documentation, visual diagrams, configuration, and sp
 ## Troubleshooting
 
 - Range read returns error
-  - Cause: `start_line`/`end_line` invalid or `start_line > end_line`
-  - Fix: Provide both `start_line` and `end_line` as positive integers with `start_line ≤ end_line`; or use `args` with one or more `line_range` entries.
-  - Prevention: Prefer `line_range` in the multi‑file format for targeted reads.
+  - Cause: Invalid `offset` or `limit` values (e.g., non-positive integers).
+  - Fix: Use `offset` (1-based starting line) and `limit` (max lines to return) as positive integers in slice mode; or use `anchor_line` in indentation mode; or use the multi-file `args` format with `line_range` entries.
+  - Prevention: Prefer the multi-file `args` format with `line_range` for targeted reads across multiple files.
 
 - Large file returned a preview
   - Cause: File exceeded token budget or the large‑file tokenization threshold; a preview was returned.