Advanced usage refactor: Stage 1 (#81)

* Enhance API Configuration Profiles documentation with detailed setup instructions and new images

* Add custom modes images for enhanced documentation visuals

* Enhance Custom Instructions documentation with detailed explanations and new images

* Enhance API Configuration Profiles documentation with improved image formatting for clarity

* Fix formatting of images in custom modes documentation for improved readability

Author: hannesrudolph

docs/advanced-usage/api-configuration-profiles.md

@@ -2,35 +2,75 @@
 
 API Configuration Profiles allow you to create and switch between different sets of AI settings. Each profile can have different configurations for each mode, letting you optimize your experience based on the task at hand.
 
+:::info
+Having multiple configuration profiles lets you quickly switch between different AI providers, models, and settings without reconfiguring everything each time you want to change your setup.
+:::
 ## How It Works
 
 Configuration profiles can have their own:
-- API providers (OpenAI, Anthropic, etc.)
-- API keys
-- Model selections
+- API providers (OpenAI, Anthropic, OpenRouter, Glama, etc.)
+- API keys and authentication details
+- Model selections (o3-mini-high, Claude 3.7 Sonnet, DeepSeek R1, etc.)
 - Temperature settings
 - Thinking budgets
+- Provider-specific settings
 
-This lets you optimize your model configuration for different modes. For instance, you might want Architect and Debug mode to use a more powerful/expensive model to come up with a great plan, while Code mode uses a more standard coding model.
+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.
 
-## Setting Up Profiles
+## Creating and Managing Profiles
 
-1. Open Settings → Providers
-2. Choose a Configuration Profile from the dropdown, or create a new one
-3. Configure the profile's provider, model, key, and parameters
+### Creating a Profile
 
-## Linking Profiles to Modes
+1. Open Settings by clicking the gear icon <Codicon name="gear" /> → Providers
+2. Click the "+" button next to the profile selector
+
+   <img src="/img/api-configuration-profiles/api-configuration-profiles-1.png" alt="Profile selector with plus button" width="550" />
+3. Enter a name for your new profile
+   
+   <img src="/img/api-configuration-profiles/api-configuration-profiles.png" alt="Creating a new profile dialog" width="550" />
+4. Configure the profile settings:
+   - Select your API provider
+      
+      <img src="/img/api-configuration-profiles/api-configuration-profiles-2.png" alt="Provider selection dropdown" width="550" />
+   - Enter API key
+   
+      <img src="/img/api-configuration-profiles/api-configuration-profiles-3.png" alt="API key entry field" width="550" />
+   - 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" />
+
+### Switching Profiles
+
+Switch profiles in two ways:
+1. From Settings panel: Select a different profile from the dropdown
+
+   <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
 
-In the <Codicon name="notebook" /> Prompts tab, you can associate a Configuration Profile with each Mode.
+   <img src="/img/api-configuration-profiles/api-configuration-profiles-9.png" alt="API Configuration dropdown in chat interface" width="550" />
 
-## Benefits
+### Editing and Deleting Profiles
 
-- **Cost optimization**: Use premium models only where they add the most value
-- **Performance tailoring**: Match model capabilities to each mode's specific needs
-- **Workflow optimization**: Seamless transitions between modes with appropriate settings
+<img src="/img/api-configuration-profiles/api-configuration-profiles-10.png" alt="Profile editing interface" width="550" />
+- Select the profile in Settings to modify any settings
+- Click the pencil icon to rename a profile
+- Click the trash icon to delete a profile (you cannot delete the only remaining profile)
+
+## Linking Profiles to Modes
+In the <Codicon name="notebook" /> Prompts tab, you can explicitly associate a specific Configuration Profile with each Mode. The system also automatically remembers which profile you last used with each mode, making your workflow more efficient.
+<img src="/img/api-configuration-profiles/api-configuration-profiles-11.png" alt="Profile-Mode association interface in Prompts tab" width="550" />
+
+## Security Note
+
+API keys are stored securely in VSCode's Secret Storage and are never exposed in plain text.
 
 ## Related Features
 
-- Works with [custom modes](custom-modes)
+- Works with [custom modes](custom-modes) you create
 - Integrates with [local models](local-models) for offline work
-- Supports [temperature settings](model-temperature) per mode
+- Supports [temperature settings](model-temperature) per mode
+- Enhances cost management with [rate limits and usage tracking](rate-limits-costs)
+

docs/advanced-usage/custom-instructions.md

@@ -1,50 +1,57 @@
 # Custom Instructions
 
-Roo Code allows you to customize its behavior using custom instructions at both global and workspace levels. These instructions are added to the system prompt and influence how Roo Code responds to your requests. You can define:
+Custom Instructions allow you to personalize how Roo behaves, providing specific guidance that shapes responses, coding style, and decision-making processes.
 
-* **Global Custom Instructions:** Apply across all workspaces
-* **Workspace-Level Instructions:**
-    * **Workspace-Wide:** Apply to all modes in the workspace through `.clinerules` files
-    * **Mode-Specific:** Apply to specific modes in the workspace through files like `.clinerules-code`
+## What Are Custom Instructions?
 
-## Preferred Language
+Custom Instructions define specific behaviors, preferences, and constraints beyond Roo's basic role definition. Examples include coding style, documentation standards, testing requirements, and workflow guidelines.
+:::info Rules Files
+Custom Instructions are simply .rules files. They use the common convention of `.clinerules`, `.cursorrules`, and `.windsurfrules` files, which can be placed in your workspace root for version control or configured through the UI.
+ :::
 
-You can specify a preferred language for Roo Code to use. When set, this appears at the start of your custom instructions and directs Roo Code to communicate in your chosen language. You can set this in the **Prompts** tab.
+## Setting Custom Instructions
 
-## Global Custom Instructions
+### Global Custom Instructions
 
-These instructions apply across all workspaces. They're useful for setting preferences that you want to maintain regardless of which project you're working on.
+These instructions apply across all workspaces and maintain your preferences regardless of which project you're working on.
 
 **How to set them:**
 
+<img src="/img/custom-instructions/custom-instructions.png" alt="Roo Code Prompts tab showing global custom instructions interface" width="600" />
 1.  **Open Prompts Tab:** Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar
 2.  **Find Section:** Find the "Custom Instructions for All Modes" section
 3.  **Enter Instructions:** Enter your instructions in the text area
 4.  **Save Changes:** Click "Done" to save your changes
 
-## Workspace-Level Instructions
+### Workspace-Level Instructions
 
 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
 
 Workspace-wide instructions are defined through rule files in your workspace root, primarily using `.clinerules`. Additional support for `.cursorrules` and `.windsurfrules` is available for editor compatibility.
 
-### Mode-Specific Instructions
+#### Mode-Specific Instructions
 
 Mode-specific instructions can be set in two independent ways that can be used simultaneously:
 
 1.  **Using the Prompts Tab:**
+
+    <img src="/img/custom-instructions/custom-instructions-2.png" alt="Roo Code Prompts tab showing mode-specific custom instructions interface" width="600" />
     * **Open Tab:** Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar
     * **Select Mode:** Under the Modes heading, click the button for the mode you want to customize
     * **Enter Instructions:** Enter your instructions in the text area under "Mode-specific Custom Instructions (optional)"
     * **Save Changes:** Click "Done" to save your changes
 
+        :::info Global Mode Rules
+        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 `.clinerules-[mode]` file in your workspace root (e.g., `.clinerules-code`)
 
 When both tab instructions and rule files are set for a mode, both sets of instructions will be included in the system prompt.
 
-### How Instructions are Combined
+## How Instructions are Combined
 
 Instructions are placed in the system prompt in this exact format:
 
@@ -63,7 +70,7 @@ Rules:
 [.windsurfrules rules]
 ```
 
-### About Rule Files
+## Rules about .rules files
 
 * **File Location:** All rule files must be placed in the workspace root directory
 * **Empty Files:** Empty or missing rule files are silently skipped
@@ -80,4 +87,10 @@ Rules:
 * "Prioritize using the most common library in the community"
 * "When adding new features to websites, ensure they are responsive and accessible"
 
-By using custom instructions, you can tailor Roo Code's behavior to match your coding style, project requirements, and personal preferences.
+:::tip Pro Tip: File-Based Team Standards
+When working in team environments, placing `.clinerules` 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.
+:::
+
+## Combining with Custom Modes
+
+For advanced customization, combine with [Custom Modes](custom-modes) to create specialized environments with specific tool access, file restrictions, and tailored instructions.