3.14 Part A (#151)

Author: hannesrudolph

docs/features/footgun-prompting.md

@@ -4,7 +4,11 @@ sidebar_label: 'Footgun Prompting'
 
 # Footgun Prompting: Override System Prompts
 
-Footgun Prompting, AKA Overriding System Prompt, allows advanced users to completely replace the default system prompt for a specific Roo Code mode. This provides granular control over the AI's behavior but bypasses built-in safeguards.
+Footgun Prompting (System Prompt Override) lets you replace the default system prompt for a specific Roo Code mode. This offers granular control but bypasses built-in safeguards. Use with caution.
+
+<img src="/img/footgun-prompting/footgun-prompting-1.png" alt="Warning indicator for active system prompt override" width="600" />
+**Warning Indicator:** When a system prompt override is active for the current mode, Roo Code will display a warning icon in the chat input area to remind you that the default behavior has been modified.
+
 
 :::info **footgun** _(noun)_
 
@@ -32,7 +36,7 @@ Footgun Prompting, AKA Overriding System Prompt, allows advanced users to comple
 
 ## Accessing the Feature
 
-You can find the option and instructions within the Roo Code UI:
+Find the option and instructions in the Roo Code UI:
 
 1.  Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar.
 2.  Expand the **"Advanced: Override System Prompt"** section.
@@ -63,7 +67,7 @@ The project is located at: {{workspace}}.
 Please respond in {{language}}.
 ```
 
-Roo Code will substitute these placeholders before sending the prompt to the AI model.
+Roo Code substitutes these placeholders before sending the prompt to the model.
 
 ## Key Considerations & Warnings
 
@@ -73,5 +77,4 @@ Roo Code will substitute these placeholders before sending the prompt to the AI
 - **No File, No Override:** If the `.roo/system-prompt-{mode-slug}` file doesn't exist, Roo Code uses the standard system prompt generation process for that mode.
 - **Blank Files Ignored:** If the override file exists but is empty (blank), it will be ignored and the default system prompt will be used.
 - **Directory Creation:** Roo Code ensures the `.roo` directory exists before attempting to read or create the override file.
-
-Use this feature cautiously. While powerful for customization, incorrect implementation can significantly degrade Roo Code's performance and reliability for the affected mode.
+Use this feature cautiously. Incorrect implementation can significantly degrade Roo Code's performance and reliability for the affected mode.

docs/features/tools/append-to-file.md

@@ -1,19 +1,19 @@
 # apply_diff
 
-The `apply_diff` tool makes precise, surgical changes to files by specifying exactly what content to replace. It uses multiple sophisticated strategies for finding and applying changes while maintaining proper code formatting and structure.
+The `apply_diff` tool makes precise, surgical changes to files by specifying exactly what content to replace. It uses a sophisticated strategy for finding and applying changes while maintaining proper code formatting and structure.
 
 ## Parameters
 
 The tool accepts these parameters:
 
 - `path` (required): The path of the file to modify relative to the current working directory.
 - `diff` (required): The search/replace block defining the changes using a format specific to the active diff strategy.
-- `start_line` (optional): A hint for where the search content begins, used by some strategies.
-- `end_line` (optional): A hint for where the search content ends, used by some strategies.
+- `start_line` (optional): A hint for where the search content begins. _Note: This top-level parameter appears unused by the current main strategy, which relies on `:start_line:` within the diff content._
+- `end_line` (optional): A hint for where the search content ends. _Note: This top-level parameter appears unused by the current main strategy._
 
 ## What It Does
 
-This tool applies targeted changes to existing files using sophisticated strategies to locate and replace content precisely. Unlike simple search and replace, it uses intelligent matching algorithms (including fuzzy matching) that adapt to different content types and file sizes, with fallback mechanisms for complex edits.
+This tool applies targeted changes to existing files using fuzzy matching guided by line number hints to locate and replace content precisely. Unlike simple search and replace, it identifies the exact block for replacement based on the provided content and location hints.
 
 ## When is it used?
 
@@ -24,11 +24,10 @@ This tool applies targeted changes to existing files using sophisticated strateg
 
 ## Key Features
 
-- Uses intelligent fuzzy matching with configurable confidence thresholds (typically 0.8-1.0).
+- Uses fuzzy matching (Levenshtein distance on normalized strings) guided by a `:start_line:` hint, with configurable confidence thresholds (typically 0.8-1.0).
 - Provides context around matches using `BUFFER_LINES` (default 40).
-- Employs an overlapping window approach for searching large files.
-- Preserves code formatting and indentation automatically.
-- Combines overlapping matches for improved confidence scoring.
+- Performs a middle-out search within a configurable context window (`bufferLines`) around the hinted start line.
+- Preserves code formatting and indentation passively by replacing exact blocks.
 - Shows changes in a diff view for user review and editing before applying.
 - Tracks consecutive errors per file (`consecutiveMistakeCountForApplyDiff`) to prevent repeated failures.
 - Validates file access against `.rooignore` rules.
@@ -49,8 +48,8 @@ When the `apply_diff` tool is invoked, it follows this process:
 1.  **Parameter Validation**: Validates required `path` and `diff` parameters.
 2.  **RooIgnore Check**: Validates if the target file path is allowed by `.rooignore` rules.
 3.  **File Analysis**: Loads the target file content.
-4.  **Match Finding**: Uses the selected strategy's algorithms (exact, fuzzy, overlapping windows) to locate the target content, considering confidence thresholds and context (`BUFFER_LINES`).
-5.  **Change Preparation**: Generates the proposed changes, preserving indentation.
+4.  **Match Finding**: Uses a fuzzy matching algorithm (Levenshtein on normalized strings) guided by the `:start_line:` hint within a context window (`BUFFER_LINES`), searching middle-out to locate the target content based on the confidence threshold.
+5.  **Change Preparation**: Generates the proposed changes by replacing the identified block.
 6.  **User Interaction**:
     *   Displays the changes in a diff view.
     *   Allows the user to review and potentially edit the proposed changes.
@@ -59,16 +58,11 @@ When the `apply_diff` tool is invoked, it follows this process:
 8.  **Error Handling**: If errors occur (e.g., match failure, partial application), increments the `consecutiveMistakeCountForApplyDiff` for the file and reports the failure type.
 9. **Feedback**: Returns the result, including any user feedback or error details.
 
-## Diff Strategy
+## Diff Format Requirements
 
-Roo Code uses this strategy for applying diffs:
+The `<diff>` parameter requires a specific format supporting one or more changes in a single request. Each change block requires a line number hint for the original content.
 
-### MultiSearchReplaceDiffStrategy
-
-An enhanced search/replace format supporting multiple changes in one request. Requires line numbers for each search block.
-
-*   **Best for**: Multiple, distinct changes where line numbers are known or can be estimated.
-*   **Requires**: Exact match for the `SEARCH` block content, including whitespace and indentation. Line numbers (`:start_line:`, `:end_line:`) are mandatory. Markers within content must be escaped (`\`).
+*   **Requires**: Exact match for the `SEARCH` block content (within the fuzzy threshold), including whitespace and indentation. The `:start_line:` number hint is mandatory within each block. The `:end_line:` hint is optional (but supported by the parser). Markers like `<<<<<<<` within the file's content must be escaped (`\\`) in the SEARCH block.
 
 Example format for the `<diff>` block:
 
@@ -94,5 +88,4 @@ Example format for the `<diff>` block:
     const defaultTimeout = 5000;
 =======
     const defaultTimeout = 10000; // Increased timeout
->>>>>>> REPLACE
-```
+>>>>>>> REPLACE

docs/features/tools/apply-diff.md

@@ -0,0 +1,104 @@
+# insert_content
+
+The `insert_content` tool adds new lines of content into an existing file without modifying the original content. It's ideal for inserting code blocks, configuration entries, or log lines at specific locations.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `path` (required): The relative path (from the workspace root) of the file to insert content into.
+- `line` (required): The 1-based line number *before* which the content should be inserted. Use `0` to append the content to the end of the file.
+- `content` (required): The text content to insert.
+
+## What It Does
+
+This tool reads the target file, identifies the specified insertion point based on the `line` parameter, and inserts the provided `content` at that location. If `line` is `0`, the content is added to the end. Changes are presented in a diff view for user approval before being saved.
+
+## When is it used?
+
+- When adding new import statements at the beginning of a file.
+- When inserting new functions or methods into existing code.
+- When adding configuration blocks to settings files.
+- When appending log entries or data records.
+- When adding any multi-line text block without altering existing lines.
+
+## Key Features
+
+- **Targeted Insertion**: Adds content precisely at the specified line number or appends to the end.
+- **Preserves Existing Content**: Does not modify or delete original file lines.
+- **Interactive Approval**: Shows proposed insertions in a diff view, requiring explicit user approval.
+- **User Edit Support**: Allows editing the proposed content directly within the diff view before final approval.
+- **Handles Line Numbers**: Correctly interprets the `line` parameter (1-based or 0 for append).
+- **Context Tracking**: Records the file edit operation for context management.
+- **Error Handling**: Checks for missing parameters, invalid line numbers, and file access issues.
+
+## Limitations
+
+- **Insert Only**: Cannot replace or delete existing content. Use `apply_diff` or `search_and_replace` for modifications.
+- **Requires Existing File**: The target file specified by `path` must exist.
+- **Review Overhead**: The mandatory diff view approval adds an interactive step.
+
+## How It Works
+
+When the `insert_content` tool is invoked, it follows this process:
+
+1.  **Parameter Validation**: Checks for required `path`, `line`, and `content`. Validates `line` is a non-negative integer.
+2.  **File Reading**: Reads the content of the target file specified by `path`.
+3.  **Insertion Point Calculation**: Converts the 1-based `line` parameter to a 0-based index for internal processing (`-1` for appending).
+4.  **Content Insertion**: Uses an internal utility (`insertGroups`) to merge the original file lines with the new `content` at the calculated index.
+5.  **Diff View Interaction**:
+    *   Opens the file in the diff view (`cline.diffViewProvider.open`).
+    *   Updates the diff view with the proposed content (`cline.diffViewProvider.update`).
+6.  **User Approval**: Presents the change via `askApproval`. Reverts if rejected.
+7.  **Saving Changes**: If approved, saves the changes using `cline.diffViewProvider.saveChanges`.
+8.  **File Context Tracking**: Tracks the edit using `cline.getFileContextTracker().trackFileContext`.
+9.  **Handling User Edits**: If the user edited the content in the diff view, reports the final merged content back.
+10. **Result Reporting**: Reports success (including user edits) or failure back to the AI model.
+
+## Usage Examples
+
+Inserting import statements at the beginning of a file (`line: 1`):
+
+```xml
+<insert_content>
+<path>src/utils.ts</path>
+<line>1</line>
+<content>
+// Add imports at start of file
+import { sum } from './math';
+import { parse } from 'date-fns';
+</content>
+</insert_content>
+```
+
+Appending content to the end of a file (`line: 0`):
+
+```xml
+<insert_content>
+<path>config/routes.yaml</path>
+<line>0</line>
+<content>
+- path: /new-feature
+  component: NewFeatureComponent
+  auth_required: true
+</content>
+</insert_content>
+```
+
+Inserting a function before line 50:
+
+```xml
+<insert_content>
+<path>src/services/api.js</path>
+<line>50</line>
+<content>
+async function fetchUserData(userId) {
+  const response = await fetch(`/api/users/${userId}`);
+  if (!response.ok) {
+    throw new Error('Failed to fetch user data');
+  }
+  return response.json();
+}
+</content>
+</insert_content>
+```

docs/features/tools/insert-content.md

@@ -28,15 +28,15 @@ This tool lists all files and directories in a specified location, providing a c
 - Intelligently ignores common large directories like `node_modules` and `.git` in recursive mode
 - Respects `.gitignore` rules when in recursive mode
 - Marks files ignored by `.rooignore` with a lock symbol (🔒) when `showRooIgnoredFiles` is enabled
-- Optimizes performance with level-by-level directory traversal
+- Optimizes file listing performance by leveraging the `ripgrep` tool.
 - Sorts results to show directories before their contents, maintaining a logical hierarchy
 - Presents results in a clean, organized format
 - Automatically creates a mental map of your project structure
 
 ## Limitations
 
 - File listing is capped at about 200 files by default to prevent performance issues
-- Has a 10-second timeout for directory traversal to prevent hanging on complex directory structures
+- The underlying `ripgrep` file listing process has a 10-second timeout; if exceeded, partial results may be returned.
 - When the file limit is hit, it adds a note suggesting to use `list_files` on specific subdirectories
 - Not designed for confirming the existence of files you've just created
 - May have reduced performance in very large directory structures
@@ -49,10 +49,10 @@ When the `list_files` tool is invoked, it follows this process:
 1. **Parameter Validation**: Validates the required `path` parameter and optional `recursive` parameter
 2. **Path Resolution**: Resolves the relative path to an absolute path
 3. **Security Checks**: Prevents listing files in sensitive locations like root or home directories
-4. **Directory Scanning**:
-   - For non-recursive mode: Lists only the top-level contents
-   - For recursive mode: Traverses the directory structure level by level with a 10-second timeout
-   - If timeout occurs, returns partial results collected up to that point
+4. **Directory/File Scanning**:
+   - Uses the `ripgrep` tool to efficiently list files, applying a 10-second timeout.
+   - Uses Node.js `fs` module to list directories.
+   - Applies different filtering logic for recursive vs. non-recursive modes.
 5. **Result Filtering**:
    - In recursive mode, skips common large directories like `node_modules`, `.git`, etc.
    - Respects `.gitignore` rules when in recursive mode