Enhance documentation and update release notes for Roo Code

- Updated custom modes documentation to clarify the use of `.roo/rules-{mode-slug}/` directories for custom instructions, emphasizing the new directory-based method over the older `.roorules-{mode-slug}` files.
- Improved MCP documentation with detailed STDIO and SSE configuration parameters.
- Revised read-file tool documentation to clarify auto-truncation behavior and updated examples for reading large text files.
- Updated update notes for versions 3.11.8, 3.11.9, and 3.11.10, including bug fixes, improvements, and new features.
- Standardized the section titles in various update notes from "Improvements" to "General and QOL Improvements" for consistency.
- Added new images for API configuration profiles.

Author: hannesrudolph

.roomodes

@@ -18,6 +18,18 @@
       "roleDefinition": "**Persona: Roo Code Expert Scriptwriter**\n\n**Background:**\nA professional scriptwriter specializing in creating clear, engaging, and informative scripts tailored specifically for YouTube, Reddit tutorials, and documentation videos focused on Roo Code. With a deep understanding of Roo Code’s functionalities and its practical applications, this expert excels at translating complex coding concepts into straightforward, easy-to-follow explanations.\n\n**Communication Style:**\n- Professional yet friendly, fostering trust and approachability.\n- Concise and structured, using precise language to ensure clarity.\n- Logical flow, breaking down complex topics into manageable steps.\n- Engaging tone, designed to maintain viewer interest throughout the video.\n\n**Specialization:**\n- Roo Code’s features and updates\n- Common troubleshooting techniques\n- Step-by-step tutorials for beginners to advanced users\n- Practical use-cases and real-world examples\n\n**Approach:**\n- Start by clearly stating the objective of the script.\n- Provide concise explanations with relatable analogies when helpful.\n- Anticipate common questions and proactively address them.\n- Conclude with actionable insights or suggested next steps for users.\n\n**Tone and Personality:**\n- Knowledgeable and authoritative without being intimidating.\n- Patient and encouraging, ensuring viewers feel capable and supported.\n- Enthusiastic about Roo Code, making viewers excited about learning and implementing the software.\n\n**Goal:**\nTo empower viewers by making Roo Code accessible and easy to master, enhancing their confidence and competence through expert guidance and clear, compelling content.",
       "groups": [],
       "source": "project"
+    },
+    {
+      "slug": "release-notes-writer",
+      "name": "Release Notes Writer",
+      "roleDefinition": "You are a technical writer specializing in creating and maintaining release notes for the Roo Code VS Code extension, specifically within the `docs/update-notes` directory. Your focus is on accuracy, consistency, and clarity, ensuring users can easily understand recent changes. You adhere strictly to the project's release note standards.",
+      "customInstructions": "**Release Notes (`docs/update-notes`) Standards:**\n\nWhen creating or updating release notes (`.md` files within the `docs/update-notes` directory), adhere to the following standards:\n\n1.  **File Naming:**\n    *   **Patch Releases:** Use the full version number (e.g., `v3.3.1.md`). These files should detail specific bug fixes or minor changes since the last patch or minor release.\n    *   **Minor/Major Releases:** Use the major.minor version number (e.g., `v3.11.md`). These files should summarize all changes included in that version cycle, including features, improvements, and bug fixes from all associated patch releases (e.g., `v3.11.0`, `v3.11.1`, `v3.11.2`, etc.).\n2.  **File Structure (`vX.Y.Z.md` or `vX.Y.md`):**\n    *   **Title:** The H1 title must follow the format: `# Roo Code X.Y.Z Release Notes (YYYY-MM-DD)` or `# Roo Code X.Y Release Notes (YYYY-MM-DD)`. Ensure the date reflects the release date and is always included.\n    *   **Summary Sentence:** Include a brief sentence below the title summarizing the key changes in the release. For minor/major releases, this should cover the scope of the entire version cycle.\n    *   **Section Headings:** Use consistent `##` headings. Recommended headings include:\n        *   `## Highlights` (for major features or changes, especially in minor/major releases)\n        *   `## Bug Fixes`\n        *   `## Improvements` (can include performance, UX, or other enhancements)\n        *   `## Provider Updates` (for changes related to specific integrations like Cloud providers)\n        *   `## Documentation Updates`\n        *   *(Avoid overly generic terms like \"Changes\" or \"Updates\" as section headers)*\n3.  **`index.md` File (Main Index):**\n    *   The main `index.md` file in the `docs/update-notes` directory should list all release versions chronologically (newest first).\n    *   Each entry should link to the corresponding release note file (e.g., `v3.11.md` for the summary page, `v3.3.1.md` for a specific patch). Use absolute paths from `/docs/` and omit the `.md` extension (e.g., `[3.11.8](/update-notes/v3.11.8)`).\n    *   Ensure the date `(YYYY-MM-DD)` is included next to each version link.\n4.  **Contributor Acknowledgments:** If acknowledging contributors for specific changes (e.g., bug fixes), do so consistently. Add `(thanks username!)` at the end of the relevant bullet point, omitting the `@` symbol.\n5.  **Content Style:** Maintain a clear, concise, and informative writing style. Use Markdown formatting correctly (e.g., use backticks `` for code or version numbers). Ensure consistent terminology (e.g., \"release notes\" vs. \"changelog\").\n6.  **Sidebar Update (`sidebars.ts`):**\n    *   When a new **minor release summary page** (e.g., `vX.Y.md`) is created, you **must** update the `sidebars.ts` file.\n    *   Add the Docusaurus ID for the new page (e.g., `'update-notes/vX.Y'`) to the `items` array within the 'Update Notes' category.",
+      "groups": [
+        "read",
+        "command",
+        "edit"
+      ],
+      "source": "project"
     }
   ]
 }

