aia 0.9.24 → 0.10.2

data/docs/examples/tools/index.md

@@ -72,10 +72,10 @@ aia --tools ./tools/ comprehensive_analysis
 ### Tool Security
 ```bash
 # Restrict to specific tools
-aia --tools ./tools/ --allowed_tools "file_analyzer,data_analyzer" safe_analysis
+aia --tools ./tools/ --allowed-tools "file_analyzer,data_analyzer" safe_analysis
 
 # Block potentially dangerous tools
-aia --tools ./tools/ --rejected_tools "system_monitor,process_manager" user_analysis
+aia --tools ./tools/ --rejected-tools "system_monitor,process_manager" user_analysis
 ```
 
 ### Tool Integration in Prompts

data/docs/faq.md

@@ -86,7 +86,7 @@ aia --model ollama/llama3.2,gpt-4o-mini my_prompt
 aia --model ollama/mistral,lms/qwen-coder,claude-3-sonnet --consensus decision
 
 # Use local for drafts, cloud for refinement
-aia --model ollama/llama3.2 --out_file draft.md initial_analysis
+aia --model ollama/llama3.2 --output draft.md initial_analysis
 aia --model gpt-4 --include draft.md final_report
 ```
 
@@ -147,13 +147,13 @@ aia --model gpt-4 my_prompt
 ```
 
 ### Q: How do I set a custom prompts directory?
-**A:** Use the `--prompts_dir` option or set it in configuration:
+**A:** Use the `--prompts-dir` option or set it in configuration:
 ```bash
 # Command line
-aia --prompts_dir /path/to/prompts my_prompt
+aia --prompts-dir /path/to/prompts my_prompt
 
-# Environment variable
-export AIA_PROMPTS_DIR="/path/to/prompts"
+# Environment variable (uses nested naming convention)
+export AIA_PROMPTS__DIR="/path/to/prompts"
 ```
 
 ## Prompts and Directives
@@ -292,7 +292,7 @@ You: /clear
 **A:**
 1. Check your API keys are set correctly
 2. Verify internet connection
-3. Test with: `aia --available_models`
+3. Test with: `aia --available-models`
 
 ### Q: "Permission denied" errors
 **A:**
@@ -396,7 +396,7 @@ git push -u origin main
 **A:** This usually means AIA can't locate your prompt file:
 ```bash
 # Check prompts directory
-ls $AIA_PROMPTS_DIR
+ls $AIA_PROMPTS__DIR
 
 # Verify prompt file exists
 ls ~/.prompts/my_prompt.txt
@@ -409,7 +409,7 @@ aia --fuzzy
 **A:** Check your model name and availability:
 ```bash
 # List available models
-aia --available_models
+aia --available-models
 
 # Check model name spelling
 aia --model gpt-4o-mini  # Correct
@@ -448,7 +448,7 @@ aia --debug --verbose my_prompt
 aia --model gpt-4o-mini my_prompt
 
 # Reduce max tokens
-aia --max_tokens 1000 my_prompt
+aia --max-tokens 1000 my_prompt
 
 # Lower temperature for faster responses
 aia --temperature 0.1 my_prompt
@@ -464,7 +464,7 @@ aia --pipeline "analyze,summarize,report" large_data.csv
 //include specific_section.txt
 
 # Check model context limits
-aia --available_models | grep context
+aia --available-models | grep context
 ```
 
 ### Q: Debug mode - how to get more information?
@@ -485,7 +485,7 @@ aia --debug --config
 | Error | Cause | Solution |
 |-------|-------|----------|
 | "Prompt not found" | Missing prompt file | Check file exists and spelling |
-| "Model not available" | Invalid model name | Use `--available_models` to list valid models |
+| "Model not available" | Invalid model name | Use `--available-models` to list valid models |
 | "Shell command failed" | Invalid shell syntax | Test shell commands separately first |
 | "Configuration error" | Invalid config syntax | Check config file YAML syntax |
 | "API key missing" | No API key configured | Set environment variables for your models |

data/docs/guides/available-models.md

@@ -7,21 +7,21 @@ AIA supports a wide range of AI models through the RubyLLM gem. This comprehensi
 ### Command Line Query
 ```bash
 # List all available models
