Enhance logging and documentation across utility tools and TUI overlays

- Added tracing instrumentation and improved logging messages in the Pong, Todofinish, and Todowrite tools for better debugging and monitoring.
- Enhanced documentation comments for clarity on tool functionalities and workflows.
- Implemented tracing in WorkflowRun, NoteFinding, ReadFindings, and HiveMind tools to track execution phases and findings.
- Updated TUI overlays (e.g., Bash, Clear Confirm, Editor, Effort Level, Help, Key Input, Learning, Loading, MCP, Model Selector, Plan, Quit Confirm, Rewind, Settings, Todo, Usage) with debug logging to capture rendering details.
- Improved the status bar and workflow panel rendering with additional debug information.
- Added tracing to various utility functions to facilitate better performance monitoring and error tracking.

apps/interfaces/tui/src/view/overlays/bash.rs

@@ -4,14 +4,17 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the Bash Jobs overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    debug!("Rendering Bash Jobs overlay");
     let block = super::overlay_block(block, "Bash Jobs", Theme::ACCENT_ORANGE);
     let lines: Vec<Line> = state
         .session_runtime

apps/interfaces/tui/src/view/overlays/clear_confirm.rs

@@ -4,14 +4,17 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the Clear Transcript confirmation dialog.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     _state: &crate::state::AppStateRest,
 ) {
+    debug!("Rendering Clear Transcript confirmation overlay");
     let block = block
         .title(Span::styled(
             " Clear Transcript ",

apps/interfaces/tui/src/view/overlays/editor.rs

@@ -5,14 +5,17 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the Editor overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    debug!("Rendering Editor overlay, buffer length: {}", state.input.buffer.len());
     let block = block
         .title(Span::styled(
             " Editor ",

apps/interfaces/tui/src/view/overlays/effort.rs

@@ -5,14 +5,18 @@ use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
+use tracing::debug;
 
 /// Render the Effort Level overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    let current_idx = current_effort(state);
+    debug!("Rendering Effort Level overlay, current idx: {current_idx}");
     let block = block
         .title(Span::styled(
             " Effort Level ",

apps/interfaces/tui/src/view/overlays/help.rs

@@ -3,14 +3,17 @@ use ratatui::style::Style;
 use ratatui::widgets::{Block, Paragraph, Wrap};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the Help overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    debug!("Rendering Help overlay, content length: {}", state.help_text.len());
     let block = super::overlay_block(block, "Help", Theme::INFO);
     let content = state.help_text;
     let paragraph = Paragraph::new(content)

apps/interfaces/tui/src/view/overlays/key_input.rs

@@ -5,14 +5,18 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the API Key input overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    let char_count = state.input.buffer.chars().count();
+    debug!("Rendering API Key overlay, char count: {char_count}");
     let block = block
         .title(Span::styled(
             " API Key ",

apps/interfaces/tui/src/view/overlays/learning.rs

@@ -7,14 +7,18 @@ use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Borders, Paragraph, Wrap};
 use ratatui::Frame;
+use tracing::debug;
 
 /// Render the Learning overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    let items = get_learning_items(state);
+    debug!("Rendering Learning overlay, {} items", items.len());
     drop(block);
 
     let h_chunks = Layout::default()

apps/interfaces/tui/src/view/overlays/loading.rs

@@ -4,14 +4,17 @@ use ratatui::text::Span;
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the Loading overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    debug!("Rendering Loading overlay, tick: {}", state.misc.tick_count);
     let block = block
         .title(Span::styled(
             " Loading ",

apps/interfaces/tui/src/view/overlays/mcp.rs

@@ -4,14 +4,17 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the MCP Servers overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    debug!("Rendering MCP Servers overlay, session dir: {}", state.session_dir.display());
     let block = block
         .title(Span::styled(
             " MCP Servers ",

apps/interfaces/tui/src/view/overlays/mod.rs

@@ -26,6 +26,7 @@ use ratatui::text::Span;
 use ratatui::widgets::{Block, Borders, Clear};
 use ratatui::Frame;
 use super::theme::Theme;
+use tracing::debug;
 
 /// Decorate an overlay block with a styled title and matching border color.
 pub fn overlay_block(block: Block<'static>, title: &str, color: ratatui::style::Color) -> Block<'static> {
@@ -53,12 +54,17 @@ pub fn centered_rect(area: Rect, percent_x: u16, percent_y: u16) -> Rect {
 }
 
 /// Render the active modal overlay as a centered panel.
+///
+/// Dispatches to the appropriate overlay module's `render` function based on the
+/// `Overlay` variant. No-ops for `Overlay::None`.
+#[tracing::instrument(skip(frame, state))]
 pub fn render_overlay(
     frame: &mut Frame,
     area: Rect,
     overlay: Overlay,
     state: &AppStateRest,
 ) {
+    debug!("Rendering overlay: {overlay:?}");
     let overlay_area = centered_rect(area, 75, 70);
     frame.render_widget(Clear, overlay_area);
 

apps/interfaces/tui/src/view/overlays/model_selector.rs

@@ -5,14 +5,17 @@ use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
+use tracing::debug;
 
 /// Render the Model Selector overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    debug!("Rendering Model Selector overlay, current provider: {}, model: {}", state.settings.provider, state.settings.model);
     let block = block
         .title(Span::styled(
             " Model Selector ",

apps/interfaces/tui/src/view/overlays/plan.rs

@@ -4,14 +4,18 @@ use ratatui::text::Span;
 use ratatui::widgets::{Block, Paragraph, Wrap};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the Project Plan overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    let has_content = !state.misc.plan_content.is_empty();
+    debug!("Rendering Project Plan overlay, has content: {has_content}");
     let block = block
         .title(Span::styled(
             " Project Plan ",

apps/interfaces/tui/src/view/overlays/quit_confirm.rs

@@ -4,14 +4,17 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the Quit confirmation overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     _state: &crate::state::AppStateRest,
 ) {
+    debug!("Rendering Quit confirmation overlay");
     let block = block
         .title(Span::styled(
             " Quit ",

apps/interfaces/tui/src/view/overlays/rewind.rs

@@ -5,15 +5,19 @@ use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
+use tracing::debug;
 use zesdex_domain::core::Role;
 
 /// Render the Rewind overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    let msg_count = state.transcript_cache.messages.len();
+    debug!("Rendering Rewind overlay, {} messages", msg_count);
     let block = block
         .title(Span::styled(
             " Rewind ",

apps/interfaces/tui/src/view/overlays/settings.rs

@@ -5,14 +5,17 @@ use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the Settings overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    debug!("Rendering Settings overlay, provider: {}, model: {}", state.settings.provider, state.settings.model);
     let block = super::overlay_block(block, "Settings", Theme::PRIMARY);
     let lines = vec![
         Line::from(Span::styled(

apps/interfaces/tui/src/view/overlays/todo.rs

@@ -4,14 +4,18 @@ use ratatui::text::Span;
 use ratatui::widgets::{Block, Paragraph, Wrap};
 use ratatui::Frame;
 use crate::view::theme::Theme;
+use tracing::debug;
 
 /// Render the Tasks / Todo overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    let has_content = !state.misc.todo_content.is_empty();
+    debug!("Rendering Tasks overlay, has content: {has_content}");
     let block = block
         .title(Span::styled(
             " Tasks ",

apps/interfaces/tui/src/view/overlays/usage.rs

@@ -6,14 +6,18 @@ use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
+use tracing::debug;
 
 /// Render the Usage overlay.
+#[tracing::instrument(skip_all)]
 pub fn render(
     frame: &mut Frame,
     area: ratatui::layout::Rect,
     block: Block<'static>,
     state: &crate::state::AppStateRest,
 ) {
+    let has_runtime = state.session_runtime.is_some();
+    debug!("Rendering Usage overlay, has runtime: {has_runtime}");
     let block = block
         .title(Span::styled(
             " Usage ",

apps/interfaces/tui/src/view/sidebar.rs

@@ -134,6 +134,10 @@ fn draw_usage_widget(frame: &mut Frame, area: Rect, state: &crate::state::AppSta
     frame.render_widget(paragraph, area);
 }
 
+/// Aggregated usage statistics for the current session.
+///
+/// Separates main (chat) and self-learning (review) token counts from
+/// the raw `UsageStats` and adds a human-readable elapsed-time breakdown.
 pub(crate) struct UsageSummary {
     pub main_tokens: u64,
     pub self_learning_tokens: u64,
@@ -144,6 +148,11 @@ pub(crate) struct UsageSummary {
     pub elapsed_seconds: i64,
 }
 
+/// Compute a human-friendly usage summary from raw `UsageStats`.
+///
+/// Fields: total_tokens = tokens_in + tokens_out, self_learning = review_tokens,
+/// main = total - self_learning. Elapsed time is broken into hours/minutes/seconds.
+#[tracing::instrument]
 pub(crate) fn compute_usage_summary(
     usage: &zesdex_domain::core::UsageStats,
     session_start: i64,

apps/interfaces/tui/src/view/status.rs

@@ -10,8 +10,13 @@ use ratatui::style::{Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::Block;
 use ratatui::Frame;
+use tracing::instrument;
 
-/// Render the single-line status bar.
+/// Render the single-line status bar at the bottom of the terminal.
+///
+/// Three visual segments: left (app name + PROG/READY/NOAPI badge),
+/// center (lesson indicator), right (token count, provider, model).
+#[instrument(skip_all)]
 pub fn draw_status_bar(frame: &mut Frame, area: Rect, state: &crate::state::AppStateRest) {
     use ratatui::layout::{Alignment, Constraint, Direction, Layout};
     let spinner_frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];

apps/interfaces/tui/src/view/workflow.rs

@@ -6,6 +6,7 @@ use ratatui::style::{Color, Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Borders, Paragraph, Wrap};
 use ratatui::Frame;
+use tracing::{debug, instrument};
 
 fn state_icon(state: AgentState) -> &'static str {
     match state {
@@ -34,12 +35,18 @@ fn state_color(state: AgentState) -> Color {
     }
 }
 
-/// Render the workflow status panel.
+/// Render the workflow status panel showing agent cards and a header.
+///
+/// Flow: render titled block → split into header (command hint + status)
+/// and body (agent cards with icon/name/label/duration, or session stats
+/// when no workflow is running).
+#[instrument(skip_all)]
 pub fn draw_workflow_panel(
     frame: &mut Frame,
     area: Rect,
     state: &crate::state::AppStateRest,
 ) {
+    debug!("draw_workflow_panel — rendering workflow panel");
     use ratatui::layout::{Constraint, Direction, Layout};
 
     let title = Span::styled(
@@ -157,6 +164,11 @@ pub fn draw_workflow_panel(
     }
 }
 
+/// Build placeholder lines for the workflow panel body when no agents are running.
+///
+/// Shows session stats (message count, tool calls, pending queue, bash jobs)
+/// or a "(no active session)" fallback.
+#[instrument(skip(state))]
 fn build_session_lines(state: &crate::state::AppStateRest) -> Vec<Line<'static>> {
     let mut lines: Vec<Line<'static>> = Vec::new();
     lines.push(Line::from(Span::styled(