docs: Update prompt structure and experimental features documentation; add tool messages and remove outdated features

Author: hannesrudolph

docs/advanced-usage/prompt-structure.md

@@ -10,6 +10,10 @@ Roo Code uses three primary message types when communicating with LLMs:
 - **User Messages**: Content sent by you (the user) to Roo
 - **Assistant Messages**: Responses generated by the LLM based on your requests
 
+At the API level, there's also a fourth message role:
+
+- **Tool Messages**: Results returned from tool executions, sent back to the LLM as input
+
 Understanding these message types helps you work more effectively with Roo and can be valuable for troubleshooting or advanced customization.
 
 ## System Prompt
@@ -42,7 +46,8 @@ User messages contain your direct inputs to Roo, plus additional contextual info
   - Cursor position
   - Active terminals with output
   - Recently modified files
-  - Current time and token/cost information
+  - Current time
+  - Token/cost information
   - Current mode
   - File listing (on initial connection)
 
@@ -55,7 +60,8 @@ Assistant messages are the LLM's responses, which may include:
 - **Text Responses**: Direct answers to your queries
 - **Thinking**: Internal reasoning process (visible when enabled)
 - **Tool Calls**: Requests to use specific tools like reading files or executing commands
-- **Tool Results**: The outcome of executed tools
+
+Note that while assistant messages contain tool calls, the results of those tools are sent back to the LLM in separate tool messages, not as part of the assistant message itself.
 
 ## Message Flow
 
@@ -77,6 +83,17 @@ Internally, Roo's prompt construction is handled by several components:
 - **Message Transformation**: Provider-specific transformers convert Roo's internal message format to the format required by each LLM API
 - **Custom Prompt Loading**: The `loadSystemPromptFile` function checks for and processes custom system prompt files
 
+## Support Prompts
+
+Alongside the main chat flow, Roo uses specialized templates for specific code actions:
+
+- **Code Action Prompts**: For commands like "Explain", "Fix", "Improve", or "Add to Context"
+- **Template-Based**: Generated from templates in `src/shared/support-prompt.ts`
+- **Independent Context**: Often operates without the main chat history
+- **Task-Specific Format**: Optimized for the specific code task being performed
+
+These support prompts work outside the normal conversation flow to provide focused assistance for specific coding tasks.
+
 ## Optimizing Your Interactions
 
 Understanding this structure can help you:

docs/features/experimental/experimental-features.md

@@ -18,14 +18,6 @@ To enable or disable experimental features:
 
 The following experimental features are currently available:
 
-### Search and Replace
-
-Adds a new tool for searching and replacing text in a file.
-
-### Insert Content
-
-Adds a new tool for inserting content at any position in a file.
-
 ### Power Steering
 
 When enabled, Roo will remind the model about the details of its current mode definition more frequently. This will lead to stronger adherence to role definitions and custom instructions, but will use more tokens per message.

sidebars.ts

@@ -36,8 +36,8 @@ const sidebars: SidebarsConfig = {
         'features/keyboard-shortcuts',
         'features/model-temperature',
         'features/settings-management',
-        'features/suggested-responses',
         'features/shell-integration',
+        'features/suggested-responses',
         {
           type: 'category',
           label: 'MCP',
@@ -67,11 +67,6 @@ const sidebars: SidebarsConfig = {
       type: 'category',
       label: 'Advanced Usage',
       items: [
-        'advanced-usage/prompt-engineering',
-        'advanced-usage/prompt-structure',
-        'advanced-usage/large-projects',
-        'advanced-usage/rate-limits-costs',
-        'advanced-usage/local-models',
         {
           type: 'category',
           label: 'Available Tools',
@@ -88,13 +83,17 @@ const sidebars: SidebarsConfig = {
             'advanced-usage/available-tools/list-files',
             'advanced-usage/available-tools/new-task',
             'advanced-usage/available-tools/read-file',
-            'advanced-usage/available-tools/search-and-replace',
             'advanced-usage/available-tools/search-files',
             'advanced-usage/available-tools/switch-mode',
             'advanced-usage/available-tools/use-mcp-tool',
             'advanced-usage/available-tools/write-to-file',
           ],
         },
+        'advanced-usage/prompt-engineering',
+        'advanced-usage/prompt-structure',
+        'advanced-usage/rate-limits-costs',
+        'advanced-usage/local-models',
+        'advanced-usage/large-projects',
       ],
     },
     {