feat: update Marketplace documentation and add new images for enhanced user guidance

Author: hannesrudolph

docs/features/marketplace.mdx

@@ -10,23 +10,19 @@ import Codicon from '@site/src/components/Codicon';
 
 ## Overview
 
-The Roo Code Marketplace is a central hub for discovering and installing community-contributed extensions, known as Modes and MCPs (Model Context Protocol). It allows you to easily extend the functionality of Roo Code to fit your specific needs and workflows.
+The Roo Code Marketplace is a central hub for discovering and installing community-contributed extensions, known as MCPs (Model Context Protocol) and Modes. It allows you to easily extend the functionality of Roo Code to fit your specific needs and workflows.
 
 ### Key Features
-- **Discoverability**: Browse a curated list of Modes and MCPs.
+- **Discoverability**: Browse a curated list of MCPs and Modes.
 - **Simple Installation**: Install and remove items with a single click.
 - **Community-Driven**: Access a growing collection of extensions from the Roo Code community.
 - **Project & Global Scopes**: Install items for a specific project or for all your projects.
 
-### Target Audiences
-- **End Users**: Anyone using Roo Code who wants to customize their experience with new Modes or connect to new AI models and tools via MCPs.
-- **Developers**: Developers who want to share their own Modes and MCPs with the community.
-
 ---
 
 ## Getting Started
 
-The Roo Code Marketplace is available directly within the Roo Code extension in VS Code. You can access it from the Roo Code sidebar.
+The Roo Code Marketplace is available directly within the Roo Code extension in VS Code. Access it by clicking the marketplace icon <Codicon name="extensions" /> in the top menu bar.
 
 :::warning Experimental Feature
 The Marketplace is an experimental feature and must be enabled in settings.
