Add and update documentation: Add new pages for custom rules, context window management, and preferences management; Update existing pages for custom instructions, experimental features, MCP, and context mentions

Author: Michaelzag

docs/advanced-usage/custom-instructions.md

@@ -70,6 +70,22 @@ Rules:
 * **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
 
+## Difference Between Custom Instructions and Custom Rules
+
+While related, custom instructions and custom rules serve slightly different purposes:
+
+* **Custom Instructions** (set via Prompts Tab): 
+  - General behavioral guidance for Roo
+  - Often more conversational or high-level
+  - Set through the UI or via rule files
+  
+* **Custom Rules** (primarily in rule files):
+  - More structured, specific technical guidelines
+  - Often focused on code standards and practices
+  - Typically organized by categories
+  
+For detailed information on creating effective structured rules in rule files, see the [Custom Rules](custom-rules.md) documentation.
+
 ## Examples of Custom Instructions
 
 * "Always use spaces for indentation, with a width of 4 spaces"
@@ -80,4 +96,33 @@ 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.
+## Strategies for Effective Custom Instructions
+
+### Be Clear and Specific
+
+Vague instructions can lead to inconsistent results. Be as specific as possible:
+
+**Good Example:**
+"Use TypeScript's strict mode and provide type annotations for all function parameters and return values."
+
+**Less Effective:**
+"Make sure to use types properly."
+
+### Prioritize Important Guidelines
+
+Put the most important instructions first, as they'll receive more attention:
+
+```
+1. Always handle errors and edge cases explicitly
+2. Include JSDoc comments for all public functions
+3. Follow the repository's existing code style
+```
+
+### Balance Flexibility and Constraint
+
+Too many rigid instructions can limit Roo's ability to help, while too few may lead to inconsistent results:
+
+**Balanced Approach:**
+"Follow the existing code style in the project, but feel free to suggest improvements where patterns are unclear or could be more efficient."
+
+By using custom instructions effectively, you can tailor Roo Code's behavior to match your coding style, project requirements, and personal preferences.

docs/advanced-usage/custom-rules.md

