feat(cortex-cli): improve CLI help text and add file safety utilities (#203)

AGENT_8 CLI Help & Validation Improvements:

1. Added AFTER_HELP section to cortex-cli main.rs with:
   - Environment variables documentation (CORTEX_HOME, CORTEX_API_KEY,
     CORTEX_MODEL, CORTEX_LOG_LEVEL, NO_COLOR, VISUAL, EDITOR)
   - Configuration paths (config, sessions, logs, agents)
   - Usage examples for common commands

2. Created cortex-utils-file-safety crate with:
   - validate_file_for_read() - validates files before reading
   - validate_file_for_read_with_limit() - with custom size limit
   - is_special_path() - quick path safety check
   - FileError enum with detailed error types
   - Cross-platform support (Unix + Windows)
   - Protection against:
     - Block/character devices
     - FIFOs and sockets
     - Special paths (/dev, /proc, /sys on Unix)
     - DOS device names (CON, NUL, COM1, etc. on Windows)
     - Files exceeding size limit (100MB default)
   - Comprehensive test coverage

Note: Many improvements from IMPROVEMENTS_STATUS.md were already
implemented in the codebase:
- PR 50 (logout confirmation)
- PR 30 (built-in agent removal warning)
- PR 61 (--force data loss warning)
- PR 27 (session ID format validation)
- PR 29 (host address validation)
- PR 45 (JSON parse error handling)

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

Author: echobt

Cargo.lock

@@ -46,6 +46,7 @@ members = [
     "cortex-utils/image",
     "cortex-utils/string",
     "cortex-utils/cache",
+    "cortex-utils/file-safety",
 
     # CLI - Features (Phase 1)
     "cortex-lsp",
@@ -183,6 +184,7 @@ cortex-utils-pty = { path = "cortex-utils/pty" }
 cortex-utils-image = { path = "cortex-utils/image" }
 cortex-utils-string = { path = "cortex-utils/string" }
 cortex-utils-cache = { path = "cortex-utils/cache" }
+cortex-utils-file-safety = { path = "cortex-utils/file-safety" }
 cortex-login = { path = "cortex-login" }
 cortex-keyring-store = { path = "cortex-keyring-store" }
 cortex-feedback = { path = "cortex-feedback" }

Cargo.toml

@@ -81,6 +81,31 @@ impl LogLevel {
     }
 }
 
+/// After-help section with environment variables documentation.
+const AFTER_HELP: &str = "\
+ENVIRONMENT VARIABLES:
+    CORTEX_HOME          Override config directory (default: ~/.config/cortex)
+    CORTEX_API_KEY       API key (alternative to --with-api-key)
+    CORTEX_MODEL         Default model (alternative to --model)
+    CORTEX_LOG_LEVEL     Log verbosity (error, warn, info, debug, trace)
+    NO_COLOR             Disable colored output (set to '1' or 'true')
+    VISUAL               Editor for /edit command (fallback: EDITOR)
+    EDITOR               Fallback editor if VISUAL is not set
+
+CONFIGURATION:
+    Config file: ~/.config/cortex/config.toml
+    Sessions:    ~/.local/share/cortex/sessions/
+    Logs:        ~/.cache/cortex/logs/
+    Agents:      ~/.cortex/agents/ (personal), .cortex/agents/ (project)
+
+EXAMPLES:
+    cortex                         Start interactive TUI
+    cortex \"fix the bug\"          Start TUI with initial prompt
+    cortex run \"explain this\"     Non-interactive single request
+    cortex exec \"run tests\"       Headless execution for CI/CD
+    cortex resume --last           Continue most recent session
+";
+
 /// Cortex CLI - AI Coding Agent
 ///
 /// If no subcommand is specified, starts the interactive TUI.
@@ -90,7 +115,8 @@ impl LogLevel {
 #[command(about = "Cortex - AI Coding Agent", long_about = None)]
 #[command(
     subcommand_negates_reqs = true,
-    override_usage = "cortex [OPTIONS] [PROMPT]\n       cortex [OPTIONS] <COMMAND> [ARGS]"
+    override_usage = "cortex [OPTIONS] [PROMPT]\n       cortex [OPTIONS] <COMMAND> [ARGS]",
+    after_help = AFTER_HELP
 )]
 struct Cli {
     #[clap(flatten)]

cortex-cli/src/main.rs

@@ -0,0 +1,19 @@
+[package]
+name = "cortex-utils-file-safety"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "File safety utilities for Cortex - validates file paths and types before reading"
+
+[lib]
+name = "cortex_utils_file_safety"
+path = "src/lib.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+thiserror = { workspace = true }
+
+[dev-dependencies]
+tempfile = { workspace = true }