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

@@ -1,3 +1,5 @@
+//! Bash-shell execution tool with safety filters and optional timeout.
+
 use std::process::Command;
 use std::time::Duration;
 use serde_json::{json, Value};
@@ -5,6 +7,8 @@ use anyhow::{Result, anyhow};
 use super::Tool;
 use super::ToolCtx;
 
+/// Tool that runs `bash -c <command>`, optionally in the background, with safety
+/// filters applied before spawning.
 pub struct Bash;
 
 impl Tool for Bash {
@@ -41,6 +45,19 @@ impl Tool for Bash {
         })
     }
 
+    /// Run a bash command (foreground or background) with safety filters and a timeout.
+    ///
+    /// Flow: extract args → run `check_credential_read` then `check_git_destructive`
+    ///       (bail if either rejects) → branch on `run_in_background`: if true, hand off
+    ///       to the bg-bash subsystem and return the job ID; else spawn `bash -c`,
+    ///       poll with `try_wait`, kill on timeout, format combined stdout+stderr.
+    ///
+    /// Why: the safety filters run unconditionally so background jobs are also gated;
+    /// the timeout is enforced by polling the child rather than relying on a libc alarm
+    /// so cleanup stays in Rust.
+    ///
+    /// Return: exit-code + elapsed-seconds summary line (plus captured output) for
+    /// foreground runs, or the job ID for background runs.
     fn run(&self, _ctx: &ToolCtx, args: &Value) -> Result<String> {
         let cmd = args.get("command")
             .and_then(|v| v.as_str())