Enhance usage documentation and README navigation

README.md

@@ -153,55 +153,31 @@ ai-shell
 ai-shell --mode translator
 ai-shell --mode assistant 
 ai-shell --mode metasploit
+ai-shell --mode wapiti
 
 # Specify provider
 ai-shell --provider local
 ai-shell --provider gemini --api-key your_key
 
 # Use custom config
 ai-shell --config myconfig.yaml
-```
-
-## 📖 Documentation
 
-### Configuration
 
-The `config.yaml` file allows you to customize AI Shell's behavior:
-
-```yaml
-llm:
-  provider: gemini  # or 'local'
-  gemini:
-    api_key: ""
-    model: gemini-1.5-flash
-  local:
-    host: localhost
-    port: 11434
-    model: llama3
-
-security:
-  require_confirmation: true
-  dangerous_commands:
-    - rm -rf
-    - format
-    - dd if=
-
-logging:
-  level: INFO
-  file: ai_shell.log
+# Adjust safety and logging
+ai-shell --no-confirmation
+ai-shell --log-level DEBUG
 ```
 
-### Environment Variables
-
-- `GEMINI_API_KEY`: Your Google Gemini API key
-- `AI_SHELL_CONFIG`: Path to custom configuration file
+For a full CLI reference and mode-by-mode walkthrough, see [docs/USAGE.md](docs/USAGE.md).
 
-### Security Features
+## 📖 Documentation
 
-- **Command Validation**: Blocks dangerous commands
-- **User Confirmation**: Requires approval before execution
-- **Input Sanitization**: Protects against command injection
-- **Configurable Restrictions**: Customizable safety lists
+Browse focused guides:
+- [Usage Guide](docs/USAGE.md) — CLI flags, modes, and provider selection  
+- [Configuration Guide](docs/CONFIGURATION.md) — config structure, profiles, and templates  
+- [Architecture Overview](docs/ARCHITECTURE.md) — component and data-flow diagrams  
+- [Examples & Tutorials](docs/EXAMPLES.md) — practical prompts and scripts  
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — common fixes and debugging tips  
 
 ## 🔧 Development
 
@@ -216,7 +192,7 @@ ai_shell/
 │   ├── executor.py     # Command execution and security
 │   └── ui.py           # User interface utilities
 ├── tests/              # Test suite
-├── docs/               # Documentation (coming soon)
+├── docs/               # Documentation guides
 ├── setup.py            # Package setup
 └── requirements.txt    # Dependencies
 ```

docs/USAGE.md

@@ -0,0 +1,64 @@
+# Usage Guide
+
+This guide summarizes how to run AI Shell from the command line, select operating modes, and choose the right provider for your environment.
+
+## ⚙️ Command-Line Quick Reference
+
+| Option | Description |
+| ------ | ----------- |
+| `--mode {translator,assistant,metasploit,wapiti}` | Run a specific mode without the interactive selector. |
+| `--provider {gemini,local}` | Choose the LLM backend (Gemini API or local Ollama). |
+| `--config <file>` | Path to a custom YAML configuration file. |
+| `--api-key <key>` | Override the Gemini API key for this run. |
+| `--no-confirmation` | Skip confirmation prompts for generated commands. |
+| `--log-level {DEBUG,INFO,WARNING,ERROR}` | Override the logging level. |
+| `--version` | Display AI Shell version. |
+
+Configuration precedence follows: **CLI flags → environment variables → `config.yaml` → defaults**.
+
+## 🎯 Operating Modes
+
+### Translator Mode
+- Start with `ai-shell --mode translator`.
+- Enter natural language prompts and receive a single shell command.
+- Commands are validated before execution; type `exit` to quit.
+
+### Assistant Mode
+- Start with `ai-shell --mode assistant`.
+- Conversational guidance with history; responses may include runnable commands.
+- When a command is detected, AI Shell asks for confirmation before running it.
+
+### Metasploit Assistant
+- Start with `ai-shell --mode metasploit` (requires `msfconsole`).
+- A Metasploit shell opens; prefix prompts with `?` to ask the AI for help.
+- Confirm before executing AI-suggested commands; type `exit` inside msfconsole to leave.
+
+### Wapiti Assistant
+- Start with `ai-shell --mode wapiti` (requires `wapiti` on PATH).
+- Opens a Bash session tailored for web security tasks; prefix prompts with `?` to get AI-generated commands.
+- Confirm before execution; exit the shell to return to your terminal.
+
+## 🤖 Provider Setup
+
+### Gemini (Cloud)
+- Export your key: `export GEMINI_API_KEY="your_key"`.
+- Run with `--provider gemini` or set `llm.provider: gemini` in `config.yaml`.
+- You can override the key per run with `--api-key`.
+
+### Local (Ollama)
+- Install Ollama and pull a model (e.g., `ollama pull llama3`).
+- Start AI Shell with `--provider local`; the guided prompt helps select a model and host/port.
+- Connection details are stored in the config for future runs.
+
+## 🛡️ Security & Confirmation
+
+- By default, AI Shell validates commands and asks for confirmation before executing.
+- Use `--no-confirmation` for automation or when running in a controlled environment.
+- Adjust safety lists in `config.yaml` under `security.dangerous_commands` and `security.safe_commands`.
+
+## 📚 Where to Go Next
+
+- **Configuration details:** [docs/CONFIGURATION.md](CONFIGURATION.md)  
+- **Architecture overview:** [docs/ARCHITECTURE.md](ARCHITECTURE.md)  
+- **Examples & tutorials:** [docs/EXAMPLES.md](EXAMPLES.md)  
+- **Troubleshooting tips:** [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)