RooCodeInc · hannesrudolph · Mar 31, 2025 · Mar 31, 2025 · Mar 31, 2025 · Mar 31, 2025
@@ -2,7 +2,7 @@
 
 ## Documentation Links
 - Do not include .md extensions in documentation links
-- Use relative paths for internal documentation links
-- Example: [link text](basic-usage/how-tools-work) NOT [link text](basic-usage/how-tools-work.md)
+- Use absolute paths starting from the `/docs/` root for internal documentation links
+- Example: [link text](/basic-usage/how-tools-work) NOT [link text](basic-usage/how-tools-work.md) or [link text](../../basic-usage/how-tools-work)
 
 This ensures links work correctly in the built documentation while maintaining clean URLs.
@@ -4,7 +4,7 @@
       "slug": "docs",
       "name": "Documentation Writer",
       "roleDefinition": "You are a technical documentation writer who is a seasoned, straightforward, and technically precise expert who prioritizes clarity and efficiency. With 24 years of coding and documentation writing experience, you have a natural conversational style that values concise, no-nonsense communication. Your approach is authentic and candid, focusing relentlessly on user comprehension without overselling features or using ambiguous language. You avoid fluff, ensuring every sentence provides clear value, practical guidance, or actionable steps. The tone remains professional yet approachable, fostering immediate trust through reliability and transparency. You specialize in writing technical documentation for the Visual Studio Code extension Roo Code, using Docusaurus to structure, format, and publish content efficiently. With deep expertise in Markdown and MDX, you optimize documentation for readability, accessibility, and seamless navigation within a static-site environment built on React. It is important to ensure the content is accessible to readers with varying technical proficiencies, including those who may have learning disabilities such as ADD/ADHD, by maintaining clear structure, logical flow, and avoiding unnecessary complexity.",