docs/advanced-usage/rate-limits-costs.md

@@ -1,10 +1,10 @@
 # Rate Limits and Costs
 
-Understanding and managing API usage is crucial for a smooth and cost-effective experience with Roo Code. This section explains how to track your token usage, costs, and how to configure rate limits.
+Understanding and managing API usage is crucial for a smooth and cost-effective experience with Roo Code. This section explains how to track your token usage and costs. Rate limits, which default to 0 (disabled) and typically don't need adjustment, are now configured per profile; see the [API Configuration Profiles](/features/api-configuration-profiles#configuring-rate-limits-per-profile) documentation for details on how to set them if needed.
 
 ## Token Usage
 
-Roo Code interacts with AI models using tokens.  Tokens are essentially pieces of words.  The number of tokens used in a request and response affects both the processing time and the cost.
+Roo Code interacts with AI models using tokens. Tokens are essentially pieces of words. The number of tokens used in a request and response affects both the processing time and the cost.
 
 *   **Input Tokens:** These are the tokens in your prompt, including the system prompt, your instructions, and any context provided (e.g., file contents).
 *   **Output Tokens:** These are the tokens generated by the AI model in its response.
@@ -13,38 +13,23 @@ You can see the number of input and output tokens used for each interaction in t
 
 ## Cost Calculation
 
-Most AI providers charge based on the number of tokens used.  Pricing varies depending on the provider and the specific model.
+Most AI providers charge based on the number of tokens used. Pricing varies depending on the provider and the specific model.
 
-Roo Code automatically calculates the estimated cost of each API request based on the configured model's pricing.  This cost is displayed in the chat history, next to the token usage.
+Roo Code automatically calculates the estimated cost of each API request based on the configured model's pricing. This cost is displayed in the chat history, next to the token usage.
 
 **Note:**
 
-*   The cost calculation is an *estimate*.  The actual cost may vary slightly depending on the provider's billing practices.
-*   Some providers may offer free tiers or credits.  Check your provider's documentation for details.
+*   The cost calculation is an *estimate*. The actual cost may vary slightly depending on the provider's billing practices.
+*   Some providers may offer free tiers or credits. Check your provider's documentation for details.
 *   Some providers offer prompt caching which greatly lowers cost.
 
-## Configuring Rate Limits
-
-To prevent accidental overuse of the API and to help you manage costs, Roo Code allows you to set a rate limit.  The rate limit specifies the minimum time (in seconds) between API requests.
-
-**How to configure:**
-
-1.  Open the Roo Code settings (<Codicon name="rocket" /> icon in the top right corner).
-2.  Go to the "Advanced Settings" section.
-3.  Find the "Rate Limit (seconds)" setting.
-4.  Enter the desired delay in seconds.  A value of 0 disables rate limiting.
-
-**Example:**
-
-If you set the rate limit to 10 seconds, Roo Code will wait at least 10 seconds after one API request completes before sending the next one.
-
 ## Tips for Optimizing Token Usage
 
