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/service/provider.rs

@@ -1,3 +1,6 @@
+//! Blocking HTTP client for OpenAI/Anthropic-compatible chat completion APIs,
+//! supporting both non-streaming and SSE-streaming requests with automatic retry.
+
 use std::time::Duration;
 use anyhow::Result;
 
@@ -12,6 +15,10 @@ pub const DEFAULT_API_KEY: &str = "sk-5dd268d88adb496b-818beb-6bc7498e";
 const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
 const REQUEST_TIMEOUT: Duration = Duration::from_secs(60);
 
+/// Blocking HTTP client for a single LLM provider endpoint.
+///
+/// Holds the reqwest client, credentials, and model/base URL selection used
+/// by both the non-streaming and streaming chat completion calls.
 pub struct LlmClient {
     pub client: reqwest::blocking::Client,
     pub api_key: String,
@@ -20,6 +27,14 @@ pub struct LlmClient {
 }
 
 impl LlmClient {
+    /// Construct a client, falling back to built-in defaults for empty inputs.
+    ///
+    /// Flow: empty api_key/model → substitute defaults → build reqwest client
+    /// with connect/request timeouts (falling back to an untimed client if
+    /// the builder fails) → normalize base_url.
+    ///
+    /// Why: empty strings are treated as "unset" rather than errors so callers
+    /// can pass through unconfigured settings without special-casing them.
     pub fn new(mut api_key: String, model: String, base_url: Option<String>) -> Self {
         if api_key.is_empty() {
             api_key = DEFAULT_API_KEY.to_string();
@@ -48,6 +63,16 @@ impl LlmClient {
         }
     }
 
+    /// Send a non-streaming chat completion request and return the assistant's reply.
+    ///
+    /// Flow: build request → POST with retry loop (up to 10 attempts, 2s backoff)
+    /// → parse JSON response → extract first choice's message and token usage.
+    ///
+    /// Why: retries transient failures but aborts immediately on 401/403, since
+    /// those indicate a bad API key that retrying won't fix.
+    ///
+    /// Return: `Err` if all retries are exhausted, an auth error occurs, or the
+    /// response has no choices.
     pub fn chat_with_tools_non_streaming(
         &self,
         messages: &[ChatMessage],
@@ -177,6 +202,17 @@ impl LlmClient {
         }
     }
 
+    /// Perform one streaming chat completion request, parsing SSE events until completion.
+    ///
+    /// Flow: POST → read body in chunks → advance past valid UTF-8 boundary →
+    /// feed into `SseParser` → dispatch each `StreamEvent` to `on_event` and
+    /// accumulate in `StreamedTurn` → return assembled assistant message on `Done`.
+    ///
+    /// Why: chunk-by-chunk UTF-8-aware reads avoid splitting multi-byte sequences;
+    /// returns `aborted` error if `on_event` returns false so the caller can cancel.
+    ///
+    /// Return: assembled message + optional usage on success, `Err` on read
+    /// failure, non-2xx status, or callback-initiated abort.
     fn try_stream_once(
         &self,
         req: &ChatRequest,