feat(ipuaro): add commands configuration

- Add CommandsConfigSchema with timeout option
- Integrate timeout configuration in RunCommandTool
- Add 22 new unit tests (19 schema + 3 integration)
- Complete v0.22.0 Extended Configuration milestone

packages/ipuaro/ARCHITECTURE.md

@@ -0,0 +1,566 @@
+# ipuaro Architecture
+
+This document describes the architecture, design decisions, and implementation details of ipuaro.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Clean Architecture](#clean-architecture)
+- [Layer Details](#layer-details)
+- [Data Flow](#data-flow)
+- [Key Design Decisions](#key-design-decisions)
+- [Tech Stack](#tech-stack)
+- [Performance Considerations](#performance-considerations)
+
+## Overview
+
+ipuaro is a local AI agent for codebase operations built on Clean Architecture principles. It enables "infinite" context feeling through lazy loading and AST-based code understanding.
+
+### Core Concepts
+
+1. **Lazy Loading**: Load code on-demand via tools, not all at once
+2. **AST-Based Understanding**: Parse and index code structure for fast lookups
+3. **100% Local**: Ollama LLM + Redis storage, no cloud dependencies
+4. **Session Persistence**: Resume conversations across restarts
+5. **Tool-Based Interface**: LLM accesses code through 18 specialized tools
+
+## Clean Architecture
+
+The project follows Clean Architecture with strict dependency rules:
+
+```
+┌─────────────────────────────────────────────────┐
+│                     TUI Layer                    │  ← Ink/React components
+│                   (Framework)                    │
+├─────────────────────────────────────────────────┤
+│                   CLI Layer                      │  ← Commander.js entry
+│                  (Interface)                     │
+├─────────────────────────────────────────────────┤
+│              Infrastructure Layer                │  ← External adapters
+│  (Storage, LLM, Indexer, Tools, Security)       │
+├─────────────────────────────────────────────────┤
+│              Application Layer                   │  ← Use cases & DTOs
+│     (StartSession, HandleMessage, etc.)          │
+├─────────────────────────────────────────────────┤
+│                 Domain Layer                     │  ← Business logic
+│  (Entities, Value Objects, Service Interfaces)  │
+└─────────────────────────────────────────────────┘
+```
+
+**Dependency Rule**: Outer layers depend on inner layers, never the reverse.
+
+## Layer Details
+
+### Domain Layer (Core Business Logic)
+
+**Location**: `src/domain/`
+
+**Responsibilities**:
+- Define business entities and value objects
+- Declare service interfaces (ports)
+- No external dependencies (pure TypeScript)
+
+**Components**:
+
+```
+domain/
+├── entities/
+│   ├── Session.ts           # Session entity with history and stats
+│   └── Project.ts           # Project entity with metadata
+├── value-objects/
+│   ├── FileData.ts          # File content with hash and size
+│   ├── FileAST.ts           # Parsed AST structure
+│   ├── FileMeta.ts          # Complexity, dependencies, hub detection
+│   ├── ChatMessage.ts       # Message with role, content, tool calls
+│   ├── ToolCall.ts          # Tool invocation with parameters
+│   ├── ToolResult.ts        # Tool execution result
+│   └── UndoEntry.ts         # File change for undo stack
+├── services/
+│   ├── IStorage.ts          # Storage interface (port)
+│   ├── ILLMClient.ts        # LLM interface (port)
+│   ├── ITool.ts             # Tool interface (port)
+│   └── IIndexer.ts          # Indexer interface (port)
+└── constants/
+    └── index.ts             # Domain constants
+```
+
+**Key Design**:
+- Value objects are immutable
+- Entities have identity and lifecycle
+- Interfaces define contracts, not implementations
+
+### Application Layer (Use Cases)
+
+**Location**: `src/application/`
+
+**Responsibilities**:
+- Orchestrate domain logic
+- Implement use cases (application-specific business rules)
+- Define DTOs for data transfer
+- Coordinate between domain and infrastructure
+
+**Components**:
+
+```
+application/
+├── use-cases/
+│   ├── StartSession.ts      # Initialize or load session
+│   ├── HandleMessage.ts     # Main message orchestrator
+│   ├── IndexProject.ts      # Project indexing workflow
+│   ├── ExecuteTool.ts       # Tool execution with validation
+│   └── UndoChange.ts        # Revert file changes
+├── dtos/
+│   ├── SessionDto.ts        # Session data transfer object
+│   ├── MessageDto.ts        # Message DTO
+│   └── ToolCallDto.ts       # Tool call DTO
+├── mappers/
+│   └── SessionMapper.ts     # Domain ↔ DTO conversion
+└── interfaces/
+    └── IToolRegistry.ts     # Tool registry interface
+```
+
+**Key Use Cases**:
+
+1. **StartSession**: Creates new session or loads latest
+2. **HandleMessage**: Main flow (LLM → Tools → Response)
+3. **IndexProject**: Scan → Parse → Analyze → Store
+4. **UndoChange**: Restore file from undo stack
+
+### Infrastructure Layer (External Implementations)
+
+**Location**: `src/infrastructure/`
+
+**Responsibilities**:
+- Implement domain interfaces
+- Handle external systems (Redis, Ollama, filesystem)
+- Provide concrete tool implementations
+- Security and validation
+
+**Components**:
+
+```
+infrastructure/
+├── storage/
+│   ├── RedisClient.ts       # Redis connection wrapper
+│   ├── RedisStorage.ts      # IStorage implementation
+│   └── schema.ts            # Redis key schema
+├── llm/
+│   ├── OllamaClient.ts      # ILLMClient implementation
+│   ├── prompts.ts           # System prompts
+│   └── ResponseParser.ts    # Parse XML tool calls
+├── indexer/
+│   ├── FileScanner.ts       # Recursive file scanning
+│   ├── ASTParser.ts         # tree-sitter parsing
+│   ├── MetaAnalyzer.ts      # Complexity and dependencies
+│   ├── IndexBuilder.ts      # Symbol index + deps graph
+│   └── Watchdog.ts          # File watching (chokidar)
+├── tools/                   # 18 tool implementations
+│   ├── registry.ts
+│   ├── read/                # GetLines, GetFunction, GetClass, GetStructure
+│   ├── edit/                # EditLines, CreateFile, DeleteFile
+│   ├── search/              # FindReferences, FindDefinition
+│   ├── analysis/            # GetDependencies, GetDependents, GetComplexity, GetTodos
+│   ├── git/                 # GitStatus, GitDiff, GitCommit
+│   └── run/                 # RunCommand, RunTests
+└── security/
+    ├── Blacklist.ts         # Dangerous commands
+    ├── Whitelist.ts         # Safe commands
+    └── PathValidator.ts     # Path traversal prevention
+```
+
+**Key Implementations**:
+
+1. **RedisStorage**: Uses Redis hashes for files/AST/meta, lists for undo
+2. **OllamaClient**: HTTP API client with tool calling support
+3. **ASTParser**: tree-sitter for TS/JS/TSX/JSX parsing
+4. **ToolRegistry**: Manages tool lifecycle and execution
+
+### TUI Layer (Terminal UI)
+
+**Location**: `src/tui/`
+
+**Responsibilities**:
+- Render terminal UI with Ink (React for terminal)
+- Handle user input and hotkeys
+- Display chat history and status
+
+**Components**:
+
+```
+tui/
+├── App.tsx                  # Main app shell
+├── components/
+│   ├── StatusBar.tsx        # Top status bar
+│   ├── Chat.tsx             # Message history display
+│   ├── Input.tsx            # User input with history
+│   ├── DiffView.tsx         # Inline diff display
+│   ├── ConfirmDialog.tsx    # Edit confirmation
+│   ├── ErrorDialog.tsx      # Error handling
+│   └── Progress.tsx         # Progress bar (indexing)
+└── hooks/
+    ├── useSession.ts        # Session state management
+    ├── useHotkeys.ts        # Keyboard shortcuts
+    └── useCommands.ts       # Slash command handling
+```
+
+**Key Features**:
+
+- Real-time status updates (context usage, session time)
+- Input history with ↑/↓ navigation
+- Hotkeys: Ctrl+C (interrupt), Ctrl+D (exit), Ctrl+Z (undo)
+- Diff preview for edits with confirmation
+- Error recovery with retry/skip/abort options
+
+### CLI Layer (Entry Point)
+
+**Location**: `src/cli/`
+
+**Responsibilities**:
+- Command-line interface with Commander.js
+- Dependency injection and initialization
+- Onboarding checks (Redis, Ollama, model)
+
+**Components**:
+
+```
+cli/
+├── index.ts                 # Commander.js setup
+└── commands/
+    ├── start.ts             # Start TUI (default command)
+    ├── init.ts              # Create .ipuaro.json config
+    └── index-cmd.ts         # Index-only command
+```
+
+**Commands**:
+
+1. `ipuaro [path]` - Start TUI in directory
+2. `ipuaro init` - Create config file
+3. `ipuaro index` - Index without TUI
+
+### Shared Module
+
+**Location**: `src/shared/`
+
+**Responsibilities**:
+- Cross-cutting concerns
+- Configuration management
+- Error handling
+- Utility functions
+
+**Components**:
+
+```
+shared/
+├── types/
+│   └── index.ts             # Shared TypeScript types
+├── constants/
+│   ├── config.ts            # Config schema and loader
+│   └── messages.ts          # User-facing messages
+├── utils/
+│   ├── hash.ts              # MD5 hashing
+│   └── tokens.ts            # Token estimation
+└── errors/
+    ├── IpuaroError.ts       # Custom error class
+    └── ErrorHandler.ts      # Error handling service
+```
+
+## Data Flow
+
+### 1. Startup Flow
+
+```
+CLI Entry (bin/ipuaro.js)
+    ↓
+Commander.js parses arguments
+    ↓
+Onboarding checks (Redis, Ollama, Model)
+    ↓
+Initialize dependencies:
+    - RedisClient connects
+    - RedisStorage initialized
+    - OllamaClient created
+    - ToolRegistry with 18 tools
+    ↓
+StartSession use case:
+    - Load latest session or create new
+    - Initialize ContextManager
+    ↓
+Launch TUI (App.tsx)
+    - Render StatusBar, Chat, Input
+    - Set up hotkeys
+```
+
+### 2. Message Flow
+
+```
+User types message in Input.tsx
+    ↓
+useSession.handleMessage()
+    ↓
+HandleMessage use case:
+    1. Add user message to history
+    2. Build context (system prompt + structure + AST)
+    3. Send to OllamaClient.chat()
+    4. Parse tool calls from response
+    5. For each tool call:
+        - If requiresConfirmation: show ConfirmDialog
+        - Execute tool via ToolRegistry
+        - Collect results
+    6. If tool results: goto step 3 (continue loop)
+    7. Add assistant response to history
+    8. Update session in Redis
+    ↓
+Display response in Chat.tsx
+```
+
+### 3. Edit Flow
+
+```
+LLM calls edit_lines tool
+    ↓
+ToolRegistry.execute()
+    ↓
+EditLinesTool.execute():
+    1. Validate path (PathValidator)
+    2. Check hash conflict
+    3. Build diff
+    ↓
+ConfirmDialog shows diff
+    ↓
+User chooses:
+    - Apply: Continue
+    - Cancel: Return error to LLM
+    - Edit: Manual edit (future)
+    ↓
+If Apply:
+    1. Create UndoEntry
+    2. Push to undo stack (Redis list)
+    3. Write to filesystem
+    4. Update RedisStorage (lines, hash, AST, meta)
+    ↓
+Return success to LLM
+```
+
+### 4. Indexing Flow
+
+```
+FileScanner.scan()
+    - Recursively walk directory
+    - Filter via .gitignore + ignore patterns
+    - Detect binary files (skip)
+    ↓
+For each file:
+    ASTParser.parse()
+        - tree-sitter parse
+        - Extract imports, exports, functions, classes
+        ↓
+    MetaAnalyzer.analyze()
+        - Calculate complexity (LOC, nesting, cyclomatic)
+        - Resolve dependencies (imports → file paths)
+        - Detect hubs (>5 dependents)
+        ↓
+    RedisStorage.setFile(), .setAST(), .setMeta()
+    ↓
+IndexBuilder.buildSymbolIndex()
+    - Map symbol names → locations
+    ↓
+IndexBuilder.buildDepsGraph()
+    - Build bidirectional import graph
+    ↓
+Store indexes in Redis
+    ↓
+Watchdog.start()
+    - Watch for file changes
+    - On change: Re-parse and update indexes
+```
+
+## Key Design Decisions
+
+### 1. Why Redis?
+
+**Pros**:
+- Fast in-memory access for frequent reads
+- AOF persistence (append-only file) for durability
+- Native support for hashes, lists, sets
+- Simple key-value model fits our needs
+- Excellent for session data
+
+**Alternatives considered**:
+- SQLite: Slower, overkill for our use case
+- JSON files: No concurrent access, slow for large data
+- PostgreSQL: Too heavy, we don't need relational features
+
+### 2. Why tree-sitter?
+
+**Pros**:
+- Incremental parsing (fast re-parsing)
+- Error-tolerant (works with syntax errors)
+- Multi-language support
+- Used by GitHub, Neovim, Atom
+
+**Alternatives considered**:
+- TypeScript Compiler API: TS-only, not error-tolerant
+- Babel: JS-focused, heavy dependencies
+- Regex: Fragile, inaccurate
+
+### 3. Why Ollama?
+
+**Pros**:
+- 100% local, no API keys
+- Easy installation (brew install ollama)
+- Good model selection (qwen2.5-coder, deepseek-coder)
+- Tool calling support
+
+**Alternatives considered**:
+- OpenAI: Costs money, sends code to cloud
+- Anthropic Claude: Same concerns as OpenAI
+- llama.cpp: Lower level, requires more setup
+
+Planned: Support for OpenAI/Anthropic in v1.2.0 as optional providers.
+
+### 4. Why XML for Tool Calls?
+
+**Pros**:
+- LLMs trained on XML (very common format)
+- Self-describing (parameter names in tags)
+- Easy to parse with regex
+- More reliable than JSON for smaller models
+
+**Alternatives considered**:
+- JSON: Smaller models struggle with exact JSON syntax
+- Function calling API: Not all models support it
+
+### 5. Why Clean Architecture?
+
+**Pros**:
+- Testability (domain has no external dependencies)
+- Flexibility (easy to swap Redis for SQLite)
+- Maintainability (clear separation of concerns)
+- Scalability (layers can evolve independently)
+
+**Cost**: More files and indirection, but worth it for long-term maintenance.
+
+### 6. Why Lazy Loading Instead of RAG?
+
+**RAG (Retrieval Augmented Generation)**:
+- Pre-computes embeddings
+- Searches embeddings for relevant chunks
+- Adds chunks to context
+
+**Lazy Loading (our approach)**:
+- Agent requests specific code via tools
+- More precise control over what's loaded
+- Simpler implementation (no embeddings)
+- Works with any LLM (no embedding model needed)
+
+**Trade-off**: RAG might be better for semantic search ("find error handling code"), but tool-based approach gives agent explicit control.
+
+## Tech Stack
+
+### Core Dependencies
+
+| Package | Purpose | Why? |
+|---------|---------|------|
+| `ioredis` | Redis client | Most popular, excellent TypeScript support |
+| `ollama` | LLM client | Official SDK, simple API |
+| `tree-sitter` | AST parsing | Fast, error-tolerant, multi-language |
+| `tree-sitter-typescript` | TS/TSX parser | Official TypeScript grammar |
+| `tree-sitter-javascript` | JS/JSX parser | Official JavaScript grammar |
+| `ink` | Terminal UI | React for terminal, declarative |
+| `ink-text-input` | Input component | Maintained ink component |
+| `react` | UI framework | Required by Ink |
+| `simple-git` | Git operations | Simple API, well-tested |
+| `chokidar` | File watching | Cross-platform, reliable |
+| `commander` | CLI framework | Industry standard |
+| `zod` | Validation | Type-safe validation |
+| `globby` | File globbing | ESM-native, .gitignore support |
+
+### Development Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `vitest` | Testing framework |
+| `@vitest/coverage-v8` | Coverage reporting |
+| `@vitest/ui` | Interactive test UI |
+| `tsup` | TypeScript bundler |
+| `typescript` | Type checking |
+
+## Performance Considerations
+
+### 1. Indexing Performance
+
+**Problem**: Large projects (10k+ files) take time to index.
+
+**Optimizations**:
+- Incremental parsing with tree-sitter (only changed files)
+- Parallel parsing (planned for v1.1.0)
+- Ignore patterns (.gitignore, node_modules, dist)
+- Skip binary files early
+
+**Current**: ~1000 files/second on M1 Mac
+
+### 2. Memory Usage
+
+**Problem**: Entire AST in memory could be 100s of MB.
+
+**Optimizations**:
+- Store ASTs in Redis (out of Node.js heap)
+- Load ASTs on-demand from Redis
+- Lazy-load file content (not stored in session)
+
+**Current**: ~200MB for 5000 files indexed
+
+### 3. Context Window Management
+
+**Problem**: 128k token context window fills up.
+
+**Optimizations**:
+- Auto-compression at 80% usage
+- LLM summarizes old messages
+- Remove tool results older than 5 messages
+- Only load structure + metadata initially (~10k tokens)
+
+### 4. Redis Performance
+
+**Problem**: Redis is single-threaded.
+
+**Optimizations**:
+- Pipeline commands where possible
+- Use hashes for related data (fewer keys)
+- AOF every second (not every command)
+- Keep undo stack limited (10 entries)
+
+**Current**: <1ms latency for most operations
+
+### 5. Tool Execution
+
+**Problem**: Tool execution could block LLM.
+
+**Current**: Synchronous execution (simpler)
+
+**Future**: Async tool execution with progress callbacks (v1.1.0)
+
+## Future Improvements
+
+### v1.1.0 - Performance
+- Parallel AST parsing
+- Incremental indexing (only changed files)
+- Response caching
+- Stream LLM responses
+
+### v1.2.0 - Features
+- Multiple file edits in one operation
+- Batch operations
+- Custom prompt templates
+- OpenAI/Anthropic provider support
+
+### v1.3.0 - Extensibility
+- Plugin system for custom tools
+- LSP integration
+- Multi-language support (Python, Go, Rust)
+- Custom indexing rules
+
+---
+
+**Last Updated**: 2025-12-01
+**Version**: 0.16.0

packages/ipuaro/README.md

@@ -7,9 +7,9 @@
 [![npm version](https://badge.fury.io/js/@samiyev%2Fipuaro.svg)](https://www.npmjs.com/package/@samiyev/ipuaro)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Status:** 🚧 Early Development (v0.1.0 Foundation)
+> **Status:** 🎉 Release Candidate (v0.16.0 → v1.0.0)
 >
-> Core infrastructure is ready. Active development in progress.
+> All core features complete. Production-ready release coming soon.
 
 ## Vision
 
@@ -19,18 +19,20 @@ Work with codebases of any size using local AI:
 - 🔒 **100% Local**: Your code never leaves your machine
 - ⚡ **Fast**: Redis persistence + tree-sitter parsing
 
-## Planned Features
+## Features
 
-### 18 LLM Tools
+### 18 LLM Tools (All Implemented ✅)
 
-| Category | Tools | Status |
-|----------|-------|--------|
-| **Read** | `get_lines`, `get_function`, `get_class`, `get_structure` | 🔜 v0.5.0 |
-| **Edit** | `edit_lines`, `create_file`, `delete_file` | 🔜 v0.6.0 |
-| **Search** | `find_references`, `find_definition` | 🔜 v0.7.0 |
-| **Analysis** | `get_dependencies`, `get_dependents`, `get_complexity`, `get_todos` | 🔜 v0.8.0 |
-| **Git** | `git_status`, `git_diff`, `git_commit` | 🔜 v0.9.0 |
-| **Run** | `run_command`, `run_tests` | 🔜 v0.9.0 |
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Read** | `get_lines`, `get_function`, `get_class`, `get_structure` | Read code without loading everything into context |
+| **Edit** | `edit_lines`, `create_file`, `delete_file` | Make changes with confirmation and undo support |
+| **Search** | `find_references`, `find_definition` | Find symbol definitions and usages across codebase |
+| **Analysis** | `get_dependencies`, `get_dependents`, `get_complexity`, `get_todos` | Analyze code structure, complexity, and TODOs |
+| **Git** | `git_status`, `git_diff`, `git_commit` | Git operations with safety checks |
+| **Run** | `run_command`, `run_tests` | Execute commands and tests with security validation |
+
+See [Tools Documentation](#tools-reference) below for detailed usage examples.
 
 ### Terminal UI
 
@@ -54,6 +56,31 @@ Work with codebases of any size using local AI:
 └───────────────────────────────────────────────────────────┘
 ```
 
+### Slash Commands
+
+Control your session with built-in commands:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all commands and hotkeys |
+| `/clear` | Clear chat history (keeps session) |
+| `/undo` | Revert last file change from undo stack |
+| `/sessions [list\|load\|delete] [id]` | Manage sessions |
+| `/status` | Show system status (LLM, context, stats) |
+| `/reindex` | Force full project reindexation |
+| `/eval` | LLM self-check for hallucinations |
+| `/auto-apply [on\|off]` | Toggle auto-apply mode for edits |
+
+### Hotkeys
+
+| Hotkey | Action |
+|--------|--------|
+| `Ctrl+C` | Interrupt generation (1st press) / Exit (2nd press within 1s) |
+| `Ctrl+D` | Exit and save session |
+| `Ctrl+Z` | Undo last file change |
+| `↑` / `↓` | Navigate input history |
+| `Tab` | Path autocomplete (coming soon) |
+
 ### Key Capabilities
 
 🔍 **Smart Code Understanding**
@@ -124,6 +151,23 @@ ipuaro --model qwen2.5-coder:32b-instruct
 ipuaro --auto-apply
 ```
 
+## Quick Start
+
+Try ipuaro with our demo project:
+
+```bash
+# Navigate to demo project
+cd examples/demo-project
+
+# Install dependencies
+npm install
+
+# Start ipuaro
+npx @samiyev/ipuaro
+```
+
+See [examples/demo-project](./examples/demo-project) for detailed usage guide and example conversations.
+
 ## Commands
 
 | Command | Description |
@@ -181,49 +225,263 @@ Clean Architecture with clear separation:
 
 ## Development Status
 
-### ✅ Completed (v0.1.0)
+### ✅ Completed (v0.1.0 - v0.16.0)
 
-- [x] Project setup (tsup, vitest, ESM)
-- [x] Domain entities (Session, Project)
-- [x] Value objects (FileData, FileAST, ChatMessage, etc.)
-- [x] Service interfaces (IStorage, ILLMClient, ITool, IIndexer)
-- [x] Shared module (Config, Errors, Utils)
-- [x] CLI placeholder commands
-- [x] 91 unit tests, 100% coverage
+- [x] **v0.1.0 - v0.4.0**: Foundation (domain, storage, indexer, LLM integration)
+- [x] **v0.5.0 - v0.9.0**: All 18 tools implemented
+- [x] **v0.10.0**: Session management with undo support
+- [x] **v0.11.0 - v0.12.0**: Full TUI with all components
+- [x] **v0.13.0**: Security (PathValidator, command validation)
+- [x] **v0.14.0**: 8 slash commands
+- [x] **v0.15.0**: CLI entry point with onboarding
+- [x] **v0.16.0**: Comprehensive error handling system
+- [x] **1420 tests, 98% coverage**
 
-### 🔜 Next Up
+### 🔜 v1.0.0 - Production Ready
 
-- [ ] **v0.2.0** - Redis Storage
-- [ ] **v0.3.0** - Indexer (file scanning, AST parsing)
-- [ ] **v0.4.0** - LLM Integration (Ollama)
-- [ ] **v0.5.0-0.9.0** - Tools implementation
-- [ ] **v0.10.0** - Session management
-- [ ] **v0.11.0** - TUI
+- [ ] Performance optimizations
+- [ ] Complete documentation
+- [ ] Working examples
 
-See [ROADMAP.md](./ROADMAP.md) for detailed development plan.
+See [ROADMAP.md](./ROADMAP.md) for detailed development plan and [CHANGELOG.md](./CHANGELOG.md) for release history.
 
-## API (Coming Soon)
+## Tools Reference
+
+The AI agent has access to 18 tools for working with your codebase. Here are the most commonly used ones:
+
+### Read Tools
+
+**`get_lines(path, start?, end?)`**
+Read specific lines from a file.
+
+```
+You: Show me the authentication logic
+Assistant: [get_lines src/auth/service.ts 45 67]
+# Returns lines 45-67 with line numbers
+```
+
+**`get_function(path, name)`**
+Get a specific function's source code and metadata.
+
+```
+You: How does the login function work?
+Assistant: [get_function src/auth/service.ts login]
+# Returns function code, params, return type, and metadata
+```
+
+**`get_class(path, name)`**
+Get a specific class's source code and metadata.
+
+```
+You: Show me the UserService class
+Assistant: [get_class src/services/user.ts UserService]
+# Returns class code, methods, properties, and inheritance info
+```
+
+**`get_structure(path?, depth?)`**
+Get directory tree structure.
+
+```
+You: What's in the src/auth directory?
+Assistant: [get_structure src/auth]
+# Returns ASCII tree with files and folders
+```
+
+### Edit Tools
+
+**`edit_lines(path, start, end, content)`**
+Replace lines in a file (requires confirmation).
+
+```
+You: Update the timeout to 5000ms
+Assistant: [edit_lines src/config.ts 23 23 "  timeout: 5000,"]
+# Shows diff, asks for confirmation
+```
+
+**`create_file(path, content)`**
+Create a new file (requires confirmation).
+
+```
+You: Create a new utility for date formatting
+Assistant: [create_file src/utils/date.ts "export function formatDate..."]
+# Creates file after confirmation
+```
+
+**`delete_file(path)`**
+Delete a file (requires confirmation).
+
+```
+You: Remove the old test file
+Assistant: [delete_file tests/old-test.test.ts]
+# Deletes after confirmation
+```
+
+### Search Tools
+
+**`find_references(symbol, path?)`**
+Find all usages of a symbol across the codebase.
+
+```
+You: Where is getUserById used?
+Assistant: [find_references getUserById]
+# Returns all files/lines where it's called
+```
+
+**`find_definition(symbol)`**
+Find where a symbol is defined.
+
+```
+You: Where is ApiClient defined?
+Assistant: [find_definition ApiClient]
+# Returns file, line, and context
+```
+
+### Analysis Tools
+
+**`get_dependencies(path)`**
+Get files that a specific file imports.
+
+```
+You: What does auth.ts depend on?
+Assistant: [get_dependencies src/auth/service.ts]
+# Returns list of imported files
+```
+
+**`get_dependents(path)`**
+Get files that import a specific file.
+
+```
+You: What files use the database module?
+Assistant: [get_dependents src/db/index.ts]
+# Returns list of files importing this
+```
+
+**`get_complexity(path?, limit?)`**
+Get complexity metrics for files.
+
+```
+You: Which files are most complex?
+Assistant: [get_complexity null 10]
+# Returns top 10 most complex files with metrics
+```
+
+**`get_todos(path?, type?)`**
+Find TODO/FIXME/HACK comments.
+
+```
+You: What TODOs are there?
+Assistant: [get_todos]
+# Returns all TODO comments with locations
+```
+
+### Git Tools
+
+**`git_status()`**
+Get current git repository status.
+
+```
+You: What files have changed?
+Assistant: [git_status]
+# Returns branch, staged, modified, untracked files
+```
+
+**`git_diff(path?, staged?)`**
+Get uncommitted changes.
+
+```
+You: Show me what changed in auth.ts
+Assistant: [git_diff src/auth/service.ts]
+# Returns diff output
+```
+
+**`git_commit(message, files?)`**
+Create a git commit (requires confirmation).
+
+```
+You: Commit these auth changes
+Assistant: [git_commit "feat: add password reset flow" ["src/auth/service.ts"]]
+# Creates commit after confirmation
+```
+
+### Run Tools
+
+**`run_command(command, timeout?)`**
+Execute shell commands (with security validation).
+
+```
+You: Run the build
+Assistant: [run_command "npm run build"]
+# Checks security, then executes
+```
+
+**`run_tests(path?, filter?, watch?)`**
+Run project tests.
+
+```
+You: Test the auth module
+Assistant: [run_tests "tests/auth" null false]
+# Auto-detects test runner and executes
+```
+
+For complete tool documentation with all parameters and options, see [TOOLS.md](./TOOLS.md).
+
+## Programmatic API
+
+You can use ipuaro as a library in your own Node.js applications:
 
 ```typescript
-import { startSession, handleMessage } from "@samiyev/ipuaro"
+import {
+    createRedisClient,
+    RedisStorage,
+    OllamaClient,
+    ToolRegistry,
+    StartSession,
+    HandleMessage
+} from "@samiyev/ipuaro"
+
+// Initialize dependencies
+const redis = await createRedisClient({ host: "localhost", port: 6379 })
+const storage = new RedisStorage(redis, "my-project")
+const llm = new OllamaClient({
+    model: "qwen2.5-coder:7b-instruct",
+    contextWindow: 128000,
+    temperature: 0.1
+})
+const tools = new ToolRegistry()
+
+// Register tools
+tools.register(new GetLinesTool(storage, "/path/to/project"))
+// ... register other tools
 
 // Start a session
-const session = await startSession({
-    projectPath: "./my-project",
-    model: "qwen2.5-coder:7b-instruct"
-})
+const startSession = new StartSession(storage)
+const session = await startSession.execute("my-project")
 
-// Send a message
-const response = await handleMessage(session, "Explain the auth flow")
+// Handle a message
+const handleMessage = new HandleMessage(storage, llm, tools)
+await handleMessage.execute(session, "Show me the auth flow")
 
-console.log(response.content)
-console.log(`Tokens: ${response.stats.tokens}`)
-console.log(`Tool calls: ${response.stats.toolCalls}`)
+// Session is automatically updated in Redis
 ```
 
+For full API documentation, see the TypeScript definitions in `src/` or explore the [source code](./src/).
+
 ## How It Works
 
-### Lazy Loading Context
+### 1. Project Indexing
+
+When you start ipuaro, it scans your project and builds an index:
+
+```
+1. File Scanner → Recursively scans files (.ts, .js, .tsx, .jsx)
+2. AST Parser → Parses with tree-sitter (extracts functions, classes, imports)
+3. Meta Analyzer → Calculates complexity, dependencies, hub detection
+4. Index Builder → Creates symbol index and dependency graph
+5. Redis Storage → Persists everything for instant startup next time
+6. Watchdog → Watches files for changes and updates index in background
+```
+
+### 2. Lazy Loading Context
 
 Instead of loading entire codebase into context:
 
@@ -232,24 +490,161 @@ Traditional approach:
 ├── Load all files → 500k tokens → ❌ Exceeds context window
 
 ipuaro approach:
-├── Load project structure → 2k tokens
-├── Load AST metadata → 10k tokens
-├── On demand: get_function("auth.ts", "login") → 200 tokens
-├── Total: ~12k tokens → ✅ Fits in context
+├── Load project structure → ~2k tokens
+├── Load AST metadata → ~10k tokens
+├── On demand: get_function("auth.ts", "login") → ~200 tokens
+├── Total: ~12k tokens → ✅ Fits in 128k context window
 ```
 
-### Tool-Based Code Access
+Context automatically compresses when usage exceeds 80% by summarizing old messages.
+
+### 3. Tool-Based Code Access
+
+The LLM doesn't see your code initially. It only sees structure and metadata. When it needs code, it uses tools:
 
 ```
-User: "How does user creation work?"
+You: "How does user creation work?"
 
-ipuaro:
-1. [get_structure src/] → sees user/ folder
-2. [get_function src/user/service.ts createUser] → gets function code
+Agent reasoning:
+1. [get_structure src/] → sees user/ folder exists
+2. [get_function src/user/service.ts createUser] → loads specific function
 3. [find_references createUser] → finds all usages
-4. Synthesizes answer with specific code context
+4. Synthesizes answer with only relevant code loaded
+
+Total tokens used: ~2k (vs loading entire src/ which could be 50k+)
 ```
 
+### 4. Session Persistence
+
+Everything is saved to Redis:
+- Chat history and context state
+- Undo stack (last 10 file changes)
+- Session metadata and statistics
+
+Resume your session anytime with `/sessions load <id>`.
+
+### 5. Security Model
+
+Three-layer security:
+1. **Blacklist**: Dangerous commands always blocked (rm -rf, sudo, etc.)
+2. **Whitelist**: Safe commands auto-approved (npm, git status, etc.)
+3. **Confirmation**: Unknown commands require user approval
+
+File operations are restricted to project directory only (path traversal prevention).
+
+## Troubleshooting
+
+### Redis Connection Errors
+
+**Error**: `Redis connection failed`
+
+**Solutions**:
+```bash
+# Check if Redis is running
+redis-cli ping  # Should return "PONG"
+
+# Start Redis with AOF persistence
+redis-server --appendonly yes
+
+# Check Redis logs
+tail -f /usr/local/var/log/redis.log  # macOS
+```
+
+### Ollama Model Not Found
+
+**Error**: `Model qwen2.5-coder:7b-instruct not found`
+
+**Solutions**:
+```bash
+# Pull the model
+ollama pull qwen2.5-coder:7b-instruct
+
+# List installed models
+ollama list
+
+# Check Ollama is running
+ollama serve
+```
+
+### Large Project Performance
+
+**Issue**: Indexing takes too long or uses too much memory
+
+**Solutions**:
+```bash
+# Index only a subdirectory
+ipuaro ./src
+
+# Add more ignore patterns to .ipuaro.json
+{
+    "project": {
+        "ignorePatterns": ["node_modules", "dist", ".git", "coverage", "build"]
+    }
+}
+
+# Increase Node.js memory limit
+NODE_OPTIONS="--max-old-space-size=4096" ipuaro
+```
+
+### Context Window Exceeded
+
+**Issue**: `Context window exceeded` errors
+
+**Solutions**:
+- Context auto-compresses at 80%, but you can manually `/clear` history
+- Use more targeted questions instead of asking about entire codebase
+- The agent will automatically use tools to load only what's needed
+
+### File Changes Not Detected
+
+**Issue**: Made changes but agent doesn't see them
+
+**Solutions**:
+```bash
+# Force reindex
+/reindex
+
+# Or restart with fresh index
+rm -rf ~/.ipuaro/cache
+ipuaro
+```
+
+### Undo Not Working
+
+**Issue**: `/undo` says no changes to undo
+
+**Explanation**: Undo stack only tracks the last 10 file edits made through ipuaro. Manual file edits outside ipuaro cannot be undone.
+
+## FAQ
+
+**Q: Does ipuaro send my code to any external servers?**
+
+A: No. Everything runs locally. Ollama runs on your machine, Redis stores data locally, and no network requests are made except to your local Ollama instance.
+
+**Q: What languages are supported?**
+
+A: Currently TypeScript, JavaScript (including TSX/JSX). More languages planned for future versions.
+
+**Q: Can I use OpenAI/Anthropic/other LLM providers?**
+
+A: Currently only Ollama is supported. OpenAI/Anthropic support is planned for v1.2.0.
+
+**Q: How much disk space does Redis use?**
+
+A: Depends on project size. A typical mid-size project (1000 files) uses ~50-100MB. Redis uses AOF persistence, so data survives restarts.
+
+**Q: Can I use ipuaro in a CI/CD pipeline?**
+
+A: Yes, but it's designed for interactive use. For automated code analysis, consider the programmatic API.
+
+**Q: What's the difference between ipuaro and GitHub Copilot?**
+
+A: Copilot is an autocomplete tool. ipuaro is a conversational agent that can read, analyze, modify files, run commands, and has full codebase understanding through AST parsing.
+
+**Q: Why Redis instead of SQLite or JSON files?**
+
+A: Redis provides fast in-memory access, AOF persistence, and handles concurrent access well. The session model fits Redis's data structures perfectly.
+
 ## Contributing
 
 Contributions welcome! This project is in early development.

packages/ipuaro/ROADMAP.md

@@ -148,9 +148,10 @@ packages/ipuaro/
 
 ---
 
-## Version 0.1.0 - Foundation ⚙️
+## Version 0.1.0 - Foundation ⚙️ ✅
 
 **Priority:** CRITICAL
+**Status:** Complete (v0.1.0 released)
 
 ### 0.1.1 - Project Setup
 
@@ -310,9 +311,10 @@ interface Config {
 
 ---
 
-## Version 0.2.0 - Redis Storage 🗄️
+## Version 0.2.0 - Redis Storage 🗄️ ✅
 
 **Priority:** CRITICAL
+**Status:** Complete (v0.2.0 released)
 
 ### 0.2.1 - Redis Client
 
@@ -367,9 +369,10 @@ class RedisStorage implements IStorage {
 
 ---
 
-## Version 0.3.0 - Indexer 📂
+## Version 0.3.0 - Indexer 📂 ✅
 
 **Priority:** CRITICAL
+**Status:** Complete (v0.3.0, v0.3.1 released)
 
 ### 0.3.1 - File Scanner
 
@@ -456,9 +459,10 @@ class Watchdog {
 
 ---
 
-## Version 0.4.0 - LLM Integration 🤖
+## Version 0.4.0 - LLM Integration 🤖 ✅
 
 **Priority:** CRITICAL
+**Status:** Complete (v0.4.0 released)
 
 ### 0.4.1 - Ollama Client
 
@@ -531,9 +535,10 @@ function parseToolCalls(response: string): ToolCall[]
 
 ---
 
-## Version 0.5.0 - Read Tools 📖
+## Version 0.5.0 - Read Tools 📖 ✅
 
 **Priority:** HIGH
+**Status:** Complete (v0.5.0 released)
 
 4 tools for reading code without modification.
 
@@ -609,9 +614,10 @@ class GetStructureTool implements ITool {
 
 ---
 
-## Version 0.6.0 - Edit Tools ✏️
+## Version 0.6.0 - Edit Tools ✏️ ✅
 
 **Priority:** HIGH
+**Status:** Complete (v0.6.0 released)
 
 3 tools for file modifications. All require confirmation (unless autoApply).
 
@@ -662,9 +668,10 @@ class DeleteFileTool implements ITool {
 
 ---
 
-## Version 0.7.0 - Search Tools 🔍
+## Version 0.7.0 - Search Tools 🔍 ✅
 
 **Priority:** HIGH
+**Status:** Complete (v0.7.0 released)
 
 ### 0.7.1 - find_references
 
@@ -699,9 +706,10 @@ class FindDefinitionTool implements ITool {
 
 ---
 
-## Version 0.8.0 - Analysis Tools 📊
+## Version 0.8.0 - Analysis Tools 📊 ✅
 
 **Priority:** MEDIUM
+**Status:** Complete (v0.8.0 released)
 
 ### 0.8.1 - get_dependencies
 
@@ -742,9 +750,10 @@ class FindDefinitionTool implements ITool {
 
 ---
 
-## Version 0.9.0 - Git & Run Tools 🚀
+## Version 0.9.0 - Git & Run Tools 🚀 ✅
 
 **Priority:** MEDIUM
+**Status:** Complete (v0.9.0 released) — includes CommandSecurity (Blacklist/Whitelist)
 
 ### 0.9.1 - git_status
 
@@ -798,9 +807,10 @@ class FindDefinitionTool implements ITool {
 
 ---
 
-## Version 0.10.0 - Session Management 💾
+## Version 0.10.0 - Session Management 💾 ✅
 
 **Priority:** HIGH
+**Status:** Complete (v0.10.0 released) — includes HandleMessage orchestrator (originally planned for 0.14.0)
 
 ### 0.10.1 - Session Entity
 
@@ -873,9 +883,10 @@ class ContextManager {
 
 ---
 
-## Version 0.11.0 - TUI Basic 🖥️
+## Version 0.11.0 - TUI Basic 🖥️ ✅
 
 **Priority:** CRITICAL
+**Status:** Complete (v0.11.0 released) — includes useHotkeys (originally planned for 0.16.0)
 
 ### 0.11.1 - App Shell
 
@@ -945,9 +956,10 @@ interface Props {
 
 ---
 
-## Version 0.12.0 - TUI Advanced 🎨
+## Version 0.12.0 - TUI Advanced 🎨 ✅
 
 **Priority:** HIGH
+**Status:** Complete (v0.12.0 released)
 
 ### 0.12.1 - DiffView
 
@@ -1009,9 +1021,10 @@ interface Props {
 
 ---
 
-## Version 0.13.0 - Security 🔒
+## Version 0.13.0 - Security 🔒 ✅
 
 **Priority:** HIGH
+**Status:** Complete (v0.13.0 released) — Blacklist/Whitelist done in v0.9.0, PathValidator in v0.13.0
 
 ### 0.13.1 - Blacklist
 
@@ -1055,11 +1068,14 @@ function validatePath(path: string, projectRoot: string): boolean
 
 ---
 
-## Version 0.14.0 - Orchestrator 🎭
+## [DONE] Original 0.14.0 - Orchestrator 🎭 ✅
 
-**Priority:** CRITICAL
+> **Note:** This was implemented in v0.10.0 as part of Session Management
 
-### 0.14.1 - HandleMessage Use Case
+<details>
+<summary>Originally planned (click to expand)</summary>
+
+### HandleMessage Use Case (Done in v0.10.5)
 
 ```typescript
 // src/application/use-cases/HandleMessage.ts
@@ -1091,7 +1107,7 @@ class HandleMessage {
 }
 ```
 
-### 0.14.2 - Edit Flow
+### Edit Flow (Done in v0.10.5)
 
 ```typescript
 // Edit handling inside HandleMessage:
@@ -1104,17 +1120,49 @@ class HandleMessage {
 //    - Update storage (lines, AST, meta)
 ```
 
-**Tests:**
-- [ ] Unit tests for HandleMessage
-- [ ] E2E tests for full message flow
+</details>
 
 ---
 
-## Version 0.15.0 - Commands 📝
+## [DONE] Original 0.16.0 - Hotkeys & Polish ⌨️ ✅
 
-**Priority:** MEDIUM
+> **Note:** useHotkeys done in v0.11.0, ContextManager auto-compression in v0.10.3
 
-7 slash commands for TUI.
+<details>
+<summary>Originally planned (click to expand)</summary>
+
+### Hotkeys (Done in v0.11.0)
+
+```typescript
+// src/tui/hooks/useHotkeys.ts
+
+Ctrl+C  // Interrupt generation (1st), exit (2nd)
+Ctrl+D  // Exit with session save
+Ctrl+Z  // Undo (= /undo)
+↑/↓     // Input history
+Tab     // Path autocomplete
+```
+
+### Auto-compression (Done in v0.10.3)
+
+```typescript
+// Triggered at >80% context:
+// 1. LLM summarizes old messages
+// 2. Remove tool results older than 5 messages
+// 3. Update status bar (ctx% changes)
+// No modal notification - silent
+```
+
+</details>
+
+---
+
+## Version 0.14.0 - Commands 📝 ✅
+
+**Priority:** HIGH
+**Status:** Complete (v0.14.0 released)
+
+8 slash commands for TUI.
 
 ```typescript
 // src/tui/hooks/useCommands.ts
@@ -1130,47 +1178,16 @@ class HandleMessage {
 ```
 
 **Tests:**
-- [ ] Unit tests for command handlers
+- [x] Unit tests for command handlers (38 tests)
 
 ---
 
-## Version 0.16.0 - Hotkeys & Polish ⌨️
-
-**Priority:** MEDIUM
-
-### 0.16.1 - Hotkeys
-
-```typescript
-// src/tui/hooks/useHotkeys.ts
-
-Ctrl+C  // Interrupt generation (1st), exit (2nd)
-Ctrl+D  // Exit with session save
-Ctrl+Z  // Undo (= /undo)
-↑/↓     // Input history
-Tab     // Path autocomplete
-```
-
-### 0.16.2 - Auto-compression
-
-```typescript
-// Triggered at >80% context:
-// 1. LLM summarizes old messages
-// 2. Remove tool results older than 5 messages
-// 3. Update status bar (ctx% changes)
-// No modal notification - silent
-```
-
-**Tests:**
-- [ ] Integration tests for hotkeys
-- [ ] Unit tests for compression
-
----
-
-## Version 0.17.0 - CLI Entry Point 🚪
+## Version 0.15.0 - CLI Entry Point 🚪 ✅
 
 **Priority:** HIGH
+**Status:** Complete (v0.15.0 released)
 
-### 0.17.1 - CLI Commands
+### 0.15.1 - CLI Commands
 
 ```typescript
 // src/cli/index.ts
@@ -1180,7 +1197,7 @@ ipuaro init             // Create .ipuaro.json config
 ipuaro index            // Index only (no TUI)
 ```
 
-### 0.17.2 - CLI Options
+### 0.15.2 - CLI Options
 
 ```bash
 --auto-apply            # Enable auto-apply mode
@@ -1189,7 +1206,7 @@ ipuaro index            // Index only (no TUI)
 --version               # Show version
 ```
 
-### 0.17.3 - Onboarding
+### 0.15.3 - Onboarding
 
 ```typescript
 // src/cli/commands/start.ts
@@ -1202,40 +1219,576 @@ ipuaro index            // Index only (no TUI)
 ```
 
 **Tests:**
-- [ ] E2E tests for CLI
+- [x] Unit tests for CLI commands (29 tests)
 
 ---
 
-## Version 0.18.0 - Error Handling ⚠️
+## Version 0.16.0 - Error Handling ⚠️ ✅
 
 **Priority:** HIGH
+**Status:** Complete (v0.16.0 released)
 
-### 0.18.1 - Error Types
+### 0.16.1 - Error Types ✅
 
 ```typescript
 // src/shared/errors/IpuaroError.ts
-type ErrorType = "redis" | "parse" | "llm" | "file" | "command" | "conflict"
+type ErrorType = "redis" | "parse" | "llm" | "file" | "command" | "conflict" | "validation" | "timeout" | "unknown"
+type ErrorOption = "retry" | "skip" | "abort" | "confirm" | "regenerate"
+
+interface ErrorMeta {
+    type: ErrorType
+    recoverable: boolean
+    options: ErrorOption[]
+    defaultOption: ErrorOption
+}
 
 class IpuaroError extends Error {
     type: ErrorType
     recoverable: boolean
     suggestion?: string
+    options: ErrorOption[]
+    defaultOption: ErrorOption
+    context?: Record<string, unknown>
+
+    getMeta(): ErrorMeta
+    hasOption(option: ErrorOption): boolean
+    toDisplayString(): string
 }
 ```
 
-### 0.18.2 - Error Handling Matrix
+### 0.16.2 - Error Handling Matrix ✅
 
-| Error | Recoverable | Options |
-|-------|-------------|---------|
-| Redis unavailable | No | Retry / Abort |
-| AST parse failed | Yes | Skip file / Abort |
-| LLM timeout | Yes | Retry / Skip / Abort |
-| File not found | Yes | Skip / Abort |
-| Command not in whitelist | Yes | Confirm / Skip / Abort |
-| Edit conflict | Yes | Apply / Skip / Regenerate |
+| Error | Recoverable | Options | Default |
+|-------|-------------|---------|---------|
+| Redis unavailable | No | Retry / Abort | Abort |
+| AST parse failed | Yes | Skip / Abort | Skip |
+| LLM timeout | Yes | Retry / Skip / Abort | Retry |
+| File not found | Yes | Skip / Abort | Skip |
+| Command not in whitelist | Yes | Confirm / Skip / Abort | Confirm |
+| Edit conflict | Yes | Skip / Regenerate / Abort | Skip |
+| Validation error | Yes | Skip / Abort | Skip |
+| Timeout | Yes | Retry / Skip / Abort | Retry |
+| Unknown | No | Abort | Abort |
+
+### 0.16.3 - ErrorHandler Service ✅
+
+```typescript
+// src/shared/errors/ErrorHandler.ts
+class ErrorHandler {
+    handle(error: IpuaroError, contextKey?: string): Promise<ErrorHandlingResult>
+    handleSync(error: IpuaroError, contextKey?: string): ErrorHandlingResult
+    wrap<T>(fn: () => Promise<T>, errorType: ErrorType, contextKey?: string): Promise<Result>
+    withRetry<T>(fn: () => Promise<T>, errorType: ErrorType, contextKey: string): Promise<T>
+    resetRetries(contextKey?: string): void
+    getRetryCount(contextKey: string): number
+    isMaxRetriesExceeded(contextKey: string): boolean
+}
+```
 
 **Tests:**
-- [ ] Unit tests for error handling
+- [x] Unit tests for IpuaroError (27 tests)
+- [x] Unit tests for ErrorHandler (32 tests)
+
+---
+
+## Version 0.17.0 - Documentation Complete 📚 ✅
+
+**Priority:** HIGH
+**Status:** Complete (v0.17.0 released)
+
+### Documentation
+
+- [x] README.md comprehensive update with all features
+- [x] ARCHITECTURE.md explaining design and decisions
+- [x] TOOLS.md complete reference for all 18 tools
+- [x] Troubleshooting guide
+- [x] FAQ section
+- [x] API examples
+- [x] ~2500 lines of documentation added
+
+---
+
+## Version 0.18.0 - Working Examples 📦 ✅
+
+**Priority:** HIGH
+**Status:** Complete (v0.18.0 released)
+
+### Examples
+
+- [x] Demo project with TypeScript application (336 LOC)
+- [x] User management service (UserService)
+- [x] Authentication service (AuthService)
+- [x] Utilities (Logger, Validation)
+- [x] Unit tests (Vitest)
+- [x] Configuration files (package.json, tsconfig.json, .ipuaro.json)
+- [x] Comprehensive README with 35+ example queries
+- [x] Workflow scenarios (bug fix, refactoring, code review)
+- [x] Demonstrates all 18 tools
+- [x] 15 files, 977 total lines
+
+---
+
+## Version 0.19.0 - XML Tool Format Refactor 🔄 ✅
+
+**Priority:** HIGH
+**Status:** Complete (v0.19.0 released)
+
+Рефакторинг: переход на чистый XML формат для tool calls (как в CONCEPT.md).
+
+### Текущая проблема
+
+OllamaClient использует Ollama native tool calling (JSON Schema), а ResponseParser реализует XML парсинг. Это создаёт путаницу и не соответствует CONCEPT.md.
+
+### 0.19.1 - OllamaClient Refactor
+
+```typescript
+// src/infrastructure/llm/OllamaClient.ts
+
+// БЫЛО:
+// - Передаём tools в Ollama SDK format
+// - Извлекаем tool_calls из response.message.tool_calls
+
+// СТАНЕТ:
+// - НЕ передаём tools в SDK
+// - Tools описаны в system prompt как XML
+// - LLM возвращает XML в content
+// - Парсим через ResponseParser
+```
+
+**Изменения:**
+- [x] Удалить `convertTools()` метод
+- [x] Удалить `extractToolCalls()` метод
+- [x] Убрать передачу `tools` в `client.chat()`
+- [x] Возвращать только `content` без `toolCalls`
+
+### 0.19.2 - System Prompt Update
+
+```typescript
+// src/infrastructure/llm/prompts.ts
+
+// Добавить в SYSTEM_PROMPT полное описание XML формата:
+
+const TOOL_FORMAT_INSTRUCTIONS = `
+## Tool Calling Format
+
+When you need to use a tool, format your call as XML:
+
+<tool_call name="tool_name">
+  <param_name>value</param_name>
+  <another_param>value</another_param>
+</tool_call>
+
+Examples:
+<tool_call name="get_lines">
+  <path>src/index.ts</path>
+  <start>1</start>
+  <end>50</end>
+</tool_call>
+
+<tool_call name="edit_lines">
+  <path>src/utils.ts</path>
+  <start>10</start>
+  <end>15</end>
+  <content>const newCode = "hello";</content>
+</tool_call>
+
+You can use multiple tool calls in one response.
+Always wait for tool results before making conclusions.
+`
+```
+
+**Изменения:**
+- [x] Добавить `TOOL_FORMAT_INSTRUCTIONS` в prompts.ts
+- [x] Включить в `SYSTEM_PROMPT`
+- [x] Добавить примеры для всех 18 tools
+
+### 0.19.3 - HandleMessage Simplification
+
+```typescript
+// src/application/use-cases/HandleMessage.ts
+
+// БЫЛО:
+// const response = await this.llm.chat(messages)
+// const parsed = parseToolCalls(response.content)
+
+// СТАНЕТ:
+// const response = await this.llm.chat(messages)  // без tools
+// const parsed = parseToolCalls(response.content) // единственный источник
+```
+
+**Изменения:**
+- [x] Убрать передачу tool definitions в `llm.chat()`
+- [x] ResponseParser — единственный источник tool calls
+- [x] Упростить логику обработки
+
+### 0.19.4 - ILLMClient Interface Update
+
+```typescript
+// src/domain/services/ILLMClient.ts
+
+// БЫЛО:
+interface ILLMClient {
+    chat(messages: ChatMessage[], tools?: ToolDef[]): Promise<LLMResponse>
+}
+
+// СТАНЕТ:
+interface ILLMClient {
+    chat(messages: ChatMessage[]): Promise<LLMResponse>
+    // tools больше не передаются - они в system prompt
+}
+```
+
+**Изменения:**
+- [x] Убрать `tools` параметр из `chat()`
+- [x] Убрать `toolCalls` из `LLMResponse` (парсятся из content)
+- [x] Обновить все реализации
+
+### 0.19.5 - ResponseParser Enhancements
+
+```typescript
+// src/infrastructure/llm/ResponseParser.ts
+
+// Улучшения:
+// - Лучшая обработка ошибок парсинга
+// - Поддержка CDATA для многострочного content
+// - Валидация имён tools
+```
+
+**Изменения:**
+- [x] Добавить поддержку `<![CDATA[...]]>` для content
+- [x] Валидация: tool name должен быть из известного списка
+- [x] Улучшить сообщения об ошибках парсинга
+
+**Tests:**
+- [x] Обновить тесты OllamaClient
+- [x] Обновить тесты HandleMessage
+- [x] Добавить тесты ResponseParser для edge cases
+- [ ] E2E тест полного flow с XML (опционально, может быть в 0.20.0)
+
+---
+
+## Version 0.20.0 - Missing Use Cases 🔧
+
+**Priority:** HIGH
+**Status:** Pending
+
+### 0.20.1 - IndexProject Use Case
+
+```typescript
+// src/application/use-cases/IndexProject.ts
+class IndexProject {
+    constructor(
+        private storage: IStorage,
+        private indexer: IIndexer
+    )
+
+    async execute(
+        projectRoot: string,
+        onProgress?: (progress: IndexProgress) => void
+    ): Promise<IndexingStats>
+    // Full indexing pipeline:
+    // 1. Scan files
+    // 2. Parse AST
+    // 3. Analyze metadata
+    // 4. Build indexes
+    // 5. Store in Redis
+}
+```
+
+**Deliverables:**
+- [ ] IndexProject use case implementation
+- [ ] Integration with CLI `index` command
+- [ ] Integration with `/reindex` slash command
+- [ ] Progress reporting via callback
+- [ ] Unit tests
+
+### 0.20.2 - ExecuteTool Use Case
+
+```typescript
+// src/application/use-cases/ExecuteTool.ts
+class ExecuteTool {
+    constructor(
+        private tools: IToolRegistry,
+        private storage: IStorage
+    )
+
+    async execute(
+        toolName: string,
+        params: Record<string, unknown>,
+        context: ToolContext
+    ): Promise<ToolResult>
+    // Orchestrates tool execution with:
+    // - Parameter validation
+    // - Confirmation flow
+    // - Undo stack management
+    // - Storage updates
+}
+```
+
+**Deliverables:**
+- [ ] ExecuteTool use case implementation
+- [ ] Refactor HandleMessage to use ExecuteTool
+- [ ] Unit tests
+
+**Tests:**
+- [ ] Unit tests for IndexProject
+- [ ] Unit tests for ExecuteTool
+
+---
+
+## Version 0.21.0 - TUI Enhancements 🎨
+
+**Priority:** MEDIUM
+**Status:** In Progress (2/4 complete)
+
+### 0.21.1 - useAutocomplete Hook ✅
+
+```typescript
+// src/tui/hooks/useAutocomplete.ts
+function useAutocomplete(options: {
+    storage: IStorage
+    projectRoot: string
+    enabled?: boolean
+    maxSuggestions?: number
+}): {
+    suggestions: string[]
+    complete: (partial: string) => string[]
+    accept: (suggestion: string) => string
+    reset: () => void
+}
+
+// Tab autocomplete for file paths
+// Sources: Redis file index
+// Fuzzy matching with scoring algorithm
+```
+
+**Deliverables:**
+- [x] useAutocomplete hook implementation
+- [x] Integration with Input component (Tab key)
+- [x] Path completion from Redis index
+- [x] Fuzzy matching support
+- [x] Unit tests (21 tests)
+- [x] Visual feedback in Input component
+- [x] Real-time suggestion updates
+
+### 0.21.2 - Edit Mode in ConfirmDialog ✅
+
+```typescript
+// Enhanced ConfirmDialog with edit mode
+// When user presses [E]:
+// 1. Show editable text area with proposed changes
+// 2. User modifies the content
+// 3. Apply modified version
+
+interface ConfirmDialogProps {
+    message: string
+    diff?: DiffViewProps
+    onSelect: (choice: ConfirmChoice, editedContent?: string[]) => void
+    editableContent?: string[]
+}
+```
+
+**Deliverables:**
+- [x] EditableContent component for inline editing
+- [x] Integration with ConfirmDialog [E] option
+- [x] Handler in App.tsx for edit choice
+- [x] ExecuteTool support for edited content
+- [x] ConfirmationResult type with editedContent field
+- [x] All existing tests passing (1484 tests)
+
+### 0.21.3 - Multiline Input
+
+```typescript
+// src/tui/components/Input.tsx enhancements
+interface InputProps {
+    // ... existing props
+    multiline?: boolean | "auto"  // auto = detect based on content
+}
+
+// Shift+Enter for new line
+// Auto-expand height
+```
+
+**Deliverables:**
+- [ ] Multiline support in Input component
+- [ ] Shift+Enter handling
+- [ ] Auto-height adjustment
+- [ ] Config option: `input.multiline`
+- [ ] Unit tests
+
+### 0.21.4 - Syntax Highlighting in DiffView
+
+```typescript
+// src/tui/components/DiffView.tsx enhancements
+// Full syntax highlighting for code in diff
+
+interface DiffViewProps {
+    // ... existing props
+    language?: "ts" | "tsx" | "js" | "jsx"
+    syntaxHighlight?: boolean
+}
+
+// Use ink-syntax-highlight or custom tokenizer
+```
+
+**Deliverables:**
+- [ ] Syntax highlighting integration
+- [ ] Language detection from file extension
+- [ ] Config option: `edit.syntaxHighlight`
+- [ ] Unit tests
+
+**Tests:**
+- [ ] Unit tests for useAutocomplete
+- [ ] Unit tests for enhanced ConfirmDialog
+- [ ] Unit tests for multiline Input
+- [ ] Unit tests for syntax highlighting
+
+---
+
+## Version 0.22.0 - Extended Configuration ⚙️
+
+**Priority:** MEDIUM
+**Status:** Complete (5/5 complete) ✅
+
+### 0.22.1 - Display Configuration ✅
+
+```typescript
+// src/shared/constants/config.ts additions
+export const DisplayConfigSchema = z.object({
+    showStats: z.boolean().default(true),
+    showToolCalls: z.boolean().default(true),
+    theme: z.enum(["dark", "light"]).default("dark"),
+    bellOnComplete: z.boolean().default(false),
+    progressBar: z.boolean().default(true),
+})
+```
+
+**Deliverables:**
+- [x] DisplayConfigSchema in config.ts
+- [x] Bell notification on response complete
+- [x] Theme support (dark/light color schemes)
+- [x] Configurable stats display
+- [x] Unit tests (46 new tests: 20 schema, 24 theme, 2 bell)
+
+### 0.22.2 - Session Configuration ✅
+
+```typescript
+// src/shared/constants/config.ts additions
+export const SessionConfigSchema = z.object({
+    persistIndefinitely: z.boolean().default(true),
+    maxHistoryMessages: z.number().int().positive().default(100),
+    saveInputHistory: z.boolean().default(true),
+})
+```
+
+**Deliverables:**
+- [x] SessionConfigSchema in config.ts
+- [x] History truncation based on maxHistoryMessages
+- [x] Input history persistence toggle
+- [x] Unit tests (19 new tests)
+
+### 0.22.3 - Context Configuration ✅
+
+```typescript
+// src/shared/constants/config.ts additions
+export const ContextConfigSchema = z.object({
+    systemPromptTokens: z.number().int().positive().default(2000),
+    maxContextUsage: z.number().min(0).max(1).default(0.8),
+    autoCompressAt: z.number().min(0).max(1).default(0.8),
+    compressionMethod: z.enum(["llm-summary", "truncate"]).default("llm-summary"),
+})
+```
+
+**Deliverables:**
+- [x] ContextConfigSchema in config.ts
+- [x] ContextManager reads from config
+- [x] Configurable compression threshold
+- [x] Unit tests (40 new tests: 32 schema, 8 ContextManager integration)
+
+### 0.22.4 - Autocomplete Configuration ✅
+
+```typescript
+// src/shared/constants/config.ts additions
+export const AutocompleteConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    source: z.enum(["redis-index", "filesystem", "both"]).default("redis-index"),
+    maxSuggestions: z.number().int().positive().default(10),
+})
+```
+
+**Deliverables:**
+- [x] AutocompleteConfigSchema in config.ts
+- [x] useAutocomplete reads from config
+- [x] Unit tests (27 tests)
+
+### 0.22.5 - Commands Configuration ✅
+
+```typescript
+// src/shared/constants/config.ts additions
+export const CommandsConfigSchema = z.object({
+    timeout: z.number().int().positive().nullable().default(null),
+})
+```
+
+**Deliverables:**
+- [x] CommandsConfigSchema in config.ts
+- [x] Timeout support for run_command tool
+- [x] Unit tests (19 schema tests + 3 RunCommandTool integration tests)
+
+**Tests:**
+- [x] Unit tests for CommandsConfigSchema (19 tests)
+- [x] Integration tests for RunCommandTool with config (3 tests)
+
+---
+
+## Version 0.23.0 - JSON/YAML & Symlinks 📄
+
+**Priority:** LOW
+**Status:** Pending
+
+### 0.23.1 - JSON/YAML AST Parsing
+
+```typescript
+// src/infrastructure/indexer/ASTParser.ts enhancements
+type Language = "ts" | "tsx" | "js" | "jsx" | "json" | "yaml"
+
+// For JSON: extract keys, structure
+// For YAML: extract keys, structure
+// Use tree-sitter-json and tree-sitter-yaml
+```
+
+**Deliverables:**
+- [ ] Add tree-sitter-json dependency
+- [ ] Add tree-sitter-yaml dependency
+- [ ] JSON parsing in ASTParser
+- [ ] YAML parsing in ASTParser
+- [ ] Unit tests
+
+### 0.23.2 - Symlinks Metadata
+
+```typescript
+// src/domain/services/IIndexer.ts enhancements
+export interface ScanResult {
+    path: string
+    type: "file" | "directory" | "symlink"
+    size: number
+    lastModified: number
+    symlinkTarget?: string  // <-- NEW: target path for symlinks
+}
+
+// Store symlink metadata in Redis
+// project:{name}:meta includes symlink info
+```
+
+**Deliverables:**
+- [ ] Add symlinkTarget to ScanResult
+- [ ] FileScanner extracts symlink targets
+- [ ] Store symlink metadata in Redis
+- [ ] Unit tests
+
+**Tests:**
+- [ ] Unit tests for JSON/YAML parsing
+- [ ] Unit tests for symlink handling
 
 ---
 
@@ -1244,16 +1797,16 @@ class IpuaroError extends Error {
 **Target:** Stable release
 
 **Checklist:**
-- [ ] All 18 tools implemented and tested
-- [ ] TUI fully functional
-- [ ] Session persistence working
-- [ ] Error handling complete
+- [x] All 18 tools implemented and tested ✅ (v0.9.0)
+- [x] TUI fully functional ✅ (v0.11.0, v0.12.0)
+- [x] Session persistence working ✅ (v0.10.0)
+- [x] Error handling complete ✅ (v0.16.0)
 - [ ] Performance optimized
-- [ ] Documentation complete
-- [ ] 80%+ test coverage
-- [ ] 0 ESLint errors
-- [ ] Examples working
-- [ ] CHANGELOG.md up to date
+- [x] Documentation complete ✅ (v0.17.0)
+- [x] Test coverage ≥92% branches, ≥95% lines/functions/statements ✅ (92.01% branches, 97.84% lines, 99.16% functions, 97.84% statements - 1441 tests)
+- [x] 0 ESLint errors ✅
+- [x] Examples working ✅ (v0.18.0)
+- [x] CHANGELOG.md up to date ✅
 
 ---
 
@@ -1327,5 +1880,6 @@ sessions:list             # List<session_id>
 
 ---
 
-**Last Updated:** 2025-11-29
-**Target Version:** 1.0.0
+**Last Updated:** 2025-12-02
+**Target Version:** 1.0.0
+**Current Version:** 0.22.1

packages/ipuaro/examples/demo-project/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.DS_Store

packages/ipuaro/examples/demo-project/.ipuaro.json

@@ -0,0 +1,21 @@
+{
+    "redis": {
+        "host": "localhost",
+        "port": 6379
+    },
+    "llm": {
+        "model": "qwen2.5-coder:7b-instruct",
+        "temperature": 0.1
+    },
+    "project": {
+        "ignorePatterns": [
+            "node_modules",
+            "dist",
+            ".git",
+            "*.log"
+        ]
+    },
+    "edit": {
+        "autoApply": false
+    }
+}

packages/ipuaro/examples/demo-project/EXAMPLE_CONVERSATIONS.md

@@ -0,0 +1,8 @@
+# Example Conversations with ipuaro
+
+This document shows realistic conversations you can have with ipuaro when working with the demo project.
+
+## Conversation 1: Understanding the Codebase
+
+```
+You: What does this project do?

packages/ipuaro/examples/demo-project/README.md

@@ -0,0 +1,406 @@
+# ipuaro Demo Project
+
+This is a demo project showcasing ipuaro's capabilities as a local AI agent for codebase operations.
+
+## Project Overview
+
+A simple TypeScript application demonstrating:
+- User management service
+- Authentication service
+- Validation utilities
+- Logging utilities
+- Unit tests
+
+The code intentionally includes various patterns (TODOs, FIXMEs, complex functions, dependencies) to demonstrate ipuaro's analysis tools.
+
+## Setup
+
+### Prerequisites
+
+1. **Redis** - Running locally
+```bash
+# macOS
+brew install redis
+redis-server --appendonly yes
+```
+
+2. **Ollama** - With qwen2.5-coder model
+```bash
+brew install ollama
+ollama serve
+ollama pull qwen2.5-coder:7b-instruct
+```
+
+3. **Node.js** - v20 or higher
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Or with pnpm
+pnpm install
+```
+
+## Using ipuaro with Demo Project
+
+### Start ipuaro
+
+```bash
+# From this directory
+npx @samiyev/ipuaro
+
+# Or if installed globally
+ipuaro
+```
+
+### Example Queries
+
+Try these queries to explore ipuaro's capabilities:
+
+#### 1. Understanding the Codebase
+
+```
+You: What is the structure of this project?
+```
+
+ipuaro will use `get_structure` to show the directory tree.
+
+```
+You: How does user creation work?
+```
+
+ipuaro will:
+1. Use `get_structure` to find relevant files
+2. Use `get_function` to read the `createUser` function
+3. Use `find_references` to see where it's called
+4. Explain the flow
+
+#### 2. Finding Issues
+
+```
+You: What TODOs and FIXMEs are in the codebase?
+```
+
+ipuaro will use `get_todos` to list all TODO/FIXME comments.
+
+```
+You: Which files are most complex?
+```
+
+ipuaro will use `get_complexity` to analyze and rank files by complexity.
+
+#### 3. Understanding Dependencies
+
+```
+You: What does the UserService depend on?
+```
+
+ipuaro will use `get_dependencies` to show imported modules.
+
+```
+You: What files use the validation utilities?
+```
+
+ipuaro will use `get_dependents` to show files importing validation.ts.
+
+#### 4. Code Analysis
+
+```
+You: Find all references to the ValidationError class
+```
+
+ipuaro will use `find_references` to locate all usages.
+
+```
+You: Where is the Logger class defined?
+```
+
+ipuaro will use `find_definition` to locate the definition.
+
+#### 5. Making Changes
+
+```
+You: Add a method to UserService to count total users
+```
+
+ipuaro will:
+1. Read UserService class with `get_class`
+2. Generate the new method
+3. Use `edit_lines` to add it
+4. Show diff and ask for confirmation
+
+```
+You: Fix the TODO in validation.ts about password validation
+```
+
+ipuaro will:
+1. Find the TODO with `get_todos`
+2. Read the function with `get_function`
+3. Implement stronger password validation
+4. Use `edit_lines` to apply changes
+
+#### 6. Testing
+
+```
+You: Run the tests
+```
+
+ipuaro will use `run_tests` to execute the test suite.
+
+```
+You: Add a test for the getUserByEmail method
+```
+
+ipuaro will:
+1. Read existing tests with `get_lines`
+2. Generate new test following the pattern
+3. Use `edit_lines` to add it
+
+#### 7. Git Operations
+
+```
+You: What files have I changed?
+```
+
+ipuaro will use `git_status` to show modified files.
+
+```
+You: Show me the diff for UserService
+```
+
+ipuaro will use `git_diff` with the file path.
+
+```
+You: Commit these changes with message "feat: add user count method"
+```
+
+ipuaro will use `git_commit` after confirmation.
+
+## Tool Demonstration Scenarios
+
+### Scenario 1: Bug Fix Flow
+
+```
+You: There's a bug - we need to sanitize user input before storing. Fix this in UserService.
+
+Agent will:
+1. get_function("src/services/user.ts", "createUser")
+2. See that sanitization is missing
+3. find_definition("sanitizeInput") to locate the utility
+4. edit_lines to add sanitization call
+5. run_tests to verify the fix
+```
+
+### Scenario 2: Refactoring Flow
+
+```
+You: Extract the ID generation logic into a separate utility function
+
+Agent will:
+1. get_class("src/services/user.ts", "UserService")
+2. Find generateId private method
+3. create_file("src/utils/id.ts") with the utility
+4. edit_lines to replace private method with import
+5. find_references("generateId") to check no other usages
+6. run_tests to ensure nothing broke
+```
+
+### Scenario 3: Feature Addition
+
+```
+You: Add password reset functionality to AuthService
+
+Agent will:
+1. get_class("src/auth/service.ts", "AuthService")
+2. get_dependencies to see what's available
+3. Design the resetPassword method
+4. edit_lines to add the method
+5. Suggest creating a test
+6. create_file("tests/auth.test.ts") if needed
+```
+
+### Scenario 4: Code Review
+
+```
+You: Review the code for security issues
+
+Agent will:
+1. get_todos to find FIXME about XSS
+2. get_complexity to find complex functions
+3. get_function for suspicious functions
+4. Suggest improvements
+5. Optionally edit_lines to fix issues
+```
+
+## Slash Commands
+
+While exploring, you can use these commands:
+
+```
+/help               # Show all commands and hotkeys
+/status             # Show system status (LLM, Redis, context)
+/sessions list      # List all sessions
+/undo               # Undo last file change
+/clear              # Clear chat history
+/reindex            # Force project reindexation
+/auto-apply on      # Enable auto-apply mode (skip confirmations)
+```
+
+## Hotkeys
+
+- `Ctrl+C` - Interrupt generation (1st) / Exit (2nd within 1s)
+- `Ctrl+D` - Exit and save session
+- `Ctrl+Z` - Undo last change
+- `↑` / `↓` - Navigate input history
+
+## Project Files Overview
+
+```
+demo-project/
+├── src/
+│   ├── auth/
+│   │   └── service.ts       # Authentication logic (login, logout, verify)
+│   ├── services/
+│   │   └── user.ts          # User CRUD operations
+│   ├── utils/
+│   │   ├── logger.ts        # Logging utility (multiple methods)
+│   │   └── validation.ts    # Input validation (with TODOs/FIXMEs)
+│   ├── types/
+│   │   └── user.ts          # TypeScript type definitions
+│   └── index.ts             # Application entry point
+├── tests/
+│   └── user.test.ts         # User service tests (vitest)
+├── package.json             # Project configuration
+├── tsconfig.json            # TypeScript configuration
+├── vitest.config.ts         # Test configuration
+└── .ipuaro.json             # ipuaro configuration
+```
+
+## What ipuaro Can Do With This Project
+
+### Read Tools ✅
+- **get_lines**: Read any file or specific line ranges
+- **get_function**: Extract specific functions (login, createUser, etc.)
+- **get_class**: Extract classes (UserService, AuthService, Logger, etc.)
+- **get_structure**: See directory tree
+
+### Edit Tools ✅
+- **edit_lines**: Modify functions, fix bugs, add features
+- **create_file**: Add new utilities, tests, services
+- **delete_file**: Remove unused files
+
+### Search Tools ✅
+- **find_references**: Find all usages of ValidationError, User, etc.
+- **find_definition**: Locate where Logger, UserService are defined
+
+### Analysis Tools ✅
+- **get_dependencies**: See what UserService imports
+- **get_dependents**: See what imports validation.ts (multiple files!)
+- **get_complexity**: Identify complex functions (createUser has moderate complexity)
+- **get_todos**: Find 2 TODOs and 1 FIXME in the project
+
+### Git Tools ✅
+- **git_status**: Check working tree
+- **git_diff**: See changes
+- **git_commit**: Commit with AI-generated messages
+
+### Run Tools ✅
+- **run_command**: Execute npm scripts
+- **run_tests**: Run vitest tests
+
+## Tips for Best Experience
+
+1. **Start Small**: Ask about structure first, then dive into specific files
+2. **Be Specific**: "Show me the createUser function" vs "How does this work?"
+3. **Use Tools Implicitly**: Just ask questions, let ipuaro choose the right tools
+4. **Review Changes**: Always review diffs before applying edits
+5. **Test Often**: Ask ipuaro to run tests after making changes
+6. **Commit Incrementally**: Use git_commit for each logical change
+
+## Advanced Workflows
+
+### Workflow 1: Add New Feature
+
+```
+You: Add email verification to the authentication flow
+
+Agent will:
+1. Analyze current auth flow
+2. Propose design (new fields, methods)
+3. Edit AuthService to add verification
+4. Edit User types to add verified field
+5. Create tests for verification
+6. Run tests
+7. Offer to commit
+```
+
+### Workflow 2: Performance Optimization
+
+```
+You: The user lookup is slow when we have many users. Optimize it.
+
+Agent will:
+1. Analyze UserService.getUserByEmail
+2. See it's using Array.find (O(n))
+3. Suggest adding an email index
+4. Edit to add private emailIndex: Map<string, User>
+5. Update createUser to populate index
+6. Update deleteUser to maintain index
+7. Run tests to verify
+```
+
+### Workflow 3: Security Audit
+
+```
+You: Audit the code for security vulnerabilities
+
+Agent will:
+1. get_todos to find FIXME about XSS
+2. Review sanitizeInput implementation
+3. Check password validation strength
+4. Look for SQL injection risks (none here)
+5. Suggest improvements
+6. Optionally implement fixes
+```
+
+## Next Steps
+
+After exploring the demo project, try:
+
+1. **Your Own Project**: Run `ipuaro` in your real codebase
+2. **Customize Config**: Edit `.ipuaro.json` to fit your needs
+3. **Different Model**: Try `--model qwen2.5-coder:32b-instruct` for better results
+4. **Auto-Apply Mode**: Use `--auto-apply` for faster iterations (with caution!)
+
+## Troubleshooting
+
+### Redis Not Connected
+```bash
+# Start Redis with persistence
+redis-server --appendonly yes
+```
+
+### Ollama Model Not Found
+```bash
+# Pull the model
+ollama pull qwen2.5-coder:7b-instruct
+
+# Check it's installed
+ollama list
+```
+
+### Indexing Takes Long
+The project is small (~10 files) so indexing should be instant. For larger projects, use ignore patterns in `.ipuaro.json`.
+
+## Learn More
+
+- [ipuaro Documentation](../../README.md)
+- [Architecture Guide](../../ARCHITECTURE.md)
+- [Tools Reference](../../TOOLS.md)
+- [GitHub Repository](https://github.com/samiyev/puaros)
+
+---
+
+**Happy coding with ipuaro!** 🎩✨

packages/ipuaro/examples/demo-project/package.json

@@ -0,0 +1,20 @@
+{
+    "name": "ipuaro-demo-project",
+    "version": "1.0.0",
+    "description": "Demo project for ipuaro - showcasing AI agent capabilities",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "tsx src/index.ts",
+        "test": "vitest",
+        "test:run": "vitest run",
+        "build": "tsc"
+    },
+    "dependencies": {},
+    "devDependencies": {
+        "@types/node": "^22.10.1",
+        "tsx": "^4.19.2",
+        "typescript": "^5.7.2",
+        "vitest": "^1.6.0"
+    }
+}

packages/ipuaro/examples/demo-project/src/auth/service.ts

@@ -0,0 +1,85 @@
+/**
+ * Authentication service
+ */
+
+import type { User, AuthToken } from "../types/user"
+import { UserService } from "../services/user"
+import { createLogger } from "../utils/logger"
+
+const logger = createLogger("AuthService")
+
+export class AuthService {
+    private tokens: Map<string, AuthToken> = new Map()
+
+    constructor(private userService: UserService) {}
+
+    async login(email: string, password: string): Promise<AuthToken> {
+        logger.info("Login attempt", { email })
+
+        // Get user
+        const user = await this.userService.getUserByEmail(email)
+        if (!user) {
+            logger.warn("Login failed - user not found", { email })
+            throw new Error("Invalid credentials")
+        }
+
+        // TODO: Implement actual password verification
+        // For demo purposes, we just check if password is provided
+        if (!password) {
+            logger.warn("Login failed - no password", { email })
+            throw new Error("Invalid credentials")
+        }
+
+        // Generate token
+        const token = this.generateToken(user)
+        this.tokens.set(token.token, token)
+
+        logger.info("Login successful", { userId: user.id })
+        return token
+    }
+
+    async logout(tokenString: string): Promise<void> {
+        logger.info("Logout", { token: tokenString.substring(0, 10) + "..." })
+
+        const token = this.tokens.get(tokenString)
+        if (!token) {
+            throw new Error("Invalid token")
+        }
+
+        this.tokens.delete(tokenString)
+        logger.info("Logout successful", { userId: token.userId })
+    }
+
+    async verifyToken(tokenString: string): Promise<User> {
+        logger.debug("Verifying token")
+
+        const token = this.tokens.get(tokenString)
+        if (!token) {
+            throw new Error("Invalid token")
+        }
+
+        if (token.expiresAt < new Date()) {
+            this.tokens.delete(tokenString)
+            throw new Error("Token expired")
+        }
+
+        const user = await this.userService.getUserById(token.userId)
+        if (!user) {
+            throw new Error("User not found")
+        }
+
+        return user
+    }
+
+    private generateToken(user: User): AuthToken {
+        const token = `tok_${Date.now()}_${Math.random().toString(36).substring(7)}`
+        const expiresAt = new Date()
+        expiresAt.setHours(expiresAt.getHours() + 24) // 24 hours
+
+        return {
+            token,
+            expiresAt,
+            userId: user.id,
+        }
+    }
+}

packages/ipuaro/examples/demo-project/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Demo application entry point
+ */
+
+import { UserService } from "./services/user"
+import { AuthService } from "./auth/service"
+import { createLogger } from "./utils/logger"
+
+const logger = createLogger("App")
+
+async function main(): Promise<void> {
+    logger.info("Starting demo application")
+
+    // Initialize services
+    const userService = new UserService()
+    const authService = new AuthService(userService)
+
+    try {
+        // Create a demo user
+        const user = await userService.createUser({
+            email: "demo@example.com",
+            name: "Demo User",
+            password: "password123",
+            role: "admin",
+        })
+
+        logger.info("Demo user created", { userId: user.id })
+
+        // Login
+        const token = await authService.login("demo@example.com", "password123")
+        logger.info("Login successful", { token: token.token })
+
+        // Verify token
+        const verifiedUser = await authService.verifyToken(token.token)
+        logger.info("Token verified", { userId: verifiedUser.id })
+
+        // Logout
+        await authService.logout(token.token)
+        logger.info("Logout successful")
+    } catch (error) {
+        logger.error("Application error", error as Error)
+        process.exit(1)
+    }
+
+    logger.info("Demo application finished")
+}
+
+main()

packages/ipuaro/examples/demo-project/src/services/user.ts

@@ -0,0 +1,100 @@
+/**
+ * User service - handles user-related operations
+ */
+
+import type { User, CreateUserDto, UpdateUserDto } from "../types/user"
+import { isValidEmail, isStrongPassword, ValidationError } from "../utils/validation"
+import { createLogger } from "../utils/logger"
+
+const logger = createLogger("UserService")
+
+export class UserService {
+    private users: Map<string, User> = new Map()
+
+    async createUser(dto: CreateUserDto): Promise<User> {
+        logger.info("Creating user", { email: dto.email })
+
+        // Validate email
+        if (!isValidEmail(dto.email)) {
+            throw new ValidationError("Invalid email address", "email")
+        }
+
+        // Validate password
+        if (!isStrongPassword(dto.password)) {
+            throw new ValidationError("Password must be at least 8 characters", "password")
+        }
+
+        // Check if user already exists
+        const existingUser = Array.from(this.users.values()).find((u) => u.email === dto.email)
+
+        if (existingUser) {
+            throw new Error("User with this email already exists")
+        }
+
+        // Create user
+        const user: User = {
+            id: this.generateId(),
+            email: dto.email,
+            name: dto.name,
+            role: dto.role || "user",
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        }
+
+        this.users.set(user.id, user)
+        logger.info("User created", { userId: user.id })
+
+        return user
+    }
+
+    async getUserById(id: string): Promise<User | null> {
+        logger.debug("Getting user by ID", { userId: id })
+        return this.users.get(id) || null
+    }
+
+    async getUserByEmail(email: string): Promise<User | null> {
+        logger.debug("Getting user by email", { email })
+        return Array.from(this.users.values()).find((u) => u.email === email) || null
+    }
+
+    async updateUser(id: string, dto: UpdateUserDto): Promise<User> {
+        logger.info("Updating user", { userId: id })
+
+        const user = this.users.get(id)
+        if (!user) {
+            throw new Error("User not found")
+        }
+
+        const updated: User = {
+            ...user,
+            ...(dto.name && { name: dto.name }),
+            ...(dto.role && { role: dto.role }),
+            updatedAt: new Date(),
+        }
+
+        this.users.set(id, updated)
+        logger.info("User updated", { userId: id })
+
+        return updated
+    }
+
+    async deleteUser(id: string): Promise<void> {
+        logger.info("Deleting user", { userId: id })
+
+        if (!this.users.has(id)) {
+            throw new Error("User not found")
+        }
+
+        this.users.delete(id)
+        logger.info("User deleted", { userId: id })
+    }
+
+    async listUsers(): Promise<User[]> {
+        logger.debug("Listing all users")
+        return Array.from(this.users.values())
+    }
+
+    private generateId(): string {
+        return `user_${Date.now()}_${Math.random().toString(36).substring(7)}`
+    }
+}

packages/ipuaro/examples/demo-project/src/types/user.ts

@@ -0,0 +1,32 @@
+/**
+ * User-related type definitions
+ */
+
+export interface User {
+    id: string
+    email: string
+    name: string
+    role: UserRole
+    createdAt: Date
+    updatedAt: Date
+}
+
+export type UserRole = "admin" | "user" | "guest"
+
+export interface CreateUserDto {
+    email: string
+    name: string
+    password: string
+    role?: UserRole
+}
+
+export interface UpdateUserDto {
+    name?: string
+    role?: UserRole
+}
+
+export interface AuthToken {
+    token: string
+    expiresAt: Date
+    userId: string
+}

packages/ipuaro/examples/demo-project/src/utils/logger.ts

@@ -0,0 +1,41 @@
+/**
+ * Simple logging utility
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error"
+
+export class Logger {
+    constructor(private context: string) {}
+
+    debug(message: string, meta?: Record<string, unknown>): void {
+        this.log("debug", message, meta)
+    }
+
+    info(message: string, meta?: Record<string, unknown>): void {
+        this.log("info", message, meta)
+    }
+
+    warn(message: string, meta?: Record<string, unknown>): void {
+        this.log("warn", message, meta)
+    }
+
+    error(message: string, error?: Error, meta?: Record<string, unknown>): void {
+        this.log("error", message, { ...meta, error: error?.message })
+    }
+
+    private log(level: LogLevel, message: string, meta?: Record<string, unknown>): void {
+        const timestamp = new Date().toISOString()
+        const logEntry = {
+            timestamp,
+            level,
+            context: this.context,
+            message,
+            ...(meta && { meta }),
+        }
+        console.log(JSON.stringify(logEntry))
+    }
+}
+
+export function createLogger(context: string): Logger {
+    return new Logger(context)
+}

packages/ipuaro/examples/demo-project/src/utils/validation.ts

@@ -0,0 +1,28 @@
+/**
+ * Validation utilities
+ */
+
+export function isValidEmail(email: string): boolean {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+    return emailRegex.test(email)
+}
+
+export function isStrongPassword(password: string): boolean {
+    // TODO: Add more sophisticated password validation
+    return password.length >= 8
+}
+
+export function sanitizeInput(input: string): string {
+    // FIXME: This is a basic implementation, needs XSS protection
+    return input.trim().replace(/[<>]/g, "")
+}
+
+export class ValidationError extends Error {
+    constructor(
+        message: string,
+        public field: string,
+    ) {
+        super(message)
+        this.name = "ValidationError"
+    }
+}

packages/ipuaro/examples/demo-project/tests/user.test.ts

@@ -0,0 +1,141 @@
+/**
+ * User service tests
+ */
+
+import { describe, it, expect, beforeEach } from "vitest"
+import { UserService } from "../src/services/user"
+import { ValidationError } from "../src/utils/validation"
+
+describe("UserService", () => {
+    let userService: UserService
+
+    beforeEach(() => {
+        userService = new UserService()
+    })
+
+    describe("createUser", () => {
+        it("should create a new user", async () => {
+            const user = await userService.createUser({
+                email: "test@example.com",
+                name: "Test User",
+                password: "password123",
+            })
+
+            expect(user).toBeDefined()
+            expect(user.email).toBe("test@example.com")
+            expect(user.name).toBe("Test User")
+            expect(user.role).toBe("user")
+        })
+
+        it("should reject invalid email", async () => {
+            await expect(
+                userService.createUser({
+                    email: "invalid-email",
+                    name: "Test User",
+                    password: "password123",
+                }),
+            ).rejects.toThrow(ValidationError)
+        })
+
+        it("should reject weak password", async () => {
+            await expect(
+                userService.createUser({
+                    email: "test@example.com",
+                    name: "Test User",
+                    password: "weak",
+                }),
+            ).rejects.toThrow(ValidationError)
+        })
+
+        it("should prevent duplicate emails", async () => {
+            await userService.createUser({
+                email: "test@example.com",
+                name: "Test User",
+                password: "password123",
+            })
+
+            await expect(
+                userService.createUser({
+                    email: "test@example.com",
+                    name: "Another User",
+                    password: "password123",
+                }),
+            ).rejects.toThrow("already exists")
+        })
+    })
+
+    describe("getUserById", () => {
+        it("should return user by ID", async () => {
+            const created = await userService.createUser({
+                email: "test@example.com",
+                name: "Test User",
+                password: "password123",
+            })
+
+            const found = await userService.getUserById(created.id)
+            expect(found).toEqual(created)
+        })
+
+        it("should return null for non-existent ID", async () => {
+            const found = await userService.getUserById("non-existent")
+            expect(found).toBeNull()
+        })
+    })
+
+    describe("updateUser", () => {
+        it("should update user name", async () => {
+            const user = await userService.createUser({
+                email: "test@example.com",
+                name: "Test User",
+                password: "password123",
+            })
+
+            const updated = await userService.updateUser(user.id, {
+                name: "Updated Name",
+            })
+
+            expect(updated.name).toBe("Updated Name")
+            expect(updated.email).toBe(user.email)
+        })
+
+        it("should throw error for non-existent user", async () => {
+            await expect(userService.updateUser("non-existent", { name: "Test" })).rejects.toThrow(
+                "not found",
+            )
+        })
+    })
+
+    describe("deleteUser", () => {
+        it("should delete user", async () => {
+            const user = await userService.createUser({
+                email: "test@example.com",
+                name: "Test User",
+                password: "password123",
+            })
+
+            await userService.deleteUser(user.id)
+
+            const found = await userService.getUserById(user.id)
+            expect(found).toBeNull()
+        })
+    })
+
+    describe("listUsers", () => {
+        it("should return all users", async () => {
+            await userService.createUser({
+                email: "user1@example.com",
+                name: "User 1",
+                password: "password123",
+            })
+
+            await userService.createUser({
+                email: "user2@example.com",
+                name: "User 2",
+                password: "password123",
+            })
+
+            const users = await userService.listUsers()
+            expect(users).toHaveLength(2)
+        })
+    })
+})

packages/ipuaro/examples/demo-project/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "target": "ES2023",
+        "module": "ESNext",
+        "lib": ["ES2023"],
+        "moduleResolution": "Bundler",
+        "esModuleInterop": true,
+        "strict": true,
+        "skipLibCheck": true,
+        "resolveJsonModule": true,
+        "outDir": "dist",
+        "rootDir": "src"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist", "tests"]
+}

packages/ipuaro/examples/demo-project/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: "node",
+    },
+})

packages/ipuaro/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@samiyev/ipuaro",
-    "version": "0.10.0",
+    "version": "0.22.4",
     "description": "Local AI agent for codebase operations with infinite context feeling",
     "author": "Fozilbek Samiyev <fozilbek.samiyev@gmail.com>",
     "license": "MIT",
@@ -8,7 +8,7 @@
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "bin": {
-        "ipuaro": "./bin/ipuaro.js"
+        "ipuaro": "bin/ipuaro.js"
     },
     "exports": {
         ".": {
@@ -48,10 +48,14 @@
         "zod": "^3.23.8"
     },
     "devDependencies": {
+        "@testing-library/react": "^16.3.0",
+        "@types/jsdom": "^27.0.0",
         "@types/node": "^22.10.1",
         "@types/react": "^18.2.0",
         "@vitest/coverage-v8": "^1.6.0",
         "@vitest/ui": "^1.6.0",
+        "jsdom": "^27.2.0",
+        "react-dom": "18.3.1",
         "tsup": "^8.3.5",
         "typescript": "^5.7.2",
         "vitest": "^1.6.0"

packages/ipuaro/src/application/use-cases/ContextManager.ts

@@ -2,6 +2,7 @@ import type { ContextState, Session } from "../../domain/entities/Session.js"
 import type { ILLMClient } from "../../domain/services/ILLMClient.js"
 import { type ChatMessage, createSystemMessage } from "../../domain/value-objects/ChatMessage.js"
 import { CONTEXT_COMPRESSION_THRESHOLD, CONTEXT_WINDOW_SIZE } from "../../domain/constants/index.js"
+import type { ContextConfig } from "../../shared/constants/config.js"
 
 /**
  * File in context with token count.
@@ -39,9 +40,13 @@ export class ContextManager {
     private readonly filesInContext = new Map<string, FileContext>()
     private currentTokens = 0
     private readonly contextWindowSize: number
+    private readonly compressionThreshold: number
+    private readonly compressionMethod: "llm-summary" | "truncate"
 
-    constructor(contextWindowSize: number = CONTEXT_WINDOW_SIZE) {
+    constructor(contextWindowSize: number = CONTEXT_WINDOW_SIZE, config?: ContextConfig) {
         this.contextWindowSize = contextWindowSize
+        this.compressionThreshold = config?.autoCompressAt ?? CONTEXT_COMPRESSION_THRESHOLD
+        this.compressionMethod = config?.compressionMethod ?? "llm-summary"
     }
 
     /**
@@ -97,7 +102,7 @@ export class ContextManager {
      * Check if compression is needed.
      */
     needsCompression(): boolean {
-        return this.getUsage() > CONTEXT_COMPRESSION_THRESHOLD
+        return this.getUsage() > this.compressionThreshold
     }
 
     /**

packages/ipuaro/src/application/use-cases/ExecuteTool.ts

@@ -0,0 +1,224 @@
+import { randomUUID } from "node:crypto"
+import type { Session } from "../../domain/entities/Session.js"
+import type { ISessionStorage } from "../../domain/services/ISessionStorage.js"
+import type { IStorage } from "../../domain/services/IStorage.js"
+import type { DiffInfo, ToolContext } from "../../domain/services/ITool.js"
+import type { ToolCall } from "../../domain/value-objects/ToolCall.js"
+import { createErrorResult, type ToolResult } from "../../domain/value-objects/ToolResult.js"
+import { createUndoEntry } from "../../domain/value-objects/UndoEntry.js"
+import type { IToolRegistry } from "../interfaces/IToolRegistry.js"
+
+/**
+ * Result of confirmation dialog.
+ */
+export interface ConfirmationResult {
+    confirmed: boolean
+    editedContent?: string[]
+}
+
+/**
+ * Confirmation handler callback type.
+ * Can return either a boolean (for backward compatibility) or a ConfirmationResult.
+ */
+export type ConfirmationHandler = (
+    message: string,
+    diff?: DiffInfo,
+) => Promise<boolean | ConfirmationResult>
+
+/**
+ * Progress handler callback type.
+ */
+export type ProgressHandler = (message: string) => void
+
+/**
+ * Options for ExecuteTool.
+ */
+export interface ExecuteToolOptions {
+    /** Auto-apply edits without confirmation */
+    autoApply?: boolean
+    /** Confirmation handler */
+    onConfirmation?: ConfirmationHandler
+    /** Progress handler */
+    onProgress?: ProgressHandler
+}
+
+/**
+ * Result of tool execution.
+ */
+export interface ExecuteToolResult {
+    result: ToolResult
+    undoEntryCreated: boolean
+    undoEntryId?: string
+}
+
+/**
+ * Use case for executing a single tool.
+ * Orchestrates tool execution with:
+ * - Parameter validation
+ * - Confirmation flow
+ * - Undo stack management
+ * - Storage updates
+ */
+export class ExecuteTool {
+    private readonly storage: IStorage
+    private readonly sessionStorage: ISessionStorage
+    private readonly tools: IToolRegistry
+    private readonly projectRoot: string
+    private lastUndoEntryId?: string
+
+    constructor(
+        storage: IStorage,
+        sessionStorage: ISessionStorage,
+        tools: IToolRegistry,
+        projectRoot: string,
+    ) {
+        this.storage = storage
+        this.sessionStorage = sessionStorage
+        this.tools = tools
+        this.projectRoot = projectRoot
+    }
+
+    /**
+     * Execute a tool call.
+     *
+     * @param toolCall - The tool call to execute
+     * @param session - Current session (for undo stack)
+     * @param options - Execution options
+     * @returns Execution result
+     */
+    async execute(
+        toolCall: ToolCall,
+        session: Session,
+        options: ExecuteToolOptions = {},
+    ): Promise<ExecuteToolResult> {
+        this.lastUndoEntryId = undefined
+        const startTime = Date.now()
+        const tool = this.tools.get(toolCall.name)
+
+        if (!tool) {
+            return {
+                result: createErrorResult(
+                    toolCall.id,
+                    `Unknown tool: ${toolCall.name}`,
+                    Date.now() - startTime,
+                ),
+                undoEntryCreated: false,
+            }
+        }
+
+        const validationError = tool.validateParams(toolCall.params)
+        if (validationError) {
+            return {
+                result: createErrorResult(toolCall.id, validationError, Date.now() - startTime),
+                undoEntryCreated: false,
+            }
+        }
+
+        const context = this.buildToolContext(toolCall, session, options)
+
+        try {
+            const result = await tool.execute(toolCall.params, context)
+
+            return {
+                result,
+                undoEntryCreated: this.lastUndoEntryId !== undefined,
+                undoEntryId: this.lastUndoEntryId,
+            }
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error)
+            return {
+                result: createErrorResult(toolCall.id, errorMessage, Date.now() - startTime),
+                undoEntryCreated: false,
+            }
+        }
+    }
+
+    /**
+     * Build tool context for execution.
+     */
+    private buildToolContext(
+        toolCall: ToolCall,
+        session: Session,
+        options: ExecuteToolOptions,
+    ): ToolContext {
+        return {
+            projectRoot: this.projectRoot,
+            storage: this.storage,
+            requestConfirmation: async (msg: string, diff?: DiffInfo) => {
+                return this.handleConfirmation(msg, diff, toolCall, session, options)
+            },
+            onProgress: (msg: string) => {
+                options.onProgress?.(msg)
+            },
+        }
+    }
+
+    /**
+     * Handle confirmation for tool actions.
+     * Supports edited content from user.
+     */
+    private async handleConfirmation(
+        msg: string,
+        diff: DiffInfo | undefined,
+        toolCall: ToolCall,
+        session: Session,
+        options: ExecuteToolOptions,
+    ): Promise<boolean> {
+        if (options.autoApply) {
+            if (diff) {
+                this.lastUndoEntryId = await this.createUndoEntry(diff, toolCall, session)
+            }
+            return true
+        }
+
+        if (options.onConfirmation) {
+            const result = await options.onConfirmation(msg, diff)
+
+            const confirmed = typeof result === "boolean" ? result : result.confirmed
+            const editedContent = typeof result === "boolean" ? undefined : result.editedContent
+
+            if (confirmed && diff) {
+                if (editedContent && editedContent.length > 0) {
+                    diff.newLines = editedContent
+                    if (toolCall.params.content && typeof toolCall.params.content === "string") {
+                        toolCall.params.content = editedContent.join("\n")
+                    }
+                }
+
+                this.lastUndoEntryId = await this.createUndoEntry(diff, toolCall, session)
+            }
+
+            return confirmed
+        }
+
+        if (diff) {
+            this.lastUndoEntryId = await this.createUndoEntry(diff, toolCall, session)
+        }
+        return true
+    }
+
+    /**
+     * Create undo entry from diff.
+     */
+    private async createUndoEntry(
+        diff: DiffInfo,
+        toolCall: ToolCall,
+        session: Session,
+    ): Promise<string> {
+        const entryId = randomUUID()
+        const entry = createUndoEntry(
+            entryId,
+            diff.filePath,
+            diff.oldLines,
+            diff.newLines,
+            `${toolCall.name}: ${diff.filePath}`,
+            toolCall.id,
+        )
+
+        session.addUndoEntry(entry)
+        await this.sessionStorage.pushUndoEntry(session.id, entry)
+        session.stats.editsApplied++
+
+        return entryId
+    }
+}

packages/ipuaro/src/application/use-cases/HandleMessage.ts

@@ -1,9 +1,8 @@
-import { randomUUID } from "node:crypto"
 import type { Session } from "../../domain/entities/Session.js"
 import type { ILLMClient } from "../../domain/services/ILLMClient.js"
 import type { ISessionStorage } from "../../domain/services/ISessionStorage.js"
 import type { IStorage } from "../../domain/services/IStorage.js"
-import type { DiffInfo, ToolContext } from "../../domain/services/ITool.js"
+import type { DiffInfo } from "../../domain/services/ITool.js"
 import {
     type ChatMessage,
     createAssistantMessage,
@@ -12,10 +11,9 @@ import {
     createUserMessage,
 } from "../../domain/value-objects/ChatMessage.js"
 import type { ToolCall } from "../../domain/value-objects/ToolCall.js"
-import { createErrorResult, type ToolResult } from "../../domain/value-objects/ToolResult.js"
-import { createUndoEntry, type UndoEntry } from "../../domain/value-objects/UndoEntry.js"
-import { IpuaroError } from "../../shared/errors/IpuaroError.js"
-import type { ErrorChoice } from "../../shared/types/index.js"
+import type { ToolResult } from "../../domain/value-objects/ToolResult.js"
+import type { UndoEntry } from "../../domain/value-objects/UndoEntry.js"
+import { type ErrorOption, IpuaroError } from "../../shared/errors/IpuaroError.js"
 import {
     buildInitialContext,
     type ProjectStructure,
@@ -24,6 +22,7 @@ import {
 import { parseToolCalls } from "../../infrastructure/llm/ResponseParser.js"
 import type { IToolRegistry } from "../interfaces/IToolRegistry.js"
 import { ContextManager } from "./ContextManager.js"
+import { type ConfirmationResult, ExecuteTool } from "./ExecuteTool.js"
 
 /**
  * Status during message handling.
@@ -57,8 +56,8 @@ export interface HandleMessageEvents {
     onMessage?: (message: ChatMessage) => void
     onToolCall?: (call: ToolCall) => void
     onToolResult?: (result: ToolResult) => void
-    onConfirmation?: (message: string, diff?: DiffInfo) => Promise<boolean>
-    onError?: (error: IpuaroError) => Promise<ErrorChoice>
+    onConfirmation?: (message: string, diff?: DiffInfo) => Promise<boolean | ConfirmationResult>
+    onError?: (error: IpuaroError) => Promise<ErrorOption>
     onStatusChange?: (status: HandleMessageStatus) => void
     onUndoEntry?: (entry: UndoEntry) => void
 }
@@ -69,6 +68,9 @@ export interface HandleMessageEvents {
 export interface HandleMessageOptions {
     autoApply?: boolean
     maxToolCalls?: number
+    maxHistoryMessages?: number
+    saveInputHistory?: boolean
+    contextConfig?: import("../../shared/constants/config.js").ContextConfig
 }
 
 const DEFAULT_MAX_TOOL_CALLS = 20
@@ -83,6 +85,7 @@ export class HandleMessage {
     private readonly llm: ILLMClient
     private readonly tools: IToolRegistry
     private readonly contextManager: ContextManager
+    private readonly executeTool: ExecuteTool
     private readonly projectRoot: string
     private projectStructure?: ProjectStructure
 
@@ -96,13 +99,15 @@ export class HandleMessage {
         llm: ILLMClient,
         tools: IToolRegistry,
         projectRoot: string,
+        contextConfig?: import("../../shared/constants/config.js").ContextConfig,
     ) {
         this.storage = storage
         this.sessionStorage = sessionStorage
         this.llm = llm
         this.tools = tools
         this.projectRoot = projectRoot
-        this.contextManager = new ContextManager(llm.getContextWindowSize())
+        this.contextManager = new ContextManager(llm.getContextWindowSize(), contextConfig)
+        this.executeTool = new ExecuteTool(storage, sessionStorage, tools, projectRoot)
     }
 
     /**
@@ -134,6 +139,15 @@ export class HandleMessage {
         this.llm.abort()
     }
 
+    /**
+     * Truncate session history if maxHistoryMessages is set.
+     */
+    private truncateHistoryIfNeeded(session: Session): void {
+        if (this.options.maxHistoryMessages !== undefined) {
+            session.truncateHistory(this.options.maxHistoryMessages)
+        }
+    }
+
     /**
      * Execute the message handling flow.
      */
@@ -144,7 +158,12 @@ export class HandleMessage {
         if (message.trim()) {
             const userMessage = createUserMessage(message)
             session.addMessage(userMessage)
-            session.addInputToHistory(message)
+            this.truncateHistoryIfNeeded(session)
+
+            if (this.options.saveInputHistory !== false) {
+                session.addInputToHistory(message)
+            }
+
             this.emitMessage(userMessage)
         }
 
@@ -182,6 +201,7 @@ export class HandleMessage {
                     toolCalls: 0,
                 })
                 session.addMessage(assistantMessage)
+                this.truncateHistoryIfNeeded(session)
                 this.emitMessage(assistantMessage)
                 this.contextManager.addTokens(response.tokens)
                 this.contextManager.updateSession(session)
@@ -196,6 +216,7 @@ export class HandleMessage {
                 toolCalls: parsed.toolCalls.length,
             })
             session.addMessage(assistantMessage)
+            this.truncateHistoryIfNeeded(session)
             this.emitMessage(assistantMessage)
 
             toolCallCount += parsed.toolCalls.length
@@ -203,6 +224,7 @@ export class HandleMessage {
                 const errorMsg = `Maximum tool calls (${String(maxToolCalls)}) exceeded`
                 const errorMessage = createSystemMessage(errorMsg)
                 session.addMessage(errorMessage)
+                this.truncateHistoryIfNeeded(session)
                 this.emitMessage(errorMessage)
                 this.emitStatus("ready")
                 return
@@ -226,6 +248,7 @@ export class HandleMessage {
 
             const toolMessage = createToolMessage(results)
             session.addMessage(toolMessage)
+            this.truncateHistoryIfNeeded(session)
 
             this.contextManager.addTokens(response.tokens)
 
@@ -258,87 +281,32 @@ export class HandleMessage {
     }
 
     private async executeToolCall(toolCall: ToolCall, session: Session): Promise<ToolResult> {
-        const startTime = Date.now()
-        const tool = this.tools.get(toolCall.name)
-
-        if (!tool) {
-            return createErrorResult(
-                toolCall.id,
-                `Unknown tool: ${toolCall.name}`,
-                Date.now() - startTime,
-            )
-        }
-
-        const context: ToolContext = {
-            projectRoot: this.projectRoot,
-            storage: this.storage,
-            requestConfirmation: async (msg: string, diff?: DiffInfo) => {
-                return this.handleConfirmation(msg, diff, toolCall, session)
+        const { result, undoEntryCreated, undoEntryId } = await this.executeTool.execute(
+            toolCall,
+            session,
+            {
+                autoApply: this.options.autoApply,
+                onConfirmation: async (msg: string, diff?: DiffInfo) => {
+                    this.emitStatus("awaiting_confirmation")
+                    if (this.events.onConfirmation) {
+                        return this.events.onConfirmation(msg, diff)
+                    }
+                    return true
+                },
+                onProgress: (_msg: string) => {
+                    this.events.onStatusChange?.("tool_call")
+                },
             },
-            onProgress: (_msg: string) => {
-                this.events.onStatusChange?.("tool_call")
-            },
-        }
-
-        try {
-            const validationError = tool.validateParams(toolCall.params)
-            if (validationError) {
-                return createErrorResult(toolCall.id, validationError, Date.now() - startTime)
-            }
-
-            const result = await tool.execute(toolCall.params, context)
-            return result
-        } catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error)
-            return createErrorResult(toolCall.id, errorMessage, Date.now() - startTime)
-        }
-    }
-
-    private async handleConfirmation(
-        msg: string,
-        diff: DiffInfo | undefined,
-        toolCall: ToolCall,
-        session: Session,
-    ): Promise<boolean> {
-        if (this.options.autoApply) {
-            if (diff) {
-                this.createUndoEntryFromDiff(diff, toolCall, session)
-            }
-            return true
-        }
-
-        this.emitStatus("awaiting_confirmation")
-
-        if (this.events.onConfirmation) {
-            const confirmed = await this.events.onConfirmation(msg, diff)
-
-            if (confirmed && diff) {
-                this.createUndoEntryFromDiff(diff, toolCall, session)
-            }
-
-            return confirmed
-        }
-
-        if (diff) {
-            this.createUndoEntryFromDiff(diff, toolCall, session)
-        }
-        return true
-    }
-
-    private createUndoEntryFromDiff(diff: DiffInfo, toolCall: ToolCall, session: Session): void {
-        const entry = createUndoEntry(
-            randomUUID(),
-            diff.filePath,
-            diff.oldLines,
-            diff.newLines,
-            `${toolCall.name}: ${diff.filePath}`,
-            toolCall.id,
         )
 
-        session.addUndoEntry(entry)
-        void this.sessionStorage.pushUndoEntry(session.id, entry)
-        session.stats.editsApplied++
-        this.events.onUndoEntry?.(entry)
+        if (undoEntryCreated && undoEntryId) {
+            const undoEntry = session.undoStack.find((entry) => entry.id === undoEntryId)
+            if (undoEntry) {
+                this.events.onUndoEntry?.(undoEntry)
+            }
+        }
+
+        return result
     }
 
     private async handleLLMError(error: unknown, session: Session): Promise<void> {
@@ -360,6 +328,7 @@ export class HandleMessage {
 
         const errorMessage = createSystemMessage(`Error: ${ipuaroError.message}`)
         session.addMessage(errorMessage)
+        this.truncateHistoryIfNeeded(session)
         this.emitMessage(errorMessage)
 
         this.emitStatus("ready")

packages/ipuaro/src/application/use-cases/IndexProject.ts

@@ -0,0 +1,184 @@
+import * as path from "node:path"
+import type { IStorage } from "../../domain/services/IStorage.js"
+import type { IndexingStats, IndexProgress } from "../../domain/services/IIndexer.js"
+import { FileScanner } from "../../infrastructure/indexer/FileScanner.js"
+import { ASTParser } from "../../infrastructure/indexer/ASTParser.js"
+import { MetaAnalyzer } from "../../infrastructure/indexer/MetaAnalyzer.js"
+import { IndexBuilder } from "../../infrastructure/indexer/IndexBuilder.js"
+import { createFileData, type FileData } from "../../domain/value-objects/FileData.js"
+import type { FileAST } from "../../domain/value-objects/FileAST.js"
+import { md5 } from "../../shared/utils/hash.js"
+
+/**
+ * Options for indexing a project.
+ */
+export interface IndexProjectOptions {
+    /** Additional ignore patterns */
+    additionalIgnore?: string[]
+    /** Progress callback */
+    onProgress?: (progress: IndexProgress) => void
+}
+
+/**
+ * Use case for indexing a project.
+ * Orchestrates the full indexing pipeline:
+ * 1. Scan files
+ * 2. Parse AST
+ * 3. Analyze metadata
+ * 4. Build indexes
+ * 5. Store in Redis
+ */
+export class IndexProject {
+    private readonly storage: IStorage
+    private readonly scanner: FileScanner
+    private readonly parser: ASTParser
+    private readonly metaAnalyzer: MetaAnalyzer
+    private readonly indexBuilder: IndexBuilder
+
+    constructor(storage: IStorage, projectRoot: string) {
+        this.storage = storage
+        this.scanner = new FileScanner()
+        this.parser = new ASTParser()
+        this.metaAnalyzer = new MetaAnalyzer(projectRoot)
+        this.indexBuilder = new IndexBuilder(projectRoot)
+    }
+
+    /**
+     * Execute the indexing pipeline.
+     *
+     * @param projectRoot - Absolute path to project root
+     * @param options - Optional configuration
+     * @returns Indexing statistics
+     */
+    async execute(projectRoot: string, options: IndexProjectOptions = {}): Promise<IndexingStats> {
+        const startTime = Date.now()
+        const stats: IndexingStats = {
+            filesScanned: 0,
+            filesParsed: 0,
+            parseErrors: 0,
+            timeMs: 0,
+        }
+
+        const fileDataMap = new Map<string, FileData>()
+        const astMap = new Map<string, FileAST>()
+        const contentMap = new Map<string, string>()
+
+        // Phase 1: Scanning
+        this.reportProgress(options.onProgress, 0, 0, "", "scanning")
+
+        const scanResults = await this.scanner.scanAll(projectRoot)
+        stats.filesScanned = scanResults.length
+
+        // Phase 2: Parsing
+        let current = 0
+        const total = scanResults.length
+
+        for (const scanResult of scanResults) {
+            current++
+            const fullPath = path.join(projectRoot, scanResult.path)
+            this.reportProgress(options.onProgress, current, total, scanResult.path, "parsing")
+
+            const content = await FileScanner.readFileContent(fullPath)
+            if (!content) {
+                continue
+            }
+
+            contentMap.set(scanResult.path, content)
+
+            const lines = content.split("\n")
+            const hash = md5(content)
+
+            const fileData = createFileData(lines, hash, scanResult.size, scanResult.lastModified)
+            fileDataMap.set(scanResult.path, fileData)
+
+            const language = this.detectLanguage(scanResult.path)
+            if (!language) {
+                continue
+            }
+
+            const ast = this.parser.parse(content, language)
+            astMap.set(scanResult.path, ast)
+
+            stats.filesParsed++
+            if (ast.parseError) {
+                stats.parseErrors++
+            }
+        }
+
+        // Phase 3: Analyzing metadata
+        current = 0
+        for (const [filePath, ast] of astMap) {
+            current++
+            this.reportProgress(options.onProgress, current, astMap.size, filePath, "analyzing")
+
+            const content = contentMap.get(filePath)
+            if (!content) {
+                continue
+            }
+
+            const fullPath = path.join(projectRoot, filePath)
+            const meta = this.metaAnalyzer.analyze(fullPath, ast, content, astMap)
+
+            await this.storage.setMeta(filePath, meta)
+        }
+
+        // Phase 4: Building indexes
+        this.reportProgress(options.onProgress, 1, 1, "Building indexes", "indexing")
+
+        const symbolIndex = this.indexBuilder.buildSymbolIndex(astMap)
+        const depsGraph = this.indexBuilder.buildDepsGraph(astMap)
+
+        // Phase 5: Store everything
+        for (const [filePath, fileData] of fileDataMap) {
+            await this.storage.setFile(filePath, fileData)
+        }
+
+        for (const [filePath, ast] of astMap) {
+            await this.storage.setAST(filePath, ast)
+        }
+
+        await this.storage.setSymbolIndex(symbolIndex)
+        await this.storage.setDepsGraph(depsGraph)
+
+        // Store last indexed timestamp
+        await this.storage.setProjectConfig("last_indexed", Date.now())
+
+        stats.timeMs = Date.now() - startTime
+
+        return stats
+    }
+
+    /**
+     * Detect language from file extension.
+     */
+    private detectLanguage(filePath: string): "ts" | "tsx" | "js" | "jsx" | null {
+        const ext = path.extname(filePath).toLowerCase()
+        switch (ext) {
+            case ".ts":
+                return "ts"
+            case ".tsx":
+                return "tsx"
+            case ".js":
+                return "js"
+            case ".jsx":
+                return "jsx"
+            default:
+                return null
+        }
+    }
+
+    /**
+     * Report progress to callback if provided.
+     */
+    private reportProgress(
+        callback: ((progress: IndexProgress) => void) | undefined,
+        current: number,
+        total: number,
+        currentFile: string,
+        phase: IndexProgress["phase"],
+    ): void {
+        if (callback) {
+            callback({ current, total, currentFile, phase })
+        }
+    }
+}

packages/ipuaro/src/application/use-cases/index.ts

@@ -4,3 +4,5 @@ export * from "./StartSession.js"
 export * from "./HandleMessage.js"
 export * from "./UndoChange.js"
 export * from "./ContextManager.js"
+export * from "./IndexProject.js"
+export * from "./ExecuteTool.js"

packages/ipuaro/src/cli/commands/index-cmd.ts

@@ -0,0 +1,148 @@
+/**
+ * Index command implementation.
+ * Indexes project without starting TUI.
+ */
+
+import * as path from "node:path"
+import { RedisClient } from "../../infrastructure/storage/RedisClient.js"
+import { RedisStorage } from "../../infrastructure/storage/RedisStorage.js"
+import { generateProjectName } from "../../infrastructure/storage/schema.js"
+import { IndexProject } from "../../application/use-cases/IndexProject.js"
+import { type Config, DEFAULT_CONFIG } from "../../shared/constants/config.js"
+import { checkRedis } from "./onboarding.js"
+
+/**
+ * Result of index command.
+ */
+export interface IndexResult {
+    success: boolean
+    filesIndexed: number
+    filesSkipped: number
+    errors: string[]
+    duration: number
+}
+
+/**
+ * Progress callback for indexing.
+ */
+export type IndexProgressCallback = (
+    phase: "scanning" | "parsing" | "analyzing" | "storing",
+    current: number,
+    total: number,
+    currentFile?: string,
+) => void
+
+/**
+ * Execute the index command.
+ */
+export async function executeIndex(
+    projectPath: string,
+    config: Config = DEFAULT_CONFIG,
+    onProgress?: IndexProgressCallback,
+): Promise<IndexResult> {
+    const startTime = Date.now()
+    const resolvedPath = path.resolve(projectPath)
+    const projectName = generateProjectName(resolvedPath)
+
+    console.warn(`📁 Indexing project: ${resolvedPath}`)
+    console.warn(`   Project name: ${projectName}\n`)
+
+    const redisResult = await checkRedis(config.redis)
+    if (!redisResult.ok) {
+        console.error(`❌ ${redisResult.error ?? "Redis unavailable"}`)
+        return {
+            success: false,
+            filesIndexed: 0,
+            filesSkipped: 0,
+            errors: [redisResult.error ?? "Redis unavailable"],
+            duration: Date.now() - startTime,
+        }
+    }
+
+    let redisClient: RedisClient | null = null
+
+    try {
+        redisClient = new RedisClient(config.redis)
+        await redisClient.connect()
+
+        const storage = new RedisStorage(redisClient, projectName)
+        const indexProject = new IndexProject(storage, resolvedPath)
+
+        let lastPhase: "scanning" | "parsing" | "analyzing" | "indexing" = "scanning"
+        let lastProgress = 0
+
+        const stats = await indexProject.execute(resolvedPath, {
+            onProgress: (progress) => {
+                if (progress.phase !== lastPhase) {
+                    if (lastPhase === "scanning") {
+                        console.warn(`   Found ${String(progress.total)} files\n`)
+                    } else if (lastProgress > 0) {
+                        console.warn("")
+                    }
+
+                    const phaseLabels = {
+                        scanning: "🔍 Scanning files...",
+                        parsing: "📝 Parsing files...",
+                        analyzing: "📊 Analyzing metadata...",
+                        indexing: "🏗️  Building indexes...",
+                    }
+                    console.warn(phaseLabels[progress.phase])
+                    lastPhase = progress.phase
+                }
+
+                if (progress.phase === "indexing") {
+                    onProgress?.("storing", progress.current, progress.total)
+                } else {
+                    onProgress?.(
+                        progress.phase,
+                        progress.current,
+                        progress.total,
+                        progress.currentFile,
+                    )
+                }
+
+                if (
+                    progress.current % 50 === 0 &&
+                    progress.phase !== "scanning" &&
+                    progress.phase !== "indexing"
+                ) {
+                    process.stdout.write(
+                        `\r   ${progress.phase === "parsing" ? "Parsed" : "Analyzed"} ${String(progress.current)}/${String(progress.total)} files...`,
+                    )
+                }
+                lastProgress = progress.current
+            },
+        })
+
+        const symbolIndex = await storage.getSymbolIndex()
+        const durationSec = (stats.timeMs / 1000).toFixed(2)
+
+        console.warn(`\n✅ Indexing complete in ${durationSec}s`)
+        console.warn(`   Files scanned: ${String(stats.filesScanned)}`)
+        console.warn(`   Files parsed: ${String(stats.filesParsed)}`)
+        console.warn(`   Parse errors: ${String(stats.parseErrors)}`)
+        console.warn(`   Symbols: ${String(symbolIndex.size)}`)
+
+        return {
+            success: true,
+            filesIndexed: stats.filesParsed,
+            filesSkipped: stats.filesScanned - stats.filesParsed,
+            errors: [],
+            duration: stats.timeMs,
+        }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        console.error(`❌ Indexing failed: ${message}`)
+        return {
+            success: false,
+            filesIndexed: 0,
+            filesSkipped: 0,
+            errors: [message],
+            duration: Date.now() - startTime,
+        }
+    } finally {
+        if (redisClient) {
+            await redisClient.disconnect()
+        }
+    }
+}

packages/ipuaro/src/cli/commands/index.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI commands module.
+ */
+
+export { executeStart, type StartOptions, type StartResult } from "./start.js"
+export { executeInit, type InitOptions, type InitResult } from "./init.js"
+export { executeIndex, type IndexResult, type IndexProgressCallback } from "./index-cmd.js"
+export {
+    runOnboarding,
+    checkRedis,
+    checkOllama,
+    checkModel,
+    checkProjectSize,
+    pullModel,
+    type OnboardingResult,
+    type OnboardingOptions,
+} from "./onboarding.js"
+export { registerAllTools } from "./tools-setup.js"

packages/ipuaro/src/cli/commands/init.ts

@@ -0,0 +1,114 @@
+/**
+ * Init command implementation.
+ * Creates .ipuaro.json configuration file.
+ */
+
+import * as fs from "node:fs/promises"
+import * as path from "node:path"
+
+/**
+ * Default configuration template for .ipuaro.json
+ */
+const CONFIG_TEMPLATE = {
+    $schema: "https://raw.githubusercontent.com/samiyev/puaros/main/packages/ipuaro/schema.json",
+    redis: {
+        host: "localhost",
+        port: 6379,
+        db: 0,
+    },
+    llm: {
+        model: "qwen2.5-coder:7b-instruct",
+        temperature: 0.1,
+        host: "http://localhost:11434",
+    },
+    project: {
+        ignorePatterns: [],
+    },
+    edit: {
+        autoApply: false,
+    },
+}
+
+/**
+ * Options for init command.
+ */
+export interface InitOptions {
+    force?: boolean
+}
+
+/**
+ * Result of init command.
+ */
+export interface InitResult {
+    success: boolean
+    filePath?: string
+    error?: string
+    skipped?: boolean
+}
+
+/**
+ * Execute the init command.
+ * Creates a .ipuaro.json file in the specified directory.
+ */
+export async function executeInit(
+    projectPath = ".",
+    options: InitOptions = {},
+): Promise<InitResult> {
+    const resolvedPath = path.resolve(projectPath)
+    const configPath = path.join(resolvedPath, ".ipuaro.json")
+
+    try {
+        const exists = await fileExists(configPath)
+
+        if (exists && !options.force) {
+            console.warn(`⚠️  Configuration file already exists: ${configPath}`)
+            console.warn("   Use --force to overwrite.")
+            return {
+                success: true,
+                skipped: true,
+                filePath: configPath,
+            }
+        }
+
+        const dirExists = await fileExists(resolvedPath)
+        if (!dirExists) {
+            await fs.mkdir(resolvedPath, { recursive: true })
+        }
+
+        const content = JSON.stringify(CONFIG_TEMPLATE, null, 4)
+        await fs.writeFile(configPath, content, "utf-8")
+
+        console.warn(`✅ Created ${configPath}`)
+        console.warn("\nConfiguration options:")
+        console.warn("  redis.host     - Redis server host (default: localhost)")
+        console.warn("  redis.port     - Redis server port (default: 6379)")
+        console.warn("  llm.model      - Ollama model name (default: qwen2.5-coder:7b-instruct)")
+        console.warn("  llm.temperature - LLM temperature (default: 0.1)")
+        console.warn("  edit.autoApply - Auto-apply edits without confirmation (default: false)")
+        console.warn("\nRun `ipuaro` to start the AI agent.")
+
+        return {
+            success: true,
+            filePath: configPath,
+        }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        console.error(`❌ Failed to create configuration: ${message}`)
+        return {
+            success: false,
+            error: message,
+        }
+    }
+}
+
+/**
+ * Check if a file or directory exists.
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+    try {
+        await fs.access(filePath)
+        return true
+    } catch {
+        return false
+    }
+}

packages/ipuaro/src/cli/commands/onboarding.ts

@@ -0,0 +1,290 @@
+/**
+ * Onboarding checks for CLI.
+ * Validates environment before starting ipuaro.
+ */
+
+import { RedisClient } from "../../infrastructure/storage/RedisClient.js"
+import { OllamaClient } from "../../infrastructure/llm/OllamaClient.js"
+import { FileScanner } from "../../infrastructure/indexer/FileScanner.js"
+import type { LLMConfig, RedisConfig } from "../../shared/constants/config.js"
+
+/**
+ * Result of onboarding checks.
+ */
+export interface OnboardingResult {
+    success: boolean
+    redisOk: boolean
+    ollamaOk: boolean
+    modelOk: boolean
+    projectOk: boolean
+    fileCount: number
+    errors: string[]
+    warnings: string[]
+}
+
+/**
+ * Options for onboarding checks.
+ */
+export interface OnboardingOptions {
+    redisConfig: RedisConfig
+    llmConfig: LLMConfig
+    projectPath: string
+    maxFiles?: number
+    skipRedis?: boolean
+    skipOllama?: boolean
+    skipModel?: boolean
+    skipProject?: boolean
+}
+
+const DEFAULT_MAX_FILES = 10_000
+
+/**
+ * Check Redis availability.
+ */
+export async function checkRedis(config: RedisConfig): Promise<{
+    ok: boolean
+    error?: string
+}> {
+    const client = new RedisClient(config)
+
+    try {
+        await client.connect()
+        const pingOk = await client.ping()
+        await client.disconnect()
+
+        if (!pingOk) {
+            return {
+                ok: false,
+                error: "Redis ping failed. Server may be overloaded.",
+            }
+        }
+
+        return { ok: true }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        return {
+            ok: false,
+            error: `Cannot connect to Redis: ${message}
+
+Redis is required for ipuaro to store project indexes and session data.
+
+Install Redis:
+  macOS:   brew install redis && brew services start redis
+  Ubuntu:  sudo apt install redis-server && sudo systemctl start redis
+  Docker:  docker run -d -p 6379:6379 redis`,
+        }
+    }
+}
+
+/**
+ * Check Ollama availability.
+ */
+export async function checkOllama(config: LLMConfig): Promise<{
+    ok: boolean
+    error?: string
+}> {
+    const client = new OllamaClient(config)
+
+    try {
+        const available = await client.isAvailable()
+
+        if (!available) {
+            return {
+                ok: false,
+                error: `Cannot connect to Ollama at ${config.host}
+
+Ollama is required for ipuaro to process your requests using local LLMs.
+
+Install Ollama:
+  macOS:   brew install ollama && ollama serve
+  Linux:   curl -fsSL https://ollama.com/install.sh | sh && ollama serve
+  Manual:  https://ollama.com/download
+
+After installing, ensure Ollama is running with: ollama serve`,
+            }
+        }
+
+        return { ok: true }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        return {
+            ok: false,
+            error: `Ollama check failed: ${message}`,
+        }
+    }
+}
+
+/**
+ * Check model availability.
+ */
+export async function checkModel(config: LLMConfig): Promise<{
+    ok: boolean
+    needsPull: boolean
+    error?: string
+}> {
+    const client = new OllamaClient(config)
+
+    try {
+        const hasModel = await client.hasModel(config.model)
+
+        if (!hasModel) {
+            return {
+                ok: false,
+                needsPull: true,
+                error: `Model "${config.model}" is not installed.
+
+Would you like to pull it? This may take a few minutes.
+Run: ollama pull ${config.model}`,
+            }
+        }
+
+        return { ok: true, needsPull: false }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        return {
+            ok: false,
+            needsPull: false,
+            error: `Model check failed: ${message}`,
+        }
+    }
+}
+
+/**
+ * Pull model from Ollama.
+ */
+export async function pullModel(
+    config: LLMConfig,
+    onProgress?: (status: string) => void,
+): Promise<{ ok: boolean; error?: string }> {
+    const client = new OllamaClient(config)
+
+    try {
+        onProgress?.(`Pulling model "${config.model}"...`)
+        await client.pullModel(config.model)
+        onProgress?.(`Model "${config.model}" pulled successfully.`)
+        return { ok: true }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        return {
+            ok: false,
+            error: `Failed to pull model: ${message}`,
+        }
+    }
+}
+
+/**
+ * Check project size.
+ */
+export async function checkProjectSize(
+    projectPath: string,
+    maxFiles: number = DEFAULT_MAX_FILES,
+): Promise<{
+    ok: boolean
+    fileCount: number
+    warning?: string
+}> {
+    const scanner = new FileScanner()
+
+    try {
+        const files = await scanner.scanAll(projectPath)
+        const fileCount = files.length
+
+        if (fileCount > maxFiles) {
+            return {
+                ok: true,
+                fileCount,
+                warning: `Project has ${fileCount.toLocaleString()} files (>${maxFiles.toLocaleString()}).
+This may take a while to index and use more memory.
+
+Consider:
+  1. Running ipuaro in a subdirectory: ipuaro ./src
+  2. Adding patterns to .gitignore to exclude unnecessary files
+  3. Using a smaller project for better performance`,
+            }
+        }
+
+        if (fileCount === 0) {
+            return {
+                ok: false,
+                fileCount: 0,
+                warning: `No supported files found in "${projectPath}".
+
+ipuaro supports: .ts, .tsx, .js, .jsx, .json, .yaml, .yml
+
+Ensure you're running ipuaro in a project directory with source files.`,
+            }
+        }
+
+        return { ok: true, fileCount }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        return {
+            ok: false,
+            fileCount: 0,
+            warning: `Failed to scan project: ${message}`,
+        }
+    }
+}
+
+/**
+ * Run all onboarding checks.
+ */
+export async function runOnboarding(options: OnboardingOptions): Promise<OnboardingResult> {
+    const errors: string[] = []
+    const warnings: string[] = []
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES
+
+    let redisOk = true
+    let ollamaOk = true
+    let modelOk = true
+    let projectOk = true
+    let fileCount = 0
+
+    if (!options.skipRedis) {
+        const redisResult = await checkRedis(options.redisConfig)
+        redisOk = redisResult.ok
+        if (!redisOk && redisResult.error) {
+            errors.push(redisResult.error)
+        }
+    }
+
+    if (!options.skipOllama) {
+        const ollamaResult = await checkOllama(options.llmConfig)
+        ollamaOk = ollamaResult.ok
+        if (!ollamaOk && ollamaResult.error) {
+            errors.push(ollamaResult.error)
+        }
+    }
+
+    if (!options.skipModel && ollamaOk) {
+        const modelResult = await checkModel(options.llmConfig)
+        modelOk = modelResult.ok
+        if (!modelOk && modelResult.error) {
+            errors.push(modelResult.error)
+        }
+    }
+
+    if (!options.skipProject) {
+        const projectResult = await checkProjectSize(options.projectPath, maxFiles)
+        projectOk = projectResult.ok
+        fileCount = projectResult.fileCount
+        if (projectResult.warning) {
+            if (projectResult.ok) {
+                warnings.push(projectResult.warning)
+            } else {
+                errors.push(projectResult.warning)
+            }
+        }
+    }
+
+    return {
+        success: redisOk && ollamaOk && modelOk && projectOk && errors.length === 0,
+        redisOk,
+        ollamaOk,
+        modelOk,
+        projectOk,
+        fileCount,
+        errors,
+        warnings,
+    }
+}

packages/ipuaro/src/cli/commands/start.ts

@@ -0,0 +1,162 @@
+/**
+ * Start command implementation.
+ * Launches the ipuaro TUI.
+ */
+
+import * as path from "node:path"
+import * as readline from "node:readline"
+import { render } from "ink"
+import React from "react"
+import { App, type AppDependencies } from "../../tui/App.js"
+import { RedisClient } from "../../infrastructure/storage/RedisClient.js"
+import { RedisStorage } from "../../infrastructure/storage/RedisStorage.js"
+import { RedisSessionStorage } from "../../infrastructure/storage/RedisSessionStorage.js"
+import { OllamaClient } from "../../infrastructure/llm/OllamaClient.js"
+import { ToolRegistry } from "../../infrastructure/tools/registry.js"
+import { generateProjectName } from "../../infrastructure/storage/schema.js"
+import { type Config, DEFAULT_CONFIG } from "../../shared/constants/config.js"
+import { checkModel, pullModel, runOnboarding } from "./onboarding.js"
+import { registerAllTools } from "./tools-setup.js"
+
+/**
+ * Options for start command.
+ */
+export interface StartOptions {
+    autoApply?: boolean
+    model?: string
+}
+
+/**
+ * Result of start command.
+ */
+export interface StartResult {
+    success: boolean
+    error?: string
+}
+
+/**
+ * Execute the start command.
+ */
+export async function executeStart(
+    projectPath: string,
+    options: StartOptions,
+    config: Config = DEFAULT_CONFIG,
+): Promise<StartResult> {
+    const resolvedPath = path.resolve(projectPath)
+    const projectName = generateProjectName(resolvedPath)
+
+    const llmConfig = {
+        ...config.llm,
+        model: options.model ?? config.llm.model,
+    }
+
+    console.warn("🔍 Running pre-flight checks...\n")
+
+    const onboardingResult = await runOnboarding({
+        redisConfig: config.redis,
+        llmConfig,
+        projectPath: resolvedPath,
+    })
+
+    for (const warning of onboardingResult.warnings) {
+        console.warn(`⚠️  ${warning}\n`)
+    }
+
+    if (!onboardingResult.success) {
+        for (const error of onboardingResult.errors) {
+            console.error(`❌ ${error}\n`)
+        }
+
+        if (!onboardingResult.modelOk && onboardingResult.ollamaOk) {
+            const shouldPull = await promptYesNo(
+                `Would you like to pull "${llmConfig.model}"? (y/n): `,
+            )
+
+            if (shouldPull) {
+                const pullResult = await pullModel(llmConfig, console.warn)
+                if (!pullResult.ok) {
+                    console.error(`❌ ${pullResult.error ?? "Unknown error"}`)
+                    return { success: false, error: pullResult.error }
+                }
+
+                const recheckModel = await checkModel(llmConfig)
+                if (!recheckModel.ok) {
+                    console.error("❌ Model still not available after pull.")
+                    return { success: false, error: "Model pull failed" }
+                }
+            } else {
+                return { success: false, error: "Model not available" }
+            }
+        } else {
+            return {
+                success: false,
+                error: onboardingResult.errors.join("\n"),
+            }
+        }
+    }
+
+    console.warn(`✅ All checks passed. Found ${String(onboardingResult.fileCount)} files.\n`)
+    console.warn("🚀 Starting ipuaro...\n")
+
+    const redisClient = new RedisClient(config.redis)
+
+    try {
+        await redisClient.connect()
+
+        const storage = new RedisStorage(redisClient, projectName)
+        const sessionStorage = new RedisSessionStorage(redisClient)
+        const llm = new OllamaClient(llmConfig)
+        const tools = new ToolRegistry()
+
+        registerAllTools(tools)
+
+        const deps: AppDependencies = {
+            storage,
+            sessionStorage,
+            llm,
+            tools,
+        }
+
+        const handleExit = (): void => {
+            void redisClient.disconnect()
+        }
+
+        const { waitUntilExit } = render(
+            React.createElement(App, {
+                projectPath: resolvedPath,
+                autoApply: options.autoApply ?? config.edit.autoApply,
+                deps,
+                onExit: handleExit,
+            }),
+        )
+
+        await waitUntilExit()
+        await redisClient.disconnect()
+
+        return { success: true }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        console.error(`❌ Failed to start ipuaro: ${message}`)
+        await redisClient.disconnect()
+        return { success: false, error: message }
+    }
+}
+
+/**
+ * Simple yes/no prompt for CLI.
+ */
+async function promptYesNo(question: string): Promise<boolean> {
+    return new Promise((resolve) => {
+        process.stdout.write(question)
+
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        })
+
+        rl.once("line", (answer: string) => {
+            rl.close()
+            resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes")
+        })
+    })
+}

packages/ipuaro/src/cli/commands/tools-setup.ts

@@ -0,0 +1,59 @@
+/**
+ * Tool registration helper for CLI.
+ * Registers all 18 tools with the tool registry.
+ */
+
+import type { IToolRegistry } from "../../application/interfaces/IToolRegistry.js"
+
+import { GetLinesTool } from "../../infrastructure/tools/read/GetLinesTool.js"
+import { GetFunctionTool } from "../../infrastructure/tools/read/GetFunctionTool.js"
+import { GetClassTool } from "../../infrastructure/tools/read/GetClassTool.js"
+import { GetStructureTool } from "../../infrastructure/tools/read/GetStructureTool.js"
+
+import { EditLinesTool } from "../../infrastructure/tools/edit/EditLinesTool.js"
+import { CreateFileTool } from "../../infrastructure/tools/edit/CreateFileTool.js"
+import { DeleteFileTool } from "../../infrastructure/tools/edit/DeleteFileTool.js"
+
+import { FindReferencesTool } from "../../infrastructure/tools/search/FindReferencesTool.js"
+import { FindDefinitionTool } from "../../infrastructure/tools/search/FindDefinitionTool.js"
+
+import { GetDependenciesTool } from "../../infrastructure/tools/analysis/GetDependenciesTool.js"
+import { GetDependentsTool } from "../../infrastructure/tools/analysis/GetDependentsTool.js"
+import { GetComplexityTool } from "../../infrastructure/tools/analysis/GetComplexityTool.js"
+import { GetTodosTool } from "../../infrastructure/tools/analysis/GetTodosTool.js"
+
+import { GitStatusTool } from "../../infrastructure/tools/git/GitStatusTool.js"
+import { GitDiffTool } from "../../infrastructure/tools/git/GitDiffTool.js"
+import { GitCommitTool } from "../../infrastructure/tools/git/GitCommitTool.js"
+
+import { RunCommandTool } from "../../infrastructure/tools/run/RunCommandTool.js"
+import { RunTestsTool } from "../../infrastructure/tools/run/RunTestsTool.js"
+
+/**
+ * Register all 18 tools with the tool registry.
+ */
+export function registerAllTools(registry: IToolRegistry): void {
+    registry.register(new GetLinesTool())
+    registry.register(new GetFunctionTool())
+    registry.register(new GetClassTool())
+    registry.register(new GetStructureTool())
+
+    registry.register(new EditLinesTool())
+    registry.register(new CreateFileTool())
+    registry.register(new DeleteFileTool())
+
+    registry.register(new FindReferencesTool())
+    registry.register(new FindDefinitionTool())
+
+    registry.register(new GetDependenciesTool())
+    registry.register(new GetDependentsTool())
+    registry.register(new GetComplexityTool())
+    registry.register(new GetTodosTool())
+
+    registry.register(new GitStatusTool())
+    registry.register(new GitDiffTool())
+    registry.register(new GitCommitTool())
+
+    registry.register(new RunCommandTool())
+    registry.register(new RunTestsTool())
+}

packages/ipuaro/src/cli/index.ts

@@ -1,44 +1,63 @@
 #!/usr/bin/env node
 
+/**
+ * ipuaro CLI entry point.
+ * Local AI agent for codebase operations with infinite context feeling.
+ */
+
+import { createRequire } from "node:module"
 import { Command } from "commander"
+import { executeStart } from "./commands/start.js"
+import { executeInit } from "./commands/init.js"
+import { executeIndex } from "./commands/index-cmd.js"
+import { loadConfig } from "../shared/config/loader.js"
+
+const require = createRequire(import.meta.url)
+const pkg = require("../../package.json") as { version: string }
 
 const program = new Command()
 
 program
     .name("ipuaro")
     .description("Local AI agent for codebase operations with infinite context feeling")
-    .version("0.1.0")
+    .version(pkg.version)
 
 program
-    .command("start")
+    .command("start", { isDefault: true })
     .description("Start ipuaro TUI in the current directory")
     .argument("[path]", "Project path", ".")
     .option("--auto-apply", "Enable auto-apply mode for edits")
-    .option("--model <name>", "Override LLM model", "qwen2.5-coder:7b-instruct")
-    .action((path: string, options: { autoApply?: boolean; model?: string }) => {
-        const model = options.model ?? "default"
-        const autoApply = options.autoApply ?? false
-        console.warn(`Starting ipuaro in ${path}...`)
-        console.warn(`Model: ${model}`)
-        console.warn(`Auto-apply: ${autoApply ? "enabled" : "disabled"}`)
-        console.warn("\nNot implemented yet. Coming in version 0.11.0!")
+    .option("--model <name>", "Override LLM model")
+    .action(async (projectPath: string, options: { autoApply?: boolean; model?: string }) => {
+        const config = loadConfig(projectPath)
+        const result = await executeStart(projectPath, options, config)
+        if (!result.success) {
+            process.exit(1)
+        }
     })
 
 program
     .command("init")
     .description("Create .ipuaro.json config file")
-    .action(() => {
-        console.warn("Creating .ipuaro.json...")
-        console.warn("\nNot implemented yet. Coming in version 0.17.0!")
+    .argument("[path]", "Project path", ".")
+    .option("--force", "Overwrite existing config file")
+    .action(async (projectPath: string, options: { force?: boolean }) => {
+        const result = await executeInit(projectPath, options)
+        if (!result.success) {
+            process.exit(1)
+        }
     })
 
 program
     .command("index")
     .description("Index project without starting TUI")
     .argument("[path]", "Project path", ".")
-    .action((path: string) => {
-        console.warn(`Indexing ${path}...`)
-        console.warn("\nNot implemented yet. Coming in version 0.3.0!")
+    .action(async (projectPath: string) => {
+        const config = loadConfig(projectPath)
+        const result = await executeIndex(projectPath, config)
+        if (!result.success) {
+            process.exit(1)
+        }
     })
 
 program.parse()

packages/ipuaro/src/domain/entities/Session.ts

@@ -94,6 +94,12 @@ export class Session {
         }
     }
 
+    truncateHistory(maxMessages: number): void {
+        if (this.history.length > maxMessages) {
+            this.history = this.history.slice(-maxMessages)
+        }
+    }
+
     clearHistory(): void {
         this.history = []
         this.context = {

packages/ipuaro/src/domain/services/ILLMClient.ts

@@ -1,26 +1,6 @@
 import type { ChatMessage } from "../value-objects/ChatMessage.js"
 import type { ToolCall } from "../value-objects/ToolCall.js"
 
-/**
- * Tool parameter definition for LLM.
- */
-export interface ToolParameter {
-    name: string
-    type: "string" | "number" | "boolean" | "array" | "object"
-    description: string
-    required: boolean
-    enum?: string[]
-}
-
-/**
- * Tool definition for LLM function calling.
- */
-export interface ToolDef {
-    name: string
-    description: string
-    parameters: ToolParameter[]
-}
-
 /**
  * Response from LLM.
  */
@@ -42,12 +22,16 @@ export interface LLMResponse {
 /**
  * LLM client service interface (port).
  * Abstracts the LLM provider.
+ *
+ * Tool definitions should be included in the system prompt as XML format,
+ * not passed as a separate parameter.
  */
 export interface ILLMClient {
     /**
      * Send messages to LLM and get response.
+     * Tool calls are extracted from the response content using XML parsing.
      */
-    chat(messages: ChatMessage[], tools?: ToolDef[]): Promise<LLMResponse>
+    chat(messages: ChatMessage[]): Promise<LLMResponse>
 
     /**
      * Count tokens in text.

packages/ipuaro/src/index.ts

@@ -21,5 +21,8 @@ export * from "./shared/index.js"
 // Infrastructure exports
 export * from "./infrastructure/index.js"
 
+// TUI exports
+export * from "./tui/index.js"
+
 // Version
 export const VERSION = pkg.version

packages/ipuaro/src/infrastructure/index.ts

@@ -3,3 +3,4 @@ export * from "./storage/index.js"
 export * from "./indexer/index.js"
 export * from "./llm/index.js"
 export * from "./tools/index.js"
+export * from "./security/index.js"

packages/ipuaro/src/infrastructure/llm/OllamaClient.ts

@@ -1,15 +1,10 @@
-import { type Message, Ollama, type Tool } from "ollama"
-import type {
-    ILLMClient,
-    LLMResponse,
-    ToolDef,
-    ToolParameter,
-} from "../../domain/services/ILLMClient.js"
+import { type Message, Ollama } from "ollama"
+import type { ILLMClient, LLMResponse } from "../../domain/services/ILLMClient.js"
 import type { ChatMessage } from "../../domain/value-objects/ChatMessage.js"
-import { createToolCall, type ToolCall } from "../../domain/value-objects/ToolCall.js"
 import type { LLMConfig } from "../../shared/constants/config.js"
 import { IpuaroError } from "../../shared/errors/IpuaroError.js"
 import { estimateTokens } from "../../shared/utils/tokens.js"
+import { parseToolCalls } from "./ResponseParser.js"
 
 /**
  * Ollama LLM client implementation.
@@ -35,19 +30,18 @@ export class OllamaClient implements ILLMClient {
 
     /**
      * Send messages to LLM and get response.
+     * Tool definitions should be included in the system prompt as XML format.
      */
-    async chat(messages: ChatMessage[], tools?: ToolDef[]): Promise<LLMResponse> {
+    async chat(messages: ChatMessage[]): Promise<LLMResponse> {
         const startTime = Date.now()
         this.abortController = new AbortController()
 
         try {
             const ollamaMessages = this.convertMessages(messages)
-            const ollamaTools = tools ? this.convertTools(tools) : undefined
 
             const response = await this.client.chat({
                 model: this.model,
                 messages: ollamaMessages,
-                tools: ollamaTools,
                 options: {
                     temperature: this.temperature,
                 },
@@ -55,15 +49,15 @@ export class OllamaClient implements ILLMClient {
             })
 
             const timeMs = Date.now() - startTime
-            const toolCalls = this.extractToolCalls(response.message)
+            const parsed = parseToolCalls(response.message.content)
 
             return {
-                content: response.message.content,
-                toolCalls,
+                content: parsed.content,
+                toolCalls: parsed.toolCalls,
                 tokens: response.eval_count ?? estimateTokens(response.message.content),
                 timeMs,
                 truncated: false,
-                stopReason: this.determineStopReason(response, toolCalls),
+                stopReason: this.determineStopReason(response, parsed.toolCalls),
             }
         } catch (error) {
             if (error instanceof Error && error.name === "AbortError") {
@@ -205,69 +199,12 @@ export class OllamaClient implements ILLMClient {
         }
     }
 
-    /**
-     * Convert ToolDef array to Ollama Tool format.
-     */
-    private convertTools(tools: ToolDef[]): Tool[] {
-        return tools.map(
-            (tool): Tool => ({
-                type: "function",
-                function: {
-                    name: tool.name,
-                    description: tool.description,
-                    parameters: {
-                        type: "object",
-                        properties: this.convertParameters(tool.parameters),
-                        required: tool.parameters.filter((p) => p.required).map((p) => p.name),
-                    },
-                },
-            }),
-        )
-    }
-
-    /**
-     * Convert ToolParameter array to JSON Schema properties.
-     */
-    private convertParameters(
-        params: ToolParameter[],
-    ): Record<string, { type: string; description: string; enum?: string[] }> {
-        const properties: Record<string, { type: string; description: string; enum?: string[] }> =
-            {}
-
-        for (const param of params) {
-            properties[param.name] = {
-                type: param.type,
-                description: param.description,
-                ...(param.enum && { enum: param.enum }),
-            }
-        }
-
-        return properties
-    }
-
-    /**
-     * Extract tool calls from Ollama response message.
-     */
-    private extractToolCalls(message: Message): ToolCall[] {
-        if (!message.tool_calls || message.tool_calls.length === 0) {
-            return []
-        }
-
-        return message.tool_calls.map((tc, index) =>
-            createToolCall(
-                `call_${String(Date.now())}_${String(index)}`,
-                tc.function.name,
-                tc.function.arguments,
-            ),
-        )
-    }
-
     /**
      * Determine stop reason from response.
      */
     private determineStopReason(
         response: { done_reason?: string },
-        toolCalls: ToolCall[],
+        toolCalls: { name: string; params: Record<string, unknown> }[],
     ): "end" | "length" | "tool_use" {
         if (toolCalls.length > 0) {
             return "tool_use"

packages/ipuaro/src/infrastructure/llm/ResponseParser.ts

@@ -27,9 +27,41 @@ const TOOL_CALL_REGEX = /<tool_call\s+name\s*=\s*"([^"]+)">([\s\S]*?)<\/tool_cal
 const PARAM_REGEX_NAMED = /<param\s+name\s*=\s*"([^"]+)">([\s\S]*?)<\/param>/gi
 const PARAM_REGEX_ELEMENT = /<([a-z_][a-z0-9_]*)>([\s\S]*?)<\/\1>/gi
 
+/**
+ * CDATA section pattern.
+ * Matches: <![CDATA[...]]>
+ */
+const CDATA_REGEX = /<!\[CDATA\[([\s\S]*?)\]\]>/g
+
+/**
+ * Valid tool names.
+ * Used for validation to catch typos or hallucinations.
+ */
+const VALID_TOOL_NAMES = new Set([
+    "get_lines",
+    "get_function",
+    "get_class",
+    "get_structure",
+    "edit_lines",
+    "create_file",
+    "delete_file",
+    "find_references",
+    "find_definition",
+    "get_dependencies",
+    "get_dependents",
+    "get_complexity",
+    "get_todos",
+    "git_status",
+    "git_diff",
+    "git_commit",
+    "run_command",
+    "run_tests",
+])
+
 /**
  * Parse tool calls from LLM response text.
  * Supports XML format: <tool_call name="get_lines"><path>src/index.ts</path></tool_call>
+ * Validates tool names and provides helpful error messages.
  */
 export function parseToolCalls(response: string): ParsedResponse {
     const toolCalls: ToolCall[] = []
@@ -41,6 +73,13 @@ export function parseToolCalls(response: string): ParsedResponse {
     for (const match of matches) {
         const [fullMatch, toolName, paramsXml] = match
 
+        if (!VALID_TOOL_NAMES.has(toolName)) {
+            parseErrors.push(
+                `Unknown tool "${toolName}". Valid tools: ${[...VALID_TOOL_NAMES].join(", ")}`,
+            )
+            continue
+        }
+
         try {
             const params = parseParameters(paramsXml)
             const toolCall = createToolCall(
@@ -91,10 +130,16 @@ function parseParameters(xml: string): Record<string, unknown> {
 
 /**
  * Parse a value string to appropriate type.
+ * Supports CDATA sections for multiline content.
  */
 function parseValue(value: string): unknown {
     const trimmed = value.trim()
 
+    const cdataMatches = [...trimmed.matchAll(CDATA_REGEX)]
+    if (cdataMatches.length > 0 && cdataMatches[0][1] !== undefined) {
+        return cdataMatches[0][1]
+    }
+
     if (trimmed === "true") {
         return true
     }

packages/ipuaro/src/infrastructure/llm/prompts.ts

@@ -23,37 +23,67 @@ export const SYSTEM_PROMPT = `You are ipuaro, a local AI code assistant speciali
 3. **Safety**: Confirm destructive operations. Never execute dangerous commands.
 4. **Efficiency**: Minimize context usage. Request only necessary code sections.
 
+## Tool Calling Format
+
+When you need to use a tool, format your call as XML:
+
+<tool_call name="tool_name">
+  <param_name>value</param_name>
+  <another_param>value</another_param>
+</tool_call>
+
+You can call multiple tools in one response. Always wait for tool results before making conclusions.
+
+**Examples:**
+
+<tool_call name="get_lines">
+  <path>src/index.ts</path>
+  <start>1</start>
+  <end>50</end>
+</tool_call>
+
+<tool_call name="edit_lines">
+  <path>src/utils.ts</path>
+  <start>10</start>
+  <end>15</end>
+  <content>const newCode = "hello";</content>
+</tool_call>
+
+<tool_call name="find_references">
+  <symbol>getUserById</symbol>
+</tool_call>
+
 ## Available Tools
 
 ### Reading Tools
-- \`get_lines\`: Get specific lines from a file
-- \`get_function\`: Get a function by name
-- \`get_class\`: Get a class by name
-- \`get_structure\`: Get project directory structure
+- \`get_lines(path, start?, end?)\`: Get specific lines from a file
+- \`get_function(path, name)\`: Get a function by name
+- \`get_class(path, name)\`: Get a class by name
+- \`get_structure(path?, depth?)\`: Get project directory structure
 
 ### Editing Tools (require confirmation)
-- \`edit_lines\`: Replace specific lines in a file
-- \`create_file\`: Create a new file
-- \`delete_file\`: Delete a file
+- \`edit_lines(path, start, end, content)\`: Replace specific lines in a file
+- \`create_file(path, content)\`: Create a new file
+- \`delete_file(path)\`: Delete a file
 
 ### Search Tools
-- \`find_references\`: Find all usages of a symbol
-- \`find_definition\`: Find where a symbol is defined
+- \`find_references(symbol, path?)\`: Find all usages of a symbol
+- \`find_definition(symbol)\`: Find where a symbol is defined
 
 ### Analysis Tools
-- \`get_dependencies\`: Get files this file imports
-- \`get_dependents\`: Get files that import this file
-- \`get_complexity\`: Get complexity metrics
-- \`get_todos\`: Find TODO/FIXME comments
+- \`get_dependencies(path)\`: Get files this file imports
+- \`get_dependents(path)\`: Get files that import this file
+- \`get_complexity(path?, limit?)\`: Get complexity metrics
+- \`get_todos(path?, type?)\`: Find TODO/FIXME comments
 
 ### Git Tools
-- \`git_status\`: Get repository status
-- \`git_diff\`: Get uncommitted changes
-- \`git_commit\`: Create a commit (requires confirmation)
+- \`git_status()\`: Get repository status
+- \`git_diff(path?, staged?)\`: Get uncommitted changes
+- \`git_commit(message, files?)\`: Create a commit (requires confirmation)
 
 ### Run Tools
-- \`run_command\`: Execute a shell command (security checked)
-- \`run_tests\`: Run the test suite
+- \`run_command(command, timeout?)\`: Execute a shell command (security checked)
+- \`run_tests(path?, filter?, watch?)\`: Run the test suite
 
 ## Response Guidelines
 

packages/ipuaro/src/infrastructure/llm/toolDefs.ts

@@ -1,4 +1,4 @@
-import type { ToolDef } from "../../domain/services/ILLMClient.js"
+import type { ToolDef } from "../../shared/types/tool-definitions.js"
 
 /**
  * Tool definitions for ipuaro LLM.

packages/ipuaro/src/infrastructure/security/PathValidator.ts

@@ -0,0 +1,293 @@
+import * as path from "node:path"
+import { promises as fs } from "node:fs"
+
+/**
+ * Path validation result classification.
+ */
+export type PathValidationStatus = "valid" | "invalid" | "outside_project"
+
+/**
+ * Result of path validation.
+ */
+export interface PathValidationResult {
+    /** Validation status */
+    status: PathValidationStatus
+    /** Reason for the status */
+    reason: string
+    /** Normalized absolute path (only if valid) */
+    absolutePath?: string
+    /** Normalized relative path (only if valid) */
+    relativePath?: string
+}
+
+/**
+ * Options for path validation.
+ */
+export interface PathValidatorOptions {
+    /** Allow paths that don't exist yet (for create operations) */
+    allowNonExistent?: boolean
+    /** Check if path is a directory */
+    requireDirectory?: boolean
+    /** Check if path is a file */
+    requireFile?: boolean
+    /** Follow symlinks when checking existence */
+    followSymlinks?: boolean
+}
+
+/**
+ * Path validator for ensuring file operations stay within project boundaries.
+ * Prevents path traversal attacks and unauthorized file access.
+ */
+export class PathValidator {
+    private readonly projectRoot: string
+
+    constructor(projectRoot: string) {
+        this.projectRoot = path.resolve(projectRoot)
+    }
+
+    /**
+     * Validate a path and return detailed result.
+     * @param inputPath - Path to validate (relative or absolute)
+     * @param options - Validation options
+     */
+    async validate(
+        inputPath: string,
+        options: PathValidatorOptions = {},
+    ): Promise<PathValidationResult> {
+        if (!inputPath || inputPath.trim() === "") {
+            return {
+                status: "invalid",
+                reason: "Path is empty",
+            }
+        }
+
+        const normalizedInput = inputPath.trim()
+
+        if (this.containsTraversalPatterns(normalizedInput)) {
+            return {
+                status: "invalid",
+                reason: "Path contains traversal patterns",
+            }
+        }
+
+        const absolutePath = path.resolve(this.projectRoot, normalizedInput)
+
+        if (!this.isWithinProject(absolutePath)) {
+            return {
+                status: "outside_project",
+                reason: "Path is outside project root",
+            }
+        }
+
+        const relativePath = path.relative(this.projectRoot, absolutePath)
+
+        if (!options.allowNonExistent) {
+            const existsResult = await this.checkExists(absolutePath, options)
+            if (existsResult) {
+                return existsResult
+            }
+        }
+
+        return {
+            status: "valid",
+            reason: "Path is valid",
+            absolutePath,
+            relativePath,
+        }
+    }
+
+    /**
+     * Synchronous validation for simple checks.
+     * Does not check file existence or type.
+     * @param inputPath - Path to validate (relative or absolute)
+     */
+    validateSync(inputPath: string): PathValidationResult {
+        if (!inputPath || inputPath.trim() === "") {
+            return {
+                status: "invalid",
+                reason: "Path is empty",
+            }
+        }
+
+        const normalizedInput = inputPath.trim()
+
+        if (this.containsTraversalPatterns(normalizedInput)) {
+            return {
+                status: "invalid",
+                reason: "Path contains traversal patterns",
+            }
+        }
+
+        const absolutePath = path.resolve(this.projectRoot, normalizedInput)
+
+        if (!this.isWithinProject(absolutePath)) {
+            return {
+                status: "outside_project",
+                reason: "Path is outside project root",
+            }
+        }
+
+        const relativePath = path.relative(this.projectRoot, absolutePath)
+
+        return {
+            status: "valid",
+            reason: "Path is valid",
+            absolutePath,
+            relativePath,
+        }
+    }
+
+    /**
+     * Quick check if path is within project.
+     * @param inputPath - Path to check (relative or absolute)
+     */
+    isWithin(inputPath: string): boolean {
+        if (!inputPath || inputPath.trim() === "") {
+            return false
+        }
+
+        const normalizedInput = inputPath.trim()
+
+        if (this.containsTraversalPatterns(normalizedInput)) {
+            return false
+        }
+
+        const absolutePath = path.resolve(this.projectRoot, normalizedInput)
+        return this.isWithinProject(absolutePath)
+    }
+
+    /**
+     * Resolve a path relative to project root.
+     * Returns null if path would be outside project.
+     * @param inputPath - Path to resolve
+     */
+    resolve(inputPath: string): string | null {
+        const result = this.validateSync(inputPath)
+        return result.status === "valid" ? (result.absolutePath ?? null) : null
+    }
+
+    /**
+     * Resolve a path or throw an error if invalid.
+     * @param inputPath - Path to resolve
+     * @returns Tuple of [absolutePath, relativePath]
+     * @throws Error if path is invalid
+     */
+    resolveOrThrow(inputPath: string): [absolutePath: string, relativePath: string] {
+        const result = this.validateSync(inputPath)
+        if (result.status !== "valid" || result.absolutePath === undefined) {
+            throw new Error(result.reason)
+        }
+        return [result.absolutePath, result.relativePath ?? ""]
+    }
+
+    /**
+     * Get relative path from project root.
+     * Returns null if path would be outside project.
+     * @param inputPath - Path to make relative
+     */
+    relativize(inputPath: string): string | null {
+        const result = this.validateSync(inputPath)
+        return result.status === "valid" ? (result.relativePath ?? null) : null
+    }
+
+    /**
+     * Get the project root path.
+     */
+    getProjectRoot(): string {
+        return this.projectRoot
+    }
+
+    /**
+     * Check if path contains directory traversal patterns.
+     */
+    private containsTraversalPatterns(inputPath: string): boolean {
+        const normalized = inputPath.replace(/\\/g, "/")
+
+        if (normalized.includes("..")) {
+            return true
+        }
+
+        if (normalized.startsWith("~")) {
+            return true
+        }
+
+        return false
+    }
+
+    /**
+     * Check if absolute path is within project root.
+     */
+    private isWithinProject(absolutePath: string): boolean {
+        const normalizedProject = this.projectRoot.replace(/\\/g, "/")
+        const normalizedPath = absolutePath.replace(/\\/g, "/")
+
+        if (normalizedPath === normalizedProject) {
+            return true
+        }
+
+        const projectWithSep = normalizedProject.endsWith("/")
+            ? normalizedProject
+            : `${normalizedProject}/`
+
+        return normalizedPath.startsWith(projectWithSep)
+    }
+
+    /**
+     * Check file existence and type.
+     */
+    private async checkExists(
+        absolutePath: string,
+        options: PathValidatorOptions,
+    ): Promise<PathValidationResult | null> {
+        try {
+            const statFn = options.followSymlinks ? fs.stat : fs.lstat
+            const stats = await statFn(absolutePath)
+
+            if (options.requireDirectory && !stats.isDirectory()) {
+                return {
+                    status: "invalid",
+                    reason: "Path is not a directory",
+                }
+            }
+
+            if (options.requireFile && !stats.isFile()) {
+                return {
+                    status: "invalid",
+                    reason: "Path is not a file",
+                }
+            }
+
+            return null
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+                return {
+                    status: "invalid",
+                    reason: "Path does not exist",
+                }
+            }
+
+            return {
+                status: "invalid",
+                reason: `Cannot access path: ${(error as Error).message}`,
+            }
+        }
+    }
+}
+
+/**
+ * Create a path validator for a project.
+ * @param projectRoot - Root directory of the project
+ */
+export function createPathValidator(projectRoot: string): PathValidator {
+    return new PathValidator(projectRoot)
+}
+
+/**
+ * Standalone function for quick path validation.
+ * @param inputPath - Path to validate
+ * @param projectRoot - Project root directory
+ */
+export function validatePath(inputPath: string, projectRoot: string): boolean {
+    const validator = new PathValidator(projectRoot)
+    return validator.isWithin(inputPath)
+}

packages/ipuaro/src/infrastructure/security/index.ts

@@ -0,0 +1,9 @@
+// Security module exports
+export {
+    PathValidator,
+    createPathValidator,
+    validatePath,
+    type PathValidationResult,
+    type PathValidationStatus,
+    type PathValidatorOptions,
+} from "./PathValidator.js"

packages/ipuaro/src/infrastructure/tools/edit/CreateFileTool.ts

@@ -8,6 +8,7 @@ import {
     type ToolResult,
 } from "../../../domain/value-objects/ToolResult.js"
 import { hashLines } from "../../../shared/utils/hash.js"
+import { PathValidator } from "../../security/PathValidator.js"
 
 /**
  * Result data from create_file tool.
@@ -62,17 +63,18 @@ export class CreateFileTool implements ITool {
         const startTime = Date.now()
         const callId = `${this.name}-${String(startTime)}`
 
-        const relativePath = params.path as string
+        const inputPath = params.path as string
         const content = params.content as string
 
-        const absolutePath = path.resolve(ctx.projectRoot, relativePath)
+        const pathValidator = new PathValidator(ctx.projectRoot)
 
-        if (!absolutePath.startsWith(ctx.projectRoot)) {
-            return createErrorResult(
-                callId,
-                "Path must be within project root",
-                Date.now() - startTime,
-            )
+        let absolutePath: string
+        let relativePath: string
+        try {
+            ;[absolutePath, relativePath] = pathValidator.resolveOrThrow(inputPath)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return createErrorResult(callId, message, Date.now() - startTime)
         }
 
         try {

packages/ipuaro/src/infrastructure/tools/edit/DeleteFileTool.ts

@@ -1,11 +1,11 @@
 import { promises as fs } from "node:fs"
-import * as path from "node:path"
 import type { ITool, ToolContext, ToolParameterSchema } from "../../../domain/services/ITool.js"
 import {
     createErrorResult,
     createSuccessResult,
     type ToolResult,
 } from "../../../domain/value-objects/ToolResult.js"
+import { PathValidator } from "../../security/PathValidator.js"
 
 /**
  * Result data from delete_file tool.
@@ -49,15 +49,16 @@ export class DeleteFileTool implements ITool {
         const startTime = Date.now()
         const callId = `${this.name}-${String(startTime)}`
 
-        const relativePath = params.path as string
-        const absolutePath = path.resolve(ctx.projectRoot, relativePath)
+        const inputPath = params.path as string
+        const pathValidator = new PathValidator(ctx.projectRoot)
 
-        if (!absolutePath.startsWith(ctx.projectRoot)) {
-            return createErrorResult(
-                callId,
-                "Path must be within project root",
-                Date.now() - startTime,
-            )
+        let absolutePath: string
+        let relativePath: string
+        try {
+            ;[absolutePath, relativePath] = pathValidator.resolveOrThrow(inputPath)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return createErrorResult(callId, message, Date.now() - startTime)
         }
 
         try {

packages/ipuaro/src/infrastructure/tools/edit/EditLinesTool.ts

@@ -1,5 +1,4 @@
 import { promises as fs } from "node:fs"
-import * as path from "node:path"
 import type { ITool, ToolContext, ToolParameterSchema } from "../../../domain/services/ITool.js"
 import { createFileData } from "../../../domain/value-objects/FileData.js"
 import {
@@ -8,6 +7,7 @@ import {
     type ToolResult,
 } from "../../../domain/value-objects/ToolResult.js"
 import { hashLines } from "../../../shared/utils/hash.js"
+import { PathValidator } from "../../security/PathValidator.js"
 
 /**
  * Result data from edit_lines tool.
@@ -94,19 +94,20 @@ export class EditLinesTool implements ITool {
         const startTime = Date.now()
         const callId = `${this.name}-${String(startTime)}`
 
-        const relativePath = params.path as string
+        const inputPath = params.path as string
         const startLine = params.start as number
         const endLine = params.end as number
         const newContent = params.content as string
 
-        const absolutePath = path.resolve(ctx.projectRoot, relativePath)
+        const pathValidator = new PathValidator(ctx.projectRoot)
 
-        if (!absolutePath.startsWith(ctx.projectRoot)) {
-            return createErrorResult(
-                callId,
-                "Path must be within project root",
-                Date.now() - startTime,
-            )
+        let absolutePath: string
+        let relativePath: string
+        try {
+            ;[absolutePath, relativePath] = pathValidator.resolveOrThrow(inputPath)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return createErrorResult(callId, message, Date.now() - startTime)
         }
 
         try {

packages/ipuaro/src/infrastructure/tools/read/GetClassTool.ts

@@ -1,5 +1,4 @@
 import { promises as fs } from "node:fs"
-import * as path from "node:path"
 import type { ITool, ToolContext, ToolParameterSchema } from "../../../domain/services/ITool.js"
 import type { ClassInfo } from "../../../domain/value-objects/FileAST.js"
 import {
@@ -7,6 +6,7 @@ import {
     createSuccessResult,
     type ToolResult,
 } from "../../../domain/value-objects/ToolResult.js"
+import { PathValidator } from "../../security/PathValidator.js"
 
 /**
  * Result data from get_class tool.
@@ -67,16 +67,17 @@ export class GetClassTool implements ITool {
         const startTime = Date.now()
         const callId = `${this.name}-${String(startTime)}`
 
-        const relativePath = params.path as string
+        const inputPath = params.path as string
         const className = params.name as string
-        const absolutePath = path.resolve(ctx.projectRoot, relativePath)
+        const pathValidator = new PathValidator(ctx.projectRoot)
 
-        if (!absolutePath.startsWith(ctx.projectRoot)) {
-            return createErrorResult(
-                callId,
-                "Path must be within project root",
-                Date.now() - startTime,
-            )
+        let absolutePath: string
+        let relativePath: string
+        try {
+            ;[absolutePath, relativePath] = pathValidator.resolveOrThrow(inputPath)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return createErrorResult(callId, message, Date.now() - startTime)
         }
 
         try {

packages/ipuaro/src/infrastructure/tools/read/GetFunctionTool.ts

@@ -1,5 +1,4 @@
 import { promises as fs } from "node:fs"
-import * as path from "node:path"
 import type { ITool, ToolContext, ToolParameterSchema } from "../../../domain/services/ITool.js"
 import type { FunctionInfo } from "../../../domain/value-objects/FileAST.js"
 import {
@@ -7,6 +6,7 @@ import {
     createSuccessResult,
     type ToolResult,
 } from "../../../domain/value-objects/ToolResult.js"
+import { PathValidator } from "../../security/PathValidator.js"
 
 /**
  * Result data from get_function tool.
@@ -65,16 +65,17 @@ export class GetFunctionTool implements ITool {
         const startTime = Date.now()
         const callId = `${this.name}-${String(startTime)}`
 
-        const relativePath = params.path as string
+        const inputPath = params.path as string
         const functionName = params.name as string
-        const absolutePath = path.resolve(ctx.projectRoot, relativePath)
+        const pathValidator = new PathValidator(ctx.projectRoot)
 
-        if (!absolutePath.startsWith(ctx.projectRoot)) {
-            return createErrorResult(
-                callId,
-                "Path must be within project root",
-                Date.now() - startTime,
-            )
+        let absolutePath: string
+        let relativePath: string
+        try {
+            ;[absolutePath, relativePath] = pathValidator.resolveOrThrow(inputPath)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return createErrorResult(callId, message, Date.now() - startTime)
         }
 
         try {

packages/ipuaro/src/infrastructure/tools/read/GetLinesTool.ts

@@ -1,11 +1,11 @@
 import { promises as fs } from "node:fs"
-import * as path from "node:path"
 import type { ITool, ToolContext, ToolParameterSchema } from "../../../domain/services/ITool.js"
 import {
     createErrorResult,
     createSuccessResult,
     type ToolResult,
 } from "../../../domain/value-objects/ToolResult.js"
+import { PathValidator } from "../../security/PathValidator.js"
 
 /**
  * Result data from get_lines tool.
@@ -84,15 +84,16 @@ export class GetLinesTool implements ITool {
         const startTime = Date.now()
         const callId = `${this.name}-${String(startTime)}`
 
-        const relativePath = params.path as string
-        const absolutePath = path.resolve(ctx.projectRoot, relativePath)
+        const inputPath = params.path as string
+        const pathValidator = new PathValidator(ctx.projectRoot)
 
-        if (!absolutePath.startsWith(ctx.projectRoot)) {
-            return createErrorResult(
-                callId,
-                "Path must be within project root",
-                Date.now() - startTime,
-            )
+        let absolutePath: string
+        let relativePath: string
+        try {
+            ;[absolutePath, relativePath] = pathValidator.resolveOrThrow(inputPath)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return createErrorResult(callId, message, Date.now() - startTime)
         }
 
         try {

packages/ipuaro/src/infrastructure/tools/read/GetStructureTool.ts

@@ -7,6 +7,7 @@ import {
     type ToolResult,
 } from "../../../domain/value-objects/ToolResult.js"
 import { DEFAULT_IGNORE_PATTERNS } from "../../../domain/constants/index.js"
+import { PathValidator } from "../../security/PathValidator.js"
 
 /**
  * Tree node representing a file or directory.
@@ -89,16 +90,17 @@ export class GetStructureTool implements ITool {
         const startTime = Date.now()
         const callId = `${this.name}-${String(startTime)}`
 
-        const relativePath = (params.path as string | undefined) ?? ""
+        const inputPath = (params.path as string | undefined) ?? "."
         const maxDepth = params.depth as number | undefined
-        const absolutePath = path.resolve(ctx.projectRoot, relativePath)
+        const pathValidator = new PathValidator(ctx.projectRoot)
 
-        if (!absolutePath.startsWith(ctx.projectRoot)) {
-            return createErrorResult(
-                callId,
-                "Path must be within project root",
-                Date.now() - startTime,
-            )
+        let absolutePath: string
+        let relativePath: string
+        try {
+            ;[absolutePath, relativePath] = pathValidator.resolveOrThrow(inputPath)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return createErrorResult(callId, message, Date.now() - startTime)
         }
 
         try {

packages/ipuaro/src/infrastructure/tools/registry.ts

@@ -16,12 +16,7 @@ export class ToolRegistry implements IToolRegistry {
      */
     register(tool: ITool): void {
         if (this.tools.has(tool.name)) {
-            throw new IpuaroError(
-                "validation",
-                `Tool "${tool.name}" is already registered`,
-                true,
-                "Use a different tool name or unregister the existing tool first",
-            )
+            throw IpuaroError.validation(`Tool "${tool.name}" is already registered`)
         }
         this.tools.set(tool.name, tool)
     }

packages/ipuaro/src/infrastructure/tools/run/RunCommandTool.ts

@@ -6,6 +6,7 @@ import {
     createSuccessResult,
     type ToolResult,
 } from "../../../domain/value-objects/ToolResult.js"
+import type { CommandsConfig } from "../../../shared/constants/config.js"
 import { CommandSecurity } from "./CommandSecurity.js"
 
 const execAsync = promisify(exec)
@@ -60,7 +61,7 @@ export class RunCommandTool implements ITool {
         {
             name: "timeout",
             type: "number",
-            description: "Timeout in milliseconds (default: 30000)",
+            description: "Timeout in milliseconds (default: from config or 30000, max: 600000)",
             required: false,
         },
     ]
@@ -69,10 +70,12 @@ export class RunCommandTool implements ITool {
 
     private readonly security: CommandSecurity
     private readonly execFn: typeof execAsync
+    private readonly configTimeout: number | null
 
-    constructor(security?: CommandSecurity, execFn?: typeof execAsync) {
+    constructor(security?: CommandSecurity, execFn?: typeof execAsync, config?: CommandsConfig) {
         this.security = security ?? new CommandSecurity()
         this.execFn = execFn ?? execAsync
+        this.configTimeout = config?.timeout ?? null
     }
 
     validateParams(params: Record<string, unknown>): string | null {
@@ -104,7 +107,7 @@ export class RunCommandTool implements ITool {
         const callId = `${this.name}-${String(startTime)}`
 
         const command = params.command as string
-        const timeout = (params.timeout as number) ?? DEFAULT_TIMEOUT
+        const timeout = (params.timeout as number) ?? this.configTimeout ?? DEFAULT_TIMEOUT
 
         const securityCheck = this.security.check(command)
 

packages/ipuaro/src/shared/constants/config.ts

@@ -76,6 +76,60 @@ export const UndoConfigSchema = z.object({
  */
 export const EditConfigSchema = z.object({
     autoApply: z.boolean().default(false),
+    syntaxHighlight: z.boolean().default(true),
+})
+
+/**
+ * Input configuration schema.
+ */
+export const InputConfigSchema = z.object({
+    multiline: z.union([z.boolean(), z.literal("auto")]).default(false),
+})
+
+/**
+ * Display configuration schema.
+ */
+export const DisplayConfigSchema = z.object({
+    showStats: z.boolean().default(true),
+    showToolCalls: z.boolean().default(true),
+    theme: z.enum(["dark", "light"]).default("dark"),
+    bellOnComplete: z.boolean().default(false),
+    progressBar: z.boolean().default(true),
+})
+
+/**
+ * Session configuration schema.
+ */
+export const SessionConfigSchema = z.object({
+    persistIndefinitely: z.boolean().default(true),
+    maxHistoryMessages: z.number().int().positive().default(100),
+    saveInputHistory: z.boolean().default(true),
+})
+
+/**
+ * Context configuration schema.
+ */
+export const ContextConfigSchema = z.object({
+    systemPromptTokens: z.number().int().positive().default(2000),
+    maxContextUsage: z.number().min(0).max(1).default(0.8),
+    autoCompressAt: z.number().min(0).max(1).default(0.8),
+    compressionMethod: z.enum(["llm-summary", "truncate"]).default("llm-summary"),
+})
+
+/**
+ * Autocomplete configuration schema.
+ */
+export const AutocompleteConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    source: z.enum(["redis-index", "filesystem", "both"]).default("redis-index"),
+    maxSuggestions: z.number().int().positive().default(10),
+})
+
+/**
+ * Commands configuration schema.
+ */
+export const CommandsConfigSchema = z.object({
+    timeout: z.number().int().positive().nullable().default(null),
 })
 
 /**
@@ -88,6 +142,12 @@ export const ConfigSchema = z.object({
     watchdog: WatchdogConfigSchema.default({}),
     undo: UndoConfigSchema.default({}),
     edit: EditConfigSchema.default({}),
+    input: InputConfigSchema.default({}),
+    display: DisplayConfigSchema.default({}),
+    session: SessionConfigSchema.default({}),
+    context: ContextConfigSchema.default({}),
+    autocomplete: AutocompleteConfigSchema.default({}),
+    commands: CommandsConfigSchema.default({}),
 })
 
 /**
@@ -100,6 +160,12 @@ export type ProjectConfig = z.infer<typeof ProjectConfigSchema>
 export type WatchdogConfig = z.infer<typeof WatchdogConfigSchema>
 export type UndoConfig = z.infer<typeof UndoConfigSchema>
 export type EditConfig = z.infer<typeof EditConfigSchema>
+export type InputConfig = z.infer<typeof InputConfigSchema>
+export type DisplayConfig = z.infer<typeof DisplayConfigSchema>
+export type SessionConfig = z.infer<typeof SessionConfigSchema>
+export type ContextConfig = z.infer<typeof ContextConfigSchema>
+export type AutocompleteConfig = z.infer<typeof AutocompleteConfigSchema>
+export type CommandsConfig = z.infer<typeof CommandsConfigSchema>
 
 /**
  * Default configuration.

packages/ipuaro/src/shared/errors/ErrorHandler.ts

@@ -0,0 +1,295 @@
+/**
+ * ErrorHandler service for handling errors with user interaction.
+ * Implements the error handling matrix from ROADMAP.md.
+ */
+
+import { ERROR_MATRIX, type ErrorOption, type ErrorType, IpuaroError } from "./IpuaroError.js"
+
+/**
+ * Result of error handling.
+ */
+export interface ErrorHandlingResult {
+    action: ErrorOption
+    shouldContinue: boolean
+    retryCount?: number
+}
+
+/**
+ * Callback for requesting user choice on error.
+ */
+export type ErrorChoiceCallback = (
+    error: IpuaroError,
+    availableOptions: ErrorOption[],
+    defaultOption: ErrorOption,
+) => Promise<ErrorOption>
+
+/**
+ * Options for ErrorHandler.
+ */
+export interface ErrorHandlerOptions {
+    maxRetries?: number
+    autoSkipParseErrors?: boolean
+    autoRetryLLMErrors?: boolean
+    onError?: ErrorChoiceCallback
+}
+
+const DEFAULT_MAX_RETRIES = 3
+
+/**
+ * Error handler service with matrix-based logic.
+ */
+export class ErrorHandler {
+    private readonly maxRetries: number
+    private readonly autoSkipParseErrors: boolean
+    private readonly autoRetryLLMErrors: boolean
+    private readonly onError?: ErrorChoiceCallback
+
+    private readonly retryCounters = new Map<string, number>()
+
+    constructor(options: ErrorHandlerOptions = {}) {
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES
+        this.autoSkipParseErrors = options.autoSkipParseErrors ?? true
+        this.autoRetryLLMErrors = options.autoRetryLLMErrors ?? false
+        this.onError = options.onError
+    }
+
+    /**
+     * Handle an error and determine the action to take.
+     */
+    async handle(error: IpuaroError, contextKey?: string): Promise<ErrorHandlingResult> {
+        const key = contextKey ?? error.message
+        const currentRetries = this.retryCounters.get(key) ?? 0
+
+        if (this.shouldAutoHandle(error)) {
+            const autoAction = this.getAutoAction(error, currentRetries)
+            if (autoAction) {
+                return this.createResult(autoAction, key, currentRetries)
+            }
+        }
+
+        if (!error.recoverable) {
+            return {
+                action: "abort",
+                shouldContinue: false,
+            }
+        }
+
+        if (this.onError) {
+            const choice = await this.onError(error, error.options, error.defaultOption)
+            return this.createResult(choice, key, currentRetries)
+        }
+
+        return this.createResult(error.defaultOption, key, currentRetries)
+    }
+
+    /**
+     * Handle an error synchronously with default behavior.
+     */
+    handleSync(error: IpuaroError, contextKey?: string): ErrorHandlingResult {
+        const key = contextKey ?? error.message
+        const currentRetries = this.retryCounters.get(key) ?? 0
+
+        if (this.shouldAutoHandle(error)) {
+            const autoAction = this.getAutoAction(error, currentRetries)
+            if (autoAction) {
+                return this.createResult(autoAction, key, currentRetries)
+            }
+        }
+
+        if (!error.recoverable) {
+            return {
+                action: "abort",
+                shouldContinue: false,
+            }
+        }
+
+        return this.createResult(error.defaultOption, key, currentRetries)
+    }
+
+    /**
+     * Reset retry counters.
+     */
+    resetRetries(contextKey?: string): void {
+        if (contextKey) {
+            this.retryCounters.delete(contextKey)
+        } else {
+            this.retryCounters.clear()
+        }
+    }
+
+    /**
+     * Get retry count for a context.
+     */
+    getRetryCount(contextKey: string): number {
+        return this.retryCounters.get(contextKey) ?? 0
+    }
+
+    /**
+     * Check if max retries exceeded for a context.
+     */
+    isMaxRetriesExceeded(contextKey: string): boolean {
+        return this.getRetryCount(contextKey) >= this.maxRetries
+    }
+
+    /**
+     * Wrap a function with error handling.
+     */
+    async wrap<T>(
+        fn: () => Promise<T>,
+        errorType: ErrorType,
+        contextKey?: string,
+    ): Promise<{ success: true; data: T } | { success: false; result: ErrorHandlingResult }> {
+        try {
+            const data = await fn()
+            if (contextKey) {
+                this.resetRetries(contextKey)
+            }
+            return { success: true, data }
+        } catch (err) {
+            const error =
+                err instanceof IpuaroError
+                    ? err
+                    : new IpuaroError(errorType, err instanceof Error ? err.message : String(err))
+
+            const result = await this.handle(error, contextKey)
+            return { success: false, result }
+        }
+    }
+
+    /**
+     * Wrap a function with retry logic.
+     */
+    async withRetry<T>(fn: () => Promise<T>, errorType: ErrorType, contextKey: string): Promise<T> {
+        const key = contextKey
+
+        while (!this.isMaxRetriesExceeded(key)) {
+            try {
+                const result = await fn()
+                this.resetRetries(key)
+                return result
+            } catch (err) {
+                const error =
+                    err instanceof IpuaroError
+                        ? err
+                        : new IpuaroError(
+                              errorType,
+                              err instanceof Error ? err.message : String(err),
+                          )
+
+                const handlingResult = await this.handle(error, key)
+
+                if (handlingResult.action !== "retry" || !handlingResult.shouldContinue) {
+                    throw error
+                }
+            }
+        }
+
+        throw new IpuaroError(
+            errorType,
+            `Max retries (${String(this.maxRetries)}) exceeded for: ${key}`,
+        )
+    }
+
+    private shouldAutoHandle(error: IpuaroError): boolean {
+        if (error.type === "parse" && this.autoSkipParseErrors) {
+            return true
+        }
+        if ((error.type === "llm" || error.type === "timeout") && this.autoRetryLLMErrors) {
+            return true
+        }
+        return false
+    }
+
+    private getAutoAction(error: IpuaroError, currentRetries: number): ErrorOption | null {
+        if (error.type === "parse" && this.autoSkipParseErrors) {
+            return "skip"
+        }
+
+        if ((error.type === "llm" || error.type === "timeout") && this.autoRetryLLMErrors) {
+            if (currentRetries < this.maxRetries) {
+                return "retry"
+            }
+            return "abort"
+        }
+
+        return null
+    }
+
+    private createResult(
+        action: ErrorOption,
+        key: string,
+        currentRetries: number,
+    ): ErrorHandlingResult {
+        if (action === "retry") {
+            this.retryCounters.set(key, currentRetries + 1)
+            const newRetryCount = currentRetries + 1
+
+            if (newRetryCount > this.maxRetries) {
+                return {
+                    action: "abort",
+                    shouldContinue: false,
+                    retryCount: newRetryCount,
+                }
+            }
+
+            return {
+                action: "retry",
+                shouldContinue: true,
+                retryCount: newRetryCount,
+            }
+        }
+
+        this.retryCounters.delete(key)
+
+        return {
+            action,
+            shouldContinue: action === "skip" || action === "confirm" || action === "regenerate",
+            retryCount: currentRetries,
+        }
+    }
+}
+
+/**
+ * Get available options for an error type.
+ */
+export function getErrorOptions(errorType: ErrorType): ErrorOption[] {
+    return ERROR_MATRIX[errorType].options
+}
+
+/**
+ * Get default option for an error type.
+ */
+export function getDefaultErrorOption(errorType: ErrorType): ErrorOption {
+    return ERROR_MATRIX[errorType].defaultOption
+}
+
+/**
+ * Check if an error type is recoverable by default.
+ */
+export function isRecoverableError(errorType: ErrorType): boolean {
+    return ERROR_MATRIX[errorType].recoverable
+}
+
+/**
+ * Convert any error to IpuaroError.
+ */
+export function toIpuaroError(error: unknown, defaultType: ErrorType = "unknown"): IpuaroError {
+    if (error instanceof IpuaroError) {
+        return error
+    }
+
+    if (error instanceof Error) {
+        return new IpuaroError(defaultType, error.message, {
+            context: { originalError: error.name },
+        })
+    }
+
+    return new IpuaroError(defaultType, String(error))
+}
+
+/**
+ * Create a default ErrorHandler instance.
+ */
+export function createErrorHandler(options?: ErrorHandlerOptions): ErrorHandler {
+    return new ErrorHandler(options)
+}

packages/ipuaro/src/shared/errors/IpuaroError.ts

@@ -12,6 +12,72 @@ export type ErrorType =
     | "timeout"
     | "unknown"
 
+/**
+ * Available options for error recovery.
+ */
+export type ErrorOption = "retry" | "skip" | "abort" | "confirm" | "regenerate"
+
+/**
+ * Error metadata with available options.
+ */
+export interface ErrorMeta {
+    type: ErrorType
+    recoverable: boolean
+    options: ErrorOption[]
+    defaultOption: ErrorOption
+}
+
+/**
+ * Error handling matrix - defines behavior for each error type.
+ */
+export const ERROR_MATRIX: Record<ErrorType, Omit<ErrorMeta, "type">> = {
+    redis: {
+        recoverable: false,
+        options: ["retry", "abort"],
+        defaultOption: "abort",
+    },
+    parse: {
+        recoverable: true,
+        options: ["skip", "abort"],
+        defaultOption: "skip",
+    },
+    llm: {
+        recoverable: true,
+        options: ["retry", "skip", "abort"],
+        defaultOption: "retry",
+    },
+    file: {
+        recoverable: true,
+        options: ["skip", "abort"],
+        defaultOption: "skip",
+    },
+    command: {
+        recoverable: true,
+        options: ["confirm", "skip", "abort"],
+        defaultOption: "confirm",
+    },
+    conflict: {
+        recoverable: true,
+        options: ["skip", "regenerate", "abort"],
+        defaultOption: "skip",
+    },
+    validation: {
+        recoverable: true,
+        options: ["skip", "abort"],
+        defaultOption: "skip",
+    },
+    timeout: {
+        recoverable: true,
+        options: ["retry", "skip", "abort"],
+        defaultOption: "retry",
+    },
+    unknown: {
+        recoverable: false,
+        options: ["abort"],
+        defaultOption: "abort",
+    },
+}
+
 /**
  * Base error class for ipuaro.
  */
@@ -19,60 +85,142 @@ export class IpuaroError extends Error {
     readonly type: ErrorType
     readonly recoverable: boolean
     readonly suggestion?: string
+    readonly options: ErrorOption[]
+    readonly defaultOption: ErrorOption
+    readonly context?: Record<string, unknown>
 
-    constructor(type: ErrorType, message: string, recoverable = true, suggestion?: string) {
+    constructor(
+        type: ErrorType,
+        message: string,
+        options?: {
+            recoverable?: boolean
+            suggestion?: string
+            context?: Record<string, unknown>
+        },
+    ) {
         super(message)
         this.name = "IpuaroError"
         this.type = type
-        this.recoverable = recoverable
-        this.suggestion = suggestion
+
+        const meta = ERROR_MATRIX[type]
+        this.recoverable = options?.recoverable ?? meta.recoverable
+        this.options = meta.options
+        this.defaultOption = meta.defaultOption
+        this.suggestion = options?.suggestion
+        this.context = options?.context
     }
 
-    static redis(message: string): IpuaroError {
-        return new IpuaroError(
-            "redis",
-            message,
-            false,
-            "Please ensure Redis is running: redis-server",
-        )
+    /**
+     * Get error metadata.
+     */
+    getMeta(): ErrorMeta {
+        return {
+            type: this.type,
+            recoverable: this.recoverable,
+            options: this.options,
+            defaultOption: this.defaultOption,
+        }
+    }
+
+    /**
+     * Check if an option is available for this error.
+     */
+    hasOption(option: ErrorOption): boolean {
+        return this.options.includes(option)
+    }
+
+    /**
+     * Create a formatted error message with suggestion.
+     */
+    toDisplayString(): string {
+        let result = `[${this.type}] ${this.message}`
+        if (this.suggestion) {
+            result += `\n  Suggestion: ${this.suggestion}`
+        }
+        return result
+    }
+
+    static redis(message: string, context?: Record<string, unknown>): IpuaroError {
+        return new IpuaroError("redis", message, {
+            suggestion: "Please ensure Redis is running: redis-server",
+            context,
+        })
     }
 
     static parse(message: string, filePath?: string): IpuaroError {
         const msg = filePath ? `${message} in ${filePath}` : message
-        return new IpuaroError("parse", msg, true, "File will be skipped")
+        return new IpuaroError("parse", msg, {
+            suggestion: "File will be skipped during indexing",
+            context: filePath ? { filePath } : undefined,
+        })
     }
 
-    static llm(message: string): IpuaroError {
-        return new IpuaroError(
-            "llm",
-            message,
-            true,
-            "Please ensure Ollama is running and model is available",
-        )
+    static llm(message: string, context?: Record<string, unknown>): IpuaroError {
+        return new IpuaroError("llm", message, {
+            suggestion: "Please ensure Ollama is running and model is available",
+            context,
+        })
     }
 
-    static file(message: string): IpuaroError {
-        return new IpuaroError("file", message, true)
+    static llmTimeout(message: string): IpuaroError {
+        return new IpuaroError("timeout", message, {
+            suggestion: "The LLM request timed out. Try again or check Ollama status.",
+        })
     }
 
-    static command(message: string): IpuaroError {
-        return new IpuaroError("command", message, true)
+    static file(message: string, filePath?: string): IpuaroError {
+        return new IpuaroError("file", message, {
+            suggestion: "Check if the file exists and you have permission to access it",
+            context: filePath ? { filePath } : undefined,
+        })
     }
 
-    static conflict(message: string): IpuaroError {
-        return new IpuaroError(
-            "conflict",
-            message,
-            true,
-            "File was modified externally. Regenerate or skip.",
-        )
+    static fileNotFound(filePath: string): IpuaroError {
+        return new IpuaroError("file", `File not found: ${filePath}`, {
+            suggestion: "Check the file path and try again",
+            context: { filePath },
+        })
     }
 
-    static validation(message: string): IpuaroError {
-        return new IpuaroError("validation", message, true)
+    static command(message: string, command?: string): IpuaroError {
+        return new IpuaroError("command", message, {
+            suggestion: "Command requires confirmation or is not in whitelist",
+            context: command ? { command } : undefined,
+        })
     }
 
-    static timeout(message: string): IpuaroError {
-        return new IpuaroError("timeout", message, true, "Try again or increase timeout")
+    static commandBlacklisted(command: string): IpuaroError {
+        return new IpuaroError("command", `Command is blacklisted: ${command}`, {
+            recoverable: false,
+            suggestion: "This command is not allowed for security reasons",
+            context: { command },
+        })
+    }
+
+    static conflict(message: string, filePath?: string): IpuaroError {
+        return new IpuaroError("conflict", message, {
+            suggestion: "File was modified externally. Regenerate or skip the change.",
+            context: filePath ? { filePath } : undefined,
+        })
+    }
+
+    static validation(message: string, field?: string): IpuaroError {
+        return new IpuaroError("validation", message, {
+            suggestion: "Please check the input and try again",
+            context: field ? { field } : undefined,
+        })
+    }
+
+    static timeout(message: string, timeoutMs?: number): IpuaroError {
+        return new IpuaroError("timeout", message, {
+            suggestion: "Try again or increase the timeout value",
+            context: timeoutMs ? { timeoutMs } : undefined,
+        })
+    }
+
+    static unknown(message: string, originalError?: Error): IpuaroError {
+        return new IpuaroError("unknown", message, {
+            context: originalError ? { originalError: originalError.message } : undefined,
+        })
     }
 }

packages/ipuaro/src/shared/errors/index.ts

@@ -1,2 +1,3 @@
 // Shared errors
 export * from "./IpuaroError.js"
+export * from "./ErrorHandler.js"

packages/ipuaro/src/shared/types/index.ts

@@ -19,9 +19,16 @@ export type ConfirmChoice = "apply" | "cancel" | "edit"
 
 /**
  * User choice for errors.
+ * @deprecated Use ErrorOption from shared/errors instead
  */
 export type ErrorChoice = "retry" | "skip" | "abort"
 
+// Re-export ErrorOption for convenience
+export type { ErrorOption } from "../errors/IpuaroError.js"
+
+// Re-export tool definition types
+export type { ToolDef, ToolParameter } from "./tool-definitions.js"
+
 /**
  * Project structure node.
  */

packages/ipuaro/src/shared/types/tool-definitions.ts

@@ -0,0 +1,21 @@
+/**
+ * Tool parameter definition for LLM prompts.
+ * Used to describe tools in system prompts.
+ */
+export interface ToolParameter {
+    name: string
+    type: "string" | "number" | "boolean" | "array" | "object"
+    description: string
+    required: boolean
+    enum?: string[]
+}
+
+/**
+ * Tool definition for LLM prompts.
+ * Used to describe available tools in the system prompt.
+ */
+export interface ToolDef {
+    name: string
+    description: string
+    parameters: ToolParameter[]
+}

packages/ipuaro/src/tui/App.tsx

@@ -0,0 +1,300 @@
+/**
+ * Main TUI App component.
+ * Orchestrates the terminal user interface.
+ */
+
+import { Box, Text, useApp } from "ink"
+import React, { useCallback, useEffect, useState } from "react"
+import type { ILLMClient } from "../domain/services/ILLMClient.js"
+import type { ISessionStorage } from "../domain/services/ISessionStorage.js"
+import type { IStorage } from "../domain/services/IStorage.js"
+import type { DiffInfo } from "../domain/services/ITool.js"
+import type { ErrorOption } from "../shared/errors/IpuaroError.js"
+import type { Config } from "../shared/constants/config.js"
+import type { IToolRegistry } from "../application/interfaces/IToolRegistry.js"
+import type { ConfirmationResult } from "../application/use-cases/ExecuteTool.js"
+import type { ProjectStructure } from "../infrastructure/llm/prompts.js"
+import { Chat, ConfirmDialog, Input, StatusBar } from "./components/index.js"
+import { type CommandResult, useCommands, useHotkeys, useSession } from "./hooks/index.js"
+import type { AppProps, BranchInfo } from "./types.js"
+import type { ConfirmChoice } from "../shared/types/index.js"
+import { ringBell } from "./utils/bell.js"
+
+export interface AppDependencies {
+    storage: IStorage
+    sessionStorage: ISessionStorage
+    llm: ILLMClient
+    tools: IToolRegistry
+    projectStructure?: ProjectStructure
+    config?: Config
+}
+
+export interface ExtendedAppProps extends AppProps {
+    deps: AppDependencies
+    onExit?: () => void
+    multiline?: boolean | "auto"
+    syntaxHighlight?: boolean
+    theme?: "dark" | "light"
+    showStats?: boolean
+    showToolCalls?: boolean
+    bellOnComplete?: boolean
+}
+
+function LoadingScreen(): React.JSX.Element {
+    return (
+        <Box flexDirection="column" padding={1}>
+            <Text color="cyan">Loading session...</Text>
+        </Box>
+    )
+}
+
+function ErrorScreen({ error }: { error: Error }): React.JSX.Element {
+    return (
+        <Box flexDirection="column" padding={1}>
+            <Text color="red" bold>
+                Error
+            </Text>
+            <Text color="red">{error.message}</Text>
+        </Box>
+    )
+}
+
+async function handleErrorDefault(_error: Error): Promise<ErrorOption> {
+    return Promise.resolve("skip")
+}
+
+interface PendingConfirmation {
+    message: string
+    diff?: DiffInfo
+    resolve: (result: boolean | ConfirmationResult) => void
+}
+
+export function App({
+    projectPath,
+    autoApply: initialAutoApply = false,
+    deps,
+    onExit,
+    multiline = false,
+    syntaxHighlight = true,
+    theme = "dark",
+    showStats = true,
+    showToolCalls = true,
+    bellOnComplete = false,
+}: ExtendedAppProps): React.JSX.Element {
+    const { exit } = useApp()
+
+    const [branch] = useState<BranchInfo>({ name: "main", isDetached: false })
+    const [sessionTime, setSessionTime] = useState("0m")
+    const [autoApply, setAutoApply] = useState(initialAutoApply)
+    const [commandResult, setCommandResult] = useState<CommandResult | null>(null)
+    const [pendingConfirmation, setPendingConfirmation] = useState<PendingConfirmation | null>(null)
+
+    const projectName = projectPath.split("/").pop() ?? "unknown"
+
+    const handleConfirmation = useCallback(
+        async (message: string, diff?: DiffInfo): Promise<boolean | ConfirmationResult> => {
+            return new Promise((resolve) => {
+                setPendingConfirmation({ message, diff, resolve })
+            })
+        },
+        [],
+    )
+
+    const handleConfirmSelect = useCallback(
+        (choice: ConfirmChoice, editedContent?: string[]) => {
+            if (!pendingConfirmation) {
+                return
+            }
+
+            if (choice === "apply") {
+                if (editedContent) {
+                    pendingConfirmation.resolve({ confirmed: true, editedContent })
+                } else {
+                    pendingConfirmation.resolve(true)
+                }
+            } else {
+                pendingConfirmation.resolve(false)
+            }
+
+            setPendingConfirmation(null)
+        },
+        [pendingConfirmation],
+    )
+
+    const { session, messages, status, isLoading, error, sendMessage, undo, clearHistory, abort } =
+        useSession(
+            {
+                storage: deps.storage,
+                sessionStorage: deps.sessionStorage,
+                llm: deps.llm,
+                tools: deps.tools,
+                projectRoot: projectPath,
+                projectName,
+                projectStructure: deps.projectStructure,
+                config: deps.config,
+            },
+            {
+                autoApply,
+                onConfirmation: handleConfirmation,
+                onError: handleErrorDefault,
+            },
+        )
+
+    const reindex = useCallback(async (): Promise<void> => {
+        const { IndexProject } = await import("../application/use-cases/IndexProject.js")
+        const indexProject = new IndexProject(deps.storage, projectPath)
+        await indexProject.execute(projectPath)
+    }, [deps.storage, projectPath])
+
+    const { executeCommand, isCommand } = useCommands(
+        {
+            session,
+            sessionStorage: deps.sessionStorage,
+            storage: deps.storage,
+            llm: deps.llm,
+            tools: deps.tools,
+            projectRoot: projectPath,
+            projectName,
+        },
+        {
+            clearHistory,
+            undo,
+            setAutoApply,
+            reindex,
+        },
+        { autoApply },
+    )
+
+    const handleExit = useCallback((): void => {
+        onExit?.()
+        exit()
+    }, [exit, onExit])
+
+    const handleInterrupt = useCallback((): void => {
+        if (status === "thinking" || status === "tool_call") {
+            abort()
+        }
+    }, [status, abort])
+
+    const handleUndo = useCallback((): void => {
+        void undo()
+    }, [undo])
+
+    useHotkeys(
+        {
+            onInterrupt: handleInterrupt,
+            onExit: handleExit,
+            onUndo: handleUndo,
+        },
+        { enabled: !isLoading },
+    )
+
+    useEffect(() => {
+        if (!session) {
+            return
+        }
+
+        const interval = setInterval(() => {
+            setSessionTime(session.getSessionDurationFormatted())
+        }, 60_000)
+
+        setSessionTime(session.getSessionDurationFormatted())
+
+        return (): void => {
+            clearInterval(interval)
+        }
+    }, [session])
+
+    useEffect(() => {
+        if (bellOnComplete && status === "ready") {
+            ringBell()
+        }
+    }, [bellOnComplete, status])
+
+    const handleSubmit = useCallback(
+        (text: string): void => {
+            if (isCommand(text)) {
+                void executeCommand(text).then((result) => {
+                    setCommandResult(result)
+                    // Auto-clear command result after 5 seconds
+                    setTimeout(() => {
+                        setCommandResult(null)
+                    }, 5000)
+                })
+                return
+            }
+            void sendMessage(text)
+        },
+        [sendMessage, isCommand, executeCommand],
+    )
+
+    if (isLoading) {
+        return <LoadingScreen />
+    }
+
+    if (error) {
+        return <ErrorScreen error={error} />
+    }
+
+    const isInputDisabled = status === "thinking" || status === "tool_call" || !!pendingConfirmation
+
+    return (
+        <Box flexDirection="column" height="100%">
+            <StatusBar
+                contextUsage={session?.context.tokenUsage ?? 0}
+                projectName={projectName}
+                branch={branch}
+                sessionTime={sessionTime}
+                status={status}
+                theme={theme}
+            />
+            <Chat
+                messages={messages}
+                isThinking={status === "thinking"}
+                theme={theme}
+                showStats={showStats}
+                showToolCalls={showToolCalls}
+            />
+            {commandResult && (
+                <Box
+                    borderStyle="round"
+                    borderColor={commandResult.success ? "green" : "red"}
+                    paddingX={1}
+                    marginY={1}
+                >
+                    <Text color={commandResult.success ? "green" : "red"} wrap="wrap">
+                        {commandResult.message}
+                    </Text>
+                </Box>
+            )}
+            {pendingConfirmation && (
+                <ConfirmDialog
+                    message={pendingConfirmation.message}
+                    diff={
+                        pendingConfirmation.diff
+                            ? {
+                                  filePath: pendingConfirmation.diff.filePath,
+                                  oldLines: pendingConfirmation.diff.oldLines,
+                                  newLines: pendingConfirmation.diff.newLines,
+                                  startLine: pendingConfirmation.diff.startLine,
+                              }
+                            : undefined
+                    }
+                    onSelect={handleConfirmSelect}
+                    editableContent={pendingConfirmation.diff?.newLines}
+                    syntaxHighlight={syntaxHighlight}
+                />
+            )}
+            <Input
+                onSubmit={handleSubmit}
+                history={session?.inputHistory ?? []}
+                disabled={isInputDisabled}
+                placeholder={isInputDisabled ? "Processing..." : "Type a message..."}
+                storage={deps.storage}
+                projectRoot={projectPath}
+                autocompleteEnabled={true}
+                multiline={multiline}
+            />
+        </Box>
+    )
+}

packages/ipuaro/src/tui/components/Chat.tsx

@@ -0,0 +1,208 @@
+/**
+ * Chat component for TUI.
+ * Displays message history with tool calls and stats.
+ */
+
+import { Box, Text } from "ink"
+import type React from "react"
+import type { ChatMessage } from "../../domain/value-objects/ChatMessage.js"
+import type { ToolCall } from "../../domain/value-objects/ToolCall.js"
+import { getRoleColor, type Theme } from "../utils/theme.js"
+
+export interface ChatProps {
+    messages: ChatMessage[]
+    isThinking: boolean
+    theme?: Theme
+    showStats?: boolean
+    showToolCalls?: boolean
+}
+
+function formatTimestamp(timestamp: number): string {
+    const date = new Date(timestamp)
+    const hours = String(date.getHours()).padStart(2, "0")
+    const minutes = String(date.getMinutes()).padStart(2, "0")
+    return `${hours}:${minutes}`
+}
+
+function formatStats(stats: ChatMessage["stats"]): string {
+    if (!stats) {
+        return ""
+    }
+    const time = (stats.timeMs / 1000).toFixed(1)
+    const tokens = stats.tokens.toLocaleString()
+    const tools = stats.toolCalls
+
+    const parts = [`${time}s`, `${tokens} tokens`]
+    if (tools > 0) {
+        parts.push(`${String(tools)} tool${tools > 1 ? "s" : ""}`)
+    }
+    return parts.join(" | ")
+}
+
+function formatToolCall(call: ToolCall): string {
+    const params = Object.entries(call.params)
+        .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+        .join(" ")
+    return `[${call.name} ${params}]`
+}
+
+interface MessageComponentProps {
+    message: ChatMessage
+    theme: Theme
+    showStats: boolean
+    showToolCalls: boolean
+}
+
+function UserMessage({ message, theme }: MessageComponentProps): React.JSX.Element {
+    const roleColor = getRoleColor("user", theme)
+
+    return (
+        <Box flexDirection="column" marginBottom={1}>
+            <Box gap={1}>
+                <Text color={roleColor} bold>
+                    You
+                </Text>
+                <Text color="gray" dimColor>
+                    {formatTimestamp(message.timestamp)}
+                </Text>
+            </Box>
+            <Box marginLeft={2}>
+                <Text>{message.content}</Text>
+            </Box>
+        </Box>
+    )
+}
+
+function AssistantMessage({
+    message,
+    theme,
+    showStats,
+    showToolCalls,
+}: MessageComponentProps): React.JSX.Element {
+    const stats = formatStats(message.stats)
+    const roleColor = getRoleColor("assistant", theme)
+
+    return (
+        <Box flexDirection="column" marginBottom={1}>
+            <Box gap={1}>
+                <Text color={roleColor} bold>
+                    Assistant
+                </Text>
+                <Text color="gray" dimColor>
+                    {formatTimestamp(message.timestamp)}
+                </Text>
+            </Box>
+
+            {showToolCalls && message.toolCalls && message.toolCalls.length > 0 && (
+                <Box flexDirection="column" marginLeft={2} marginBottom={1}>
+                    {message.toolCalls.map((call) => (
+                        <Text key={call.id} color="yellow">
+                            {formatToolCall(call)}
+                        </Text>
+                    ))}
+                </Box>
+            )}
+
+            {message.content && (
+                <Box marginLeft={2}>
+                    <Text>{message.content}</Text>
+                </Box>
+            )}
+
+            {showStats && stats && (
+                <Box marginLeft={2} marginTop={1}>
+                    <Text color="gray" dimColor>
+                        {stats}
+                    </Text>
+                </Box>
+            )}
+        </Box>
+    )
+}
+
+function ToolMessage({ message }: MessageComponentProps): React.JSX.Element {
+    return (
+        <Box flexDirection="column" marginBottom={1} marginLeft={2}>
+            {message.toolResults?.map((result) => (
+                <Box key={result.callId} flexDirection="column">
+                    <Text color={result.success ? "green" : "red"}>
+                        {result.success ? "+" : "x"} {result.callId.slice(0, 8)}
+                    </Text>
+                </Box>
+            ))}
+        </Box>
+    )
+}
+
+function SystemMessage({ message, theme }: MessageComponentProps): React.JSX.Element {
+    const isError = message.content.toLowerCase().startsWith("error")
+    const roleColor = getRoleColor("system", theme)
+
+    return (
+        <Box marginBottom={1} marginLeft={2}>
+            <Text color={isError ? "red" : roleColor} dimColor={!isError}>
+                {message.content}
+            </Text>
+        </Box>
+    )
+}
+
+function MessageComponent({
+    message,
+    theme,
+    showStats,
+    showToolCalls,
+}: MessageComponentProps): React.JSX.Element {
+    const props = { message, theme, showStats, showToolCalls }
+
+    switch (message.role) {
+        case "user": {
+            return <UserMessage {...props} />
+        }
+        case "assistant": {
+            return <AssistantMessage {...props} />
+        }
+        case "tool": {
+            return <ToolMessage {...props} />
+        }
+        case "system": {
+            return <SystemMessage {...props} />
+        }
+        default: {
+            return <></>
+        }
+    }
+}
+
+function ThinkingIndicator({ theme }: { theme: Theme }): React.JSX.Element {
+    const color = getRoleColor("assistant", theme)
+
+    return (
+        <Box marginBottom={1}>
+            <Text color={color}>Thinking...</Text>
+        </Box>
+    )
+}
+
+export function Chat({
+    messages,
+    isThinking,
+    theme = "dark",
+    showStats = true,
+    showToolCalls = true,
+}: ChatProps): React.JSX.Element {
+    return (
+        <Box flexDirection="column" flexGrow={1} paddingX={1}>
+            {messages.map((message, index) => (
+                <MessageComponent
+                    key={`${String(message.timestamp)}-${String(index)}`}
+                    message={message}
+                    theme={theme}
+                    showStats={showStats}
+                    showToolCalls={showToolCalls}
+                />
+            ))}
+            {isThinking && <ThinkingIndicator theme={theme} />}
+        </Box>
+    )
+}

packages/ipuaro/src/tui/components/ConfirmDialog.tsx

@@ -0,0 +1,137 @@
+/**
+ * ConfirmDialog component for TUI.
+ * Displays a confirmation dialog with [Y] Apply / [N] Cancel / [E] Edit options.
+ * Supports inline editing when user selects Edit.
+ */
+
+import { Box, Text, useInput } from "ink"
+import React, { useCallback, useState } from "react"
+import type { ConfirmChoice } from "../../shared/types/index.js"
+import { DiffView, type DiffViewProps } from "./DiffView.js"
+import { EditableContent } from "./EditableContent.js"
+
+export interface ConfirmDialogProps {
+    message: string
+    diff?: DiffViewProps
+    onSelect: (choice: ConfirmChoice, editedContent?: string[]) => void
+    editableContent?: string[]
+    syntaxHighlight?: boolean
+}
+
+type DialogMode = "confirm" | "edit"
+
+function ChoiceButton({
+    hotkey,
+    label,
+    isSelected,
+}: {
+    hotkey: string
+    label: string
+    isSelected: boolean
+}): React.JSX.Element {
+    return (
+        <Box>
+            <Text color={isSelected ? "cyan" : "gray"}>
+                [<Text bold>{hotkey}</Text>] {label}
+            </Text>
+        </Box>
+    )
+}
+
+export function ConfirmDialog({
+    message,
+    diff,
+    onSelect,
+    editableContent,
+    syntaxHighlight = false,
+}: ConfirmDialogProps): React.JSX.Element {
+    const [mode, setMode] = useState<DialogMode>("confirm")
+    const [selected, setSelected] = useState<ConfirmChoice | null>(null)
+
+    const linesToEdit = editableContent ?? diff?.newLines ?? []
+    const canEdit = linesToEdit.length > 0
+
+    const handleEditSubmit = useCallback(
+        (editedLines: string[]) => {
+            setSelected("apply")
+            onSelect("apply", editedLines)
+        },
+        [onSelect],
+    )
+
+    const handleEditCancel = useCallback(() => {
+        setMode("confirm")
+        setSelected(null)
+    }, [])
+
+    useInput(
+        (input, key) => {
+            if (mode === "edit") {
+                return
+            }
+
+            const lowerInput = input.toLowerCase()
+
+            if (lowerInput === "y") {
+                setSelected("apply")
+                onSelect("apply")
+            } else if (lowerInput === "n") {
+                setSelected("cancel")
+                onSelect("cancel")
+            } else if (lowerInput === "e" && canEdit) {
+                setSelected("edit")
+                setMode("edit")
+            } else if (key.escape) {
+                setSelected("cancel")
+                onSelect("cancel")
+            }
+        },
+        { isActive: mode === "confirm" },
+    )
+
+    if (mode === "edit") {
+        return (
+            <EditableContent
+                lines={linesToEdit}
+                onSubmit={handleEditSubmit}
+                onCancel={handleEditCancel}
+            />
+        )
+    }
+
+    return (
+        <Box
+            flexDirection="column"
+            borderStyle="round"
+            borderColor="yellow"
+            paddingX={1}
+            paddingY={1}
+        >
+            <Box marginBottom={1}>
+                <Text color="yellow" bold>
+                    ⚠ {message}
+                </Text>
+            </Box>
+
+            {diff && (
+                <Box marginBottom={1}>
+                    <DiffView {...diff} syntaxHighlight={syntaxHighlight} />
+                </Box>
+            )}
+
+            <Box gap={2}>
+                <ChoiceButton hotkey="Y" label="Apply" isSelected={selected === "apply"} />
+                <ChoiceButton hotkey="N" label="Cancel" isSelected={selected === "cancel"} />
+                {canEdit ? (
+                    <ChoiceButton hotkey="E" label="Edit" isSelected={selected === "edit"} />
+                ) : (
+                    <Box>
+                        <Text color="gray" dimColor>
+                            [E] Edit (disabled)
+                        </Text>
+                    </Box>
+                )}
+            </Box>
+        </Box>
+    )
+}

packages/ipuaro/src/tui/components/DiffView.tsx

@@ -0,0 +1,219 @@
+/**
+ * DiffView component for TUI.
+ * Displays inline diff with green (added) and red (removed) highlighting.
+ */
+
+import { Box, Text } from "ink"
+import type React from "react"
+import { detectLanguage, highlightLine, type Language } from "../utils/syntax-highlighter.js"
+
+export interface DiffViewProps {
+    filePath: string
+    oldLines: string[]
+    newLines: string[]
+    startLine: number
+    language?: Language
+    syntaxHighlight?: boolean
+}
+
+interface DiffLine {
+    type: "add" | "remove" | "context"
+    content: string
+    lineNumber?: number
+}
+
+function computeDiff(oldLines: string[], newLines: string[], startLine: number): DiffLine[] {
+    const result: DiffLine[] = []
+
+    let oldIdx = 0
+    let newIdx = 0
+
+    while (oldIdx < oldLines.length || newIdx < newLines.length) {
+        const oldLine = oldIdx < oldLines.length ? oldLines[oldIdx] : undefined
+        const newLine = newIdx < newLines.length ? newLines[newIdx] : undefined
+
+        if (oldLine === newLine) {
+            result.push({
+                type: "context",
+                content: oldLine ?? "",
+                lineNumber: startLine + newIdx,
+            })
+            oldIdx++
+            newIdx++
+        } else {
+            if (oldLine !== undefined) {
+                result.push({
+                    type: "remove",
+                    content: oldLine,
+                })
+                oldIdx++
+            }
+            if (newLine !== undefined) {
+                result.push({
+                    type: "add",
+                    content: newLine,
+                    lineNumber: startLine + newIdx,
+                })
+                newIdx++
+            }
+        }
+    }
+
+    return result
+}
+
+function getLinePrefix(line: DiffLine): string {
+    switch (line.type) {
+        case "add": {
+            return "+"
+        }
+        case "remove": {
+            return "-"
+        }
+        case "context": {
+            return " "
+        }
+    }
+}
+
+function getLineColor(line: DiffLine): string {
+    switch (line.type) {
+        case "add": {
+            return "green"
+        }
+        case "remove": {
+            return "red"
+        }
+        case "context": {
+            return "gray"
+        }
+    }
+}
+
+function formatLineNumber(num: number | undefined, width: number): string {
+    if (num === undefined) {
+        return " ".repeat(width)
+    }
+    return String(num).padStart(width, " ")
+}
+
+function DiffLine({
+    line,
+    lineNumberWidth,
+    language,
+    syntaxHighlight,
+}: {
+    line: DiffLine
+    lineNumberWidth: number
+    language?: Language
+    syntaxHighlight?: boolean
+}): React.JSX.Element {
+    const prefix = getLinePrefix(line)
+    const color = getLineColor(line)
+    const lineNum = formatLineNumber(line.lineNumber, lineNumberWidth)
+
+    const shouldHighlight = syntaxHighlight && language && line.type === "add"
+
+    return (
+        <Box>
+            <Text color="gray">{lineNum} </Text>
+            {shouldHighlight ? (
+                <Box>
+                    <Text color={color}>{prefix} </Text>
+                    {highlightLine(line.content, language).map((token, idx) => (
+                        <Text key={idx} color={token.color}>
+                            {token.text}
+                        </Text>
+                    ))}
+                </Box>
+            ) : (
+                <Text color={color}>
+                    {prefix} {line.content}
+                </Text>
+            )}
+        </Box>
+    )
+}
+
+function DiffHeader({
+    filePath,
+    startLine,
+    endLine,
+}: {
+    filePath: string
+    startLine: number
+    endLine: number
+}): React.JSX.Element {
+    const lineRange =
+        startLine === endLine
+            ? `line ${String(startLine)}`
+            : `lines ${String(startLine)}-${String(endLine)}`
+
+    return (
+        <Box>
+            <Text color="gray">┌─── </Text>
+            <Text color="cyan">{filePath}</Text>
+            <Text color="gray"> ({lineRange}) ───┐</Text>
+        </Box>
+    )
+}
+
+function DiffFooter(): React.JSX.Element {
+    return (
+        <Box>
+            <Text color="gray">└───────────────────────────────────────┘</Text>
+        </Box>
+    )
+}
+
+function DiffStats({
+    additions,
+    deletions,
+}: {
+    additions: number
+    deletions: number
+}): React.JSX.Element {
+    return (
+        <Box gap={1} marginTop={1}>
+            <Text color="green">+{String(additions)}</Text>
+            <Text color="red">-{String(deletions)}</Text>
+        </Box>
+    )
+}
+
+export function DiffView({
+    filePath,
+    oldLines,
+    newLines,
+    startLine,
+    language,
+    syntaxHighlight = false,
+}: DiffViewProps): React.JSX.Element {
+    const diffLines = computeDiff(oldLines, newLines, startLine)
+    const endLine = startLine + newLines.length - 1
+    const lineNumberWidth = String(endLine).length
+
+    const additions = diffLines.filter((l) => l.type === "add").length
+    const deletions = diffLines.filter((l) => l.type === "remove").length
+
+    const detectedLanguage = language ?? detectLanguage(filePath)
+
+    return (
+        <Box flexDirection="column" paddingX={1}>
+            <DiffHeader filePath={filePath} startLine={startLine} endLine={endLine} />
+            <Box flexDirection="column" paddingX={1}>
+                {diffLines.map((line, index) => (
+                    <DiffLine
+                        key={`${line.type}-${String(index)}`}
+                        line={line}
+                        lineNumberWidth={lineNumberWidth}
+                        language={detectedLanguage}
+                        syntaxHighlight={syntaxHighlight}
+                    />
+                ))}
+            </Box>
+            <DiffFooter />
+            <DiffStats additions={additions} deletions={deletions} />
+        </Box>
+    )
+}

packages/ipuaro/src/tui/components/EditableContent.tsx

@@ -0,0 +1,146 @@
+/**
+ * EditableContent component for TUI.
+ * Displays editable multi-line text with line-by-line navigation.
+ */
+
+import { Box, Text, useInput } from "ink"
+import TextInput from "ink-text-input"
+import React, { useCallback, useState } from "react"
+
+export interface EditableContentProps {
+    /** Initial lines to edit */
+    lines: string[]
+    /** Called when user finishes editing (Enter key) */
+    onSubmit: (editedLines: string[]) => void
+    /** Called when user cancels editing (Escape key) */
+    onCancel: () => void
+    /** Maximum visible lines before scrolling */
+    maxVisibleLines?: number
+}
+
+/**
+ * EditableContent component.
+ * Allows line-by-line editing of multi-line text.
+ * - Up/Down: Navigate between lines
+ * - Enter (on last line): Submit changes
+ * - Ctrl+Enter: Submit changes from any line
+ * - Escape: Cancel editing
+ */
+export function EditableContent({
+    lines: initialLines,
+    onSubmit,
+    onCancel,
+    maxVisibleLines = 20,
+}: EditableContentProps): React.JSX.Element {
+    const [lines, setLines] = useState<string[]>(initialLines.length > 0 ? initialLines : [""])
+    const [currentLineIndex, setCurrentLineIndex] = useState(0)
+    const [currentLineValue, setCurrentLineValue] = useState(lines[0] ?? "")
+
+    const updateCurrentLine = useCallback(
+        (value: string) => {
+            const newLines = [...lines]
+            newLines[currentLineIndex] = value
+            setLines(newLines)
+            setCurrentLineValue(value)
+        },
+        [lines, currentLineIndex],
+    )
+
+    const handleLineSubmit = useCallback(() => {
+        updateCurrentLine(currentLineValue)
+
+        if (currentLineIndex === lines.length - 1) {
+            onSubmit(lines)
+        } else {
+            const nextIndex = currentLineIndex + 1
+            setCurrentLineIndex(nextIndex)
+            setCurrentLineValue(lines[nextIndex] ?? "")
+        }
+    }, [currentLineValue, currentLineIndex, lines, updateCurrentLine, onSubmit])
+
+    const handleMoveUp = useCallback(() => {
+        if (currentLineIndex > 0) {
+            updateCurrentLine(currentLineValue)
+            const prevIndex = currentLineIndex - 1
+            setCurrentLineIndex(prevIndex)
+            setCurrentLineValue(lines[prevIndex] ?? "")
+        }
+    }, [currentLineIndex, currentLineValue, lines, updateCurrentLine])
+
+    const handleMoveDown = useCallback(() => {
+        if (currentLineIndex < lines.length - 1) {
+            updateCurrentLine(currentLineValue)
+            const nextIndex = currentLineIndex + 1
+            setCurrentLineIndex(nextIndex)
+            setCurrentLineValue(lines[nextIndex] ?? "")
+        }
+    }, [currentLineIndex, currentLineValue, lines, updateCurrentLine])
+
+    const handleCtrlEnter = useCallback(() => {
+        updateCurrentLine(currentLineValue)
+        onSubmit(lines)
+    }, [currentLineValue, lines, updateCurrentLine, onSubmit])
+
+    useInput(
+        (input, key) => {
+            if (key.escape) {
+                onCancel()
+            } else if (key.upArrow) {
+                handleMoveUp()
+            } else if (key.downArrow) {
+                handleMoveDown()
+            } else if (key.ctrl && key.return) {
+                handleCtrlEnter()
+            }
+        },
+        { isActive: true },
+    )
+
+    const startLine = Math.max(0, currentLineIndex - Math.floor(maxVisibleLines / 2))
+    const endLine = Math.min(lines.length, startLine + maxVisibleLines)
+    const visibleLines = lines.slice(startLine, endLine)
+
+    return (
+        <Box flexDirection="column" borderStyle="round" borderColor="cyan" paddingX={1}>
+            <Box marginBottom={1}>
+                <Text color="cyan" bold>
+                    Edit Content (Line {currentLineIndex + 1}/{lines.length})
+                </Text>
+            </Box>
+
+            <Box flexDirection="column" marginBottom={1}>
+                {visibleLines.map((line, idx) => {
+                    const actualIndex = startLine + idx
+                    const isCurrentLine = actualIndex === currentLineIndex
+
+                    return (
+                        <Box key={actualIndex}>
+                            <Text color="gray" dimColor>
+                                {String(actualIndex + 1).padStart(3, " ")}:{" "}
+                            </Text>
+                            {isCurrentLine ? (
+                                <Box>
+                                    <Text color="cyan">▶ </Text>
+                                    <TextInput
+                                        value={currentLineValue}
+                                        onChange={setCurrentLineValue}
+                                        onSubmit={handleLineSubmit}
+                                    />
+                                </Box>
+                            ) : (
+                                <Text color={isCurrentLine ? "cyan" : "white"}>{line}</Text>
+                            )}
+                        </Box>
+                    )
+                })}
+            </Box>
+
+            <Box flexDirection="column" borderStyle="single" borderColor="gray" paddingX={1}>
+                <Text dimColor>↑/↓: Navigate lines</Text>
+                <Text dimColor>Enter: Next line / Submit (last line)</Text>
+                <Text dimColor>Ctrl+Enter: Submit from any line</Text>
+                <Text dimColor>Escape: Cancel</Text>
+            </Box>
+        </Box>
+    )
+}

packages/ipuaro/src/tui/components/ErrorDialog.tsx

@@ -0,0 +1,105 @@
+/**
+ * ErrorDialog component for TUI.
+ * Displays an error with [R] Retry / [S] Skip / [A] Abort options.
+ */
+
+import { Box, Text, useInput } from "ink"
+import React, { useState } from "react"
+import type { ErrorOption } from "../../shared/errors/IpuaroError.js"
+
+export interface ErrorInfo {
+    type: string
+    message: string
+    recoverable: boolean
+}
+
+export interface ErrorDialogProps {
+    error: ErrorInfo
+    onChoice: (choice: ErrorOption) => void
+}
+
+function ChoiceButton({
+    hotkey,
+    label,
+    isSelected,
+    disabled,
+}: {
+    hotkey: string
+    label: string
+    isSelected: boolean
+    disabled?: boolean
+}): React.JSX.Element {
+    if (disabled) {
+        return (
+            <Box>
+                <Text color="gray" dimColor>
+                    [{hotkey}] {label}
+                </Text>
+            </Box>
+        )
+    }
+
+    return (
+        <Box>
+            <Text color={isSelected ? "cyan" : "gray"}>
+                [<Text bold>{hotkey}</Text>] {label}
+            </Text>
+        </Box>
+    )
+}
+
+export function ErrorDialog({ error, onChoice }: ErrorDialogProps): React.JSX.Element {
+    const [selected, setSelected] = useState<ErrorOption | null>(null)
+
+    useInput((input, key) => {
+        const lowerInput = input.toLowerCase()
+
+        if (lowerInput === "r" && error.recoverable) {
+            setSelected("retry")
+            onChoice("retry")
+        } else if (lowerInput === "s" && error.recoverable) {
+            setSelected("skip")
+            onChoice("skip")
+        } else if (lowerInput === "a") {
+            setSelected("abort")
+            onChoice("abort")
+        } else if (key.escape) {
+            setSelected("abort")
+            onChoice("abort")
+        }
+    })
+
+    return (
+        <Box flexDirection="column" borderStyle="round" borderColor="red" paddingX={1} paddingY={1}>
+            <Box marginBottom={1}>
+                <Text color="red" bold>
+                    x {error.type}: {error.message}
+                </Text>
+            </Box>
+
+            <Box gap={2}>
+                <ChoiceButton
+                    hotkey="R"
+                    label="Retry"
+                    isSelected={selected === "retry"}
+                    disabled={!error.recoverable}
+                />
+                <ChoiceButton
+                    hotkey="S"
+                    label="Skip"
+                    isSelected={selected === "skip"}
+                    disabled={!error.recoverable}
+                />
+                <ChoiceButton hotkey="A" label="Abort" isSelected={selected === "abort"} />
+            </Box>
+
+            {!error.recoverable && (
+                <Box marginTop={1}>
+                    <Text color="gray" dimColor>
+                        This error is not recoverable. Press [A] to abort.
+                    </Text>
+                </Box>
+            )}
+        </Box>
+    )
+}

packages/ipuaro/src/tui/components/Input.tsx

@@ -0,0 +1,250 @@
+/**
+ * Input component for TUI.
+ * Prompt with history navigation (up/down) and path autocomplete (tab).
+ */
+
+import { Box, Text, useInput } from "ink"
+import TextInput from "ink-text-input"
+import React, { useCallback, useState } from "react"
+import type { IStorage } from "../../domain/services/IStorage.js"
+import { useAutocomplete } from "../hooks/useAutocomplete.js"
+
+export interface InputProps {
+    onSubmit: (text: string) => void
+    history: string[]
+    disabled: boolean
+    placeholder?: string
+    storage?: IStorage
+    projectRoot?: string
+    autocompleteEnabled?: boolean
+    multiline?: boolean | "auto"
+}
+
+export function Input({
+    onSubmit,
+    history,
+    disabled,
+    placeholder = "Type a message...",
+    storage,
+    projectRoot = "",
+    autocompleteEnabled = true,
+    multiline = false,
+}: InputProps): React.JSX.Element {
+    const [value, setValue] = useState("")
+    const [historyIndex, setHistoryIndex] = useState(-1)
+    const [savedInput, setSavedInput] = useState("")
+    const [lines, setLines] = useState<string[]>([""])
+    const [currentLineIndex, setCurrentLineIndex] = useState(0)
+
+    const isMultilineActive = multiline === true || (multiline === "auto" && lines.length > 1)
+
+    /*
+     * Initialize autocomplete hook if storage is provided
+     * Create a dummy storage object if storage is not provided (autocomplete will be disabled)
+     */
+    const dummyStorage = {} as IStorage
+    const autocomplete = useAutocomplete({
+        storage: storage ?? dummyStorage,
+        projectRoot,
+        enabled: autocompleteEnabled && !!storage,
+    })
+
+    const handleChange = useCallback(
+        (newValue: string) => {
+            setValue(newValue)
+            setHistoryIndex(-1)
+            // Update autocomplete suggestions as user types
+            if (storage && autocompleteEnabled) {
+                autocomplete.complete(newValue)
+            }
+        },
+        [storage, autocompleteEnabled, autocomplete],
+    )
+
+    const handleSubmit = useCallback(
+        (text: string) => {
+            if (disabled || !text.trim()) {
+                return
+            }
+            onSubmit(text)
+            setValue("")
+            setLines([""])
+            setCurrentLineIndex(0)
+            setHistoryIndex(-1)
+            setSavedInput("")
+            autocomplete.reset()
+        },
+        [disabled, onSubmit, autocomplete],
+    )
+
+    const handleLineChange = useCallback(
+        (newValue: string) => {
+            const newLines = [...lines]
+            newLines[currentLineIndex] = newValue
+            setLines(newLines)
+            setValue(newLines.join("\n"))
+        },
+        [lines, currentLineIndex],
+    )
+
+    const handleAddLine = useCallback(() => {
+        const newLines = [...lines]
+        newLines.splice(currentLineIndex + 1, 0, "")
+        setLines(newLines)
+        setCurrentLineIndex(currentLineIndex + 1)
+        setValue(newLines.join("\n"))
+    }, [lines, currentLineIndex])
+
+    const handleMultilineSubmit = useCallback(() => {
+        const fullText = lines.join("\n").trim()
+        if (fullText) {
+            handleSubmit(fullText)
+        }
+    }, [lines, handleSubmit])
+
+    const handleTabKey = useCallback(() => {
+        if (storage && autocompleteEnabled && value.trim()) {
+            const suggestions = autocomplete.suggestions
+            if (suggestions.length > 0) {
+                const completed = autocomplete.accept(value)
+                setValue(completed)
+                autocomplete.complete(completed)
+            }
+        }
+    }, [storage, autocompleteEnabled, value, autocomplete])
+
+    const handleUpArrow = useCallback(() => {
+        if (history.length > 0) {
+            if (historyIndex === -1) {
+                setSavedInput(value)
+            }
+            const newIndex =
+                historyIndex === -1 ? history.length - 1 : Math.max(0, historyIndex - 1)
+            setHistoryIndex(newIndex)
+            setValue(history[newIndex] ?? "")
+            autocomplete.reset()
+        }
+    }, [history, historyIndex, value, autocomplete])
+
+    const handleDownArrow = useCallback(() => {
+        if (historyIndex === -1) {
+            return
+        }
+        if (historyIndex >= history.length - 1) {
+            setHistoryIndex(-1)
+            setValue(savedInput)
+        } else {
+            const newIndex = historyIndex + 1
+            setHistoryIndex(newIndex)
+            setValue(history[newIndex] ?? "")
+        }
+        autocomplete.reset()
+    }, [historyIndex, history, savedInput, autocomplete])
+
+    useInput(
+        (input, key) => {
+            if (disabled) {
+                return
+            }
+            if (key.tab) {
+                handleTabKey()
+            }
+            if (key.return && key.shift && isMultilineActive) {
+                handleAddLine()
+            }
+            if (key.upArrow) {
+                if (isMultilineActive && currentLineIndex > 0) {
+                    setCurrentLineIndex(currentLineIndex - 1)
+                } else if (!isMultilineActive) {
+                    handleUpArrow()
+                }
+            }
+            if (key.downArrow) {
+                if (isMultilineActive && currentLineIndex < lines.length - 1) {
+                    setCurrentLineIndex(currentLineIndex + 1)
+                } else if (!isMultilineActive) {
+                    handleDownArrow()
+                }
+            }
+        },
+        { isActive: !disabled },
+    )
+
+    const hasSuggestions = autocomplete.suggestions.length > 0
+
+    return (
+        <Box flexDirection="column">
+            <Box
+                borderStyle="single"
+                borderColor={disabled ? "gray" : "cyan"}
+                paddingX={1}
+                flexDirection="column"
+            >
+                {disabled ? (
+                    <Box>
+                        <Text color="gray" bold>
+                            {">"}{" "}
+                        </Text>
+                        <Text color="gray" dimColor>
+                            {placeholder}
+                        </Text>
+                    </Box>
+                ) : isMultilineActive ? (
+                    <Box flexDirection="column">
+                        {lines.map((line, index) => (
+                            <Box key={index}>
+                                <Text color="green" bold>
+                                    {index === currentLineIndex ? ">" : " "}{" "}
+                                </Text>
+                                {index === currentLineIndex ? (
+                                    <TextInput
+                                        value={line}
+                                        onChange={handleLineChange}
+                                        onSubmit={handleMultilineSubmit}
+                                        placeholder={index === 0 ? placeholder : ""}
+                                    />
+                                ) : (
+                                    <Text>{line}</Text>
+                                )}
+                            </Box>
+                        ))}
+                        <Box marginTop={1}>
+                            <Text dimColor>Shift+Enter: new line | Enter: submit</Text>
+                        </Box>
+                    </Box>
+                ) : (
+                    <Box>
+                        <Text color="green" bold>
+                            {">"}{" "}
+                        </Text>
+                        <TextInput
+                            value={value}
+                            onChange={handleChange}
+                            onSubmit={handleSubmit}
+                            placeholder={placeholder}
+                        />
+                    </Box>
+                )}
+            </Box>
+            {hasSuggestions && !disabled && (
+                <Box paddingLeft={2} flexDirection="column">
+                    <Text dimColor>
+                        {autocomplete.suggestions.length === 1
+                            ? "Press Tab to complete"
+                            : `${String(autocomplete.suggestions.length)} suggestions (Tab to complete)`}
+                    </Text>
+                    {autocomplete.suggestions.slice(0, 5).map((suggestion, i) => (
+                        <Text key={i} dimColor color="cyan">
+                            {"  "}• {suggestion}
+                        </Text>
+                    ))}
+                    {autocomplete.suggestions.length > 5 && (
+                        <Text dimColor>
+                            {"  "}... and {String(autocomplete.suggestions.length - 5)} more
+                        </Text>
+                    )}
+                </Box>
+            )}
+        </Box>
+    )
+}

packages/ipuaro/src/tui/components/Progress.tsx

@@ -0,0 +1,62 @@
+/**
+ * Progress component for TUI.
+ * Displays a progress bar: [=====>    ] 45% (120/267 files)
+ */
+
+import { Box, Text } from "ink"
+import type React from "react"
+
+export interface ProgressProps {
+    current: number
+    total: number
+    label: string
+    width?: number
+}
+
+function calculatePercentage(current: number, total: number): number {
+    if (total === 0) {
+        return 0
+    }
+    return Math.min(100, Math.round((current / total) * 100))
+}
+
+function createProgressBar(percentage: number, width: number): { filled: string; empty: string } {
+    const filledWidth = Math.round((percentage / 100) * width)
+    const emptyWidth = width - filledWidth
+
+    const filled = "=".repeat(Math.max(0, filledWidth - 1)) + (filledWidth > 0 ? ">" : "")
+    const empty = " ".repeat(Math.max(0, emptyWidth))
+
+    return { filled, empty }
+}
+
+function getProgressColor(percentage: number): string {
+    if (percentage >= 100) {
+        return "green"
+    }
+    if (percentage >= 50) {
+        return "yellow"
+    }
+    return "cyan"
+}
+
+export function Progress({ current, total, label, width = 30 }: ProgressProps): React.JSX.Element {
+    const percentage = calculatePercentage(current, total)
+    const { filled, empty } = createProgressBar(percentage, width)
+    const color = getProgressColor(percentage)
+
+    return (
+        <Box gap={1}>
+            <Text color="gray">[</Text>
+            <Text color={color}>{filled}</Text>
+            <Text color="gray">{empty}</Text>
+            <Text color="gray">]</Text>
+            <Text color={color} bold>
+                {String(percentage)}%
+            </Text>
+            <Text color="gray">
+                ({String(current)}/{String(total)} {label})
+            </Text>
+        </Box>
+    )
+}

packages/ipuaro/src/tui/components/StatusBar.tsx

@@ -0,0 +1,83 @@
+/**
+ * StatusBar component for TUI.
+ * Displays: [ipuaro] [ctx: 12%] [project: myapp] [main] [47m] status
+ */
+
+import { Box, Text } from "ink"
+import type React from "react"
+import type { BranchInfo, TuiStatus } from "../types.js"
+import { getContextColor, getStatusColor, type Theme } from "../utils/theme.js"
+
+export interface StatusBarProps {
+    contextUsage: number
+    projectName: string
+    branch: BranchInfo
+    sessionTime: string
+    status: TuiStatus
+    theme?: Theme
+}
+
+function getStatusIndicator(status: TuiStatus, theme: Theme): { text: string; color: string } {
+    const color = getStatusColor(status, theme)
+
+    switch (status) {
+        case "ready": {
+            return { text: "ready", color }
+        }
+        case "thinking": {
+            return { text: "thinking...", color }
+        }
+        case "tool_call": {
+            return { text: "executing...", color }
+        }
+        case "awaiting_confirmation": {
+            return { text: "confirm?", color }
+        }
+        case "error": {
+            return { text: "error", color }
+        }
+        default: {
+            return { text: "ready", color }
+        }
+    }
+}
+
+function formatContextUsage(usage: number): string {
+    return `${String(Math.round(usage * 100))}%`
+}
+
+export function StatusBar({
+    contextUsage,
+    projectName,
+    branch,
+    sessionTime,
+    status,
+    theme = "dark",
+}: StatusBarProps): React.JSX.Element {
+    const statusIndicator = getStatusIndicator(status, theme)
+    const branchDisplay = branch.isDetached ? `HEAD@${branch.name.slice(0, 7)}` : branch.name
+    const contextColor = getContextColor(contextUsage, theme)
+
+    return (
+        <Box borderStyle="single" borderColor="gray" paddingX={1} justifyContent="space-between">
+            <Box gap={1}>
+                <Text color="cyan" bold>
+                    [ipuaro]
+                </Text>
+                <Text color="gray">
+                    [ctx: <Text color={contextColor}>{formatContextUsage(contextUsage)}</Text>]
+                </Text>
+                <Text color="gray">
+                    [<Text color="blue">{projectName}</Text>]
+                </Text>
+                <Text color="gray">
+                    [<Text color="green">{branchDisplay}</Text>]
+                </Text>
+                <Text color="gray">
+                    [<Text color="white">{sessionTime}</Text>]
+                </Text>
+            </Box>
+            <Text color={statusIndicator.color}>{statusIndicator.text}</Text>
+        </Box>
+    )
+}

packages/ipuaro/src/tui/components/index.ts

@@ -0,0 +1,12 @@
+/**
+ * TUI components.
+ */
+
+export { StatusBar, type StatusBarProps } from "./StatusBar.js"
+export { Chat, type ChatProps } from "./Chat.js"
+export { Input, type InputProps } from "./Input.js"
+export { DiffView, type DiffViewProps } from "./DiffView.js"
+export { ConfirmDialog, type ConfirmDialogProps } from "./ConfirmDialog.js"
+export { ErrorDialog, type ErrorDialogProps, type ErrorInfo } from "./ErrorDialog.js"
+export { Progress, type ProgressProps } from "./Progress.js"
+export { EditableContent, type EditableContentProps } from "./EditableContent.js"

packages/ipuaro/src/tui/hooks/index.ts

@@ -0,0 +1,26 @@
+/**
+ * TUI hooks.
+ */
+
+export {
+    useSession,
+    type UseSessionDependencies,
+    type UseSessionOptions,
+    type UseSessionReturn,
+} from "./useSession.js"
+export { useHotkeys, type HotkeyHandlers, type UseHotkeysOptions } from "./useHotkeys.js"
+export {
+    useCommands,
+    parseCommand,
+    type UseCommandsDependencies,
+    type UseCommandsActions,
+    type UseCommandsOptions,
+    type UseCommandsReturn,
+    type CommandResult,
+    type CommandDefinition,
+} from "./useCommands.js"
+export {
+    useAutocomplete,
+    type UseAutocompleteOptions,
+    type UseAutocompleteReturn,
+} from "./useAutocomplete.js"

packages/ipuaro/src/tui/hooks/useAutocomplete.ts

@@ -0,0 +1,204 @@
+/**
+ * useAutocomplete hook for file path autocomplete.
+ * Provides Tab completion for file paths using Redis index.
+ */
+
+import { useCallback, useEffect, useState } from "react"
+import type { IStorage } from "../../domain/services/IStorage.js"
+import type { AutocompleteConfig } from "../../shared/constants/config.js"
+import path from "node:path"
+
+export interface UseAutocompleteOptions {
+    storage: IStorage
+    projectRoot: string
+    enabled?: boolean
+    maxSuggestions?: number
+    config?: AutocompleteConfig
+}
+
+export interface UseAutocompleteReturn {
+    suggestions: string[]
+    complete: (partial: string) => string[]
+    accept: (suggestion: string) => string
+    reset: () => void
+}
+
+/**
+ * Normalizes a path by removing leading ./ and trailing /
+ */
+function normalizePath(p: string): string {
+    let normalized = p.trim()
+    if (normalized.startsWith("./")) {
+        normalized = normalized.slice(2)
+    }
+    if (normalized.endsWith("/") && normalized.length > 1) {
+        normalized = normalized.slice(0, -1)
+    }
+    return normalized
+}
+
+/**
+ * Calculates fuzzy match score between partial and candidate.
+ * Returns 0 if no match, higher score for better matches.
+ */
+function fuzzyScore(partial: string, candidate: string): number {
+    const partialLower = partial.toLowerCase()
+    const candidateLower = candidate.toLowerCase()
+
+    // Exact prefix match gets highest score
+    if (candidateLower.startsWith(partialLower)) {
+        return 1000 + (1000 - partial.length)
+    }
+
+    // Check if all characters from partial appear in order in candidate
+    let partialIndex = 0
+    let candidateIndex = 0
+    let lastMatchIndex = -1
+    let consecutiveMatches = 0
+
+    while (partialIndex < partialLower.length && candidateIndex < candidateLower.length) {
+        if (partialLower[partialIndex] === candidateLower[candidateIndex]) {
+            // Bonus for consecutive matches
+            if (candidateIndex === lastMatchIndex + 1) {
+                consecutiveMatches++
+            } else {
+                consecutiveMatches = 0
+            }
+            lastMatchIndex = candidateIndex
+            partialIndex++
+        }
+        candidateIndex++
+    }
+
+    // If we didn't match all characters, no match
+    if (partialIndex < partialLower.length) {
+        return 0
+    }
+
+    // Score based on how tight the match is
+    const matchSpread = lastMatchIndex - (partialLower.length - 1)
+    const score = 100 + consecutiveMatches * 10 - matchSpread
+
+    return Math.max(0, score)
+}
+
+/**
+ * Gets the common prefix of all suggestions
+ */
+function getCommonPrefix(suggestions: string[]): string {
+    if (suggestions.length === 0) {
+        return ""
+    }
+    if (suggestions.length === 1) {
+        return suggestions[0] ?? ""
+    }
+
+    let prefix = suggestions[0] ?? ""
+    for (let i = 1; i < suggestions.length; i++) {
+        const current = suggestions[i] ?? ""
+        let j = 0
+        while (j < prefix.length && j < current.length && prefix[j] === current[j]) {
+            j++
+        }
+        prefix = prefix.slice(0, j)
+        if (prefix.length === 0) {
+            break
+        }
+    }
+    return prefix
+}
+
+export function useAutocomplete(options: UseAutocompleteOptions): UseAutocompleteReturn {
+    const { storage, projectRoot, enabled, maxSuggestions, config } = options
+
+    // Read from config if provided, otherwise use options, otherwise use defaults
+    const isEnabled = config?.enabled ?? enabled ?? true
+    const maxSuggestionsCount = config?.maxSuggestions ?? maxSuggestions ?? 10
+
+    const [filePaths, setFilePaths] = useState<string[]>([])
+    const [suggestions, setSuggestions] = useState<string[]>([])
+
+    // Load file paths from storage
+    useEffect(() => {
+        if (!isEnabled) {
+            return
+        }
+
+        const loadPaths = async (): Promise<void> => {
+            try {
+                const files = await storage.getAllFiles()
+                const paths = Array.from(files.keys()).map((p) => {
+                    // Make paths relative to project root
+                    const relative = path.relative(projectRoot, p)
+                    return normalizePath(relative)
+                })
+                setFilePaths(paths.sort())
+            } catch {
+                // Silently fail - autocomplete is non-critical
+                setFilePaths([])
+            }
+        }
+
+        loadPaths().catch(() => {
+            // Ignore errors
+        })
+    }, [storage, projectRoot, isEnabled])
+
+    const complete = useCallback(
+        (partial: string): string[] => {
+            if (!isEnabled || !partial.trim()) {
+                setSuggestions([])
+                return []
+            }
+
+            const normalized = normalizePath(partial)
+
+            // Score and filter matches
+            const scored = filePaths
+                .map((p) => ({
+                    path: p,
+                    score: fuzzyScore(normalized, p),
+                }))
+                .filter((item) => item.score > 0)
+                .sort((a, b) => b.score - a.score)
+                .slice(0, maxSuggestionsCount)
+                .map((item) => item.path)
+
+            setSuggestions(scored)
+            return scored
+        },
+        [isEnabled, filePaths, maxSuggestionsCount],
+    )
+
+    const accept = useCallback(
+        (suggestion: string): string => {
+            // If there's only one suggestion, complete with it
+            if (suggestions.length === 1) {
+                setSuggestions([])
+                return suggestions[0] ?? ""
+            }
+
+            // If there are multiple suggestions, complete with common prefix
+            if (suggestions.length > 1) {
+                const prefix = getCommonPrefix(suggestions)
+                if (prefix.length > suggestion.length) {
+                    return prefix
+                }
+            }
+
+            return suggestion
+        },
+        [suggestions],
+    )
+
+    const reset = useCallback(() => {
+        setSuggestions([])
+    }, [])
+
+    return {
+        suggestions,
+        complete,
+        accept,
+        reset,
+    }
+}

packages/ipuaro/src/tui/hooks/useCommands.ts

@@ -0,0 +1,444 @@
+/**
+ * useCommands hook for TUI.
+ * Handles slash commands (/help, /clear, /undo, etc.)
+ */
+
+import { useCallback, useMemo } from "react"
+import type { Session } from "../../domain/entities/Session.js"
+import type { ILLMClient } from "../../domain/services/ILLMClient.js"
+import type { ISessionStorage } from "../../domain/services/ISessionStorage.js"
+import type { IStorage } from "../../domain/services/IStorage.js"
+import type { IToolRegistry } from "../../application/interfaces/IToolRegistry.js"
+
+/**
+ * Command result returned after execution.
+ */
+export interface CommandResult {
+    success: boolean
+    message: string
+    data?: unknown
+}
+
+/**
+ * Command definition.
+ */
+export interface CommandDefinition {
+    name: string
+    description: string
+    usage: string
+    execute: (args: string[]) => Promise<CommandResult>
+}
+
+/**
+ * Dependencies for useCommands hook.
+ */
+export interface UseCommandsDependencies {
+    session: Session | null
+    sessionStorage: ISessionStorage
+    storage: IStorage
+    llm: ILLMClient
+    tools: IToolRegistry
+    projectRoot: string
+    projectName: string
+}
+
+/**
+ * Actions provided by the parent component.
+ */
+export interface UseCommandsActions {
+    clearHistory: () => void
+    undo: () => Promise<boolean>
+    setAutoApply: (value: boolean) => void
+    reindex: () => Promise<void>
+}
+
+/**
+ * Options for useCommands hook.
+ */
+export interface UseCommandsOptions {
+    autoApply: boolean
+}
+
+/**
+ * Return type for useCommands hook.
+ */
+export interface UseCommandsReturn {
+    executeCommand: (input: string) => Promise<CommandResult | null>
+    isCommand: (input: string) => boolean
+    getCommands: () => CommandDefinition[]
+}
+
+/**
+ * Parses command input into command name and arguments.
+ */
+export function parseCommand(input: string): { command: string; args: string[] } | null {
+    const trimmed = input.trim()
+    if (!trimmed.startsWith("/")) {
+        return null
+    }
+
+    const parts = trimmed.slice(1).split(/\s+/)
+    const command = parts[0]?.toLowerCase() ?? ""
+    const args = parts.slice(1)
+
+    return { command, args }
+}
+
+// Command factory functions to keep the hook clean and under line limits
+
+function createHelpCommand(map: Map<string, CommandDefinition>): CommandDefinition {
+    return {
+        name: "help",
+        description: "Shows all commands and hotkeys",
+        usage: "/help",
+        execute: async (): Promise<CommandResult> => {
+            const commandList = Array.from(map.values())
+                .map((cmd) => `  ${cmd.usage.padEnd(25)} ${cmd.description}`)
+                .join("\n")
+
+            const hotkeys = [
+                "  Ctrl+C (1x)              Interrupt current operation",
+                "  Ctrl+C (2x)              Exit ipuaro",
+                "  Ctrl+D                   Exit with session save",
+                "  Ctrl+Z                   Undo last change",
+                "  ↑/↓                      Navigate input history",
+            ].join("\n")
+
+            const message = ["Available commands:", commandList, "", "Hotkeys:", hotkeys].join("\n")
+
+            return Promise.resolve({ success: true, message })
+        },
+    }
+}
+
+function createClearCommand(actions: UseCommandsActions): CommandDefinition {
+    return {
+        name: "clear",
+        description: "Clears chat history (keeps session)",
+        usage: "/clear",
+        execute: async (): Promise<CommandResult> => {
+            actions.clearHistory()
+            return Promise.resolve({ success: true, message: "Chat history cleared." })
+        },
+    }
+}
+
+function createUndoCommand(
+    deps: UseCommandsDependencies,
+    actions: UseCommandsActions,
+): CommandDefinition {
+    return {
+        name: "undo",
+        description: "Reverts last file change",
+        usage: "/undo",
+        execute: async (): Promise<CommandResult> => {
+            if (!deps.session) {
+                return { success: false, message: "No active session." }
+            }
+
+            const undoStack = deps.session.undoStack
+            if (undoStack.length === 0) {
+                return { success: false, message: "Nothing to undo." }
+            }
+
+            const result = await actions.undo()
+            if (result) {
+                return { success: true, message: "Last change reverted." }
+            }
+            return { success: false, message: "Failed to undo. File may have been modified." }
+        },
+    }
+}
+
+function createSessionsCommand(deps: UseCommandsDependencies): CommandDefinition {
+    return {
+        name: "sessions",
+        description: "Manage sessions (list, load <id>, delete <id>)",
+        usage: "/sessions [list|load|delete] [id]",
+        execute: async (args: string[]): Promise<CommandResult> => {
+            const subCommand = args[0]?.toLowerCase() ?? "list"
+
+            if (subCommand === "list") {
+                return handleSessionsList(deps)
+            }
+
+            if (subCommand === "load") {
+                return handleSessionsLoad(deps, args[1])
+            }
+
+            if (subCommand === "delete") {
+                return handleSessionsDelete(deps, args[1])
+            }
+
+            return { success: false, message: "Usage: /sessions [list|load|delete] [id]" }
+        },
+    }
+}
+
+async function handleSessionsList(deps: UseCommandsDependencies): Promise<CommandResult> {
+    const sessions = await deps.sessionStorage.listSessions(deps.projectName)
+    if (sessions.length === 0) {
+        return { success: true, message: "No sessions found." }
+    }
+
+    const currentId = deps.session?.id
+    const sessionList = sessions
+        .map((s) => {
+            const current = s.id === currentId ? " (current)" : ""
+            const date = new Date(s.createdAt).toLocaleString()
+            return `  ${s.id.slice(0, 8)}${current} - ${date} - ${String(s.messageCount)} messages`
+        })
+        .join("\n")
+
+    return {
+        success: true,
+        message: `Sessions for ${deps.projectName}:\n${sessionList}`,
+        data: sessions,
+    }
+}
+
+async function handleSessionsLoad(
+    deps: UseCommandsDependencies,
+    sessionId: string | undefined,
+): Promise<CommandResult> {
+    if (!sessionId) {
+        return { success: false, message: "Usage: /sessions load <id>" }
+    }
+
+    const exists = await deps.sessionStorage.sessionExists(sessionId)
+    if (!exists) {
+        return { success: false, message: `Session ${sessionId} not found.` }
+    }
+
+    return {
+        success: true,
+        message: `To load session ${sessionId}, restart ipuaro with --session ${sessionId}`,
+        data: { sessionId },
+    }
+}
+
+async function handleSessionsDelete(
+    deps: UseCommandsDependencies,
+    sessionId: string | undefined,
+): Promise<CommandResult> {
+    if (!sessionId) {
+        return { success: false, message: "Usage: /sessions delete <id>" }
+    }
+
+    if (deps.session?.id === sessionId) {
+        return { success: false, message: "Cannot delete current session." }
+    }
+
+    const exists = await deps.sessionStorage.sessionExists(sessionId)
+    if (!exists) {
+        return { success: false, message: `Session ${sessionId} not found.` }
+    }
+
+    await deps.sessionStorage.deleteSession(sessionId)
+    return { success: true, message: `Session ${sessionId} deleted.` }
+}
+
+function createStatusCommand(
+    deps: UseCommandsDependencies,
+    options: UseCommandsOptions,
+): CommandDefinition {
+    return {
+        name: "status",
+        description: "Shows system and session status",
+        usage: "/status",
+        execute: async (): Promise<CommandResult> => {
+            const llmAvailable = await deps.llm.isAvailable()
+            const llmStatus = llmAvailable ? "connected" : "unavailable"
+
+            const contextUsage = deps.session?.context.tokenUsage ?? 0
+            const contextPercent = Math.round(contextUsage * 100)
+
+            const sessionStats = deps.session?.stats ?? {
+                totalTokens: 0,
+                totalTime: 0,
+                toolCalls: 0,
+                editsApplied: 0,
+                editsRejected: 0,
+            }
+
+            const undoCount = deps.session?.undoStack.length ?? 0
+
+            const message = [
+                "System Status:",
+                `  LLM:          ${llmStatus}`,
+                `  Context:      ${String(contextPercent)}% used`,
+                `  Auto-apply:   ${options.autoApply ? "on" : "off"}`,
+                "",
+                "Session Stats:",
+                `  Tokens:       ${sessionStats.totalTokens.toLocaleString()}`,
+                `  Tool calls:   ${String(sessionStats.toolCalls)}`,
+                `  Edits:        ${String(sessionStats.editsApplied)} applied, ${String(sessionStats.editsRejected)} rejected`,
+                `  Undo stack:   ${String(undoCount)} entries`,
+                "",
+                "Project:",
+                `  Name:         ${deps.projectName}`,
+                `  Root:         ${deps.projectRoot}`,
+            ].join("\n")
+
+            return { success: true, message }
+        },
+    }
+}
+
+function createReindexCommand(actions: UseCommandsActions): CommandDefinition {
+    return {
+        name: "reindex",
+        description: "Forces full project reindexation",
+        usage: "/reindex",
+        execute: async (): Promise<CommandResult> => {
+            try {
+                await actions.reindex()
+                return { success: true, message: "Project reindexed successfully." }
+            } catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err)
+                return { success: false, message: `Reindex failed: ${errorMessage}` }
+            }
+        },
+    }
+}
+
+function createEvalCommand(deps: UseCommandsDependencies): CommandDefinition {
+    return {
+        name: "eval",
+        description: "LLM self-check for hallucinations",
+        usage: "/eval",
+        execute: async (): Promise<CommandResult> => {
+            if (!deps.session || deps.session.history.length === 0) {
+                return { success: false, message: "No conversation to evaluate." }
+            }
+
+            const lastAssistantMessage = [...deps.session.history]
+                .reverse()
+                .find((m) => m.role === "assistant")
+
+            if (!lastAssistantMessage) {
+                return { success: false, message: "No assistant response to evaluate." }
+            }
+
+            const evalPrompt = [
+                "Review your last response for potential issues:",
+                "1. Are there any factual errors or hallucinations?",
+                "2. Did you reference files or code that might not exist?",
+                "3. Are there any assumptions that should be verified?",
+                "",
+                "Last response to evaluate:",
+                lastAssistantMessage.content.slice(0, 2000),
+            ].join("\n")
+
+            try {
+                const response = await deps.llm.chat([
+                    { role: "user", content: evalPrompt, timestamp: Date.now() },
+                ])
+
+                return {
+                    success: true,
+                    message: `Self-evaluation:\n${response.content}`,
+                    data: { evaluated: lastAssistantMessage.content.slice(0, 100) },
+                }
+            } catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err)
+                return { success: false, message: `Evaluation failed: ${errorMessage}` }
+            }
+        },
+    }
+}
+
+function createAutoApplyCommand(
+    actions: UseCommandsActions,
+    options: UseCommandsOptions,
+): CommandDefinition {
+    return {
+        name: "auto-apply",
+        description: "Toggle auto-apply mode (on/off)",
+        usage: "/auto-apply [on|off]",
+        execute: async (args: string[]): Promise<CommandResult> => {
+            const arg = args[0]?.toLowerCase()
+
+            if (arg === "on") {
+                actions.setAutoApply(true)
+                return Promise.resolve({ success: true, message: "Auto-apply enabled." })
+            }
+
+            if (arg === "off") {
+                actions.setAutoApply(false)
+                return Promise.resolve({ success: true, message: "Auto-apply disabled." })
+            }
+
+            if (!arg) {
+                const current = options.autoApply ? "on" : "off"
+                return Promise.resolve({
+                    success: true,
+                    message: `Auto-apply is currently: ${current}`,
+                })
+            }
+
+            return Promise.resolve({ success: false, message: "Usage: /auto-apply [on|off]" })
+        },
+    }
+}
+
+/**
+ * Hook for handling slash commands in TUI.
+ */
+export function useCommands(
+    deps: UseCommandsDependencies,
+    actions: UseCommandsActions,
+    options: UseCommandsOptions,
+): UseCommandsReturn {
+    const commands = useMemo((): Map<string, CommandDefinition> => {
+        const map = new Map<string, CommandDefinition>()
+
+        // Register all commands
+        const helpCmd = createHelpCommand(map)
+        map.set("help", helpCmd)
+        map.set("clear", createClearCommand(actions))
+        map.set("undo", createUndoCommand(deps, actions))
+        map.set("sessions", createSessionsCommand(deps))
+        map.set("status", createStatusCommand(deps, options))
+        map.set("reindex", createReindexCommand(actions))
+        map.set("eval", createEvalCommand(deps))
+        map.set("auto-apply", createAutoApplyCommand(actions, options))
+
+        return map
+    }, [deps, actions, options])
+
+    const isCommand = useCallback((input: string): boolean => {
+        return input.trim().startsWith("/")
+    }, [])
+
+    const executeCommand = useCallback(
+        async (input: string): Promise<CommandResult | null> => {
+            const parsed = parseCommand(input)
+            if (!parsed) {
+                return null
+            }
+
+            const command = commands.get(parsed.command)
+            if (!command) {
+                const available = Array.from(commands.keys()).join(", ")
+                return {
+                    success: false,
+                    message: `Unknown command: /${parsed.command}\nAvailable: ${available}`,
+                }
+            }
+
+            return command.execute(parsed.args)
+        },
+        [commands],
+    )
+
+    const getCommands = useCallback((): CommandDefinition[] => {
+        return Array.from(commands.values())
+    }, [commands])
+
+    return {
+        executeCommand,
+        isCommand,
+        getCommands,
+    }
+}

packages/ipuaro/src/tui/hooks/useHotkeys.ts

@@ -0,0 +1,59 @@
+/**
+ * useHotkeys hook for TUI.
+ * Handles global keyboard shortcuts.
+ */
+
+import { useInput } from "ink"
+import { useCallback, useRef } from "react"
+
+export interface HotkeyHandlers {
+    onInterrupt?: () => void
+    onExit?: () => void
+    onUndo?: () => void
+}
+
+export interface UseHotkeysOptions {
+    enabled?: boolean
+}
+
+export function useHotkeys(handlers: HotkeyHandlers, options: UseHotkeysOptions = {}): void {
+    const { enabled = true } = options
+    const interruptCount = useRef(0)
+    const interruptTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+    const resetInterruptCount = useCallback((): void => {
+        interruptCount.current = 0
+        if (interruptTimer.current) {
+            clearTimeout(interruptTimer.current)
+            interruptTimer.current = null
+        }
+    }, [])
+
+    useInput(
+        (_input, key) => {
+            if (key.ctrl && _input === "c") {
+                interruptCount.current++
+
+                if (interruptCount.current === 1) {
+                    handlers.onInterrupt?.()
+
+                    interruptTimer.current = setTimeout(() => {
+                        resetInterruptCount()
+                    }, 1000)
+                } else if (interruptCount.current >= 2) {
+                    resetInterruptCount()
+                    handlers.onExit?.()
+                }
+            }
+
+            if (key.ctrl && _input === "d") {
+                handlers.onExit?.()
+            }
+
+            if (key.ctrl && _input === "z") {
+                handlers.onUndo?.()
+            }
+        },
+        { isActive: enabled },
+    )
+}

packages/ipuaro/src/tui/hooks/useSession.ts

@@ -0,0 +1,214 @@
+/**
+ * useSession hook for TUI.
+ * Manages session state and message handling.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import type { Session } from "../../domain/entities/Session.js"
+import type { ILLMClient } from "../../domain/services/ILLMClient.js"
+import type { ISessionStorage } from "../../domain/services/ISessionStorage.js"
+import type { IStorage } from "../../domain/services/IStorage.js"
+import type { DiffInfo } from "../../domain/services/ITool.js"
+import type { ChatMessage } from "../../domain/value-objects/ChatMessage.js"
+import type { ErrorOption } from "../../shared/errors/IpuaroError.js"
+import type { Config } from "../../shared/constants/config.js"
+import type { IToolRegistry } from "../../application/interfaces/IToolRegistry.js"
+import {
+    HandleMessage,
+    type HandleMessageStatus,
+} from "../../application/use-cases/HandleMessage.js"
+import { StartSession } from "../../application/use-cases/StartSession.js"
+import { UndoChange } from "../../application/use-cases/UndoChange.js"
+import type { ConfirmationResult } from "../../application/use-cases/ExecuteTool.js"
+import type { ProjectStructure } from "../../infrastructure/llm/prompts.js"
+import type { TuiStatus } from "../types.js"
+
+export interface UseSessionDependencies {
+    storage: IStorage
+    sessionStorage: ISessionStorage
+    llm: ILLMClient
+    tools: IToolRegistry
+    projectRoot: string
+    projectName: string
+    projectStructure?: ProjectStructure
+    config?: Config
+}
+
+export interface UseSessionOptions {
+    autoApply?: boolean
+    onConfirmation?: (message: string, diff?: DiffInfo) => Promise<boolean | ConfirmationResult>
+    onError?: (error: Error) => Promise<ErrorOption>
+}
+
+export interface UseSessionReturn {
+    session: Session | null
+    messages: ChatMessage[]
+    status: TuiStatus
+    isLoading: boolean
+    error: Error | null
+    sendMessage: (message: string) => Promise<void>
+    undo: () => Promise<boolean>
+    clearHistory: () => void
+    abort: () => void
+}
+
+interface SessionRefs {
+    session: Session | null
+    handleMessage: HandleMessage | null
+    undoChange: UndoChange | null
+}
+
+type SetStatus = React.Dispatch<React.SetStateAction<TuiStatus>>
+type SetMessages = React.Dispatch<React.SetStateAction<ChatMessage[]>>
+
+interface StateSetters {
+    setMessages: SetMessages
+    setStatus: SetStatus
+    forceUpdate: () => void
+}
+
+function createEventHandlers(
+    setters: StateSetters,
+    options: UseSessionOptions,
+): Parameters<HandleMessage["setEvents"]>[0] {
+    return {
+        onMessage: (msg) => {
+            setters.setMessages((prev) => [...prev, msg])
+        },
+        onToolCall: () => {
+            setters.setStatus("tool_call")
+        },
+        onToolResult: () => {
+            setters.setStatus("thinking")
+        },
+        onConfirmation: options.onConfirmation,
+        onError: options.onError,
+        onStatusChange: (s: HandleMessageStatus) => {
+            setters.setStatus(s)
+        },
+        onUndoEntry: () => {
+            setters.forceUpdate()
+        },
+    }
+}
+
+async function initializeSession(
+    deps: UseSessionDependencies,
+    options: UseSessionOptions,
+    refs: React.MutableRefObject<SessionRefs>,
+    setters: StateSetters,
+): Promise<void> {
+    const startSession = new StartSession(deps.sessionStorage)
+    const result = await startSession.execute(deps.projectName)
+    refs.current.session = result.session
+    setters.setMessages([...result.session.history])
+
+    const handleMessage = new HandleMessage(
+        deps.storage,
+        deps.sessionStorage,
+        deps.llm,
+        deps.tools,
+        deps.projectRoot,
+        deps.config?.context,
+    )
+    if (deps.projectStructure) {
+        handleMessage.setProjectStructure(deps.projectStructure)
+    }
+    handleMessage.setOptions({
+        autoApply: options.autoApply,
+        maxHistoryMessages: deps.config?.session.maxHistoryMessages,
+        saveInputHistory: deps.config?.session.saveInputHistory,
+        contextConfig: deps.config?.context,
+    })
+    handleMessage.setEvents(createEventHandlers(setters, options))
+    refs.current.handleMessage = handleMessage
+    refs.current.undoChange = new UndoChange(deps.sessionStorage, deps.storage)
+    setters.forceUpdate()
+}
+
+export function useSession(
+    deps: UseSessionDependencies,
+    options: UseSessionOptions = {},
+): UseSessionReturn {
+    const [messages, setMessages] = useState<ChatMessage[]>([])
+    const [status, setStatus] = useState<TuiStatus>("ready")
+    const [isLoading, setIsLoading] = useState(true)
+    const [error, setError] = useState<Error | null>(null)
+    const [, setTrigger] = useState(0)
+    const refs = useRef<SessionRefs>({ session: null, handleMessage: null, undoChange: null })
+    const forceUpdate = useCallback(() => {
+        setTrigger((v) => v + 1)
+    }, [])
+
+    useEffect(() => {
+        setIsLoading(true)
+        const setters: StateSetters = { setMessages, setStatus, forceUpdate }
+        initializeSession(deps, options, refs, setters)
+            .then(() => {
+                setError(null)
+            })
+            .catch((err: unknown) => {
+                setError(err instanceof Error ? err : new Error(String(err)))
+            })
+            .finally(() => {
+                setIsLoading(false)
+            })
+    }, [deps.projectName, forceUpdate])
+
+    const sendMessage = useCallback(async (message: string): Promise<void> => {
+        const { session, handleMessage } = refs.current
+        if (!session || !handleMessage) {
+            return
+        }
+        try {
+            setStatus("thinking")
+            await handleMessage.execute(session, message)
+        } catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)))
+            setStatus("error")
+        }
+    }, [])
+
+    const undo = useCallback(async (): Promise<boolean> => {
+        const { session, undoChange } = refs.current
+        if (!session || !undoChange) {
+            return false
+        }
+        try {
+            const result = await undoChange.execute(session)
+            if (result.success) {
+                forceUpdate()
+                return true
+            }
+            return false
+        } catch {
+            return false
+        }
+    }, [forceUpdate])
+
+    const clearHistory = useCallback(() => {
+        if (!refs.current.session) {
+            return
+        }
+        refs.current.session.clearHistory()
+        setMessages([])
+        forceUpdate()
+    }, [forceUpdate])
+
+    const abort = useCallback(() => {
+        refs.current.handleMessage?.abort()
+        setStatus("ready")
+    }, [])
+
+    return {
+        session: refs.current.session,
+        messages,
+        status,
+        isLoading,
+        error,
+        sendMessage,
+        undo,
+        clearHistory,
+        abort,
+    }
+}

packages/ipuaro/src/tui/index.ts

@@ -0,0 +1,8 @@
+/**
+ * TUI module - Terminal User Interface.
+ */
+
+export { App, type AppDependencies, type ExtendedAppProps } from "./App.js"
+export * from "./components/index.js"
+export * from "./hooks/index.js"
+export * from "./types.js"

packages/ipuaro/src/tui/types.ts

@@ -0,0 +1,38 @@
+/**
+ * TUI types and interfaces.
+ */
+
+import type { HandleMessageStatus } from "../application/use-cases/HandleMessage.js"
+
+/**
+ * TUI status - maps to HandleMessageStatus.
+ */
+export type TuiStatus = HandleMessageStatus
+
+/**
+ * Git branch information.
+ */
+export interface BranchInfo {
+    name: string
+    isDetached: boolean
+}
+
+/**
+ * Props for the main App component.
+ */
+export interface AppProps {
+    projectPath: string
+    autoApply?: boolean
+    model?: string
+}
+
+/**
+ * Status bar display data.
+ */
+export interface StatusBarData {
+    contextUsage: number
+    projectName: string
+    branch: BranchInfo
+    sessionTime: string
+    status: TuiStatus
+}

packages/ipuaro/src/tui/utils/bell.ts

@@ -0,0 +1,11 @@
+/**
+ * Bell notification utility for terminal.
+ */
+
+/**
+ * Ring the terminal bell.
+ * Works by outputting the ASCII bell character (\u0007).
+ */
+export function ringBell(): void {
+    process.stdout.write("\u0007")
+}

packages/ipuaro/src/tui/utils/syntax-highlighter.ts

@@ -0,0 +1,167 @@
+/**
+ * Simple syntax highlighter for terminal UI.
+ * Highlights keywords, strings, comments, numbers, and operators.
+ */
+
+export type Language = "typescript" | "javascript" | "tsx" | "jsx" | "json" | "yaml" | "unknown"
+
+export interface HighlightedToken {
+    text: string
+    color: string
+}
+
+const KEYWORDS = new Set([
+    "abstract",
+    "any",
+    "as",
+    "async",
+    "await",
+    "boolean",
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "constructor",
+    "continue",
+    "debugger",
+    "declare",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "from",
+    "function",
+    "get",
+    "if",
+    "implements",
+    "import",
+    "in",
+    "instanceof",
+    "interface",
+    "let",
+    "module",
+    "namespace",
+    "new",
+    "null",
+    "number",
+    "of",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "readonly",
+    "require",
+    "return",
+    "set",
+    "static",
+    "string",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "type",
+    "typeof",
+    "undefined",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+])
+
+export function detectLanguage(filePath: string): Language {
+    const ext = filePath.split(".").pop()?.toLowerCase()
+    switch (ext) {
+        case "ts":
+            return "typescript"
+        case "tsx":
+            return "tsx"
+        case "js":
+            return "javascript"
+        case "jsx":
+            return "jsx"
+        case "json":
+            return "json"
+        case "yaml":
+        case "yml":
+            return "yaml"
+        default:
+            return "unknown"
+    }
+}
+
+const COMMENT_REGEX = /^(\/\/.*|\/\*[\s\S]*?\*\/)/
+const STRING_REGEX = /^("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`)/
+const NUMBER_REGEX = /^(\b\d+\.?\d*\b)/
+const WORD_REGEX = /^([a-zA-Z_$][a-zA-Z0-9_$]*)/
+const OPERATOR_REGEX = /^([+\-*/%=<>!&|^~?:;,.()[\]{}])/
+const WHITESPACE_REGEX = /^(\s+)/
+
+export function highlightLine(line: string, language: Language): HighlightedToken[] {
+    if (language === "unknown" || language === "json" || language === "yaml") {
+        return [{ text: line, color: "white" }]
+    }
+
+    const tokens: HighlightedToken[] = []
+    let remaining = line
+
+    while (remaining.length > 0) {
+        const commentMatch = COMMENT_REGEX.exec(remaining)
+        if (commentMatch) {
+            tokens.push({ text: commentMatch[0], color: "gray" })
+            remaining = remaining.slice(commentMatch[0].length)
+            continue
+        }
+
+        const stringMatch = STRING_REGEX.exec(remaining)
+        if (stringMatch) {
+            tokens.push({ text: stringMatch[0], color: "green" })
+            remaining = remaining.slice(stringMatch[0].length)
+            continue
+        }
+
+        const numberMatch = NUMBER_REGEX.exec(remaining)
+        if (numberMatch) {
+            tokens.push({ text: numberMatch[0], color: "cyan" })
+            remaining = remaining.slice(numberMatch[0].length)
+            continue
+        }
+
+        const wordMatch = WORD_REGEX.exec(remaining)
+        if (wordMatch) {
+            const word = wordMatch[0]
+            const color = KEYWORDS.has(word) ? "magenta" : "white"
+            tokens.push({ text: word, color })
+            remaining = remaining.slice(word.length)
+            continue
+        }
+
+        const operatorMatch = OPERATOR_REGEX.exec(remaining)
+        if (operatorMatch) {
+            tokens.push({ text: operatorMatch[0], color: "yellow" })
+            remaining = remaining.slice(operatorMatch[0].length)
+            continue
+        }
+
+        const whitespaceMatch = WHITESPACE_REGEX.exec(remaining)
+        if (whitespaceMatch) {
+            tokens.push({ text: whitespaceMatch[0], color: "white" })
+            remaining = remaining.slice(whitespaceMatch[0].length)
+            continue
+        }
+
+        tokens.push({ text: remaining[0] ?? "", color: "white" })
+        remaining = remaining.slice(1)
+    }
+
+    return tokens
+}

packages/ipuaro/src/tui/utils/theme.ts

@@ -0,0 +1,115 @@
+/**
+ * Theme color utilities for TUI.
+ */
+
+export type Theme = "dark" | "light"
+
+/**
+ * Color scheme for a theme.
+ */
+export interface ColorScheme {
+    primary: string
+    secondary: string
+    success: string
+    warning: string
+    error: string
+    info: string
+    muted: string
+    background: string
+    foreground: string
+}
+
+/**
+ * Dark theme color scheme (default).
+ */
+const DARK_THEME: ColorScheme = {
+    primary: "cyan",
+    secondary: "blue",
+    success: "green",
+    warning: "yellow",
+    error: "red",
+    info: "cyan",
+    muted: "gray",
+    background: "black",
+    foreground: "white",
+}
+
+/**
+ * Light theme color scheme.
+ */
+const LIGHT_THEME: ColorScheme = {
+    primary: "blue",
+    secondary: "cyan",
+    success: "green",
+    warning: "yellow",
+    error: "red",
+    info: "blue",
+    muted: "gray",
+    background: "white",
+    foreground: "black",
+}
+
+/**
+ * Get color scheme for a theme.
+ */
+export function getColorScheme(theme: Theme): ColorScheme {
+    return theme === "dark" ? DARK_THEME : LIGHT_THEME
+}
+
+/**
+ * Get color for a status.
+ */
+export function getStatusColor(
+    status: "ready" | "thinking" | "error" | "tool_call" | "awaiting_confirmation",
+    theme: Theme = "dark",
+): string {
+    const scheme = getColorScheme(theme)
+
+    switch (status) {
+        case "ready":
+            return scheme.success
+        case "thinking":
+        case "tool_call":
+            return scheme.warning
+        case "awaiting_confirmation":
+            return scheme.info
+        case "error":
+            return scheme.error
+    }
+}
+
+/**
+ * Get color for a message role.
+ */
+export function getRoleColor(
+    role: "user" | "assistant" | "system" | "tool",
+    theme: Theme = "dark",
+): string {
+    const scheme = getColorScheme(theme)
+
+    switch (role) {
+        case "user":
+            return scheme.success
+        case "assistant":
+            return scheme.primary
+        case "system":
+            return scheme.muted
+        case "tool":
+            return scheme.secondary
+    }
+}
+
+/**
+ * Get color for context usage percentage.
+ */
+export function getContextColor(usage: number, theme: Theme = "dark"): string {
+    const scheme = getColorScheme(theme)
+
+    if (usage >= 0.8) {
+        return scheme.error
+    }
+    if (usage >= 0.6) {
+        return scheme.warning
+    }
+    return scheme.success
+}

packages/ipuaro/tests/unit/application/use-cases/ContextManager.test.ts

@@ -245,4 +245,65 @@ describe("ContextManager", () => {
             expect(state.needsCompression).toBe(false)
         })
     })
+
+    describe("configuration", () => {
+        it("should use default compression threshold when no config provided", () => {
+            const manager = new ContextManager(CONTEXT_SIZE)
+            manager.addToContext("test.ts", CONTEXT_SIZE * 0.85)
+
+            expect(manager.needsCompression()).toBe(true)
+        })
+
+        it("should use custom compression threshold from config", () => {
+            const manager = new ContextManager(CONTEXT_SIZE, { autoCompressAt: 0.9 })
+            manager.addToContext("test.ts", CONTEXT_SIZE * 0.85)
+
+            expect(manager.needsCompression()).toBe(false)
+        })
+
+        it("should trigger compression at custom threshold", () => {
+            const manager = new ContextManager(CONTEXT_SIZE, { autoCompressAt: 0.9 })
+            manager.addToContext("test.ts", CONTEXT_SIZE * 0.95)
+
+            expect(manager.needsCompression()).toBe(true)
+        })
+
+        it("should accept compression method in config", () => {
+            const manager = new ContextManager(CONTEXT_SIZE, { compressionMethod: "truncate" })
+
+            expect(manager).toBeDefined()
+        })
+
+        it("should use default compression method when not specified", () => {
+            const manager = new ContextManager(CONTEXT_SIZE, {})
+
+            expect(manager).toBeDefined()
+        })
+
+        it("should accept full context config", () => {
+            const manager = new ContextManager(CONTEXT_SIZE, {
+                systemPromptTokens: 3000,
+                maxContextUsage: 0.9,
+                autoCompressAt: 0.85,
+                compressionMethod: "llm-summary",
+            })
+
+            manager.addToContext("test.ts", CONTEXT_SIZE * 0.87)
+            expect(manager.needsCompression()).toBe(true)
+        })
+
+        it("should handle edge case: autoCompressAt = 0", () => {
+            const manager = new ContextManager(CONTEXT_SIZE, { autoCompressAt: 0 })
+            manager.addToContext("test.ts", 1)
+
+            expect(manager.needsCompression()).toBe(true)
+        })
+
+        it("should handle edge case: autoCompressAt = 1", () => {
+            const manager = new ContextManager(CONTEXT_SIZE, { autoCompressAt: 1 })
+            manager.addToContext("test.ts", CONTEXT_SIZE * 0.99)
+
+            expect(manager.needsCompression()).toBe(false)
+        })
+    })
 })

packages/ipuaro/tests/unit/application/use-cases/HandleMessage.test.ts

@@ -198,12 +198,12 @@ describe("HandleMessage", () => {
             expect(toolMessages.length).toBeGreaterThan(0)
         })
 
-        it("should return error for unknown tools", async () => {
+        it("should return error for unregistered tools", async () => {
             vi.mocked(mockTools.get).mockReturnValue(undefined)
             vi.mocked(mockLLM.chat)
                 .mockResolvedValueOnce(
                     createMockLLMResponse(
-                        '<tool_call name="unknown_tool"><param>value</param></tool_call>',
+                        '<tool_call name="get_complexity"><path>src</path></tool_call>',
                         true,
                     ),
                 )

packages/ipuaro/tests/unit/application/use-cases/IndexProject.test.ts

@@ -0,0 +1,318 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+import { IndexProject } from "../../../../src/application/use-cases/IndexProject.js"
+import type { IStorage, SymbolIndex, DepsGraph } from "../../../../src/domain/services/IStorage.js"
+import type { IndexProgress } from "../../../../src/domain/services/IIndexer.js"
+import { createFileData } from "../../../../src/domain/value-objects/FileData.js"
+import { createEmptyFileAST } from "../../../../src/domain/value-objects/FileAST.js"
+import { createFileMeta } from "../../../../src/domain/value-objects/FileMeta.js"
+
+vi.mock("../../../../src/infrastructure/indexer/FileScanner.js", () => ({
+    FileScanner: class {
+        async scanAll() {
+            return [
+                { path: "src/index.ts", type: "file", size: 100, lastModified: Date.now() },
+                { path: "src/utils.ts", type: "file", size: 200, lastModified: Date.now() },
+            ]
+        }
+        static async readFileContent(path: string) {
+            if (path.includes("index.ts")) {
+                return 'export function main() { return "hello" }'
+            }
+            if (path.includes("utils.ts")) {
+                return "export const add = (a: number, b: number) => a + b"
+            }
+            return null
+        }
+    },
+}))
+
+vi.mock("../../../../src/infrastructure/indexer/ASTParser.js", () => ({
+    ASTParser: class {
+        parse() {
+            return {
+                ...createEmptyFileAST(),
+                functions: [
+                    {
+                        name: "test",
+                        lineStart: 1,
+                        lineEnd: 5,
+                        params: [],
+                        isAsync: false,
+                        isExported: true,
+                    },
+                ],
+            }
+        }
+    },
+}))
+
+vi.mock("../../../../src/infrastructure/indexer/MetaAnalyzer.js", () => ({
+    MetaAnalyzer: class {
+        constructor() {}
+        analyze() {
+            return createFileMeta()
+        }
+    },
+}))
+
+vi.mock("../../../../src/infrastructure/indexer/IndexBuilder.js", () => ({
+    IndexBuilder: class {
+        constructor() {}
+        buildSymbolIndex() {
+            return new Map([
+                ["test", [{ path: "src/index.ts", line: 1, type: "function" }]],
+            ]) as SymbolIndex
+        }
+        buildDepsGraph() {
+            return {
+                imports: new Map(),
+                importedBy: new Map(),
+            } as DepsGraph
+        }
+    },
+}))
+
+describe("IndexProject", () => {
+    let useCase: IndexProject
+    let mockStorage: IStorage
+
+    beforeEach(() => {
+        mockStorage = {
+            getFile: vi.fn().mockResolvedValue(null),
+            setFile: vi.fn().mockResolvedValue(undefined),
+            deleteFile: vi.fn().mockResolvedValue(undefined),
+            getAllFiles: vi.fn().mockResolvedValue(new Map()),
+            getFileCount: vi.fn().mockResolvedValue(0),
+            getAST: vi.fn().mockResolvedValue(null),
+            setAST: vi.fn().mockResolvedValue(undefined),
+            deleteAST: vi.fn().mockResolvedValue(undefined),
+            getAllASTs: vi.fn().mockResolvedValue(new Map()),
+            getMeta: vi.fn().mockResolvedValue(null),
+            setMeta: vi.fn().mockResolvedValue(undefined),
+            deleteMeta: vi.fn().mockResolvedValue(undefined),
+            getAllMetas: vi.fn().mockResolvedValue(new Map()),
+            getSymbolIndex: vi.fn().mockResolvedValue(new Map()),
+            setSymbolIndex: vi.fn().mockResolvedValue(undefined),
+            getDepsGraph: vi.fn().mockResolvedValue({ imports: new Map(), importedBy: new Map() }),
+            setDepsGraph: vi.fn().mockResolvedValue(undefined),
+            getProjectConfig: vi.fn().mockResolvedValue(null),
+            setProjectConfig: vi.fn().mockResolvedValue(undefined),
+            connect: vi.fn().mockResolvedValue(undefined),
+            disconnect: vi.fn().mockResolvedValue(undefined),
+            isConnected: vi.fn().mockReturnValue(true),
+            clear: vi.fn().mockResolvedValue(undefined),
+        }
+
+        useCase = new IndexProject(mockStorage, "/test/project")
+    })
+
+    describe("execute", () => {
+        it("should index project and return stats", async () => {
+            const stats = await useCase.execute("/test/project")
+
+            expect(stats.filesScanned).toBe(2)
+            expect(stats.filesParsed).toBe(2)
+            expect(stats.parseErrors).toBe(0)
+            expect(stats.timeMs).toBeGreaterThanOrEqual(0)
+        })
+
+        it("should store file data for all scanned files", async () => {
+            await useCase.execute("/test/project")
+
+            expect(mockStorage.setFile).toHaveBeenCalledTimes(2)
+            expect(mockStorage.setFile).toHaveBeenCalledWith(
+                "src/index.ts",
+                expect.objectContaining({
+                    hash: expect.any(String),
+                    lines: expect.any(Array),
+                }),
+            )
+        })
+
+        it("should store AST for all parsed files", async () => {
+            await useCase.execute("/test/project")
+
+            expect(mockStorage.setAST).toHaveBeenCalledTimes(2)
+            expect(mockStorage.setAST).toHaveBeenCalledWith(
+                "src/index.ts",
+                expect.objectContaining({
+                    functions: expect.any(Array),
+                }),
+            )
+        })
+
+        it("should store metadata for all files", async () => {
+            await useCase.execute("/test/project")
+
+            expect(mockStorage.setMeta).toHaveBeenCalledTimes(2)
+            expect(mockStorage.setMeta).toHaveBeenCalledWith("src/index.ts", expect.any(Object))
+        })
+
+        it("should build and store symbol index", async () => {
+            await useCase.execute("/test/project")
+
+            expect(mockStorage.setSymbolIndex).toHaveBeenCalledTimes(1)
+            expect(mockStorage.setSymbolIndex).toHaveBeenCalledWith(expect.any(Map))
+        })
+
+        it("should build and store dependency graph", async () => {
+            await useCase.execute("/test/project")
+
+            expect(mockStorage.setDepsGraph).toHaveBeenCalledTimes(1)
+            expect(mockStorage.setDepsGraph).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    imports: expect.any(Map),
+                    importedBy: expect.any(Map),
+                }),
+            )
+        })
+
+        it("should store last indexed timestamp", async () => {
+            await useCase.execute("/test/project")
+
+            expect(mockStorage.setProjectConfig).toHaveBeenCalledWith(
+                "last_indexed",
+                expect.any(Number),
+            )
+        })
+
+        it("should call progress callback during indexing", async () => {
+            const progressCallback = vi.fn()
+
+            await useCase.execute("/test/project", {
+                onProgress: progressCallback,
+            })
+
+            expect(progressCallback).toHaveBeenCalled()
+            expect(progressCallback).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    current: expect.any(Number),
+                    total: expect.any(Number),
+                    currentFile: expect.any(String),
+                    phase: expect.stringMatching(/scanning|parsing|analyzing|indexing/),
+                }),
+            )
+        })
+
+        it("should report scanning phase", async () => {
+            const progressCallback = vi.fn()
+
+            await useCase.execute("/test/project", {
+                onProgress: progressCallback,
+            })
+
+            const scanningCalls = progressCallback.mock.calls.filter(
+                (call) => call[0].phase === "scanning",
+            )
+            expect(scanningCalls.length).toBeGreaterThan(0)
+        })
+
+        it("should report parsing phase", async () => {
+            const progressCallback = vi.fn()
+
+            await useCase.execute("/test/project", {
+                onProgress: progressCallback,
+            })
+
+            const parsingCalls = progressCallback.mock.calls.filter(
+                (call) => call[0].phase === "parsing",
+            )
+            expect(parsingCalls.length).toBeGreaterThan(0)
+        })
+
+        it("should report analyzing phase", async () => {
+            const progressCallback = vi.fn()
+
+            await useCase.execute("/test/project", {
+                onProgress: progressCallback,
+            })
+
+            const analyzingCalls = progressCallback.mock.calls.filter(
+                (call) => call[0].phase === "analyzing",
+            )
+            expect(analyzingCalls.length).toBeGreaterThan(0)
+        })
+
+        it("should report indexing phase", async () => {
+            const progressCallback = vi.fn()
+
+            await useCase.execute("/test/project", {
+                onProgress: progressCallback,
+            })
+
+            const indexingCalls = progressCallback.mock.calls.filter(
+                (call) => call[0].phase === "indexing",
+            )
+            expect(indexingCalls.length).toBeGreaterThan(0)
+        })
+
+        it("should detect TypeScript files", async () => {
+            await useCase.execute("/test/project")
+
+            expect(mockStorage.setAST).toHaveBeenCalledWith("src/index.ts", expect.any(Object))
+        })
+
+        it("should handle files without parseable language", async () => {
+            vi.mocked(mockStorage.setFile).mockClear()
+
+            await useCase.execute("/test/project")
+
+            const stats = await useCase.execute("/test/project")
+            expect(stats.filesScanned).toBeGreaterThanOrEqual(0)
+        })
+
+        it("should calculate indexing duration", async () => {
+            const startTime = Date.now()
+            const stats = await useCase.execute("/test/project")
+            const endTime = Date.now()
+
+            expect(stats.timeMs).toBeGreaterThanOrEqual(0)
+            expect(stats.timeMs).toBeLessThanOrEqual(endTime - startTime + 10)
+        })
+    })
+
+    describe("language detection", () => {
+        it("should detect .ts files", async () => {
+            await useCase.execute("/test/project")
+
+            expect(mockStorage.setAST).toHaveBeenCalledWith(
+                expect.stringContaining(".ts"),
+                expect.any(Object),
+            )
+        })
+    })
+
+    describe("progress reporting", () => {
+        it("should not fail if progress callback is not provided", async () => {
+            await expect(useCase.execute("/test/project")).resolves.toBeDefined()
+        })
+
+        it("should include current file in progress updates", async () => {
+            const progressCallback = vi.fn()
+
+            await useCase.execute("/test/project", {
+                onProgress: progressCallback,
+            })
+
+            const callsWithFiles = progressCallback.mock.calls.filter(
+                (call) => call[0].currentFile && call[0].currentFile.length > 0,
+            )
+            expect(callsWithFiles.length).toBeGreaterThan(0)
+        })
+
+        it("should report correct total count", async () => {
+            const progressCallback = vi.fn()
+
+            await useCase.execute("/test/project", {
+                onProgress: progressCallback,
+            })
+
+            const parsingCalls = progressCallback.mock.calls.filter(
+                (call) => call[0].phase === "parsing",
+            )
+            if (parsingCalls.length > 0) {
+                expect(parsingCalls[0][0].total).toBe(2)
+            }
+        })
+    })
+})

packages/ipuaro/tests/unit/cli/commands/init.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
+import * as fs from "node:fs/promises"
+import * as path from "node:path"
+import { executeInit } from "../../../../src/cli/commands/init.js"
+
+vi.mock("node:fs/promises")
+
+describe("executeInit", () => {
+    const testPath = "/test/project"
+    const configPath = path.join(testPath, ".ipuaro.json")
+
+    beforeEach(() => {
+        vi.clearAllMocks()
+        vi.spyOn(console, "warn").mockImplementation(() => {})
+        vi.spyOn(console, "error").mockImplementation(() => {})
+    })
+
+    afterEach(() => {
+        vi.restoreAllMocks()
+    })
+
+    it("should create .ipuaro.json file successfully", async () => {
+        vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"))
+        vi.mocked(fs.mkdir).mockResolvedValue(undefined)
+        vi.mocked(fs.writeFile).mockResolvedValue(undefined)
+
+        const result = await executeInit(testPath)
+
+        expect(result.success).toBe(true)
+        expect(result.filePath).toBe(configPath)
+        expect(fs.writeFile).toHaveBeenCalledWith(
+            configPath,
+            expect.stringContaining('"redis"'),
+            "utf-8",
+        )
+    })
+
+    it("should skip existing file without force option", async () => {
+        vi.mocked(fs.access).mockResolvedValue(undefined)
+
+        const result = await executeInit(testPath)
+
+        expect(result.success).toBe(true)
+        expect(result.skipped).toBe(true)
+        expect(fs.writeFile).not.toHaveBeenCalled()
+    })
+
+    it("should overwrite existing file with force option", async () => {
+        vi.mocked(fs.access).mockResolvedValue(undefined)
+        vi.mocked(fs.writeFile).mockResolvedValue(undefined)
+
+        const result = await executeInit(testPath, { force: true })
+
+        expect(result.success).toBe(true)
+        expect(result.skipped).toBeUndefined()
+        expect(fs.writeFile).toHaveBeenCalled()
+    })
+
+    it("should handle write errors", async () => {
+        vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"))
+        vi.mocked(fs.mkdir).mockResolvedValue(undefined)
+        vi.mocked(fs.writeFile).mockRejectedValue(new Error("Permission denied"))
+
+        const result = await executeInit(testPath)
+
+        expect(result.success).toBe(false)
+        expect(result.error).toContain("Permission denied")
+    })
+
+    it("should create parent directories if needed", async () => {
+        vi.mocked(fs.access)
+            .mockRejectedValueOnce(new Error("ENOENT"))
+            .mockRejectedValueOnce(new Error("ENOENT"))
+        vi.mocked(fs.mkdir).mockResolvedValue(undefined)
+        vi.mocked(fs.writeFile).mockResolvedValue(undefined)
+
+        const result = await executeInit(testPath)
+
+        expect(result.success).toBe(true)
+        expect(fs.mkdir).toHaveBeenCalledWith(expect.any(String), { recursive: true })
+    })
+
+    it("should use current directory as default", async () => {
+        vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"))
+        vi.mocked(fs.mkdir).mockResolvedValue(undefined)
+        vi.mocked(fs.writeFile).mockResolvedValue(undefined)
+
+        const result = await executeInit()
+
+        expect(result.success).toBe(true)
+        expect(result.filePath).toContain(".ipuaro.json")
+    })
+
+    it("should include expected config sections", async () => {
+        vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"))
+        vi.mocked(fs.mkdir).mockResolvedValue(undefined)
+        vi.mocked(fs.writeFile).mockResolvedValue(undefined)
+
+        await executeInit(testPath)
+
+        const writeCall = vi.mocked(fs.writeFile).mock.calls[0]
+        const content = writeCall[1] as string
+        const config = JSON.parse(content) as {
+            redis: unknown
+            llm: unknown
+            edit: unknown
+        }
+
+        expect(config).toHaveProperty("redis")
+        expect(config).toHaveProperty("llm")
+        expect(config).toHaveProperty("edit")
+        expect(config.redis).toHaveProperty("host", "localhost")
+        expect(config.redis).toHaveProperty("port", 6379)
+        expect(config.llm).toHaveProperty("model", "qwen2.5-coder:7b-instruct")
+        expect(config.edit).toHaveProperty("autoApply", false)
+    })
+})

packages/ipuaro/tests/unit/cli/commands/onboarding.test.ts

@@ -0,0 +1,353 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
+import {
+    checkRedis,
+    checkOllama,
+    checkModel,
+    checkProjectSize,
+    runOnboarding,
+} from "../../../../src/cli/commands/onboarding.js"
+import { RedisClient } from "../../../../src/infrastructure/storage/RedisClient.js"
+import { OllamaClient } from "../../../../src/infrastructure/llm/OllamaClient.js"
+import { FileScanner } from "../../../../src/infrastructure/indexer/FileScanner.js"
+
+vi.mock("../../../../src/infrastructure/storage/RedisClient.js")
+vi.mock("../../../../src/infrastructure/llm/OllamaClient.js")
+vi.mock("../../../../src/infrastructure/indexer/FileScanner.js")
+
+describe("onboarding", () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+    })
+
+    afterEach(() => {
+        vi.restoreAllMocks()
+    })
+
+    describe("checkRedis", () => {
+        it("should return ok when Redis connects and pings successfully", async () => {
+            const mockConnect = vi.fn().mockResolvedValue(undefined)
+            const mockPing = vi.fn().mockResolvedValue(true)
+            const mockDisconnect = vi.fn().mockResolvedValue(undefined)
+
+            vi.mocked(RedisClient).mockImplementation(
+                () =>
+                    ({
+                        connect: mockConnect,
+                        ping: mockPing,
+                        disconnect: mockDisconnect,
+                    }) as unknown as RedisClient,
+            )
+
+            const result = await checkRedis({
+                host: "localhost",
+                port: 6379,
+                db: 0,
+                keyPrefix: "ipuaro:",
+            })
+
+            expect(result.ok).toBe(true)
+            expect(result.error).toBeUndefined()
+            expect(mockConnect).toHaveBeenCalled()
+            expect(mockPing).toHaveBeenCalled()
+            expect(mockDisconnect).toHaveBeenCalled()
+        })
+
+        it("should return error when Redis connection fails", async () => {
+            vi.mocked(RedisClient).mockImplementation(
+                () =>
+                    ({
+                        connect: vi.fn().mockRejectedValue(new Error("Connection refused")),
+                    }) as unknown as RedisClient,
+            )
+
+            const result = await checkRedis({
+                host: "localhost",
+                port: 6379,
+                db: 0,
+                keyPrefix: "ipuaro:",
+            })
+
+            expect(result.ok).toBe(false)
+            expect(result.error).toContain("Cannot connect to Redis")
+        })
+
+        it("should return error when ping fails", async () => {
+            vi.mocked(RedisClient).mockImplementation(
+                () =>
+                    ({
+                        connect: vi.fn().mockResolvedValue(undefined),
+                        ping: vi.fn().mockResolvedValue(false),
+                        disconnect: vi.fn().mockResolvedValue(undefined),
+                    }) as unknown as RedisClient,
+            )
+
+            const result = await checkRedis({
+                host: "localhost",
+                port: 6379,
+                db: 0,
+                keyPrefix: "ipuaro:",
+            })
+
+            expect(result.ok).toBe(false)
+            expect(result.error).toContain("Redis ping failed")
+        })
+    })
+
+    describe("checkOllama", () => {
+        it("should return ok when Ollama is available", async () => {
+            vi.mocked(OllamaClient).mockImplementation(
+                () =>
+                    ({
+                        isAvailable: vi.fn().mockResolvedValue(true),
+                    }) as unknown as OllamaClient,
+            )
+
+            const result = await checkOllama({
+                model: "qwen2.5-coder:7b-instruct",
+                contextWindow: 128_000,
+                temperature: 0.1,
+                host: "http://localhost:11434",
+                timeout: 120_000,
+            })
+
+            expect(result.ok).toBe(true)
+            expect(result.error).toBeUndefined()
+        })
+
+        it("should return error when Ollama is not available", async () => {
+            vi.mocked(OllamaClient).mockImplementation(
+                () =>
+                    ({
+                        isAvailable: vi.fn().mockResolvedValue(false),
+                    }) as unknown as OllamaClient,
+            )
+
+            const result = await checkOllama({
+                model: "qwen2.5-coder:7b-instruct",
+                contextWindow: 128_000,
+                temperature: 0.1,
+                host: "http://localhost:11434",
+                timeout: 120_000,
+            })
+
+            expect(result.ok).toBe(false)
+            expect(result.error).toContain("Cannot connect to Ollama")
+        })
+    })
+
+    describe("checkModel", () => {
+        it("should return ok when model is available", async () => {
+            vi.mocked(OllamaClient).mockImplementation(
+                () =>
+                    ({
+                        hasModel: vi.fn().mockResolvedValue(true),
+                    }) as unknown as OllamaClient,
+            )
+
+            const result = await checkModel({
+                model: "qwen2.5-coder:7b-instruct",
+                contextWindow: 128_000,
+                temperature: 0.1,
+                host: "http://localhost:11434",
+                timeout: 120_000,
+            })
+
+            expect(result.ok).toBe(true)
+            expect(result.needsPull).toBe(false)
+        })
+
+        it("should return needsPull when model is not available", async () => {
+            vi.mocked(OllamaClient).mockImplementation(
+                () =>
+                    ({
+                        hasModel: vi.fn().mockResolvedValue(false),
+                    }) as unknown as OllamaClient,
+            )
+
+            const result = await checkModel({
+                model: "qwen2.5-coder:7b-instruct",
+                contextWindow: 128_000,
+                temperature: 0.1,
+                host: "http://localhost:11434",
+                timeout: 120_000,
+            })
+
+            expect(result.ok).toBe(false)
+            expect(result.needsPull).toBe(true)
+            expect(result.error).toContain("not installed")
+        })
+    })
+
+    describe("checkProjectSize", () => {
+        it("should return ok when file count is within limits", async () => {
+            vi.mocked(FileScanner).mockImplementation(
+                () =>
+                    ({
+                        scanAll: vi.fn().mockResolvedValue(
+                            Array.from({ length: 100 }, (_, i) => ({
+                                path: `file${String(i)}.ts`,
+                                type: "file" as const,
+                                size: 1000,
+                                lastModified: Date.now(),
+                            })),
+                        ),
+                    }) as unknown as FileScanner,
+            )
+
+            const result = await checkProjectSize("/test/path")
+
+            expect(result.ok).toBe(true)
+            expect(result.fileCount).toBe(100)
+            expect(result.warning).toBeUndefined()
+        })
+
+        it("should return warning when file count exceeds limit", async () => {
+            vi.mocked(FileScanner).mockImplementation(
+                () =>
+                    ({
+                        scanAll: vi.fn().mockResolvedValue(
+                            Array.from({ length: 15000 }, (_, i) => ({
+                                path: `file${String(i)}.ts`,
+                                type: "file" as const,
+                                size: 1000,
+                                lastModified: Date.now(),
+                            })),
+                        ),
+                    }) as unknown as FileScanner,
+            )
+
+            const result = await checkProjectSize("/test/path", 10_000)
+
+            expect(result.ok).toBe(true)
+            expect(result.fileCount).toBe(15000)
+            expect(result.warning).toContain("15")
+            expect(result.warning).toContain("000 files")
+        })
+
+        it("should return error when no files found", async () => {
+            vi.mocked(FileScanner).mockImplementation(
+                () =>
+                    ({
+                        scanAll: vi.fn().mockResolvedValue([]),
+                    }) as unknown as FileScanner,
+            )
+
+            const result = await checkProjectSize("/test/path")
+
+            expect(result.ok).toBe(false)
+            expect(result.fileCount).toBe(0)
+            expect(result.warning).toContain("No supported files found")
+        })
+    })
+
+    describe("runOnboarding", () => {
+        it("should return success when all checks pass", async () => {
+            vi.mocked(RedisClient).mockImplementation(
+                () =>
+                    ({
+                        connect: vi.fn().mockResolvedValue(undefined),
+                        ping: vi.fn().mockResolvedValue(true),
+                        disconnect: vi.fn().mockResolvedValue(undefined),
+                    }) as unknown as RedisClient,
+            )
+
+            vi.mocked(OllamaClient).mockImplementation(
+                () =>
+                    ({
+                        isAvailable: vi.fn().mockResolvedValue(true),
+                        hasModel: vi.fn().mockResolvedValue(true),
+                    }) as unknown as OllamaClient,
+            )
+
+            vi.mocked(FileScanner).mockImplementation(
+                () =>
+                    ({
+                        scanAll: vi.fn().mockResolvedValue([{ path: "file.ts" }]),
+                    }) as unknown as FileScanner,
+            )
+
+            const result = await runOnboarding({
+                redisConfig: { host: "localhost", port: 6379, db: 0, keyPrefix: "ipuaro:" },
+                llmConfig: {
+                    model: "test",
+                    contextWindow: 128_000,
+                    temperature: 0.1,
+                    host: "http://localhost:11434",
+                    timeout: 120_000,
+                },
+                projectPath: "/test/path",
+            })
+
+            expect(result.success).toBe(true)
+            expect(result.redisOk).toBe(true)
+            expect(result.ollamaOk).toBe(true)
+            expect(result.modelOk).toBe(true)
+            expect(result.projectOk).toBe(true)
+            expect(result.errors).toHaveLength(0)
+        })
+
+        it("should return failure when Redis fails", async () => {
+            vi.mocked(RedisClient).mockImplementation(
+                () =>
+                    ({
+                        connect: vi.fn().mockRejectedValue(new Error("Connection refused")),
+                    }) as unknown as RedisClient,
+            )
+
+            vi.mocked(OllamaClient).mockImplementation(
+                () =>
+                    ({
+                        isAvailable: vi.fn().mockResolvedValue(true),
+                        hasModel: vi.fn().mockResolvedValue(true),
+                    }) as unknown as OllamaClient,
+            )
+
+            vi.mocked(FileScanner).mockImplementation(
+                () =>
+                    ({
+                        scanAll: vi.fn().mockResolvedValue([{ path: "file.ts" }]),
+                    }) as unknown as FileScanner,
+            )
+
+            const result = await runOnboarding({
+                redisConfig: { host: "localhost", port: 6379, db: 0, keyPrefix: "ipuaro:" },
+                llmConfig: {
+                    model: "test",
+                    contextWindow: 128_000,
+                    temperature: 0.1,
+                    host: "http://localhost:11434",
+                    timeout: 120_000,
+                },
+                projectPath: "/test/path",
+            })
+
+            expect(result.success).toBe(false)
+            expect(result.redisOk).toBe(false)
+            expect(result.errors.length).toBeGreaterThan(0)
+        })
+
+        it("should skip checks when skip options are set", async () => {
+            const result = await runOnboarding({
+                redisConfig: { host: "localhost", port: 6379, db: 0, keyPrefix: "ipuaro:" },
+                llmConfig: {
+                    model: "test",
+                    contextWindow: 128_000,
+                    temperature: 0.1,
+                    host: "http://localhost:11434",
+                    timeout: 120_000,
+                },
+                projectPath: "/test/path",
+                skipRedis: true,
+                skipOllama: true,
+                skipModel: true,
+                skipProject: true,
+            })
+
+            expect(result.success).toBe(true)
+            expect(result.redisOk).toBe(true)
+            expect(result.ollamaOk).toBe(true)
+            expect(result.modelOk).toBe(true)
+            expect(result.projectOk).toBe(true)
+        })
+    })
+})

packages/ipuaro/tests/unit/cli/commands/tools-setup.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from "vitest"
+import { registerAllTools } from "../../../../src/cli/commands/tools-setup.js"
+import { ToolRegistry } from "../../../../src/infrastructure/tools/registry.js"
+
+describe("registerAllTools", () => {
+    it("should register all 18 tools", () => {
+        const registry = new ToolRegistry()
+
+        registerAllTools(registry)
+
+        expect(registry.size).toBe(18)
+    })
+
+    it("should register all read tools", () => {
+        const registry = new ToolRegistry()
+
+        registerAllTools(registry)
+
+        expect(registry.has("get_lines")).toBe(true)
+        expect(registry.has("get_function")).toBe(true)
+        expect(registry.has("get_class")).toBe(true)
+        expect(registry.has("get_structure")).toBe(true)
+    })
+
+    it("should register all edit tools", () => {
+        const registry = new ToolRegistry()
+
+        registerAllTools(registry)
+
+        expect(registry.has("edit_lines")).toBe(true)
+        expect(registry.has("create_file")).toBe(true)
+        expect(registry.has("delete_file")).toBe(true)
+    })
+
+    it("should register all search tools", () => {
+        const registry = new ToolRegistry()
+
+        registerAllTools(registry)
+
+        expect(registry.has("find_references")).toBe(true)
+        expect(registry.has("find_definition")).toBe(true)
+    })
+
+    it("should register all analysis tools", () => {
+        const registry = new ToolRegistry()
+
+        registerAllTools(registry)
+
+        expect(registry.has("get_dependencies")).toBe(true)
+        expect(registry.has("get_dependents")).toBe(true)
+        expect(registry.has("get_complexity")).toBe(true)
+        expect(registry.has("get_todos")).toBe(true)
+    })
+
+    it("should register all git tools", () => {
+        const registry = new ToolRegistry()
+
+        registerAllTools(registry)
+
+        expect(registry.has("git_status")).toBe(true)
+        expect(registry.has("git_diff")).toBe(true)
+        expect(registry.has("git_commit")).toBe(true)
+    })
+
+    it("should register all run tools", () => {
+        const registry = new ToolRegistry()
+
+        registerAllTools(registry)
+
+        expect(registry.has("run_command")).toBe(true)
+        expect(registry.has("run_tests")).toBe(true)
+    })
+
+    it("should register tools with correct categories", () => {
+        const registry = new ToolRegistry()
+
+        registerAllTools(registry)
+
+        const readTools = registry.getByCategory("read")
+        const editTools = registry.getByCategory("edit")
+        const searchTools = registry.getByCategory("search")
+        const analysisTools = registry.getByCategory("analysis")
+        const gitTools = registry.getByCategory("git")
+        const runTools = registry.getByCategory("run")
+
+        expect(readTools.length).toBe(4)
+        expect(editTools.length).toBe(3)
+        expect(searchTools.length).toBe(2)
+        expect(analysisTools.length).toBe(4)
+        expect(gitTools.length).toBe(3)
+        expect(runTools.length).toBe(2)
+    })
+
+    it("should register tools with requiresConfirmation flag", () => {
+        const registry = new ToolRegistry()
+
+        registerAllTools(registry)
+
+        const confirmationTools = registry.getConfirmationTools()
+        const safeTools = registry.getSafeTools()
+
+        expect(confirmationTools.length).toBeGreaterThan(0)
+        expect(safeTools.length).toBeGreaterThan(0)
+
+        const confirmNames = confirmationTools.map((t) => t.name)
+        expect(confirmNames).toContain("edit_lines")
+        expect(confirmNames).toContain("create_file")
+        expect(confirmNames).toContain("delete_file")
+        expect(confirmNames).toContain("git_commit")
+    })
+})

packages/ipuaro/tests/unit/infrastructure/indexer/Watchdog.test.ts

@@ -109,24 +109,80 @@ describe("Watchdog", () => {
 
     describe("flushAll", () => {
         it("should not throw when no pending changes", () => {
+            watchdog.start(tempDir)
             expect(() => watchdog.flushAll()).not.toThrow()
         })
 
-        it("should flush all pending changes", async () => {
+        it("should handle flushAll with active timers", async () => {
+            const slowWatchdog = new Watchdog({ debounceMs: 1000 })
             const events: FileChangeEvent[] = []
-            watchdog.onFileChange((event) => events.push(event))
-            watchdog.start(tempDir)
+            slowWatchdog.onFileChange((event) => events.push(event))
+            slowWatchdog.start(tempDir)
+
+            await new Promise((resolve) => setTimeout(resolve, 200))
+
+            const testFile = path.join(tempDir, "instant-flush.ts")
+            await fs.writeFile(testFile, "const x = 1")
+
+            await new Promise((resolve) => setTimeout(resolve, 150))
+
+            const pendingCount = slowWatchdog.getPendingCount()
+            if (pendingCount > 0) {
+                slowWatchdog.flushAll()
+                expect(slowWatchdog.getPendingCount()).toBe(0)
+                expect(events.length).toBeGreaterThan(0)
+            }
+
+            await slowWatchdog.stop()
+        })
+
+        it("should flush all pending changes immediately", async () => {
+            const slowWatchdog = new Watchdog({ debounceMs: 500 })
+            const events: FileChangeEvent[] = []
+            slowWatchdog.onFileChange((event) => events.push(event))
+            slowWatchdog.start(tempDir)
 
             await new Promise((resolve) => setTimeout(resolve, 100))
 
-            const testFile = path.join(tempDir, "flush-test.ts")
+            const testFile1 = path.join(tempDir, "flush-test1.ts")
+            const testFile2 = path.join(tempDir, "flush-test2.ts")
+            await fs.writeFile(testFile1, "const x = 1")
+            await fs.writeFile(testFile2, "const y = 2")
+
+            await new Promise((resolve) => setTimeout(resolve, 100))
+
+            const pendingCount = slowWatchdog.getPendingCount()
+            if (pendingCount > 0) {
+                slowWatchdog.flushAll()
+                expect(slowWatchdog.getPendingCount()).toBe(0)
+            }
+
+            await slowWatchdog.stop()
+        })
+
+        it("should clear all timers when flushing", async () => {
+            const slowWatchdog = new Watchdog({ debounceMs: 500 })
+            const events: FileChangeEvent[] = []
+            slowWatchdog.onFileChange((event) => events.push(event))
+            slowWatchdog.start(tempDir)
+
+            await new Promise((resolve) => setTimeout(resolve, 100))
+
+            const testFile = path.join(tempDir, "timer-test.ts")
             await fs.writeFile(testFile, "const x = 1")
 
-            await new Promise((resolve) => setTimeout(resolve, 20))
+            await new Promise((resolve) => setTimeout(resolve, 100))
 
-            watchdog.flushAll()
+            const pendingBefore = slowWatchdog.getPendingCount()
 
-            await new Promise((resolve) => setTimeout(resolve, 50))
+            if (pendingBefore > 0) {
+                const eventsBefore = events.length
+                slowWatchdog.flushAll()
+                expect(slowWatchdog.getPendingCount()).toBe(0)
+                expect(events.length).toBeGreaterThan(eventsBefore)
+            }
+
+            await slowWatchdog.stop()
         })
     })
 
@@ -145,7 +201,7 @@ describe("Watchdog", () => {
             await customWatchdog.stop()
         })
 
-        it("should handle simple directory patterns", async () => {
+        it("should handle simple directory patterns without wildcards", async () => {
             const customWatchdog = new Watchdog({
                 debounceMs: 50,
                 ignorePatterns: ["node_modules", "dist"],
@@ -158,6 +214,48 @@ describe("Watchdog", () => {
 
             await customWatchdog.stop()
         })
+
+        it("should handle mixed wildcard and non-wildcard patterns", async () => {
+            const customWatchdog = new Watchdog({
+                debounceMs: 50,
+                ignorePatterns: ["node_modules", "*.log", "**/*.tmp", "dist", "build"],
+            })
+
+            customWatchdog.start(tempDir)
+            await new Promise((resolve) => setTimeout(resolve, 100))
+
+            expect(customWatchdog.isWatching()).toBe(true)
+
+            await customWatchdog.stop()
+        })
+
+        it("should handle patterns with dots correctly", async () => {
+            const customWatchdog = new Watchdog({
+                debounceMs: 50,
+                ignorePatterns: ["*.test.ts", "**/*.spec.js"],
+            })
+
+            customWatchdog.start(tempDir)
+            await new Promise((resolve) => setTimeout(resolve, 100))
+
+            expect(customWatchdog.isWatching()).toBe(true)
+
+            await customWatchdog.stop()
+        })
+
+        it("should handle double wildcards correctly", async () => {
+            const customWatchdog = new Watchdog({
+                debounceMs: 50,
+                ignorePatterns: ["**/node_modules/**", "**/.git/**"],
+            })
+
+            customWatchdog.start(tempDir)
+            await new Promise((resolve) => setTimeout(resolve, 100))
+
+            expect(customWatchdog.isWatching()).toBe(true)
+
+            await customWatchdog.stop()
+        })
     })
 
     describe("file change detection", () => {
@@ -333,4 +431,94 @@ describe("Watchdog", () => {
             }
         })
     })
+
+    describe("error handling", () => {
+        it("should handle watcher errors gracefully", async () => {
+            const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+
+            watchdog.start(tempDir)
+
+            const watcher = (watchdog as any).watcher
+            if (watcher) {
+                watcher.emit("error", new Error("Test watcher error"))
+            }
+
+            await new Promise((resolve) => setTimeout(resolve, 100))
+
+            expect(consoleErrorSpy).toHaveBeenCalledWith(
+                expect.stringContaining("Test watcher error"),
+            )
+
+            consoleErrorSpy.mockRestore()
+        })
+    })
+
+    describe("polling mode", () => {
+        it("should support polling mode", () => {
+            const pollingWatchdog = new Watchdog({
+                debounceMs: 50,
+                usePolling: true,
+                pollInterval: 500,
+            })
+
+            pollingWatchdog.start(tempDir)
+            expect(pollingWatchdog.isWatching()).toBe(true)
+
+            pollingWatchdog.stop()
+        })
+    })
+
+    describe("edge cases", () => {
+        it("should handle flushing non-existent change", () => {
+            watchdog.start(tempDir)
+            const flushChange = (watchdog as any).flushChange.bind(watchdog)
+            expect(() => flushChange("/non/existent/path.ts")).not.toThrow()
+        })
+
+        it("should handle clearing timer for same file multiple times", async () => {
+            const events: FileChangeEvent[] = []
+            watchdog.onFileChange((event) => events.push(event))
+            watchdog.start(tempDir)
+
+            await new Promise((resolve) => setTimeout(resolve, 100))
+
+            const testFile = path.join(tempDir, "test.ts")
+            await fs.writeFile(testFile, "const x = 1")
+            await new Promise((resolve) => setTimeout(resolve, 10))
+            await fs.writeFile(testFile, "const x = 2")
+            await new Promise((resolve) => setTimeout(resolve, 10))
+            await fs.writeFile(testFile, "const x = 3")
+
+            await new Promise((resolve) => setTimeout(resolve, 200))
+
+            expect(events.length).toBeGreaterThanOrEqual(0)
+        })
+
+        it("should normalize file paths", async () => {
+            const events: FileChangeEvent[] = []
+            watchdog.onFileChange((event) => {
+                events.push(event)
+                expect(path.isAbsolute(event.path)).toBe(true)
+            })
+            watchdog.start(tempDir)
+
+            await new Promise((resolve) => setTimeout(resolve, 100))
+
+            const testFile = path.join(tempDir, "normalize-test.ts")
+            await fs.writeFile(testFile, "const x = 1")
+
+            await new Promise((resolve) => setTimeout(resolve, 200))
+        })
+
+        it("should handle empty directory", async () => {
+            const emptyDir = await fs.mkdtemp(path.join(os.tmpdir(), "empty-"))
+            const emptyWatchdog = new Watchdog({ debounceMs: 50 })
+
+            emptyWatchdog.start(emptyDir)
+            expect(emptyWatchdog.isWatching()).toBe(true)
+
+            await emptyWatchdog.stop()
+            await fs.rm(emptyDir, { recursive: true, force: true })
+        })
+    })
 })

packages/ipuaro/tests/unit/infrastructure/llm/OllamaClient.test.ts

@@ -95,53 +95,36 @@ describe("OllamaClient", () => {
             )
         })
 
-        it("should pass tools when provided", async () => {
+        it("should not pass tools parameter (tools are in system prompt)", async () => {
             const client = new OllamaClient(defaultConfig)
             const messages = [createUserMessage("Read file")]
-            const tools = [
-                {
-                    name: "get_lines",
-                    description: "Get lines from file",
-                    parameters: [
-                        {
-                            name: "path",
-                            type: "string" as const,
-                            description: "File path",
-                            required: true,
-                        },
-                    ],
-                },
-            ]
 
-            await client.chat(messages, tools)
+            await client.chat(messages)
 
             expect(mockOllamaInstance.chat).toHaveBeenCalledWith(
                 expect.objectContaining({
-                    tools: expect.arrayContaining([
+                    model: "qwen2.5-coder:7b-instruct",
+                    messages: expect.arrayContaining([
                         expect.objectContaining({
-                            type: "function",
-                            function: expect.objectContaining({
-                                name: "get_lines",
-                            }),
+                            role: "user",
+                            content: "Read file",
                         }),
                     ]),
                 }),
             )
+            expect(mockOllamaInstance.chat).toHaveBeenCalledWith(
+                expect.not.objectContaining({
+                    tools: expect.anything(),
+                }),
+            )
         })
 
-        it("should extract tool calls from response", async () => {
+        it("should extract tool calls from XML in response content", async () => {
             mockOllamaInstance.chat.mockResolvedValue({
                 message: {
                     role: "assistant",
-                    content: "",
-                    tool_calls: [
-                        {
-                            function: {
-                                name: "get_lines",
-                                arguments: { path: "src/index.ts" },
-                            },
-                        },
-                    ],
+                    content: '<tool_call name="get_lines"><path>src/index.ts</path></tool_call>',
+                    tool_calls: undefined,
                 },
                 eval_count: 30,
             })
@@ -424,48 +407,6 @@ describe("OllamaClient", () => {
         })
     })
 
-    describe("tool parameter conversion", () => {
-        it("should include enum values when present", async () => {
-            const client = new OllamaClient(defaultConfig)
-            const messages = [createUserMessage("Get status")]
-            const tools = [
-                {
-                    name: "get_status",
-                    description: "Get status",
-                    parameters: [
-                        {
-                            name: "type",
-                            type: "string" as const,
-                            description: "Status type",
-                            required: true,
-                            enum: ["active", "inactive", "pending"],
-                        },
-                    ],
-                },
-            ]
-
-            await client.chat(messages, tools)
-
-            expect(mockOllamaInstance.chat).toHaveBeenCalledWith(
-                expect.objectContaining({
-                    tools: expect.arrayContaining([
-                        expect.objectContaining({
-                            function: expect.objectContaining({
-                                parameters: expect.objectContaining({
-                                    properties: expect.objectContaining({
-                                        type: expect.objectContaining({
-                                            enum: ["active", "inactive", "pending"],
-                                        }),
-                                    }),
-                                }),
-                            }),
-                        }),
-                    ]),
-                }),
-            )
-        })
-    })
-
     describe("error handling", () => {
         it("should handle ECONNREFUSED errors", async () => {
             mockOllamaInstance.chat.mockRejectedValue(new Error("ECONNREFUSED"))
@@ -484,5 +425,27 @@ describe("OllamaClient", () => {
 
             await expect(client.pullModel("test")).rejects.toThrow(/Failed to pull model/)
         })
+
+        it("should handle AbortError correctly", async () => {
+            const abortError = new Error("aborted")
+            abortError.name = "AbortError"
+            mockOllamaInstance.chat.mockRejectedValue(abortError)
+
+            const client = new OllamaClient(defaultConfig)
+
+            await expect(client.chat([createUserMessage("Hello")])).rejects.toThrow(
+                /Request was aborted/,
+            )
+        })
+
+        it("should handle model not found errors", async () => {
+            mockOllamaInstance.chat.mockRejectedValue(new Error("model 'unknown' not found"))
+
+            const client = new OllamaClient(defaultConfig)
+
+            await expect(client.chat([createUserMessage("Hello")])).rejects.toThrow(
+                /Model.*not found/,
+            )
+        })
     })
 })

packages/ipuaro/tests/unit/infrastructure/llm/ResponseParser.test.ts

@@ -72,7 +72,7 @@ describe("ResponseParser", () => {
         })
 
         it("should parse null values", () => {
-            const response = `<tool_call name="test">
+            const response = `<tool_call name="get_lines">
                 <value>null</value>
             </tool_call>`
 
@@ -92,7 +92,7 @@ describe("ResponseParser", () => {
         })
 
         it("should parse JSON objects", () => {
-            const response = `<tool_call name="test">
+            const response = `<tool_call name="get_lines">
                 <config>{"key": "value"}</config>
             </tool_call>`
 
@@ -123,6 +123,59 @@ describe("ResponseParser", () => {
                 start: 5,
             })
         })
+
+        it("should reject unknown tool names", () => {
+            const response = `<tool_call name="unknown_tool"><path>test.ts</path></tool_call>`
+
+            const result = parseToolCalls(response)
+
+            expect(result.toolCalls).toHaveLength(0)
+            expect(result.hasParseErrors).toBe(true)
+            expect(result.parseErrors[0]).toContain("Unknown tool")
+            expect(result.parseErrors[0]).toContain("unknown_tool")
+        })
+
+        it("should support CDATA for multiline content", () => {
+            const response = `<tool_call name="edit_lines">
+                <path>src/index.ts</path>
+                <content><![CDATA[const x = 1;
+const y = 2;]]></content>
+            </tool_call>`
+
+            const result = parseToolCalls(response)
+
+            expect(result.toolCalls[0].params.content).toBe("const x = 1;\nconst y = 2;")
+        })
+
+        it("should handle multiple tool calls with mixed content", () => {
+            const response = `Some text
+<tool_call name="get_lines"><path>a.ts</path></tool_call>
+More text
+<tool_call name="get_function"><path>b.ts</path><name>foo</name></tool_call>`
+
+            const result = parseToolCalls(response)
+
+            expect(result.toolCalls).toHaveLength(2)
+            expect(result.toolCalls[0].name).toBe("get_lines")
+            expect(result.toolCalls[1].name).toBe("get_function")
+            expect(result.content).toContain("Some text")
+            expect(result.content).toContain("More text")
+        })
+
+        it("should handle parse errors gracefully and continue", () => {
+            const response = `<tool_call name="unknown_tool1"><path>test.ts</path></tool_call>
+<tool_call name="get_lines"><path>valid.ts</path></tool_call>
+<tool_call name="unknown_tool2"><path>test2.ts</path></tool_call>`
+
+            const result = parseToolCalls(response)
+
+            expect(result.toolCalls).toHaveLength(1)
+            expect(result.toolCalls[0].name).toBe("get_lines")
+            expect(result.hasParseErrors).toBe(true)
+            expect(result.parseErrors).toHaveLength(2)
+            expect(result.parseErrors[0]).toContain("unknown_tool1")
+            expect(result.parseErrors[1]).toContain("unknown_tool2")
+        })
     })
 
     describe("formatToolCallsAsXml", () => {

packages/ipuaro/tests/unit/infrastructure/security/PathValidator.test.ts

@@ -0,0 +1,320 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import * as path from "node:path"
+import * as fs from "node:fs/promises"
+import * as os from "node:os"
+import {
+    PathValidator,
+    createPathValidator,
+    validatePath,
+} from "../../../../src/infrastructure/security/PathValidator.js"
+
+describe("PathValidator", () => {
+    let validator: PathValidator
+    let tempDir: string
+    let projectRoot: string
+
+    beforeEach(async () => {
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "pathvalidator-test-"))
+        projectRoot = path.join(tempDir, "project")
+        await fs.mkdir(projectRoot)
+        validator = new PathValidator(projectRoot)
+    })
+
+    afterEach(async () => {
+        await fs.rm(tempDir, { recursive: true, force: true })
+    })
+
+    describe("constructor", () => {
+        it("should resolve project root to absolute path", () => {
+            const relativeValidator = new PathValidator("./project")
+            expect(relativeValidator.getProjectRoot()).toBe(path.resolve("./project"))
+        })
+
+        it("should store project root", () => {
+            expect(validator.getProjectRoot()).toBe(projectRoot)
+        })
+    })
+
+    describe("validateSync", () => {
+        it("should validate relative path within project", () => {
+            const result = validator.validateSync("src/file.ts")
+            expect(result.status).toBe("valid")
+            expect(result.absolutePath).toBe(path.join(projectRoot, "src/file.ts"))
+            expect(result.relativePath).toBe(path.join("src", "file.ts"))
+        })
+
+        it("should validate nested relative paths", () => {
+            const result = validator.validateSync("src/components/Button.tsx")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should validate root level files", () => {
+            const result = validator.validateSync("package.json")
+            expect(result.status).toBe("valid")
+            expect(result.relativePath).toBe("package.json")
+        })
+
+        it("should reject empty path", () => {
+            const result = validator.validateSync("")
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path is empty")
+        })
+
+        it("should reject whitespace-only path", () => {
+            const result = validator.validateSync("   ")
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path is empty")
+        })
+
+        it("should reject path with .. traversal", () => {
+            const result = validator.validateSync("../outside")
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path contains traversal patterns")
+        })
+
+        it("should reject path with embedded .. traversal", () => {
+            const result = validator.validateSync("src/../../../etc/passwd")
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path contains traversal patterns")
+        })
+
+        it("should reject path starting with tilde", () => {
+            const result = validator.validateSync("~/secret/file")
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path contains traversal patterns")
+        })
+
+        it("should reject absolute path outside project", () => {
+            const result = validator.validateSync("/etc/passwd")
+            expect(result.status).toBe("outside_project")
+            expect(result.reason).toBe("Path is outside project root")
+        })
+
+        it("should accept absolute path inside project", () => {
+            const absoluteInside = path.join(projectRoot, "src/file.ts")
+            const result = validator.validateSync(absoluteInside)
+            expect(result.status).toBe("valid")
+        })
+
+        it("should trim whitespace from path", () => {
+            const result = validator.validateSync("  src/file.ts  ")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should handle Windows-style backslashes", () => {
+            const result = validator.validateSync("src\\components\\file.ts")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should reject path that resolves outside via symlink-like patterns", () => {
+            const result = validator.validateSync("src/./../../etc")
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path contains traversal patterns")
+        })
+    })
+
+    describe("validate (async)", () => {
+        beforeEach(async () => {
+            await fs.mkdir(path.join(projectRoot, "src"), { recursive: true })
+            await fs.writeFile(path.join(projectRoot, "src/file.ts"), "// content")
+            await fs.mkdir(path.join(projectRoot, "dist"), { recursive: true })
+        })
+
+        it("should validate existing file", async () => {
+            const result = await validator.validate("src/file.ts")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should reject non-existent file by default", async () => {
+            const result = await validator.validate("src/nonexistent.ts")
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path does not exist")
+        })
+
+        it("should allow non-existent file with allowNonExistent option", async () => {
+            const result = await validator.validate("src/newfile.ts", { allowNonExistent: true })
+            expect(result.status).toBe("valid")
+        })
+
+        it("should validate directory when requireDirectory is true", async () => {
+            const result = await validator.validate("src", { requireDirectory: true })
+            expect(result.status).toBe("valid")
+        })
+
+        it("should reject file when requireDirectory is true", async () => {
+            const result = await validator.validate("src/file.ts", { requireDirectory: true })
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path is not a directory")
+        })
+
+        it("should validate file when requireFile is true", async () => {
+            const result = await validator.validate("src/file.ts", { requireFile: true })
+            expect(result.status).toBe("valid")
+        })
+
+        it("should reject directory when requireFile is true", async () => {
+            const result = await validator.validate("src", { requireFile: true })
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path is not a file")
+        })
+
+        it("should handle permission errors gracefully", async () => {
+            const result = await validator.validate("src/../../../root/secret")
+            expect(result.status).toBe("invalid")
+        })
+
+        it("should still check traversal before existence", async () => {
+            const result = await validator.validate("../outside", { allowNonExistent: true })
+            expect(result.status).toBe("invalid")
+            expect(result.reason).toBe("Path contains traversal patterns")
+        })
+    })
+
+    describe("isWithin", () => {
+        it("should return true for path within project", () => {
+            expect(validator.isWithin("src/file.ts")).toBe(true)
+        })
+
+        it("should return true for project root itself", () => {
+            expect(validator.isWithin(".")).toBe(true)
+            expect(validator.isWithin("")).toBe(false)
+        })
+
+        it("should return false for path outside project", () => {
+            expect(validator.isWithin("/etc/passwd")).toBe(false)
+        })
+
+        it("should return false for traversal path", () => {
+            expect(validator.isWithin("../outside")).toBe(false)
+        })
+
+        it("should return false for empty path", () => {
+            expect(validator.isWithin("")).toBe(false)
+        })
+
+        it("should return false for tilde path", () => {
+            expect(validator.isWithin("~/file")).toBe(false)
+        })
+    })
+
+    describe("resolve", () => {
+        it("should resolve valid relative path to absolute", () => {
+            const result = validator.resolve("src/file.ts")
+            expect(result).toBe(path.join(projectRoot, "src/file.ts"))
+        })
+
+        it("should return null for invalid path", () => {
+            expect(validator.resolve("../outside")).toBeNull()
+        })
+
+        it("should return null for empty path", () => {
+            expect(validator.resolve("")).toBeNull()
+        })
+
+        it("should return null for path outside project", () => {
+            expect(validator.resolve("/etc/passwd")).toBeNull()
+        })
+    })
+
+    describe("relativize", () => {
+        it("should return relative path for valid input", () => {
+            const result = validator.relativize("src/file.ts")
+            expect(result).toBe(path.join("src", "file.ts"))
+        })
+
+        it("should handle absolute path within project", () => {
+            const absolutePath = path.join(projectRoot, "src/file.ts")
+            const result = validator.relativize(absolutePath)
+            expect(result).toBe(path.join("src", "file.ts"))
+        })
+
+        it("should return null for path outside project", () => {
+            expect(validator.relativize("/etc/passwd")).toBeNull()
+        })
+
+        it("should return null for traversal path", () => {
+            expect(validator.relativize("../outside")).toBeNull()
+        })
+    })
+
+    describe("edge cases", () => {
+        it("should handle path with multiple slashes", () => {
+            const result = validator.validateSync("src///file.ts")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should handle path with dots in filename", () => {
+            const result = validator.validateSync("src/file.test.ts")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should handle hidden files", () => {
+            const result = validator.validateSync(".gitignore")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should handle hidden directories", () => {
+            const result = validator.validateSync(".github/workflows/ci.yml")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should handle single dot current directory", () => {
+            const result = validator.validateSync("./src/file.ts")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should handle project root as path", () => {
+            const result = validator.validateSync(projectRoot)
+            expect(result.status).toBe("valid")
+        })
+
+        it("should handle unicode characters in path", () => {
+            const result = validator.validateSync("src/файл.ts")
+            expect(result.status).toBe("valid")
+        })
+
+        it("should handle spaces in path", () => {
+            const result = validator.validateSync("src/my file.ts")
+            expect(result.status).toBe("valid")
+        })
+    })
+})
+
+describe("createPathValidator", () => {
+    it("should create PathValidator instance", () => {
+        const validator = createPathValidator("/tmp/project")
+        expect(validator).toBeInstanceOf(PathValidator)
+        expect(validator.getProjectRoot()).toBe("/tmp/project")
+    })
+})
+
+describe("validatePath", () => {
+    let tempDir: string
+    let projectRoot: string
+
+    beforeEach(async () => {
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "validatepath-test-"))
+        projectRoot = path.join(tempDir, "project")
+        await fs.mkdir(projectRoot)
+    })
+
+    afterEach(async () => {
+        await fs.rm(tempDir, { recursive: true, force: true })
+    })
+
+    it("should return true for valid path", () => {
+        expect(validatePath("src/file.ts", projectRoot)).toBe(true)
+    })
+
+    it("should return false for traversal path", () => {
+        expect(validatePath("../outside", projectRoot)).toBe(false)
+    })
+
+    it("should return false for path outside project", () => {
+        expect(validatePath("/etc/passwd", projectRoot)).toBe(false)
+    })
+
+    it("should return false for empty path", () => {
+        expect(validatePath("", projectRoot)).toBe(false)
+    })
+})

packages/ipuaro/tests/unit/infrastructure/tools/edit/CreateFileTool.test.ts

@@ -224,7 +224,7 @@ describe("CreateFileTool", () => {
             const result = await tool.execute({ path: "../outside/file.ts", content: "test" }, ctx)
 
             expect(result.success).toBe(false)
-            expect(result.error).toBe("Path must be within project root")
+            expect(result.error).toBe("Path contains traversal patterns")
         })
 
         it("should return error if file already exists", async () => {

packages/ipuaro/tests/unit/infrastructure/tools/edit/DeleteFileTool.test.ts

@@ -189,7 +189,7 @@ describe("DeleteFileTool", () => {
             const result = await tool.execute({ path: "../outside/file.ts" }, ctx)
 
             expect(result.success).toBe(false)
-            expect(result.error).toBe("Path must be within project root")
+            expect(result.error).toBe("Path contains traversal patterns")
         })
 
         it("should return error if file does not exist", async () => {

packages/ipuaro/tests/unit/infrastructure/tools/edit/EditLinesTool.test.ts

@@ -296,7 +296,7 @@ describe("EditLinesTool", () => {
             )
 
             expect(result.success).toBe(false)
-            expect(result.error).toBe("Path must be within project root")
+            expect(result.error).toBe("Path contains traversal patterns")
         })
 
         it("should return error when start exceeds file length", async () => {

packages/ipuaro/tests/unit/infrastructure/tools/read/GetClassTool.test.ts

@@ -271,7 +271,7 @@ describe("GetClassTool", () => {
             const result = await tool.execute({ path: "../outside/file.ts", name: "MyClass" }, ctx)
 
             expect(result.success).toBe(false)
-            expect(result.error).toBe("Path must be within project root")
+            expect(result.error).toBe("Path contains traversal patterns")
         })
 
         it("should handle class with no extends", async () => {
@@ -344,5 +344,47 @@ describe("GetClassTool", () => {
 
             expect(result.callId).toMatch(/^get_class-\d+$/)
         })
+
+        it("should handle undefined extends in class", async () => {
+            const lines = ["class StandaloneClass { method() {} }"]
+            const cls = createMockClass({
+                name: "StandaloneClass",
+                lineStart: 1,
+                lineEnd: 1,
+                extends: undefined,
+                methods: [{ name: "method", lineStart: 1, lineEnd: 1 }],
+            })
+            const ast = createMockAST([cls])
+            const storage = createMockStorage({ lines }, ast)
+            const ctx = createMockContext(storage)
+
+            const result = await tool.execute({ path: "test.ts", name: "StandaloneClass" }, ctx)
+
+            expect(result.success).toBe(true)
+            const data = result.data as GetClassResult
+            expect(data.extends).toBeUndefined()
+            expect(data.methods.length).toBe(1)
+        })
+
+        it("should handle error when reading lines fails", async () => {
+            const ast = createMockAST([createMockClass({ name: "Test", lineStart: 1, lineEnd: 1 })])
+            const storage: IStorage = {
+                getFile: vi.fn().mockResolvedValue(null),
+                getAST: vi.fn().mockResolvedValue(ast),
+                setFile: vi.fn(),
+                deleteFile: vi.fn(),
+                getAllFiles: vi.fn(),
+                setAST: vi.fn(),
+                getSymbolIndex: vi.fn(),
+                setSymbolIndex: vi.fn(),
+                getDepsGraph: vi.fn(),
+                setDepsGraph: vi.fn(),
+            }
+            const ctx = createMockContext(storage)
+
+            const result = await tool.execute({ path: "test.ts", name: "Test" }, ctx)
+
+            expect(result.success).toBe(false)
+        })
     })
 })

packages/ipuaro/tests/unit/infrastructure/tools/read/GetFunctionTool.test.ts

@@ -229,7 +229,7 @@ describe("GetFunctionTool", () => {
             const result = await tool.execute({ path: "../outside/file.ts", name: "myFunc" }, ctx)
 
             expect(result.success).toBe(false)
-            expect(result.error).toBe("Path must be within project root")
+            expect(result.error).toBe("Path contains traversal patterns")
         })
 
         it("should pad line numbers correctly for large files", async () => {
@@ -301,5 +301,49 @@ describe("GetFunctionTool", () => {
             const data = result.data as GetFunctionResult
             expect(data.params).toEqual([])
         })
+
+        it("should handle error when reading lines fails", async () => {
+            const ast = createMockAST([
+                createMockFunction({ name: "test", lineStart: 1, lineEnd: 1 }),
+            ])
+            const storage: IStorage = {
+                getFile: vi.fn().mockResolvedValue(null),
+                getAST: vi.fn().mockResolvedValue(ast),
+                setFile: vi.fn(),
+                deleteFile: vi.fn(),
+                getAllFiles: vi.fn(),
+                setAST: vi.fn(),
+                getSymbolIndex: vi.fn(),
+                setSymbolIndex: vi.fn(),
+                getDepsGraph: vi.fn(),
+                setDepsGraph: vi.fn(),
+            }
+            const ctx = createMockContext(storage)
+
+            const result = await tool.execute({ path: "test.ts", name: "test" }, ctx)
+
+            expect(result.success).toBe(false)
+        })
+
+        it("should handle undefined returnType", async () => {
+            const lines = ["function implicitReturn() { return }"]
+            const func = createMockFunction({
+                name: "implicitReturn",
+                lineStart: 1,
+                lineEnd: 1,
+                returnType: undefined,
+                isAsync: false,
+            })
+            const ast = createMockAST([func])
+            const storage = createMockStorage({ lines }, ast)
+            const ctx = createMockContext(storage)
+
+            const result = await tool.execute({ path: "test.ts", name: "implicitReturn" }, ctx)
+
+            expect(result.success).toBe(true)
+            const data = result.data as GetFunctionResult
+            expect(data.returnType).toBeUndefined()
+            expect(data.isAsync).toBe(false)
+        })
     })
 })

packages/ipuaro/tests/unit/infrastructure/tools/read/GetLinesTool.test.ts

@@ -214,7 +214,7 @@ describe("GetLinesTool", () => {
             const result = await tool.execute({ path: "../outside/file.ts" }, ctx)
 
             expect(result.success).toBe(false)
-            expect(result.error).toBe("Path must be within project root")
+            expect(result.error).toBe("Path contains traversal patterns")
         })
 
         it("should return error when file not found", async () => {
@@ -269,5 +269,69 @@ describe("GetLinesTool", () => {
             expect(data.totalLines).toBe(1)
             expect(data.content).toBe("1│only line")
         })
+
+        it("should read from filesystem fallback when not in storage", async () => {
+            const storage: IStorage = {
+                getFile: vi.fn().mockResolvedValue(null),
+                setFile: vi.fn(),
+                deleteFile: vi.fn(),
+                getAllFiles: vi.fn(),
+                getAST: vi.fn(),
+                setAST: vi.fn(),
+                getSymbolIndex: vi.fn(),
+                setSymbolIndex: vi.fn(),
+                getDepsGraph: vi.fn(),
+                setDepsGraph: vi.fn(),
+            }
+
+            const ctx = createMockContext(storage)
+
+            const result = await tool.execute({ path: "test.ts" }, ctx)
+
+            expect(storage.getFile).toHaveBeenCalledWith("test.ts")
+
+            if (result.success) {
+                expect(result.success).toBe(true)
+            } else {
+                expect(result.error).toBeDefined()
+            }
+        })
+
+        it("should handle when start equals end", async () => {
+            const storage = createMockStorage({ lines: ["line 1", "line 2", "line 3"] })
+            const ctx = createMockContext(storage)
+
+            const result = await tool.execute({ path: "test.ts", start: 2, end: 2 }, ctx)
+
+            expect(result.success).toBe(true)
+            const data = result.data as GetLinesResult
+            expect(data.startLine).toBe(2)
+            expect(data.endLine).toBe(2)
+            expect(data.content).toContain("line 2")
+        })
+
+        it("should handle undefined end parameter", async () => {
+            const storage = createMockStorage({ lines: ["line 1", "line 2", "line 3"] })
+            const ctx = createMockContext(storage)
+
+            const result = await tool.execute({ path: "test.ts", start: 2, end: undefined }, ctx)
+
+            expect(result.success).toBe(true)
+            const data = result.data as GetLinesResult
+            expect(data.startLine).toBe(2)
+            expect(data.endLine).toBe(3)
+        })
+
+        it("should handle undefined start parameter", async () => {
+            const storage = createMockStorage({ lines: ["line 1", "line 2", "line 3"] })
+            const ctx = createMockContext(storage)
+
+            const result = await tool.execute({ path: "test.ts", start: undefined, end: 2 }, ctx)
+
+            expect(result.success).toBe(true)
+            const data = result.data as GetLinesResult
+            expect(data.startLine).toBe(1)
+            expect(data.endLine).toBe(2)
+        })
     })
 })

packages/ipuaro/tests/unit/infrastructure/tools/read/GetStructureTool.test.ts

@@ -228,7 +228,7 @@ describe("GetStructureTool", () => {
             const result = await tool.execute({ path: "../outside" }, ctx)
 
             expect(result.success).toBe(false)
-            expect(result.error).toBe("Path must be within project root")
+            expect(result.error).toBe("Path contains traversal patterns")
         })
 
         it("should return error for non-directory path", async () => {

packages/ipuaro/tests/unit/infrastructure/tools/run/RunCommandTool.test.ts

@@ -354,6 +354,36 @@ describe("RunCommandTool", () => {
             expect(execFn).toHaveBeenCalledWith("ls", expect.objectContaining({ timeout: 5000 }))
         })
 
+        it("should use config timeout", async () => {
+            const execFn = createMockExec({})
+            const toolWithMock = new RunCommandTool(undefined, execFn, { timeout: 45000 })
+            const ctx = createMockContext()
+
+            await toolWithMock.execute({ command: "ls" }, ctx)
+
+            expect(execFn).toHaveBeenCalledWith("ls", expect.objectContaining({ timeout: 45000 }))
+        })
+
+        it("should use null config timeout as default", async () => {
+            const execFn = createMockExec({})
+            const toolWithMock = new RunCommandTool(undefined, execFn, { timeout: null })
+            const ctx = createMockContext()
+
+            await toolWithMock.execute({ command: "ls" }, ctx)
+
+            expect(execFn).toHaveBeenCalledWith("ls", expect.objectContaining({ timeout: 30000 }))
+        })
+
+        it("should prefer param timeout over config timeout", async () => {
+            const execFn = createMockExec({})
+            const toolWithMock = new RunCommandTool(undefined, execFn, { timeout: 45000 })
+            const ctx = createMockContext()
+
+            await toolWithMock.execute({ command: "ls", timeout: 5000 }, ctx)
+
+            expect(execFn).toHaveBeenCalledWith("ls", expect.objectContaining({ timeout: 5000 }))
+        })
+
         it("should execute in project root", async () => {
             const execFn = createMockExec({})
             const toolWithMock = new RunCommandTool(undefined, execFn)

packages/ipuaro/tests/unit/shared/autocomplete-config.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Tests for AutocompleteConfigSchema.
+ */
+
+import { describe, expect, it } from "vitest"
+import { AutocompleteConfigSchema } from "../../../src/shared/constants/config.js"
+
+describe("AutocompleteConfigSchema", () => {
+    describe("default values", () => {
+        it("should use defaults when empty object provided", () => {
+            const result = AutocompleteConfigSchema.parse({})
+
+            expect(result).toEqual({
+                enabled: true,
+                source: "redis-index",
+                maxSuggestions: 10,
+            })
+        })
+
+        it("should use defaults via .default({})", () => {
+            const result = AutocompleteConfigSchema.default({}).parse({})
+
+            expect(result).toEqual({
+                enabled: true,
+                source: "redis-index",
+                maxSuggestions: 10,
+            })
+        })
+    })
+
+    describe("enabled", () => {
+        it("should accept true", () => {
+            const result = AutocompleteConfigSchema.parse({ enabled: true })
+            expect(result.enabled).toBe(true)
+        })
+
+        it("should accept false", () => {
+            const result = AutocompleteConfigSchema.parse({ enabled: false })
+            expect(result.enabled).toBe(false)
+        })
+
+        it("should reject non-boolean", () => {
+            expect(() => AutocompleteConfigSchema.parse({ enabled: "true" })).toThrow()
+        })
+
+        it("should reject number", () => {
+            expect(() => AutocompleteConfigSchema.parse({ enabled: 1 })).toThrow()
+        })
+    })
+
+    describe("source", () => {
+        it("should accept redis-index", () => {
+            const result = AutocompleteConfigSchema.parse({ source: "redis-index" })
+            expect(result.source).toBe("redis-index")
+        })
+
+        it("should accept filesystem", () => {
+            const result = AutocompleteConfigSchema.parse({ source: "filesystem" })
+            expect(result.source).toBe("filesystem")
+        })
+
+        it("should accept both", () => {
+            const result = AutocompleteConfigSchema.parse({ source: "both" })
+            expect(result.source).toBe("both")
+        })
+
+        it("should use default redis-index", () => {
+            const result = AutocompleteConfigSchema.parse({})
+            expect(result.source).toBe("redis-index")
+        })
+
+        it("should reject invalid source", () => {
+            expect(() => AutocompleteConfigSchema.parse({ source: "invalid" })).toThrow()
+        })
+
+        it("should reject non-string", () => {
+            expect(() => AutocompleteConfigSchema.parse({ source: 123 })).toThrow()
+        })
+    })
+
+    describe("maxSuggestions", () => {
+        it("should accept valid positive integer", () => {
+            const result = AutocompleteConfigSchema.parse({ maxSuggestions: 5 })
+            expect(result.maxSuggestions).toBe(5)
+        })
+
+        it("should accept default value", () => {
+            const result = AutocompleteConfigSchema.parse({ maxSuggestions: 10 })
+            expect(result.maxSuggestions).toBe(10)
+        })
+
+        it("should accept large value", () => {
+            const result = AutocompleteConfigSchema.parse({ maxSuggestions: 100 })
+            expect(result.maxSuggestions).toBe(100)
+        })
+
+        it("should accept 1", () => {
+            const result = AutocompleteConfigSchema.parse({ maxSuggestions: 1 })
+            expect(result.maxSuggestions).toBe(1)
+        })
+
+        it("should reject zero", () => {
+            expect(() => AutocompleteConfigSchema.parse({ maxSuggestions: 0 })).toThrow()
+        })
+
+        it("should reject negative number", () => {
+            expect(() => AutocompleteConfigSchema.parse({ maxSuggestions: -5 })).toThrow()
+        })
+
+        it("should reject float", () => {
+            expect(() => AutocompleteConfigSchema.parse({ maxSuggestions: 10.5 })).toThrow()
+        })
+
+        it("should reject non-number", () => {
+            expect(() => AutocompleteConfigSchema.parse({ maxSuggestions: "10" })).toThrow()
+        })
+    })
+
+    describe("partial config", () => {
+        it("should merge partial config with defaults (enabled only)", () => {
+            const result = AutocompleteConfigSchema.parse({
+                enabled: false,
+            })
+
+            expect(result).toEqual({
+                enabled: false,
+                source: "redis-index",
+                maxSuggestions: 10,
+            })
+        })
+
+        it("should merge partial config with defaults (source only)", () => {
+            const result = AutocompleteConfigSchema.parse({
+                source: "filesystem",
+            })
+
+            expect(result).toEqual({
+                enabled: true,
+                source: "filesystem",
+                maxSuggestions: 10,
+            })
+        })
+
+        it("should merge partial config with defaults (maxSuggestions only)", () => {
+            const result = AutocompleteConfigSchema.parse({
+                maxSuggestions: 20,
+            })
+
+            expect(result).toEqual({
+                enabled: true,
+                source: "redis-index",
+                maxSuggestions: 20,
+            })
+        })
+
+        it("should merge multiple partial fields", () => {
+            const result = AutocompleteConfigSchema.parse({
+                enabled: false,
+                maxSuggestions: 5,
+            })
+
+            expect(result).toEqual({
+                enabled: false,
+                source: "redis-index",
+                maxSuggestions: 5,
+            })
+        })
+    })
+
+    describe("full config", () => {
+        it("should accept valid full config", () => {
+            const config = {
+                enabled: false,
+                source: "both" as const,
+                maxSuggestions: 15,
+            }
+
+            const result = AutocompleteConfigSchema.parse(config)
+            expect(result).toEqual(config)
+        })
+
+        it("should accept all defaults explicitly", () => {
+            const config = {
+                enabled: true,
+                source: "redis-index" as const,
+                maxSuggestions: 10,
+            }
+
+            const result = AutocompleteConfigSchema.parse(config)
+            expect(result).toEqual(config)
+        })
+
+        it("should accept filesystem as source", () => {
+            const config = {
+                enabled: true,
+                source: "filesystem" as const,
+                maxSuggestions: 20,
+            }
+
+            const result = AutocompleteConfigSchema.parse(config)
+            expect(result).toEqual(config)
+        })
+    })
+})

packages/ipuaro/tests/unit/shared/commands-config.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Tests for CommandsConfigSchema.
+ */
+
+import { describe, expect, it } from "vitest"
+import { CommandsConfigSchema } from "../../../src/shared/constants/config.js"
+
+describe("CommandsConfigSchema", () => {
+    describe("default values", () => {
+        it("should use defaults when empty object provided", () => {
+            const result = CommandsConfigSchema.parse({})
+
+            expect(result).toEqual({
+                timeout: null,
+            })
+        })
+
+        it("should use defaults via .default({})", () => {
+            const result = CommandsConfigSchema.default({}).parse({})
+
+            expect(result).toEqual({
+                timeout: null,
+            })
+        })
+    })
+
+    describe("timeout", () => {
+        it("should accept null (default)", () => {
+            const result = CommandsConfigSchema.parse({ timeout: null })
+            expect(result.timeout).toBe(null)
+        })
+
+        it("should accept positive integer", () => {
+            const result = CommandsConfigSchema.parse({ timeout: 5000 })
+            expect(result.timeout).toBe(5000)
+        })
+
+        it("should accept large timeout", () => {
+            const result = CommandsConfigSchema.parse({ timeout: 600000 })
+            expect(result.timeout).toBe(600000)
+        })
+
+        it("should accept 1", () => {
+            const result = CommandsConfigSchema.parse({ timeout: 1 })
+            expect(result.timeout).toBe(1)
+        })
+
+        it("should accept small timeout", () => {
+            const result = CommandsConfigSchema.parse({ timeout: 100 })
+            expect(result.timeout).toBe(100)
+        })
+
+        it("should reject zero", () => {
+            expect(() => CommandsConfigSchema.parse({ timeout: 0 })).toThrow()
+        })
+
+        it("should reject negative number", () => {
+            expect(() => CommandsConfigSchema.parse({ timeout: -5000 })).toThrow()
+        })
+
+        it("should reject float", () => {
+            expect(() => CommandsConfigSchema.parse({ timeout: 5000.5 })).toThrow()
+        })
+
+        it("should reject string", () => {
+            expect(() => CommandsConfigSchema.parse({ timeout: "5000" })).toThrow()
+        })
+
+        it("should reject boolean", () => {
+            expect(() => CommandsConfigSchema.parse({ timeout: true })).toThrow()
+        })
+
+        it("should reject undefined (use null instead)", () => {
+            const result = CommandsConfigSchema.parse({ timeout: undefined })
+            expect(result.timeout).toBe(null)
+        })
+    })
+
+    describe("partial config", () => {
+        it("should use default null when timeout not provided", () => {
+            const result = CommandsConfigSchema.parse({})
+
+            expect(result).toEqual({
+                timeout: null,
+            })
+        })
+
+        it("should accept explicit null", () => {
+            const result = CommandsConfigSchema.parse({
+                timeout: null,
+            })
+
+            expect(result).toEqual({
+                timeout: null,
+            })
+        })
+
+        it("should accept explicit timeout value", () => {
+            const result = CommandsConfigSchema.parse({
+                timeout: 10000,
+            })
+
+            expect(result).toEqual({
+                timeout: 10000,
+            })
+        })
+    })
+
+    describe("full config", () => {
+        it("should accept valid config with null", () => {
+            const config = {
+                timeout: null,
+            }
+
+            const result = CommandsConfigSchema.parse(config)
+            expect(result).toEqual(config)
+        })
+
+        it("should accept valid config with timeout", () => {
+            const config = {
+                timeout: 30000,
+            }
+
+            const result = CommandsConfigSchema.parse(config)
+            expect(result).toEqual(config)
+        })
+
+        it("should accept default explicitly", () => {
+            const config = {
+                timeout: null,
+            }
+
+            const result = CommandsConfigSchema.parse(config)
+            expect(result).toEqual(config)
+        })
+    })
+})

packages/ipuaro/tests/unit/shared/context-config.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Tests for ContextConfigSchema.
+ */
+
+import { describe, expect, it } from "vitest"
+import { ContextConfigSchema } from "../../../src/shared/constants/config.js"
+
+describe("ContextConfigSchema", () => {
+    describe("default values", () => {
+        it("should use defaults when empty object provided", () => {
+            const result = ContextConfigSchema.parse({})
+
+            expect(result).toEqual({
+                systemPromptTokens: 2000,
+                maxContextUsage: 0.8,
+                autoCompressAt: 0.8,
+                compressionMethod: "llm-summary",
+            })
+        })
+
+        it("should use defaults via .default({})", () => {
+            const result = ContextConfigSchema.default({}).parse({})
+
+            expect(result).toEqual({
+                systemPromptTokens: 2000,
+                maxContextUsage: 0.8,
+                autoCompressAt: 0.8,
+                compressionMethod: "llm-summary",
+            })
+        })
+    })
+
+    describe("systemPromptTokens", () => {
+        it("should accept valid positive integer", () => {
+            const result = ContextConfigSchema.parse({ systemPromptTokens: 1500 })
+            expect(result.systemPromptTokens).toBe(1500)
+        })
+
+        it("should accept default value", () => {
+            const result = ContextConfigSchema.parse({ systemPromptTokens: 2000 })
+            expect(result.systemPromptTokens).toBe(2000)
+        })
+
+        it("should accept large value", () => {
+            const result = ContextConfigSchema.parse({ systemPromptTokens: 5000 })
+            expect(result.systemPromptTokens).toBe(5000)
+        })
+
+        it("should reject zero", () => {
+            expect(() => ContextConfigSchema.parse({ systemPromptTokens: 0 })).toThrow()
+        })
+
+        it("should reject negative number", () => {
+            expect(() => ContextConfigSchema.parse({ systemPromptTokens: -100 })).toThrow()
+        })
+
+        it("should reject float", () => {
+            expect(() => ContextConfigSchema.parse({ systemPromptTokens: 1500.5 })).toThrow()
+        })
+
+        it("should reject non-number", () => {
+            expect(() => ContextConfigSchema.parse({ systemPromptTokens: "2000" })).toThrow()
+        })
+    })
+
+    describe("maxContextUsage", () => {
+        it("should accept valid ratio", () => {
+            const result = ContextConfigSchema.parse({ maxContextUsage: 0.7 })
+            expect(result.maxContextUsage).toBe(0.7)
+        })
+
+        it("should accept default value", () => {
+            const result = ContextConfigSchema.parse({ maxContextUsage: 0.8 })
+            expect(result.maxContextUsage).toBe(0.8)
+        })
+
+        it("should accept minimum value (0)", () => {
+            const result = ContextConfigSchema.parse({ maxContextUsage: 0 })
+            expect(result.maxContextUsage).toBe(0)
+        })
+
+        it("should accept maximum value (1)", () => {
+            const result = ContextConfigSchema.parse({ maxContextUsage: 1 })
+            expect(result.maxContextUsage).toBe(1)
+        })
+
+        it("should reject value above 1", () => {
+            expect(() => ContextConfigSchema.parse({ maxContextUsage: 1.1 })).toThrow()
+        })
+
+        it("should reject negative value", () => {
+            expect(() => ContextConfigSchema.parse({ maxContextUsage: -0.1 })).toThrow()
+        })
+
+        it("should reject non-number", () => {
+            expect(() => ContextConfigSchema.parse({ maxContextUsage: "0.8" })).toThrow()
+        })
+    })
+
+    describe("autoCompressAt", () => {
+        it("should accept valid ratio", () => {
+            const result = ContextConfigSchema.parse({ autoCompressAt: 0.75 })
+            expect(result.autoCompressAt).toBe(0.75)
+        })
+
+        it("should accept default value", () => {
+            const result = ContextConfigSchema.parse({ autoCompressAt: 0.8 })
+            expect(result.autoCompressAt).toBe(0.8)
+        })
+
+        it("should accept minimum value (0)", () => {
+            const result = ContextConfigSchema.parse({ autoCompressAt: 0 })
+            expect(result.autoCompressAt).toBe(0)
+        })
+
+        it("should accept maximum value (1)", () => {
+            const result = ContextConfigSchema.parse({ autoCompressAt: 1 })
+            expect(result.autoCompressAt).toBe(1)
+        })
+
+        it("should reject value above 1", () => {
+            expect(() => ContextConfigSchema.parse({ autoCompressAt: 1.5 })).toThrow()
+        })
+
+        it("should reject negative value", () => {
+            expect(() => ContextConfigSchema.parse({ autoCompressAt: -0.5 })).toThrow()
+        })
+
+        it("should reject non-number", () => {
+            expect(() => ContextConfigSchema.parse({ autoCompressAt: "0.8" })).toThrow()
+        })
+    })
+
+    describe("compressionMethod", () => {
+        it("should accept llm-summary", () => {
+            const result = ContextConfigSchema.parse({ compressionMethod: "llm-summary" })
+            expect(result.compressionMethod).toBe("llm-summary")
+        })
+
+        it("should accept truncate", () => {
+            const result = ContextConfigSchema.parse({ compressionMethod: "truncate" })
+            expect(result.compressionMethod).toBe("truncate")
+        })
+
+        it("should reject invalid method", () => {
+            expect(() => ContextConfigSchema.parse({ compressionMethod: "invalid" })).toThrow()
+        })
+
+        it("should reject non-string", () => {
+            expect(() => ContextConfigSchema.parse({ compressionMethod: 123 })).toThrow()
+        })
+    })
+
+    describe("partial config", () => {
+        it("should merge partial config with defaults (systemPromptTokens)", () => {
+            const result = ContextConfigSchema.parse({
+                systemPromptTokens: 3000,
+            })
+
+            expect(result).toEqual({
+                systemPromptTokens: 3000,
+                maxContextUsage: 0.8,
+                autoCompressAt: 0.8,
+                compressionMethod: "llm-summary",
+            })
+        })
+
+        it("should merge partial config with defaults (autoCompressAt)", () => {
+            const result = ContextConfigSchema.parse({
+                autoCompressAt: 0.9,
+            })
+
+            expect(result).toEqual({
+                systemPromptTokens: 2000,
+                maxContextUsage: 0.8,
+                autoCompressAt: 0.9,
+                compressionMethod: "llm-summary",
+            })
+        })
+
+        it("should merge multiple partial fields", () => {
+            const result = ContextConfigSchema.parse({
+                maxContextUsage: 0.7,
+                compressionMethod: "truncate",
+            })
+
+            expect(result).toEqual({
+                systemPromptTokens: 2000,
+                maxContextUsage: 0.7,
+                autoCompressAt: 0.8,
+                compressionMethod: "truncate",
+            })
+        })
+    })
+
+    describe("full config", () => {
+        it("should accept valid full config", () => {
+            const config = {
+                systemPromptTokens: 3000,
+                maxContextUsage: 0.9,
+                autoCompressAt: 0.85,
+                compressionMethod: "truncate" as const,
+            }
+
+            const result = ContextConfigSchema.parse(config)
+            expect(result).toEqual(config)
+        })
+
+        it("should accept all defaults explicitly", () => {
+            const config = {
+                systemPromptTokens: 2000,
+                maxContextUsage: 0.8,
+                autoCompressAt: 0.8,
+                compressionMethod: "llm-summary" as const,
+            }
+
+            const result = ContextConfigSchema.parse(config)
+            expect(result).toEqual(config)
+        })
+    })
+})

packages/ipuaro/tests/unit/shared/display-config.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Tests for DisplayConfigSchema.
+ */
+
+import { describe, expect, it } from "vitest"
+import { DisplayConfigSchema } from "../../../src/shared/constants/config.js"
+
+describe("DisplayConfigSchema", () => {
+    describe("default values", () => {
+        it("should use defaults when empty object provided", () => {
+            const result = DisplayConfigSchema.parse({})
+
+            expect(result).toEqual({
+                showStats: true,
+                showToolCalls: true,
+                theme: "dark",
+                bellOnComplete: false,
+                progressBar: true,
+            })
+        })
+
+        it("should use defaults via .default({})", () => {
+            const result = DisplayConfigSchema.default({}).parse({})
+
+            expect(result).toEqual({
+                showStats: true,
+                showToolCalls: true,
+                theme: "dark",
+                bellOnComplete: false,
+                progressBar: true,
+            })
+        })
+    })
+
+    describe("showStats", () => {
+        it("should accept true", () => {
+            const result = DisplayConfigSchema.parse({ showStats: true })
+            expect(result.showStats).toBe(true)
+        })
+
+        it("should accept false", () => {
+            const result = DisplayConfigSchema.parse({ showStats: false })
+            expect(result.showStats).toBe(false)
+        })
+
+        it("should reject non-boolean", () => {
+            expect(() => DisplayConfigSchema.parse({ showStats: "yes" })).toThrow()
+        })
+    })
+
+    describe("showToolCalls", () => {
+        it("should accept true", () => {
+            const result = DisplayConfigSchema.parse({ showToolCalls: true })
+            expect(result.showToolCalls).toBe(true)
+        })
+
+        it("should accept false", () => {
+            const result = DisplayConfigSchema.parse({ showToolCalls: false })
+            expect(result.showToolCalls).toBe(false)
+        })
+
+        it("should reject non-boolean", () => {
+            expect(() => DisplayConfigSchema.parse({ showToolCalls: "yes" })).toThrow()
+        })
+    })
+
+    describe("theme", () => {
+        it("should accept dark", () => {
+            const result = DisplayConfigSchema.parse({ theme: "dark" })
+            expect(result.theme).toBe("dark")
+        })
+
+        it("should accept light", () => {
+            const result = DisplayConfigSchema.parse({ theme: "light" })
+            expect(result.theme).toBe("light")
+        })
+
+        it("should reject invalid theme", () => {
+            expect(() => DisplayConfigSchema.parse({ theme: "blue" })).toThrow()
+        })
+
+        it("should reject non-string", () => {
+            expect(() => DisplayConfigSchema.parse({ theme: 123 })).toThrow()
+        })
+    })
+
+    describe("bellOnComplete", () => {
+        it("should accept true", () => {
+            const result = DisplayConfigSchema.parse({ bellOnComplete: true })
+            expect(result.bellOnComplete).toBe(true)
+        })
+
+        it("should accept false", () => {
+            const result = DisplayConfigSchema.parse({ bellOnComplete: false })
+            expect(result.bellOnComplete).toBe(false)
+        })
+
+        it("should reject non-boolean", () => {
+            expect(() => DisplayConfigSchema.parse({ bellOnComplete: "yes" })).toThrow()
+        })
+    })
+
+    describe("progressBar", () => {
+        it("should accept true", () => {
+            const result = DisplayConfigSchema.parse({ progressBar: true })
+            expect(result.progressBar).toBe(true)
+        })
+
+        it("should accept false", () => {
+            const result = DisplayConfigSchema.parse({ progressBar: false })
+            expect(result.progressBar).toBe(false)
+        })
+
+        it("should reject non-boolean", () => {
+            expect(() => DisplayConfigSchema.parse({ progressBar: "yes" })).toThrow()
+        })
+    })
+
+    describe("partial config", () => {
+        it("should merge partial config with defaults", () => {
+            const result = DisplayConfigSchema.parse({
+                theme: "light",
+                bellOnComplete: true,
+            })
+
+            expect(result).toEqual({
+                showStats: true,
+                showToolCalls: true,
+                theme: "light",
+                bellOnComplete: true,
+                progressBar: true,
+            })
+        })
+    })
+
+    describe("full config", () => {
+        it("should accept valid full config", () => {
+            const config = {
+                showStats: false,
+                showToolCalls: false,
+                theme: "light" as const,
+                bellOnComplete: true,
+                progressBar: false,
+            }
+
+            const result = DisplayConfigSchema.parse(config)
+            expect(result).toEqual(config)
+        })
+    })
+})

packages/ipuaro/tests/unit/shared/errors/ErrorHandler.test.ts

@@ -0,0 +1,327 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+import {
+    createErrorHandler,
+    ErrorHandler,
+    getDefaultErrorOption,
+    getErrorOptions,
+    isRecoverableError,
+    toIpuaroError,
+} from "../../../../src/shared/errors/ErrorHandler.js"
+import { IpuaroError } from "../../../../src/shared/errors/IpuaroError.js"
+
+describe("ErrorHandler", () => {
+    let handler: ErrorHandler
+
+    beforeEach(() => {
+        handler = new ErrorHandler()
+    })
+
+    describe("handle", () => {
+        it("should abort non-recoverable errors", async () => {
+            const error = IpuaroError.redis("Connection failed")
+
+            const result = await handler.handle(error)
+
+            expect(result.action).toBe("abort")
+            expect(result.shouldContinue).toBe(false)
+        })
+
+        it("should use default option for recoverable errors without callback", async () => {
+            const error = IpuaroError.llm("Timeout")
+
+            const result = await handler.handle(error)
+
+            expect(result.action).toBe("retry")
+            expect(result.shouldContinue).toBe(true)
+        })
+
+        it("should call onError callback when provided", async () => {
+            const onError = vi.fn().mockResolvedValue("skip")
+            const handler = new ErrorHandler({ onError })
+            const error = IpuaroError.llm("Timeout")
+
+            const result = await handler.handle(error)
+
+            expect(onError).toHaveBeenCalledWith(error, error.options, error.defaultOption)
+            expect(result.action).toBe("skip")
+        })
+
+        it("should auto-skip parse errors when enabled", async () => {
+            const handler = new ErrorHandler({ autoSkipParseErrors: true })
+            const error = IpuaroError.parse("Syntax error")
+
+            const result = await handler.handle(error)
+
+            expect(result.action).toBe("skip")
+            expect(result.shouldContinue).toBe(true)
+        })
+
+        it("should auto-retry LLM errors when enabled", async () => {
+            const handler = new ErrorHandler({ autoRetryLLMErrors: true })
+            const error = IpuaroError.llm("Timeout")
+
+            const result = await handler.handle(error, "test-key")
+
+            expect(result.action).toBe("retry")
+            expect(result.shouldContinue).toBe(true)
+            expect(result.retryCount).toBe(1)
+        })
+
+        it("should track retry count", async () => {
+            const handler = new ErrorHandler({ autoRetryLLMErrors: true })
+            const error = IpuaroError.llm("Timeout")
+
+            await handler.handle(error, "test-key")
+            await handler.handle(error, "test-key")
+            const result = await handler.handle(error, "test-key")
+
+            expect(result.retryCount).toBe(3)
+        })
+
+        it("should abort after max retries", async () => {
+            const handler = new ErrorHandler({ autoRetryLLMErrors: true, maxRetries: 2 })
+            const error = IpuaroError.llm("Timeout")
+
+            await handler.handle(error, "test-key")
+            await handler.handle(error, "test-key")
+            const result = await handler.handle(error, "test-key")
+
+            expect(result.action).toBe("abort")
+            expect(result.shouldContinue).toBe(false)
+        })
+    })
+
+    describe("handleSync", () => {
+        it("should abort non-recoverable errors", () => {
+            const error = IpuaroError.redis("Connection failed")
+
+            const result = handler.handleSync(error)
+
+            expect(result.action).toBe("abort")
+            expect(result.shouldContinue).toBe(false)
+        })
+
+        it("should use default option for recoverable errors", () => {
+            const error = IpuaroError.file("Not found")
+
+            const result = handler.handleSync(error)
+
+            expect(result.action).toBe("skip")
+            expect(result.shouldContinue).toBe(true)
+        })
+    })
+
+    describe("resetRetries", () => {
+        it("should reset specific context", async () => {
+            const handler = new ErrorHandler({ autoRetryLLMErrors: true })
+            const error = IpuaroError.llm("Timeout")
+
+            await handler.handle(error, "key1")
+            await handler.handle(error, "key1")
+            handler.resetRetries("key1")
+
+            expect(handler.getRetryCount("key1")).toBe(0)
+        })
+
+        it("should reset all contexts when no key provided", async () => {
+            const handler = new ErrorHandler({ autoRetryLLMErrors: true })
+            const error = IpuaroError.llm("Timeout")
+
+            await handler.handle(error, "key1")
+            await handler.handle(error, "key2")
+            handler.resetRetries()
+
+            expect(handler.getRetryCount("key1")).toBe(0)
+            expect(handler.getRetryCount("key2")).toBe(0)
+        })
+    })
+
+    describe("getRetryCount", () => {
+        it("should return 0 for unknown context", () => {
+            expect(handler.getRetryCount("unknown")).toBe(0)
+        })
+    })
+
+    describe("isMaxRetriesExceeded", () => {
+        it("should return false when retries not exceeded", () => {
+            expect(handler.isMaxRetriesExceeded("test")).toBe(false)
+        })
+
+        it("should return true when retries exceeded", async () => {
+            const handler = new ErrorHandler({ autoRetryLLMErrors: true, maxRetries: 1 })
+            const error = IpuaroError.llm("Timeout")
+
+            await handler.handle(error, "test")
+
+            expect(handler.isMaxRetriesExceeded("test")).toBe(true)
+        })
+    })
+
+    describe("wrap", () => {
+        it("should return success result on success", async () => {
+            const fn = vi.fn().mockResolvedValue("result")
+
+            const result = await handler.wrap(fn, "llm")
+
+            expect(result.success).toBe(true)
+            if (result.success) {
+                expect(result.data).toBe("result")
+            }
+        })
+
+        it("should return error result on failure", async () => {
+            const fn = vi.fn().mockRejectedValue(new Error("Failed"))
+
+            const result = await handler.wrap(fn, "llm")
+
+            expect(result.success).toBe(false)
+            if (!result.success) {
+                expect(result.result.action).toBe("retry")
+            }
+        })
+
+        it("should handle IpuaroError directly", async () => {
+            const fn = vi.fn().mockRejectedValue(IpuaroError.file("Not found"))
+
+            const result = await handler.wrap(fn, "llm")
+
+            expect(result.success).toBe(false)
+            if (!result.success) {
+                expect(result.result.action).toBe("skip")
+            }
+        })
+
+        it("should reset retries on success", async () => {
+            const handler = new ErrorHandler({ autoRetryLLMErrors: true })
+            const error = IpuaroError.llm("Timeout")
+
+            await handler.handle(error, "test-key")
+            await handler.wrap(() => Promise.resolve("ok"), "llm", "test-key")
+
+            expect(handler.getRetryCount("test-key")).toBe(0)
+        })
+    })
+
+    describe("withRetry", () => {
+        it("should return result on success", async () => {
+            const fn = vi.fn().mockResolvedValue("result")
+
+            const result = await handler.withRetry(fn, "llm", "test")
+
+            expect(result).toBe("result")
+        })
+
+        it("should retry on failure", async () => {
+            const fn = vi
+                .fn()
+                .mockRejectedValueOnce(new Error("Fail 1"))
+                .mockResolvedValueOnce("success")
+            const handler = new ErrorHandler({
+                onError: vi.fn().mockResolvedValue("retry"),
+            })
+
+            const result = await handler.withRetry(fn, "llm", "test")
+
+            expect(result).toBe("success")
+            expect(fn).toHaveBeenCalledTimes(2)
+        })
+
+        it("should throw after max retries", async () => {
+            const fn = vi.fn().mockRejectedValue(new Error("Always fails"))
+            const handler = new ErrorHandler({
+                maxRetries: 2,
+                onError: vi.fn().mockResolvedValue("retry"),
+            })
+
+            await expect(handler.withRetry(fn, "llm", "test")).rejects.toThrow("Max retries")
+        })
+
+        it("should throw immediately when skip is chosen", async () => {
+            const fn = vi.fn().mockRejectedValue(new Error("Fail"))
+            const handler = new ErrorHandler({
+                onError: vi.fn().mockResolvedValue("skip"),
+            })
+
+            await expect(handler.withRetry(fn, "llm", "test")).rejects.toThrow("Fail")
+        })
+    })
+})
+
+describe("utility functions", () => {
+    describe("getErrorOptions", () => {
+        it("should return options for error type", () => {
+            const options = getErrorOptions("llm")
+
+            expect(options).toEqual(["retry", "skip", "abort"])
+        })
+    })
+
+    describe("getDefaultErrorOption", () => {
+        it("should return default option for error type", () => {
+            expect(getDefaultErrorOption("llm")).toBe("retry")
+            expect(getDefaultErrorOption("parse")).toBe("skip")
+            expect(getDefaultErrorOption("redis")).toBe("abort")
+        })
+    })
+
+    describe("isRecoverableError", () => {
+        it("should return true for recoverable errors", () => {
+            expect(isRecoverableError("llm")).toBe(true)
+            expect(isRecoverableError("parse")).toBe(true)
+            expect(isRecoverableError("file")).toBe(true)
+        })
+
+        it("should return false for non-recoverable errors", () => {
+            expect(isRecoverableError("redis")).toBe(false)
+            expect(isRecoverableError("unknown")).toBe(false)
+        })
+    })
+
+    describe("toIpuaroError", () => {
+        it("should return IpuaroError as-is", () => {
+            const error = IpuaroError.llm("Timeout")
+
+            const result = toIpuaroError(error)
+
+            expect(result).toBe(error)
+        })
+
+        it("should convert Error to IpuaroError", () => {
+            const error = new Error("Something went wrong")
+
+            const result = toIpuaroError(error, "llm")
+
+            expect(result).toBeInstanceOf(IpuaroError)
+            expect(result.type).toBe("llm")
+            expect(result.message).toBe("Something went wrong")
+        })
+
+        it("should convert string to IpuaroError", () => {
+            const result = toIpuaroError("Error message", "file")
+
+            expect(result).toBeInstanceOf(IpuaroError)
+            expect(result.type).toBe("file")
+            expect(result.message).toBe("Error message")
+        })
+
+        it("should use unknown type by default", () => {
+            const result = toIpuaroError("Error")
+
+            expect(result.type).toBe("unknown")
+        })
+    })
+
+    describe("createErrorHandler", () => {
+        it("should create handler with default options", () => {
+            const handler = createErrorHandler()
+
+            expect(handler).toBeInstanceOf(ErrorHandler)
+        })
+
+        it("should create handler with custom options", () => {
+            const handler = createErrorHandler({ maxRetries: 5 })
+
+            expect(handler).toBeInstanceOf(ErrorHandler)
+        })
+    })
+})