-*   **Be Concise:**  Use clear and concise language in your prompts. Avoid unnecessary words or details.
-*   **Provide Only Relevant Context:** Use context mentions (`@file.ts`, `@folder/`) selectively.  Only include the files that are directly relevant to the task.
+*   **Be Concise:** Use clear and concise language in your prompts. Avoid unnecessary words or details.
+*   **Provide Only Relevant Context:** Use context mentions (`@file.ts`, `@folder/`) selectively. Only include the files that are directly relevant to the task.
 *   **Break Down Tasks:** Divide large tasks into smaller, more focused sub-tasks.
-*   **Use Custom Instructions:**  Provide custom instructions to guide Roo Code's behavior and reduce the need for lengthy explanations in each prompt.
-*   **Choose the Right Model:**  Some models are more cost-effective than others.  Consider using a smaller, faster model for tasks that don't require the full power of a larger model.
+*   **Use Custom Instructions:** Provide custom instructions to guide Roo Code's behavior and reduce the need for lengthy explanations in each prompt.
+*   **Choose the Right Model:** Some models are more cost-effective than others. Consider using a smaller, faster model for tasks that don't require the full power of a larger model.
 *   **Use Modes:** Different modes can access different tools, for example `Architect` can't modify code, which makes it a safe choice when analyzing a complex codebase, without worrying about accidentally allowing expensive operations.
 *   **Disable MCP If Not Used:** If you're not using MCP (Model Context Protocol) features, consider [disabling it in the MCP settings](/features/mcp/using-mcp-in-roo#enabling-or-disabling-mcp-server-creation) to significantly reduce the size of the system prompt and save tokens.
 

docs/features/api-configuration-profiles.md

@@ -14,6 +14,7 @@ Configuration profiles can have their own:
 - [Temperature settings](/features/model-temperature) for controlling response randomness
 - Thinking budgets
 - Provider-specific settings
+- Rate limit settings
 
 Note that available settings vary by provider and model. Each provider offers different configuration options, and even within the same provider, different models may support different parameter ranges or features.
 
@@ -38,10 +39,14 @@ Note that available settings vary by provider and model. Each provider offers di
    - Choose a model
 
       <img src="/img/api-configuration-profiles/api-configuration-profiles-8.png" alt="Model selection interface" width="550" />
-   - Adjust model parameters
-   
-      <img src="/img/api-configuration-profiles/api-configuration-profiles-5.png" alt="Model parameter adjustment controls" width="550" />
+   - Configure the **Rate Limit** for this profile:
+     - **Default is 0 (disabled), which is suitable for most users.** If needed, you can set a minimum time (in seconds) between API requests *for this profile* to help manage costs or avoid provider rate limits.
+     - A value of 0 disables rate limiting (default).
+     - Requests using other profiles follow their own rate limits.
 
+         <img src="/img/api-configuration-profiles/api-configuration-profiles-12.png" alt="Rate limit slider control within API profile settings" width="550" />
+   - Adjust model parameters (like [temperature](/features/model-temperature))
+   
 ### Switching Profiles
 
 Switch profiles in two ways:
@@ -86,5 +91,5 @@ API keys are stored securely in VSCode's Secret Storage and are never exposed in
 - Works with [custom modes](/features/custom-modes) you create
 - Integrates with [local models](/advanced-usage/local-models) for offline work
 - Supports [temperature settings](/features/model-temperature) per mode
-- Enhances cost management with [rate limits and usage tracking](/advanced-usage/rate-limits-costs)
+- Supports per-profile rate limits (configured here) and general [usage tracking/cost info](/advanced-usage/rate-limits-costs)
 

docs/features/custom-instructions.md

@@ -24,9 +24,17 @@ These instructions apply across all workspaces and maintain your preferences reg
 
 These instructions only apply within your current workspace, allowing you to customize Roo Code's behavior for specific projects.
 
-#### Workspace-Wide Instructions
+#### Workspace-Wide Instructions via Files/Directories
 
-Workspace-wide instructions can be defined in a `.roorules` file in your workspace root.
+Workspace-wide instructions apply to all modes within the current project and can be defined using files:
+
+*   **Preferred Method: Directory-Based (`.roo/rules/`)**
+    *   Create a directory named `.roo/rules/` in your workspace root.
+    *   Place instruction files (e.g., `.md`, `.txt`) inside. Roo Code reads files recursively, appending their content to the system prompt in **alphabetical order** based on filename.
+    *   This method takes precedence if the directory exists and contains files.
+*   **Fallback Method: File-Based (`.roorules`)**
+    *   If `.roo/rules/` doesn't exist or is empty, Roo Code looks for a single `.roorules` file in the workspace root.
+    *   If found, its content is loaded.
 
 #### Mode-Specific Instructions
 
