aia 1.1.1 → 2.0.0.0.pre.alpha

data/docs/faq.md

@@ -1,3 +1,79 @@
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+- [Frequently Asked Questions](#frequently-asked-questions)
+  - [Installation and Setup](#installation-and-setup)
+    - [Q: What Ruby version is required for AIA?](#q-what-ruby-version-is-required-for-aia)
+    - [Q: How do I install AIA?](#q-how-do-i-install-aia)
+    - [Q: Where should I store my API keys?](#q-where-should-i-store-my-api-keys)
+    - [Q: Can I use AIA without internet access?](#q-can-i-use-aia-without-internet-access)
+    - [Q: How do I list available local models?](#q-how-do-i-list-available-local-models)
+    - [Q: What's the difference between Ollama and LM Studio?](#q-whats-the-difference-between-ollama-and-lm-studio)
+    - [Q: Can I mix local and cloud models?](#q-can-i-mix-local-and-cloud-models)
+    - [Q: Why does my lms/ model show an error?](#q-why-does-my-lms-model-show-an-error)
+  - [Basic Usage](#basic-usage)
+    - [Q: How do I create my first prompt?](#q-how-do-i-create-my-first-prompt)
+    - [Q: What's the difference between batch mode and chat mode?](#q-whats-the-difference-between-batch-mode-and-chat-mode)
+    - [Q: How do I use fuzzy search for prompts?](#q-how-do-i-use-fuzzy-search-for-prompts)
+  - [Configuration](#configuration)
+    - [Q: Where is the configuration file located?](#q-where-is-the-configuration-file-located)
+    - [Q: How do I change the default AI model?](#q-how-do-i-change-the-default-ai-model)
+    - [Q: How do I set a custom prompts directory?](#q-how-do-i-set-a-custom-prompts-directory)
+  - [Prompts and Directives](#prompts-and-directives)
+    - [Q: What are directives and how do I use them?](#q-what-are-directives-and-how-do-i-use-them)
+    - [Q: How do I include files in prompts?](#q-how-do-i-include-files-in-prompts)
+    - [Q: Can I use Ruby code in prompts?](#q-can-i-use-ruby-code-in-prompts)
+    - [Q: How do I create prompt workflows?](#q-how-do-i-create-prompt-workflows)
+  - [Models and Performance](#models-and-performance)
+    - [Q: Which AI model should I use?](#q-which-ai-model-should-i-use)
+    - [Q: How do I use multiple models simultaneously?](#q-how-do-i-use-multiple-models-simultaneously)
+    - [Q: How do I reduce token usage and costs?](#q-how-do-i-reduce-token-usage-and-costs)
+    - [Q: What's consensus mode?](#q-whats-consensus-mode)
+  - [Tools and Integration](#tools-and-integration)
+    - [Q: What are RubyLLM tools?](#q-what-are-rubyllm-tools)
+    - [Q: How do I use tools with AIA?](#q-how-do-i-use-tools-with-aia)
+    - [Q: What's the difference between tools and MCP clients?](#q-whats-the-difference-between-tools-and-mcp-clients)
+    - [Q: How do I create custom tools?](#q-how-do-i-create-custom-tools)
+  - [Chat Mode](#chat-mode)
+    - [Q: How do I start a chat session?](#q-how-do-i-start-a-chat-session)
+    - [Q: How do I save chat conversations?](#q-how-do-i-save-chat-conversations)
+    - [Q: Can I use tools in chat mode?](#q-can-i-use-tools-in-chat-mode)
+    - [Q: How do I send a message to just one robot in a multi-model session?](#q-how-do-i-send-a-message-to-just-one-robot-in-a-multi-model-session)
+    - [Q: Can I save my place in a conversation and return to it later?](#q-can-i-save-my-place-in-a-conversation-and-return-to-it-later)
+    - [Q: How do I clear chat history?](#q-how-do-i-clear-chat-history)
+  - [Troubleshooting](#troubleshooting)
+    - [Q: "Command not found: aia"](#q-command-not-found-aia)
+    - [Q: "No models available" error](#q-no-models-available-error)
+    - [Q: "Permission denied" errors](#q-permission-denied-errors)
+    - [Q: Prompts are slow or timing out](#q-prompts-are-slow-or-timing-out)
+    - [Q: "Tool not found" errors](#q-tool-not-found-errors)
+  - [Advanced Usage](#advanced-usage)
+    - [Q: How do I use AIA for code review?](#q-how-do-i-use-aia-for-code-review)
+    - [Q: Can I use AIA for data analysis?](#q-can-i-use-aia-for-data-analysis)
+    - [Q: How do I integrate AIA into my development workflow?](#q-how-do-i-integrate-aia-into-my-development-workflow)
+    - [Q: How do I backup my prompts?](#q-how-do-i-backup-my-prompts)
+  - [Getting Help](#getting-help)
+    - [Q: Where can I find more examples?](#q-where-can-i-find-more-examples)
+    - [Q: How do I report bugs or request features?](#q-how-do-i-report-bugs-or-request-features)
+    - [Q: Is there a community or forum?](#q-is-there-a-community-or-forum)
+    - [Q: Where can I find the latest documentation?](#q-where-can-i-find-the-latest-documentation)
+  - [Tips and Best Practices](#tips-and-best-practices)
+    - [Q: What are some general best practices for prompts?](#q-what-are-some-general-best-practices-for-prompts)
+    - [Q: How do I optimize for performance?](#q-how-do-i-optimize-for-performance)
+    - [Q: Security considerations?](#q-security-considerations)
+  - [Troubleshooting](#troubleshooting-1)
+    - [Q: "Prompt not found" error](#q-prompt-not-found-error)
+    - [Q: Model errors or "Model not available"](#q-model-errors-or-model-not-available)
+    - [Q: Shell integration not working](#q-shell-integration-not-working)
+    - [Q: Configuration issues](#q-configuration-issues)
+    - [Q: Performance issues with slow responses](#q-performance-issues-with-slow-responses)
+    - [Q: Large prompt processing issues](#q-large-prompt-processing-issues)
+    - [Q: Debug mode - how to get more information?](#q-debug-mode---how-to-get-more-information)
+    - [Q: Common error messages and solutions](#q-common-error-messages-and-solutions)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
 # Frequently Asked Questions
 
 Common questions and answers about using AIA.
@@ -202,7 +278,7 @@ See the [Directives Reference](directives-reference.md) for all available direct
 
 ### Q: Which AI model should I use?
 **A:** It depends on your needs:
-- **GPT-3.5 Turbo**: Fast, cost-effective for simple tasks
+- **GPT-4o Mini**: Fast, cost-effective for simple tasks
 - **GPT-4**: Best quality for complex reasoning
 - **Claude-3 Sonnet**: Great for long documents and analysis
 - **Claude-3 Haiku**: Fast and economical
@@ -216,7 +292,7 @@ aia --model "gpt-4,claude-3-sonnet" my_prompt
 ### Q: How do I reduce token usage and costs?
 **A:**
 - Use shorter prompts when possible
-- Choose appropriate models (GPT-3.5 for simple tasks)
+- Choose appropriate models (`gpt-4o-mini` for simple tasks)
 - Use temperature settings wisely
 - Clear chat context regularly with `/clear`
 
@@ -277,6 +353,12 @@ aia --chat --output conversation.md
 aia --chat --tools ./tools/
 ```
 
+### Q: How do I send a message to just one robot in a multi-model session?
+**A:** Use @mention syntax: prefix the robot's name with `@` (e.g., `@tobor explain this`). Use `/robots` to see the active robots and their names. Only the mentioned robot responds; others stay silent.
+
+### Q: Can I save my place in a conversation and return to it later?
+**A:** Yes, use `/checkpoint name` to create a named checkpoint and `/restore name` to return to it. Use `/checkpoints` to list all checkpoints. `/clear` removes all history and checkpoints.
+
 ### Q: How do I clear chat history?
 **A:** Use the `/clear` command or `/clear` directive:
 ```
@@ -305,7 +387,7 @@ You: /clear
 
 ### Q: Prompts are slow or timing out
 **A:**
-1. Try a faster model like `gpt-3.5-turbo`
+1. Try a faster model like `gpt-4o-mini`
 2. Reduce prompt length or complexity
 3. Check your internet connection
 4. Use `--debug` to see what's happening

data/docs/guides/available-models.md

@@ -1,6 +1,6 @@
 # Available Models
 
-AIA supports a wide range of AI models through the RubyLLM gem. This comprehensive list shows all supported models, their capabilities, and best use cases.
+AIA supports a wide range of AI models via robot_lab orchestration and ruby_llm LLM abstraction. This comprehensive list shows all supported models, their capabilities, and best use cases.
 
 ## Viewing Available Models
 

data/docs/guides/basic-usage.md

@@ -311,7 +311,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 3.1
+          ruby-version: 4.0.0
       - name: Install AIA
         run: gem install aia
       - name: Run Analysis
@@ -381,16 +381,16 @@ The `run` prompt is a configuration-only prompt that serves as a foundation for
 **Usage Examples:**
 ```bash
 # Direct question via pipe
-echo "What is the meaning of life?" | aia run
+echo "What is the meaning of life?" | aia
 
 # File analysis
-aia run my_code.py
+aia my_code.py
 
 # Multiple files
-aia run *.txt
+aia *.txt
 
 # With custom configuration
-echo "Explain quantum computing" | aia run --model gpt-4 --temperature 1.0
+echo "Explain quantum computing" | aia --model gpt-4 --temperature 1.0
 ```
 
 ### The Ad Hoc One-Shot Prompt
@@ -425,7 +425,7 @@ export AIA_FLAGS__VERBOSE=true  # Shows spinner while waiting for LLM response
 alias chat='aia --chat --terse'
 
 # Quick question function
-ask() { echo "$1" | aia run --no-output; }
+ask() { echo "$1" | aia --no-output; }
 ```
 
 **Usage Examples:**

data/docs/guides/chat.md

@@ -42,6 +42,7 @@ Once in chat mode, you can use these commands:
 - **`/temperature 0.8`**: Adjust creativity level
 - **`/tools`**: List available tools
 - **`/context`**: Show current context
+- **`/robots`**: List active robots and their `@mention` handles
 
 ### Special Features
 
@@ -78,6 +79,9 @@ which files are over 1 week old?
 
 ### Multi-Model Conversations
 
+#### @mention Routing
+In a multi-model network, direct your message to a specific robot by prefixing its name with `@` (e.g., `@tobor What do you think?`). Use `/robots` to see active robot names and their `@mention` handles.
+
 #### Consensus Mode
 ```bash
 # Start chat with multiple models seeking consensus
@@ -273,15 +277,43 @@ AI: Absolutely! Let's use a simple example everyone can relate to...
 ## Voice and Audio Features
 
 ### Text-to-Speech
+
+`--speak` runs a three-stage pipeline after each AI response:
+
+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):** the macOS `say` command handles both conversion and
+playback in one step, so it shows a single `Speaking...` spinner.
+
 ```bash
-# Enable speech output
+# Enable speech (uses macOS say, system default voice)
 aia --chat --speak
 
-# Choose specific voice
-aia --chat --speak --voice nova
+# Choose a specific macOS voice (run `say -v '?'` to list available voices)
+aia --chat --speak --voice Samantha
+aia --chat --speak --voice Alex
+```
+
+**OpenAI TTS:** point `speak_command` at `~/.config/aia/tts.sh` (installed with
+AIA). The script converts text to an audio file; AIA plays it with `afplay` and
+shows separate spinners for each stage.
+
+```bash
+aia --chat --speak \
+    --speak-command ~/.config/aia/tts.sh \
+    --speech-model tts-1-hd \
+    --voice nova \
+    my_prompt
+```
 
-# Use high-quality speech model
-aia --chat --speak --speech-model tts-1-hd
+```yaml
+# ~/.config/aia/aia.yml
+audio:
+  speak_command: ~/.config/aia/tts.sh
+  speech_model: tts-1-hd        # passed as SPEECH_MODEL env var to the script
+  voice: nova                   # passed as AIA_AUDIO__VOICE env var
 ```
 
 ### Audio Input
@@ -290,14 +322,6 @@ aia --chat --speak --speech-model tts-1-hd
 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
-
-# Great for hands-free operation or accessibility
-```
-
 ## Session Management
 
 ### Saving Conversations
@@ -476,10 +500,10 @@ llm:
   temperature: 0.7
   max_tokens: 2048
 
-# Audio for /say directive
+# Audio for --speak and /say directive
 audio:
-  voice: alloy
-  speak_command: afplay
+  voice: ~                  # macOS system default; set e.g. "Samantha" to pick a voice
+  speak_command: say        # macOS local TTS; use ~/.config/aia/tts.sh for OpenAI TTS
 ```
 
 Start chat with specific options via CLI:

data/docs/guides/crew.md

@@ -0,0 +1,239 @@
+# Crews
+
+Every AIA chat session is a **crew** — a small team of robots that share the
+conversation. Even when you start with a single model, that model is the crew's
+**chief**, and you can add more members on the fly, address them individually or
+together, and have them build on each other's answers.
+
+This guide covers how the crew works, how to address members, and how to grow or
+shrink the crew while you chat.
+
+## What a crew is
+
+A crew is a network of robots backing one chat session:
+
+- The **chief** is the lead robot — the first (or only) model you started with.
+  It answers plain turns and is the model your `/model`, consensus, and
+  history-transfer behavior revolve around.
+- **Members** (also called recruits) are additional robots you add during the
+  session. Each has a name, a provider/model, and its own system prompt, and is
+  reachable by `@name`.
+
+A single-model session is simply a crew of one. Multi-model sessions
+(`-m model1,model2,...`) start as a crew with one member per model.
+
+<svg width="640" height="280" viewBox="0 0 640 280" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Crew topology: a chief robot with recruited members addressed by @mention">
+  <style>
+    .lbl { font: 13px -apple-system, Segoe UI, sans-serif; fill: #e6e6e6; }
+    .sub { font: 11px -apple-system, Segoe UI, sans-serif; fill: #9aa4b2; }
+    .chief { fill: #1f6feb; }
+    .member { fill: #2ea043; }
+    .you { fill: #8957e5; }
+    .edge { stroke: #6e7681; stroke-width: 1.5; fill: none; }
+    .edge-bc { stroke: #d29922; stroke-width: 1.5; stroke-dasharray: 5 4; fill: none; }
+  </style>
+  <!-- You -->
+  <rect class="you" x="20" y="120" rx="8" width="110" height="44"/>
+  <text class="lbl" x="75" y="140" text-anchor="middle">You</text>
+  <text class="sub" x="75" y="156" text-anchor="middle">the prompt</text>
+  <!-- Chief -->
+  <rect class="chief" x="250" y="120" rx="8" width="130" height="44"/>
+  <text class="lbl" x="315" y="140" text-anchor="middle">chief</text>
+  <text class="sub" x="315" y="156" text-anchor="middle">lead robot</text>
+  <!-- Members -->
+  <rect class="member" x="490" y="30"  rx="8" width="130" height="44"/>
+  <text class="lbl" x="555" y="50"  text-anchor="middle">@researcher</text>
+  <text class="sub" x="555" y="66"  text-anchor="middle">gpt-4o</text>
+  <rect class="member" x="490" y="120" rx="8" width="130" height="44"/>
+  <text class="lbl" x="555" y="140" text-anchor="middle">@critic</text>
+  <text class="sub" x="555" y="156" text-anchor="middle">claude</text>
+  <rect class="member" x="490" y="210" rx="8" width="130" height="44"/>
+  <text class="lbl" x="555" y="230" text-anchor="middle">@local</text>
+  <text class="sub" x="555" y="246" text-anchor="middle">ollama/qwen</text>
+  <!-- edges -->
+  <path class="edge" d="M130 142 H250"/>
+  <path class="edge" d="M380 142 C 430 142, 440 52, 490 52"/>
+  <path class="edge" d="M380 142 H490"/>
+  <path class="edge" d="M380 142 C 430 142, 440 232, 490 232"/>
+  <text class="sub" x="190" y="135" text-anchor="middle">plain turn</text>
+  <text class="sub" x="435" y="120" text-anchor="middle">@name / @crew</text>
+</svg>
+
+## Seeing the crew
+
+Use `/robots` to list the active crew, each member's model, and its `@mention`
+handle:
+
+```text
+/robots
+```
+
+By default a robot's name is derived from its model name; recruited robots use
+the name you give them.
+
+## Addressing members with @mention
+
+Prefix a name with `@` to direct a prompt at one member instead of the chief:
+
+```text
+> @critic Does this API design have any obvious flaws?
+```
+
+Only the addressed robot responds; the `@critic` prefix is stripped before the
+prompt reaches it. Unknown names are reported (with the list of available
+members) rather than silently broadcast.
+
+### Addressing several members at once
+
+You can mention more than one member. **Where** the mentions appear changes how
+they run:
+
+- **Leading address → concurrent.** When the prompt is nothing but `@names`
+  followed by the message, every addressee runs at the same time, each in its
+  own thread, and replies render as they finish:
+
+  ```text
+  > @researcher @critic what are the trade-offs of optimistic locking?
+  ```
+
+- **Body mention → sequential pipeline.** When a `@name` is woven into the body
+  of the message, the mentioned members run one at a time, and each reply is
+  injected into the other members' conversations so later members build on what
+  earlier ones said:
+
+  ```text
+  > draft a plan @researcher then have @critic poke holes in it
+  ```
+
+  Here `@researcher` runs first; its answer is shared into `@critic`'s context
+  before `@critic` runs, so the critique responds to the actual draft.
+
+### Broadcasting to the whole crew
+
+`@crew` is a reserved handle that broadcasts the message to **every** member,
+concurrently:
+
+```text
+> @crew in one sentence, what is your specialty?
+```
+
+Because `crew` is reserved for broadcast, you cannot name a member `crew`.
+
+> **Local models and concurrency.** A leading-address or `@crew` broadcast runs
+> its members **concurrently** — several HTTP requests at once. When every member
+> shares one local model server (e.g. all on `ollama/qwen3.6:latest`), those
+> requests compete for the same instance: the server processes only
+> `OLLAMA_NUM_PARALLEL` at a time and the rest queue, so a big task can blow past
+> the per-request timeout and you'll see `Net::ReadTimeout` for several members.
+> If you hit this, raise Ollama's parallelism (`OLLAMA_NUM_PARALLEL=4`,
+> `OLLAMA_MAX_LOADED_MODELS=1`), give each member a smaller scoped task (see
+> [skills](#giving-a-recruit-a-role-with-skills)), or address members one at a
+> time (a body mention runs them sequentially) instead of broadcasting.
+
+## Building a crew at runtime
+
+### Recruiting a member
+
+`/add_recruit` (alias `/add`) adds a persistent member to the crew. It stays for
+the rest of the session and is reachable by `@name`.
+
+```text
+# Inherit the chief's model; give it a default persona
+/add_recruit researcher
+
+# Pick an explicit provider/model and write its system prompt
+/add_recruit critic anthropic/claude-3-5-sonnet You are a ruthless design critic. Find flaws.
+
+# A local model member
+/add_recruit local ollama/qwen3.6:latest You are concise and fast.
+```
+
+Syntax:
+
+```text
+/add_recruit <name> [provider/model] [system prompt...]
+```
+
+- **`<name>`** — required, unique within the crew (and not `crew`).
+- **`provider/model`** — optional. Omit it (give only a name) to inherit the
+  chief's model and provider. Use `-` or `inherit` as the model token to inherit
+  explicitly while still supplying a system prompt. `lms/...` maps to the
+  `openai` provider for LM Studio.
+- **system prompt** — everything after the model becomes the member's system
+  prompt. Without one, the member gets a simple default persona.
+
+Recruits inherit the chief's local tools and any connected MCP servers, so a new
+member can do the same file/shell/MCP work the chief can without reopening
+connections.
+
+### Giving a recruit a role with skills
+
+A bare crew of identical robots all do the same undifferentiated work. To divide
+labor, assign each member a **skill** — a named, reusable system prompt (the same
+skills used by `--skill` and `/skill`; list them with `/skills`). A skill becomes
+the recruit's role:
+
+```text
+# One skill as the recruit's role
+/add_recruit reviewer skill:security-review
+
+# Skill + explicit model, then an extra instruction appended after the skill
+/add_recruit reviewer ollama/qwen3.6:latest skill:security-review focus on the auth module
+
+# Several skills at once (repeat the token or comma-separate)
+/add_recruit reviewer - skill:security-review,ruby-style
+```
+
+The `skill:<id>` token may appear anywhere after the name; everything else is
+parsed as the model (position 1) and an optional trailing system prompt. The
+final role is the skill bodies joined, followed by any explicit prompt. An
+unknown skill id is reported rather than silently ignored, so the recruit always
+gets the role you intended.
+
+This is how you turn a `@crew` broadcast from four identical answers into a real
+division of labor — e.g. a security reviewer, a performance reviewer, a test
+reviewer, and a style reviewer, each with its own skill.
+
+### Re-skilling a member
+
+`/reskill` resets a member to a **clean slate** (a fresh conversation) and gives
+it a new role. The member keeps its `@name` and model:
+
+```text
+# Repurpose larry for the next phase
+/reskill larry skill:test-writing
+
+# Or hand it a freeform role
+/reskill larry - you now summarize the other members' findings
+```
+
+Use it to recover a member that drifted off task, or to move the crew through
+phases (review → fix → summarize) without re-creating robots.
+
+### Dropping a member
+
+`/drop_recruit` (alias `/drop`) removes a member by name:
+
+```text
+/drop_recruit researcher
+```
+
+The chief cannot be dropped — it is the session's lead robot.
+
+## Recruits vs. spawned specialists
+
+`/add_recruit` and `/spawn` look similar but serve different needs:
+
+| | `/add_recruit` (`/add`) | `/spawn` |
+|---|---|---|
+| Lifetime | Persists for the whole session | One-shot, for the **next** prompt only |
+| Joins the crew | Yes — shows in `/robots`, answers to `@name` | No — handles a single subtask, then is set aside |
+| Best for | A standing teammate you'll address repeatedly | A throwaway specialist for one focused task |
+
+Both accept the same explicit `name provider/model system prompt` form, so a
+specialist you find yourself reaching for repeatedly is a good candidate to
+promote from `/spawn` to `/add_recruit`.
+
+See the [Directives Reference](../directives-reference.md) for the full
+directive list and the [Working with Models](models.md) guide for multi-model
+sessions, consensus mode, and dynamic model switching.

data/docs/guides/executable-prompts.md

@@ -267,7 +267,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.3'
+          ruby-version: '4.0.0'
       - run: gem install aia
       - name: Run Analysis
         run: cat ./prompts/pr_analyzer.md | aia --no-output --no-mcp

data/docs/guides/index.md

@@ -12,6 +12,7 @@ Welcome to the AIA guides section! These comprehensive guides will help you mast
 
 - [Chat Mode](chat.md) - Interactive conversations with AI models
 - [Working with Models](models.md) - Multi-model support and configuration
+- [Crews](crew.md) - Address robots with @mention, broadcast with @crew, and recruit members at runtime
 - [Available Models](available-models.md) - Complete list of supported AI models
 - [Image Generation](image-generation.md) - Generate images with AI
 - [Tools Integration](tools.md) - Extend AIA with custom Ruby tools

data/docs/guides/models.md

@@ -690,6 +690,21 @@ aia --model ollama/llama3.2 --chat
 aia --model ollama/llama3.2,gpt-4o-mini,claude-3-sonnet my_prompt
 ```
 
+#### Reasoning models and `--thinking`
+
+Reasoning models such as `qwen3` emit their chain-of-thought wrapped in
+`<think>...</think>` tags as part of the streamed response. By default AIA
+hides these blocks so you only see the final answer. Use `--thinking` to show
+the reasoning as well:
+
+```bash
+# Hide reasoning (default)
+aia --chat --model ollama/qwen3:latest
+
+# Show the model's reasoning
+aia --chat --thinking --model ollama/qwen3:latest
+```
+
 #### Configuration
 
 ```yaml

data/docs/index.md

@@ -1,3 +1,28 @@
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+- [AIA - AI Assistant](#aia---ai-assistant)
+  - [Key Features](#key-features)
+    - [🚀 Dynamic Prompt Management](#-dynamic-prompt-management)
+    - [🎭 Roles & 🎓 Skills](#-roles---skills)
+    - [🔧 Powerful Integration](#-powerful-integration)
+    - [💬 Interactive Chat Sessions](#-interactive-chat-sessions)
+    - [🎯 Advanced Features](#-advanced-features)
+  - [Quick Start](#quick-start)
+  - [Core Architecture](#core-architecture)
+    - [Component Overview](#component-overview)
+    - [Core Components](#core-components)
+    - [External Dependencies](#external-dependencies)
+  - [Documentation Structure](#documentation-structure)
+    - [Getting Started](#getting-started)
+    - [Guides](#guides)
+    - [Reference](#reference)
+  - [Community & Support](#community--support)
+  - [License](#license)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
 # AIA - AI Assistant
 
 <table border="0">
@@ -185,7 +210,8 @@ graph TD
 - **AIA::PromptHandler** - Main prompt processing orchestrator
 - **AIA::ChatProcessorService** - Interactive chat session management
 - **AIA::DirectiveProcessor** - Processes embedded directives (`/command params`)
-- **AIA::RubyLLMAdapter** - Interfaces with the ruby_llm gem for AI model communication (manages conversation history via RubyLLM's Chat.@messages)
+- **AIA::RubyLLMAdapter** - Replaced in v2 by `RobotFactory` which builds `RobotLab::Robot` or `RobotLab::Network` instances powered by the `robot_lab` gem.
+- **AIA::RobotFactory** - Builds `RobotLab::Robot` or `RobotLab::Network` instances; the primary AI execution backend in v2
 - **AIA::ShellCommandExecutor** - Executes shell commands safely within prompts
 - **AIA::HistoryManager** - Manages prompt parameter history and user input
 - **AIA::UIPresenter** - Terminal output formatting and presentation
@@ -196,7 +222,8 @@ graph TD
 ### External Dependencies
 
 - **prompt_manager gem** - Core prompt management functionality
-- **ruby_llm gem** - AI model interface layer
+- **robot_lab gem** - Robot/network execution engine (replaces direct ruby_llm usage in v2)
+- **ruby_llm gem** - AI model interface layer (used internally by robot_lab)
 - **fzf** - Command-line fuzzy finder (external CLI tool)
 
 ## Documentation Structure

data/docs/installation.md

@@ -1,3 +1,46 @@
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+- [Installation](#installation)
+  - [Prerequisites](#prerequisites)
+    - [Required](#required)
+    - [Recommended](#recommended)
+  - [Installation Methods](#installation-methods)
+    - [Method 1: Install from RubyGems (Recommended)](#method-1-install-from-rubygems-recommended)
+    - [Method 2: Install from Source](#method-2-install-from-source)
+    - [Method 3: Using Bundler](#method-3-using-bundler)
+  - [Verify Installation](#verify-installation)
+  - [Initial Setup](#initial-setup)
+    - [1. Create Prompts Directory](#1-create-prompts-directory)
+    - [2. Create Configuration Directory](#2-create-configuration-directory)
+    - [3. Basic Configuration File (Optional)](#3-basic-configuration-file-optional)
+    - [4. Set Up API Keys](#4-set-up-api-keys)
+      - [OpenAI](#openai)
+      - [Anthropic Claude](#anthropic-claude)
+      - [Google Gemini](#google-gemini)
+      - [Ollama (Local models)](#ollama-local-models)
+  - [Optional Dependencies](#optional-dependencies)
+    - [Install fzf for Fuzzy Search](#install-fzf-for-fuzzy-search)
+      - [macOS (using Homebrew)](#macos-using-homebrew)
+      - [Ubuntu/Debian](#ubuntudebian)
+      - [Other systems](#other-systems)
+  - [Testing Your Installation](#testing-your-installation)
+    - [1. Check Available Models](#1-check-available-models)
+    - [2. Test Basic Functionality](#2-test-basic-functionality)
+    - [3. Test Chat Mode](#3-test-chat-mode)
+  - [Troubleshooting](#troubleshooting)
+    - [Common Issues](#common-issues)
+      - ["Command not found: aia"](#command-not-found-aia)
+      - ["No models available"](#no-models-available)
+      - ["fzf not found" warning](#fzf-not-found-warning)
+      - [Permission errors](#permission-errors)
+    - [Getting Help](#getting-help)
+  - [Next Steps](#next-steps)
+  - [Updating AIA](#updating-aia)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
 # Installation
 
 This guide will help you install AIA and get it running on your system.
@@ -5,7 +48,7 @@ This guide will help you install AIA and get it running on your system.
 ## Prerequisites
 
 ### Required
-- **Ruby**: Version 3.2 or higher
+- **Ruby**: Version >= 4.0.0
 - **RubyGems**: Usually comes with Ruby
 
 ### Recommended
@@ -84,7 +127,6 @@ Create a basic configuration file at `~/.config/aia/aia.yml`:
 # Uses nested structure - see docs/configuration.md for full reference
 
 llm:
-  adapter: ruby_llm
   temperature: 0.7
 
 models:
@@ -142,21 +184,6 @@ apt-get install fzf
 #### Other systems
 See the [fzf installation guide](https://github.com/junegunn/fzf#installation).
 
-### Install Additional Ruby Gems
-
-Some features may require additional gems:
-
-```bash
-# For advanced audio processing
-gem install ruby-audio
-
-# For advanced image processing  
-gem install mini_magick
-
-# For enhanced terminal features
-gem install tty-prompt
-```
-
 ## Testing Your Installation
 
 ### 1. Check Available Models