aia 1.1.0 → 2.0.0.0.pre.alpha

data/docs/tools-and-mcp-examples.md

@@ -1,3 +1,26 @@
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+- [Tools and MCP Examples](#tools-and-mcp-examples)
+  - [Real-World Tool Examples](#real-world-tool-examples)
+    - [File Processing Tools](#file-processing-tools)
+      - [Advanced Log Analyzer](#advanced-log-analyzer)
+      - [Configuration File Manager](#configuration-file-manager)
+    - [Development Tools](#development-tools)
+      - [Code Quality Analyzer](#code-quality-analyzer)
+  - [MCP Integration Examples](#mcp-integration-examples)
+    - [GitHub Repository Analyzer MCP](#github-repository-analyzer-mcp)
+    - [Database Schema Analyzer MCP](#database-schema-analyzer-mcp)
+  - [Integration Workflows](#integration-workflows)
+    - [Full-Stack Application Analysis](#full-stack-application-analysis)
+    - [DevOps Pipeline Assessment](#devops-pipeline-assessment)
+  - [Advanced Integration Patterns](#advanced-integration-patterns)
+    - [Multi-Environment Consistency Checker](#multi-environment-consistency-checker)
+  - [Related Documentation](#related-documentation)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
 # Tools and MCP Examples
 
 This comprehensive collection showcases real-world examples of RubyLLM tools and MCP client integrations, demonstrating practical applications and advanced techniques.

data/docs/workflows-and-pipelines.md

@@ -1,3 +1,57 @@
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+- [Workflows and Pipelines](#workflows-and-pipelines)
+  - [Understanding Workflows](#understanding-workflows)
+    - [Basic Concepts](#basic-concepts)
+  - [Simple Workflows](#simple-workflows)
+    - [Sequential Processing](#sequential-processing)
+    - [Basic Pipeline](#basic-pipeline)
+  - [Pipeline Definition](#pipeline-definition)
+    - [Command Line Pipelines](#command-line-pipelines)
+    - [Directive-Based Pipelines](#directive-based-pipelines)
+    - [Dynamic Pipeline Generation](#dynamic-pipeline-generation)
+  - [Advanced Workflow Patterns](#advanced-workflow-patterns)
+    - [Conditional Workflows](#conditional-workflows)
+    - [Parallel Processing Workflows](#parallel-processing-workflows)
+    - [Error Recovery Workflows](#error-recovery-workflows)
+  - [State Management in Workflows](#state-management-in-workflows)
+    - [Context Persistence](#context-persistence)
+    - [Data Passing Between Stages](#data-passing-between-stages)
+  - [Current Stage: <%= current_stage.capitalize %>](#current-stage--current_stagecapitalize-)
+  - [Analysis Task](#analysis-task)
+- [Prepare data for next stage (this would be set by the AI response processing)](#prepare-data-for-next-stage-this-would-be-set-by-the-ai-response-processing)
+- [This would typically be saved after AI processing](#this-would-typically-be-saved-after-ai-processing)
+- [master_controller.md](#master_controllermd)
+- [Master Workflow Controller](#master-workflow-controller)
+- [workflow_monitor.md](#workflow_monitormd)
+- [Setup workflow logging](#setup-workflow-logging)
+- [Log workflow start](#log-workflow-start)
+- [model_optimized_workflow.md](#model_optimized_workflowmd)
+- [cached_workflow.md](#cached_workflowmd)
+- [Create cache key from inputs and configuration](#create-cache-key-from-inputs-and-configuration)
+- [software_dev_pipeline.md](#software_dev_pipelinemd)
+- [Software Development Pipeline](#software-development-pipeline)
+  - [Pipeline Stages:](#pipeline-stages)
+- [content_creation_pipeline.md](#content_creation_pipelinemd)
+- [Content Creation Pipeline](#content-creation-pipeline)
+  - [Research Phase](#research-phase)
+- [data_science_workflow.md](#data_science_workflowmd)
+    - [Checkpoints in Interactive Workflows](#checkpoints-in-interactive-workflows)
+  - [Workflow Best Practices](#workflow-best-practices)
+    - [Design Principles](#design-principles)
+    - [Performance Considerations](#performance-considerations)
+    - [Maintenance and Debugging](#maintenance-and-debugging)
+  - [Troubleshooting Workflows](#troubleshooting-workflows)
+    - [Common Issues](#common-issues)
+      - [Workflow Interruption](#workflow-interruption)
+      - [Context Size Issues](#context-size-issues)
+      - [Model Rate Limiting](#model-rate-limiting)
+  - [Related Documentation](#related-documentation)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
+
 # Workflows and Pipelines
 
 AIA's workflow system allows you to chain prompts together, creating sophisticated multi-stage processes for complex tasks. This enables automated processing pipelines that can handle everything from simple two-step workflows to complex enterprise-level automation.
@@ -8,9 +62,21 @@ AIA's workflow system allows you to chain prompts together, creating sophisticat
 
 **Workflow**: A sequence of prompts executed in order, where each prompt can pass context to the next.
 
-**Pipeline**: A predefined sequence of prompt IDs that are executed automatically.
+**Next Prompt**: The immediate next prompt to execute after the current one completes. Specified as a `next` key in the YAML front matter of a `.md` prompt file:
+
+```yaml
+---
+next: summary
+---
+```
 
-**Next Prompt**: The immediate next prompt to execute after the current one completes.
+**Pipeline**: A predefined sequence of prompt IDs specified as a `pipeline` key in YAML front matter, or via `--pipeline` on the command line. These keys are placed at the top of the `.md` prompt file and are processed during prompt loading, not as chat-time directives:
+
+```yaml
+---
+pipeline: analyze_data,generate_insights,write_report
+---
+```
 
 **Context Passing**: Information and results flow from one prompt to the next in the sequence.
 
@@ -19,7 +85,9 @@ AIA's workflow system allows you to chain prompts together, creating sophisticat
 ### Sequential Processing
 ```markdown
 # first_prompt.md
-/next second_prompt
+---
+next: second_prompt
+---
 /config model gpt-4
 
 Analyze the following data and prepare it for detailed analysis:
@@ -62,9 +130,14 @@ aia --model gpt-4 --pipeline "review,optimize,test" code.py
 ```
 
 ### Directive-Based Pipelines
+
+The `pipeline` key is placed in YAML front matter at the top of the prompt file and is processed during prompt loading:
+
 ```markdown
 # pipeline_starter.md
-/pipeline analyze_data,generate_insights,create_visualization,write_report
+---
+pipeline: analyze_data,generate_insights,create_visualization,write_report
+---
 /config model claude-3-sonnet
 
 # Data Analysis Pipeline
@@ -216,7 +289,7 @@ state['current_stage'] = stage_name
 state['data'][stage_name] = {
   'started_at' => Time.now.iso8601,
   'input_file' => '<%= input_file %>',
-  'model' => AIA.config.model
+  'model' => AIA.config.models.first&.name
 }
 
 # Save state
@@ -325,7 +398,7 @@ workflow_id = ENV['WORKFLOW_ID'] || SecureRandom.uuid
 # Log workflow start
 logger.info("Workflow #{workflow_id} started")
 logger.info("Stage: <%= stage_name %>")
-logger.info("Model: #{AIA.config.model}")
+logger.info("Model: #{AIA.config.models.first&.name}")
 logger.info("Input: <%= input_description %>")
 
 start_time = Time.now
@@ -373,7 +446,7 @@ require 'digest'
 cache_inputs = {
   'stage' => '<%= stage_name %>',
   'input_file' => '<%= input_file %>',
-  'model' => AIA.config.model,
+  'model' => AIA.config.models.first&.name,
   'temperature' => AIA.config.temperature
 }
 
@@ -481,6 +554,10 @@ Pipeline optimized for <%= complexity %> analysis with <%= selected_pipeline.len
 /config temperature 0.3
 ```
 
+### Checkpoints in Interactive Workflows
+
+In interactive chat-based workflows, use `/checkpoint` to save the current conversation state at a meaningful point, and `/restore` to return to that saved state if a later branch produces unsatisfactory results. This is especially useful when running multi-stage workflows that involve experimental or speculative steps.
+
 ## Workflow Best Practices
 
 ### Design Principles

data/examples/.gitignore

@@ -1 +1,2 @@
 output/
+orchestrated_build_*/

data/examples/00_setup_aia.sh

@@ -6,10 +6,9 @@
 #
 # What it does:
 #   1. Verifies aia is installed
-#   2. Verifies ollama is installed and running
-#   3. Pulls the qwen3 model (good tool-calling support)
-#   4. Verifies examples/prompts_dir exists
-#   5. Writes examples/aia_config.yml for use with -c flag
+#   2. Verifies OPENAI_API_KEY is set
+#   3. Verifies examples/prompts_dir exists
+#   4. Writes examples/aia_config.yml for use with -c flag
 #
 # Each demo script sources common.sh which clears AIA_* env vars
 # and sets CONFIG=aia_config.yml for clean, isolated runs.
@@ -24,9 +23,16 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROMPTS_DIR="${SCRIPT_DIR}/prompts_dir"
 CONFIG_FILE="${SCRIPT_DIR}/aia_config.yml"
 
-# The model to use for demos. qwen3 is Ollama's reference model
-# for tool calling and has strong instruction-following ability.
-DEMO_MODEL="qwen3"
+# When running from inside the development repo, prefer the local bin/aia
+# over any system-installed gem so setup reflects the version being demoed.
+REPO_BIN="$(cd "${SCRIPT_DIR}/.." && pwd)/bin"
+if [ -f "${REPO_BIN}/aia" ]; then
+  export PATH="${REPO_BIN}:${PATH}"
+fi
+
+# The model to use for demos. gpt-4.1 is OpenAI's flagship model with
+# strong instruction-following and tool-calling support.
+DEMO_MODEL="gpt-4.1"
 
 echo "=== AIA Examples Setup ==="
 echo
@@ -34,51 +40,28 @@ echo
 # --- Step 1: Check that aia is installed ---
 
 if ! command -v aia &> /dev/null; then
-  echo "ERROR: 'aia' is not installed."
-  echo "       Install with: gem install aia"
+  echo "ERROR: 'aia' is not found."
+  echo "       From the repo:  just install   (installs local build)"
+  echo "       From RubyGems:  gem install aia"
   exit 1
 fi
 
 AIA_VERSION=$(aia --version 2>/dev/null || echo "unknown")
 echo "[ok] aia is installed (v${AIA_VERSION})"
 
-# --- Step 2: Check that ollama is installed and running ---
-
-if ! command -v ollama &> /dev/null; then
-  echo "ERROR: 'ollama' is not installed."
-  echo "       Install from: https://ollama.com"
-  echo "       macOS: brew install ollama"
-  exit 1
-fi
-
-echo "[ok] ollama is installed"
-
-# Check if ollama is serving
-OLLAMA_BASE="${OLLAMA_API_BASE:-http://localhost:11434}"
+# --- Step 2: Check that OPENAI_API_KEY is set ---
 
-if ! curl -s "${OLLAMA_BASE}/api/tags" > /dev/null 2>&1; then
-  echo "WARNING: ollama does not appear to be running."
-  echo "         Start it with: ollama serve"
-  echo "         Then re-run this script."
+if [ -z "${OPENAI_API_KEY:-}" ]; then
+  echo "ERROR: OPENAI_API_KEY is not set."
+  echo "       Export your key before running demos:"
+  echo "         export OPENAI_API_KEY=sk-..."
+  echo "       Get a key at: https://platform.openai.com/api-keys"
   exit 1
 fi
 
-echo "[ok] ollama is running at ${OLLAMA_BASE}"
-
-# --- Step 3: Pull the demo model ---
-
-echo
-echo "Checking for model: ${DEMO_MODEL} ..."
-
-if ollama list 2>/dev/null | grep -q "^${DEMO_MODEL}"; then
-  echo "[ok] ${DEMO_MODEL} is already available"
-else
-  echo "Pulling ${DEMO_MODEL} (this may take a few minutes on first run) ..."
-  ollama pull "${DEMO_MODEL}"
-  echo "[ok] ${DEMO_MODEL} pulled successfully"
-fi
+echo "[ok] OPENAI_API_KEY is set"
 
-# --- Step 4: Verify prompts directory ---
+# --- Step 3: Verify prompts directory ---
 
 echo
 if [ -d "${PROMPTS_DIR}" ]; then
@@ -88,7 +71,7 @@ else
   echo "[ok] created prompts_dir at ${PROMPTS_DIR}"
 fi
 
-# --- Step 5: Write the config file ---
+# --- Step 4: Write the config file ---
 
 cat > "${CONFIG_FILE}" <<EOF
 # AIA configuration for example demos
@@ -106,7 +89,7 @@ prompts:
   dir: ./prompts_dir
 
 models:
-  - name: ollama/${DEMO_MODEL}
+  - name: ${DEMO_MODEL}
 
 output:
   file: ~
@@ -124,5 +107,5 @@ echo "=== Setup Complete ==="
 echo
 echo "All demo scripts use:"
 echo "  aia -c aia_config.yml ..."
-echo "  Model:       ollama/${DEMO_MODEL}"
+echo "  Model:       ${DEMO_MODEL}"
 echo "  Prompts dir: ${PROMPTS_DIR}"

data/examples/11_multi_model.sh

@@ -12,18 +12,16 @@
 #   synthesizes a unified response from all answers.
 #
 # Multiple models are specified as a comma-separated list with -m.
-# This demo uses two Ollama models. If you only have one model
-# available, pull a second one first:
-#   ollama pull phi4-mini
+# This demo uses two OpenAI models (gpt-4.1 and gpt-4.1-mini).
 #
-# Prerequisites: Run 00_setup_aia.sh first, plus a second model.
+# Prerequisites: Run 00_setup_aia.sh first (OPENAI_API_KEY must be set).
 # Usage: cd examples && bash 11_multi_model.sh
 
 set -euo pipefail
 source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
 
-MODEL_A="ollama/qwen3"
-MODEL_B="ollama/phi4-mini"
+MODEL_A="gpt-4.1"
+MODEL_B="gpt-4.1-mini"
 
 echo "=== Demo 11: Multiple Models ==="
 echo
@@ -40,14 +38,6 @@ cat prompts_dir/explain_recursion.md
 echo "==="
 echo
 
-# --- Check that the second model is available ---
-
-if ! ollama list 2>/dev/null | grep -q "^phi4-mini"; then
-  echo "Model phi4-mini is not available. Pulling it now ..."
-  ollama pull phi4-mini
-  echo
-fi
-
 # --- Part 1: Comparison mode ---
 
 echo "--- Part 1: Comparison mode (default) ---"

data/examples/12_token_usage.sh

@@ -5,15 +5,14 @@
 # after each response. When used with multiple models this lets
 # you compare how verbose each model is.
 #
-# Prerequisites: Run 00_setup_aia.sh first, plus a second model.
-#   ollama pull phi4-mini
+# Prerequisites: Run 00_setup_aia.sh first (OPENAI_API_KEY must be set).
 # Usage: cd examples && bash 12_token_usage.sh
 
 set -euo pipefail
 source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
 
-MODEL_A="ollama/qwen3"
-MODEL_B="ollama/phi4-mini"
+MODEL_A="gpt-4.1"
+MODEL_B="gpt-4.1-mini"
 
 echo "=== Demo 12: Token Usage ==="
 echo
@@ -28,14 +27,6 @@ cat prompts_dir/sort_compare.md
 echo "==="
 echo
 
-# --- Check that the second model is available ---
-
-if ! ollama list 2>/dev/null | grep -q "^phi4-mini"; then
-  echo "Model phi4-mini is not available. Pulling it now ..."
-  ollama pull phi4-mini
-  echo
-fi
-
 # --- Part 1: Single model with --tokens ---
 
 echo "--- Part 1: Single model with --tokens ---"

data/examples/18_tools.sh

@@ -44,10 +44,18 @@ echo "==="
 cat prompts_dir/use_tools.md
 echo "==="
 echo
-echo "Running: aia -c ${CONFIG} --no-output --rq shared_tools use_tools"
+echo "shared_tools ships with 35+ tools. Passing all of them in one API"
+echo "call causes gpt-4.1 to skip tool use entirely. We use --allowed-tools"
+echo "to expose only the three tools this prompt actually needs."
+echo
+echo "Running: aia -c ${CONFIG} --no-output --rq shared_tools \\"
+echo "         --allowed-tools current_date_time_tool,system_info_tool,dns_tool \\"
+echo "         use_tools"
 echo
 echo "The model will call tools to get live data, then summarize"
 echo "the results."
 echo
 
-aia -c "${CONFIG}" --no-output --rq shared_tools use_tools
+aia -c "${CONFIG}" --no-output --rq shared_tools \
+  --allowed-tools current_date_time_tool,system_info_tool,dns_tool \
+  use_tools

data/examples/22_chat_mode.sh

@@ -32,16 +32,6 @@ if ! command -v expect &>/dev/null; then
     exit 1
 fi
 
-# Drain leaked escape sequences from the terminal input buffer.
-# Reline queries cursor position (\e[6n) inside the pty; the
-# terminal's responses (\e[row;colR) can leak into bash's stdin
-# after expect exits.
-drain_terminal() {
-    sleep 0.2
-    stty sane 2>/dev/null || true
-    while IFS= read -r -t 0.2 -n 100 _ 2>/dev/null; do :; done
-}
-
 echo "=== Demo 22: Chat Mode ==="
 echo
 echo "The --chat flag opens an interactive conversation after all"

data/examples/23_verify.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# examples/23_verify.sh
+#
+# Demonstrates /verify mode: VerificationNetwork.
+#
+# Two robots independently answer the same question with
+# slightly different system prompts, then a third "reconciler"
+# robot compares both answers, identifies agreements and
+# disagreements, and produces a final verified answer.
+#
+# All three robots use the same model -- no second model needed.
+#
+# How it works in chat:
+#   1. Type /verify  →  AIA sets verification mode for next prompt
+#   2. Type your question  →  two verifiers + reconciler run
+#
+# Prerequisites: Run 00_setup_aia.sh first
+# Usage: cd examples && bash 23_verify.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+if ! command -v expect &>/dev/null; then
+    echo "ERROR: expect is not installed."
+    echo "       Install with: brew install expect"
+    exit 1
+fi
+
+echo "=== Demo 23: Verify Mode (VerificationNetwork) ==="
+echo
+echo "The /verify directive runs two independent robots on the same"
+echo "question, then a third reconciler robot compares the answers"
+echo "and produces a final verified response."
+echo
+echo "Directive mechanics: /verify sets the mode for the NEXT prompt."
+echo "Type /verify, then type your question on the next line."
+echo
+
+# --- Part 1: Verify a factual question ---
+
+echo "--- Part 1: Verify a factual claim ---"
+echo
+echo "We'll type /verify, then ask about the causes of the 2008"
+echo "financial crisis. Two verifiers answer independently; the"
+echo "reconciler synthesizes a final, checked response."
+echo
+echo "Running: aia -c ${CONFIG} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 300
+log_user 1
+
+spawn aia -c aia_config.yml --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "/verify\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for directive confirmation ***"; exit 1 }
+}
+
+send "What were the three main causes of the 2008 global financial crisis?\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for verification results ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 2: Verify a technical question ---
+
+echo "--- Part 2: Verify a technical explanation ---"
+echo
+echo "Verification is especially useful for technical topics where"
+echo "subtle errors can slip through. Two independent passes catch"
+echo "more mistakes than one."
+echo
+echo "Running: aia -c ${CONFIG} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 300
+log_user 1
+
+spawn aia -c aia_config.yml --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "/verify\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for directive confirmation ***"; exit 1 }
+}
+
+send "Explain how TCP's three-way handshake works and why it guarantees reliable connection establishment.\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for verification results ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 3: Your turn ---
+
+echo "--- Part 3: Your turn ---"
+echo
+echo "Try /verify on any factual or technical question where you"
+echo "want cross-checked confidence rather than a single answer."
+echo
+
+if [[ "${BATCH_MODE:-}" == "true" ]]; then
+  echo "(Skipping interactive session in batch mode)"
+else
+  aia -c "${CONFIG}" --chat
+fi

data/examples/24_decompose.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# examples/24_decompose.sh
+#
+# Demonstrates /decompose mode: PromptDecomposer.
+#
+# A coordinator robot analyzes whether a complex prompt can be
+# split into 2-5 independent sub-tasks. If decomposable, specialist
+# robots solve each in parallel and results are synthesized into
+# a unified answer. Falls back to normal mode if the prompt is not
+# decomposable.
+#
+# How it works in chat:
+#   1. Type /decompose  →  AIA sets decomposition mode for next prompt
+#   2. Type your complex question  →  coordinator splits, runs, synthesizes
+#
+# Prerequisites: Run 00_setup_aia.sh first
+# Usage: cd examples && bash 24_decompose.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+if ! command -v expect &>/dev/null; then
+    echo "ERROR: expect is not installed."
+    echo "       Install with: brew install expect"
+    exit 1
+fi
+
+echo "=== Demo 24: Decompose Mode (PromptDecomposer) ==="
+echo
+echo "The /decompose directive breaks a complex prompt into"
+echo "independent sub-tasks that run in parallel, then synthesizes"
+echo "their results into a single coherent response."
+echo
+echo "Directive mechanics: /decompose sets the mode for the NEXT prompt."
+echo "Type /decompose, then type your complex multi-part question."
+echo
+
+# --- Part 1: Decomposable multi-part question ---
+
+echo "--- Part 1: A complex decomposable question ---"
+echo
+echo "This question has several independent parts: explaining a"
+echo "concept, listing use cases, and making a recommendation."
+echo "The decomposer should split these and run them in parallel."
+echo
+echo "Running: aia -c ${CONFIG} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 300
+log_user 1
+
+spawn aia -c aia_config.yml --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "/decompose\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for directive confirmation ***"; exit 1 }
+}
+
+send "Explain the difference between TCP and UDP, list the top 3 use cases for each protocol, and recommend which to use for a real-time multiplayer game and explain why.\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for decomposition results ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 2: Non-decomposable question (fallback) ---
+
+echo "--- Part 2: A simple question (fallback to normal mode) ---"
+echo
+echo "If the prompt cannot be meaningfully split, the decomposer"
+echo "falls back to normal mode and answers directly. This shows"
+echo "that /decompose is safe to use on any prompt."
+echo
+echo "Running: aia -c ${CONFIG} --chat"
+echo
+
+expect <<'EXPECT_SCRIPT'
+set timeout 180
+log_user 1
+
+spawn aia -c aia_config.yml --chat
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for chat prompt ***"; exit 1 }
+}
+
+send "/decompose\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for directive confirmation ***"; exit 1 }
+}
+
+send "What is the capital of France?\r"
+
+expect {
+  "#=> " {}
+  timeout { puts "\n*** Timed out waiting for response ***"; exit 1 }
+}
+
+send "exit\r"
+expect eof
+EXPECT_SCRIPT
+
+drain_terminal
+echo
+echo
+
+# --- Part 3: Your turn ---
+
+echo "--- Part 3: Your turn ---"
+echo
+echo "Try /decompose on any complex, multi-part question or request."
+echo "The decomposer works best on prompts that have 2-5 clearly"
+echo "independent components."
+echo
+
+if [[ "${BATCH_MODE:-}" == "true" ]]; then
+  echo "(Skipping interactive session in batch mode)"
+else
+  aia -c "${CONFIG}" --chat
+fi