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/view/chat.rs

@@ -1,3 +1,15 @@
+//! Chat transcript panel rendering.
+//!
+//! Flow: `draw_chat` turns `state.transcript_cache.messages` into a
+//! header + markdown-rendered body per message (via `super::markdown`),
+//! appends a streaming spinner line when a turn is in flight, then
+//! slices the combined line list to the currently visible scroll window
+//! before handing it to a ratatui `Paragraph`.
+//!
+//! Why: lines are recomputed every frame instead of cached, since
+//! markdown wrapping depends on the current terminal width, which can
+//! change between frames.
+
 use ratatui::layout::Rect;
 use ratatui::style::{Style, Modifier};
 use ratatui::text::{Line, Span};
@@ -5,6 +17,17 @@ use ratatui::widgets::{Block, Borders, Paragraph, Wrap};
 use ratatui::Frame;
 use super::theme::Theme;
 
+/// Break a flat run of styled spans into `Line`s at embedded `\n` boundaries.
+///
+/// Flow: for each span, split its text on '\n' → push non-empty parts onto
+/// the current line's span buffer → on each newline boundary, flush the
+/// buffer into a new `Line` and start fresh.
+///
+/// Why: `render_markdown` produces a single Vec<Span> with newlines baked
+/// into span content; ratatui's Paragraph wants pre-split `Line`s to lay
+/// out and scroll correctly.
+///
+/// Return: at least one (possibly empty) `Line`, never an empty vec.
 fn split_spans_into_lines<'a>(spans: Vec<Span<'a>>) -> Vec<Line<'a>> {
     let mut lines = Vec::new();
     let mut current_spans = Vec::new();
@@ -39,6 +62,7 @@ fn _role_name(role: &crate::dto::chat::message::Role) -> &'static str {
     }
 }
 
+/// Map a message role to its short uppercase badge label for the chat header.
 fn role_badge(role: &crate::dto::chat::message::Role) -> &'static str {
     match role {
         crate::dto::chat::message::Role::User => "YOU",
@@ -56,6 +80,17 @@ fn format_timestamp(ts: i64) -> String {
     format!("{:02}:{:02}", hrs, mins)
 }
 
+/// Render the scrollable chat transcript panel.
+///
+/// Flow: build a header + markdown-rendered body Line list per message →
+/// append a streaming spinner line if a turn is in flight → slice the
+/// combined lines to the visible window based on scroll offset → wrap in
+/// a Paragraph and render.
+///
+/// Why: lines are computed fresh every frame rather than cached, since
+/// wrapping depends on the current terminal width.
+///
+/// Return: nothing; draws directly into `frame` at `area`.
 pub fn draw_chat(frame: &mut Frame, area: Rect, state: &crate::app::state::rest::AppStateRest) {
     let messages = &state.transcript_cache.messages;
     let scroll_offset = state.scroll.offset;