Getting started with pictures (#78)

* Update custom instructions in .roomodes to enhance clarity and add image placeholder guidance

* docs: enhance installation instructions for Roo Code extension

* docs: update connecting API provider instructions and add images for clarity

* docs: enhance 'Your First Task' guide with clearer instructions and new images

* docs: update installation instructions for Roo Code extension to clarify development builds and troubleshooting steps

* Update docs/getting-started/installing.md

Co-authored-by: Matt Rubens <[email protected]>

* Update docs/getting-started/installing.md

Co-authored-by: Matt Rubens <[email protected]>

* docs: add manual installation instructions for VSIX file in installation guide

---------

Co-authored-by: Matt Rubens <[email protected]>

Author: hannesrudolph

.roomodes

@@ -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": "Directness and Clarity: Each documentation entry must begin directly with what users need to know, avoiding introductory filler phrases or unnecessary context.\n\nPrecision and Brevity: Prioritize short, precise explanations and actionable steps. Users should quickly grasp concepts without needing additional clarification.\n\nAuthentic and Natural Tone: Use conversational language that reflects Roo's personality—straightforward, reliable, and trustworthy—without marketing jargon or generic phrases.\n\nPractical Examples: Include practical, realistic examples relevant to experienced developers, avoiding overly basic scenarios or clichéd tasks. Code snippets must be accurate, concise, and ready for immediate use.\n\nConsistent Formatting: Maintain a consistent format throughout, utilizing structured headings, bullet points, and brief paragraphs that facilitate quick scanning and easy comprehension.\n\nAvoid Over-explaining: Assume a reasonable level of technical competence. Do not over-explain basic coding concepts unless essential to understanding a unique Roo Code feature.\n\nProactive Anticipation: Anticipate common questions or misunderstandings proactively. Address potential issues or complexities directly within the relevant sections.\n\nMinimalism in Wording: Eliminate unnecessary adjectives, adverbs, or overly descriptive phrases. Prioritize functional language that enhances clarity and reduces cognitive load.\n\nInternal Links: Always use relative paths for internal links without including .md file extensions.\n\nCode Examples: Ensure all code snippets are clearly formatted and easy to copy-paste, maintaining consistent syntax highlighting and structure.",
+      "customInstructions": "Directness and Clarity: Each documentation entry must begin directly with what users need to know, avoiding introductory filler phrases or unnecessary context.\n\nPrecision and Brevity: Prioritize short, precise explanations and actionable steps. Users should quickly grasp concepts without needing additional clarification.\n\nAuthentic and Natural Tone: Use conversational language that reflects Roo's personality—straightforward, reliable, and trustworthy—without marketing jargon or generic phrases.\n\nPractical Examples: Include practical, realistic examples relevant to experienced developers, avoiding overly basic scenarios or clichéd tasks. Code snippets must be accurate, concise, and ready for immediate use.\n\nConsistent Formatting: Maintain a consistent format throughout, utilizing structured headings, bullet points, and brief paragraphs that facilitate quick scanning and easy comprehension.\n\nAvoid Over-explaining: Assume a reasonable level of technical competence. Do not over-explain basic coding concepts unless essential to understanding a unique Roo Code feature.\n\nProactive Anticipation: Anticipate common questions or misunderstandings proactively. Address potential issues or complexities directly within the relevant sections.\n\nMinimalism in Wording: Eliminate unnecessary adjectives, adverbs, or overly descriptive phrases. Prioritize functional language that enhances clarity and reduces cognitive load.\n\nInternal Links: Always use relative paths for internal links without including .md file extensions.\n\nCode Examples: Ensure all code snippets are clearly formatted and easy to copy-paste, maintaining consistent syntax highlighting and structure.\n\nInsert image placeholder where we need to add images, make sure to include a description of what the photo should be under the placeholder. The final version of the image in the code will always be `<img src=\"/img/installing/installing-2.png\" alt=\"VS Code's Install from VSIX dialog\" width=\"600\" />` and with the folder starting with `/img/`",
       "groups": [
         "read",
         [

docs/getting-started/connecting-api-provider.md

@@ -4,58 +4,73 @@ sidebar_label: Connecting To A Provider
 
 # Connecting Your First AI Provider
 
-To get started, you'll need to connect Roo Code to an AI model provider. We recommend starting with one of these options, which all offer access to Anthropic's powerful **Claude 3.7 Sonnet** model:
+Roo Code requires an API key from an AI model provider to function. We recommend these options for accessing the powerful **Claude 3.7 Sonnet** model:
 
-1.  **OpenRouter (Recommended):** A platform that provides access to multiple AI models, including Claude 3.7 Sonnet. This is often the easiest option for getting started.
-
-2.  **Anthropic:** Direct access to Claude models from Anthropic. Requires applying for API access, and may be rate limited depending on your tier.
-
-Choose one of these options and follow the instructions below to obtain an API key.
+- **OpenRouter (Recommended):** Provides access to multiple AI models through a single API key. Ideal for getting started quickly with minimal setup. [View pricing](https://openrouter.ai/models?order=pricing-low-to-high).
+- **Anthropic:** Direct access to Claude models. Requires API access approval and may have [rate limits depending on your tier](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier). See [Anthropic's pricing page](https://www.anthropic.com/pricing#anthropic-api) for details.
 
 ## Getting Your API Key
 
-### Option 1: Using an LLM router
+### Option 1: LLM Routers
 
-LLM routers allow you to use multiple models via a single provider, simplifying cost and API key management.
+LLM routers let you access multiple AI models with one API key, simplifying cost management and switching between models. They often offer [competitive pricing](https://openrouter.ai/models?order=pricing-low-to-high) compared to direct providers.
 
 #### OpenRouter
 
-1.  **Go to the OpenRouter website:** [https://openrouter.ai/](https://openrouter.ai/)
-2.  **Sign in** with your Google or GitHub account.
-3.  **Get an API Key:** Go to the [keys page](https://openrouter.ai/keys) and create a key.  Copy the key.
+1. Go to [openrouter.ai](https://openrouter.ai/)
+2. Sign in with your Google or GitHub account
+3. Navigate to the [API keys page](https://openrouter.ai/keys) and create a new key
+4. Copy your API key - you'll need this for Roo Code setup
+
+<img src="/img/connecting-api-provider/connecting-api-provider-4.png" alt="OpenRouter API keys page" width="600" />
+
+*OpenRouter dashboard with "Create key" button. Name your key and copy it after creation.*
 
 #### Requesty
 
-1.  **Go to the Requesty website:** [https://requesty.ai/](https://requesty.ai/)
-2.  **Sign in** with your Google or email account
-3.  **Get an API Key:** Go to the [API management page](https://app.requesty.ai/manage-api) and create a key.  **Important:** Copy the key immediately, as you won't be able to see it again.
+1. Go to [requesty.ai](https://requesty.ai/)
+2. Sign in with your Google account or email
+3. Navigate to the [API management page](https://app.requesty.ai/manage-api) and create a new key
+4. **Important:** Copy your API key immediately as it won't be displayed again
+
+<img src="/img/connecting-api-provider/connecting-api-provider-7.png" alt="Requesty API management page" width="600" />
+
+*Requesty API management page with "Create API Key" button. Copy your key immediately - it's shown only once.*
 
-### Option 2: Using an LLM provider directly
+### Option 2: Direct Providers
 
-If you prefer to use a specific LLM provider directly, that is always an option.
+For direct access to specific models from their original providers, with full access to their features and capabilities:
 
 #### Anthropic
 
-1.  **Go to the Anthropic Console:** [https://console.anthropic.com/](https://console.anthropic.com/)
-2.  **Sign up** for an account or log in.
-3.  **Create an API Key:** Go to the API keys page (you may need to navigate through the dashboard) and create a new key.  **Important:** Copy the key immediately, as you won't be able to see it again.
+1. Go to [console.anthropic.com](https://console.anthropic.com/)
+2. Sign up for an account or log in
+3. Navigate to the [API keys section](https://console.anthropic.com/settings/keys) and create a new key
+4. **Important:** Copy your API key immediately as it won't be displayed again
 
-#### OpenAI
+<img src="/img/connecting-api-provider/connecting-api-provider-5.png" alt="Anthropic console API Keys section" width="600" />
 
-1.  **Go to the OpenAI Console:** [https://platform.openai.com/](https://platform.openai.com/)
-2.  **Sign up** for an account or log in.
-3.  **Create an API Key:** Go to the API keys page (you may need to navigate through the dashboard) and create a new key.  **Important:** Copy the key immediately, as you won't be able to see it again.
+*Anthropic console API Keys section with "Create key" button. Name your key, set expiration, and copy it immediately.*
 
-## Configuring Roo Code in VS Code
+#### OpenAI
 
-1.  **Open the Roo Code Sidebar:** Click the Roo Code icon (<Codicon name="rocket" />) in the VS Code Activity Bar.  You should see the welcome screen.
+1. Go to [platform.openai.com](https://platform.openai.com/)
+2. Sign up for an account or log in
+3. Navigate to the [API keys section](https://platform.openai.com/api-keys) and create a new key
+4. **Important:** Copy your API key immediately as it won't be displayed again
 
-2.  **Select your API Provider:** In the "API Provider" dropdown, choose your API provider.
+<img src="/img/connecting-api-provider/connecting-api-provider-6.png" alt="OpenAI API keys page" width="600" />
 
-3.  **Enter your API Key:** Paste your API key into the "API Key" field.
+*OpenAI platform with "Create new secret key" button. Name your key and copy it immediately after creation.*
+
+## Configuring Roo Code in VS Code
 
-4. **Select your Model:**
-    * If you're using **OpenRouter**, select `anthropic/claude-3.7-sonnet`.
-    * If you're using **Anthropic**, select `claude-3-7-sonnet-20250219`.
+Once you have your API key:
 
-5.  **Click "Let's go!":**  Roo Code will save your settings, and you'll be ready to start coding!
+1. Open the Roo Code sidebar by clicking the Roo Code icon (<Codicon name="rocket" />) in the VS Code Activity Bar
+2. In the welcome screen, select your API provider from the dropdown
+3. Paste your API key into the appropriate field
+4. Select your model:
+   - For **OpenRouter**: select `anthropic/claude-3.7-sonnet` ([model details](https://openrouter.ai/anthropic/claude-3.7-sonnet))
+   - For **Anthropic**: select `claude-3-7-sonnet-20250219` ([model details](https://www.anthropic.com/pricing#anthropic-api))
+5. Click "Let's go!" to save your settings and start using Roo Code

docs/getting-started/installing.md

@@ -4,62 +4,89 @@ sidebar_label: Installing Roo Code
 
 # Installing Roo Code
 
-Roo Code is a VS Code extension that brings AI-powered coding assistance to your editor.  There are three main ways to install it:
+Roo Code is a VS Code extension that brings AI-powered coding assistance directly to your editor. Install using one of these methods:
+1. **VS Code Marketplace (Recommended)** - fastest method for standard VS Code and Cursor users
+2. **Open VSX Registry** - for VS Code-compatible editors like VSCodium
 
-1.  **From the VS Code Marketplace (Recommended)**
-2.  **From the Open VSX Registry**
-3.  **From a VSIX file (Advanced)**
+## VS Code Marketplace
 
-## 1. Installation from the VS Code Marketplace
+1. Open VS Code
+2. Access Extensions: Click the Extensions icon in the Activity Bar or press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS)
+3. Search for "Roo Code"
+4. Select "Roo Code" by RooVeterinaryInc and click **Install**
+5. Reload VS Code if prompted
 
-This is the easiest and recommended method for most users.
+After installation, find the Roo Code icon (<Codicon name="rocket" />) in the Activity Bar to open the Roo Code panel.
 
-1.  **Open VS Code.**
-2.  **Open the Extensions View:**
-    *   Click the Extensions icon in the Activity Bar on the side of VS Code.  (It looks like four squares, with one detached.)
-    *   Or, use the keyboard shortcut: `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS).
-3.  **Search for Roo Code:** In the Extensions view search box, type `Roo Code`.
-4.  **Install:** Find "Roo Code" in the search results (by RooVeterinaryInc). Click the **Install** button.
-5.  **Reload (if required):**  VS Code may prompt you to reload.  If so, click the **Reload** button.
+<img src="/img/installing/installing.png" alt="VS Code marketplace with Roo Code extension ready to install" width="400" />
+*VS Code marketplace with Roo Code extension ready to install*
 
-Once installed, you'll see the Roo Code icon (<Codicon name="rocket" />) in the Activity Bar.  Click it to open the Roo Code panel.
+## Open VSX Registry
 
-## 2. Installation from the Open VSX Registry
+For VS Code-compatible editors without Marketplace access (like VSCodium and Windsurf):
 
-If you're using a VS Code-compatible editor that doesn't have access to the VS Code Marketplace (like VSCodium), you can install Roo Code from the Open VSX Registry.
+1. Open your editor
+2. Access the Extensions view
+3. Search for "Roo Code"
+4. Select "Roo Code" by RooVeterinaryInc and click **Install**
+5. Reload if prompted
 
-1.  **Open your editor.**
-2.  **Open the Extensions View.**
-3.  **Search for Roo Code:** Type `Roo Code` in the Extensions view search box.
-4.  **Install:** Find "Roo Code" in the search results (by RooVeterinaryInc). Click the **Install** button.
-5.  **Reload (if required):** Your editor may prompt you to reload. If so, click the reload button.
+<img src="/img/installing/installing-1.png" alt="Open VSX Registry with Roo Code extension ready to install" width="400" />
+*Open VSX Registry with Roo Code extension ready to install*
+## Manual Installation from VSIX
 
-## 3. Installation from a VSIX File (Advanced)
+If you prefer to download and install the VSIX file directly:
 
-This method is useful if you're developing Roo Code, testing a specific build, or need to install it offline.
+1. **Download the VSIX file:**
+   * Find official releases on the [Roo Code GitHub Releases page](https://github.com/RooVetGit/Roo-Code/releases)
+   * Download the `.vsix` file from the latest release
 
-1.  **Download the VSIX file:**
-    *   **Releases:**  You can find official releases on the [Roo Code GitHub Releases page](https://github.com/RooVetGit/Roo-Code/releases).  Download the `.vsix` file from the latest release.
-    *   **Development Builds:** If you're building the extension yourself, the `.vsix` file is located in the `bin/` directory after running `npm run package`.
+2. **Install in VS Code:**
+   * Open VS Code
+   * Access Extensions view
+   * Click the "..." menu in the Extensions view
+   * Select "Install from VSIX..."
+   * Browse to and select your downloaded `.vsix` file
 
-2.  **Open VS Code.**
-3.  **Open the Extensions View.**
-4.  **Install from VSIX:**
-    *   Click the **"..."** (Views and More Actions...) menu in the top-right corner of the Extensions view.
-    *   Select **"Install from VSIX..."**
-    *   Browse to the downloaded `.vsix` file and select it.
-5.  **Reload (if required):**  VS Code may prompt you to reload.  If so, click the **Reload** button.
+<img src="/img/installing/installing-2.png" alt="VS Code's Install from VSIX dialog" width="400" />
+*Installing Roo Code using VS Code's "Install from VSIX" dialog*
 
-## Troubleshooting Installation
+## Development Builds
 
-*   **Extension Doesn't Appear:**
-    *   Make sure you've restarted VS Code after installation.
-    *   Check the Extensions view to see if Roo Code is listed and enabled.
-    *   Try disabling and re-enabling the extension.
-    *   Check for any error messages in the VS Code Output panel (View -> Output, then select "Roo Code" from the dropdown).
-*   **Marketplace Issues:**
-    *   If you're having trouble with the VS Code Marketplace, try installing from a VSIX file (see instructions above).
-    *   Ensure you have a stable internet connection.
-* **Compatibility:** Roo Code requires VS Code version 1.84.0 or later.
+:::note Developer Information Only
+This section is intended only for developers contributing to Roo Code.
+:::
 
-If you continue to experience problems, please visit our [GitHub Issues page](https://github.com/RooVetGit/Roo-Code/issues) or [Reddit community](https://www.reddit.com/r/RooCode) to report the issue or ask for help.
+If you're building Roo Code from source:
+
+1. Run `npm run build` in the project directory
+2. Find the generated VSIX file in the `bin/` directory
+3. In VS Code, open Extensions view and select "Install from VSIX..." from the "..." menu
+4. Browse to and select your generated `.vsix` file
+
+<img src="/img/installing/installing-2.png" alt="VS Code's Install from VSIX dialog" width="400" />
+*Installing a development build using VS Code's "Install from VSIX" dialog*
+
+## Troubleshooting
+
+<img src="/img/installing/installing-4.png" alt="VS Code Output panel showing Roo Code logs for troubleshooting" width="100%" />
+*VS Code Output panel showing Roo Code logs for troubleshooting*
+
+**Extension Not Visible**
+* Restart VS Code
+* Verify Roo Code is listed and enabled in Extensions
+* Try disabling and re-enabling
+* Check Output panel for errors (View → Output, select "Roo Code")
+
+**Installation Problems**
+* Ensure stable internet connection
+* Verify VS Code version 1.84.0 or later
+* If VS Code Marketplace is inaccessible, try the Open VSX Registry method
+
+## Getting Support
+
+If you encounter issues not covered here:
+
+* Join our [Discord community](https://discord.gg/roocode) for real-time support
+* Submit issues on [GitHub](https://github.com/RooVetGit/Roo-Code/issues)
+* Visit our [Reddit community](https://www.reddit.com/r/RooCode)