-aia --available_models
+aia --available-models
 
 # Filter by provider
-aia --available_models openai
-aia --available_models anthropic
-aia --available_models google
+aia --available-models openai
+aia --available-models anthropic
+aia --available-models google
 
 # Filter by capability
-aia --available_models vision
-aia --available_models function_calling
-aia --available_models text_to_image
+aia --available-models vision
+aia --available-models function_calling
+aia --available-models text_to_image
 
 # Complex filtering (AND operation)
-aia --available_models openai,gpt,4
-aia --available_models anthropic,claude,sonnet
+aia --available-models openai,gpt,4
+aia --available-models anthropic,claude,sonnet
 ```
 
 ### Within Prompts
@@ -329,7 +329,7 @@ puts "//config model #{model}"
 # Model fallback chain
 //ruby
 preferred_models = ['gpt-4', 'claude-3-sonnet', 'gpt-3.5-turbo']
-available_models = `aia --available_models`.split("\n").map { |line| line.split.first }
+available_models = `aia --available-models`.split("\n").map { |line| line.split.first }
 
 selected_model = preferred_models.find { |model| available_models.include?(model) }
 puts "//config model #{selected_model || 'gpt-3.5-turbo'}"
@@ -338,7 +338,7 @@ puts "//config model #{selected_model || 'gpt-3.5-turbo'}"
 ## Staying Current
 
 ### Model Updates
-- **Check regularly**: `aia --available_models`
+- **Check regularly**: `aia --available-models`
 - **Version changes**: Models are updated periodically
 - **New releases**: Follow provider announcements
 - **Deprecations**: Some models may be retired

data/docs/guides/basic-usage.md

@@ -34,13 +34,13 @@ Control where and how AIA saves results:
 
 ```bash
 # Save to file
-aia --out_file result.md analysis_prompt data.csv
+aia --output result.md analysis_prompt data.csv
 
 # Append to existing file
-aia --out_file log.md --append status_check
+aia --output log.md --append status_check
 
 # Format with markdown
-aia --out_file report.md --markdown comprehensive_analysis
+aia --output report.md --markdown comprehensive_analysis
 ```
 
 ## Common Workflow Patterns
@@ -108,8 +108,8 @@ debug: false
 
 ```bash
 # Use environment-specific configs
-aia --config_file ~/.aia/dev_config.yml development_task
-aia --config_file ~/.aia/prod_config.yml production_analysis
+aia --config-file ~/.aia/dev_config.yml development_task
+aia --config-file ~/.aia/prod_config.yml production_analysis
 ```
 
 ### Task-Specific Model Selection
@@ -216,7 +216,7 @@ Validate inputs before processing:
 test -f input.csv && aia data_analysis input.csv || echo "Input file not found"
 
 # Verify model availability
-aia --available_models | grep -q "gpt-4" && aia --model gpt-4 task || aia task
+aia --available-models | grep -q "gpt-4" && aia --model gpt-4 task || aia task
 ```
 
 ## Performance Optimization
@@ -237,11 +237,11 @@ Handle multiple similar tasks efficiently:
 ```bash
 # Process multiple files
 for file in *.py; do
-  aia code_review "$file" --out_file "reviews/${file%.py}_review.md"
+  aia code_review "$file" --output "reviews/${file%.py}_review.md"
 done
 
 # Parallel processing
-parallel -j4 aia analysis_task {} --out_file {.}_analysis.md ::: *.csv
+parallel -j4 aia analysis_task {} --output {.}_analysis.md ::: *.csv
 ```
 
 ### Caching and Reuse
