aia 0.9.19 → 0.9.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fb298b4e9a1ddc4748425decde69e1c11d8e7eb195cf264b918c4d69bf64e01
-  data.tar.gz: a0cffea9fec68a81fbe5e5d36fed20255e33c1d230ec0dd518e08ad7adc56afa
+  metadata.gz: 2d974eb8f23ef8b3af71447951101047c7bdf04a203d4690655b8bfbe940fb2f
+  data.tar.gz: d63ff74f8837d642a454e116e2efb29f5a57d2d3e37a0e1181378d93d15f4660
 SHA512:
-  metadata.gz: 6076117839c543fda6756e6657f69d9c35fb561213697e464701eb1515a1d38cff130e7cc57159bf44a8586387144257887906e2ffc63cf183886e816cfd6b84
-  data.tar.gz: 42a6d282bcf587edf84e0db8d13998e0f233f9a66f52977cbaa2d0c152d44e7691207a48a8bec68800e18b1abe81bd2964d841c29eca7437a69f91a2febfd67b
+  metadata.gz: 1c20c13f8d2c80abcc1dafc0401d6bfb3c1c1045ff4dc0821b3de256ba59241938a076f0cb74583758e1bbadd2e31cd933a2137440eee1a78e4adea794e66ea6
+  data.tar.gz: f7b6d1301362e22ccb3ef07956f5a9fe3766504ec23a2df82b420ab330b2e628406a1ce98b43dced48ab4142d49ccc5f7737f6fef0e9c9bded5d4ecda8626c8a

data/.version

@@ -1 +1 @@
-0.9.19
+0.9.21

data/CHANGELOG.md

@@ -1,14 +1,85 @@
 # Changelog
 ## [Unreleased]
 