@@ -0,0 +1,257 @@
+# Custom Rules
+
+Custom rules allow you to define specific guidelines and behaviors for Roo Code to follow when working with your projects. These rules help ensure consistent code quality, adherence to project standards, and tailored assistance for your specific needs.
+
+## What Are Custom Rules?
+
+Custom rules are guidelines stored in special files in your project's root directory. They tell Roo how to approach various aspects of your codebase, such as:
+
+- Coding style and formatting preferences
+- Documentation requirements
+- Testing practices
+- Error handling approaches
+- Project-specific conventions
+
+Unlike general custom instructions, rules are typically more structured and focused on specific technical requirements.
+
+## Rule File Types
+
+Roo Code supports several rule file formats:
+
+| File Name | Purpose |
+|-----------|---------|
+| `.clinerules` | Primary rule file for all modes |
+| `.clinerules-code` | Rules specific to Code mode |
+| `.clinerules-architect` | Rules specific to Architect mode |
+| `.clinerules-[mode]` | Rules for any custom mode |
+| `.cursorrules` | Alternative format (compatible with Cursor AI) |
+| `.windsurfrules` | Alternative format (compatible with Windsurf) |
+
+All rule files should be placed in your project's root directory.
+
+## Rule File Format
+
+Rule files use a simple, markdown-based format that's easy to read and write:
+
+```markdown
+# Category Title
+
+1. Rule Group Title:
+   - Specific guideline
+   - Another guideline
+   - Technical requirement
+
+2. Another Rule Group:
+   - Guideline one
+   - Guideline two
+```
+
+This format makes rules easy to read for both humans and AI.
+
+## Global vs. Mode-Specific Rules
+
+Roo Code allows you to create both global rules and mode-specific rules:
+
+- **Global Rules** (`.clinerules`) apply to all modes
+- **Mode-Specific Rules** (`.clinerules-[mode]`) only apply when using that specific mode
+
+When both exist, mode-specific rules take priority, but global rules still apply if they don't conflict.
+
+## Example Rule Categories
+
+### Code Style Rules
+
+```markdown
+# Code Style
+
+1. Formatting:
+   - Use 2-space indentation for all files
+   - Keep line length under 100 characters
+   - Place opening braces on the same line
+   - Use trailing commas in multi-line arrays and objects
+
+2. Naming Conventions:
+   - Use camelCase for variables and functions
+   - Use PascalCase for classes and components
+   - Use UPPER_SNAKE_CASE for constants
+   - Prefix private methods with underscore
+```
+
+### Testing Rules
+
+```markdown
+# Testing Requirements
+
+1. Test Coverage:
+   - Write tests for all new functions
+   - Maintain at least 80% code coverage
+   - Test both success and error paths
+   - Use descriptive test names
+
+2. Test Structure:
+   - Organize tests by feature or component
+   - Use setup and teardown for common operations
+   - Mock external dependencies
+   - Test edge cases explicitly
+```
+
+### Documentation Rules
+
+```markdown
+# Documentation Standards
+
+1. Code Documentation:
+   - Document all public functions with JSDoc
+   - Explain complex algorithms with comments
+   - Include examples for APIs
+   - Document parameters and return values
+
+2. Project Documentation:
+   - Keep README up-to-date
+   - Document setup steps
+   - Include troubleshooting guidance
+   - Add comments for non-obvious code
+```
+
+## Best Practices for Writing Effective Rules
+
+### 1. Be Specific and Clear
+
+Write clear, actionable guidelines rather than vague principles:
+
+**Good:**
+```markdown
+- Validate all user inputs before processing
+- Log errors with stack traces and context
+- Use parameterized queries for database operations
+```
+
+**Not as helpful:**
+```markdown
+- Make sure code is secure
+- Handle errors properly
+- Be careful with databases
+```
+
+### 2. Organize Logically
+
+Group related rules together under clear categories:
+
+```markdown
+# Security
+
+1. Input Validation:
+   - Validate all user inputs
+   - Sanitize data before use
+   - Reject unexpected values
+
+2. Authentication:
+   - Require strong passwords
+   - Implement account lockouts
+   - Log authentication attempts
+```
+
+### 3. Prioritize Important Rules
+
+Put the most important rules first:
+
+```markdown
+# Performance
+
+1. Critical Paths:
+   - Optimize database queries
+   - Cache frequently accessed data
+   - Minimize network requests
+
+2. General Optimizations:
+   - Use efficient algorithms
+   - Minimize DOM manipulations
+   - Implement lazy loading
+```
+
+### 4. Keep Rules Updated
+
+Review and update your rules as your project evolves:
+
+- Remove outdated guidelines
+- Add rules for new technologies
+- Refine based on project learnings
+
+## Practical Rule Examples by Project Type
+
+### Web Development Project
+
+```markdown
+# Web Project Rules
+
+1. Accessibility:
+   - Use semantic HTML elements
+   - Include alt text for images
+   - Ensure keyboard navigation works
+   - Maintain WCAG AA compliance
+
+2. Performance:
+   - Keep bundle size under 500KB
+   - Optimize images before adding
+   - Implement code splitting
+   - Lazy load non-critical resources
+```
+
+### Data Science Project
+
+```markdown
+# Data Science Rules
+
+1. Data Management:
+   - Document data sources
+   - Version control datasets
+   - Include data cleaning steps
+   - Note missing value handling
+
+2. Models:
+   - Document training parameters
+   - Include accuracy metrics
+   - Validate against test data
+   - Explain feature importance
+```
+
+### Mobile App Project
+
+```markdown
+# Mobile App Rules
+
+1. UI/UX:
+   - Support both light and dark themes
+   - Implement responsive layouts
+   - Follow platform design guidelines
+   - Test on multiple device sizes
+
+2. Performance:
+   - Minimize app size
+   - Optimize battery usage
+   - Cache network responses
+   - Use efficient list rendering
+```
+
+## Combining Rules with Custom Modes
+
+For an even more tailored experience, you can:
+
+1. Create a custom mode with specific capabilities
+2. Create matching `.clinerules-[mode]` file
+3. Get specialized assistance that follows your guidelines
+
+For example, you might create a "security-auditor" mode with a `.clinerules-security-auditor` file containing security-focused rules.
+
+## How to Test Your Rules
+
+To verify your rules are working:
+
+1. Create your rule file in the project root
+2. Switch to the appropriate mode if using mode-specific rules
+3. Ask Roo to perform a task related to your rules
+4. Check if the response follows your guidelines
+
+For example, after adding code style rules, ask Roo to write a new function and see if it follows your specified style.
+
+By using custom rules effectively, you can transform Roo into a team member who understands and follows your project's unique needs and standards.