-      "customInstructions": "### Custom Instructions\n\n1. **Directness and Clarity**  \n   Begin each documentation entry with the most important information users need, avoiding introductory filler or unnecessary context.\n\n2. **Precision and Brevity**  \n   Favor short, precise explanations and actionable steps. Users should swiftly grasp concepts without requiring additional clarification.\n\n3. **Authentic and Natural Tone**  \n   Write in a conversational style that reflects Roo's straightforward, reliable, and trustworthy personality—avoiding marketing jargon or generic phrases.\n\n4. **Practical Examples**  \n   Include realistic examples aimed at experienced developers. Provide accurate, concise code snippets ready for immediate use, avoiding trivial or clichéd demos.\n\n5. **Consistent Formatting**  \n   Use structured headings, bullet points, and brief paragraphs for easy scanning and comprehension.\n\n6. **Avoid Over-explaining**  \n   Assume a reasonable level of technical competence. Do not elaborate on basic coding concepts unless it’s essential to clarify a unique Roo Code feature.\n\n7. **Proactive Anticipation**  \n   Address likely questions or pitfalls within the relevant sections. Incorporate tips or clarifications to prevent common mistakes.\n\n8. **Minimalism in Wording**  \n   Eliminate unnecessary adjectives, adverbs, or verbose descriptions. Use clear, functional language that reduces cognitive load.\n\n9. **Internal Links**  \n   Always use **relative paths** for internal links, and **omit the `.md` file extension**.  \n   Example:  \n   ```md\n   [Link to Guide](../intro/)\n\n\t10.\t@site Alias\n\t•\tFor code imports or special references that need to resolve from the project root, use the @site alias.\n\t•\tExample:\n\nimport Header from '@site/src/components/Header';\n\n\n\t•\tAvoid @site in Markdown links—use relative paths instead.\n\n\t11.\tCode Examples\nProvide clearly formatted code snippets suitable for copy-pasting. Maintain consistent syntax highlighting, indentation, and structure.\n\t12.\tImages\nInsert an image placeholder where needed. Include a brief description of the image below the placeholder. The final image element should follow this format (folder name may vary):\n\n<img src=\"/img/installing/installing-2.png\" alt=\"VS Code's Install from VSIX dialog\" width=\"600\" />\n\n(with the folder starting at /img/)",
+      "customInstructions": "### Custom Instructions\n\n1. **Directness and Clarity**  \n   Begin each documentation entry with the most important information users need, avoiding introductory filler or unnecessary context.\n\n2. **Precision and Brevity**  \n   Favor short, precise explanations and actionable steps. Users should swiftly grasp concepts without requiring additional clarification.\n\n3. **Authentic and Natural Tone**  \n   Write in a conversational style that reflects Roo's straightforward, reliable, and trustworthy personality—avoiding marketing jargon or generic phrases.\n\n4. **Practical Examples**  \n   Include realistic examples aimed at experienced developers. Provide accurate, concise code snippets ready for immediate use, avoiding trivial or clichéd demos.\n\n5. **Consistent Formatting**  \n   Use structured headings, bullet points, and brief paragraphs for easy scanning and comprehension.\n\n6. **Avoid Over-explaining**  \n   Assume a reasonable level of technical competence. Do not elaborate on basic coding concepts unless it’s essential to clarify a unique Roo Code feature.\n\n7. **Proactive Anticipation**  \n   Address likely questions or pitfalls within the relevant sections. Incorporate tips or clarifications to prevent common mistakes.\n\n8. **Minimalism in Wording**  \n   Eliminate unnecessary adjectives, adverbs, or verbose descriptions. Use clear, functional language that reduces cognitive load.\n\n9. **Internal Links**  \n   Always use **absolute paths starting from the `/docs/` root** for internal links, and **omit the `.md` file extension**.  \n   Example:  \n   ```md\n   [Link to Guide](/intro/)\n\n\t10.\t@site Alias\n\t•\tFor code imports or special references that need to resolve from the project root, use the @site alias.\n\t•\tExample:\n\nimport Header from '@site/src/components/Header';\n\n\n\t•\tAvoid @site in Markdown links—use absolute paths instead.\n\n\t11.\tCode Examples\nProvide clearly formatted code snippets suitable for copy-pasting. Maintain consistent syntax highlighting, indentation, and structure.\n\t12.\tImages\nInsert an image placeholder where needed. Include a brief description of the image below the placeholder. The final image element should follow this format (folder name may vary):\n\n<img src=\"/img/installing/installing-2.png\" alt=\"VS Code's Install from VSIX dialog\" width=\"600\" />\n\n(with the folder starting at /img/)",
       "groups": [
         "read",
         "command",

@@ -50,7 +50,21 @@ Switch profiles in two ways:
    <img src="/img/api-configuration-profiles/api-configuration-profiles-7.png" alt="Profile selection dropdown in Settings" width="550" />
 2. During chat: Access the API Configuration dropdown in the chat interface
 
-   <img src="/img/api-configuration-profiles/api-configuration-profiles-9.png" alt="API Configuration dropdown in chat interface" width="550" />
+   <img src="/img/api-configuration-profiles/api-configuration-profiles-6.png" alt="API Configuration dropdown in chat interface" width="550" />
+### Pinning and Sorting Profiles
+
+The API configuration dropdown now supports pinning your favorite profiles for quicker access:
+
+1. Hover over any profile in the dropdown to reveal the pin icon
+2. Click the pin icon to add the profile to your pinned list
+3. Pinned profiles appear at the top of the dropdown, sorted alphabetically
+4. Unpinned profiles appear below a separator, also sorted alphabetically
+5. You can unpin a profile by clicking the same icon again
+
+<img src="/img/api-configuration-profiles/api-configuration-profiles-4.png" alt="Pinning API configuration profiles" width="550" />
+
+This feature makes it easier to navigate between commonly used profiles, especially when you have many configurations.
+
 
 ### Editing and Deleting Profiles
 

@@ -16,10 +16,25 @@ Clicking the lightbulb, right-clicking and selecting "Roo Code", or using the ke
 
 Roo Code provides the following Code Actions:
 
-*   **Explain Code:** Asks Roo Code to explain the selected code. This is useful for understanding unfamiliar code or for getting a high-level overview of a function or class.
-*   **Fix Code:** Asks Roo Code to fix problems in the selected code. This action is available when there are diagnostics (errors or warnings) on the selected lines. Roo Code will analyze the diagnostics and propose a fix.
-*   **Improve Code:** Asks Roo Code to suggest improvements to the selected code. This can include suggestions for better readability, performance, or adherence to best practices.
-*   **Add to Context:** Adds the selected code to the current Roo Code conversation, allowing you to refer to it in subsequent messages.
+*   **Add to Context:** Quickly adds the selected code to your chat with Roo, including line numbers so Roo knows exactly where the code is from. It's listed first in the menu for easy access. (More details below).
+*   **Explain Code:** Asks Roo Code to explain the selected code.
+*   **Fix Code:** Asks Roo Code to fix problems in the selected code (available when diagnostics are present).
+*   **Improve Code:** Asks Roo Code to suggest improvements to the selected code.
+
+### Add to Context Deep Dive
+
+The **Add to Context** action is listed first in the Code Actions menu so you can quickly add code snippets to your conversation. When you use it, Roo Code includes the filename and line numbers along with the code.
+
+This helps Roo understand the exact context of your code within the project, allowing it to provide more relevant and accurate assistance.
+
+**Example Chat Input:**
+
+```
+Can you explain this function?
+@myFile.js:15:25
+```
+
+*(Where `@myFile.js:15:25` represents the code added via "Add to Context")*
 
 Each of these actions can be performed "in a new task" or "in the current task."
 

@@ -10,38 +10,36 @@ Roo Code offers an advanced setting to change how it edits files, using diffs (d
 
 Open Settings by clicking the gear icon <Codicon name="gear" /> → Advanced
 
-<img src="/img/fast-edits/fast-edits.png" alt="Roo Code settings showing Enable editing through diffs, Diff strategy dropdown, and Match precision slider" width="500" />
+
 
 When **Enable editing through diffs** is checked:
 
+    <img src="/img/fast-edits/fast-edits-5.png" alt="Roo Code settings showing Enable editing through diffs" width="500" />
 1.  **Faster File Editing**: Roo modifies files more quickly by applying only the necessary changes.
 2.  **Prevents Truncated Writes**: The system automatically detects and rejects attempts by the AI to write incomplete file content, which can happen with large files or complex instructions. This helps prevent corrupted files.
 
 :::note Disabling Fast Edits
 If you uncheck **Enable editing through diffs**, Roo will revert to writing the entire file content for every edit using the [`write_to_file`](/features/tools/write-to-file) tool, instead of applying targeted changes with [`apply_diff`](/features/tools/apply-diff). This full-write approach is generally slower for modifying existing files and leads to higher token usage.
 :::
 
-## Diff Strategy
-
-This setting determines the method Roo uses to calculate and apply changes:
-
-*   **Multi-block diff** (Default since v3.11): Allows updating multiple, separate code blocks within the same file in a single operation. More efficient for widespread changes. (Uses `MultiSearchReplaceDiffStrategy` internally).
-*   **Single block**: Applies changes to one code block at a time. Reliable for most common edits. (Uses `SearchReplaceDiffStrategy` internally).
-*   **Unified diff**: A more sophisticated strategy that analyzes the changes and selects the best approach, potentially using different matching techniques. (Uses `NewUnifiedDiffStrategy` internally).
-
-Choose the strategy that best suits the complexity of the edits you typically perform. The experimental options offer potential efficiency gains but may behave differently.
-
 ## Match Precision
 
 This slider controls how closely the code sections identified by the AI must match the actual code in your file before a change is applied.
 
+    <img src="/img/fast-edits/fast-edits-4.png" alt="Roo Code settings showing Enable editing through diffs checkbox and Match precision slider" width="500" />
+
 *   **100% (Default)**: Requires an exact match. This is the safest option, minimizing the risk of incorrect changes.
 *   **Lower Values (80%-99%)**: Allows for "fuzzy" matching. Roo can apply changes even if the code section has minor differences from what the AI expected. This can be useful if the file has been slightly modified, but **increases the risk** of applying changes in the wrong place.
 
 **Use values below 100% with extreme caution.** Lower precision might be necessary occasionally, but always review the proposed changes carefully.
 
 Internally, this setting adjusts a `fuzzyMatchThreshold` used with algorithms like Levenshtein distance to compare code similarity.
 
-## Model Recommendation
 
-The setting description notes that diff-based editing "Works best with the latest Claude 3.7 Sonnet model." This is likely because newer, more capable models can generate the precise diff formats required for this feature more reliably.
+## Experimental Features
+
+Under the "Experimental Features" section, you will find this option:
+
+    <img src="/img/fast-edits/fast-edits-2.png" alt="Roo Code settings showing the Experimental Features section with the experimental unified diff strategy checkbox" width="500" />
+
+*   **Use experimental unified diff strategy**: This checkbox might appear to enable specific variations or optimizations of the `UnifiedDiffStrategy`. Enabling this could potentially reduce retries caused by model errors but might also introduce unexpected behavior or incorrect edits. Enable only if you understand the risks and are prepared to carefully review all changes.
@@ -7,20 +7,31 @@ sidebar_label: Using MCP in Roo Code
 
 Model Context Protocol (MCP) extends Roo Code's capabilities by connecting to external tools and services. This guide covers everything you need to know about using MCP with Roo Code.
 
-> **Note:** All MCP-related settings are global across all workspaces. Any changes you make to MCP configurations will affect all your Roo Code projects.
+## Configuring MCP Servers
 
-## Installing/Editing Your MCP Servers
+MCP server configurations can be managed at two levels:
 
-MCP server configurations are stored in the `cline_mcp_settings.json` file. You can access it by:
+1.  **Global Configuration**: Stored in the `mcp_settings.json` file, accessible via VS Code settings (see below). These settings apply across all your workspaces unless overridden by a project-level configuration.
+2.  **Project-level Configuration**: Defined in a `.roo/mcp.json` file within your project's root directory. This allows you to set up project-specific servers and share configurations with your team by committing the file to version control. Roo Code automatically detects and loads this file if it exists.
 
-1. Click the <Codicon name="server" /> icon in the top navigation of the Roo Code pane
+**Precedence**: If a server name exists in both global and project configurations, the **project-level configuration takes precedence**.
+
+### Editing MCP Settings Files
+
+You can edit both global and project-level MCP configuration files directly from the Roo Code MCP settings view:
+
+1. Click the <Codicon name="server" /> icon in the top navigation of the Roo Code pane.
+
+  <img src="/img/using-mcp-in-roo/using-mcp-in-roo-10.png" alt="MCP Servers interface in Roo Code" width="400" />
 
-  <img src="/img/using-mcp-in-roo/using-mcp-in-roo.png" alt="MCP Servers interface in Roo Code" width="400" />
-2. Click the `Edit MCP Settings` button. This will open `cline_mcp_settings.json`
+2. Scroll to the bottom of the MCP settings view.
+3. Click the appropriate button:
+    *   **`Edit Global MCP`**: Opens the global `mcp_settings.json` file.
+    *   **`Edit Project MCP`**: Opens the project-specific `.roo/mcp.json` file. If this file doesn't exist, Roo Code will create it for you.
 
-  <img src="/img/using-mcp-in-roo/using-mcp-in-roo-1.png" alt="Edit MCP Settings button" width="400" />
+  <img src="/img/using-mcp-in-roo/using-mcp-in-roo-9.png" alt="Edit Global MCP and Edit Project MCP buttons" width="600" />
 
-  The file uses a JSON format with a `mcpServers` object containing named server configurations:
+Both files use a JSON format with a `mcpServers` object containing named server configurations:
 
   ```json
   {
@@ -189,6 +200,6 @@ Example: "Analyze the performance of my API" might use an MCP tool that tests AP
 Common issues and solutions:
 
 * **Server Not Responding:** Check if the server process is running and verify network connectivity
-* **Permission Errors:** Ensure proper API keys and credentials are configured in your `cline_mcp_settings.json`
+* **Permission Errors:** Ensure proper API keys and credentials are configured in your `mcp_settings.json` (for global settings) or `.roo/mcp.json` (for project settings).
 * **Tool Not Available:** Confirm the server is properly implementing the tool and it's not disabled in settings
 * **Slow Performance:** Try adjusting the network timeout value for the specific MCP server