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

@@ -1,9 +1,12 @@
+//! SSE stream parser: converts SSE- or JSON-chunked LLM responses into
+//! typed `StreamEvent` variants (tokens, reasoning, tool calls, usage, done).
 pub mod turn;
 pub mod tools;
 
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
+/// One atomic event extracted from an LLM streaming response stream.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum StreamEvent {
     Token(String),
@@ -23,6 +26,8 @@ pub enum StreamEvent {
     Error(String),
 }
 
+/// Buffered SSE frame parser that accumulates raw `data:` lines and
+/// flushes a `StreamEvent` on each blank-line boundary.
 pub struct SseParser {
     buffer: String,
     event_type: Option<String>,
@@ -30,6 +35,7 @@ pub struct SseParser {
 }
 
 impl SseParser {
+    /// Create a new parser with an empty buffer.
     pub fn new() -> Self {
         SseParser {
             buffer: String::new(),
@@ -38,6 +44,17 @@ impl SseParser {
         }
     }
 
+    /// Feed a raw SSE chunk and produce any completed events.
+    ///
+    /// Flow: append chunk to buffer → scan for '\n' → strip '\r' → on
+    /// blank line, call `flush_event` to parse the accumulated data →
+    /// on `event:` line, store the event type → on `data:` line, append
+    /// to data accumulator → continue until buffer exhausted.
+    ///
+    /// Edge case: a chunk may split mid-line; the remainder stays in the
+    /// buffer for the next `feed()` call.
+    ///
+    /// Return: all `StreamEvent`s completed by this chunk.
     pub fn feed(&mut self, chunk: &str) -> Vec<StreamEvent> {
         self.buffer.push_str(chunk);
         let mut events = Vec::new();
@@ -57,6 +74,19 @@ impl SseParser {
         events
     }
 
+    /// Flush the current buffered `data:` lines as one or more `StreamEvent`s.
+    ///
+    /// Flow: join data lines → handle `[DONE]` sentinel → JSON-parse →
+    /// emit `Usage` if a usage object is present → else match `event_type`
+    /// ("message.stop", "message.delta", etc.) → extract content,
+    /// reasoning, tool-call deltas, or finish-reason from the delta
+    /// structure (supporting both Anthropic-style top-level delta and
+    /// OpenAI-style `choices` array).
+    ///
+    /// Why: dual-format support in one method avoids a separate
+    /// provider-specific parsing layer.
+    ///
+    /// Return: 0, 1, or more `StreamEvent`s from the flushed frame.
     fn flush_event(&mut self) -> Vec<StreamEvent> {
         let data = self.data_lines.join("\n");
         self.data_lines.clear();
@@ -179,6 +209,13 @@ impl SseParser {
 /// Fallback parser for providers that send bare JSON chunks instead of SSE-framed
 /// `data: ...` lines. Not used by the `SseParser` streaming path (which handles
 /// standard SSE framing directly), kept for providers/tests that feed raw chunks.
+///
+/// Flow: parse `data` as JSON → extract first `choices[0].delta` →
+/// return a `Token`, `Reasoning`, `Done`, or `ToolCallDelta` event based
+/// on the fields present.
+///
+/// Return: `Some(StreamEvent)` if the chunk contained recognisable
+/// content, `None` otherwise.
 #[allow(dead_code)]
 pub fn parse_stream_chunk(data: &str) -> Option<StreamEvent> {
     let value: Value = serde_json::from_str(data).ok()?;