@@ -44,11 +40,15 @@ See the main [Experimental Features](/features/experimental/experimental-feature
 
 The marketplace offers two types of items:
 
+### MCPs (Model Context Protocol)
+MCPs allow Roo Code to connect to and interact with various AI models, APIs, and other external tools. By installing an MCP, you can configure Roo Code to use different language models (like those from OpenAI, Anthropic, or others) or to integrate with other services. Learn more about [What is MCP?](/features/mcp/what-is-mcp) and [how to use MCP in Roo Code](/features/mcp/using-mcp-in-roo).
+
+<img src="/img/marketplace/marketplace-1.png" alt="MCP tab showing available MCPs with install and remove buttons" width="500" />
+
 ### Modes
-Modes are custom sets of instructions and rules that tailor Roo Code's behavior for specific tasks. For example, you might find a "React Component" mode that is optimized for creating React components, or a "Documentation Writer" mode for writing technical documentation.
+Modes are custom sets of instructions and rules that tailor Roo Code's behavior for specific tasks. For example, you might find a "React Component" mode that is optimized for creating React components, or a "Documentation Writer" mode for writing technical documentation. Learn more about [using modes](/basic-usage/using-modes) and [creating custom modes](/features/custom-modes).
 
-### MCPs (Model Context Protocol)
-MCPs allow Roo Code to connect to and interact with various AI models, APIs, and other external tools. By installing an MCP, you can configure Roo Code to use different language models (like those from OpenAI, Anthropic, or others) or to integrate with other services.
+<img src="/img/marketplace/marketplace-4.png" alt="Modes tab showing available modes" width="500" />
 
 ---
 
@@ -59,54 +59,98 @@ When you install an item from the marketplace, you can choose to install it at t
 ### Project Installation
 - **Scope**: The item is only available within the current VS Code workspace (your project).
 - **Configuration File**:
-    - **Modes**: `.roomodes` in the root of your project.
-    - **MCPs**: `.roo/mcp.json` in the root of your project.
+    - **MCPs**: [`.roo/mcp.json`](/features/mcp/using-mcp-in-roo#configuring-mcp-servers) in the root of your project.
+    - **Modes**: [`.roomodes`](/features/custom-modes#manual-configuration-yaml--json) in the root of your project.
 - **Use Case**: This is useful when an item is specific to a particular project's needs or when you want to share a project-specific configuration with your team.
 
 ### Global Installation
 - **Scope**: The item is available across all your VS Code workspaces.
 - **Configuration File**:
-    - **Modes**: `custom-modes.yaml` in the Roo Code extension's global settings directory.
-    - **MCPs**: `mcp-settings.json` in the Roo Code extension's global settings directory.
+    - **MCPs**: [`mcp_settings.json`](/features/mcp/using-mcp-in-roo#configuring-mcp-servers) in the Roo Code extension's global settings directory.
+    - **Modes**: [`custom_modes.yaml`](/features/custom-modes#manual-configuration-yaml--json) in the Roo Code extension's global settings directory.
 - **Use Case**: This is ideal for items that you want to use in all your projects, such as a favorite Mode or a commonly used MCP.
 
 ---
 
 ## Using the Marketplace
 
 ### Browsing and Filtering
-You can browse all available items in the marketplace view. To find specific items, you can:
+
+You can browse all available items in the marketplace view. To find specific items:
 - **Search**: Use the search bar to find items by name or description.
-- **Filter by Type**: Filter to show only Modes or only MCPs.
-- **Filter by Tags**: Filter by tags to find items related to specific technologies or tasks.
+- **Filter by Type**: Show only MCPs or only Modes.
+- **Filter by Tags**: Find items related to specific technologies or tasks.
 
 ### Installing an Item
+
 1. Find the item you want to install.
 2. Click the "Install" button.
-3. If prompted, choose whether to install it for the current **Project** or **Globally**.
-4. For some MCPs, you may be asked to provide additional parameters (see [Parameterized MCPs](#parameterized-mcps)).
-5. Roo Code will automatically add the item to the appropriate configuration file and notify you upon successful installation. The configuration file will be opened for your review.
+3. Choose whether to install it for the current **Project** or **Globally**.
+
+#### Installing MCPs
+<img src="/img/marketplace/marketplace-3.png" alt="MCP installation modal showing installation scope and method options" width="500" />
+
+For MCPs, you may also need to:
+- Select an installation method (NPX or Docker)
+- Provide additional parameters when prompted (see [Parameterized MCPs](#parameterized-mcps))
+
+#### Installing Modes
+<img src="/img/marketplace/marketplace-5.png" alt="Mode installation modal showing installation scope options" width="500" />
+
+For Modes, simply select the installation scope and click Install.
+
+5. Roo Code automatically adds the item to the appropriate configuration file. If the file doesn't exist, Roo Code will create it for you. The file is then opened for your review.
 
 ### Removing an Item
-1. Find the installed item in the marketplace view.
-2. Click the "Uninstall" button.
-3. Roo Code will remove the item from the corresponding configuration file.
+
+1. Find the installed item in the marketplace view (installed items show a "Remove" button).
+2. Click the "Remove" button.
+
+<img src="/img/marketplace/marketplace-2.png" alt="Remove button dropdown showing removal options" width="500" />
+
+3. Choose to remove from the current project or remove globally.
+4. Roo Code removes the item from the corresponding configuration file.
+
+**Note:** The "Remove" button is context-aware. If an item is installed in only one scope (e.g., just for the project), it will be a single-action button. The dropdown menu with "Remove from Project" and "Remove Globally" options only appears if the item is installed in both scopes.
+
+**Important:** The removal is immediate after you click the button or select an option from the dropdown. There is no additional confirmation prompt.
 
 ### Parameterized MCPs
-Some MCPs require you to provide specific information during installation, such as an API key or a URL. These are called "parameterized" MCPs.
 
-When you install a parameterized MCP, you will be prompted to enter the required values. This allows for a more flexible and secure way to configure MCPs without hardcoding sensitive information.
+<img src="/img/marketplace/marketplace-6.png" alt="Parameterized MCP installation showing API key input and prerequisites" width="500" />
+
+Some MCPs require specific information during installation, such as API keys or URLs. When installing these "parameterized" MCPs, you'll be prompted to:
+- Review any prerequisites (like creating accounts or obtaining API keys)
+- Enter required configuration values
+- Select the installation method if applicable
+
+This keeps sensitive information secure and makes configuration more flexible.
 
 ---
 
 ## Troubleshooting
 
 ### Installation Errors
-- **Invalid YAML/JSON**: If you see an error about invalid YAML or JSON, it means the configuration file (`.roomodes`, `.roo/mcp.json`, etc.) has a syntax error. You will need to fix the error in the file before you can install or remove items.
-- **File Not Found**: This error should not typically occur, as Roo Code will create the necessary configuration files if they don't exist.
+- **Invalid YAML/JSON**: The configuration file (`.roomodes`, `.roo/mcp.json`, etc.) has a syntax error. To prevent data loss, Roo Code will not modify a corrupted configuration file. Please fix the syntax error before installing or removing items.
+- **File Not Found**: Rare error - Roo Code automatically creates necessary configuration files.
 
 ### Item Not Working
-If you've installed an item but it doesn't seem to be working:
-- **Check the configuration file**: Ensure the item was added correctly.
-- **Restart VS Code**: Sometimes a restart is necessary to load new configurations.
-- **Check for prerequisites**: Some items may have prerequisites listed in their description.
+If an installed item isn't working:
+1. **Check the configuration file**: Verify the item was added correctly.
+2. **Restart VS Code**: New configurations sometimes require a restart.
+3. **Check prerequisites**: Review the item's description for any requirements.
+4. **Check Roo Code logs**: Look for error messages in the Roo Code output panel.
+
+---
+
+## Related Documentation
+
+### For MCPs
+- [MCP Overview](/features/mcp/overview) - Comprehensive guide to Model Context Protocol
+- [What is MCP?](/features/mcp/what-is-mcp) - Understanding the fundamentals
+- [Using MCP in Roo Code](/features/mcp/using-mcp-in-roo) - Detailed configuration and usage guide
+- [Recommended MCP Servers](/features/mcp/recommended-mcp-servers) - Curated list of tested servers
+
+### For Modes
+- [Using Modes](/basic-usage/using-modes) - Learn about built-in modes and how to switch between them
+- [Custom Modes](/features/custom-modes) - Create and configure your own specialized modes