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

@@ -1,3 +1,5 @@
+//! Provider-facing DTOs: chat completion request, response, and usage/cost.
+
 pub mod request;
 pub mod response;
 pub mod usage;

src/dto/provider/request.rs

@@ -1,6 +1,25 @@
+//! Outbound request DTOs for the OpenAI/Anthropic-compatible chat completions API.
+//!
+//! Flow: `harness`/`runtime` builds a `ChatRequest` from conversation state and
+//! the active tool set → serializes to JSON via `serde` → sends to the
+//! provider's `/chat/completions`-style endpoint (streaming or not).
+//!
+//! Why: fields mirror the wire format exactly (including `#[serde(rename)]`
+//! for reserved words like `type`) so no manual (de)serialization glue is
+//! needed; optional fields use `skip_serializing_if` so unset knobs are
+//! omitted rather than sent as `null`, matching provider expectations.
+
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
+/// Outbound chat completion request body sent to an OpenAI/Anthropic-compatible provider.
+///
+/// Flow: constructed from the current message history plus optional
+/// generation knobs (temperature, max_tokens, tools, etc.) and serialized
+/// directly into the HTTP request body.
+///
+/// Return: not a function, but the value that becomes the JSON request
+/// payload for a completion call.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChatRequest {
     pub model: String,
@@ -21,11 +40,21 @@ pub struct ChatRequest {
     pub stream_options: Option<StreamOptions>,
 }
 
+/// Streaming options for the request; `include_usage` asks the provider to
+/// emit a final usage chunk in the SSE stream.
+///
+/// Why: usage tokens are otherwise unavailable in a streamed response since
+/// they're normally only attached to the final non-streamed completion.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct StreamOptions {
     pub include_usage: bool,
 }
 
+/// Wire format for a single tool definition sent to the provider.
+///
+/// Flow: built from the harness's registered `Tool` impls (see `all_tools()`)
+/// and attached to `ChatRequest.tools` so the model knows which functions it
+/// may call.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolDef {
     #[serde(rename = "type")]
@@ -33,6 +62,10 @@ pub struct ToolDef {
     pub function: ToolFunctionDef,
 }
 
+/// Name, description, and JSON schema parameters for a tool definition.
+///
+/// Why: `parameters` is a raw `serde_json::Value` rather than a typed struct
+/// because each tool defines its own arbitrary JSON schema.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolFunctionDef {
     pub name: String,

src/dto/provider/response.rs

@@ -1,5 +1,21 @@
+//! Inbound response DTOs for the non-streaming chat completions API.
+//!
+//! Flow: provider HTTP response body → `serde_json` deserializes into
+//! `ChatResponse` → caller reads `choices[0].message` for the assistant
+//! reply and `usage` for token accounting.
+//!
+//! Why: separate from the streaming SSE path (see `app/runtime/stream/mod.rs`),
+//! which parses incremental deltas rather than a single complete payload.
+
 use serde::{Deserialize, Serialize};
 
+/// Non-streaming chat completion response returned by the provider.
+///
+/// Flow: deserialized directly from the HTTP response body of a
+/// non-streaming completion call.
+///
+/// Return: not a function, but the value callers inspect for the model's
+/// reply (`choices`) and token usage (`usage`).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChatResponse {
     pub id: String,
@@ -9,6 +25,10 @@ pub struct ChatResponse {
     pub created: Option<i64>,
 }
 
+/// One completion candidate within a `ChatResponse.choices` list.
+///
+/// Why: `finish_reason` is optional/string-typed since providers vary in
+/// what values they emit (e.g. `"stop"`, `"tool_calls"`, `"length"`).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Choice {
     pub index: u32,

src/dto/provider/usage.rs

@@ -1,5 +1,18 @@
+//! Token usage accounting DTO shared by streaming and non-streaming responses.
+//!
+//! Flow: populated from the provider's `usage` object (either the final SSE
+//! chunk when `stream_options.include_usage` is set, or the `usage` field of
+//! a non-streaming `ChatResponse`) → surfaced to the TUI for cost/token
+//! display.
+
 use serde::{Deserialize, Serialize};
 
+/// Token counts and optional cost breakdown for a single completion request.
+///
+/// Why: all fields are optional because providers differ in what they
+/// report — some omit per-token cost entirely, others omit usage altogether
+/// on certain response paths. `Default` lets callers start from an empty
+/// usage record when a provider sends none.
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 pub struct Usage {
     pub prompt_tokens: Option<u32>,