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/app/state/rest.rs

@@ -1,3 +1,9 @@
+//! Top-level mutable application state (`AppStateRest`) and the transcript
+//! display type it owns.
+//!
+//! `AppStateRest` is the single source-of-truth struct mutated in-place from
+//! `actions/mod.rs` and `controller/input.rs`; every other module reads it.
+
 use std::collections::VecDeque;
 use std::path::PathBuf;
 use std::sync::{Arc, Mutex};
@@ -12,6 +18,7 @@ use crate::model::app_config::AppConfig;
 use crate::model::editlog::EditLog;
 use crate::model::settings::Settings;
 
+/// A single transcript entry rendered in the TUI chat pane.
 #[derive(Debug, Clone, PartialEq)]
 pub struct ChatMessageDisplay {
     pub role: crate::dto::chat::message::Role,
@@ -20,6 +27,7 @@ pub struct ChatMessageDisplay {
 }
 
 impl ChatMessageDisplay {
+    /// Build a display entry, stamping it with the current time.
     pub fn new(role: crate::dto::chat::message::Role, content: String) -> Self {
         ChatMessageDisplay {
             role,
@@ -29,6 +37,11 @@ impl ChatMessageDisplay {
     }
 }
 
+/// The single source-of-truth state struct for the entire application.
+///
+/// Mutated in-place from two locations: `actions/mod.rs` (`apply_action`)
+/// and `controller/input.rs` (key event handlers). Read-only from every
+/// other module.
 #[derive(Clone)]
 pub struct AppStateRest {
 
@@ -58,6 +71,15 @@ pub struct AppStateRest {
 }
 
 impl AppStateRest {
+    /// Construct the initial application state for a session.
+    ///
+    /// Flow: load settings/config -> derive download/worktree dirs from
+    /// `memory_dir`'s parent -> derive `session_id` from the session dir's
+    /// file name -> build the sub-state structs.
+    ///
+    /// Why: falls back to `memory_dir` itself (with a warning) when it has
+    /// no parent, and to an empty session id when the dir name can't be
+    /// read, so construction never fails.
     pub fn new(workspace_roots: Vec<PathBuf>, session_dir: PathBuf, memory_dir: PathBuf) -> Self {
         let settings = Settings::load();
         let app_config = AppConfig::load();
@@ -105,6 +127,10 @@ impl AppStateRest {
         }
     }
 
+    /// Whether an agent turn is currently running.
+    ///
+    /// Return: `false` (and logs a warning) if the mutex is poisoned, rather
+    /// than propagating a panic.
     pub fn turn_in_flight(&self) -> bool {
         self.turn_in_flight.lock().map(|g| *g).unwrap_or_else(|_| {
             tracing::warn!("[state] turn_in_flight mutex poisoned");
@@ -114,6 +140,8 @@ impl AppStateRest {
 
 
 
+    /// Append a message to the transcript, evicting the oldest entry once
+    /// `max_lines` is exceeded, and mark both the cache and the app dirty.
     pub fn push_transcript(&mut self, msg: ChatMessageDisplay) {
         self.transcript_cache.messages.push(msg);
         if self.transcript_cache.messages.len() > self.transcript_cache.max_lines {
@@ -123,11 +151,19 @@ impl AppStateRest {
         self.dirty = true;
     }
 
+    /// Queue a toast notification for display and mark the app dirty.
     pub fn push_toast(&mut self, toast: Toast) {
         self.misc.push_toast(toast);
         self.dirty = true;
     }
 
+    /// Resolve the base directory that stores this session (grandparent of
+    /// `session_dir`, i.e. the sessions root, not the individual session
+    /// folder).
+    ///
+    /// Why: falls back progressively -- grandparent, then parent, then
+    /// `session_dir` itself -- logging a warning at each step down, so this
+    /// never fails even on a shallow path.
     pub fn store_base_dir(&self) -> std::path::PathBuf {
         self.session_dir.parent()
             .and_then(|p| p.parent())
@@ -143,10 +179,13 @@ impl AppStateRest {
             })
     }
 
+    /// Build a `ToolCtx` for tool calls originating from the main agent.
     pub fn tool_ctx(&self) -> crate::tool::ToolCtx {
         self.tool_ctx_for(Origin::Main)
     }
 
+    /// Build a `ToolCtx` scoped to the given call origin (main, subagent,
+    /// reviewer), copying workspace/session/memory paths from state.
     pub fn tool_ctx_for(&self, origin: Origin) -> crate::tool::ToolCtx {
         crate::tool::ToolCtx {
             workspaces: self.workspace_roots.clone(),