@@ -250,7 +250,7 @@ Avoid redundant processing:
 ```bash
 # Check if output exists before processing
 output_file="analysis_$(date +%Y%m%d).md"
-test -f "$output_file" || aia daily_analysis --out_file "$output_file"
+test -f "$output_file" || aia daily_analysis --output "$output_file"
 
 # Reuse previous analysis
 aia followup_analysis --previous_analysis yesterday_analysis.md
@@ -266,11 +266,11 @@ Integrate AIA into shell workflows:
 # Automated analysis script
 
 echo "Starting analysis..."
-aia system_health_check --out_file health_$(date +%Y%m%d_%H%M).md
+aia system_health_check --output health_$(date +%Y%m%d_%H%M).md
 
 if [ $? -eq 0 ]; then
     echo "Health check complete"
-    aia generate_report --source health_*.md --out_file daily_report.md
+    aia generate_report --source health_*.md --output daily_report.md
 else
     echo "Health check failed, investigating..."
     aia troubleshoot_system --debug --verbose
@@ -316,7 +316,7 @@ jobs:
         run: gem install aia
       - name: Run Analysis
         run: |
-          aia pr_analysis --diff_only --out_file analysis.md
+          aia pr_analysis --diff_only --output analysis.md
           cat analysis.md >> $GITHUB_STEP_SUMMARY
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
@@ -327,7 +327,7 @@ jobs:
 ### Model and API Issues
 ```bash
 # Test model availability
-aia --available_models | grep "gpt-4" || echo "GPT-4 not available"
+aia --available-models | grep "gpt-4" || echo "GPT-4 not available"
 
 # Test API connection
 aia --model gpt-3.5-turbo --debug simple_test_prompt
@@ -415,16 +415,17 @@ Add these powerful aliases and functions to your shell configuration:
 
 ```bash
 # ~/.bashrc_aia (or add to ~/.bashrc)
-export AIA_PROMPTS_DIR=~/.prompts
-export AIA_OUT_FILE=./temp.md
+# Uses nested naming convention with double underscore
+export AIA_PROMPTS__DIR=~/.prompts
+export AIA_OUTPUT__FILE=./temp.md
 export AIA_MODEL=gpt-4o-mini
-export AIA_VERBOSE=true  # Shows spinner while waiting for LLM response
+export AIA_FLAGS__VERBOSE=true  # Shows spinner while waiting for LLM response
 
 # Quick chat alias
 alias chat='aia --chat --terse'
 
 # Quick question function
-ask() { echo "$1" | aia run --no-out_file; }
+ask() { echo "$1" | aia run --no-output; }
 ```
 
 **Usage Examples:**

data/docs/guides/chat.md

@@ -22,7 +22,7 @@ aia --chat --role assistant my_context.txt
 aia --chat my_initial_prompt
 
 # Chat with system prompt
-aia --chat --system_prompt helpful_assistant
+aia --chat --system-prompt helpful_assistant
 
 # Chat with role-based context
 aia --chat --role code_expert debugging_session
@@ -190,7 +190,7 @@ aia --chat --tools ./my_tools.rb
 aia --chat --tools ./tools/
 
 # Restrict tool access
-aia --chat --tools ./tools/ --allowed_tools "file_reader,calculator"
+aia --chat --tools ./tools/ --allowed-tools "file_reader,calculator"
 ```
 
 #### Using Tools in Conversation
@@ -216,7 +216,7 @@ Available Tools:
 ### Code Review Session
 ```bash
 # Start specialized code review chat
-aia --chat --role code_expert --system_prompt code_reviewer
+aia --chat --role code_expert --system-prompt code_reviewer
 
 You: I need help reviewing this Python function:
 //include my_function.py
@@ -259,7 +259,7 @@ AI: Here's how we can make it more engaging...
 ### Learning Session
 ```bash
 # Start educational chat
-aia --chat --role teacher --system_prompt patient_explainer
+aia --chat --role teacher --system-prompt patient_explainer
 
 You: Explain how blockchain works, but I'm completely new to this
 AI: Let me explain blockchain in simple terms, starting from the basics...
@@ -279,19 +279,19 @@ aia --chat --speak
 aia --chat --speak --voice nova
 
 # Use high-quality speech model
-aia --chat --speak --speech_model tts-1-hd
+aia --chat --speak --speech-model tts-1-hd
 ```
 
 ### Audio Input
 ```bash
 # Use speech-to-text for input
-aia --chat --transcription_model whisper-1 audio_input.wav
+aia --chat --transcription-model whisper-1 audio_input.wav
 ```
 
 ### Interactive Voice Chat
 ```bash
 # Full voice interaction
-aia --chat --speak --voice echo --transcription_model whisper-1
+aia --chat --speak --voice echo --transcription-model whisper-1
 
 # Great for hands-free operation or accessibility
 ```