@@ -44,9 +52,16 @@ Mode-specific instructions can be set in two independent ways that can be used s
         If the mode itself is global (not workspace-specific), any custom instructions you set for it will also apply globally for that mode across all workspaces.
         :::
 
-2.  **Using Rule Files:** Create a `.roorules-[mode]` file in your workspace root (e.g., `.roorules-code`)
+2.  **Using Rule Files/Directories:** Provide mode-specific instructions via files:
+    *   **Preferred Method: Directory-Based (`.roo/rules-{modeSlug}/`)**
+        *   Create a directory named `.roo/rules-{modeSlug}/` (e.g., `.roo/rules-docs-writer/`) in your workspace root.
+        *   Place instruction files inside (recursive loading). Files are read and appended to the system prompt in **alphabetical order** by filename.
+        *   This method takes precedence over the fallback file method for the specific mode if the directory exists and contains files.
+    *   **Fallback Method: File-Based (`.roorules-{modeSlug}`)**
+        *   If `.roo/rules-{modeSlug}/` doesn't exist or is empty, Roo Code looks for a single `.roorules-{modeSlug}` file (e.g., `.roorules-code`) in the workspace root.
+        *   If found, its content is loaded for that mode.
 
-When both tab instructions and rule files are set for a mode, both sets of instructions will be included in the system prompt.
+Instructions from the Prompts tab, the mode-specific directory/file, and the workspace-wide directory/file are all combined. See the section below for the exact order.
 
 ## How Instructions are Combined
 
@@ -55,19 +70,31 @@ Instructions are placed in the system prompt in this exact format:
 ```
 ====
 USER'S CUSTOM INSTRUCTIONS
+
 The following additional instructions are provided by the user, and should be followed to the best of your ability without interfering with the TOOL USE guidelines.
+
 [Language Preference (if set)]
-[Global Instructions]
-[Mode-specific Instructions]
 
-Rules:
-[.roorules-{mode} rules]
-[.roorules rules]
+[Global Instructions (from Prompts Tab)]
+
+[Mode-specific Instructions (from Prompts Tab for the current mode)]
+
+Mode-Specific Instructions (from Files/Directories):
+[Contents of files in .roo/rules-{modeSlug}/ (if directory exists and is not empty)]
+[Contents of .roorules-{modeSlug} file (if .roo/rules-{modeSlug}/ does not exist or is empty, and file exists)]
+
+Workspace-Wide Instructions (from Files/Directories):
+[Contents of files in .roo/rules/ (if directory exists and is not empty)]
+[Contents of .roorules file (if .roo/rules/ does not exist or is empty, and file exists)]
+
+====
 ```
 
+*Note: The exact order ensures that more specific instructions (mode-level) appear before more general ones (workspace-wide), and directory-based rules take precedence over file-based fallbacks within each level.*
+
 ## Rules about .rules files
 
-* **File Location:** All rule files must be placed in the workspace root directory
+* **File Location:** The preferred method uses directories within `.roo/` (`.roo/rules/` and `.roo/rules-{modeSlug}/`). The fallback method uses single files (`.roorules` and `.roorules-{modeSlug}`) located directly in the workspace root.
 * **Empty Files:** Empty or missing rule files are silently skipped
 * **Source Headers:** Each rule file's contents are included with a header indicating its source
 * **Rule Interaction:** Mode-specific rules complement global rules rather than replacing them
@@ -83,7 +110,7 @@ Rules:
 * "When adding new features to websites, ensure they are responsive and accessible"
 
 :::tip Pro Tip: File-Based Team Standards
-When working in team environments, placing `.roorules` files under version control allows you to standardize Roo's behavior across your entire development team. This ensures consistent code style, documentation practices, and development workflows for everyone on the project.
+When working in team environments, using the `.roo/rules/` directory structure (and potentially `.roo/rules-{modeSlug}/` directories for specific modes) under version control is the recommended way to standardize Roo's behavior across your team. This allows for better organization of multiple instruction files and ensures consistent code style, documentation practices, and development workflows. The older `.roorules` file method can still be used but offers less flexibility.
 :::
 
 ## Combining with Custom Modes