logging docs

README.md

@@ -29,6 +29,7 @@ Key sections:
 - [Recommended Configuration](https://docs.ra-aid.ai/quickstart/recommended)
 - [Open Models Setup](https://docs.ra-aid.ai/quickstart/open-models)
 - [Usage Examples](https://docs.ra-aid.ai/category/usage)
+- [Logging System](https://docs.ra-aid.ai/usage/logging)
 - [Contributing Guide](https://docs.ra-aid.ai/contributing)
 - [Getting Help](https://docs.ra-aid.ai/getting-help)
 
@@ -186,10 +187,10 @@ ra-aid -m "Explain the authentication flow" --research-only
 ra-aid -m "Add new feature" --log-mode file
 
 # Console-only logging with detailed output
-ra-aid -m "Add new feature" --log-mode console
+ra-aid -m "Add new feature" --log-mode console --log-level debug
 ```
 
-More information is available in our [Usage Examples](https://docs.ra-aid.ai/category/usage).
+More information is available in our [Usage Examples](https://docs.ra-aid.ai/category/usage) and [Logging System](https://docs.ra-aid.ai/usage/logging) documentation.
 
 ### Command Line Options
 
@@ -207,11 +208,14 @@ More information is available in our [Usage Examples](https://docs.ra-aid.ai/cat
 - `--hil, -H`: Enable human-in-the-loop mode for interactive assistance during task execution
 - `--chat`: Enable chat mode with direct human interaction (implies --hil)
 - `--log-mode`: Logging mode (choices: file, console)
-  - `file`: Logs to both file and console (only warnings+ to console)
+  - `file` (default): Logs to both file and console (only warnings and errors to console)
-  - `console`: Logs to console only at the specified log level
+  - `console`: Logs to console only at the specified log level with no file logging
 - `--log-level`: Set specific logging level (debug, info, warning, error, critical)
+  - With `--log-mode=file`: Controls the file logging level (console still shows only warnings+)
+  - With `--log-mode=console`: Controls the console logging level directly
+  - Default: warning
 - `--experimental-fallback-handler`: Enable experimental fallback handler to attempt to fix too calls when the same tool fails 3 times consecutively. (OPENAI_API_KEY recommended as openai has the top 5 tool calling models.) See `ra_aid/tool_leaderboard.py` for more info.
-- `--pretty-logger`: Enables panel markdown formatted logger messages for debugging purposes.
+- `--pretty-logger`: Enables colored panel-style formatted logging output for better readability.
 - `--temperature`: LLM temperature (0.0-2.0) to control randomness in responses
 - `--disable-limit-tokens`: Disable token limiting for Anthropic Claude react agents
 - `--recursion-limit`: Maximum recursion depth for agent operations (default: 100)

docs/docs/getting-help.md

@@ -1,5 +1,23 @@
 # Getting Help
 
+## Troubleshooting Common Issues
+
+Before seeking external help, check the following:
+
+### Check the Logs
+
+RA.Aid maintains detailed logs that can help diagnose many common issues. By default, logs are stored in the `.ra-aid/logs/` directory in your working directory.
+
+1. Check the most recent log file in `.ra-aid/logs/` directory
+2. Look for ERROR or WARNING level messages that might indicate what went wrong
+3. For more detailed logging options, see the [Logging documentation](/usage/logging)
+
+### Common Problems
+
+- **Error connecting to API**: Verify your API key is set correctly
+- **Command not found**: Ensure RA.Aid is installed properly and in your PATH
+- **Script execution failures**: Check that required dependencies are installed
+
 ## Bug Reports and Feature Requests
 
 If you encounter any issues or have ideas for improvements, please file them on our [GitHub Issues page](https://github.com/ai-christianson/RA.Aid/issues).

docs/docs/quickstart/recommended.md

@@ -54,3 +54,15 @@ Or run with a single command:
 ```bash
 ra-aid -m "Help me understand this code"
 ```
+
+You can control logging verbosity and location using the `--log-mode` and `--log-level` options:
+
+```bash
+# Log to file (with only warnings to console)
+ra-aid -m "Your task" --log-mode file --log-level debug
+
+# Log everything to console
+ra-aid -m "Your task" --log-mode console --log-level info
+```
+
+For more detailed logging configuration, see the [Logging documentation](../usage/logging.md).

docs/docs/usage/logging.md

@@ -0,0 +1,167 @@
+# Logging System
+
+RA.Aid includes a powerful and flexible logging system that helps you troubleshoot issues and monitor the tool's operation. This document explains how to configure and use the logging features effectively.
+
+## Overview
+
+The logging system in RA.Aid provides:
+
+- Configurable logging modes for different use cases
+- Multiple log levels for controlling verbosity
+- File logging with rotation and backup capabilities
+- Pretty console logging with formatted display
+- Comprehensive log messages capturing agent activity
+
+## Command Line Options
+
+RA.Aid provides the following command line options to control logging behavior:
+
+### Log Mode
+
+The `--log-mode` option determines where logs are directed:
+
+```bash
+ra-aid -m "Add new feature" --log-mode file
+```
+
+Available modes:
+
+- `file` (default): Logs are written to both file and console
+  - Console shows only warnings and errors
+  - File contains all logs at the specified log level
+- `console`: Logs are only shown in the console at the specified log level
+  - No log files are created
+
+### Log Level
+
+The `--log-level` option controls the verbosity of logging:
+
+```bash
+ra-aid -m "Add new feature" --log-level debug
+```
+
+Available levels (case-insensitive):
+
+- `debug`: Most verbose, includes detailed debugging information
+- `info`: General information about operations
+- `warning` (default): Potential issues that might need attention
+- `error`: Error conditions that prevent normal operation
+- `critical`: Critical errors that may cause the application to terminate
+
+The log level affects different outputs depending on the log mode:
+- With `--log-mode=file`: Controls the file logging level, while console still shows only warnings and errors
+- With `--log-mode=console`: Controls the console logging level directly
+
+### Pretty Logger
+
+The `--pretty-logger` option enables formatted panel-style logging output:
+
+```bash
+ra-aid -m "Add new feature" --pretty-logger
+```
+
+When enabled, log messages appear in colored panels with titles indicating the log level:
+- 🔥 CRITICAL: Bold red panels for critical errors
+- ❌ ERROR: Red panels for errors
+- ⚠️ WARNING: Yellow panels for warnings
+- ℹ️ INFO: Green panels for informational messages
+- 🐞 DEBUG: Blue panels for debug messages
+
+## Log Files
+
+When `--log-mode=file` is used, RA.Aid creates and maintains log files with the following characteristics:
+
+### Location
+
+Log files are stored in the `.ra-aid/logs/` directory in your current working directory:
+
+```
+.ra-aid/logs/ra_aid_YYYYMMDD_HHMMSS.log
+```
+
+RA.Aid automatically creates this directory if it doesn't exist.
+
+### Naming Convention
+
+Log files follow a timestamp-based naming pattern:
+
+```
+ra_aid_YYYYMMDD_HHMMSS.log
+```
+
+Where:
+- `YYYYMMDD`: Year, month, and day when the log file was created
+- `HHMMSS`: Hour, minute, and second when the log file was created
+
+Example: `ra_aid_20250301_143027.log`
+
+### Log Rotation
+
+RA.Aid uses automatic log rotation to manage log file size and prevent excessive disk usage:
+
+- Maximum file size: 5 MB
+- Maximum backup files: 100
+
+When a log file reaches 5 MB, it is renamed with a numeric suffix (e.g., `.1`, `.2`), and a new log file is created. Up to 100 backup files are maintained.
+
+## Examples
+
+### Basic Usage (Default)
+
+Use the default file logging mode with warnings and errors:
+
+```bash
+ra-aid -m "Add new feature"
+```
+
+### Detailed File Logging
+
+Log everything including debug messages to file (console still shows only warnings+):
+
+```bash
+ra-aid -m "Add new feature" --log-level debug
+```
+
+### Console-Only Debugging
+
+Get detailed debug logs in the console without creating log files:
+
+```bash
+ra-aid -m "Add new feature" --log-mode console --log-level debug
+```
+
+### Informational Console Logging
+
+Get informational console output without debug details:
+
+```bash
+ra-aid -m "Add new feature" --log-mode console --log-level info
+```
+
+### Pretty Logging Output
+
+Use formatted panel-style logging for better readability:
+
+```bash
+ra-aid -m "Add new feature" --pretty-logger
+```
+
+## Debugging Tips
+
+- For troubleshooting issues, start with `--log-mode console --log-level debug`
+- Examine log files in `.ra-aid/logs/` for historical issues
+- Use `--pretty-logger` when working with complex tasks for better log clarity
+- For production use, the default settings (`--log-mode file --log-level warning`) provide a good balance of information without excessive output
+
+## Log Message Format
+
+Standard log messages follow this format:
+
+```
+YYYY-MM-DD HH:MM:SS,MS - logger_name - LEVEL - Message text
+```
+
+Example:
+```
+2025-03-01 14:30:27,123 - ra_aid.agent_utils - WARNING - Command execution timeout after 60 seconds
+```

docs/docusaurus.config.ts

@@ -5,7 +5,7 @@ import type * as Preset from '@docusaurus/preset-classic';
 const config: Config = {
   title: 'RA-Aid Documentation',
   favicon: 'img/favicon.ico',
-  url: 'https://ra-aid.0.dev',
+  url: 'https://docs.ra-aid.ai',
   baseUrl: '/',
   
   onDuplicateRoutes: 'ignore',