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/chat/message.rs

@@ -1,5 +1,9 @@
+//! Chat message types shared across the DTO layer: `Role` and `ChatMessage`
+//! with convenience constructors.
+
 use serde::{Deserialize, Serialize};
 
+/// The conversation participant who authored a message.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum Role {
     #[serde(rename = "user")]
@@ -15,6 +19,8 @@ pub enum Role {
 impl Role {
 }
 
+/// A single message in a conversation, compatible with the OpenAI/Anthropic
+/// chat-completion API structures.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChatMessage {
     pub role: Role,
@@ -28,6 +34,7 @@ pub struct ChatMessage {
 }
 
 impl ChatMessage {
+    /// Build a user-role message with the given text content.
     pub fn user(content: impl Into<String>) -> Self {
         ChatMessage {
             role: Role::User,
@@ -38,6 +45,7 @@ impl ChatMessage {
         }
     }
 
+    /// Build an assistant-role message with an optional text response.
     pub fn assistant(content: Option<String>) -> Self {
         ChatMessage {
             role: Role::Assistant,
@@ -48,6 +56,7 @@ impl ChatMessage {
         }
     }
 
+    /// Build a system-role message with the given instruction text.
     pub fn system(content: impl Into<String>) -> Self {
         ChatMessage {
             role: Role::System,
@@ -58,6 +67,7 @@ impl ChatMessage {
         }
     }
 
+    /// Build a tool-role result message referencing a prior tool call.
     pub fn tool_result(tool_call_id: String, content: String) -> Self {
         ChatMessage {
             role: Role::Tool,

src/dto/chat/mod.rs

@@ -1,2 +1,4 @@
+//! Chat DTO submodules: message roles/content and tool-call structures.
+
 pub mod message;
 pub mod tool;

src/dto/chat/tool.rs

@@ -1,6 +1,17 @@
+//! Tool-call DTOs embedded in assistant chat messages.
+//!
+//! Flow: provider response/stream carries `tool_calls` on an assistant
+//! message → deserialized into `ToolCall`/`ToolFunction` → harness resolves
+//! `function.name` against `all_tools()` and runs it with
+//! `sanitize_tool_arguments(function.arguments)`.
+//!
+//! Why: kept separate from `dto::provider` because tool calls are a property
+//! of a chat *message*, not of the request/response envelope.
+
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
+/// A single tool-call request emitted by the model in an assistant message.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolCall {
     pub id: String,
@@ -9,12 +20,23 @@ pub struct ToolCall {
     pub function: ToolFunction,
 }
 
+/// The function name and raw arguments payload for a `ToolCall`.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolFunction {
     pub name: String,
     pub arguments: Value,
 }
 
+/// Normalize tool-call arguments into a JSON object/value.
+///
+/// Flow: some providers send `arguments` as a JSON-encoded string rather
+/// than a nested object; if `args` is a string, attempt to parse it as
+/// JSON. Objects and other value types pass through unchanged.
+///
+/// Why: falling back to the raw string on parse failure (rather than
+/// erroring) keeps the harness resilient to malformed provider output.
+///
+/// Return: the parsed `Value`, or the original `args` clone if parsing fails.
 pub fn sanitize_tool_arguments(args: &Value) -> Value {
     match args {
         Value::String(s) => {

src/dto/mod.rs

@@ -1,2 +1,5 @@
+//! Data transfer objects shared across the app: chat messages/tool calls
+//! and provider request/response/usage shapes.
+
 pub mod chat;
 pub mod provider;

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>,