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/runtime/event_loop/mod.rs

@@ -1,3 +1,5 @@
+//! Adaptive poll-rate event loop: polls faster for IDLE_THRESHOLD_MS
+//! after any activity, then slows down to conserve CPU.
 use std::collections::VecDeque;
 use std::time::{Duration, Instant};
 
@@ -7,12 +9,15 @@ const FAST_POLL_MS: u64 = 8;
 const SLOW_POLL_MS: u64 = 100;
 const IDLE_THRESHOLD_MS: u64 = 500;
 
+/// Tracks whether the app has been active vs idle to adjust the TUI poll
+/// rate, balancing responsiveness against CPU usage.
 pub struct EventLoop {
     last_activity: Instant,
     fast_poll_until: Option<Instant>,
 }
 
 impl EventLoop {
+    /// Create an `EventLoop` with the current instant as the last activity.
     pub fn new() -> Self {
         EventLoop {
             last_activity: Instant::now(),
@@ -20,6 +25,10 @@ impl EventLoop {
         }
     }
 
+    /// Return the appropriate polling delay based on activity state.
+    ///
+    /// Flow: if `fast_poll_until` is set and the deadline hasn't expired,
+    /// return `FAST_POLL_MS`; otherwise return `SLOW_POLL_MS`.
     pub fn poll_interval(&self) -> Duration {
         if let Some(fast_until) = self.fast_poll_until {
             if Instant::now() < fast_until {
@@ -29,15 +38,21 @@ impl EventLoop {
         Duration::from_millis(SLOW_POLL_MS)
     }
 
+    /// Mark the current time as the last activity and arm the fast-poll
+    /// window for the next `IDLE_THRESHOLD_MS`.
     pub fn mark_active(&mut self) {
         self.last_activity = Instant::now();
         self.fast_poll_until = Some(Instant::now() + Duration::from_millis(IDLE_THRESHOLD_MS));
     }
 
+    /// Return `true` if the app has been idle for more than `IDLE_THRESHOLD_MS`.
     pub fn is_idle(&self) -> bool {
         self.last_activity.elapsed().as_millis() as u64 > IDLE_THRESHOLD_MS
     }
 
+    /// Drain all pending `TurnEvent`s from the shared mutex queue.
+    ///
+    /// Return: a `Vec` of all events that were in the queue (may be empty).
     pub fn drain_events(
         events: &std::sync::Mutex<VecDeque<TurnEvent>>,
     ) -> Vec<TurnEvent> {