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

@@ -1,2 +1,4 @@
+//! External service integrations: the LLM provider HTTP client and OAuth flows.
+
 pub mod provider;
 pub mod oauth;

src/service/oauth/loopback.rs

@@ -1,28 +1,46 @@
+//! Minimal loopback HTTP server for capturing OAuth authorization-code redirects.
+
 use std::io::{Read, Write};
 use std::net::{TcpListener, TcpStream};
 
+/// A single-use HTTP listener on `127.0.0.1` that receives the OAuth
+/// `?code=...` redirect and serves back a static confirmation page.
 pub struct LoopbackServer {
     listener: TcpListener,
     port: u16,
 }
 
 impl LoopbackServer {
+    /// Bind to an OS-assigned free port on localhost.
+    ///
+    /// Return: `Err` if the loopback interface can't be bound.
     pub fn bind() -> std::io::Result<Self> {
         let listener = TcpListener::bind("127.0.0.1:0")?;
         let port = listener.local_addr()?.port();
         Ok(LoopbackServer { listener, port })
     }
 
+    /// The redirect URI to hand to the OAuth authorization endpoint.
     pub fn redirect_uri(&self) -> String {
         format!("http://127.0.0.1:{}/callback", self.port)
     }
 
+    /// Block until one HTTP request arrives, then extract its `code` query param.
+    ///
+    /// Flow: accept one connection → apply read timeout → parse request line
+    /// → respond 200/400 depending on whether a code was found.
+    ///
+    /// Return: `Err(InvalidData)` if no `code` param is present in the request.
     pub fn wait_for_code(&self, timeout_ms: u64) -> std::io::Result<String> {
         let (mut stream, _) = self.listener.accept()?;
         stream.set_read_timeout(Some(std::time::Duration::from_millis(timeout_ms)))?;
         Self::read_callback(&mut stream)
     }
 
+    /// Read and parse a single HTTP callback request off `stream`, replying with a status page.
+    ///
+    /// Why: writes the HTTP response before returning so the browser tab
+    /// shows a result regardless of whether the code was found.
     fn read_callback(stream: &mut TcpStream) -> std::io::Result<String> {
         let mut buf = [0u8; 4096];
         let n = stream.read(&mut buf)?;
@@ -38,6 +56,9 @@ impl LoopbackServer {
         code.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidData, "code not found in callback"))
     }
 
+    /// Extract and percent-decode the `code` query parameter from an HTTP request line.
+    ///
+    /// Return: `None` if the request is malformed or has no `code` param.
     fn extract_code(request: &str) -> Option<String> {
         let line = request.lines().next()?;
         let path = line.split(' ').nth(1)?;
@@ -52,6 +73,11 @@ impl LoopbackServer {
     }
 }
 
