fix(cortex-cli): implement improvements from code analysis (#174)

This commit addresses multiple improvements identified in IMPROVEMENTS_STATUS.md
and CORTEX_CLI_ANALYSIS.md:

## CLI Help Text Improvements (Group A)
- Enhanced --ask-for-approval help with detailed values (ask/medium/low/yolo)
- Expanded --full-auto help explaining sandbox restrictions and use cases
- Added --oss flag help listing all supported providers
- Improved --search flag help with detailed capabilities
- Added --output-schema help with JSON Schema format example
- Enhanced --host help in ServeCommand with security warnings
- Improved --selector help in scrape command with CSS selector examples
- Improved --user-agent help with common examples

## CLI Validation & Error Handling (Group B/H)
- MCP server command now returns proper error instead of silent failure

## CLI Features & Behavior (Group C)
- Fixed zip dependency to use workspace version (2.2 vs 0.6)
- Removed redundant 'bytes' suffix in debug paths size output

## Agent & Execution (Group G)
- Added helpful alternatives when trying to remove built-in agents

## Sessions & Minor Fixes (Group D/E/F)
- Added confirmation prompt to logout command
- Added data loss warning to --force flag in pr command
- Enhanced agent create help with detailed examples
- Enhanced PR review automation help text

Co-authored-by: Droid Agent <droid@factory.ai>

Author: echobt

cortex-cli/Cargo.toml

@@ -52,7 +52,7 @@ base64 = { workspace = true }
 reqwest = { workspace = true, features = ["json"] }
 
 # For upgrade command (archive extraction)
-zip = "0.6"
+zip = { workspace = true }
 flate2 = "1.0"
 tar = "0.4"
 

cortex-cli/src/agent_cmd.rs

@@ -72,11 +72,15 @@ pub struct ShowArgs {
     about = "Create a new custom agent",
     long_about = "Create a new custom agent with a specific persona and capabilities.\n\n\
     Agents can be customized with:\n\
-    - Custom system prompts\n\
-    - Tool restrictions (allowed/disallowed tools)\n\
-    - Model preferences\n\
-    - Color themes for identification\n\n\
-    Example: cortex agent create my-agent --model gpt-4o --color '#FF5733'"
+    - Custom system prompts that define the agent's personality and expertise\n\
+    - Tool restrictions (allowed/disallowed tools) to limit agent capabilities\n\
+    - Model preferences for specific use cases\n\
+    - Color themes for visual identification in the UI\n\
+    - Delegation settings to control sub-agent spawning\n\n\
+    Examples:\n\
+      cortex agent create my-agent --model gpt-4o --color '#FF5733'\n\
+      cortex agent create reviewer --generate \"A code reviewer focused on security\"\n\
+      cortex agent create --name helper --non-interactive"
 )]
 pub struct CreateArgs {
     /// Agent name (if not provided, interactive mode will prompt).
@@ -1175,7 +1179,16 @@ async fn run_remove(args: RemoveArgs) -> Result<()> {
         .ok_or_else(|| anyhow::anyhow!("Agent '{}' not found", args.name))?;
 
     if agent.native {
-        bail!("Cannot remove built-in agent '{}'", args.name);
+        bail!(
+            "Cannot remove built-in agent '{}'.\n\n\
+            Built-in agents are part of the Cortex core and cannot be removed.\n\
+            Alternative options:\n\
+            1. Create a custom agent to replace it: cortex agent create my-{}\n\
+            2. Disable specific tools on the built-in agent by creating a wrapper\n\
+            3. Use a different agent with: cortex run --agent <other-agent>",
+            args.name,
+            args.name
+        );
     }
 
     let path = agent

cortex-cli/src/debug_cmd.rs

@@ -495,13 +495,13 @@ fn format_size(bytes: u64) -> String {
     const GB: u64 = MB * 1024;
 
     if bytes >= GB {
-        format!("{:.2} GB ({} bytes)", bytes as f64 / GB as f64, bytes)
+        format!("{:.2} GB", bytes as f64 / GB as f64)
     } else if bytes >= MB {
-        format!("{:.2} MB ({} bytes)", bytes as f64 / MB as f64, bytes)
+        format!("{:.2} MB", bytes as f64 / MB as f64)
     } else if bytes >= KB {
-        format!("{:.2} KB ({} bytes)", bytes as f64 / KB as f64, bytes)
+        format!("{:.2} KB", bytes as f64 / KB as f64)
     } else {
-        format!("{} bytes", bytes)
+        format!("{} B", bytes)
     }
 }
 
@@ -1535,8 +1535,9 @@ mod tests {
 
     #[test]
     fn test_format_size() {
-        assert_eq!(format_size(500), "500 bytes");
-        assert_eq!(format_size(1024), "1.00 KB (1024 bytes)");
-        assert_eq!(format_size(1048576), "1.00 MB (1048576 bytes)");
+        assert_eq!(format_size(500), "500 B");
+        assert_eq!(format_size(1024), "1.00 KB");
+        assert_eq!(format_size(1048576), "1.00 MB");
+        assert_eq!(format_size(1073741824), "1.00 GB");
     }
 }

cortex-cli/src/github_cmd.rs

@@ -40,7 +40,13 @@ pub struct InstallArgs {
     #[arg(short, long)]
     pub force: bool,
 
-    /// Include PR review automation. When enabled, the agent will automatically review pull requests, suggest improvements, and can approve/request changes based on configured policies
+    /// Include PR review automation in the workflow.
+    /// When enabled, the agent will:
+    ///   - Automatically review new and updated pull requests
+    ///   - Analyze code changes for bugs, security issues, and best practices
+    ///   - Suggest improvements with inline comments
+    ///   - Respond to review comments and questions
+    /// Triggered by: pull_request (opened, synchronize, reopened)
     #[arg(long, default_value_t = true)]
     pub pr_review: bool,
 

cortex-cli/src/login.rs

@@ -6,7 +6,7 @@ use cortex_login::{
     safe_format_key, save_auth_with_fallback,
 };
 use std::collections::HashSet;
-use std::io::{IsTerminal, Read};
+use std::io::{BufRead, IsTerminal, Read};
 use std::path::PathBuf;
 
 /// Check for duplicate config override keys and warn the user.
@@ -143,6 +143,34 @@ pub async fn run_logout(config_overrides: CliConfigOverrides) -> ! {
     check_duplicate_config_overrides(&config_overrides);
     let fabric_home = get_fabric_home();
 
+    // Check if user is logged in first
+    match load_auth_with_fallback(&fabric_home) {
+        Ok(Some(_)) => {
+            // User is logged in, ask for confirmation if terminal is interactive
+            if std::io::stdin().is_terminal() {
+                eprint!("Are you sure you want to log out? This will remove your stored credentials. [y/N]: ");
+                let _ = std::io::Write::flush(&mut std::io::stderr());
+
+                let mut input = String::new();
+                if std::io::stdin().read_line(&mut input).is_ok() {
+                    let input = input.trim().to_lowercase();
+                    if input != "y" && input != "yes" {
+                        eprintln!("Logout cancelled.");
+                        std::process::exit(0);
+                    }
+                }
+            }
+        }
+        Ok(None) => {
+            eprintln!("Not logged in");
+            std::process::exit(0);
+        }
+        Err(e) => {
+            eprintln!("Error checking login status: {e}");
+            std::process::exit(1);
+        }
+    }
+
     match logout(&fabric_home, CredentialsStoreMode::default()) {
         Ok(true) => {
             eprintln!("Successfully logged out");

cortex-cli/src/main.rs

@@ -65,7 +65,13 @@ struct InteractiveArgs {
     #[arg(short, long)]
     model: Option<String>,
 
-    /// Use open-source/local LLM providers. Supported: ollama, lmstudio, llamacpp, vllm, openrouter
+    /// Use open-source/local LLM providers instead of cloud APIs.
+    /// Supported providers:
+    ///   ollama     - Ollama local LLM server (default port: 11434)
+    ///   lmstudio   - LM Studio local server
+    ///   llamacpp   - llama.cpp server
+    ///   vllm       - vLLM inference server
+    ///   openrouter - OpenRouter API (cloud, supports many OSS models)
     #[arg(long = "oss", default_value_t = false)]
     oss: bool,
 
@@ -77,11 +83,20 @@ struct InteractiveArgs {
     #[arg(long = "sandbox", short = 's')]
     sandbox_mode: Option<String>,
 
-    /// Set the approval policy for tool executions. Valid values: ask (always ask), medium (risky only), low (rarely ask), yolo (never ask)
-    #[arg(long = "ask-for-approval", short = 'a')]
+    /// Set the approval policy for tool executions.
+    /// Valid values:
+    ///   ask    - Always ask for approval before executing tools
+    ///   medium - Ask for approval only for risky operations
+    ///   low    - Rarely ask for approval (only for dangerous operations)
+    ///   yolo   - Never ask for approval (DANGEROUS: use with caution)
+    #[arg(long = "ask-for-approval", short = 'a', value_name = "POLICY")]
     approval_policy: Option<String>,
 
-    /// Enable fully automatic mode with sandboxed execution. Equivalent to --dangerously-skip-permissions combined with workspace-write sandbox. Use for non-destructive automated workflows
+    /// Enable fully automatic mode with sandboxed execution.
+    /// Combines approval_policy=yolo with workspace-write sandbox restrictions.
+    /// The sandbox ensures operations are confined to the workspace directory.
+    /// Best suited for automated CI/CD pipelines and non-destructive scripted workflows.
+    /// For interactive use, consider --ask-for-approval=medium instead.
     #[arg(long = "full-auto", default_value_t = false)]
     full_auto: bool,
 
@@ -98,7 +113,13 @@ struct InteractiveArgs {
     #[arg(long = "cd", short = 'C', value_name = "DIR")]
     cwd: Option<PathBuf>,
 
-    /// Enable web search capability. Allows the agent to search the web for up-to-date information, documentation, and code examples during the conversation
+    /// Enable web search capability for the agent.
+    /// When enabled, the agent can:
+    ///   - Search the web for up-to-date information and documentation
+    ///   - Find code examples and best practices
+    ///   - Look up library/API documentation
+    ///   - Research error messages and solutions
+    /// Requires network access. Search results are automatically filtered for relevance.
     #[arg(long = "search", default_value_t = false)]
     web_search: bool,
 
@@ -215,8 +236,12 @@ struct ExecCommand {
     #[arg(short, long, default_value = "human")]
     format: String,
 
-    /// Path to a JSON Schema file (.json) that defines the expected structure of the output. The schema should follow JSON Schema draft-07 or later format
-    #[arg(long)]
+    /// Path to a JSON Schema file (.json) that defines the expected structure of the output.
+    /// The schema should follow JSON Schema draft-07 or later format.
+    /// Example schema:
+    ///   {"type": "object", "properties": {"summary": {"type": "string"}}, "required": ["summary"]}
+    /// The agent will format its response to match the specified schema structure.
+    #[arg(long, value_name = "SCHEMA_FILE")]
     output_schema: Option<PathBuf>,
 
     /// Agent to use for this request
@@ -377,7 +402,11 @@ struct ServeCommand {
     #[arg(short, long, default_value = "3000")]
     port: u16,
 
-    /// Host to bind to
+    /// Host address to bind the server to.
+    /// Examples:
+    ///   127.0.0.1 - Local only (default, most secure)
+    ///   0.0.0.0   - All interfaces (accessible from network)
+    /// Warning: Binding to 0.0.0.0 exposes the server to the network.
     #[arg(long, default_value = "127.0.0.1")]
     host: String,
 
@@ -485,8 +514,7 @@ async fn main() -> Result<()> {
         Some(Commands::Mcp(mcp_cli)) => mcp_cli.run().await,
         Some(Commands::Agent(agent_cli)) => agent_cli.run().await,
         Some(Commands::McpServer) => {
-            eprintln!("MCP server mode not yet implemented");
-            Ok(())
+            bail!("MCP server mode is not yet implemented. Use 'cortex mcp' for MCP server management.");
         }
         Some(Commands::Completion(completion_cli)) => {
             generate_completions(completion_cli.shell);

cortex-cli/src/pr_cmd.rs

@@ -63,7 +63,9 @@ pub struct PrCli {
     #[arg(short, long)]
     pub path: Option<PathBuf>,
 
-    /// Force checkout even if there are uncommitted changes. WARNING: This may discard uncommitted work
+    /// Force checkout even if there are uncommitted changes.
+    /// WARNING: This may result in data loss! Uncommitted changes in your working
+    /// directory may be overwritten. Consider using 'git stash' first to save your work.
     #[arg(short, long)]
     pub force: bool,
 

cortex-cli/src/scrape_cmd.rs

@@ -56,7 +56,13 @@ pub struct ScrapeCommand {
     #[arg(short, long, default_value = "30")]
     pub timeout: u64,
 
-    /// Custom User-Agent string. Examples: 'Mozilla/5.0 (compatible; Googlebot/2.1)', 'curl/7.68.0', 'PostmanRuntime/7.29.0'
+    /// Custom User-Agent string to identify the request.
+    /// Common examples:
+    ///   Mozilla/5.0 (compatible; Googlebot/2.1)   - Googlebot
+    ///   Mozilla/5.0 (Windows NT 10.0; Win64)      - Windows browser
+    ///   curl/7.68.0                               - curl client
+    ///   PostmanRuntime/7.29.0                     - Postman
+    /// Some sites block requests from unknown user agents.
     #[arg(long)]
     pub user_agent: Option<String>,
 
@@ -72,7 +78,15 @@ pub struct ScrapeCommand {
     #[arg(long)]
     pub no_links: bool,
 
-    /// CSS selector to extract specific elements. Examples: 'article', '.content', '#main', 'div.post > p', 'table tbody tr'
+    /// CSS selector to extract specific elements from the page.
+    /// Examples:
+    ///   article           - Select all <article> elements
+    ///   .content          - Select elements with class "content"
+    ///   #main             - Select element with id "main"
+    ///   div.post > p      - Select <p> children of div.post
+    ///   table tbody tr    - Select table rows in tbody
+    ///   h1, h2, h3        - Select multiple heading levels
+    ///   [data-id="123"]   - Select by attribute
     #[arg(long, value_name = "SELECTOR")]
     pub selector: Option<String>,