aia 1.1.0 → 2.0.0.0.pre.alpha

data/docs/configuration.md

@@ -1,3 +1,43 @@
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+- [Configuration](#configuration)
+  - [Configuration Precedence](#configuration-precedence)
+  - [Configuration Files](#configuration-files)
+    - [Primary Configuration File](#primary-configuration-file)
+  - [Environment Variables](#environment-variables)
+  - [Command Line Arguments](#command-line-arguments)
+  - [Embedded Directives](#embedded-directives)
+  - [Logger Configuration](#logger-configuration)
+    - [Configuration File Settings](#configuration-file-settings)
+    - [CLI Log Level Override](#cli-log-level-override)
+    - [Environment Variables](#environment-variables-1)
+    - [Log Levels](#log-levels)
+    - [Example: File-Based Logging](#example-file-based-logging)
+  - [Advanced Configuration](#advanced-configuration)
+    - [Multi-Model Configuration](#multi-model-configuration)
+    - [Tool Configuration](#tool-configuration)
+    - [MCP Server Configuration](#mcp-server-configuration)
+    - [Prompt Directory Structure](#prompt-directory-structure)
+  - [Configuration Examples](#configuration-examples)
+    - [Development Setup](#development-setup)
+    - [Production Setup](#production-setup)
+    - [Creative Writing Setup](#creative-writing-setup)
+  - [Validation and Troubleshooting](#validation-and-troubleshooting)
+    - [Check Configuration](#check-configuration)
+    - [Validate Settings](#validate-settings)
+    - [Common Issues](#common-issues)
+      - [Model Not Found](#model-not-found)
+      - [Permission Errors](#permission-errors)
+      - [Tool Loading Errors](#tool-loading-errors)
+  - [Configuration Migration](#configuration-migration)
+    - [Updating from Older Versions](#updating-from-older-versions)
+  - [Best Practices](#best-practices)
+  - [Security Considerations](#security-considerations)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
 # Configuration
 
 AIA provides a flexible configuration system with multiple layers of precedence, allowing you to customize behavior at different levels.
@@ -27,10 +67,9 @@ service:
   name: aia
 
 # LLM Configuration
-# Access: AIA.config.llm.adapter, AIA.config.llm.temperature, etc.
-# Env: AIA_LLM__ADAPTER, AIA_LLM__TEMPERATURE, etc.
+# Access: AIA.config.llm.temperature, etc.
+# Env: AIA_LLM__TEMPERATURE, etc.
 llm:
-  adapter: ruby_llm           # AI adapter to use (currently only ruby_llm)
   temperature: 0.7            # Creativity/randomness (0.0-2.0)
   max_tokens: 2048            # Maximum response length
   top_p: 1.0                  # Nucleus sampling
@@ -54,7 +93,7 @@ prompts:
   roles_dir: ~/.prompts/roles # Full path to roles directory
   role: ~                     # Default role
   skills: []                  # Skill IDs to prepend to prompt (set by --skill/-s)
-  skills_prefix: skills       # Subdirectory name for skill directories
+  skills_prefix: ~            # Subdirectory appended to skills base path (nil = unset)
   system_prompt: ~            # Default system prompt
   parameter_regex: ~          # Regex for parameter extraction
 
@@ -81,16 +120,16 @@ output:
   file: temp.md               # Output file (null = no file output)
   append: false               # Append to output file instead of overwriting
   markdown: true              # Format output with Markdown
-  history_file: ~/.prompts/_prompts.log  # Conversation history log
+  history_file: ~/.prompts/_prompts.log  # Reline chat input history (chat mode only; up to 50 entries)
 
 # Audio Configuration
 # Access: AIA.config.audio.voice, AIA.config.audio.speak_command, etc.
 # Env: AIA_AUDIO__VOICE, AIA_AUDIO__SPEAK_COMMAND, etc.
 audio:
-  voice: alloy                # Voice for speech synthesis
-  speak_command: afplay       # Command to play audio files
-  speech_model: tts-1         # Model for text-to-speech
-  transcription_model: whisper-1  # Model for speech-to-text
+  voice: ~                    # Voice name (macOS say: e.g. Samantha; OpenAI: alloy/nova/echo/…)
+  speak_command: say          # TTS command; macOS default is `say`
+  speech_model: ~             # Passed as SPEECH_MODEL env var to the speak command (unset = not passed)
+  transcription_model: ~      # Default transcription model for RubyLLM (unset = RubyLLM default)
 
 # Image Configuration
 # Access: AIA.config.image.model, AIA.config.image.size, etc.
@@ -127,11 +166,11 @@ flags:
   tokens: false               # Show token usage
   no_mcp: false               # Disable MCP server processing
   speak: false                # Convert text to speech
-  terse: false                # Request shorter AI responses
   shell: true                 # Enable shell integration
   erb: true                   # Enable ERB processing
   clear: false                # Clear conversation history
   consensus: false            # Enable consensus mode for multi-model
+  thinking: false             # Show raw <think> reasoning blocks from local models
 
 # Logger Configuration
 # Access: AIA.config.logger.aia.file, AIA.config.logger.llm.level, etc.
@@ -183,6 +222,41 @@ paths:
 # Context Files (set at runtime)
 # Access: AIA.config.context_files (array of file paths)
 context_files: []
+
+# Concurrency Configuration
+# Access: AIA.config.concurrency.auto, .independent_servers, .threshold
+# Controls automatic MCP server parallelization.
+concurrency:
+  auto: false                 # Enable automatic MCP concurrency
+  independent_servers: []     # Servers safe to run in parallel
+  threshold: 2                # Minimum servers needed to trigger concurrency
+
+# Model Aliases (short name → full model ID)
+# Access: AIA.config.model_aliases
+# Example: { "gpt4": "gpt-4o", "sonnet": "claude-sonnet-4-20250514" }
+model_aliases: {}
+
+# MCP Server Filtering
+# Access: AIA.config.mcp_use, AIA.config.mcp_skip
+mcp_use: ~                    # Array of MCP server names to activate (nil = all)
+mcp_skip: ~                   # Array of MCP server names to skip
+
+# Tool Filter Flags
+# Access: AIA.config.flags.track_pipeline, AIA.config.flags.expert_routing
+# Env: AIA_FLAGS__TRACK_PIPELINE, AIA_FLAGS__EXPERT_ROUTING, etc.
+# (These belong under flags: but are shown here for reference)
+#
+# flags:
+#   track_pipeline: false     # Track which pipeline prompts are executed
+#   expert_routing: false     # Route chat turns to specialist robots
+#
+# Tool Filter Strategy Flags
+#   auto_tool_filter: true    # TF-IDF cosine similarity filter (on by default)
+#   tool_filter_b: false      # Zvec HNSW vector DB filter
+#   tool_filter_c: false      # SqliteVec filter
+#   tool_filter_d: false      # LSI (latent semantic indexing) filter
+#   tool_filter_load: false   # Load saved filter model from disk
+#   tool_filter_save: false   # Save filter model to disk after build
 ```
 
 ## Environment Variables
@@ -192,7 +266,6 @@ Use double underscore (`__`) for nested configuration sections:
 
 ```bash
 # LLM settings (nested under llm:)
-export AIA_LLM__ADAPTER="ruby_llm"
 export AIA_LLM__TEMPERATURE="0.8"
 export AIA_LLM__MAX_TOKENS="2048"
 export AIA_LLM__TOP_P="1.0"
@@ -209,7 +282,7 @@ export AIA_PROMPTS__EXTNAME=".md"
 export AIA_PROMPTS__ROLES_PREFIX="roles"
 export AIA_PROMPTS__ROLES_DIR="~/.prompts/roles"
 export AIA_PROMPTS__ROLE="expert"
-export AIA_PROMPTS__SKILLS_PREFIX="skills"
+# export AIA_PROMPTS__SKILLS_PREFIX="my-prefix"    # No default — unset means use skills.dir directly
 export AIA_PROMPTS__SYSTEM_PROMPT="my_system_prompt"
 export AIA_PROMPTS__PARAMETER_REGEX='\{\{(\w+)\}\}'
 
@@ -223,9 +296,9 @@ export AIA_OUTPUT__MARKDOWN="true"
 export AIA_OUTPUT__HISTORY_FILE="~/.prompts/_prompts.log"
 
 # Audio settings (nested under audio:)
-export AIA_AUDIO__VOICE="alloy"
-export AIA_AUDIO__SPEAK_COMMAND="afplay"
-export AIA_AUDIO__SPEECH_MODEL="tts-1"
+export AIA_AUDIO__VOICE="Samantha"       # macOS say voice (see: say -v '?')
+export AIA_AUDIO__SPEAK_COMMAND="say"    # default; swap for custom TTS script
+export AIA_AUDIO__SPEECH_MODEL="tts-1"  # passed as SPEECH_MODEL to speak_command
 export AIA_AUDIO__TRANSCRIPTION_MODEL="whisper-1"
 
 # Image settings (nested under image:)
@@ -251,11 +324,11 @@ export AIA_FLAGS__FUZZY="false"
 export AIA_FLAGS__TOKENS="true"
 export AIA_FLAGS__NO_MCP="false"
 export AIA_FLAGS__SPEAK="false"
-export AIA_FLAGS__TERSE="false"
 export AIA_FLAGS__SHELL="true"
 export AIA_FLAGS__ERB="true"
 export AIA_FLAGS__CLEAR="false"
 export AIA_FLAGS__CONSENSUS="false"
+export AIA_FLAGS__THINKING="false"
 
 # Logger settings (nested under logger:)
 export AIA_LOGGER__AIA__FILE="~/.config/aia/aia.log"
@@ -476,10 +549,51 @@ prompts:
   roles_prefix: roles       # ~/.prompts/roles/
   roles_dir: ~/.prompts/roles
   role: ~                   # Default role (null = none)
+  skills_prefix: ~          # Prefix appended to skills base (nil = unset, uses skills.dir directly)
+  skills: []                # Default skills (empty = none)
   system_prompt: ~          # Default system prompt
   parameter_regex: ~        # Custom parameter extraction regex
+
+# Top-level directory shortcuts (expand ~ automatically)
+roles:
+  dir: ~/.prompts/roles
+
+skills:
+  dir: ~/.prompts/skills
 ```
 
+**Prompt assembly order**:
+
+In **pipeline mode** (default), each prompt text is assembled as:
+1. **Role content** — identity and personality (`--role`)
+2. **Skill content** — capabilities and approach (`--skill`, in declaration order)
+3. **User prompt** — the actual request
+
+In **chat mode** (`--chat`), the system prompt is assembled once at startup:
+1. **System prompt** — guardrails and constraints (`--system-prompt`)
+2. **Role content** — identity and personality (`--role`)
+3. **Skill content** — injected here so it persists across all turns without repetition
+
+Follow-up chat turns carry role and skill context implicitly via conversation history.
+
+**Recommended directory layout**:
+```
+~/.prompts/
+├── roles/
+│   ├── ruby_expert.md          # "You are a senior Ruby developer..."
+│   └── teacher.md
+├── skills/
+│   ├── testing/
+│   │   └── SKILL.md            # Skill ID: "testing"
+│   ├── debugging/
+│   │   └── SKILL.md            # Skill ID: "debugging"
+│   └── refactoring/
+│       └── SKILL.md            # Skill ID: "refactoring"
+└── my_prompt.md
+```
+
+Each skill is a **subdirectory** containing a `SKILL.md` file. The skill ID is the subdirectory name. Subdirectories without `SKILL.md` and plain `.md` files are ignored by `--list-skills`.
+
 ## Configuration Examples
 
 ### Development Setup
@@ -487,7 +601,6 @@ prompts:
 ```yaml
 # ~/.config/aia/aia.yml - Development setup
 llm:
-  adapter: ruby_llm
   temperature: 0.3
 
 models:
@@ -513,7 +626,6 @@ flags:
 ```yaml
 # ~/.config/aia/aia.yml - Production setup
 llm:
-  adapter: ruby_llm
   temperature: 0.7
 
 models:
@@ -542,7 +654,6 @@ flags:
 ```yaml
 # ~/.config/aia/aia.yml - Creative writing
 llm:
-  adapter: ruby_llm
   temperature: 1.1
   max_tokens: 4000
 

data/docs/contributing.md

@@ -1,3 +1,56 @@
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+- [Contributing to AIA](#contributing-to-aia)
+  - [Ways to Contribute](#ways-to-contribute)
+    - [1. Report Issues](#1-report-issues)
+    - [2. Submit Code Changes](#2-submit-code-changes)
+    - [3. Improve Documentation](#3-improve-documentation)
+    - [4. Contribute Examples](#4-contribute-examples)
+  - [Getting Started](#getting-started)
+    - [Prerequisites](#prerequisites)
+    - [Setting Up Development Environment](#setting-up-development-environment)
+  - [Development Guidelines](#development-guidelines)
+    - [Code Standards](#code-standards)
+      - [Ruby Style Guide](#ruby-style-guide)
+      - [Testing Requirements](#testing-requirements)
+      - [Documentation Standards](#documentation-standards)
+    - [Commit Message Format](#commit-message-format)
+  - [Contributing Examples](#contributing-examples)
+    - [Prompt Examples](#prompt-examples)
+      - [File Structure](#file-structure)
+      - [Prompt Template Format](#prompt-template-format)
+    - [Tool Examples](#tool-examples)
+      - [File Structure](#file-structure-1)
+      - [Tool Template](#tool-template)
+    - [MCP Client Examples](#mcp-client-examples)
+      - [File Structure](#file-structure-2)
+  - [Pull Request Process](#pull-request-process)
+    - [Before Submitting](#before-submitting)
+    - [Submitting the Pull Request](#submitting-the-pull-request)
+    - [Review Process](#review-process)
+  - [Community Guidelines](#community-guidelines)
+    - [Communication](#communication)
+    - [Issue Reporting](#issue-reporting)
+    - [Feature Requests](#feature-requests)
+  - [Security](#security)
+    - [Reporting Security Issues](#reporting-security-issues)
+    - [Security Best Practices](#security-best-practices)
+  - [Recognition](#recognition)
+    - [Contributors](#contributors)
+    - [Types of Recognition](#types-of-recognition)
+  - [Getting Help](#getting-help)
+    - [Development Questions](#development-questions)
+    - [Code Review](#code-review)
+    - [Community Support](#community-support)
+  - [Release Process](#release-process)
+    - [Version Management](#version-management)
+    - [Release Schedule](#release-schedule)
+  - [Thank You!](#thank-you)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
 # Contributing to AIA
 
 We welcome contributions to AIA! This guide will help you get started with contributing to the project.
@@ -29,7 +82,7 @@ We welcome contributions to AIA! This guide will help you get started with contr
 ## Getting Started
 
 ### Prerequisites
-- Ruby 3.2+ installed
+- Ruby >= 4.0.0 installed
 - Git for version control
 - Familiarity with AI/LLM concepts
 - Understanding of command-line tools
@@ -192,7 +245,7 @@ docs/examples/mcp/
 1. **Test Your Changes**
    ```bash
    rake test
-   rake integration_test
+   rake integration
    ```
 
 2. **Check Code Quality**
@@ -200,6 +253,7 @@ docs/examples/mcp/
    rubocop
    reek
    ```
+   Note: `rubocop` and `reek` are not bundled dev dependencies. Install them manually if you wish to run these checks.
 
 3. **Update Documentation**
    - Add/update relevant documentation