aia 1.1.0 → 2.0.0.0.pre.alpha

data/docs/cli-reference.md

@@ -1,3 +1,90 @@
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+- [CLI Reference](#cli-reference)
+  - [Usage Patterns](#usage-patterns)
+  - [Mode Options](#mode-options)
+    - [`--chat`](#--chat)
+    - [`-f, --fuzzy`](#-f---fuzzy)
+    - [`--terse`](#--terse)
+    - [`--tokens`](#--tokens)
+    - [`--cost`](#--cost)
+    - [`--mcp FILE`](#--mcp-file)
+    - [`--no-mcp`](#--no-mcp)
+    - [`--mcp-list`](#--mcp-list)
+    - [`--mu`, `--mcp-use NAMES`](#--mu---mcp-use-names)
+    - [`--ms`, `--mcp-skip NAMES`](#--ms---mcp-skip-names)
+  - [Adapter Options](#adapter-options)
+    - [`--available-models [QUERY]`](#--available-models-query)
+  - [Model Options](#model-options)
+    - [`-m MODEL, --model MODEL`](#-m-model---model-model)
+    - [`--[no-]consensus`](#--no-consensus)
+    - [`-s, --skill SKILL_IDS`](#-s---skill-skill_ids)
+    - [`--list-skills`](#--list-skills)
+    - [`--skills-dir DIR`](#--skills-dir-dir)
+    - [`--skills-prefix PREFIX`](#--skills-prefix-prefix)
+    - [`--sm, --speech-model MODEL`](#--sm---speech-model-model)
+    - [`--tm, --transcription-model MODEL`](#--tm---transcription-model-model)
+  - [File Options](#file-options)
+    - [`-c, --config-file FILE`](#-c---config-file-file)
+    - [`-o, --[no-]output [FILE]`](#-o---no-output-file)
+    - [`-a, --[no-]append`](#-a---no-append)
+    - [`--[no-]history-file [FILE]`](#--no-history-file-file)
+    - [`--md, --[no-]markdown`](#--md---no-markdown)
+  - [Prompt Options](#prompt-options)
+    - [`--prompts-dir DIR`](#--prompts-dir-dir)
+    - [`--roles-prefix PREFIX`](#--roles-prefix-prefix)
+    - [`-r, --role ROLE_ID`](#-r---role-role_id)
+    - [`--list-roles`](#--list-roles)
+    - [`--skills-prefix PREFIX`](#--skills-prefix-prefix-1)
+    - [`-s, --skill SKILL_IDS`](#-s---skill-skill_ids-1)
+    - [`--list-skills`](#--list-skills-1)
+    - [`-n, --next PROMPT_ID`](#-n---next-prompt_id)
+    - [`-p PROMPTS, --pipeline PROMPTS`](#-p-prompts---pipeline-prompts)
+    - [`--system-prompt PROMPT_ID`](#--system-prompt-prompt_id)
+    - [`--regex PATTERN`](#--regex-pattern)
+  - [AI Parameters](#ai-parameters)
+    - [`-t, --temperature TEMP`](#-t---temperature-temp)
+    - [`--max-tokens TOKENS`](#--max-tokens-tokens)
+    - [`--top-p VALUE`](#--top-p-value)
+    - [`--frequency-penalty VALUE`](#--frequency-penalty-value)
+    - [`--presence-penalty VALUE`](#--presence-penalty-value)
+  - [Audio/Image Options](#audioimage-options)
+    - [`--speak`](#--speak)
+    - [`--voice VOICE`](#--voice-voice)
+    - [`--is, --image-size SIZE`](#--is---image-size-size)
+    - [`--iq, --image-quality QUALITY`](#--iq---image-quality-quality)
+    - [`--style, --image-style STYLE`](#--style---image-style-style)
+  - [Tool Options](#tool-options)
+    - [`--rq LIBS, --require LIBS`](#--rq-libs---require-libs)
+    - [`--tools PATH_LIST`](#--tools-path_list)
+    - [`--at, --allowed-tools TOOLS_LIST`](#--at---allowed-tools-tools_list)
+    - [`--rt, --rejected-tools TOOLS_LIST`](#--rt---rejected-tools-tools_list)
+    - [`--list-tools`](#--list-tools)
+  - [Utility Options](#utility-options)
+    - [Log Level Options](#log-level-options)
+    - [`-d, --debug`](#-d---debug)
+    - [`--no-debug`](#--no-debug)
+    - [`--log-level LEVEL`](#--log-level-level)
+    - [`--log-to FILE`](#--log-to-file)
+    - [`-v, --[no-]verbose`](#-v---no-verbose)
+    - [`--[no-]thinking`](#--no-thinking)
+    - [`--refresh DAYS`](#--refresh-days)
+    - [`--dump FILE`](#--dump-file)
+    - [`--completion SHELL`](#--completion-shell)
+    - [`--version`](#--version)
+    - [`-h, --help`](#-h---help)
+  - [Usage Examples](#usage-examples)
+    - [Basic Examples](#basic-examples)
+    - [Advanced Examples](#advanced-examples)
+    - [Configuration Examples](#configuration-examples)
+  - [Environment Variables](#environment-variables)
+  - [Configuration Precedence](#configuration-precedence)
+  - [Related Documentation](#related-documentation)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
 # CLI Reference
 
 Complete reference for all AIA command-line arguments, options, and flags.
@@ -41,7 +128,9 @@ aia -f
 **Note**: If `fzf` is not installed, AIA will exit with an error.
 
 ### `--terse`
-Adds a special instruction to the prompt asking the AI to keep responses short and to the point.
+**Deprecated.** Accepted for backward compatibility but has no effect.
+
+Formerly added a special instruction to the prompt asking the AI to keep responses short and to the point.
 
 ```bash
 aia --terse my_prompt
@@ -164,15 +253,6 @@ aia --ms playwright --ms filesystem --chat
 
 ## Adapter Options
 
-### `--adapter ADAPTER`
-Interface that adapts AIA to the LLM. Currently supported: `ruby_llm`
-
-```bash
-aia --adapter ruby_llm
-```
-
-**Valid adapters**: `ruby_llm`
-
 ### `--available-models [QUERY]`
 List (then exit) available models that match the optional query. Query is a comma-separated list of AND components.
 
@@ -239,8 +319,12 @@ aia --model "gpt-4,claude-3-sonnet" --no-consensus my_prompt
 ### `-s, --skill SKILL_IDS`
 Inject one or more skills into the prompt before it is sent to the AI. Skills are loaded from the skills directory (default: `~/.prompts/skills/`). Multiple skills can be specified as a comma-separated list, and the flag may be repeated.
 
-Skills are inserted **after the role and before the user prompt**, providing task-level instructions for how the LLM should approach the request:
+**Injection mode depends on `--chat`:**
+
+- **Chat mode** (`--chat`): skill content is appended to the system prompt once, so it persists across all turns without repetition.
+- **Pipeline mode** (default): skill content is appended to each individual prompt text, immediately after the role content.
 
+In both modes the assembled order is:
 ```
 Role content  (who the LLM is)
 Skill content (how to approach the task)
@@ -314,14 +398,26 @@ aia --skills-dir /shared/team-skills -s code-review my_prompt
 **Environment variable**: `AIA_SKILLS__DIR`
 
 ### `--skills-prefix PREFIX`
-Subdirectory name within `--prompts-dir` used as the skills prefix (default: `skills`). Affects `AIA.config.prompts.skills_prefix`.
+Subdirectory name appended to the skills base to build the full skills path (default: none — unset). Affects `AIA.config.prompts.skills_prefix`.
+
+Path resolution when prefix is set:
+- If `--skills-dir` is also given: `skills-dir/prefix`
+- Otherwise: `prompts-dir/prefix` (using `--prompts-dir` or `AIA_PROMPTS__DIR`)
 
 ```bash
 aia --skills-prefix team-skills --list-skills
+# Looks for skills under ~/.prompts/team-skills/
+
+aia --skills-dir /shared --skills-prefix team-skills --list-skills
+# Looks for skills under /shared/team-skills/
 ```
 
+**Environment variable**: `AIA_PROMPTS__SKILLS_PREFIX`
+
 ### `--sm, --speech-model MODEL`
-Speech model to use for text-to-speech functionality.
+Set the `SPEECH_MODEL` environment variable that AIA passes to the
+`speak_command`. AIA does not call any TTS API — this value is only meaningful
+if your `speak_command` script reads `$SPEECH_MODEL`.
 
 ```bash
 aia --speech-model tts-1 --speak my_prompt
@@ -375,19 +471,30 @@ aia --output log.md --no-append my_prompt
 ```
 
 ### `--[no-]history-file [FILE]`
-Conversation history file for logging prompts and responses.
+Path to the Reline readline history file used in `--chat` mode. Each chat session saves the raw follow-up inputs you typed so they can be recalled with the up-arrow key in future sessions. Up to 50 entries are kept; oldest entries are dropped first when the limit is reached. Has no effect in pipeline mode.
+
+**File content**: plain text, one user input per line — no timestamps, no AI responses, no prompt IDs.
+
+**Path resolution** (first match wins):
+1. `FILE` supplied to this flag (or `AIA_OUTPUT__HISTORY_FILE` env var)
+2. `<aia_dir>/chat_history` when `paths.aia_dir` is configured
+3. `~/.config/aia/chat_history` (built-in default)
+
+**Large-file rotation**: when the history file exceeds an internal size threshold, the session renames it to `<file>.1` and starts a fresh file.
 
 ```bash
-# Enable history logging to default location
-aia --history-file my_prompt
+# Use the default history file location
+aia --chat my_prompt
 
-# Log to specific file
-aia --history-file /var/log/aia_history.log my_prompt
+# Use a custom history file
+aia --history-file ~/.aia_chat_history --chat my_prompt
 
-# Disable history logging
-aia --no-history-file my_prompt
+# Disable history entirely for this session
+aia --no-history-file --chat my_prompt
 ```
 
+**Environment variable**: `AIA_OUTPUT__HISTORY_FILE`
+
 ### `--md, --[no-]markdown`
 Format output with Markdown.
 
@@ -472,6 +579,88 @@ Roles are discovered from:
 
 **See also**: `--role`, `--model`, `--prompts-dir`, `--roles-prefix`
 
+### `--skills-prefix PREFIX`
+Subdirectory name appended to the base path to form the skills directory (default: none — unset).
+
+When unset and no `--skills-dir` is given, skills are resolved from `~/.prompts/skills/`.
+
+```bash
+# Use custom prefix under prompts-dir
+aia --skills-prefix capabilities --skill expert
+# Looks for ~/.prompts/capabilities/expert/SKILL.md
+
+# Use prefix under an explicit skills-dir
+aia --skills-dir /shared --skills-prefix team --skill expert
+# Looks for /shared/team/expert/SKILL.md
+```
+
+### `-s, --skill SKILL_IDS`
+One or more skill IDs to layer into the prompt after the role. Skills define *what the LLM does* in order to respond — they sit between the role (identity) and the user prompt in the assembled system prompt.
+
+Each skill ID is the name of a subdirectory under `skills.dir` that contains a `SKILL.md` file (e.g., skill `testing` → `~/.prompts/skills/testing/SKILL.md`).
+
+Accepts comma-separated values, multiple flags, or a combination of both:
+
+```bash
+# Single skill
+aia --skill testing my_prompt
+aia -s testing my_prompt
+
+# Comma-separated
+aia --skill testing,debugging my_prompt
+
+# Repeatable flag
+aia --skill testing --skill debugging my_prompt
+
+# Combined
+aia --skill testing,debugging --skill refactoring my_prompt
+
+# With a role (system → role → skills → user)
+aia --role ruby_expert --skill testing --skill minitest my_prompt
+```
+
+**Prompt assembly order** (first turn only):
+1. System prompt (guardrails)
+2. Role prompt (identity/personality)
+3. Skill prompt(s) (capabilities, in declaration order)
+4. User prompt
+
+Follow-up turns in chat mode include only the system prompt and the user message; role and skills are carried implicitly via conversation history.
+
+**See also**: `--role`, `--list-skills`, `--skills-prefix`
+
+### `--list-skills`
+List all available skills and exit. A skill is a subdirectory of the skills directory that contains a `SKILL.md` file. Output is a formatted markdown document.
+
+```bash
+# List all available skills
+aia --list-skills
+
+# Example output:
+#
+# ## debugging
+#
+# | Key | Value |
+# |-----|-------|
+# | name | debugging |
+# | description | Debug Ruby applications. |
+#
+# ## minitest
+#
+# | Key | Value |
+# |-----|-------|
+# | name | minitest |
+# | description | Write tests using Minitest. |
+```
+
+Skills are discovered from:
+- **Default location**: `~/.prompts/skills/`
+- **Custom location**: Set via `--prompts-dir` and `--skills-prefix`
+- **Convention**: Each skill is a subdirectory containing a `SKILL.md` file; plain `.md` files and subdirectories without `SKILL.md` are ignored
+- **Output**: H2 heading per skill ID, followed by a two-column table of YAML front matter key/value pairs
+
+**See also**: `--skill`, `--skills-prefix`
+
 ### `-n, --next PROMPT_ID`
 Next prompt to process (can be used multiple times to build a pipeline).
 
@@ -498,7 +687,7 @@ aia --system-prompt code_expert --chat my_code.py
 ```
 
 ### `--regex PATTERN`
-Regex pattern to extract parameters from prompt text.
+**Deprecated.** No longer used; prompt parameters use ERB syntax.
 
 ```bash
 aia --regex '\{\{(\w+)\}\}' my_template_prompt
@@ -565,23 +754,77 @@ aia --presence-penalty -0.5 deep_dive
 ## Audio/Image Options
 
 ### `--speak`
-Convert text to audio and play it. Uses the configured speech model and voice.
+After each AI response, AIA runs a three-stage pipeline with a progress spinner
+for each stage:
+
+| Stage | What happens | Spinner |
+|-------|-------------|---------|
+| 1. Generation | LLM streams text to the terminal | `Processing...` |
+| 2. Conversion | Text is converted to an audio file | `Converting to audio...` |
+| 3. Playback | Audio file is played | `Speaking...` |
+
+**Local TTS (default):** `say` converts and plays in one step, so stages 2 and 3
+share a single `Speaking...` spinner.
 
 ```bash
-aia --speak my_prompt
-aia --speak --voice nova my_prompt
+aia --chat --speak my_prompt
+aia --speak --voice Samantha my_prompt
+```
+
+**Custom TTS script (e.g. OpenAI TTS):** AIA calls the script with two
+arguments — the text (`$1`) and the path to write the audio file (`$2`) — then
+plays the resulting file with `afplay`. The script is responsible **only** for
+conversion; AIA handles playback and shows both spinners.
+
+AIA does **not** call any TTS API itself. A ready-made script for OpenAI TTS is
+installed at `~/.config/aia/tts.sh`:
+
+```bash
+# ~/.config/aia/tts.sh — called as: tts.sh "text" /path/to/output.mp3
+#!/usr/bin/env bash
+model="${SPEECH_MODEL:-tts-1}"
+voice="${AIA_AUDIO__VOICE:-alloy}"
+curl -s https://api.openai.com/v1/audio/speech \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"model\": \"$model\", \"input\": $(printf '%s' "$1" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'), \"voice\": \"$voice\"}" \
+  --output "$2"
+```
+
+```yaml
+# ~/.config/aia/aia.yml
+audio:
+  speak_command: ~/.config/aia/tts.sh
+  speech_model: tts-1-hd
+  voice: nova
+```
+
+Or entirely from the CLI:
+
+```bash
+aia --chat --speak \
+    --speak-command ~/.config/aia/tts.sh \
+    --speech-model tts-1-hd \
+    --voice nova \
+    my_prompt
 ```
 
 ### `--voice VOICE`
-Voice to use for speech synthesis.
+Voice name passed to the `speak_command`.
+
+For macOS `say` (default), specify a macOS voice name (run `say -v '?'` to list
+available voices):
+
+```bash
+aia --voice Samantha --speak my_prompt
+aia --voice Alex --speak my_prompt
+```
+
+For a custom OpenAI TTS script, use an OpenAI voice name instead:
 
 ```bash
 aia --voice alloy --speak my_prompt
-aia --voice echo --speak my_prompt
-aia --voice fable --speak my_prompt
-aia --voice nova --speak my_prompt  
-aia --voice onyx --speak my_prompt
-aia --voice shimmer --speak my_prompt
+aia --voice nova --speak my_prompt
 ```
 
 ### `--is, --image-size SIZE`
@@ -760,38 +1003,28 @@ Explicitly disable debug output. Sets `$DEBUG_ME = false`.
 aia --no-debug my_prompt
 ```
 
-### `--info`
-Set all loggers to INFO level. Shows informational messages and above.
-
-```bash
-aia --info my_prompt
-aia --info --chat
-```
-
-### `--warn`
-Set all loggers to WARN level (this is the default). Shows warnings, errors, and fatal messages.
-
-```bash
-aia --warn my_prompt
-```
+### `--log-level LEVEL`
+Set all loggers to the specified level. Only `--debug` / `--no-debug` exist as standalone flags; all other levels are set via this option.
 
-### `--error`
-Set all loggers to ERROR level. Shows only errors and fatal messages.
+Valid values for LEVEL: `debug`, `info`, `warn`, `error`, `fatal`
 
 ```bash
-aia --error my_prompt
-aia --error --chat
+aia --log-level info my_prompt
+aia --log-level warn --chat
+aia --log-level error my_prompt
+aia --log-level fatal my_prompt
 ```
 
-### `--fatal`
-Set all loggers to FATAL level (least verbose). Shows only critical/fatal messages.
+### `--log-to FILE`
+Redirect all logger output to FILE instead of STDOUT.
 
 ```bash
-aia --fatal my_prompt
+aia --log-to /var/log/aia.log my_prompt
+aia --log-to ~/aia_debug.log --debug --chat
 ```
 
 **Log Level Hierarchy** (from most to least verbose):
-1. `debug` - All messages including detailed debugging information
+1. `debug` - All messages including detailed debugging information (use `--debug` / `--no-debug`)
 2. `info` - Informational messages and above
 3. `warn` - Warnings, errors, and fatal messages (default)
 4. `error` - Only errors and fatal messages
@@ -809,6 +1042,24 @@ aia -v my_prompt
 aia --no-verbose my_prompt
 ```
 
+### `--[no-]thinking`
+Show or hide raw thinking/reasoning blocks in the output. Default: **off**.
+
+Some local reasoning models (e.g. `qwen3` on Ollama) emit their chain-of-thought
+wrapped in `<think>...</think>` tags as part of the streamed response. By default
+AIA filters these blocks out so you only see the final answer. Pass `--thinking`
+to display the reasoning as well.
+
+```bash
+# Show the model's reasoning
+aia --chat --thinking -m ollama/qwen3:latest
+
+# Explicitly hide it (the default)
+aia --chat --no-thinking -m ollama/qwen3:latest
+```
+
+Equivalent config key: `flags.thinking` (env: `AIA_FLAGS__THINKING`).
+
 ### `--refresh DAYS`
 Refresh models database interval in days.
 
@@ -908,8 +1159,11 @@ aia --config-file ./project_config.yml --prompts-dir ./project_prompts/ my_promp
 # Save output with markdown formatting
 aia --output analysis.md --markdown --append data_analysis dataset.csv
 
-# Audio processing
-aia --transcription-model whisper-1 --speech-model tts-1-hd --voice echo audio_prompt audio_file.wav
+# Speak responses aloud (macOS say, default voice)
+aia --speak my_prompt
+
+# Speak with a specific macOS voice
+aia --speak --voice Samantha my_prompt
 ```
 
 ## Environment Variables
@@ -931,6 +1185,7 @@ export AIA_LLM__MAX_TOKENS="2048"
 # Prompts settings (nested under prompts:)
 export AIA_PROMPTS__DIR="/custom/prompts"
 export AIA_PROMPTS__ROLES_PREFIX="roles"
+export AIA_PROMPTS__SKILLS_PREFIX="skills"
 
 # Output settings (nested under output:)
 export AIA_OUTPUT__FILE="./output.md"
@@ -938,8 +1193,9 @@ export AIA_OUTPUT__APPEND="true"
 export AIA_OUTPUT__HISTORY_FILE="~/.prompts/_prompts.log"
 
 # Audio settings (nested under audio:)
-export AIA_AUDIO__VOICE="alloy"
-export AIA_AUDIO__SPEECH_MODEL="tts-1"
+export AIA_AUDIO__VOICE="Samantha"         # macOS voice (say -v '?'); or OpenAI voice for custom scripts
+export AIA_AUDIO__SPEAK_COMMAND="say"      # default; replace with a custom TTS script for OpenAI TTS
+export AIA_AUDIO__SPEECH_MODEL="tts-1"    # passed as SPEECH_MODEL to the speak_command script
 
 # Image settings (nested under image:)
 export AIA_IMAGE__SIZE="1024x1024"