@@ -421,6 +421,52 @@ class ChatCommands < RubyLLM::Tool
 end
 ```
 
+## Token Usage and Cost Tracking
+
+### Displaying Token Usage
+Use the `--tokens` flag to see token usage after each response:
+
+```bash
+# Enable token usage display
+aia --chat --tokens
+
+# Example output after a response:
+# AI: Here's my response to your question...
+#
+# Tokens: input=125, output=89, model=gpt-4o-mini
+```
+
+### Cost Estimation
+Use the `--cost` flag to include cost calculations with token usage:
+
+```bash
+# Enable cost estimation (automatically enables --tokens)
+aia --chat --cost
+
+# Example output after a response:
+# AI: Here's my response to your question...
+#
+# Tokens: input=125, output=89, model=gpt-4o-mini
+# Cost: $0.0003 (input: $0.0002, output: $0.0001)
+```
+
+### Multi-Model Token Tracking
+When using multiple models, token usage is displayed for each model:
+
+```bash
+aia --chat --tokens --model gpt-4,claude-3-sonnet
+
+# Example output:
+# from: gpt-4
+# Here's my response...
+#
+# from: claude-3-sonnet
+# Here's my alternative response...
+#
+# Model: gpt-4 - Tokens: input=125, output=89
+# Model: claude-3-sonnet - Tokens: input=125, output=112
+```
+
 ## Troubleshooting Chat Mode
 
 ### Common Issues
@@ -498,19 +544,19 @@ aia --pipeline "data_prep,analysis" --chat dataset.csv
 ### Configuration Integration
 ```bash
 # Use predefined configurations in chat
-aia --config_file chat_setup.yml --chat
+aia --config-file chat_setup.yml --chat
 
 # Override specific settings
-aia --chat --temperature 0.9 --max_tokens 3000
+aia --chat --temperature 0.9 --max-tokens 3000
 ```
 
 ### Output Integration
 ```bash
 # Save chat output to file
-aia --chat --out_file discussion.md --markdown
+aia --chat --output discussion.md --markdown
 
 # Append to existing files
-aia --chat --out_file project_log.md --append
+aia --chat --output project_log.md --append
 ```
 
 ## Related Documentation

data/docs/guides/executable-prompts.md

@@ -11,7 +11,7 @@ Executable prompts are prompt files with a special shebang line that makes them
 ### Basic Structure
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Your prompt description and comments
 
 Your prompt content here...
@@ -20,7 +20,7 @@ Your prompt content here...
 ### Key Components
 
 1. **Shebang Line**: Must include `--exec` flag to enable prompt processing
-2. **Output Configuration**: Use `--no-out_file` to send output to STDOUT
+2. **Output Configuration**: Use `--no-output` to send output to STDOUT
 3. **Executable Permissions**: Make file executable with `chmod +x`
 
 ## The `run` Prompt Pattern
@@ -56,7 +56,7 @@ This pattern allows for quick one-shot questions without creating specific promp
 Create a weather monitoring executable:
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Get current storm activity for the east and south coast of the US
 
 Summarize the tropical storm outlook for the Atlantic, Caribbean Sea and Gulf of America.
@@ -79,7 +79,7 @@ chmod +x weather_report
 ### System Status Monitor
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # System health check and analysis
 
 Analyze the current system status and provide recommendations:
@@ -102,7 +102,7 @@ Provide analysis and recommendations for system optimization.
 ### Code Quality Checker
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Analyze code quality for the current directory
 
 //config model = gpt-4
@@ -125,7 +125,7 @@ Provide code quality assessment and improvement recommendations.
 ### Daily Standup Generator
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Generate daily standup report from git activity
 
 //config model = gpt-4o-mini
@@ -151,7 +151,7 @@ Provide a structured standup report.
 Create executable prompts that accept command-line parameters:
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Code review for specific file
 # Usage: ./code_review <filename>
 
@@ -172,7 +172,7 @@ Provide specific, actionable feedback for improvements.
 Chain multiple prompts in an executable workflow:
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Complete project analysis pipeline
 
 //pipeline project_scan,security_check,recommendations
@@ -183,7 +183,7 @@ Starting comprehensive project analysis...
 ### Conditional Logic Executables
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Environment-aware deployment checker
 
 //ruby
@@ -216,7 +216,7 @@ Analyze the deployment configuration and provide environment-specific recommenda
 ### As Git Hooks
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # .git/hooks/pre-commit
 # Automated commit message analysis
 
@@ -285,7 +285,7 @@ chmod 700 sensitive_prompt     # Owner only
 ### Error Handling
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Robust executable with error handling
 
 //ruby
@@ -327,7 +327,7 @@ Analyze the file structure, quality, and provide recommendations.
 ### Enable Debug Mode
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec --debug --verbose
+#!/usr/bin/env aia run --no-output --exec --debug --verbose
 # Debug version of your executable prompt
 ```
 