-### [0.9.19] 2025-10-06
-
-#### Bug Fixes
+## [0.9.21] 2025-10-08
+### Bug Fixes
+- **Checkpoint Directive Output**: Fixed `//checkpoint` directive to return empty string instead of status message (lib/aia/directives/configuration.rb:155)
+  - Prevents checkpoint creation messages from entering AI context
+  - Outputs confirmation to STDOUT instead for user feedback
+  - Prevents potential AI manipulation of checkpoint system
+
+## [0.9.20] 2025-10-06
+### Added
+- **Enhanced Multi-Model Role System (ADR-005)**: Implemented per-model role assignment with inline syntax
+  - New inline syntax: `--model MODEL[=ROLE][,MODEL[=ROLE]]...`
+  - Example: `aia --model gpt-4o=architect,claude=security,gemini=performance design_doc.md`
+  - Support for duplicate models with different roles: `gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist`
+  - Added `--list-roles` command to discover available role files
+  - Display format shows instance numbers and roles: `gpt-4o #1 (optimist):`, `gpt-4o #2 (pessimist):`
+  - Consensus mode drops role for neutral synthesis
+  - Chat mode roles are immutable during session
+  - Nested role path support: `--model gpt-4o=specialized/architect`
+  - Full backward compatibility with existing `--role` flag
+
+- **Config File Model Roles Support (ADR-005 v2)**:
+  - Enhanced `model` key in config files to support array of hashes with roles
+  - Format: `model: [{model: gpt-4o, role: architect}, {model: claude, role: security}]`
+  - Mirrors internal data structure (array of hashes with `model`, `role`, `instance`, `internal_id`)
+  - Supports models without roles: `model: [{model: gpt-4o}]`
+  - Enables reusable model-role setups across sessions
+  - Configuration precedence: CLI inline > CLI flag > Environment variable > Config file
+
+- **Environment Variable Inline Syntax (ADR-005 v2)**:
+  - Added support for inline role syntax in `AIA_MODEL` environment variable
+  - Example: `export AIA_MODEL="gpt-4o=architect,claude=security,gemini=performance"`
+  - Maintains backward compatibility with simple comma-separated model lists
+  - Detects `=` to distinguish between formats
+
+### Bug Fixes
+- **Multi-Model Chat Cross-Talk**: Fixed bug where model instances with different roles could see each other's conversation history
+  - Updated Session to properly extract `internal_id` from hash-based model specs (lib/aia/session.rb:47-68)
+  - Fixed `parse_multi_model_response` to normalize display names to internal IDs (lib/aia/session.rb:538-570)
+  - Each model instance now maintains completely isolated conversation context
+  - Fixes issue where models would respond as if aware of other models' perspectives
+
+### Improvements
+- **Robot ASCII Display**: Updated `robot` method to extract and display only model names from new hash format (lib/aia/utility.rb:24-53)
+  - Handles string, array of strings, and array of hashes formats
+  - Shows clean model list: "gpt-4o, claude, gemini" instead of hash objects
+
+### Testing
+- Added comprehensive test suite for config file and environment variable model roles
+  - test/aia/config_model_roles_test.rb: 8 tests covering array processing, env var parsing, YAML config files
+- Added 15 tests for role parsing with inline syntax (test/aia/role_parsing_test.rb)
+- Fixed Mocha test cleanup in multi_model_isolation_test.rb
+- Full test suite: 306 runs, 980 assertions, 0 failures (1 pre-existing Mocha isolation issue)
+
+### Technical Implementation
+- Modified `config.model` to support array of hashes with model metadata: `{model:, role:, instance:, internal_id:}`
+- Added `parse_models_with_roles` method with fail-fast validation (lib/aia/config/cli_parser.rb)
+- Added `validate_role_exists` with helpful error messages showing available roles
+- Added `list_available_roles` and `list_available_role_names` methods for role discovery
+- Added `load_role_for_model` method to PromptHandler for per-model role loading (lib/aia/prompt_handler.rb)
+- Enhanced RubyLLMAdapter to handle hash-based model specs and prepend roles per model
+  - Added `extract_model_names` to extract model names from specs
+  - Added `get_model_spec` to retrieve full spec by internal_id
+  - Added `prepend_model_role` to inject role content into prompts
+  - Added `format_model_display_name` for consistent display formatting
+- Updated Session initialization to handle hash-based model specs for context managers
+- Updated display formatting to show instance numbers and roles
+- Maintained backward compatibility with string/array model configurations
+- Added `process_model_array_with_roles` method in FileLoader (lib/aia/config/file_loader.rb:91-116)
+- Enhanced `apply_file_config_to_struct` to detect and process model arrays with role hashes
+- Enhanced `envar_options` to parse inline syntax for `:model` key (lib/aia/config/base.rb:212-217)
+
+## [0.9.19] 2025-10-06
+
+### Bug Fixes
 - **CRITICAL BUG FIX**: Fixed multi-model cross-talk issue (#118) where models could see each other's conversation history
 - **BUG FIX**: Implemented complete two-level context isolation to prevent models from contaminating each other's responses
 - **BUG FIX**: Fixed token count inflation caused by models processing combined conversation histories
 
-#### Technical Changes
+### Technical Changes
 - **Level 1 (Library)**: Implemented per-model RubyLLM::Context isolation - each model now has its own Context instance (lib/aia/ruby_llm_adapter.rb)
 - **Level 2 (Application)**: Implemented per-model ContextManager isolation - each model maintains its own conversation history (lib/aia/session.rb)
 - Added `parse_multi_model_response` method to extract individual model responses from combined output (lib/aia/session.rb:502-533)
@@ -23,17 +94,17 @@
 - Added comprehensive test coverage with 6 new tests for multi-model isolation
 - Updated LocalProvidersTest to reflect Context-based architecture
 
-#### Architecture
+### Architecture
 - **ADR-002-revised**: Complete Multi-Model Isolation (see `.architecture/decisions/adrs/ADR-002-revised-multi-model-isolation.md`)
 - Eliminated global state dependencies in multi-model chat sessions
 - Maintained backward compatibility with single-model mode (verified with tests)
 
-#### Test Coverage
+### Test Coverage
 - Added `test/aia/multi_model_isolation_test.rb` with comprehensive isolation tests
 - Tests cover: response parsing, per-model context managers, single-model compatibility, RubyLLM::Context isolation
 - Full test suite: 282 runs, 837 assertions, 0 failures, 0 errors, 13 skips ✅
 
-#### Expected Behavior After Fix
+### Expected Behavior After Fix
 Previously, when running multi-model chat with repeated prompts:
 - ❌ Models would see BOTH their own AND other models' responses
 - ❌ Models would report inflated counts (e.g., "5 times", "6 times" instead of "3 times")
@@ -44,7 +115,7 @@ Now with the fix:
 - ✅ Each model correctly reports its own interaction count
 - ✅ Token counts accurately reflect per-model conversation size
 
-#### Usage Examples
+### Usage Examples
 ```bash
 # Multi-model chat now properly isolates each model's context
 bin/aia --chat --model lms/openai/gpt-oss-20b,ollama/gpt-oss:20b --metrics
@@ -64,47 +135,47 @@ bin/aia --chat --model lms/openai/gpt-oss-20b,ollama/gpt-oss:20b --metrics
 # (Previously: LMS would say "5 times", Ollama "6 times" due to cross-talk)
 ```
 
-### [0.9.18] 2025-10-05
+## [0.9.18] 2025-10-05
 
-#### Bug Fixes
+### Bug Fixes
 - **BUG FIX**: Fixed RubyLLM provider error parsing to handle both OpenAI and LM Studio error formats
 - **BUG FIX**: Fixed "String does not have #dig method" errors when parsing error responses from local providers
 - **BUG FIX**: Enhanced error parsing to gracefully handle malformed JSON responses
 
-#### Improvements
+### Improvements
 - **ENHANCEMENT**: Removed debug output statements from RubyLLMAdapter for cleaner production logs
 - **ENHANCEMENT**: Improved error handling with debug logging for JSON parsing failures
 
-#### Documentation
+### Documentation
 - **DOCUMENTATION**: Added Local Models entry to MkDocs navigation for better documentation accessibility
 
-#### Technical Changes
+### Technical Changes
 - Enhanced provider_fix extension to support multiple error response formats (lib/extensions/ruby_llm/provider_fix.rb)
 - Cleaned up debug puts statements from RubyLLMAdapter and provider_fix
 - Added robust JSON parsing with fallback error handling
 
-### [0.9.17] 2025-10-04
+## [0.9.17] 2025-10-04
 
-#### New Features
+### New Features
 - **NEW FEATURE**: Enhanced local model support with comprehensive validation and error handling
 - **NEW FEATURE**: Added `lms/` prefix support for LM Studio models with automatic validation against loaded models
 - **NEW FEATURE**: Enhanced `//models` directive to auto-detect and display local providers (Ollama and LM Studio)
 - **NEW FEATURE**: Added model name prefix display in error messages for LM Studio (`lms/` prefix)
 
-#### Improvements
+### Improvements
 - **ENHANCEMENT**: Improved LM Studio integration with model validation against `/v1/models` endpoint
 - **ENHANCEMENT**: Enhanced error messages showing exact model names with correct prefixes when validation fails
 - **ENHANCEMENT**: Added environment variable support for custom LM Studio API base (`LMS_API_BASE`)
 - **ENHANCEMENT**: Improved `//models` directive output formatting for local models with size and modified date for Ollama
 - **ENHANCEMENT**: Enhanced multi-model support to seamlessly mix local and cloud models
 
-#### Documentation
+### Documentation
 - **DOCUMENTATION**: Added comprehensive local model documentation to README.md
 - **DOCUMENTATION**: Created new docs/guides/local-models.md guide covering Ollama and LM Studio setup, usage, and troubleshooting
 - **DOCUMENTATION**: Updated docs/guides/models.md with local provider sections including comparison table and workflow examples
 - **DOCUMENTATION**: Enhanced docs/faq.md with 5 new FAQ entries covering local model usage, differences, and error handling
 
-#### Technical Changes
+### Technical Changes
 - Enhanced RubyLLMAdapter with LM Studio model validation (lib/aia/ruby_llm_adapter.rb)
 - Updated models directive to query local provider endpoints (lib/aia/directives/models.rb)
 - Added provider_fix extension for RubyLLM compatibility (lib/extensions/ruby_llm/provider_fix.rb)
@@ -112,12 +183,12 @@ bin/aia --chat --model lms/openai/gpt-oss-20b,ollama/gpt-oss:20b --metrics
 - Updated dependencies: ruby_llm, webmock, crack, rexml
 - Bumped Ruby bundler version to 2.7.2
 
-#### Bug Fixes
+### Bug Fixes
 - **BUG FIX**: Fixed missing `lms/` prefix in LM Studio model listings
 - **BUG FIX**: Fixed model validation error messages to show usable model names with correct prefixes
 - **BUG FIX**: Fixed Ollama endpoint to use native API (removed incorrect `/v1` suffix)
 
-#### Usage Examples
+### Usage Examples
 ```bash
 # Use LM Studio with validation
 aia --model lms/qwen/qwen3-coder-30b my_prompt
@@ -133,75 +204,74 @@ aia --model ollama/llama3.2 --chat
 > //models
 ```
 
-### [0.9.16] 2025-09-26
+## [0.9.16] 2025-09-26
 
-#### New Features
+### New Features
 - **NEW FEATURE**: Added support for Ollama AI provider
 - **NEW FEATURE**: Added support for Osaurus AI provider
 - **NEW FEATURE**: Added support for LM Studio AI provider
 
-#### Improvements
+### Improvements
 - **ENHANCEMENT**: Expanded AI provider ecosystem with three new local/self-hosted model options
 - **ENHANCEMENT**: Improved flexibility for users preferring local LLM deployments
 
-## Released
-### [0.9.15] 2025-09-21
+## [0.9.15] 2025-09-21
 
-#### New Features
+### New Features
 - **NEW FEATURE**: Added `//paste` directive to insert clipboard contents into prompts
 - **NEW FEATURE**: Added `//clipboard` alias for the paste directive
 
-#### Technical Changes
+### Technical Changes
 - Enhanced DirectiveProcessor with clipboard integration using the clipboard gem
 - Added comprehensive test coverage for paste directive functionality
 
-### [0.9.14] 2025-09-19
+## [0.9.14] 2025-09-19
 
-#### New Features
+### New Features
 - **NEW FEATURE**: Added `//checkpoint` directive to create named snapshots of conversation context
 - **NEW FEATURE**: Added `//restore` directive to restore context to a previous checkpoint
 - **NEW FEATURE**: Enhanced `//context` (and `//review`) directive to display checkpoint markers in conversation history
 - **NEW FEATURE**: Added `//cp` alias for checkpoint directive
 
-#### Improvements
+### Improvements
 - **ENHANCEMENT**: Context manager now tracks checkpoint positions for better context visualization
 - **ENHANCEMENT**: Checkpoint system uses auto-incrementing integer names when no name is provided
 - **ENHANCEMENT**: Restore directive defaults to last checkpoint when no name specified
 - **ENHANCEMENT**: Clear context now also clears all checkpoints
 
-#### Bug Fixes
+### Bug Fixes
 - **BUG FIX**: Fixed `//help` directive that was showing empty list of directives
 - **BUG FIX**: Help directive now displays all directives from all registered modules
 - **BUG FIX**: Help directive now shows proper descriptions and aliases for all directives
 - **BUG FIX**: Help directive organizes directives by category for better readability
 
-#### Technical Changes
+### Technical Changes
 - Enhanced ContextManager with checkpoint storage and restoration capabilities
 - Added checkpoint_positions method to track checkpoint locations in context
 - Refactored help directive to collect directives from all registered modules
 - Added comprehensive test coverage for checkpoint and restore functionality
 
-### [0.9.13] 2025-09-02
-#### New Features
+## [0.9.13] 2025-09-02
+### New Features
 - **NEW FEATURE**: Added `--metrics` flag to show token counts for each model
 - **NEW FEATURE**: Added `--cost` flag to enable cost estimation for each model
 
-#### Improvements
+### Improvements
 - **DEPENDENCY**: Removed versionaire dependency, simplifying version management
 - **ENHANCEMENT**: Improved test suite reliability and coverage
 - **ENHANCEMENT**: Updated Gemfile.lock with latest dependency versions
 
-#### Bug Fixes
+### Bug Fixes
 - **BUG FIX**: Fixed version handling issues by removing external versioning dependency
 
-#### Technical Changes
+### Technical Changes
 - Simplified version management by removing versionaire gem
 - Enhanced test suite with improved assertions and coverage
 - Updated various gem dependencies to latest stable versions
 
-### [0.9.12] 2025-08-28
+## [0.9.12] 2025-08-28
 
-#### New Features
+### New Features
 - **MAJOR NEW FEATURE**: Multi-model support - specify multiple AI models simultaneously with comma-separated syntax
 - **NEW FEATURE**: `--consensus` flag to enable primary model consensus mode for synthesized responses from multiple models
 - **NEW FEATURE**: `--no-consensus` flag to explicitly force individual responses from all models
@@ -212,21 +282,21 @@ aia --model ollama/llama3.2 --chat
 - **NEW FEATURE**: Multi-model support in both batch and interactive chat modes
 - **NEW FEATURE**: Comprehensive documentation website https://madbomber.github.io/aia/
 
-#### Improvements
+### Improvements
 - **ENHANCEMENT**: Enhanced `//model` directive output with detailed multi-model configuration display
 - **ENHANCEMENT**: Improved error handling with graceful fallback when model initialization fails
 - **ENHANCEMENT**: Better TTY handling in chat mode to prevent `Errno::ENXIO` errors in containerized environments
 - **ENHANCEMENT**: Updated directive processor to use new module-based architecture for better maintainability
 - **ENHANCEMENT**: Improved batch mode output file formatting consistency between STDOUT and file output
 
-#### Bug Fixes
+### Bug Fixes
 - **BUG FIX**: Fixed DirectiveProcessor TypeError that prevented application startup with invalid directive calls
 - **BUG FIX**: Fixed missing primary model output in batch mode output files
 - **BUG FIX**: Fixed inconsistent formatting between STDOUT and file output in batch mode
 - **BUG FIX**: Fixed TTY availability issues in chat mode for containerized environments
 - **BUG FIX**: Fixed directive processing to use updated module-based registry system
 
-#### Technical Changes
+### Technical Changes
 - Fixed ruby_llm version to 1.5.1
 - Added extra API_KEY configuration for new LLM providers
 - Updated RubyLLMAdapter to support multiple model initialization and management
@@ -235,13 +305,13 @@ aia --model ollama/llama3.2 --chat
 - Updated CLI parser to support multi-model flags and options
 - Enhanced configuration system to support consensus mode settings
 
-#### Documentation
+### Documentation
 - **DOCUMENTATION**: Comprehensive README.md updates with multi-model usage examples and best practices
 - **DOCUMENTATION**: Added multi-model section to README with detailed usage instructions
 - **DOCUMENTATION**: Updated command-line options table with new multi-model flags
 - **DOCUMENTATION**: Added practical multi-model examples for decision-making scenarios
 
-#### Usage Examples
+### Usage Examples
 ```bash
 # Basic multi-model usage
 aia my_prompt -m gpt-4o-mini,gpt-3.5-turbo
@@ -256,25 +326,25 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 //model  # Use in any prompt or chat session
 ```
 
-#### Migration Notes
+### Migration Notes
 - Existing single-model usage remains unchanged and fully compatible
 - Multi-model is opt-in via comma-separated model names
 - Default behavior without `--consensus` flag shows individual responses from all models
 - Invalid model names are reported but don't prevent valid models from working
 
-#### TODO
+### TODO
 - TODO: focus on log file consistency using Logger
 
 
-### [0.9.11] 2025-07-31
+## [0.9.11] 2025-07-31
 - added a cost per 1 million input tokens to available_models query output
 - updated ruby_llm to version 1.4.0
 - updated all other gem dependencies to their latest versions
 
-### [0.9.10] 2025-07-18
+## [0.9.10] 2025-07-18
 - updated ruby_llm-mcp to version 0.6.1 which solves problems with MCP tools not being installed
 
-### [0.9.9] 2025-07-10
+## [0.9.9] 2025-07-10
 - refactored the Session and Config classes into more testable method_missing
 - updated the test suire for both the Session and Config classes
 - added support for MCP servers coming into AIA via the shared_tools gem
@@ -285,13 +355,13 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - //available_models now has context window size and capabilities for each model returned
 
 
-### [0.9.8] 2025-06-25
+## [0.9.8] 2025-06-25
 - fixing an issue with pipelined prompts
 - now showing the complete modality of the model on the processing line.
 - changed -p option from prompts_dir to pipeline
 - found problem with simple cov and deep cov w/r/t their reported test coverage; they have problems with heredoc and complex conditionals.
 
-### [0.9.7] 2025-06-20
+## [0.9.7] 2025-06-20
 
 - **NEW FEATURE**: Added `--available_models` CLI option to list all available AI models
 - **NEW FEATURE**: Added `//tools` to show a list of available tools and their description
@@ -302,7 +372,7 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - **DOCUMENTATION**: Updated README for better clarity and structure
 - **DEPENDENCY**: Updated Gemfile.lock with latest dependency versions
 
-### [0.9.6] 2025-06-13
+## [0.9.6] 2025-06-13
 - fixed issue 84 with the //llms directive
 - changed the monkey patch to the RubyLLM::Model::Modalities class at the suggestions of the RubyLLM author in prep for a PR against that gem.
 - added the shared_tools gem - need to add examples on how to use it with the --tools option
@@ -310,11 +380,11 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - added images/aia.png to README.md
 - let claude code rewrite the README.md file.  Some details were dropped but overall in reads better.  Need to add the details to a wiki or other documentation site.
 
-### [0.9.5] 2025-06-04
+## [0.9.5] 2025-06-04
 - changed the RubyLLM::Modalities class to use method_missing for mode query
 - hunting for why the //llms query directive is not finding image_to_image LLMs.
 
-### [0.9.4] 2025-06-03
+## [0.9.4] 2025-06-03
 - using RubyLLM v1.3.0
 - setting up a docs infrastructure to behave like the ruby_llm gem's guides side
 - fixed bug in the text-to-image workflow
@@ -322,7 +392,7 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - need to pay attention to the test suite
 - also need to ensure the non text2text modes are working
 
-### [0.9.3rc1] 2025-05-24
+## [0.9.3rc1] 2025-05-24
 - using ruby_llm v1.3.0rc1
 - added a models database refresh based on integer days interval with the --refresh option
 - config file now has a "last_refresh" String in format YYYY-MM-DD
@@ -331,43 +401,41 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - fixed a bug in the prompt_manager gem which is now at v0.5.5
 
 
-### [0.9.2] 2025-05-18
+## [0.9.2] 2025-05-18
 - removing the MCP experiment
 - adding support for RubyLLM::Tool usage in place of the MCP stuff
 - updated prompt_manager to v0.5.4 which fixed shell integration problem
 
-### [0.9.1] 2025-05-16
+## [0.9.1] 2025-05-16
 - rethink MCP approach in favor of just RubyLLM::Tool
 - fixed problem with //clear
 - fixed a problem with a priming prompt in a chat loop
 
-### [0.9.0] 2025-05-13
+## [0.9.0] 2025-05-13
 - Adding experimental MCP Client suppot
 - removed the CLI options --erb and --shell but kept them in the config file with a default of true for both
 
-### [0.8.6] 2025-04-23
+## [0.8.6] 2025-04-23
 - Added a client adapter for the ruby_llm gem
 - Added the adapter config item and the --adapter option to select at runtime which client to use ai_client or ruby_llm
 
-### [0.8.5] 2025-04-19
+## [0.8.5] 2025-04-19
 - documentation updates
 - integrated the https://pure.md web service for inserting web pages into the context window
    - //include http?://example.com/stuff
    - //webpage http?://example.com/stuff
 
-### [0.8.2] 2025-04-18
+## [0.8.2] 2025-04-18
 - fixed problems with pre-loaded context and chat repl
 - piped content into `aia --chat` is now a part of the context/instructions
 - content via "aia --chat < some_file" is added to the context/instructions
 - `aia --chat context_file.txt context_file2.txt` now works
 - `aia --chat prompt_id context)file.txt` also works
 
-
-
-### [0.8.1] 2025-04-17
+## [0.8.1] 2025-04-17
 - bumped version to 0.8.1 after correcting merge conflicts
 
-### [0.8.0] WIP - 2025-04-15
+## [0.8.0] WIP - 2025-04-15
 - Updated PromptManager to v0.5.1 which has some of the functionality that was originally developed in the AIA.
 - Enhanced README.md to include a comprehensive table of configuration options with defaults and associated environment variables.
 - Added a note in README.md about the expandability of configuration options from a config file for dynamic prompt generation.
@@ -375,7 +443,7 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - Ensured version consistency across `.version`, `aia.gemspec`, and `lib/aia/version.rb`.
 - Verified and updated documentation to ensure readiness for release on RubyGems.org.
 
-### [0.7.1] WIP - 2025-03-22
+## [0.7.1] WIP - 2025-03-22
 - Added `UIPresenter` class for handling user interface presentation.
 - Added `DirectiveProcessor` class for processing chat-based directives.
 - Added `HistoryManager` class for managing conversation and variable history.
@@ -389,7 +457,7 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - Improved error handling and user feedback for directive processing.
 - Enhanced logging and output options for chat sessions.
 
-### [0.7.0] WIP - 2025-03-17
+## [0.7.0] WIP - 2025-03-17
 - Major code refactoring for better organization and maintainability:
   - Extracted `DirectiveProcessor` class to handle chat-based directives
   - Extracted `HistoryManager` class for conversation and variable history management
@@ -400,13 +468,13 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - Improved output handling to suppress STDOUT when chat mode is off and output file is specified
 - Updated spinner format in the process_prompt method for better user experience
 
-### [0.6.?] WIP
+## [0.6.?] WIP
 - Implemented Tony Stark's Clean Slate Protocol on the develop branch
 
-### [0.5.17] 2024-05-17
+## [0.5.17] 2024-05-17
 - removed replaced `semver` with `versionaire`
 
-### [0.5.16] 2024-04-02
+## [0.5.16] 2024-04-02
 - fixed prompt pipelines
 - added //next and //pipeline directives as shortcuts to //config [next,pipeline]
 - Added new backend "client" as an internal OpenAI client
@@ -415,83 +483,82 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - Added --voice default: alloy (if "siri" and Mac? then uses cli tool "say")
 - Added --image_size and --image_quality (--is --iq)
 
-
-### [0.5.15] 2024-03-30
+## [0.5.15] 2024-03-30
 - Added the ability to accept piped in text to be appeded to the end of the prompt text: curl $URL | aia ad_hoc
 - Fixed bugs with entering directives as follow-up prompts during a chat session
 
-### [0.5.14] 2024-03-09
+## [0.5.14] 2024-03-09
 - Directly access OpenAI to do text to speech when using the `--speak` option
 - Added --voice to specify which voice to use
 - Added --speech_model to specify which TTS model to use
 
-### [0.5.13] 2024-03-03
+## [0.5.13] 2024-03-03
 - Added CLI-utility `llm` as a backend processor
 
-### [0.5.12] 2024-02-24
+## [0.5.12] 2024-02-24
 - Happy Birthday Ruby!
 - Added --next CLI option
 - Added --pipeline CLI option
 
-### [0.5.11] 2024-02-18
+## [0.5.11] 2024-02-18
 - allow directives to return information that is inserted into the prompt text
 - added //shell command directive
 - added //ruby ruby_code directive
 - added //include path_to_file directive
 
-### [0.5.10] 2024-02-03
+## [0.5.10] 2024-02-03
 - Added --roles_dir to isolate roles from other prompts if desired
 - Changed --prompts to --prompts_dir to be consistent
 - Refactored common fzf usage into its own tool class
 
-### [0.5.9] 2024-02-01
+## [0.5.9] 2024-02-01
 - Added a "I'm working" spinner thing when "--verbose" is used as an indication that the backend is in the process of composing its response to the prompt.
 
-### [0.5.8] 2024-01-17
+## [0.5.8] 2024-01-17
 - Changed the behavior of the --dump option.  It must now be followed by path/to/file.ext where ext is a supported config file format: yml, yaml, toml
 
-### [0.5.7] 2024-01-15
+## [0.5.7] 2024-01-15
 - Added ERB processing to the config_file
 
-### [0.5.6] 2024-01-15
+## [0.5.6] 2024-01-15
 - Adding processing for directives, shell integration and erb to the follow up prompt in a chat session
 - some code refactoring.
 
 ## [0.5.3] 2024-01-14
 - adding ability to render markdown to the terminal using the "glow" CLI utility
 
-### [0.5.2] 2024-01-13
+## [0.5.2] 2024-01-13
 - wrap response when its going to the terminal
 
-### [0.5.1] 2024-01-12
+## [0.5.1] 2024-01-12
 - removed a wicked puts "loaded" statement
 - fixed missed code when the options were changed to --out_file and --log_file
 - fixed completion functions by updating $PROMPT_DIR to $AIA_PROMPTS_DIR to match the documentation.
 
-### [0.5.0] 2024-01-05
+## [0.5.0] 2024-01-05
 - breaking changes:
     - changed `--config` to `--config_file`
     - changed `--env` to `--shell`
     - changed `--output` to `--out_file`
         - changed default `out_file` to `STDOUT`
 
-### [0.4.3] 2023-12-31
+## [0.4.3] 2023-12-31
 - added --env to process embedded system environment variables and shell commands within a prompt.
 - added --erb to process Embedded RuBy within a prompt because have embedded shell commands will only get you in a trouble.  Having ERB will really get you into trouble.  Remember the simple prompt is usually the best prompt.
 
-### [0.4.2] 2023-12-31
+## [0.4.2] 2023-12-31
 - added the --role CLI option to pre-pend a "role" prompt to the front of a primary prompt.
 
-### [0.4.1] 2023-12-31
+## [0.4.1] 2023-12-31
 - added a chat mode
 - prompt directives now supported
 - version bumped to match the `prompt_manager` gem
 
-### [0.3.20] 2023-12-28
+## [0.3.20] 2023-12-28
 - added work around to issue with multiple context files going to the `mods` backend
 - added shellwords gem to santize prompt text on the command line
 
-### [0.3.19] 2023-12-26
+## [0.3.19] 2023-12-26
 - major code refactoring.
 - supports config files \*.yml, \*.yaml and \*.toml
 - usage implemented as a man page. --help will display the man page/
@@ -504,10 +571,10 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
     3. envar values             over-rides ...
     4. default values
 
-### [0.3.0] = 2023-11-23
+## [0.3.0] = 2023-11-23
 
 - Matching version to [prompt_manager](https://github.com/prompt_manager) This version allows for the user of history in the entery of values to prompt keywords.  KW_HISTORY_MAX is set at 5.  Changed CLI enteraction to use historical selection and editing of prior keyword values.
 
-### [0.1.0] - 2023-11-23
+## [0.1.0] - 2023-11-23
 
 - Initial release