Enhance tool documentation and add new features

- Added module-level documentation for memory tools (`remember`, `recall`, `forget`) to clarify their purpose.
- Improved documentation in `recall.rs` and `remember.rs` to describe the functionality and flow of memory entry operations.
- Updated `mod.rs` to include descriptions for the tool trait and execution context.
- Enhanced `plan.rs` with detailed comments on plan-mode signaling tools.
- Documented text search tools in `search.rs` to explain their functionality.
- Improved sequential-thinking tool documentation in `seqthink.rs`.
- Added safety filter documentation in `shell_filter` for credential and git operations.
- Enhanced utility tools documentation, including `cd`, `dir_cache_update`, and `todowrite`.
- Improved rendering documentation in view modules (`chat`, `markdown`, `status`, `workflow`) to clarify rendering flows and purposes.

src/tool/fs/edit.rs

@@ -1,3 +1,5 @@
+//! Tool: `edit` — replace a substring in a file with a new string.
+
 use std::fs;
 use std::path::PathBuf;
 use serde_json::{json, Value};
@@ -8,6 +10,7 @@ use super::super::resolve_path;
 use super::super::check_graduated_checks;
 use super::helpers::arg_str;
 
+/// Tool: replace text in a file. Requires the old string to be unique unless `replace_all` is true.
 pub struct Edit;
 
 impl Tool for Edit {
@@ -48,6 +51,13 @@ impl Tool for Edit {
         })
     }
 
+    /// Perform the in-file string replacement.
+    ///
+    /// Flow: validate args → resolve path → read file → count occurrences →
+    /// replace one or all → write back → report byte delta (+ optional graduated checks).
+    ///
+    /// Why: requires a non-empty `reason` and a non-empty `old` string to prevent
+    /// accidental identity edits. Enforces uniqueness unless `replace_all` is set.
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let rel = arg_str(args, "path")?;
         let old = arg_str(args, "old")?;