4runr-os 2.4.1 → 2.4.2

package/mk3-tui/src/app.rs

@@ -29,6 +29,35 @@ pub enum AppMode {
     Main,
 }
 
+#[derive(Debug, Clone)]
+pub struct AgentListState {
+    pub agents: Vec<AgentInfo>,
+    pub selected_index: usize,
+    pub detail_view: Option<usize>,  // None = list view, Some(index) = detail popup
+}
+
+impl Default for AgentListState {
+    fn default() -> Self {
+        Self {
+            agents: Vec::new(),
+            selected_index: 0,
+            detail_view: None,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct AgentInfo {
+    pub name: String,
+    pub description: Option<String>,
+    pub model: String,
+    pub provider: String,
+    pub system_prompt: Option<String>,
+    pub temperature: Option<f32>,
+    pub max_tokens: Option<u32>,
+    pub tools: Vec<String>,
+}
+
 #[derive(Debug, Clone)]
 pub struct AppState {
     // Navigation state (NEW - replaces simple mode)
@@ -96,6 +125,7 @@ pub struct AppState {
     pub agent_builder: AgentBuilderState,
     pub run_manager: RunManagerState,
     pub settings: SettingsState,
+    pub agent_list: AgentListState,
     
     // Local cache
     pub cache: Option<Cache>,
@@ -153,6 +183,7 @@ impl Default for AppState {
             agent_builder: AgentBuilderState::default(),
             run_manager: RunManagerState::default(),
             settings: SettingsState::default(),
+            agent_list: AgentListState::default(),
             cache: Cache::new().ok(),
             cache_loaded: false,
         }
@@ -339,6 +370,11 @@ impl App {
             return self.handle_settings_input(key);
         }
         
+        // === AGENT LIST INPUT HANDLING ===
+        if self.state.navigation.current_screen() == &Screen::AgentList {
+            return self.handle_agent_list_input(key);
+        }
+        
         // === MAIN INPUT HANDLING ===
         match key.code {
             // Typing - ALL characters go to command input (with debounce)
@@ -362,48 +398,9 @@ impl App {
                         "quit" | "exit" => return Ok(true),
                         "clear" => self.state.logs.clear(),
                         "help" => {
-                            self.state.logs.push_back("[HELP] ═══════════════════════════════════════".into());
-                            self.state.logs.push_back("[HELP] 4Runr AI Agent OS - Command Reference".into());
-                            self.state.logs.push_back("[HELP] ═══════════════════════════════════════".into());
-                            self.state.logs.push_back("".into());
-                            
-                            // Local Commands
-                            self.state.logs.push_back("[HELP] Local Commands:".into());
-                            self.state.logs.push_back("  quit, exit       - Exit application".into());
-                            self.state.logs.push_back("  clear            - Clear logs".into());
-                            self.state.logs.push_back("  help             - Show this help".into());
-                            self.state.logs.push_back("  :perf            - Show performance stats".into());
-                            self.state.logs.push_back("".into());
-                            
-                            // Navigation Commands
-                            self.state.logs.push_back("[HELP] Navigation Commands:".into());
-                            self.state.logs.push_back("  build            - Open Agent Builder (6-step wizard)".into());
-                            self.state.logs.push_back("  runs             - Open Run Manager (list, filter, sort)".into());
-                            self.state.logs.push_back("  config, settings - Open Settings (mode, AI provider)".into());
-                            self.state.logs.push_back("  ESC              - Close overlay/popup or clear input".into());
-                            self.state.logs.push_back("".into());
-                            
-                            // Screen Controls
-                            self.state.logs.push_back("[HELP] Screen Controls:".into());
-                            self.state.logs.push_back("  Agent Builder: Enter=Next, Backspace=Prev, ESC=Cancel".into());
-                            self.state.logs.push_back("  Run Manager: ↑/↓=Navigate, F=Filter, S=Sort, R=Refresh".into());
-                            self.state.logs.push_back("  Settings: ↑/↓=Navigate, Space=Toggle, Enter=Save".into());
-                            self.state.logs.push_back("".into());
-                            
-                            // WebSocket Commands - Label BEFORE separator
-                            self.state.logs.push_back("[HELP] WebSocket Commands (requires connection):".into());
-                            self.state.logs.push_back("[HELP] ─────────────────────────────────────────".into());
-                            self.state.logs.push_back("  agent.list       - List all agents".into());
-                            self.state.logs.push_back("  agent.get        - Get agent details (data: {name})".into());
-                            self.state.logs.push_back("  agent.create     - Create agent (use Agent Builder)".into());
-                            self.state.logs.push_back("  agent.delete     - Delete agent (data: {name})".into());
-                            self.state.logs.push_back("  system.status    - Get system status".into());
-                            self.state.logs.push_back("  run.list         - List runs (requires gateway)".into());
-                            self.state.logs.push_back("  tool.list        - List available tools".into());
-                            self.state.logs.push_back("".into());
-                            
-                            self.state.logs.push_back("[HELP] Press F12 to toggle performance overlay".into());
-                            self.state.logs.push_back("[HELP] ═══════════════════════════════════════".into());
+                            // Open help popup instead of logging to operations log
+                            self.push_popup(Screen::Help);
+                            self.request_render("help_command");
                         }
                         ":perf" => {
                             // Perf self-check command
@@ -591,6 +588,10 @@ impl App {
                 use crate::ui::settings;
                 settings::render(f, &self.state);
             }
+            Screen::AgentList => {
+                use crate::ui::agent_list;
+                agent_list::render(f, &self.state);
+            }
             Screen::Confirmation { message, action } => {
                 // TODO: Implement confirmation popup
                 // For now, just render the base screen
@@ -606,10 +607,13 @@ impl App {
                 let _ = message; // Suppress warning
             }
             Screen::Help => {
-                // TODO: Implement help popup
-                // For now, just render the base screen
+                // Render base screen first (dimmed)
                 use crate::ui::layout;
                 layout::render(f, &self.state);
+                
+                // Render help popup overlay
+                use crate::ui::help;
+                help::render_help(f, f.size(), &self.state);
             }
         }
     }
@@ -1108,6 +1112,69 @@ impl App {
         Ok(false)
     }
     
+    // ============================================================
+    // AGENT LIST INPUT HANDLING (Step 4)
+    // ============================================================
+    
+    /// Handle input when Agent List screen is active
+    fn handle_agent_list_input(&mut self, key: KeyEvent) -> anyhow::Result<bool> {
+        use crossterm::event::KeyModifiers;
+        
+        // Ctrl+C/Q to exit
+        if key.modifiers.contains(KeyModifiers::CONTROL) {
+            match key.code {
+                KeyCode::Char('c') | KeyCode::Char('q') => return Ok(true),
+                _ => return Ok(false),
+            }
+        }
+        
+        match key.code {
+            // Navigation
+            KeyCode::Up => {
+                if self.state.agent_list.selected_index > 0 {
+                    self.state.agent_list.selected_index -= 1;
+                }
+                self.request_render("agent_list_up");
+            }
+            KeyCode::Down => {
+                let max = self.state.agent_list.agents.len().saturating_sub(1);
+                if self.state.agent_list.selected_index < max {
+                    self.state.agent_list.selected_index += 1;
+                }
+                self.request_render("agent_list_down");
+            }
+            
+            // View details / Close detail view
+            KeyCode::Enter => {
+                if self.state.agent_list.detail_view.is_some() {
+                    // Close detail view
+                    self.state.agent_list.detail_view = None;
+                } else {
+                    // Open detail view for selected agent
+                    self.state.agent_list.detail_view = Some(self.state.agent_list.selected_index);
+                }
+                self.request_render("agent_list_toggle_detail");
+            }
+            
+            // Close
+            KeyCode::Esc => {
+                if self.state.agent_list.detail_view.is_some() {
+                    // Close detail popup first
+                    self.state.agent_list.detail_view = None;
+                    self.request_render("agent_list_close_detail");
+                } else {
+                    // Close agent list
+                    self.pop_overlay();
+                    self.request_render("agent_list_close");
+                }
+            }
+            
+            _ => {}
+        }
+        
+        Ok(false)
+    }
+    
     // ============================================================
     // SETTINGS INPUT HANDLING (Step 4.8)
     // ============================================================

package/mk3-tui/src/main.rs

@@ -151,12 +151,35 @@ fn main() -> Result<()> {
                                                 })
                                                 .collect();
                                             
+                                            // Parse agents into AgentInfo structs for Agent List viewer
+                                            use crate::app::AgentInfo;
+                                            let agents: Vec<AgentInfo> = agents_array.iter()
+                                                .filter_map(|agent| {
+                                                    let obj = agent.as_object()?;
+                                                    Some(AgentInfo {
+                                                        name: obj.get("name")?.as_str()?.to_string(),
+                                                        description: obj.get("description").and_then(|d| d.as_str()).map(|s| s.to_string()),
+                                                        model: obj.get("model").and_then(|m| m.as_str()).unwrap_or("unknown").to_string(),
+                                                        provider: obj.get("provider").and_then(|p| p.as_str()).unwrap_or("unknown").to_string(),
+                                                        system_prompt: obj.get("systemPrompt").and_then(|sp| sp.as_str()).map(|s| s.to_string()),
+                                                        temperature: obj.get("temperature").and_then(|t| t.as_f64()).map(|f| f as f32),
+                                                        max_tokens: obj.get("maxTokens").and_then(|mt| mt.as_u64()).map(|u| u as u32),
+                                                        tools: obj.get("tools")
+                                                            .and_then(|t| t.as_array())
+                                                            .map(|arr| arr.iter()
+                                                                .filter_map(|v| v.as_str().map(|s| s.to_string()))
+                                                                .collect())
+                                                            .unwrap_or_default(),
+                                                    })
+                                                })
+                                                .collect();
+                                            
                                             // Update cache with agent data
                                             if let Some(cache) = &mut app.state.cache {
                                                 use crate::storage::cache::AgentData;
                                                 use std::time::{SystemTime, UNIX_EPOCH};
                                                 
-                                                let agents: Vec<AgentData> = agents_array.iter()
+                                                let cache_agents: Vec<AgentData> = agents_array.iter()
                                                     .filter_map(|agent| {
                                                         let obj = agent.as_object()?;
                                                         Some(AgentData {
@@ -169,9 +192,18 @@ fn main() -> Result<()> {
                                                     })
                                                     .collect();
                                                 
-                                                let _ = cache.update_agents(agents);
+                                                let _ = cache.update_agents(cache_agents);
                                             }
                                             
+                                            // Update agent list state
+                                            app.state.agent_list.agents = agents;
+                                            app.state.agent_list.selected_index = 0;
+                                            app.state.agent_list.detail_view = None;
+                                            
+                                            // Open AgentList overlay
+                                            app.push_overlay(Screen::AgentList);
+                                            app.request_render("agent_list_opened");
+                                            
                                             // Only log if agents were actually loaded
                                             if agents_array.len() > 0 {
                                                 app.add_log(format!(

package/mk3-tui/src/screens/mod.rs

@@ -19,6 +19,7 @@ pub enum Screen {
     AgentBuilder,
     RunManager,
     Settings,
+    AgentList,
     
     // Popup screens (small overlays)
     Confirmation { message: String, action: String },
@@ -31,7 +32,7 @@ impl Screen {
     pub fn is_overlay(&self) -> bool {
         matches!(
             self,
-            Screen::AgentBuilder | Screen::RunManager | Screen::Settings
+            Screen::AgentBuilder | Screen::RunManager | Screen::Settings | Screen::AgentList
         )
     }
     
@@ -56,6 +57,7 @@ impl Screen {
             Screen::AgentBuilder => "Agent Builder",
             Screen::RunManager => "Run Manager",
             Screen::Settings => "Settings",
+            Screen::AgentList => "Agent List",
             Screen::Confirmation { .. } => "Confirmation",
             Screen::Alert { .. } => "Alert",
             Screen::Help => "Help",

package/mk3-tui/src/ui/agent_list.rs

@@ -0,0 +1,247 @@
+/// Agent List Screen
+/// View and manage AI agents
+
+use ratatui::prelude::*;
+use ratatui::widgets::{Block, Borders, Paragraph, Wrap, Table, Row, Cell};
+use crate::app::{AppState, AgentInfo};
+
+// === 4RUNR BRAND COLORS ===
+const BRAND_PURPLE: Color = Color::Rgb(138, 43, 226);
+const CYBER_CYAN: Color = Color::Rgb(0, 255, 255);
+const NEON_GREEN: Color = Color::Rgb(57, 255, 20);
+const TEXT_PRIMARY: Color = Color::Rgb(230, 230, 240);
+const TEXT_DIM: Color = Color::Rgb(100, 100, 120);
+const TEXT_MUTED: Color = Color::Rgb(60, 60, 80);
+const BG_PANEL: Color = Color::Rgb(18, 18, 25);
+
+/// Render agent list screen
+pub fn render(f: &mut Frame, state: &AppState) {
+    let area = f.size();
+    
+    if state.agent_list.detail_view.is_some() {
+        // Render list view first (as base)
+        render_list_view(f, area, state);
+        // Then render detail popup on top
+        render_detail_popup(f, area, state);
+    } else {
+        // Render list view only
+        render_list_view(f, area, state);
+    }
+}
+
+fn render_list_view(f: &mut Frame, area: Rect, state: &AppState) {
+    use ratatui::layout::{Constraint, Direction, Layout};
+    
+    // Split into header, content, footer
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(3),  // Header
+            Constraint::Min(0),      // Content
+            Constraint::Length(3),  // Footer
+        ])
+        .split(area);
+    
+    // === HEADER ===
+    let agent_count = state.agent_list.agents.len();
+    let header_block = Block::default()
+        .title(format!(" 🤖 Agent List ({} agents) ", agent_count))
+        .title_style(Style::default().fg(BRAND_PURPLE).add_modifier(Modifier::BOLD))
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(CYBER_CYAN))
+        .style(Style::default().bg(BG_PANEL));
+    
+    f.render_widget(header_block, chunks[0]);
+    
+    // === CONTENT: Agent Table ===
+    let content_block = Block::default()
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(TEXT_MUTED))
+        .style(Style::default().bg(BG_PANEL));
+    
+    f.render_widget(content_block.clone(), chunks[1]);
+    
+    let table_area = content_block.inner(chunks[1]);
+    
+    // Create table rows
+    let rows: Vec<Row> = state.agent_list.agents.iter().enumerate().map(|(i, agent)| {
+        let is_selected = i == state.agent_list.selected_index;
+        let style = if is_selected {
+            Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)
+        } else {
+            Style::default().fg(TEXT_PRIMARY)
+        };
+        
+        let name = if is_selected {
+            format!("▶ {}", agent.name)
+        } else {
+            format!("  {}", agent.name)
+        };
+        
+        let desc = agent.description.as_deref().unwrap_or("No description")
+            .chars().take(30).collect::<String>();
+        let model = agent.model.chars().take(15).collect::<String>();
+        let provider = agent.provider.chars().take(10).collect::<String>();
+        
+        Row::new(vec![
+            Cell::from(name).style(style),
+            Cell::from(desc).style(style),
+            Cell::from(model).style(style),
+            Cell::from(provider).style(style),
+        ])
+    }).collect();
+    
+    let table = Table::new(
+        rows,
+        [
+            Constraint::Percentage(25),
+            Constraint::Percentage(35),
+            Constraint::Percentage(20),
+            Constraint::Percentage(20),
+        ]
+    )
+        .header(Row::new(vec![
+            Cell::from("Name").style(Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+            Cell::from("Description").style(Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+            Cell::from("Model").style(Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+            Cell::from("Provider").style(Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+        ]))
+        .column_spacing(1)
+        .style(Style::default().fg(TEXT_PRIMARY));
+    
+    f.render_widget(table, table_area);
+    
+    // === FOOTER ===
+    let footer_text = Line::from(vec![
+        Span::styled("↑/↓", Style::default().fg(CYBER_CYAN)),
+        Span::styled(" Navigate  |  ", Style::default().fg(TEXT_DIM)),
+        Span::styled("Enter", Style::default().fg(NEON_GREEN)),
+        Span::styled(" View Details  |  ", Style::default().fg(TEXT_DIM)),
+        Span::styled("ESC", Style::default().fg(BRAND_PURPLE)),
+        Span::styled(" Close", Style::default().fg(TEXT_DIM)),
+    ]);
+    
+    f.render_widget(
+        Paragraph::new(footer_text)
+            .alignment(Alignment::Center)
+            .style(Style::default().bg(BG_PANEL)),
+        chunks[2]
+    );
+}
+
+fn render_detail_popup(f: &mut Frame, area: Rect, state: &AppState) {
+    let detail_index = state.agent_list.detail_view.unwrap();
+    if let Some(agent) = state.agent_list.agents.get(detail_index) {
+        render_agent_detail(f, area, agent);
+    }
+}
+
+fn render_agent_detail(f: &mut Frame, area: Rect, agent: &AgentInfo) {
+    use ratatui::layout::{Constraint, Direction, Layout};
+    
+    // Calculate popup size (70% width, 80% height, centered)
+    let popup_width = (area.width * 70 / 100).max(50);
+    let popup_height = (area.height * 80 / 100).max(15);
+    let popup_x = (area.width.saturating_sub(popup_width)) / 2;
+    let popup_y = (area.height.saturating_sub(popup_height)) / 2;
+    
+    let popup_area = Rect {
+        x: popup_x,
+        y: popup_y,
+        width: popup_width,
+        height: popup_height,
+    };
+    
+    // Render dimmed overlay
+    let overlay = Block::default()
+        .style(Style::default().bg(Color::Black).fg(Color::Black));
+    f.render_widget(overlay, area);
+    
+    // Render detail popup
+    let detail_block = Block::default()
+        .title(format!(" 📋 Agent Details: {} ", agent.name))
+        .title_style(Style::default().fg(BRAND_PURPLE).add_modifier(Modifier::BOLD))
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(CYBER_CYAN))
+        .style(Style::default().bg(BG_PANEL));
+    
+    f.render_widget(detail_block.clone(), popup_area);
+    
+    let inner = detail_block.inner(popup_area);
+    
+    // Create detail text
+    let mut detail_lines = vec![
+        Line::from(vec![
+            Span::styled("Name: ", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+            Span::styled(&agent.name, Style::default().fg(NEON_GREEN)),
+        ]),
+        Line::from(""),
+    ];
+    
+    if let Some(desc) = &agent.description {
+        detail_lines.push(Line::from(vec![
+            Span::styled("Description: ", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+            Span::styled(desc, Style::default().fg(TEXT_PRIMARY)),
+        ]));
+        detail_lines.push(Line::from(""));
+    }
+    
+    detail_lines.push(Line::from(vec![
+        Span::styled("Model: ", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+        Span::styled(&agent.model, Style::default().fg(TEXT_PRIMARY)),
+    ]));
+    detail_lines.push(Line::from(vec![
+        Span::styled("Provider: ", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+        Span::styled(&agent.provider, Style::default().fg(TEXT_PRIMARY)),
+    ]));
+    
+    if let Some(temp) = agent.temperature {
+        detail_lines.push(Line::from(vec![
+            Span::styled("Temperature: ", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+            Span::styled(format!("{:.2}", temp), Style::default().fg(TEXT_PRIMARY)),
+        ]));
+    }
+    
+    if let Some(max_tokens) = agent.max_tokens {
+        detail_lines.push(Line::from(vec![
+            Span::styled("Max Tokens: ", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+            Span::styled(format!("{}", max_tokens), Style::default().fg(TEXT_PRIMARY)),
+        ]));
+    }
+    
+    if !agent.tools.is_empty() {
+        detail_lines.push(Line::from(""));
+        detail_lines.push(Line::from(vec![
+            Span::styled("Tools: ", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+        ]));
+        for tool in &agent.tools {
+            detail_lines.push(Line::from(vec![
+                Span::raw("  • "),
+                Span::styled(tool, Style::default().fg(NEON_GREEN)),
+            ]));
+        }
+    }
+    
+    if let Some(prompt) = &agent.system_prompt {
+        detail_lines.push(Line::from(""));
+        detail_lines.push(Line::from(vec![
+            Span::styled("System Prompt: ", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+        ]));
+        // Show first 200 chars of prompt
+        let prompt_preview = prompt.chars().take(200).collect::<String>();
+        detail_lines.push(Line::from(format!("  {}", prompt_preview)).style(Style::default().fg(TEXT_DIM)));
+    }
+    
+    detail_lines.push(Line::from(""));
+    detail_lines.push(Line::from(vec![
+        Span::styled("Press ", Style::default().fg(TEXT_DIM)),
+        Span::styled("ESC", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+        Span::styled(" to close", Style::default().fg(TEXT_DIM)),
+    ]));
+    
+    f.render_widget(
+        Paragraph::new(detail_lines)
+            .wrap(Wrap { trim: false }),
+        inner
+    );
+}

package/mk3-tui/src/ui/help.rs

@@ -0,0 +1,353 @@
+/// Help popup screen
+/// Professional, organized command reference
+
+use ratatui::prelude::*;
+use ratatui::widgets::{Block, Borders, Paragraph, Wrap, List, ListItem};
+use crate::app::AppState;
+
+// === 4RUNR BRAND COLORS ===
+const BRAND_PURPLE: Color = Color::Rgb(138, 43, 226);
+const CYBER_CYAN: Color = Color::Rgb(0, 255, 255);
+const NEON_GREEN: Color = Color::Rgb(57, 255, 20);
+const AMBER_WARN: Color = Color::Rgb(255, 191, 0);
+const TEXT_PRIMARY: Color = Color::Rgb(230, 230, 240);
+const TEXT_DIM: Color = Color::Rgb(100, 100, 120);
+const TEXT_MUTED: Color = Color::Rgb(60, 60, 80);
+const BG_PANEL: Color = Color::Rgb(18, 18, 25);
+
+/// Render help popup overlay
+pub fn render_help(f: &mut Frame, area: Rect, _state: &AppState) {
+    // Calculate popup size (80% width, 85% height, centered)
+    let popup_width = (area.width * 80 / 100).max(60);
+    let popup_height = (area.height * 85 / 100).max(20);
+    let popup_x = (area.width.saturating_sub(popup_width)) / 2;
+    let popup_y = (area.height.saturating_sub(popup_height)) / 2;
+    
+    let popup_area = Rect {
+        x: popup_x,
+        y: popup_y,
+        width: popup_width,
+        height: popup_height,
+    };
+    
+    // Render background overlay (dimmed)
+    let overlay = Block::default()
+        .style(Style::default().bg(Color::Black).fg(Color::Black));
+    f.render_widget(overlay, area);
+    
+    // Render help popup
+    render_help_content(f, popup_area);
+}
+
+fn render_help_content(f: &mut Frame, area: Rect) {
+    use ratatui::layout::{Constraint, Direction, Layout};
+    
+    // Split into sections
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(3),  // Header
+            Constraint::Min(0),     // Content
+            Constraint::Length(1),  // Footer
+        ])
+        .split(area);
+    
+    // === HEADER ===
+    let header_block = Block::default()
+        .title(" 📖 4Runr AI Agent OS - Command Reference ")
+        .title_style(Style::default().fg(BRAND_PURPLE).add_modifier(Modifier::BOLD))
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(CYBER_CYAN))
+        .style(Style::default().bg(BG_PANEL));
+    
+    let header_text = Line::from(vec![
+        Span::styled("Press ", Style::default().fg(TEXT_DIM)),
+        Span::styled("ESC", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+        Span::styled(" to close", Style::default().fg(TEXT_DIM)),
+    ]);
+    
+    f.render_widget(header_block, chunks[0]);
+    f.render_widget(
+        Paragraph::new(header_text).alignment(Alignment::Right),
+        Rect {
+            x: chunks[0].x + 1,
+            y: chunks[0].y + 1,
+            width: chunks[0].width.saturating_sub(2),
+            height: 1,
+        }
+    );
+    
+    // === CONTENT ===
+    let content_chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([
+            Constraint::Percentage(40),  // Left: Command list
+            Constraint::Percentage(60),  // Right: Details
+        ])
+        .split(chunks[1]);
+    
+    // Left panel: Command categories
+    render_command_list(f, content_chunks[0]);
+    
+    // Right panel: Command details
+    render_command_details(f, content_chunks[1]);
+    
+    // === FOOTER ===
+    let footer_text = Line::from(vec![
+        Span::styled("Navigate: ", Style::default().fg(TEXT_DIM)),
+        Span::styled("↑/↓", Style::default().fg(CYBER_CYAN)),
+        Span::styled(" Select  |  ", Style::default().fg(TEXT_MUTED)),
+        Span::styled("ESC", Style::default().fg(NEON_GREEN)),
+        Span::styled(" Close", Style::default().fg(TEXT_DIM)),
+    ]);
+    
+    f.render_widget(
+        Paragraph::new(footer_text)
+            .alignment(Alignment::Center)
+            .style(Style::default().bg(BG_PANEL)),
+        chunks[2]
+    );
+}
+
+fn render_command_list(f: &mut Frame, area: Rect) {
+    use ratatui::layout::{Constraint, Direction, Layout};
+    
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(8),  // Navigation Commands
+            Constraint::Length(7),  // Local Commands
+            Constraint::Min(0),     // WebSocket Commands
+        ])
+        .split(area);
+    
+    // Navigation Commands section
+    let nav_block = Block::default()
+        .title(" 🧭 Navigation ")
+        .title_style(Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD))
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(CYBER_CYAN))
+        .style(Style::default().bg(BG_PANEL));
+    
+    let nav_items = vec![
+        ListItem::new(Line::from(vec![
+            Span::styled("build", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("runs", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("config", Style::default().fg(NEON_GREEN)),
+            Span::styled(", ", Style::default().fg(TEXT_DIM)),
+            Span::styled("settings", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("ESC", Style::default().fg(NEON_GREEN)),
+        ])),
+    ];
+    
+    f.render_widget(nav_block.clone(), chunks[0]);
+    f.render_widget(
+        List::new(nav_items)
+            .style(Style::default().fg(TEXT_PRIMARY)),
+        nav_block.inner(chunks[0])
+    );
+    
+    // Local Commands section
+    let local_block = Block::default()
+        .title(" 💻 Local ")
+        .title_style(Style::default().fg(BRAND_PURPLE).add_modifier(Modifier::BOLD))
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(BRAND_PURPLE))
+        .style(Style::default().bg(BG_PANEL));
+    
+    let local_items = vec![
+        ListItem::new(Line::from(vec![
+            Span::styled("quit", Style::default().fg(NEON_GREEN)),
+            Span::styled(", ", Style::default().fg(TEXT_DIM)),
+            Span::styled("exit", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("clear", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("help", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled(":perf", Style::default().fg(NEON_GREEN)),
+        ])),
+    ];
+    
+    f.render_widget(local_block.clone(), chunks[1]);
+    f.render_widget(
+        List::new(local_items)
+            .style(Style::default().fg(TEXT_PRIMARY)),
+        local_block.inner(chunks[1])
+    );
+    
+    // WebSocket Commands section
+    let ws_block = Block::default()
+        .title(" 🌐 WebSocket (requires connection) ")
+        .title_style(Style::default().fg(AMBER_WARN).add_modifier(Modifier::BOLD))
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(AMBER_WARN))
+        .style(Style::default().bg(BG_PANEL));
+    
+    let ws_items = vec![
+        ListItem::new(Line::from(vec![
+            Span::styled("agent.list", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("agent.get", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("agent.create", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("agent.delete", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("system.status", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("run.list", Style::default().fg(NEON_GREEN)),
+        ])),
+        ListItem::new(Line::from(vec![
+            Span::styled("tool.list", Style::default().fg(NEON_GREEN)),
+        ])),
+    ];
+    
+    f.render_widget(ws_block.clone(), chunks[2]);
+    f.render_widget(
+        List::new(ws_items)
+            .style(Style::default().fg(TEXT_PRIMARY)),
+        ws_block.inner(chunks[2])
+    );
+}
+
+fn render_command_details(f: &mut Frame, area: Rect) {
+    use ratatui::layout::{Constraint, Direction, Layout};
+    
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Percentage(50),  // Command descriptions
+            Constraint::Percentage(50),  // Screen controls
+        ])
+        .split(area);
+    
+    // Command descriptions
+    let desc_block = Block::default()
+        .title(" 📋 Command Details ")
+        .title_style(Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD))
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(CYBER_CYAN))
+        .style(Style::default().bg(BG_PANEL));
+    
+    let desc_text = vec![
+        Line::from(vec![
+            Span::styled("build", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+            Span::styled(" - Open Agent Builder (6-step wizard)", Style::default().fg(TEXT_PRIMARY)),
+        ]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled("runs", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+            Span::styled(" - Open Run Manager (list, filter, sort)", Style::default().fg(TEXT_PRIMARY)),
+        ]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled("config, settings", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+            Span::styled(" - Open Settings (mode, AI provider)", Style::default().fg(TEXT_PRIMARY)),
+        ]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled("ESC", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+            Span::styled(" - Close overlay/popup or clear input", Style::default().fg(TEXT_PRIMARY)),
+        ]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled("quit, exit", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+            Span::styled(" - Exit application", Style::default().fg(TEXT_PRIMARY)),
+        ]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled("clear", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+            Span::styled(" - Clear operations log", Style::default().fg(TEXT_PRIMARY)),
+        ]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled("help", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+            Span::styled(" - Show this help", Style::default().fg(TEXT_PRIMARY)),
+        ]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(":perf", Style::default().fg(NEON_GREEN).add_modifier(Modifier::BOLD)),
+            Span::styled(" - Show performance stats", Style::default().fg(TEXT_PRIMARY)),
+        ]),
+    ];
+    
+    f.render_widget(desc_block.clone(), chunks[0]);
+    f.render_widget(
+        Paragraph::new(desc_text)
+            .wrap(Wrap { trim: false }),
+        desc_block.inner(chunks[0])
+    );
+    
+    // Screen controls
+    let controls_block = Block::default()
+        .title(" ⌨️  Screen Controls ")
+        .title_style(Style::default().fg(BRAND_PURPLE).add_modifier(Modifier::BOLD))
+        .borders(Borders::ALL)
+        .border_style(Style::default().fg(BRAND_PURPLE))
+        .style(Style::default().bg(BG_PANEL));
+    
+    let controls_text = vec![
+        Line::from(vec![
+            Span::styled("Agent Builder:", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+        ]),
+        Line::from(vec![
+            Span::raw("  "),
+            Span::styled("Enter", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Next  |  ", Style::default().fg(TEXT_DIM)),
+            Span::styled("Backspace", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Prev  |  ", Style::default().fg(TEXT_DIM)),
+            Span::styled("ESC", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Cancel", Style::default().fg(TEXT_DIM)),
+        ]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled("Run Manager:", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+        ]),
+        Line::from(vec![
+            Span::raw("  "),
+            Span::styled("↑/↓", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Navigate  |  ", Style::default().fg(TEXT_DIM)),
+            Span::styled("F", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Filter  |  ", Style::default().fg(TEXT_DIM)),
+            Span::styled("S", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Sort  |  ", Style::default().fg(TEXT_DIM)),
+            Span::styled("R", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Refresh", Style::default().fg(TEXT_DIM)),
+        ]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled("Settings:", Style::default().fg(CYBER_CYAN).add_modifier(Modifier::BOLD)),
+        ]),
+        Line::from(vec![
+            Span::raw("  "),
+            Span::styled("↑/↓", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Navigate  |  ", Style::default().fg(TEXT_DIM)),
+            Span::styled("Space", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Toggle  |  ", Style::default().fg(TEXT_DIM)),
+            Span::styled("Enter", Style::default().fg(NEON_GREEN)),
+            Span::styled(" = Save", Style::default().fg(TEXT_DIM)),
+        ]),
+    ];
+    
+    f.render_widget(controls_block.clone(), chunks[1]);
+    f.render_widget(
+        Paragraph::new(controls_text)
+            .wrap(Wrap { trim: false }),
+        controls_block.inner(chunks[1])
+    );
+}

package/mk3-tui/src/ui/layout.rs

@@ -120,7 +120,7 @@ fn render_header(f: &mut Frame, area: Rect, state: &AppState) {
     
     // Line 1: Brand + version + uptime - Bug 3 fix: Use "4Runr." with dot (matches brand logo)
     // Use npm package version (2.3.5) - matches package.json
-    const PACKAGE_VERSION: &str = "2.4.1";
+    const PACKAGE_VERSION: &str = "2.4.2";
     let brand_line = Line::from(vec![
         Span::styled("4Runr.", Style::default().fg(BRAND_PURPLE).add_modifier(Modifier::BOLD)),
         Span::styled(" AI AGENT OS", Style::default().fg(BRAND_VIOLET)),
@@ -422,64 +422,6 @@ fn mem_color(value: f64) -> Color {
     else if value > 0.6 { Color::Rgb(255, 191, 0) }
     else { CYBER_CYAN }
 }
-
-/// Parse help log format and return styled spans
-fn parse_help_log(log: &str) -> Vec<Span> {
-    // Remove [HELP] prefix if present
-    let content = if log.starts_with("[HELP] ") {
-        &log[7..] // Skip "[HELP] "
-    } else if log.starts_with("[HELP]") {
-        &log[6..] // Skip "[HELP]"
-    } else {
-        log
-    };
-    
-    // Check for separator line (all dashes or equals)
-    if content.trim().chars().all(|c| c == '─' || c == '-' || c == '═') {
-        return vec![
-            Span::styled("> ", Style::default().fg(CYBER_CYAN)),
-            Span::styled("[HELP] ", Style::default().fg(CYBER_CYAN)),
-            Span::styled(content, Style::default().fg(TEXT_MUTED)),
-        ];
-    }
-    
-    // Check for section header (ends with colon)
-    if content.ends_with(':') && !content.starts_with("  ") {
-        return vec![
-            Span::styled("> ", Style::default().fg(CYBER_CYAN)),
-            Span::styled("[HELP] ", Style::default().fg(CYBER_CYAN)),
-            Span::styled(
-                content,
-                Style::default().fg(BRAND_PURPLE).add_modifier(Modifier::BOLD)
-            ),
-        ];
-    }
-    
-    // Check for command line (starts with "  " and contains " - ")
-    if content.starts_with("  ") && content.contains(" - ") {
-        if let Some(dash_pos) = content.find(" - ") {
-            let command_part = content[2..dash_pos].trim_end();
-            let desc_part = &content[dash_pos + 3..];
-            
-            return vec![
-                Span::styled("> ", Style::default().fg(CYBER_CYAN)),
-                Span::styled("[HELP] ", Style::default().fg(CYBER_CYAN)),
-                Span::styled("  ", Style::default().fg(TEXT_PRIMARY)),
-                Span::styled(command_part, Style::default().fg(NEON_GREEN)),
-                Span::styled(" - ", Style::default().fg(TEXT_MUTED)),
-                Span::styled(desc_part, Style::default().fg(TEXT_PRIMARY)),
-            ];
-        }
-    }
-    
-    // Default: regular help message
-    vec![
-        Span::styled("> ", Style::default().fg(CYBER_CYAN)),
-        Span::styled("[HELP] ", Style::default().fg(CYBER_CYAN)),
-        Span::styled(content, Style::default().fg(TEXT_PRIMARY)),
-    ]
-}
-
 fn render_center_column(f: &mut Frame, area: Rect, state: &AppState) {
     let panel_area = Rect {
         x: area.x + 1,
@@ -525,11 +467,7 @@ fn render_center_column(f: &mut Frame, area: Rect, state: &AppState) {
     
     // Show real logs with proper formatting (reversed order - newest first)
     for log in state.logs.iter().rev().skip(start_idx).take(visible_height) {
-        // Check if this is a HELP log
-        if log.starts_with("[HELP]") {
-            let spans = parse_help_log(log);
-            lines.push(Line::from(spans));
-        } else if log.starts_with("[") {
+        if log.starts_with("[") {
             // Parse log format: [COMPONENT] message
             if let Some(bracket_end) = log.find(']') {
                 let component = &log[1..bracket_end];

package/mk3-tui/src/ui/mod.rs

@@ -1,5 +1,7 @@
 pub mod agent_builder;
+pub mod agent_list;
 pub mod boot;
+pub mod help;
 pub mod layout;
 pub mod run_manager;
 pub mod safe_viewport;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "4runr-os",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "type": "module",
+  "private": false,
   "description": "4Runr AI Agent OS - Secure terminal interface for AI agents. v2.3.5: Fixed boot screen logo rendering (restored original working version), fully functional Agent Builder with input handling and TUI styling. Built with Rust + Ratatui. ⚠️ Pre-MVP / Development Phase",
   "main": "dist/index.js",
   "bin": {