@@ -352,14 +352,14 @@ git status
 | "Permission denied" | File not executable | `chmod +x filename` |
 | "Command not found" | Missing shebang or wrong path | Check shebang line |
 | "Prompt not found" | Missing run prompt | Create ~/.prompts/run.txt |
-| "Output not appearing" | Missing --no-out_file | Add flag to shebang |
+| "Output not appearing" | Missing --no-output | Add flag to shebang |
 
 ## Advanced Executable Patterns
 
 ### Self-Documenting Executables
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Self-documenting code analyzer
 # Usage: ./code_analyzer [--help] <directory>
 
@@ -384,7 +384,7 @@ end
 ### Multi-Stage Executables
 
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Multi-stage project analysis
 
 //ruby

data/docs/guides/first-prompt.md

@@ -385,7 +385,7 @@ git commit -m "My first AIA prompts"
 aia --help
 
 # Model information
-aia --available_models
+aia --available-models
 
 # Debug information
 aia --debug my_prompt
@@ -417,7 +417,7 @@ ls ~/.prompts/your_prompt.txt
 chmod 644 ~/.prompts/your_prompt.txt
 
 # Use full path if needed
-aia --prompts_dir ~/.prompts your_prompt
+aia --prompts-dir ~/.prompts your_prompt
 ```
 
 ### API Errors

data/docs/guides/getting-started.md

@@ -53,7 +53,7 @@ aia --model gpt-4 --chat
 aia --model claude-3-sonnet --chat
 
 # See all available models
-aia --available_models
+aia --available-models
 ```
 
 ### 3. Adjusting AI Behavior
@@ -71,7 +71,7 @@ aia --temperature 0.3 --chat
 aia --terse --chat
 
 # Limit response length
-aia --max_tokens 100 --chat
+aia --max-tokens 100 --chat
 ```
 
 ## Creating Your First Prompt
@@ -239,13 +239,13 @@ Save AI responses to files:
 
 ```bash
 # Save to a file
-aia --out_file response.md my_prompt
+aia --output response.md my_prompt
 
 # Append to an existing file
-aia --out_file response.md --append my_prompt
+aia --output response.md --append my_prompt
 
 # Format with Markdown
-aia --out_file response.md --markdown my_prompt
+aia --output response.md --markdown my_prompt
 ```
 
 ## Chat Mode Features
@@ -426,7 +426,7 @@ Now that you understand the basics:
 
 #### "Model not available"
 - Check your API keys: `echo $OPENAI_API_KEY`
-- List available models: `aia --available_models`
+- List available models: `aia --available-models`
 - Check your internet connection
 
 #### "Permission denied"