docs: comprehensive audit and sync with Roo Code v3.47.3 source

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

@@ -0,0 +1,110 @@
+---
+description: Apply unified diff patches to multiple files in a single operation using the apply_patch tool in Roo Code.
+keywords:
+  - apply_patch
+  - patch
+  - unified diff
+  - multi-file edits
+  - file operations
+  - Roo Code tools
+  - diff patches
+---
+
+# apply_patch
+
+The `apply_patch` tool applies unified diff patches to multiple files in a single operation. It supports custom patch headers for adding, deleting, and updating files, making it ideal for complex multi-file refactoring operations.
+
+---
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `patch` (required): A unified diff patch string with custom headers. Supports `*** Add File:`, `*** Delete File:`, and `*** Update File:` headers.
+
+---
+
+## What It Does
+
+This tool processes unified diff patches containing operations for multiple files. It parses the patch content, identifies file operations (add, delete, update), and applies the changes atomically. Unlike [`apply_diff`](/advanced-usage/available-tools/apply-diff) which handles single-file search-and-replace operations, `apply_patch` works with traditional unified diff format.
+
+---
+
+## When is it used?
+
+- When applying patches generated by version control systems or diff tools
+- When performing complex multi-file refactoring with precise line-level changes
+- When migrating code changes from one branch or repository to another
+- When bulk-adding, updating, or removing multiple files in one operation
+- When working with patches from external sources or automated tools
+
+---
+
+## Key Features
+
+- Supports multiple files in a single patch operation
+- Handles file addition, deletion, and modification
+- Uses unified diff format for precise line-level control
+- Custom headers (`*** Add File:`, `*** Delete File:`, `*** Update File:`) for clarity
+- Atomic operations with validation before applying changes
+- Compatible with standard diff/patch tooling output
+
+---
+
+## Limitations
+
+- Requires proper unified diff format syntax
+- Line numbers and context must match existing file content
+- Cannot apply patches with conflicts or mismatched context
+- Less flexible than search-and-replace tools for fuzzy matching
+- Requires exact line-level accuracy in patches
+
+---
+
+## How It Works
+
+When the `apply_patch` tool is invoked, it follows this process:
+
+1. **Patch Parsing**: Parses the patch string to identify custom headers (`*** Add File:`, `*** Delete File:`, `*** Update File:`) and unified diff blocks.
+2. **Operation Identification**: Groups changes by file path and operation type (add, delete, update).
+3. **Validation**: Validates that target files exist (for updates/deletes) or can be created (for adds).
+4. **RooIgnore Check**: Ensures target files are not restricted by `.rooignore` rules.
+5. **User Review**: Presents the patch operations for user review and approval.
+6. **Application**: Applies approved changes to each file sequentially.
+7. **Feedback**: Reports success or failure for each file operation.
+
+---
+
+## Patch Format
+
+The patch format uses custom headers followed by unified diff blocks:
+
+```diff
+*** Add File: src/utils/newHelper.ts
+--- /dev/null
++++ b/src/utils/newHelper.ts
+@@ -0,0 +1,5 @@
++export function helperFunction(value: string): string {
++  return value.toUpperCase();
++}
+
+*** Update File: src/main.ts
+--- a/src/main.ts
++++ b/src/main.ts
+@@ -10,7 +10,7 @@
+ import { config } from './config';
+-const timeout = 5000;
++const timeout = 10000;
+
+ function main() {
+
+*** Delete File: src/deprecated/oldUtil.ts
+```
+
+---
+
+## Relation to Other Tools
+
+- [`apply_diff`](/advanced-usage/available-tools/apply-diff): Use for single-file search-and-replace with fuzzy matching
+- `apply_patch`: Use for multi-file operations with unified diff format
+- [`write_to_file`](/advanced-usage/available-tools/write-to-file): Use for creating entire new files

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

@@ -0,0 +1,88 @@
+---
+description: Replace all occurrences of text in files using the edit_file search-and-replace tool in Roo Code.
+keywords:
+  - edit_file
+  - search and replace
+  - file editing
+  - text replacement
+  - Roo Code tools
+  - code modifications
+---
+
+# 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.
+
+---
+
+## Parameters
+
+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.
+
+---
+
+## 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.
+
+---
+
+## 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 you need to ensure exact match replacement without fuzzy logic
+
+---
+
+## Key Features
+
+- Replaces **all occurrences** by default (global replacement)
+- Exact string matching (no regex or fuzzy matching)
+- Optional validation via `expected_replacements` parameter
+- Shows preview of changes before applying
+- Fails safely if expected replacement count doesn't match actual
+- Preserves file formatting and structure
+
+---
+
+## Limitations
+
+- Requires exact string matches (case-sensitive, whitespace-sensitive)
+- Always replaces all occurrences (cannot target specific instances)
+- 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
+
+---
+
+## How It Works
+
+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`.
+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.
+
+---
+
+## Relation to Other Tools
+
+- `edit_file`: Replaces **all occurrences** (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**
+- [`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.