docs(ipuaro): improve README with detailed documentation

packages/ipuaro/README.md

@@ -1,17 +1,75 @@
-# @samiyev/ipuaro
+# @samiyev/ipuaro 🎩
 
-Local AI agent for codebase operations with "infinite" context feeling through lazy loading.
+**Local AI Agent for Codebase Operations**
 
-## Features
+"Infinite" context feeling through lazy loading - work with your entire codebase using local LLM.
 
-- 18 LLM tools for code operations (read, edit, search, analysis, git, run)
+[![npm version](https://badge.fury.io/js/@samiyev%2Fipuaro.svg)](https://www.npmjs.com/package/@samiyev/ipuaro)
-- Redis persistence with AOF for durability
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **Status:** 🚧 Early Development (v0.1.0 Foundation)
+>
+> Core infrastructure is ready. Active development in progress.
+
+## Vision
+
+Work with codebases of any size using local AI:
+- 📂 **Lazy Loading**: Load code on-demand, not all at once
+- 🧠 **Smart Context**: AST-based understanding of your code structure
+- 🔒 **100% Local**: Your code never leaves your machine
+- ⚡ **Fast**: Redis persistence + tree-sitter parsing
+
+## Planned Features
+
+### 18 LLM Tools
+
+| 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 |
+
+### Terminal UI
+
+```
+┌─ ipuaro ──────────────────────────────────────────────────┐
+│ [ctx: 12%] [project: myapp] [main] [47m] ✓ Ready          │
+├───────────────────────────────────────────────────────────┤
+│ You: How does the authentication flow work?               │
+│                                                           │
+│ Assistant: Let me analyze the auth module...              │
+│ [get_structure src/auth/]                                 │
+│ [get_function src/auth/service.ts login]                  │
+│                                                           │
+│ The authentication flow works as follows:                 │
+│ 1. User calls POST /auth/login                            │
+│ 2. AuthService.login() validates credentials...           │
+│                                                           │
+│ ⏱ 3.2s │ 1,247 tokens │ 2 tool calls                     │
+├───────────────────────────────────────────────────────────┤
+│ > _                                                       │
+└───────────────────────────────────────────────────────────┘
+```
+
+### Key Capabilities
+
+🔍 **Smart Code Understanding**
 - tree-sitter AST parsing (TypeScript, JavaScript)
-- Ollama LLM integration (local, private)
+- Symbol index for fast lookups
-- File watching for live index updates
+- Dependency graph analysis
-- Session and undo management
+
-- Security (blacklist/whitelist for shell commands)
+💾 **Persistent Sessions**
-- Terminal UI with Ink/React
+- Redis storage with AOF persistence
+- Session history across restarts
+- Undo stack for file changes
+
+🛡️ **Security**
+- Command blacklist (dangerous operations blocked)
+- Command whitelist (safe commands auto-approved)
+- Path validation (no access outside project)
 
 ## Installation
 
@@ -23,24 +81,47 @@ pnpm add @samiyev/ipuaro
 
 ## Requirements
 
-- Node.js >= 20.0.0
+- **Node.js** >= 20.0.0
-- Redis server (for persistence)
+- **Redis** (for persistence)
-- Ollama (for LLM inference)
+- **Ollama** (for local LLM inference)
 
-## Quick Start
+### Setup Ollama
 
 ```bash
-# Start in current directory
+# Install Ollama (macOS)
+brew install ollama
+
+# Start Ollama
+ollama serve
+
+# Pull recommended model
+ollama pull qwen2.5-coder:7b-instruct
+```
+
+### Setup Redis
+
+```bash
+# Install Redis (macOS)
+brew install redis
+
+# Start Redis with persistence
+redis-server --appendonly yes
+```
+
+## Usage
+
+```bash
+# Start ipuaro in current directory
 ipuaro
 
 # Start in specific directory
 ipuaro /path/to/project
 
-# With auto-apply mode
-ipuaro --auto-apply
-
 # With custom model
 ipuaro --model qwen2.5-coder:32b-instruct
+
+# With auto-apply mode (skip edit confirmations)
+ipuaro --auto-apply
 ```
 
 ## Commands
@@ -48,7 +129,7 @@ ipuaro --model qwen2.5-coder:32b-instruct
 | Command | Description |
 |---------|-------------|
 | `ipuaro [path]` | Start TUI in directory |
-| `ipuaro init` | Create .ipuaro.json config |
+| `ipuaro init` | Create `.ipuaro.json` config |
 | `ipuaro index` | Index project without TUI |
 
 ## Configuration
@@ -65,6 +146,9 @@ Create `.ipuaro.json` in your project root:
         "model": "qwen2.5-coder:7b-instruct",
         "temperature": 0.1
     },
+    "project": {
+        "ignorePatterns": ["node_modules", "dist", ".git"]
+    },
     "edit": {
         "autoApply": false
     }
@@ -76,55 +160,125 @@ Create `.ipuaro.json` in your project root:
 Clean Architecture with clear separation:
 
 ```
-src/
+@samiyev/ipuaro/
-├── domain/          # Business logic (entities, value objects, interfaces)
+├── domain/              # Business logic (no dependencies)
-├── application/     # Use cases, DTOs, orchestration
+│   ├── entities/        # Session, Project
-├── infrastructure/  # External implementations (Redis, Ollama, tools)
+│   ├── value-objects/   # FileData, FileAST, ChatMessage, etc.
-├── tui/             # Terminal UI (Ink/React components)
+│   └── services/        # IStorage, ILLMClient, ITool, IIndexer
-├── cli/             # CLI commands
+├── application/         # Use cases & orchestration
-└── shared/          # Cross-cutting concerns
+│   ├── use-cases/       # StartSession, HandleMessage, etc.
+│   └── interfaces/      # IToolRegistry
+├── infrastructure/      # External implementations
+│   ├── storage/         # Redis client & storage
+│   ├── llm/             # Ollama client & prompts
+│   ├── indexer/         # File scanner, AST parser
+│   └── tools/           # 18 tool implementations
+├── tui/                 # Terminal UI (Ink/React)
+│   └── components/      # StatusBar, Chat, Input, etc.
+├── cli/                 # CLI entry point
+└── shared/              # Config, errors, utils
 ```
 
-## Tools (18 total)
-
-| Category | Tool | Description |
-|----------|------|-------------|
-| **Read** | `get_lines` | Get file lines |
-| | `get_function` | Get function by name |
-| | `get_class` | Get class by name |
-| | `get_structure` | Get project tree |
-| **Edit** | `edit_lines` | Replace lines |
-| | `create_file` | Create new file |
-| | `delete_file` | Delete file |
-| **Search** | `find_references` | Find symbol usages |
-| | `find_definition` | Find symbol definition |
-| **Analysis** | `get_dependencies` | File imports |
-| | `get_dependents` | Files importing this |
-| | `get_complexity` | Complexity metrics |
-| | `get_todos` | Find TODO/FIXME |
-| **Git** | `git_status` | Repository status |
-| | `git_diff` | Uncommitted changes |
-| | `git_commit` | Create commit |
-| **Run** | `run_command` | Execute shell command |
-| | `run_tests` | Run test suite |
-
 ## Development Status
 
-Currently at version **0.1.0** (Foundation). See [ROADMAP.md](./ROADMAP.md) for full development plan.
+### ✅ Completed (v0.1.0)
 
-### Completed
+- [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] 0.1.1 Project Setup
+### 🔜 Next Up
-- [x] 0.1.2 Domain Value Objects
-- [x] 0.1.3 Domain Services Interfaces
-- [x] 0.1.4 Shared Config
 
-### Next
+- [ ] **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
 
-- [ ] 0.2.0 Redis Storage
+See [ROADMAP.md](./ROADMAP.md) for detailed development plan.
-- [ ] 0.3.0 Indexer
+
-- [ ] 0.4.0 LLM Integration
+## API (Coming Soon)
+
+```typescript
+import { startSession, handleMessage } from "@samiyev/ipuaro"
+
+// Start a session
+const session = await startSession({
+    projectPath: "./my-project",
+    model: "qwen2.5-coder:7b-instruct"
+})
+
+// Send a message
+const response = await handleMessage(session, "Explain the auth flow")
+
+console.log(response.content)
+console.log(`Tokens: ${response.stats.tokens}`)
+console.log(`Tool calls: ${response.stats.toolCalls}`)
+```
+
+## How It Works
+
+### Lazy Loading Context
+
+Instead of loading entire codebase into context:
+
+```
+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
+```
+
+### Tool-Based Code Access
+
+```
+User: "How does user creation work?"
+
+ipuaro:
+1. [get_structure src/] → sees user/ folder
+2. [get_function src/user/service.ts createUser] → gets function code
+3. [find_references createUser] → finds all usages
+4. Synthesizes answer with specific code context
+```
+
+## Contributing
+
+Contributions welcome! This project is in early development.
+
+```bash
+# Clone
+git clone https://github.com/samiyev/puaros.git
+cd puaros/packages/ipuaro
+
+# Install
+pnpm install
+
+# Build
+pnpm build
+
+# Test
+pnpm test:run
+
+# Coverage
+pnpm test:coverage
+```
 
 ## License
 
-MIT
+MIT © Fozilbek Samiyev
+
+## Links
+
+- [GitHub Repository](https://github.com/samiyev/puaros/tree/main/packages/ipuaro)
+- [Issues](https://github.com/samiyev/puaros/issues)
+- [Changelog](./CHANGELOG.md)
+- [Roadmap](./ROADMAP.md)