docs: replace 'modes' documentation with 'using-modes' and update links; add images for better clarity

Author: hannesrudolph

docs/basic-usage/modes.md

@@ -0,0 +1,76 @@
+# Using Modes
+
+Modes in Roo Code are specialized personas that tailor the assistant's behavior to your current task. Each mode offers different capabilities, expertise, and access levels to help you accomplish specific goals.
+
+## Why Use Different Modes?
+
+- **Task specialization:** Get precisely the type of assistance you need for your current task
+- **Safety controls:** Prevent unintended file modifications when focusing on planning or learning
+- **Focused interactions:** Receive responses optimized for your current activity
+- **Workflow optimization:** Seamlessly transition between planning, implementing, debugging, and learning
+
+## Switching Between Modes
+
+Four ways to switch modes:
+
+1. **Dropdown menu:** Click the selector to the left of the chat input
+   
+   <img src="/img/modes/modes.png" alt="Using the dropdown menu to switch modes" width="400" />
+
+2. **Slash command:** Type `/architect`, `/ask`, `/debug`, or `/code` in the chat input
+   
+   <img src="/img/modes/modes-1.png" alt="Using slash commands to switch modes" width="400" />
+
+3. **Toggle command/Keyboard shortcut:** Use the keyboard shortcut below, applicable to your operating system. Each press cycles through the available modes in sequence, wrapping back to the first mode after reaching the end.
+       
+    | Operating System | Shortcut |
+    |------------------|----------|
+    | macOS | ⌘ + . |
+    | Windows | Ctrl + . |
+    | Linux | Ctrl + . |
+
+4. **Accept suggestions:** Click on mode switch suggestions that Roo offers when appropriate
+   
+    <img src="/img/modes/modes-2.png" alt="Accepting a mode switch suggestion from Roo" width="400" />
+
+## Built-in Modes
+
+### Code Mode (Default)
+
+| Aspect | Details |
+|--------|---------|
+| **Description** | A skilled software engineer with expertise in programming languages, design patterns, and best practices |
+| **Tool Access** | Full access to all tool groups: `read`, `edit`, `browser`, `command`, `mcp` |
+| **Ideal For** | Writing code, implementing features, debugging, and general development |
+| **Special Features** | No tool restrictions—full flexibility for all coding tasks |
+
+### Ask Mode
+
+| Aspect | Details |
+|--------|---------|
+| **Description** | A knowledgeable technical assistant focused on answering questions without changing your codebase |
+| **Tool Access** | Limited access: `read`, `browser`, `mcp` only (cannot edit files or run commands) |
+| **Ideal For** | Code explanation, concept exploration, and technical learning |
+| **Special Features** | Optimized for informative responses without modifying your project |
+
+### Architect Mode
+
+| Aspect | Details |
+|--------|---------|
+| **Description** | An experienced technical leader and planner who helps design systems and create implementation plans |
+| **Tool Access** | Access to `read`, `browser`, `mcp`, and restricted `edit` (markdown files only) |
+| **Ideal For** | System design, high-level planning, and architecture discussions |
+| **Special Features** | Follows a structured approach from information gathering to detailed planning |
+
+### Debug Mode
+
+| Aspect | Details |
+|--------|---------|
+| **Description** | An expert problem solver specializing in systematic troubleshooting and diagnostics |
+| **Tool Access** | Full access to all tool groups: `read`, `edit`, `browser`, `command`, `mcp` |
+| **Ideal For** | Tracking down bugs, diagnosing errors, and resolving complex issues |
+| **Special Features** | Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues |
+
+## Custom Modes
+
+Create your own specialized assistants by defining tool access, file permissions, and behavior instructions. Custom modes help enforce team standards or create purpose-specific assistants. See [Custom Modes documentation](../advanced-usage/custom-modes) for setup instructions.

docs/basic-usage/using-modes.md

@@ -85,7 +85,7 @@ Open the Roo Code panel (<Codicon name="rocket" />) and type your task in the ch
 
 ### What are modes in Roo Code?
 
-[Modes](/basic-usage/modes) are different personas that Roo Code can adopt, each with a specific focus and set of capabilities. The built-in modes are:
+[Modes](/basic-usage/using-modes) are different personas that Roo Code can adopt, each with a specific focus and set of capabilities. The built-in modes are:
 
 *   **Code:** For general-purpose coding tasks.
 *   **Architect:** For planning and technical leadership.

docs/faq.md

@@ -24,7 +24,7 @@ Roo Code (formerly Roo Cline) is an AI-powered autonomous coding agent that live
 ## Key Features
 
 ### Multiple Modes
-Roo Code adapts to your needs with specialized [modes](basic-usage/modes):
+Roo Code adapts to your needs with specialized [modes](basic-usage/using-modes):
 - **Code Mode:** For general-purpose coding tasks
 - **Architect Mode:** For planning and technical leadership
 - **Ask Mode:** For answering questions and providing information

docs/index.md

@@ -20,7 +20,7 @@ const sidebars: SidebarsConfig = {
         'basic-usage/typing-your-requests',
         'basic-usage/how-tools-work',
         'basic-usage/context-mentions',
-        'basic-usage/modes',
+        'basic-usage/using-modes',
       ],
     },
     {