erosolar-cli 1.6.13 → 1.6.14

package/README.md

@@ -2,8 +2,6 @@
 
 ## AI Coding Agent Comparison
 
-A comparison of AI coding agents for building complete projects from scratch:
-
 | Agent | Screenshot |
 |-------|------------|
 | **Claude Code** | ![Claude](https://erosolar-public-assets.s3.amazonaws.com/images/Claude.png) |
@@ -28,964 +26,262 @@ A comparison of AI coding agents for building complete projects from scratch:
 
 ![Gemini](https://erosolar-public-assets.s3.amazonaws.com/images/Gemini.png)
 
-A unified AI agent framework for the command line. Multi-provider support with schema-driven tools, code intelligence, competitive RL, and transparent reasoning.
+---
+
+## What is Erosolar CLI?
+
+**Erosolar CLI** is a unified AI coding agent for the command line that works with **any major AI provider**. It's designed to be model-agnostic—you bring your own API keys, and erosolar-cli handles the rest: tool orchestration, file editing, code search, bash execution, and autonomous task completion.
+
+Think of it as a **universal interface** for AI-powered coding that doesn't lock you into a single provider.
 
 [![npm version](https://img.shields.io/npm/v/erosolar-cli.svg)](https://www.npmjs.com/package/erosolar-cli)
-[![PyPI version](https://img.shields.io/pypi/v/erosolar.svg)](https://pypi.org/project/erosolar/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/node/v/erosolar-cli.svg)](https://nodejs.org)
 
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         EROSOLAR CLI                                │
-├─────────────────────────────────────────────────────────────────────┤
-│  CORE (Always Available)          │  PLUGINS (Optional)             │
-│  ─────────────────────────        │  ────────────────────           │
-│  • Filesystem (read/write/list)   │  • alpha_zero (RL framework)    │
-│  • Edit (surgical replacement)    │  • coding (analysis tools)      │
-│  • Bash (safe shell execution)    │  • security (vuln scanning)     │
-│  • Glob (pattern matching)        │                                 │
-│  • Grep (regex search)            │                                 │
-└─────────────────────────────────────────────────────────────────────┘
-```
+---
 
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Supported Providers](#supported-providers)
-- [Core Concepts](#core-concepts)
-- [Plugin System](#plugin-system)
-- [Alpha Zero 2](#alpha-zero-2)
-- [Usage Guide](#usage-guide)
-- [Commands Reference](#commands-reference)
-- [Tool Capabilities](#tool-capabilities)
-- [Programmatic Usage](#programmatic-usage)
-- [Schema Architecture](#schema-architecture)
-- [Configuration](#configuration)
-- [Development](#development)
+## Key Features
+
+- **Multi-Provider Support** - Switch between OpenAI, Anthropic, Google, xAI, DeepSeek, or run locally with Ollama
+- **25+ Built-in Models** - From GPT-5 to Claude Opus to Gemini Pro to local Llama models
+- **Full Filesystem Access** - Read, write, edit files with surgical precision
+- **Safe Bash Execution** - Run shell commands with guardrails
+- **Code Intelligence** - Glob patterns, regex search, AST-aware editing
+- **Continuous Execution** - Runs autonomously until tasks are complete
+- **Schema-Driven Architecture** - Extensible via JSON schemas and plugins
 
 ---
 
 ## Installation
 
-### TypeScript/Node.js (npm)
-
 ```bash
 npm install -g erosolar-cli
 ```
 
-**Commands:** `erosolar-ts`, `erosolar-cli`, `erosolar`
-
-**Requirements:** Node.js 20+
-
-### Python (PyPI)
-
+Then run:
 ```bash
-pip install erosolar
-```
-
-**Commands:** `erosolar-py`, `erosolar`, `bo-cli`, `bo`
-
-**Requirements:** Python 3.10+
-
-**Verify installation:**
-
-```bash
-erosolar --version
-```
-
----
-
-## Quick Start
-
-```bash
-# Start interactive session
-erosolar-cli
-
-# Or use the short alias
 erosolar
 ```
 
-On first run, you'll see available providers based on your configured API keys:
-
-```
-✓ Providers: anthropic (claude-sonnet-4-5) | openai (gpt-4o) | deepseek (deepseek-reasoner)
-ℹ Add: google: set GOOGLE_API_KEY, xai: set XAI_API_KEY
-```
-
-### Basic Workflow
-
-1. **Ask a question or give a task** in natural language
-2. **Watch the agent work** - see tool calls, reasoning, and results in real-time
-3. **Iterate** - refine your request based on results
-
-```
-> find all TODO comments in the codebase
-
-⏺ I'll search for TODO comments across the codebase.
-
-⏺ Grep(pattern: "TODO", output_mode: "content")
-⎿ Found 23 matches in 8 files
-
-Here are the TODO comments I found:
-- src/api/handler.ts:45 - TODO: Add rate limiting
-- src/utils/cache.ts:12 - TODO: Implement TTL expiration
-...
-```
+**Requirements:** Node.js 20+
 
 ---
 
-## Supported Providers
-
-| Provider | Models | Environment Variable |
-|----------|--------|---------------------|
-| **Anthropic** | Claude Opus, Sonnet, Haiku | `ANTHROPIC_API_KEY` |
-| **OpenAI** | GPT-4o, GPT-4, o1, o1-mini | `OPENAI_API_KEY` |
-| **Google** | Gemini 2.0 Flash, 1.5 Pro | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
-| **DeepSeek** | deepseek-reasoner, deepseek-chat | `DEEPSEEK_API_KEY` |
-| **xAI** | Grok-2, Grok-beta | `XAI_API_KEY` |
-| **Ollama** | Llama, Qwen, Mistral (local) | `OLLAMA_BASE_URL` (optional) |
-| **Mistral** | Mistral Large, Codestral | `MISTRAL_API_KEY` |
-| **Groq** | Llama 3.1, Mixtral (fast) | `GROQ_API_KEY` |
-| **Together** | Various open models | `TOGETHER_API_KEY` |
-| **Fireworks** | Various open models | `FIREWORKS_API_KEY` |
+## Supported Providers & Models
 
-### Setting Up API Keys
+### OpenAI
+| Model | Description |
+|-------|-------------|
+| `gpt-5.1-codex` | Optimized for coding with the latest OpenAI weights |
+| `gpt-5.1` | Balanced reasoning for code and analysis |
+| `gpt-5-pro` | Flagship model for maximum depth and planning |
+| `gpt-5-mini` | Faster turnarounds while staying code-aware |
+| `gpt-5-nano` | Ultra-responsive for quick edits and summaries |
 
 ```bash
-# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
-export ANTHROPIC_API_KEY="sk-ant-..."
-export OPENAI_API_KEY="sk-..."
-export DEEPSEEK_API_KEY="sk-..."
+export OPENAI_API_KEY=your_key
+erosolar
 ```
 
-### Switching Providers
+### Anthropic (Claude)
+| Model | Description |
+|-------|-------------|
+| `claude-sonnet-4-5-20250929` | Sonnet 4.5 for deep planning across large repos |
+| `claude-opus-4.1` | Opus 4.1 for richest reasoning |
+| `claude-haiku-4.5` | Haiku 4.5 for latency-sensitive workflows |
 
 ```bash
-# In the CLI
-/provider anthropic     # Switch to Anthropic
-/provider deepseek      # Switch to DeepSeek
-/providers              # List all configured providers
-```
-
----
-
-## Core Concepts
-
-### Transparent Reasoning
-
-Every action is visible. The agent narrates its thought process and shows tool execution in real-time:
-
+export ANTHROPIC_API_KEY=your_key
+erosolar
 ```
-⏺ I'll analyze the authentication module for security issues.
-
-⏺ Read(src/auth/login.ts)
-⎿ Read 156 lines
 
-⏺ Grep(pattern: "password.*=", type: "ts")
-⎿ Found 3 matches
+### Google (Gemini)
+| Model | Description |
+|-------|-------------|
+| `gemini-2.5-pro` | Multimodal deep reasoning with longer outputs |
+| `gemini-2.5-flash` | Lower-latency for iterative coding |
+| `gemini-3.0-pro-preview` | Next-gen multimodal reasoning (preview) |
 
-Based on my analysis, I found a potential issue at line 42...
+```bash
+export GEMINI_API_KEY=your_key
+erosolar
 ```
 
-### Schema-Driven Tools
-
-All tools are defined in JSON schemas, making them:
-- **Provider-agnostic**: Same tools work across all LLM providers
-- **Self-documenting**: Schemas describe parameters and types
-- **Extensible**: Add custom tools via plugins or MCP servers
-
-### Context Management
-
-The CLI tracks token usage and manages context efficiently:
+### xAI (Grok)
+| Model | Description |
+|-------|-------------|
+| `grok-4` | Highest quality coding and reasoning |
+| `grok-4.1-fast-reasoning` | Fast reasoning with enhanced thinking |
+| `grok-4-fast-reasoning` | Lower latency with thinking enabled |
+| `grok-4-fast-non-reasoning` | Concise edits and summaries |
+| `grok-code-fast-1` | Tuned specifically for rapid coding |
 
+```bash
+export XAI_API_KEY=your_key
+erosolar
 ```
-• Context 45% used (52.3k tokens) • Ready for prompts
-```
-
-- **Green** (<70%): Plenty of room
-- **Yellow** (70-90%): Getting full
-- **Red** (>90%): Approaching limit, consider `/clear`
 
-### Session Persistence
-
-Sessions auto-save and restore. Use `/sessions` to manage:
+### DeepSeek
+| Model | Description |
+|-------|-------------|
+| `deepseek-reasoner` | Chain-of-thought exploration with tool depth |
+| `deepseek-chat` | Faster interactive editing and summarization |
 
 ```bash
-/sessions list          # Show saved sessions
-/sessions load <name>   # Load a session
-/sessions save <name>   # Save current session
+export DEEPSEEK_API_KEY=your_key
+erosolar
 ```
 
-### Automatic Context Management
-
-Erosolar automatically manages conversation context to prevent hitting token limits:
-
-- **Model-aware limits**: Each model has appropriate context thresholds (GPT-4o: 128K, Claude 3: 200K, etc.)
-- **Automatic summarization**: When context reaches 70% capacity, LLM-based summarization preserves key information
-- **Progressive warnings**: Visual indicators at 60% (info), 70% (pruning), 85% (critical)
-
-Preserved information includes file paths, function names, error solutions, user decisions, and work completed.
-
----
-
-## Plugin System
-
-Plugins are **opt-in** extensions that add specialized capabilities beyond the core tools.
-
-### Enabling Plugins
+### Ollama (Local/Air-Gapped)
+| Model | Description |
+|-------|-------------|
+| `llama3.1:8b` | Meta Llama 3.1 8B - Strong general purpose (128K context) |
+| `llama3.2:3b` | Meta Llama 3.2 3B - Efficient for quick responses |
+| `qwen2.5:7b` | Alibaba Qwen 2.5 7B - Excellent multilingual support |
+| `qwen2.5:14b` | Alibaba Qwen 2.5 14B - Enhanced reasoning |
+| `mistral:7b` | Mistral 7B - Fast and efficient |
+| `deepseek-coder:6.7b` | DeepSeek Coder - Specialized for programming |
+| `codellama:7b` | Meta Code Llama - Optimized for code |
 
 ```bash
-# TypeScript
-erosolar --alpha-zero       # Enable Alpha Zero 2
-erosolar --coding           # Enable enhanced coding tools
-erosolar --all-plugins      # Enable all plugins
-
-# Python
-erosolar-py --alpha-zero
-erosolar-py --interactive --coding
+# Start Ollama first
+ollama serve
+erosolar --provider ollama
 ```
 
-### Available Plugins
-
-| Plugin | Flag | Description |
-|--------|------|-------------|
-| **Alpha Zero 2** | `--alpha-zero` | Competitive RL framework with code metrics |
-| **Coding Tools** | `--coding` | Enhanced code analysis and refactoring |
-| **Security** | `--security` | Vulnerability scanning and security research |
-
-### Coding Tools Plugin
-
-Enhanced code analysis and development assistance:
-
-| Tool | Description |
-|------|-------------|
-| `analyze_complexity` | Cyclomatic complexity, maintainability index |
-| `find_dependencies` | Import analysis (stdlib/third-party/local) |
-| `generate_docstring` | Auto-generate docstrings (Google/NumPy style) |
-| `suggest_refactorings` | Identify refactoring opportunities |
-| `generate_test_stub` | Create pytest/jest test templates |
-
-### Security Tools Plugin
-
-Security research and vulnerability assessment:
-
-| Tool | Description |
-|------|-------------|
-| `dependency_audit` | Check dependencies for known vulnerabilities |
-| `code_security_scan` | Pattern-based security issue detection |
-| `analyze_attack_surface` | Project security posture analysis |
-
-**Detected Issues:** Hardcoded secrets, code injection risks, insecure deserialization, SQL injection, XSS risks
-
 ---
 
-## Alpha Zero 2
-
-**Principal Investigator:** Bo Shang
-
-A competitive multi-agent reinforcement learning framework for code optimization that demonstrates practical recursive self-improvement in autonomous coding agents.
-
-### Key Innovations
-
-1. **Competitive Learning** - Agents improve faster when competing against each other
-2. **Code Quality Metrics** - AST-based evaluation across 10+ dimensions
-3. **Safe Self-Modification** - Version control with automatic rollback
-4. **Meta-Learning** - Learning to improve the improvement process itself
-
-### Code Quality Dimensions
-
-| Metric | Weight | Description |
-|--------|--------|-------------|
-| Code Quality | 25% | Structure, naming, organization |
-| Algorithm Efficiency | 20% | Data structures, complexity |
-| Error Handling | 20% | Try/catch, validation, edge cases |
-| Documentation | 15% | Docstrings, comments |
-| Maintainability | 10% | Function length, coupling |
-| Security | 10% | Injection risks, secrets handling |
-
-### CLI Commands
+## Quick Start
 
 ```bash
-# Run a tournament
-erosolar alpha-zero tournament --rounds 10
+# Set your API key
+export OPENAI_API_KEY=your_key
 
-# Evaluate code quality
-erosolar alpha-zero evaluate myfile.py
+# Start erosolar
+erosolar
 
-# View competition history
-erosolar alpha-zero history
+# Or specify a provider/model directly
+erosolar --provider anthropic --model claude-sonnet-4-5-20250929
 ```
 
-### Shell Commands
+Once running, just describe what you want:
 
 ```
-/metrics      Show performance metrics
-/suggestions  Show improvement suggestions
-```
+> Create a REST API with Express that has user authentication
 
-### Citation
+> Find all files that import 'lodash' and refactor to use native methods
 
-```bibtex
-@software{alpha_zero_2,
-  title={Alpha Zero 2: Recursive Self-Improvement in Competitive Multi-Agent Systems},
-  author={Bo Shang},
-  year={2024},
-  framework={erosolar-cli}
-}
+> Run the tests, fix any failures, and commit the changes
 ```
 
 ---
 
-## Usage Guide
-
-### Natural Language Tasks
-
-Just describe what you want:
+## Core Tools
 
-```
-> refactor the UserService class to use dependency injection
-> write tests for the authentication module
-> find and fix the memory leak in the event handler
-> explain how the caching system works
-```
-
-### File Operations
-
-```
-> read src/config.ts
-> create a new utility file for date formatting
-> rename all instances of 'userId' to 'accountId' in the api folder
-```
-
-### Code Analysis
-
-```
-> analyze the complexity of this codebase
-> find all functions with more than 50 lines
-> show the dependency graph for the auth module
-```
-
-### Git Operations
-
-```
-> show recent commits
-> create a commit with a descriptive message
-> what changed in the last PR?
-```
-
-### Multi-Step Tasks
-
-For complex tasks, the agent uses a todo list to track progress:
-
-```
-> implement user authentication with JWT, tests, and documentation
-
-⏺ Creating task list...
-
-[1. [in_progress] Design JWT authentication flow
-2. [pending] Implement login endpoint
-3. [pending] Implement token refresh
-4. [pending] Add middleware for protected routes
-5. [pending] Write unit tests
-6. [pending] Add API documentation]
-```
+| Tool | Description |
+|------|-------------|
+| **Read** | Read file contents with line numbers |
+| **Write** | Create new files |
+| **Edit** | Surgical string replacement in files |
+| **Glob** | Find files by pattern (`**/*.ts`, `src/**/*.js`) |
+| **Grep** | Regex search across codebase |
+| **Bash** | Execute shell commands safely |
+| **TodoWrite** | Track multi-step task progress |
+| **AskUser** | Request clarification when needed |
 
 ---
 
-## Commands Reference
-
-### Provider & Model Commands
+## Slash Commands
 
 | Command | Description |
 |---------|-------------|
-| `/provider <name>` | Switch to a provider (openai, anthropic, etc.) |
-| `/providers` | List all configured providers |
-| `/model` | Interactive model selection menu |
-| `/discover` | Auto-discover models from provider APIs |
-
-### Session Commands
-
-| Command | Description |
-|---------|-------------|
-| `/sessions list` | Show saved sessions |
-| `/sessions save <name>` | Save current session |
-| `/sessions load <name>` | Load a saved session |
-| `/clear` | Clear conversation history |
-
-### Tool Commands
-
-| Command | Description |
-|---------|-------------|
-| `/tools` | Manage enabled tool suites |
-| `/doctor` | Diagnose environment and credentials |
-| `/checks` | Run repo validation (test/build/lint) |
-
-### Display Commands
-
-| Command | Description |
-|---------|-------------|
-| `/shortcuts` or `/keys` | Show keyboard shortcuts |
-| `/thinking [mode]` | Set thinking display (concise/balanced/extended) |
-| `/changes` | Show file modifications this session |
-| `/metrics` | Show performance metrics |
-
-### Other Commands
-
-| Command | Description |
-|---------|-------------|
-| `/context` | Refresh workspace context |
-| `/agents` | Switch agent profiles |
-| `/skills` | Load skill bundles |
-| `/local` | Manage local LLM providers |
-
-### Keyboard Shortcuts
-
-| Shortcut | Action |
-|----------|--------|
-| `Ctrl+C` | Cancel current operation |
-| `Ctrl+D` | Exit (when input empty) |
-| `Ctrl+G` | Compose multi-line message |
-| `Ctrl+O` | Expand collapsed output |
-| `Up/Down` | Navigate command history |
+| `/model` | Switch models mid-session |
+| `/provider` | Switch AI providers |
+| `/thinking` | Toggle extended thinking mode |
+| `/tools` | Enable/disable specific tools |
+| `/secrets` | Configure API keys |
+| `/context` | Refresh workspace snapshot |
+| `/sessions` | Manage conversation history |
+| `/doctor` | Check environment readiness |
 
 ---
 
-## Tool Capabilities
-
-### Core Tools
-
-| Tool Suite | Tools | Description |
-|------------|-------|-------------|
-| **Filesystem** | `read_file`, `write_file`, `list_files` | File I/O operations |
-| **Edit** | `edit_file` | Surgical string replacement |
-| **Search** | `grep_search`, `find_definition` | Code and text search |
-| **Glob** | `glob_files` | Pattern-based file matching |
-| **Bash** | `execute_command` | Sandboxed shell execution |
-
-### Analysis Tools
-
-| Tool Suite | Tools | Description |
-|------------|-------|-------------|
-| **Code Analysis** | `analyze_structure`, `dependency_graph` | AST and dependency analysis |
-| **Code Quality** | `lint_check`, `complexity_metrics` | Quality inspection |
-| **Refactoring** | `find_hotspots`, `impact_analysis` | Refactoring assistance |
-| **Testing** | `run_tests`, `coverage_report` | Test execution |
-
-### Integration Tools
-
-| Tool Suite | Tools | Description |
-|------------|-------|-------------|
-| **Web** | `fetch_url`, `web_search` | HTTP and search |
-| **Git** | `git_status`, `git_diff`, `git_commit` | Version control |
-| **MCP** | Dynamic | Model Context Protocol servers |
-| **Agent Spawning** | `spawn_agent` | Sub-agent delegation |
-
-### Task Management
-
-| Tool Suite | Tools | Description |
-|------------|-------|-------------|
-| **Todo** | `todo_write`, `todo_read` | Task tracking |
-| **Planning** | `create_plan`, `update_plan` | Multi-step planning |
-| **Interaction** | `ask_user` | User clarification |
-
----
-
-## Programmatic Usage
-
-### TypeScript/Node.js
-
-```typescript
-import { AgentRuntime } from 'erosolar-cli/core/agent';
-import { createDefaultToolRuntime, ToolExecutionContext } from 'erosolar-cli/core/toolRuntime';
-import { createProvider } from 'erosolar-cli/providers/providerFactory';
-
-async function main() {
-  // Create provider
-  const provider = createProvider({
-    provider: 'anthropic',
-    model: 'claude-sonnet-4-5-20250929',
-  });
-
-  // Create tool runtime
-  const context: ToolExecutionContext = {
-    profileName: 'default',
-    provider: 'anthropic',
-    model: 'claude-sonnet-4-5-20250929',
-    workspaceContext: '/path/to/workspace',
-  };
-  const toolRuntime = createDefaultToolRuntime(context, []);
-
-  // Create agent
-  const agent = new AgentRuntime({
-    provider,
-    toolRuntime,
-    systemPrompt: 'You are a helpful coding assistant.',
-  });
-
-  // Send message
-  const response = await agent.send('List all TypeScript files');
-  console.log(response);
-}
-```
-
-### Python
-
-```python
-import asyncio
-from erosolar_cli.core.agent import AgentRuntime, AgentOptions
-from erosolar_cli.core.tool_runtime import create_default_tool_runtime, ToolExecutionContext
-from erosolar_cli.providers.provider_factory import create_provider
-
-async def main():
-    # Create provider
-    provider = create_provider(provider="anthropic", model="claude-sonnet-4")
-
-    # Create tool runtime with core tools
-    context = ToolExecutionContext(
-        profile_name="default",
-        provider="anthropic",
-        model="claude-sonnet-4",
-    )
-    tool_runtime = create_default_tool_runtime(context)
-
-    # Create agent
-    agent = AgentRuntime(AgentOptions(
-        provider=provider,
-        tool_runtime=tool_runtime,
-        system_prompt="You are a helpful coding assistant.",
-    ))
-
-    # Send message
-    response = await agent.send("List all Python files")
-    print(response)
-
-asyncio.run(main())
-```
-
-### Alpha Zero 2 Direct Usage
-
-```python
-from erosolar_cli.alpha_zero import (
-    CompetitiveFramework,
-    RewardSystem,
-    TournamentRunner,
-    TournamentConfig,
-)
-from pathlib import Path
-
-# Evaluate code quality
-reward_system = RewardSystem()
-metrics = await reward_system.evaluate_code('''
-def fibonacci(n):
-    if n <= 1:
-        return n
-    return fibonacci(n-1) + fibonacci(n-2)
-''')
-
-print(f"Quality Score: {metrics.code_quality_score * 100:.1f}/100")
-print(f"Efficiency: {metrics.algorithm_efficiency * 100:.1f}/100")
-
-# Run tournament
-config = TournamentConfig(
-    tournament_id="test-tournament",
-    task_prompts=[
-        "Write an efficient prime number checker",
-        "Implement merge sort with O(n log n) complexity",
-    ],
-    rounds_per_task=3,
-)
-
-runner = TournamentRunner(data_dir=Path("./tournaments"))
-result = await runner.run(config)
-
-print(f"Winner: Agent {1 if result.agent1_wins > result.agent2_wins else 2}")
-```
-
-### Creating Custom Plugins
-
-```python
-from erosolar_cli.plugins import Plugin, PluginMetadata, PluginCategory, register_plugin
-from erosolar_cli.core.tool_runtime import ToolDefinition, ToolSuite
-
-@register_plugin
-class MyPlugin(Plugin):
-    metadata = PluginMetadata(
-        id="my_plugin",
-        name="My Plugin",
-        version="1.0.0",
-        description="Description of what this plugin does",
-        category=PluginCategory.CODING,
-        author="Your Name",
-    )
-
-    def get_tool_suites(self) -> list[ToolSuite]:
-        async def my_tool_handler(param: str) -> dict:
-            return {"result": f"Processed: {param}"}
-
-        return [ToolSuite(
-            id="plugin.my_plugin",
-            name="My Plugin",
-            description="My plugin tools",
-            tools=[
-                ToolDefinition(
-                    name="my_tool",
-                    description="Does something useful",
-                    parameters={
-                        "type": "object",
-                        "properties": {
-                            "param": {"type": "string", "description": "Input"}
-                        },
-                        "required": ["param"]
-                    },
-                    handler=my_tool_handler,
-                )
-            ]
-        )]
-```
-
----
-
-## Schema Architecture
-
-Erosolar CLI uses a **unified schema architecture** for configuration, providers, tools, and agent behavior. All schemas are JSON-based and version-controlled.
-
-### Schema Hierarchy
-
-```
-contracts/
-├── unified-schema.json      # Master schema - single source of truth
-├── agent-schemas.json       # Agent and model configurations
-├── tools.schema.json        # Tool capability definitions
-├── agent-profiles.schema.json
-└── schemas/
-    ├── agent.schema.json
-    ├── agent-profile.schema.json
-    ├── agent-rules.schema.json
-    ├── agent-schemas.schema.json
-    └── tool-selection.schema.json
-```
-
-### Unified Schema (unified-schema.json)
-
-The master schema defines all providers, models, and capabilities:
-
-```json
-{
-  "contractVersion": "2.0.0",
-  "providers": [
-    {
-      "id": "anthropic",
-      "label": "Anthropic",
-      "baseUrl": "https://api.anthropic.com",
-      "envVars": { "apiKey": "ANTHROPIC_API_KEY" },
-      "capabilities": ["chat", "reasoning", "tools", "streaming", "vision"],
-      "models": ["claude-opus-4-5-20251101", "claude-sonnet-4-5-20250929"],
-      "defaultModel": "claude-sonnet-4-5-20250929"
-    }
-  ]
-}
-```
-
-### Provider Schema
+## How It Works
 
-Each provider defines:
+1. **You describe a task** in natural language
+2. **Erosolar analyzes** the request and plans an approach
+3. **Tools execute autonomously** - reading files, searching code, making edits
+4. **Validation runs** - tests, builds, linting
+5. **Results reported** with what changed and what to verify
 
-| Field | Description |
-|-------|-------------|
-| `id` | Unique identifier (e.g., "anthropic") |
-| `baseUrl` | API endpoint |
-| `envVars` | Required environment variables |
-| `capabilities` | Supported features (chat, tools, streaming, vision) |
-| `models` | Available model IDs |
-| `openaiCompatible` | If true, uses OpenAI-compatible API |
-
-### Tool Schema (tools.schema.json)
-
-Tools are organized into capability suites:
-
-```json
-{
-  "options": [
-    {
-      "id": "filesystem",
-      "label": "File operations",
-      "defaultEnabled": true,
-      "category": "core",
-      "scopes": ["filesystem:read", "filesystem:write"],
-      "pluginIds": ["tool.filesystem.local"]
-    }
-  ]
-}
-```
-
-### Agent Rules (agents/*.rules.json)
-
-Agent behavior is controlled by rules:
-
-```json
-{
-  "profile": "erosolar-code",
-  "globalPrinciples": [
-    {
-      "id": "guardrail.snapshot_lock",
-      "summary": "Require workspace snapshot before editing",
-      "severity": "critical"
-    },
-    {
-      "id": "guardrail.tool_transparency",
-      "summary": "Narrate intent before running tools",
-      "severity": "required"
-    }
-  ]
-}
-```
-
-### Type System (src/core/types.ts)
-
-TypeScript types mirror the JSON schemas:
-
-```typescript
-export interface LLMProvider {
-  readonly id: ProviderId;
-  readonly model: string;
-  generate(messages: ConversationMessage[], tools: ProviderToolDefinition[]): Promise<ProviderResponse>;
-  generateStream?(messages: ConversationMessage[], tools: ProviderToolDefinition[]): AsyncIterableIterator<StreamChunk>;
-}
-
-export interface ProviderToolDefinition {
-  name: string;
-  description: string;
-  parameters?: JSONSchemaObject;
-}
-```
-
-### Model Discovery
-
-Models can be statically defined or auto-discovered:
-
-```typescript
-// Discover models from provider APIs
-const result = await discoverAllModels();
-// Returns models from OpenAI, Anthropic, Google, etc.
-
-// Get best model for a provider
-const best = getBestModel('anthropic', models);
-// Returns highest-priority model based on rankings
-```
+The AI operates within guardrails defined in `agents/*.rules.json`, ensuring safe, auditable behavior.
 
 ---
 
 ## Configuration
 
-### Agent Profiles
-
-Profiles define provider, model, and behavior. Located in `agents/`:
-
-```json
-{
-  "profile": "erosolar-code",
-  "label": "Erosolar Code",
-  "defaultProvider": "openai",
-  "defaultModel": "gpt-4o",
-  "systemPrompt": "You are an expert coding assistant..."
-}
-```
-
-### MCP Servers
-
-Add Model Context Protocol servers via `.mcp.json` or `.erosolar/mcp.json`:
-
-```json
-{
-  "filesystem": {
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-filesystem", "${WORKSPACE_ROOT}"]
-  },
-  "github": {
-    "command": "npx",
-    "args": ["-y", "@modelcontextprotocol/server-github"],
-    "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
-  }
-}
-```
-
-### Skills
-
-Load reusable knowledge bundles from `SKILL.md` files:
-
-```markdown
-<!-- SKILL.md -->
-# React Component Development
-
-## Principles
-- Use functional components with hooks
-- Implement proper error boundaries
-- Follow accessibility guidelines
-
-## Patterns
-```typescript
-const Component: FC<Props> = ({ data }) => {
-  const [state, setState] = useState(initial);
-  // ...
-};
-```
-```
-
-Load with `/skill <name>` or reference in prompts.
-
-### Tool Settings
-
-Configure which tools are enabled via `/tools` command or `~/.erosolar/tools.json`:
-
-```json
-{
-  "enabled": ["filesystem", "search", "bash", "edit"],
-  "disabled": ["web"]
-}
-```
-
----
-
-## Development
-
-### Setup
+### Environment Variables
 
 ```bash
-git clone https://github.com/ErosolarAI/erosolar-by-bo.git
-cd erosolar-by-bo
-npm install
-npm run build
-```
+# Choose your provider
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GEMINI_API_KEY=...
+export XAI_API_KEY=...
+export DEEPSEEK_API_KEY=...
 
-### Development Mode
-
-```bash
-npm run dev          # Run with ts-node
-npm run build        # Compile TypeScript
-npm run type-check   # Check types only
+# For local models
+export OLLAMA_BASE_URL=http://localhost:11434
 ```
 
-### Testing
+### Runtime Options
 
 ```bash
-npm test             # Run test suite
-npm run lint         # Run ESLint
-npm run health-check # Validate core components
-npm run quality-gate # All quality checks
-```
-
-### Project Structure
-
-```
-src/
-├── bin/              # CLI entry point
-├── core/             # Core types, agent, context management
-│   ├── agent.ts
-│   ├── types.ts
-│   ├── modelDiscovery.ts
-│   └── unified/      # Unified schema runtime
-├── providers/        # LLM provider implementations
-│   ├── anthropicProvider.ts
-│   ├── openaiResponsesProvider.ts
-│   └── googleProvider.ts
-├── capabilities/     # Tool implementations
-│   ├── filesystemCapability.ts
-│   ├── searchCapability.ts
-│   └── bashCapability.ts
-├── shell/            # Interactive shell
-│   ├── shellApp.ts
-│   └── interactiveShell.ts
-├── ui/               # Display and theming
-├── plugins/          # Plugin system
-├── contracts/        # JSON schemas
-└── mcp/              # MCP client
-```
+erosolar --help
 
-### Adding a Provider
-
-1. Create provider in `src/providers/`:
-
-```typescript
-export class CustomProvider implements LLMProvider {
-  readonly id = 'custom';
-  readonly model: string;
-
-  async generate(messages, tools) {
-    // Implementation
-  }
-
-  async *generateStream(messages, tools) {
-    // Streaming implementation
-  }
-}
+Options:
+  --provider <name>    AI provider (openai, anthropic, google, xai, deepseek, ollama)
+  --model <name>       Specific model to use
+  --profile <name>     Agent profile (general, erosolar-code)
+  --restore            Resume last session
+  --version            Show version
 ```
 
-2. Register in `src/plugins/providers/`:
-
-```typescript
-registerProvider('custom', (config) => new CustomProvider(config));
-```
+---
 
-3. Add to `unified-schema.json`:
+## Architecture
 
-```json
-{
-  "id": "custom",
-  "label": "Custom Provider",
-  "envVars": { "apiKey": "CUSTOM_API_KEY" },
-  "capabilities": ["chat", "tools", "streaming"]
-}
 ```
-
-### Adding a Tool
-
-1. Create capability in `src/capabilities/`:
-
-```typescript
-export function createCustomTools(): ProviderToolDefinition[] {
-  return [{
-    name: 'custom_tool',
-    description: 'Does something useful',
-    parameters: {
-      type: 'object',
-      properties: {
-        input: { type: 'string', description: 'Input value' }
-      },
-      required: ['input']
-    }
-  }];
-}
-
-export async function executeCustomTool(args: { input: string }) {
-  // Implementation
-  return { result: 'success' };
-}
+erosolar-cli/
+├── src/
+│   ├── core/           # Agent runtime, tool execution
+│   ├── providers/      # OpenAI, Anthropic, Google adapters
+│   ├── tools/          # File, bash, search tools
+│   ├── shell/          # Interactive CLI interface
+│   └── capabilities/   # Tool registration system
+├── agents/
+│   ├── general.rules.json       # General agent guardrails
+│   └── erosolar-code.rules.json # Coding specialist rules
+└── contracts/
+    └── agent-schemas.json       # Model & provider definitions
 ```
 
-2. Register in tool registry
-
-3. Add to `tools.schema.json`
-
 ---
 
 ## License
 
 MIT
 
+---
+
 ## Links
 
-- [npm Package (TypeScript)](https://www.npmjs.com/package/erosolar-cli)
-- [PyPI Package (Python)](https://pypi.org/project/erosolar/)
-- [GitHub Repository](https://github.com/ErosolarAI/erosolar-by-bo)
+- [npm Package](https://www.npmjs.com/package/erosolar-cli)
+- [GitHub](https://github.com/ErosolarAI/erosolar-by-bo)
 - [Issues](https://github.com/ErosolarAI/erosolar-by-bo/issues)
 
-## Support
-
-- Email: support@ero.solar
-- GitHub Issues for bug reports and feature requests
+---
 
-## Research
+## Author
 
-Alpha Zero 2 Research: See `src/alpha-zero/` (TypeScript) and `python-bo-cli/erosolar_cli/alpha_zero/` (Python)
+Built by **Bo Shang** with assistance from Claude Code, OpenAI Codex CLI, and a lot of caffeine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "erosolar-cli",
-  "version": "1.6.13",
+  "version": "1.6.14",
   "description": "Unified AI agent framework for the command line - Multi-provider support with schema-driven tools, code intelligence, and transparent reasoning",
   "main": "dist/bin/erosolar-optimized.js",
   "type": "module",