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

@@ -1,3 +1,21 @@
+//! The `Action` enum and its single dispatcher, `apply_action` — the
+//! chokepoint through which every key input, streaming event, and async
+//! background-thread result mutates `AppStateRest`.
+//!
+//! Flow: controllers/subagent threads construct `Action` values → the event
+//! loop calls `apply_action(&mut state, action)` → for turn-producing
+//! actions (`SubmitInput`), `spawn_turn` is kicked off on a background OS
+//! thread which drives `run_agent_turn` (stream to the LLM, gate and
+//! execute tool calls via `Harness`, archive messages to SQLite, log edits)
+//! and pushes `TurnEvent`s onto a shared queue → on the next `Tick`, queued
+//! `TurnEvent`s are drained back into `AppStateRest` (transcript, toasts,
+//! usage counters).
+//!
+//! Why: keeping all state mutation behind one function means callers only
+//! need to know how to *produce* actions, not how to update state safely;
+//! running turns on plain OS threads (rather than blocking the main loop)
+//! keeps the TUI responsive while the LLM streams.
+
 use std::collections::VecDeque;
 
 use crate::app::harness::Verdict;
@@ -9,11 +27,14 @@ use crate::app::state::runtime::TurnEvent;
 use crate::app::state::types::{Origin, Overlay, Toast, ToastKind};
 use crate::dto::chat::message::{ChatMessage, Role};
 
