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/utility/dir_list.rs

@@ -1,9 +1,20 @@
+//! Tool for listing the immediate contents of a workspace directory.
+//!
+//! Flow: resolve the requested path against workspace roots → validate
+//! it exists and is a directory → read its direct children with
+//! `fs::read_dir`, tagging subdirectories with a trailing `/` → format
+//! into a header + newline-joined listing.
+//!
+//! Why: gives the agent a quick, one-level view of the workspace
+//! structure without pulling in the full recursive directory cache.
+
 use std::fs;
 use serde_json::{json, Value};
 use anyhow::{Result, anyhow};
 use super::super::Tool;
 use super::super::ToolCtx;
 
+/// Tool that lists the immediate contents of a workspace directory.
 pub struct DirList;
 
 impl Tool for DirList {
@@ -28,6 +39,19 @@ impl Tool for DirList {
         })
     }
 
+    /// List the immediate entries of the requested workspace directory.
+    ///
+    /// Flow: extract `path` argument → resolve against workspace roots →
+    /// short-circuit with a plain message if the path doesn't exist or
+    /// isn't a directory → `read_dir` → map each entry to its name
+    /// (appending `/` for subdirectories) → join into a formatted listing
+    /// with an entry-count header showing the canonicalized path.
+    ///
+    /// Why: entries whose metadata fails to read (`e.ok()` filter) are
+    /// silently skipped rather than aborting the whole listing.
+    ///
+    /// Return: header + newline-joined entry names, or an error if the
+    /// `path` argument is missing or `read_dir` fails outright.
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let rel = args.get("path")
             .and_then(|v| v.as_str())