docs: remove deprecated insert_content tool documentation and references

Author: hannesrudolph

.roo/rules-release-notes-writer/1_main_workflow.xml

@@ -110,10 +110,10 @@ gh pr list --repo RooCodeInc/Roo-Code --state merged --base main --limit 1000 \
       <initialization priority="CRITICAL">
         <action>Create .roo/tmp/release-notes/temp_pr_analysis_v[version].md</action>
         <details>
-          Parent task MUST create this file (and .roo/tmp/release-notes/temp_pr_inclusion_v[version].json, .roo/tmp/release-notes/temp_pr_list_v[VERSION].md if needed) before ANY subtasks.
-          Subtasks will ONLY append using insert_content.
-          Parent task MUST NOT append to temp_pr_analysis_v[version].md; this file is reserved exclusively for subtask outputs. The parent may only create/initialize the empty file(s).
-          Temp files live under .roo/tmp/release-notes/
+      Parent task MUST create this file (and .roo/tmp/release-notes/temp_pr_inclusion_v[version].json, .roo/tmp/release-notes/temp_pr_list_v[VERSION].md if needed) before ANY subtasks.
+      Subtasks will ONLY add entries to these temp files using the available safe file-editing capability (preserve existing content; no overwrites).
+      Parent task MUST NOT add entries to temp_pr_analysis_v[version].md; this file is reserved exclusively for subtask outputs. The parent may only create/initialize the empty file(s).
+      Temp files live under .roo/tmp/release-notes/
         </details>
       </initialization>
 
@@ -139,15 +139,15 @@ gh pr list --repo RooCodeInc/Roo-Code --state merged --base main --limit 1000 \
   3. Get issue details if linked
   4. Categorize change (Feature/QOL/Bug Fix/Provider Update)
   5. Identify documentation needs (new features, behavior changes, deprecations)
-  6. Append to .roo/tmp/release-notes/temp_pr_analysis_v[version].md using insert_content line 0
+      6. Add to .roo/tmp/release-notes/temp_pr_analysis_v[version].md at the start, preserving existing content (use the available safe file-editing capability)
 
   Include documentation flags:
   - docs-new: Completely new feature
   - docs-update: Existing docs need updating
   - docs-example: New examples needed
   - docs-migration: Breaking changes
 
-  CRITICAL: Never create/overwrite files, only append.
+  CRITICAL: Never overwrite existing content; only add entries while preserving prior content.
   MANDATORY: Insert the marker line '&lt;!-- generated-by-subtask: true --&gt;' immediately before the '---' separator in each PR entry.
   </message_template>
         <todos_template>
@@ -187,7 +187,7 @@ gh pr list --repo RooCodeInc/Roo-Code --state merged --base main --limit 1000 \
 Get PR details: gh pr view 1234 --repo RooCodeInc/Roo-Code --json number,title,author,mergedAt,labels,body,url
 Extract linked issues and get details
 Categorize the change and identify documentation needs
-Append analysis to .roo/tmp/release-notes/temp_pr_analysis_v3.20.1.md using insert_content line 0</message>
+Add analysis to .roo/tmp/release-notes/temp_pr_analysis_v3.20.1.md at the start, preserving existing content</message>
 <todos>
 [ ] Fetch PR #1234 details
 [ ] Extract linked issues and get details
@@ -199,7 +199,7 @@ Append analysis to .roo/tmp/release-notes/temp_pr_analysis_v3.20.1.md using inse
         <critical_notes>
           - Parent creates temp files first
           - Each PR gets its own subtask
-          - Subtasks only append, never overwrite
+          - Subtasks only add entries; never overwrite existing content
         </critical_notes>
       </subtask_creation_example>
     </phase>
@@ -366,7 +366,7 @@ fi
         <action>Supplement candidate PR set with changelog-referenced PRs not in fetched list and spawn analysis subtasks</action>
         <details>
           - Identify referenced PR numbers from step 2 that are missing from .roo/tmp/release-notes/temp_pr_analysis_v[version].md
-          - For each missing PR, fetch details and create a new investigation subtask (same pattern as pr_processing) to append analysis to temp_pr_analysis_v[version].md
+          - For each missing PR, fetch details and create a new investigation subtask (same pattern as pr_processing) to add analysis to temp_pr_analysis_v[version].md without overwriting existing content
           - Mark these as out_of_range if their mergedAt is outside the computed date window
           - Wait for all spawned subtasks to complete before proceeding
         </details>