-// Step bounds intentionally left unbounded (usize::MAX) so the agent can
-// continue across as many turns as needed. Each iteration still honours
-// `tc.abort_flag` and the per-call LLM timeout, so a runaway loop is
-// observable and cancellable from the UI.
-
+/// A single, well-typed event in the app — produced by key input, the
+/// streaming pipeline, or subagent threads — that mutates `AppStateRest`
+/// when applied via `apply_action`.
+///
+/// Step bounds intentionally left unbounded (usize::MAX) so the agent can
+/// continue across as many turns as needed. Each iteration still honours
+/// `tc.abort_flag` and the per-call LLM timeout, so a runaway loop is
+/// observable and cancellable from the UI.
 #[derive(Debug, Clone)]
 pub enum Action {
     ForceQuit,
@@ -63,6 +84,18 @@ pub enum Action {
     AbortTurn,
 }
 
+/// Apply an `Action` to the application state.
+///
+/// Flow: pattern-match the variant → mutate `state` (input buffer, scroll
+/// position, overlay, transcript, runtime, toasts, dirty flag, etc.) →
+/// for `Tick`, also drain queued `TurnEvent`s and run periodic side jobs
+/// (staleness sweep, pending-lesson commit).
+///
+/// Why: the single chokepoint that turns every typed key and async event
+/// into a state change, so callers (controllers, subagent threads) only
+/// need to know how to *produce* actions.
+///
+/// Return: nothing; `state` is mutated in place.
 pub fn apply_action(state: &mut AppStateRest, action: Action) {
     match action {
         Action::ForceQuit => {
@@ -449,6 +482,19 @@ pub fn apply_action(state: &mut AppStateRest, action: Action) {
     }
 }
 
+/// Spawn a background thread that runs one full LLM turn.
+///
+/// Flow: check that no turn is currently in-flight → bail if so →
+/// collect messages and config from state → determine API key (from
+/// settings, env var, or default) → resolve generation params from
+/// the current effort level → collect all tools (built-in + MCP) →
+/// build `TurnCtx` → spawn a thread running `run_agent_turn` →
+/// on any error, push a `TurnEvent::Error` → clear the in-flight flag
+/// when the thread exits.
+///
+/// Why: runs on a plain OS thread so the async event loop stays responsive.
+///
+/// Return: nothing; results flow through `state.turn_events`.
 fn spawn_turn(state: &AppStateRest) {
     let in_flight = if let Ok(guard) = state.turn_in_flight.lock() {
         *guard
@@ -532,6 +578,7 @@ fn spawn_turn(state: &AppStateRest) {
     });
 }
 
+/// Context bundle passed to `run_agent_turn` on its background thread.
 struct TurnCtx {
     client: crate::service::provider::LlmClient,
     tdefs: Vec<crate::dto::provider::request::ToolDef>,
@@ -547,6 +594,14 @@ struct TurnCtx {
     abort_flag: std::sync::Arc<std::sync::atomic::AtomicBool>,
 }
 
+/// Build an ASCII tree of the workspace directory structure for the
+/// system prompt, so the LLM can see the file layout.
+///
+/// Flow: for each root, walk using `ignore::WalkBuilder` (respecting
+/// `.gitignore` and hidden files) → prefix `[DIR]` for directories →
+/// truncate after 1000 entries.
+///
+/// Return: a formatted string with one entry per line.
 fn generate_workspace_tree(roots: &[std::path::PathBuf]) -> String {
     let mut out = String::new();
     out.push_str("Current Workspace Directory Structure:\n");
@@ -575,6 +630,11 @@ fn generate_workspace_tree(roots: &[std::path::PathBuf]) -> String {
     out
 }
 
+/// Persist a `ChatMessage` to the SQLite message log, if a database
+/// connection is available.
+///
+/// Flow: if `db` is `Some`, lock the mutex and call `insert_message`.
+/// Errors are silently ignored.
 fn archive_message(db: &Option<std::sync::Arc<std::sync::Mutex<rusqlite::Connection>>>, session_id: &str, msg: &ChatMessage) {
     if let Some(ref arc) = db {
         if let Ok(conn) = arc.lock() {
@@ -583,6 +643,28 @@ fn archive_message(db: &Option<std::sync::Arc<std::sync::Mutex<rusqlite::Connect
     }
 }
 
+/// Execute one full agent turn: stream the conversation to the LLM,
+/// handle tool calls, and loop until the LLM produces a non-tool response
+/// or runs out of unfinished todo items.
+///
+/// Flow: build system prompt with workspace tree → optionally shape
+/// (compact) messages via `shortsend` → call `chat_with_tools_streaming`
+/// with a callback that pushes `StreamStart`, `StreamToken`, `Reasoning`,
+/// and `Usage` events → on streaming success, handle tool calls (gated
+/// through `Harness::gate_tool_call`) or unwrap the final assistant
+/// message → check for unfinished todo.md tasks (auto-retry with a
+/// system message if any remain) → finalise with `Done` and an `edits`
+/// SystemNote.
+///
+/// On streaming failure: retry once with a non-streaming call → if that
+/// also fails and there are unfinished tasks, sleep 5s and loop back;
+/// otherwise return the error.
+///
+/// Why: non-streaming fallback handles flaky connections without aborting
+/// the turn; todo.md polling lets the agent self-direct toward completeness.
+///
+/// Return: `Ok(())` on successful completion, or an error from the LLM
+/// API after retries are exhausted.
 fn run_agent_turn(
     tc: TurnCtx,
     messages: &[ChatMessage],
@@ -836,6 +918,20 @@ fn run_agent_turn(
     Ok(())
 }
 
+/// Execute a single tool call: find the tool by name, snapshot the file
+/// (if write/edit) for rewind, run the tool, log an `EditLogEntry` for
+/// write/edit, and return the output.
+///
+/// Flow: iterate tools → match by name → for write/edit, snapshot the
+/// pre-existing file content into the blob store → call `tool.run()` →
+/// for write/edit, compute SHA-256 of the new content and append an
+/// `EditLogEntry` → return the tool output string.
+///
+/// Why: snapshots enable the rewind feature to restore previous content
+/// after a write/edit.
+///
+/// Return: the tool's stdout string, or an error if no matching tool was
+/// found or the tool run itself failed.
 #[allow(clippy::too_many_arguments)]
 fn execute_one_tool(
     tools: &[Box<dyn crate::tool::Tool>],
@@ -910,6 +1006,15 @@ fn execute_one_tool(
     anyhow::bail!("tool not found: {}", name)
 }
 
+/// Optionally push a review-available toast at the end of a turn that
+/// performed edits.
+///
+/// Flow: skip if review is disabled → skip if `edit_count` is zero →
+/// push an info toast listing the number of modified files.
+///
+/// Why: does not launch the review itself (that happens inside
+/// `should_trigger_review` on `Tick`), only informs the user that
+/// a review has material to examine.
 fn maybe_trigger_review(state: &mut AppStateRest) {
     if !state.settings.review_enabled {
         return;
@@ -928,6 +1033,13 @@ fn maybe_trigger_review(state: &mut AppStateRest) {
     ));
 }
 
+/// Persist the current session metadata and conversation to disk.
+///
+/// Flow: build a `Session` object → save its metadata → write
+/// `rt.messages` as JSON to the conversation file → errors are silently
+/// ignored.
+///
+/// Why: called on `ForceQuit` so the session can be resumed later.
 fn save_current_session(state: &AppStateRest) {
     let base = state.store_base_dir();
     let session = crate::model::session::Session::new(
@@ -943,6 +1055,20 @@ fn save_current_session(state: &AppStateRest) {
     }
 }
 
+/// Run a browser-based OAuth PKCE flow for the given provider.
+///
+/// Flow: look up config by provider name ("zen"/"opencode", "openai",
+/// or a custom provider via env vars) → bind a loopback server → generate
+/// a PKCE code verifier and challenge → build the authorisation URL →
+/// wait for the redirect code on the loopback server (with a 120s timeout)
+/// → exchange the code for a token → save the token to
+/// `~/.config/zesdex/oauth_{provider}.json`.
+///
+/// Why: the `webbrowser::open` call is currently commented out; the user
+/// must open the auth URL manually until that line is reinstated.
+///
+/// Return: a success message on completion, or an error if the flow fails
+/// at any step.
 fn run_oauth_flow(provider: &str) -> anyhow::Result<String> {
     use crate::service::oauth::manager::{OAuthConfig, OAuthManager};
     use crate::service::oauth::loopback::LoopbackServer;
@@ -1013,6 +1139,11 @@ fn run_oauth_flow(provider: &str) -> anyhow::Result<String> {
     Ok(format!("Successfully authenticated with {}.", provider))
 }
 
+/// Generate `n` pseudo-random bytes from the current sub-second timestamp.
+///
+/// Why: avoids pulling in a full RNG crate for the OAuth state token;
+/// sufficient for a nonce that only needs to be unpredictable over the
+/// lifetime of a single OAuth flow.
 fn rand_bytes(n: usize) -> Vec<u8> {
     use std::time::{SystemTime, UNIX_EPOCH};
     let seed = SystemTime::now().duration_since(UNIX_EPOCH).unwrap_or_default().subsec_nanos();

src/app/runtime/commands.rs

@@ -1,7 +1,18 @@
+//! Maps parsed `/` slash commands into one or more `Action` variants
+//! that `apply_action` can process.
 use crate::controller::command::Command;
 use crate::app::runtime::actions::Action;
 use crate::app::state::types::Overlay;
 
+/// Convert a parsed `Command` into the corresponding sequence of `Action`s.
+///
+/// Flow: match each `Command` variant to its handler — most produce a
+/// single `Action` (open an overlay, dispatch an OAuth flow, open the
+/// editor, etc.); some produce an `Action::SystemNote` for errors or
+/// informational responses.
+///
+/// Return: a `Vec<Action>` (always non-empty) to be applied sequentially
+/// by `apply_action`.
 pub fn apply_command(command: Command) -> Vec<Action> {
     match command {
         Command::Help => {

src/app/runtime/event_loop/mod.rs

@@ -1,3 +1,5 @@
+//! Adaptive poll-rate event loop: polls faster for IDLE_THRESHOLD_MS
+//! after any activity, then slows down to conserve CPU.
 use std::collections::VecDeque;
 use std::time::{Duration, Instant};
 
@@ -7,12 +9,15 @@ const FAST_POLL_MS: u64 = 8;
 const SLOW_POLL_MS: u64 = 100;
 const IDLE_THRESHOLD_MS: u64 = 500;
 
+/// Tracks whether the app has been active vs idle to adjust the TUI poll
+/// rate, balancing responsiveness against CPU usage.
 pub struct EventLoop {
     last_activity: Instant,
     fast_poll_until: Option<Instant>,
 }
 
 impl EventLoop {
+    /// Create an `EventLoop` with the current instant as the last activity.
     pub fn new() -> Self {
         EventLoop {
             last_activity: Instant::now(),
@@ -20,6 +25,10 @@ impl EventLoop {
         }
     }
 
+    /// Return the appropriate polling delay based on activity state.
+    ///
+    /// Flow: if `fast_poll_until` is set and the deadline hasn't expired,
+    /// return `FAST_POLL_MS`; otherwise return `SLOW_POLL_MS`.
     pub fn poll_interval(&self) -> Duration {
         if let Some(fast_until) = self.fast_poll_until {
             if Instant::now() < fast_until {
@@ -29,15 +38,21 @@ impl EventLoop {
         Duration::from_millis(SLOW_POLL_MS)
     }
 
+    /// Mark the current time as the last activity and arm the fast-poll
+    /// window for the next `IDLE_THRESHOLD_MS`.
     pub fn mark_active(&mut self) {
         self.last_activity = Instant::now();
         self.fast_poll_until = Some(Instant::now() + Duration::from_millis(IDLE_THRESHOLD_MS));
     }
 
+    /// Return `true` if the app has been idle for more than `IDLE_THRESHOLD_MS`.
     pub fn is_idle(&self) -> bool {
         self.last_activity.elapsed().as_millis() as u64 > IDLE_THRESHOLD_MS
     }
 
+    /// Drain all pending `TurnEvent`s from the shared mutex queue.
+    ///
+    /// Return: a `Vec` of all events that were in the queue (may be empty).
     pub fn drain_events(
         events: &std::sync::Mutex<VecDeque<TurnEvent>>,
     ) -> Vec<TurnEvent> {

src/app/runtime/mod.rs

@@ -1,3 +1,5 @@
+//! Runtime layer: action dispatch, slash commands, short-send handling,
+//! and the LLM streaming pipeline.
 pub mod actions;
 pub mod commands;
 pub mod shortsend;

src/app/runtime/shortsend.rs

@@ -1,9 +1,20 @@
+//! Short-send / message shaping: compacts long conversation histories so
+//! they fit within the provider's context window before being sent to the
+//! LLM API.
 use crate::dto::chat::message::ChatMessage;
 
 const MAX_WIRE_TOKENS: usize = 2_000_000;
 const MIN_MESSAGES_BEFORE_SHAPE: usize = 20;
 const ENGAGE_HYSTERESIS: usize = 5;
 
+/// Decide whether the message list should be shaped (compacted) before
+/// sending to the LLM.
+///
+/// Flow: skip shaping if fewer than `MIN_MESSAGES_BEFORE_SHAPE` messages
+/// → once past that threshold, use hysteresis (require 5 more messages
+/// before re-engaging if shaping is currently active) to avoid oscillation.
+///
+/// Return: `true` if shaping should be applied.
 pub fn should_shape(total_messages: usize, prev_shaped: bool) -> bool {
     if total_messages < MIN_MESSAGES_BEFORE_SHAPE {
         return false;
@@ -16,6 +27,19 @@ pub fn should_shape(total_messages: usize, prev_shaped: bool) -> bool {
     total_messages >= threshold
 }
 
+/// Compact a long message list by dropping middle messages and inserting
+/// a summary placeholder.
+///
+/// Flow: if the estimated token count is within budget, return messages
+/// unchanged → otherwise keep the system message and the most recent
+/// messages (up to `MAX_WIRE_TOKENS / 200` of them) with a `[prior
+/// conversation compacted]` system message in between.
+///
+/// Why: keeps context-size overhead roughly constant regardless of
+/// session length.
+///
+/// Return: a new Vec<ChatMessage> that preserves the first message and
+/// the tail.
 pub fn shape_messages(messages: &[ChatMessage], token_count: usize) -> Vec<ChatMessage> {
     if token_count <= MAX_WIRE_TOKENS || messages.len() < 10 {
         return messages.to_vec();

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()?;

src/app/runtime/stream/tools/mod.rs

@@ -1,3 +1,16 @@
+//! Standalone accumulator for streamed tool-call deltas.
+//!
+//! Flow: `ToolCallAccumulator::add_delta` is fed incremental `(index, id,
+//! name, arguments_delta)` chunks as they arrive over SSE → grows its
+//! internal `Vec<ParsedToolCall>` as needed → `is_complete` reports once
+//! every accumulated call has both a name and arguments.
+//!
+//! Why: mirrors the accumulation logic built into `StreamedTurn::apply_event`
+//! but as an independent, reusable type for callers that want to track
+//! tool-call deltas without a full `StreamedTurn` (e.g. a lighter-weight
+//! preview). Currently unused (`#[allow(dead_code)]`), kept for that future
+//! use case.
+
 use super::turn::ParsedToolCall;
 use serde_json::{json, Value};
 
@@ -11,10 +24,15 @@ pub struct ToolCallAccumulator {
 
 #[allow(dead_code)]
 impl ToolCallAccumulator {
+    /// Construct an empty accumulator with no tool calls tracked yet.
+    ///
+    /// Return: a fresh `ToolCallAccumulator`.
     pub fn new() -> Self {
         ToolCallAccumulator { calls: Vec::new() }
     }
 
+    /// Append a delta to the tool call at the given index, growing the
+    /// calls vector if needed.
     pub fn add_delta(
         &mut self,
         index: usize,
@@ -44,18 +62,23 @@ impl ToolCallAccumulator {
         tc.arguments.push_str(arguments_delta);
     }
 
+    /// Borrow the accumulated tool calls.
     pub fn calls(&self) -> &[ParsedToolCall] {
         &self.calls
     }
 
+    /// Return true once all tool calls have both a name and arguments.
     pub fn is_complete(&self) -> bool {
         !self.calls.is_empty() && self.calls.iter().all(|tc| !tc.name.is_empty() && !tc.arguments.is_empty())
     }
 
+    /// Clear all accumulated calls (starting a fresh turn).
     pub fn reset(&mut self) {
         self.calls.clear();
     }
 
+    /// Build a JSON-serialisable `Vec<Value>` of pending (non-empty-name)
+    /// tool calls, suitable for downstream inspection or replay.
     pub fn pending_args(&self) -> Vec<Value> {
         self.calls
             .iter()

src/app/runtime/stream/turn.rs

@@ -1,9 +1,14 @@
+//! Accumulates streaming LLM responses into complete message/tool-call
+//! representation via `StreamedTurn`, and provides a standalone tool-call
+//! accumulator in `tools::ToolCallAccumulator`.
 use super::StreamEvent;
 use crate::dto::chat::message::ChatMessage;
 use crate::dto::chat::tool::{ToolCall, ToolFunction};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
+/// Accumulates a single streaming assistant turn into its final
+/// `ChatMessage` form, including tool-call deltas and content/reasoning.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct StreamedTurn {
     pub messages: Vec<ChatMessage>,
@@ -13,6 +18,7 @@ pub struct StreamedTurn {
     pub accumulated_reasoning: String,
 }
 
+/// A single tool call being built up from streaming deltas.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ParsedToolCall {
     pub id: String,
@@ -22,9 +28,11 @@ pub struct ParsedToolCall {
 }
 
 impl ParsedToolCall {
-    /// Attempts to parse the accumulated argument string as JSON before the tool call is
-    /// marked complete — useful for callers that want a speculative preview mid-stream.
-    /// `build_assistant_message` does its own (lossy-fallback) parse for the final message.
+    /// Attempt to parse the accumulated argument string as JSON before
+    /// the tool call is marked complete — useful for a speculative preview.
+    ///
+    /// Return: `Some(Value)` if the arguments are parsable JSON, `None`
+    /// if still partial.
     #[allow(dead_code)]
     pub fn try_parse(&self) -> Option<Value> {
         serde_json::from_str(&self.arguments).ok()
@@ -32,6 +40,7 @@ impl ParsedToolCall {
 }
 
 impl StreamedTurn {
+    /// Create an empty turn accumulator.
     pub fn new() -> Self {
         StreamedTurn {
             messages: Vec::new(),
@@ -42,6 +51,12 @@ impl StreamedTurn {
         }
     }
 
+    /// Apply a `StreamEvent` to the turn, updating accumulated content,
+    /// reasoning, and tool-call deltas.
+    ///
+    /// Flow: match on variant — `Token` appends to `accumulated_content`,
+    /// `Reasoning` to `accumulated_reasoning`, `ToolCallDelta` fills or
+    /// grows the `tool_calls` vector, `Done` sets `is_complete = true`.
     pub fn apply_event(&mut self, event: &StreamEvent) {
         match event {
             StreamEvent::Token(token) => {
@@ -84,6 +99,14 @@ impl StreamedTurn {
         }
     }
 
+    /// Finalise the turn into a `ChatMessage`, combining accumulated
+    /// reasoning (wrapped in `<think>` tags) with content and tool calls.
+    ///
+    /// Flow: if tool calls exist, build a `ChatMessage` with `tool_calls`
+    /// set; otherwise build a plain assistant message → set `content` to
+    /// the combined reasoning+content string (or `None` if empty).
+    ///
+    /// Return: a complete `ChatMessage` with role `Assistant`.
     pub fn build_assistant_message(&self) -> ChatMessage {
         let mut msg = if self.tool_calls.is_empty() {
             ChatMessage::assistant(None)