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/delete.rs

@@ -1,3 +1,5 @@
+//! Tool: `delete` — remove a file or empty directory relative to a workspace root.
+
 use std::fs;
 use std::path::PathBuf;
 use serde_json::{json, Value};
@@ -7,6 +9,7 @@ use super::super::ToolCtx;
 use super::super::resolve_path;
 use super::helpers::arg_str;
 
+/// Tool: delete a file or empty directory. Refuses non-empty directories.
 pub struct Delete;
 
 impl Tool for Delete {
@@ -31,6 +34,10 @@ impl Tool for Delete {
         })
     }
 
+    /// Delete a file or empty directory. Returns success message or errors on failure.
+    ///
+    /// Flow: resolve path → check existence → check dir/file → remove.
+    /// Only empty directories are deletable (non-empty returns an error).
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let rel = arg_str(args, "path")?;
         let path: PathBuf = resolve_path(&ctx.workspaces, &rel)?;

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")?;

src/tool/fs/helpers.rs

@@ -1,7 +1,14 @@
+//! Shared helpers for filesystem tools: extracting string arguments from JSON
+//! and producing user-friendly "not found" diagnostics.
+
 use std::path::Path;
 use serde_json::Value;
 use anyhow::{Result, anyhow};
 
+/// Extract a required string argument from a JSON args map.
+///
+/// Return: the value as `String` if present and a string type; `Err` if missing
+/// or of a different JSON type (null, number, boolean, array, object).
 pub fn arg_str(args: &Value, name: &str) -> Result<String> {
     args.get(name)
         .and_then(|v| v.as_str())
@@ -9,6 +16,12 @@ pub fn arg_str(args: &Value, name: &str) -> Result<String> {
         .ok_or_else(|| anyhow!("missing required argument: {}", name))
 }
 
+/// Produce a user-friendly diagnostic string when a path doesn't resolve or exist.
+///
+/// Checks whether the resolved path canonically falls inside any workspace root
+/// and reports either "path outside workspaces" or "path does not exist" accordingly.
+///
+/// Return: a one-line description of the resolution failure.
 pub fn not_found_help(ctx: &super::super::ToolCtx, path: &Path, rel: &str) -> String {
     let canon = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
     let in_ws = ctx.workspaces.iter().any(|w| {

src/tool/fs/mod.rs

@@ -1,3 +1,6 @@
+//! Filesystem tool implementations: read, write, edit, and delete operations
+//! on workspace-rooted paths.
+
 pub mod delete;
 pub mod edit;
 pub mod helpers;

src/tool/fs/read.rs

@@ -1,3 +1,5 @@
+//! Tool: `read` — display file contents with line numbers.
+
 use std::fs;
 use std::path::PathBuf;
 use serde_json::{json, Value};
@@ -7,6 +9,7 @@ use super::super::ToolCtx;
 use super::super::resolve_path;
 use super::helpers::{arg_str, not_found_help};
 
+/// Tool: read a file and display it with line numbers, optionally truncated to `limit` lines.
 pub struct Read;
 
 impl Tool for Read {
@@ -35,6 +38,13 @@ impl Tool for Read {
         })
     }
 
+    /// Read and display a file with line numbers.
+    ///
+    /// Flow: resolve path → if not found, call `not_found_help` for diagnostic →
+    /// read entire file → enumerate and format lines → optionally truncate by `limit`.
+    ///
+    /// Return: line-numbered content; `not_found_help` message if the path doesn't
+    /// exist; a "is a directory" message if the path points at a directory.
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let rel = arg_str(args, "path")?;
         let limit = args.get("limit").and_then(|v| v.as_u64()).map(|v| v as usize);

src/tool/fs/write.rs

@@ -1,3 +1,5 @@
+//! Tool: `write` — write content to a file, creating parent directories on demand.
+
 use std::fs;
 use serde_json::{json, Value};
 use anyhow::{Result, anyhow};
@@ -7,6 +9,7 @@ use super::super::resolve_path;
 use super::super::check_graduated_checks;
 use super::helpers::arg_str;
 
+/// Tool: write content to a file, auto-creating parent directories as needed.
 pub struct Write;
 
 impl Tool for Write {
@@ -39,6 +42,13 @@ impl Tool for Write {
         })
     }
 
+    /// Write content to a file, creating parent directories as needed.
+    ///
+    /// Flow: validate args (non-empty reason) → resolve path → create parent
+    /// dirs → write file → report byte count (+ optional graduated checks).
+    ///
+    /// Why: requires a non-empty `reason` to discourage stray writes; parent
+    /// directories are created silently so the tool works for new paths.
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let rel = arg_str(args, "path")?;
         let content = arg_str(args, "content")?;