+/// Percent-decode a string (e.g. `%20` -> space).
+///
+/// Why: invalid escape sequences (missing/non-hex digits) are passed through
+/// literally as `%` rather than erroring, since this only handles a redirect
+/// query param, not untrusted binary data.
 fn urlencoding(s: &str) -> String {
     let mut result = String::with_capacity(s.len());
     let mut chars = s.chars();

src/service/oauth/manager.rs

@@ -1,6 +1,9 @@
+//! OAuth 2.0 authorization-code + PKCE flow: token exchange and authorization URL building.
+
 use std::time::{SystemTime, UNIX_EPOCH};
 use serde::{Deserialize, Serialize};
 
+/// An OAuth access token plus its refresh token and absolute expiry (unix seconds).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct OAuthToken {
     pub access_token: String,
@@ -12,6 +15,7 @@ pub struct OAuthToken {
 impl OAuthToken {
 }
 
+/// Static configuration for an OAuth provider: endpoints, client identity, and requested scopes.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct OAuthConfig {
     pub auth_url: String,
@@ -33,6 +37,7 @@ impl Default for OAuthConfig {
     }
 }
 
+/// Drives one OAuth flow: holds config, the current token (if any), and an HTTP client.
 pub struct OAuthManager {
     pub config: OAuthConfig,
     pub token: Option<OAuthToken>,
@@ -40,6 +45,7 @@ pub struct OAuthManager {
 }
 
 impl OAuthManager {
+    /// Create a manager for the given provider config with no token yet acquired.
     pub fn new(config: OAuthConfig) -> Self {
         OAuthManager {
             config,
@@ -48,6 +54,12 @@ impl OAuthManager {
         }
     }
 
+    /// Exchange an authorization code for an access token via the provider's token endpoint.
+    ///
+    /// Flow: POST form-encoded grant to `token_url` → parse JSON body →
+    /// compute absolute `expires_at` from `expires_in` → store on `self.token`.
+    ///
+    /// Return: `Err(String)` on network failure, non-2xx status, or a missing `access_token` field.
     pub fn exchange_code(&mut self, code: &str, redirect_uri: &str, code_verifier: &str) -> Result<(), String> {
         let mut params = std::collections::HashMap::new();
         params.insert("grant_type", "authorization_code");
@@ -83,13 +95,17 @@ impl OAuthManager {
         Ok(())
     }
 
+    /// Build the provider's authorization URL with PKCE and state params attached.
+    ///
+    /// Why: refuses to build a URL if `auth_url` is missing or invalid. Previously
+    /// this silently fell back to https://example.com, which produced a valid-looking
+    /// auth URL pointing at the wrong server and leaked client credentials in
+    /// query params. Returning an empty string signals failure to callers, who
+    /// can prompt the user to fix the OAuth config instead of starting a flow
+    /// against a wrong host.
+    ///
+    /// Return: the full authorization URL, or `""` if `auth_url` is empty/unparseable.
     pub fn build_auth_url(&self, redirect_uri: &str, state: &str, code_challenge: &str) -> String {
-        // Refuse to build a URL if `auth_url` is missing or invalid. Previously this
-        // silently fell back to https://example.com, which produced a valid-looking
-        // auth URL pointing at the wrong server and leaked client credentials in
-        // query params. Returning an empty string signals failure to callers, who
-        // can prompt the user to fix the OAuth config instead of starting a flow
-        // against a wrong host.
         let mut url = match url::Url::parse(&self.config.auth_url) {
             Ok(u) if !self.config.auth_url.is_empty() => u,
             _ => {

src/service/oauth/mod.rs

@@ -1,3 +1,6 @@
+//! OAuth 2.0 authorization-code + PKCE support: verifier/challenge generation,
+//! the loopback redirect server, and the token-exchange manager.
+
 pub mod pkce;
 pub mod loopback;
 pub mod manager;

src/service/oauth/pkce.rs

@@ -1,20 +1,27 @@
+//! PKCE (Proof Key for Code Exchange) verifier/challenge pair generation for OAuth flows.
+
 use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
 use sha2::{Sha256, Digest};
 
 const VERIFIER_LENGTH: usize = 64;
 
+/// A randomly generated, base64url-encoded PKCE code verifier.
 pub struct CodeVerifier(String);
 
 impl CodeVerifier {
+    /// Generate a fresh random code verifier.
     pub fn new() -> Self {
         let bytes: Vec<u8> = (0..VERIFIER_LENGTH).map(|_| rand_byte()).collect();
         CodeVerifier(URL_SAFE_NO_PAD.encode(&bytes))
     }
 
+    /// Borrow the verifier as a string, to send in the token exchange request.
     pub fn as_str(&self) -> &str {
         &self.0
     }
 
+    /// Derive the S256 code challenge (SHA-256 hash, base64url-encoded) to send
+    /// in the authorization request.
     pub fn challenge(&self) -> CodeChallenge {
         let mut hasher = Sha256::new();
         hasher.update(self.0.as_bytes());
@@ -23,6 +30,11 @@ impl CodeVerifier {
     }
 }
 
+/// Produce one pseudo-random byte from the sub-second component of the system clock.
+///
+/// Why: avoids pulling in a `rand` dependency for a short-lived, non-cryptographic
+/// verifier; each byte only needs to be unpredictable enough to prevent code
+/// interception, not cryptographically secure.
 fn rand_byte() -> u8 {
     use std::time::{SystemTime, UNIX_EPOCH};
     let nanos = SystemTime::now()
@@ -35,9 +47,11 @@ fn rand_byte() -> u8 {
     (nanos & 0xFF) as u8
 }
 
+/// The S256-derived code challenge sent in the authorization request URL.
 pub struct CodeChallenge(String);
 
 impl CodeChallenge {
+    /// Borrow the challenge as a string.
     pub fn as_str(&self) -> &str {
         &self.0
     }

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,