@@ -378,7 +378,7 @@ gh pr view N --repo RooCodeInc/Roo-Code --json number,title,author,mergedAt,labe
           <spawn_subtask><![CDATA[
 <new_task>
 <mode>release-notes-writer</mode>
-<message>Investigate PR #[NUMBER] (changelog-referenced, possibly out of original range) for release notes v[version]. Follow standard analysis and append to .roo/tmp/release-notes/temp_pr_analysis_v[version].md.</message>
+<message>Investigate PR #[NUMBER] (changelog-referenced, possibly out of original range) for release notes v[version]. Follow standard analysis and add to .roo/tmp/release-notes/temp_pr_analysis_v[version].md without overwriting existing content.</message>
 <todos>
 [ ] Fetch PR #[NUMBER] details using gh pr view --repo RooCodeInc/Roo-Code
 [ ] Extract linked issues from PR body
@@ -709,10 +709,10 @@ gh pr list --repo RooCodeInc/Roo-Code --state merged --base main --limit 1000 \
       Date format is YYYY-MM-DD (ISO 8601) where MM is month (01-12)
     </rule>
     <rule priority="CRITICAL">
-      Parent task creates temp files, subtasks only append
+      Parent task creates temp files, subtasks only add entries (never overwrite)
     </rule>
     <rule priority="CRITICAL">
-      For each PR, the parent MUST create a subtask via new_task. The parent MUST NOT write PR analysis entries; only subtasks may append to .roo/tmp/release-notes/temp_pr_analysis_v[version].md. Do not proceed to changelog_alignment or compilation until all PR subtasks complete.
+      For each PR, the parent MUST create a subtask via new_task. The parent MUST NOT write PR analysis entries; only subtasks may add entries to .roo/tmp/release-notes/temp_pr_analysis_v[version].md without overwriting existing content. Do not proceed to changelog_alignment or compilation until all PR subtasks complete.
       Even when the parent already has the PR number, title, description, or a user‑provided
       summary list, it MUST still create and wait on the per‑PR subtask. These summaries are
       insufficient for functional understanding of the change, discovery of linked issues, and

docs/advanced-usage/available-tools/insert-content.md

@@ -29,7 +29,7 @@ Tools are organized into logical groups based on their functionality:
 |----------|---------|-------|------------|
 | **Read Group** | File system reading and exploration | [read_file](/advanced-usage/available-tools/read-file), [list_files](/advanced-usage/available-tools/list-files), [list_code_definition_names](/advanced-usage/available-tools/list-code-definition-names) | Code exploration and analysis |
 | **Search Group** | Pattern and semantic searching | [search_files](/advanced-usage/available-tools/search-files), [codebase_search](/advanced-usage/available-tools/codebase-search) | Finding code patterns and functionality |
-| **Edit Group** | File system modifications | [apply_diff](/advanced-usage/available-tools/apply-diff), [insert_content](/advanced-usage/available-tools/insert-content), [write_to_file](/advanced-usage/available-tools/write-to-file) | Code changes and file manipulation |
+| **Edit Group** | File system modifications | [apply_diff](/advanced-usage/available-tools/apply-diff), [write_to_file](/advanced-usage/available-tools/write-to-file) | Code changes and file manipulation |
 | **Browser Group** | Web automation | [browser_action](/advanced-usage/available-tools/browser-action) | Web testing and interaction |
 | **Command Group** | System command execution | [execute_command](/advanced-usage/available-tools/execute-command), [run_slash_command](/advanced-usage/available-tools/run-slash-command)* | Running scripts, building projects, executing command templates |
 | **MCP Group** | External tool integration | [use_mcp_tool](/advanced-usage/available-tools/use-mcp-tool), [access_mcp_resource](/advanced-usage/available-tools/access-mcp-resource) | Specialized functionality through external servers |
@@ -67,7 +67,6 @@ These tools help Roo find patterns and functionality across your codebase:
 These tools help Roo make changes to your code:
 
 - [apply_diff](/advanced-usage/available-tools/apply-diff) - Makes precise, surgical changes to your code
-- [insert_content](/advanced-usage/available-tools/insert-content) - Adds new lines of content without modifying existing lines
 - [write_to_file](/advanced-usage/available-tools/write-to-file) - Creates new files or completely rewrites existing ones
 
 ### Browser Tools

docs/advanced-usage/available-tools/tool-use-overview.md

@@ -75,7 +75,7 @@ When the `write_to_file` tool is invoked, it follows this process:
 
 1. **Parameter Validation**: Validates the required parameters and permissions
    - Checks that `path`, `content`, and `line_count` are provided
-   - If `line_count` is missing/invalid, reverts any diff view changes and returns an error suggesting alternative tools (`apply_diff`, `insert_content`, etc.) if modifying an existing file.
+   - If `line_count` is missing/invalid, reverts any diff view changes and returns an error suggesting alternative tools (`apply_diff`, etc.) if modifying an existing file.
    - Validates the file is allowed (not restricted by `.rooignore`)
    - Ensures the path is within the workspace boundaries
    - Tracks consecutive mistake counts for missing parameters

docs/advanced-usage/available-tools/write-to-file.md

@@ -53,7 +53,6 @@ These tools directly check `.rooignore` before any file operation. If a file is
 *   [`read_file`](/advanced-usage/available-tools/read-file): Will not read ignored files.
 *   [`write_to_file`](/advanced-usage/available-tools/write-to-file): Will not write to or create new ignored files.
 *   [`apply_diff`](/advanced-usage/available-tools/apply-diff): Will not apply diffs to ignored files.
-*   [`insert_content`](/advanced-usage/available-tools/insert-content): Will not write to ignored files.
 *   [`list_code_definition_names`](/advanced-usage/available-tools/list-code-definition-names): Will not parse ignored files for code symbols.
 
 ### File Discovery and Listing

docs/features/rooignore.md

@@ -14,7 +14,7 @@ This release introduces Gemini prompt caching, improves several tools, and inclu
 *   Improve [`apply_diff`](/advanced-usage/available-tools/apply-diff) to work better with **Google Gemini 2.5** and other models
 *   Automatically close files opened by edit tools (`apply_diff`, `insert_content`, `search_and_replace`, `write_to_file`) after changes are approved. This prevents cluttering the editor with files opened by Roo and helps clarify context by only showing files intentionally opened by the user.
 *   Added the `search_and_replace` tool. This tool finds and replaces text within a file using literal strings or regex patterns, optionally within specific line ranges (thanks samhvw8!).
-*   Added the [`insert_content`](/advanced-usage/available-tools/insert-content) tool. This tool adds new lines into a file at a specific location or the end, without modifying existing content (thanks samhvw8!).
+*   Added the `insert_content` tool (now retired). This tool added new lines into a file at a specific location or the end, without modifying existing content (thanks samhvw8!).
 *   Deprecated the `append_to_file` tool in favor of `insert_content` (use `line: 0`).
 *   Correctly revert changes and suggest alternative tools when [`write_to_file`](/advanced-usage/available-tools/write-to-file) fails on a missing line count
 *   Better progress indicator for [`apply_diff`](/advanced-usage/available-tools/apply-diff) tools (thanks qdaxb!)

docs/update-notes/v3.14.0.md

@@ -46,7 +46,7 @@ image: /img/social-share.jpg
 *   Improve [`apply_diff`](/advanced-usage/available-tools/apply-diff) to work better with **Google Gemini 2.5** and other models
 *   Automatically close files opened by edit tools (`apply_diff`, `insert_content`, `search_and_replace`, `write_to_file`) after changes are approved. This prevents cluttering the editor with files opened by Roo and helps clarify context by only showing files intentionally opened by the user.
 *   Added the `search_and_replace` tool. This tool finds and replaces text within a file using literal strings or regex patterns, optionally within specific line ranges (thanks samhvw8!).
-*   Added the [`insert_content`](/advanced-usage/available-tools/insert-content) tool. This tool adds new lines into a file at a specific location or the end, without modifying existing content (thanks samhvw8!).
+*   Added the `insert_content` tool (now retired). This tool added new lines into a file at a specific location or the end, without modifying existing content (thanks samhvw8!).
 *   Deprecated the `append_to_file` tool in favor of `insert_content` (use `line: 0`).
 *   Correctly revert changes and suggest alternative tools when [`write_to_file`](/advanced-usage/available-tools/write-to-file) fails on a missing line count
 *   Better progress indicator for [`apply_diff`](/advanced-usage/available-tools/apply-diff) tools (thanks qdaxb!)

docs/update-notes/v3.14.md

@@ -235,8 +235,8 @@ const config: Config = {
             from: ['/features/tools/execute-command'],
           },
           {
-            to: '/advanced-usage/available-tools/insert-content',
-            from: ['/features/tools/insert-content'],
+            to: '/advanced-usage/available-tools/tool-use-overview',
+            from: ['/features/tools/insert-content', '/advanced-usage/available-tools/insert-content'],
           },
           {
             to: '/advanced-usage/available-tools/list-code-definition-names',

docusaurus.config.ts

@@ -92,7 +92,6 @@ const sidebars: SidebarsConfig = {
                 'advanced-usage/available-tools/browser-action',
                 'advanced-usage/available-tools/codebase-search',
                 'advanced-usage/available-tools/execute-command',
-                'advanced-usage/available-tools/insert-content',
                 'advanced-usage/available-tools/list-code-definition-names',
                 'advanced-usage/available-tools/list-files',
                 'advanced-usage/available-tools/new-task',