jiva-core 0.3.3 → 0.3.4-dev.945ddfc

package/README.md

@@ -1,709 +1,381 @@
-# Jiva - Versatile Autonomous AI Agent
+# Jiva
 
-[![npm version](https://img.shields.io/npm/v/jiva-core.svg)](https://www.npmjs.com/package/jiva-core) [![License](https://img.shields.io/github/license/KarmaloopAI/Jiva.svg)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/KarmaloopAI/Jiva.svg?style=social&label=Star)](https://github.com/KarmaloopAI/Jiva)
+[![npm version](https://img.shields.io/npm/v/jiva-core.svg)](https://www.npmjs.com/package/jiva-core)
+[![License](https://img.shields.io/github/license/KarmaloopAI/Jiva.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/KarmaloopAI/Jiva.svg?style=social&label=Star)](https://github.com/KarmaloopAI/Jiva)
 
-Jiva is a powerful autonomous AI agent with a three-agent architecture (Manager, Worker, Client) powered by gpt-oss-120b with full MCP (Model Context Protocol) support. Deploy as a CLI tool or scale to production on Google Cloud Run.
-
-## Quick Links
-
-- **[Quick Start Guide](docs/guides/QUICKSTART.md)** - Get up and running in 30 seconds
-- **[Cloud Run Deployment](docs/deployment/CLOUD_RUN_DEPLOYMENT.md)** - Deploy to production
-- **[Configuration Guide](docs/guides/CONFIGURATION.md)** - Detailed configuration and provider setup
-- **[Documentation](docs/README.md)** - Complete documentation index
-- **[Build Instructions](docs/guides/BUILD.md)** - Detailed setup and development workflow
-- **[Troubleshooting](docs/guides/TROUBLESHOOTING.md)** - Common issues and solutions
+Jiva is an autonomous AI agent for the terminal and cloud. It works with any OpenAI-compatible model provider and supports two execution modes — a general-purpose two-agent system (Manager + Worker) for complex tasks, and a code-optimized single-loop engine with LSP integration for software engineering.
 
 ## Demo
 
 ![Demo](jiva-new-demo.gif)
 
-## Features
-
-### Core Capabilities
-- **Three-Agent Architecture**: Manager for planning, Worker for execution, Client for quality validation
-- **Adaptive Quality Control**: Client agent uses tiered validation (MINIMAL→STANDARD→THOROUGH) based on task complexity
-- **Unjustified Failure Detection**: LLM-powered analysis catches agents giving up without trying
-- **Cloud-Ready Deployment**: Run on Google Cloud Run with auto-scaling, WebSocket support, and GCS storage
-- **Multi-Tenancy**: Per-tenant isolation with authenticated session management
-- **Provider Agnostic**: Works with Krutrim, Groq, OpenAI, Ollama, and any OpenAI-compatible API
-- **MCP Integration**: Seamless integration with Model Context Protocol servers for extensible tooling
-- **Smart Conversations**: Auto-save, restore, and AI-generated titles for all conversations
-- **Directive-Based**: Orient agent behavior with custom `jiva-directive.md` files
-- **Storage Abstraction**: Local filesystem or cloud storage (GCS, future: S3, Redis)
-
-### v0.3.1 Features
-- **Production Deployment**: One-command Cloud Run deployment with GCS persistence
-- **Client Agent**: Intelligent validation that ensures work quality and catches false failures
-- **HTTP/WebSocket API**: RESTful endpoints and real-time bidirectional communication
-- **Authentication**: Firebase Auth, custom JWT, or development mode
-- **Session Management**: Auto-scaling agent instances with idle timeout and cleanup
-- **Container Orchestration**: Multi-stage Docker builds, health probes, graceful shutdown
-- **Personas & Skills**: 100% compatible with Claude's Skills/Plugins system - extend Jiva with domain-specific capabilities
-
-### Personas (Skills & Plugins)
-
-Jiva supports persona-based skill management, fully compatible with Claude's Skills/Plugins system:
-
-```bash
-# List available personas
-jiva persona list
-
-# Activate a persona
-jiva persona activate data-analyst
-
-# Create your own skill
-jiva persona create-skill my-skill \
-  --description "Custom functionality" \
-  --author "Your Name"
-
-# Package and distribute
-jiva persona package-skill my-skill
-```
-
-**Key Features:**
-- **Progressive Disclosure**: Skills load only what's needed (L1→L2→L3)
-- **Automatic Routing**: Agent selects skills based on user request
-- **Composable**: Bundle skills, commands, agents, and MCP servers
-- **Portable**: Same .skill files work on Claude and Jiva
-
-See **[Personas Guide](docs/guides/PERSONAS.md)** for complete documentation.
-
-### v0.3.23 Bug Fixes
-- **Linux Path Fix**: Resolved startup errors on Linux where Jiva was reading from the wrong directory — new `platform.ts` utility ensures correct path resolution across all platforms
-- **Punycode Deprecation**: Eliminated `[DEP0040] DeprecationWarning` by lazy-loading `@google-cloud/storage` so the deprecated built-in `punycode` module is never loaded during CLI-only sessions
-- **Type Safety**: Fixed a `mustUseTools` type error in the Client agent
-- **Dev Publishing**: Added CI workflow to auto-publish `dev`-tagged npm releases on every merge to `develop`
-
-### v0.3.22 Maintenance
-- **Security Updates**: Upgraded `glob` and `tr46` via npm `overrides` to resolve known vulnerabilities
-- **CI/CD**: Added GitHub Actions workflow to automatically publish releases to npm
-
-### v0.3.2 Bug Fixes & Quality Improvements
-**Bug Fixes:**
-- **Persona Isolation**: Sub-agents now use ephemeral personas that don't overwrite parent agent configuration
-- **Context Propagation**: Workspace directory automatically injected into all sub-agent task messages
-- **Enhanced Logging**: Persona context included in all log messages for better multi-agent debugging
-- **Reduced Hallucination**: Temperature lowered from 0.3-0.7 to 0.1-0.2 for more deterministic, fact-based behavior
-
-**HTTP/Cloud Compatibility:**
-- **🚨 Per-Tenant Persona Config** (CRITICAL): Fixed cross-tenant persona configuration leakage - each tenant's settings now isolated in GCS
-- **Session-Scoped Logging**: Fixed persona context race conditions in concurrent HTTP sessions
-- **Cloud-Aware Orchestration**: Orchestration logs now persist to cloud storage (GCS/S3) instead of ephemeral filesystem
-
-**Quality Improvements:**
-- **LLM-Based Validation**: Client agent uses semantic analysis instead of keyword matching for involvement level detection
-- **Coherence Checking**: Detects when Worker fabricates accomplishments not supported by actual tool usage
-- **Robust Plan Parsing**: Manager agent parsing with JSON format, LLM cleanup fallback, and garbage filtering
-- **Client Logging**: Full orchestration traceability for validation decisions and quality control
-
-**⚠️ CRITICAL:** If running in HTTP/Cloud mode (v0.3.1+), **upgrade immediately**:
-- v0.3.1 has cross-tenant configuration leakage (security issue)
-- v0.3.2 fixes multi-tenant isolation with per-tenant storage
-
-### v0.2.1 Features
-- **Dual-Agent System**: Separate Manager and Worker agents for better task focus and reliability
-- **Chain-of-Thought Logging**: Transparent reasoning at INFO level with clean ASCII formatting
-- **Robust Error Recovery**: Automatic retry with error feedback for API and tool failures
-- **Workspace-Aware Operations**: Smart path resolution for file operations
-- **Slash Commands**: Use `/help`, `/load`, `/save`, `/list` for easy conversation management
-- **Smart Tool Format Detection**: Auto-detects Harmony vs Standard OpenAI tool calling format
-
-See [release notes](docs/release_notes/) for detailed version history.
+---
 
 ## Installation
 
-### Global Install (Recommended)
-
 ```bash
 npm install -g jiva-core
-```
-
-After installation, run the setup wizard:
-
-```bash
 jiva setup
 ```
 
-### Development Install
-
-```bash
-git clone https://github.com/KarmaloopAI/Jiva.git
-cd jCLI Mode (Local Development)
+The setup wizard prompts for your API endpoint, key, and model name. Jiva works with Krutrim, Groq, OpenAI, Ollama, and any OpenAI-compatible provider.
 
-#### 1. Install Jiva
+### Development install
 
 ```bash
-npm install -g jiva-core
+git clone https://github.com/KarmaloopAI/Jiva.git
+cd Jiva
+npm install && npm run build && npm link
+jiva setup
 ```
 
-#### 2. First-Time Setup
+---
 
-Run the interactive setup wizard:
+## Quick Start
 
 ```bash
-jiva setup
-```
+# General-purpose interactive session
+jiva chat
 
-You'll be prompted for:
-- Krutrim API endpoint (default: `https://cloud.olakrutrim.com/v1/chat/completions`)
-- API key for gpt-oss-120b ([Get your API key](https://cloud.olakrutrim.com))
-- Optional multimodal model (Llama-4-Maverick-17B)
-- MCP server configuration
+# Code mode — optimized for software engineering tasks
+jiva chat --code
 
-#### 3. Start Chatting
+# Code mode with plan-then-approve flow
+jiva chat --code --plan
 
-Launch interactive mode:
+# Single prompt
+jiva run "What changed in the last 5 commits?"
 
-```bash
-jiva chat
+# Single prompt in code mode
+jiva run "Add error handling to the database module" --code
 ```
 
-**Try these commands:**
-```bash
-You: /help                    # Show all available commands
-You: /servers                 # Check MCP server status
-You: /tools                   # List all available tools
-You: List files in this directory
-You: /save                    # Save this conversation
-You: /list                    # View all saved conversations
-```
+### REPL commands
 
-### Cloud Run Mode (Production)
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/tools` | List active tools |
+| `/servers` | Show MCP server status |
+| `/save` | Save current conversation |
+| `/load` | Resume a saved conversation |
+| `/list` | Browse all saved conversations |
+| `/reset` | Clear conversation history |
+| `/exit` | Exit Jiva |
 
-Deploy Jiva as an auto-scaling HTTP/WebSocket service:
+---
 
-#### 1. Prerequisites
+## Execution Modes
 
-- Google Cloud account with billing enabled
-- `gcloud` CLI installed and configured
-- Docker installed (for local testing)
+### General mode (default)
 
-#### 2. One-Command Deployment
+A two-agent pipeline designed for complex, multi-step tasks:
 
-```bash
-git clone https://github.com/KarmaloopAI/Jiva.git
-cd jiva
-./deploy.sh YOUR_PROJECT_ID us-central1
+```
+User Request
+    ↓
+Manager Agent    — plans, decomposes, and synthesizes
+    ↓
+Worker Agent     — executes subtasks with MCP tools
+    ↓
+Response
 ```
 
-The script automatically:
-- Enables required GCP APIs
-- Creates GCS bucket for state storage
-- Configures service account and IAM roles
-- Builds and deploys container to Cloud Run
-- Outputs service URL
+The Worker has access to any configured MCP server (filesystem, browser automation, shell commands, etc.). The Manager synthesizes results from all subtasks into a final coherent response. Simple conversational messages are answered directly without executing subtasks.
 
-#### 3. Test Deployment
+### Code mode (`--code`)
 
-```bash
-SERVICE_URL=$(gcloud run services describe jiva --region=us-central1 --format='value(status.url)')
+A single streaming loop optimized for coding tasks:
 
-# Health check
-curl $SERVICE_URL/health
-
-# Chat endpoint (with auth bypass for testing)
-curl -X POST $SERVICE_URL/api/chat \
-  -H "Content-Type: application/json" \
-  -H "X-Session-Id: test-session" \
-  -d '{"message": "Hello, Jiva!"}'
 ```
+User Request
+    ↓
+CodeAgent
+    loop until done:
+        LLM call with tool definitions
+        ↓
+        Tool execution (in-process, no subprocess)
+        ↓
+        LSP feedback after file edits
+    ↓
+Response
+```
+
+Code mode reduces latency by eliminating inter-agent overhead and running all file tools directly in the Node.js process. It includes a multi-strategy edit engine that reliably handles indentation drift and whitespace inconsistencies.
+
+**Available tools in code mode:**
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read files with line numbers, list directories |
+| `edit_file` | Multi-strategy string replacement (9 strategies) |
+| `write_file` | Create or overwrite files |
+| `glob` | Find files by pattern |
+| `grep` | Regex content search |
+| `bash` | Run shell commands |
+| `spawn_code_agent` | Delegate a sub-task to a child agent |
+
+**LSP integration:** After each file edit, Jiva notifies the appropriate language server and appends any compiler errors to the tool result. Language servers are auto-detected from your PATH. If none is installed for a given language, the tool continues silently.
 
-**Full deployment guide:** [Cloud Run Deployment](docs/deployment/CLOUD_RUN_DEPLOYMENT.md)ry these commands:**
 ```bash
-You: /help                    # Show all available commands
-You: /servers                 # Check MCP server status
-You: /tools                   # List all available tools
-You: List files in this directory
-You: /save                    # Save this conversation
-You: /list                    # View all saved conversations
+# Install language servers (optional but recommended for code mode)
+npm install -g typescript-language-server typescript   # TypeScript / JavaScript
+pip install python-lsp-server                          # Python
+go install golang.org/x/tools/gopls@latest             # Go
+rustup component add rust-analyzer                     # Rust
 ```
 
-### 4. Advanced Usage
+For a complete technical reference see [Code Mode Architecture](docs/architecture/CODE_MODE.md).
 
-**View current configuration:**
-```bash
-jiva config --show
-```
+---
 
-**Use a custom configuration file:**
-```bash
-jiva chat --config ./my-project-config.json
-jiva run "analyze code" --config ./team-config.json
-```
+## Configuration
 
-**Custom workspace and directive:**
 ```bash
-jiva chat --workspace /path/to/project --directive ./project-directive.md
-```
+# Run setup wizard
+jiva setup
 
-**Single command execution:**
-```bash
-jiva run "Analyze the code in this directory and suggest improvements"
-```
+# View or update settings interactively
+jiva config
 
-**Enable debug mode:**
-```bash
-jiva chat --debug
+# View current configuration and file path
+jiva config --show
 ```
 
-### 5. Example Workflows
+Configuration is stored at `~/.config/jiva-nodejs/config.json` (Linux/macOS) or `%APPDATA%\jiva-nodejs\config.json` (Windows).
 
-**Code Review:**
-```bash
-You: Review all TypeScript files and identify potential bugs
-Jiva: *Uses filesystem to read files, analyzes code, provides detailed review*
-```
+### Provider examples
 
-**Web Research:**
-```bash
-You: Open Hacker News and summarize the top 5 articles
-Jiva: *Uses playwright to navigate, scrape content, and summarize*
+**Krutrim (gpt-oss-120b)**
+```json
+{
+  "models": {
+    "reasoning": {
+      "endpoint": "https://cloud.olakrutrim.com/v1/chat/completions",
+      "apiKey": "kr-...",
+      "model": "gpt-oss-120b",
+      "type": "reasoning",
+      "useHarmonyFormat": true
+    }
+  }
+}
 ```
 
-**System Administration:**
-```bash
-You: Check disk usage and list the 10 largest directories
-Jiva: *Uses desktop-commander to run du commands and analyze output*
+**Groq**
+```json
+{
+  "models": {
+    "reasoning": {
+      "endpoint": "https://api.groq.com/openai/v1/chat/completions",
+      "apiKey": "gsk_...",
+      "model": "openai/gpt-oss-20b",
+      "type": "reasoning"
+    }
+  }
+}
 ```
 
-**Conversation Management:**
-```bash
-You: /list                    # Browse previous conversations
-You: /load                    # Resume a conversation
-# Select from interactive menu with arrow keys
-You: Continue where we left off
+**Ollama (local)**
+```json
+{
+  "models": {
+    "reasoning": {
+      "endpoint": "http://localhost:11434/v1/chat/completions",
+      "apiKey": "not-needed",
+      "model": "llama3.1",
+      "type": "reasoning"
+    }
+  }
+}
 ```
 
-## Configuration
-
-Configuration is stored in your system's config directory (managed by `conf` package).
-
-### View Configuration Location
+### Code mode configuration
 
-```bash
-jiva config
+```json
+{
+  "codeMode": {
+    "enabled": true,
+    "lsp": { "enabled": true },
+    "maxIterations": 50
+  }
+}
 ```
 
-### Manual Configuration
+Full configuration reference: [Configuration Guide](docs/guides/CONFIGURATION.md)
 
-You can also manually edit the config file. Location varies by OS:
-- macOS: `~/Library/Preferences/jiva-nodejs/`
-- Linux: `~/.config/jiva-nodejs/`
-- Windows: `%APPDATA%\jiva-nodejs\`
+---
 
 ## Directive Files
 
-Jiva can be oriented with a `jiva-directive.md` file that defines its purpose, tasks, and constraints.
-
-### Example Directive
-
-Create a file called `jiva-directive.md`:
+Create a `jiva-directive.md` in your project root to orient the agent to your codebase:
 
 ```markdown
 # Purpose
-
-You are a code review assistant focused on identifying security vulnerabilities
-and suggesting performance improvements in Python projects.
+Code review assistant for a Django web application.
 
 # Tasks
-
-- Scan Python files for common security issues (SQL injection, XSS, etc.)
+- Scan for security vulnerabilities (SQLi, XSS, CSRF)
 - Identify performance bottlenecks
 - Suggest modern Python best practices
-- Check for outdated dependencies
 
 # Constraints
-
-- Only analyze Python files (.py)
-- Do not modify code without explicit approval
-- Prioritize security issues over style improvements
+- Only analyze .py files
+- Do not modify files without explicit approval
 
 # Context
-
-This project is a Django web application with a PostgreSQL database.
-It handles sensitive user data and must comply with GDPR.
+PostgreSQL backend, GDPR-sensitive user data.
 ```
 
-Jiva will automatically look for this file in:
-1. Path specified with `--directive` flag
-2. `jiva-directive.md` in workspace root
-3. `.jiva/directive.md` in workspace root
-
-## MCP Servers
-
-Jiva leverages the Model Context Protocol (MCP) to provide extensible tooling. It comes pre-configured with the Filesystem server and makes it easy to add more.
-
-### Default Server: Filesystem
+Jiva searches for directive files automatically:
+1. Path given via `--directive`
+2. `jiva-directive.md` in the workspace root
+3. `.jiva/directive.md` in the workspace root
 
-Provides comprehensive file operations across user directories (subject to OS permissions).
+---
 
-- **Status:** ✅ Enabled by default
-- **Package:** `@modelcontextprotocol/server-filesystem`
-- **Access:** `/Users` (macOS/Linux) or `C:\Users` (Windows)
-- **Tools:** read_file, write_file, list_directory, create_directory, and more
-- **Details:** See [FILESYSTEM_ACCESS.md](docs/architecture/FILESYSTEM_ACCESS.md)
+## MCP Servers (general mode)
 
-### Recommended Additional Servers
+General mode uses MCP servers to extend the agent's capabilities. Jiva ships with the filesystem server enabled; additional servers can be added via `jiva config`.
 
-#### 1. Playwright MCP - Browser Automation
+### Recommended servers
 
-Control real browsers, take screenshots, scrape web content, and automate web interactions.
+**Playwright** — browser automation, web scraping, screenshot capture
 
 ```bash
-# Add Playwright MCP server
 jiva config
-# Select "MCP Servers" > "Add Server"
-# Name: playwright
-# Command: npx
-# Args: @playwright/mcp@latest
-# Enabled: true
+# MCP Servers > Add Server
+# Name: playwright  Command: npx  Args: @playwright/mcp@latest
 ```
 
-**Capabilities:**
-- 🌐 Navigate to URLs and interact with web pages
-- 📸 Take screenshots and extract page content
-- 🤖 Automate web forms and workflows
-- 🔍 Scrape data from websites
-- 📝 Fill forms and click buttons
-
-**Example usage:**
-```
-You: Open LinkedIn and take a screenshot
-Jiva: *Uses playwright to open LinkedIn, waits for load, captures screenshot*
-```
-
-#### 2. Desktop Commander - Shell Command Execution
-
-Execute shell commands, manage processes, and interact with the terminal.
+**Desktop Commander** — shell command execution, process management
 
 ```bash
-# Add Desktop Commander MCP server
-jiva config
-# Select "MCP Servers" > "Add Server"
-# Name: desktop-commander
-# Command: npx
-# Args: -y desktop-commander
-# Enabled: true
+# Name: desktop-commander  Command: npx  Args: -y desktop-commander
 ```
 
-**Capabilities:**
-- 💻 Execute shell commands (ls, grep, git, etc.)
-- 🔄 Start and manage background processes
-- 📊 Read process output with timeout control
-- 🎯 Session management for long-running commands
+Other popular servers: GitHub, Postgres, Slack, Google Maps — see [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers).
 
-**Example usage:**
-```
-You: Run npm test and show me the results
-Jiva: *Uses desktop-commander to execute tests and parse output*
-```
-
-**⚠️ Security Note:** Desktop Commander can execute any shell command. Only enable if you understand the security implications and trust the agent.
-
-### Other Available MCP Servers
+---
 
-The MCP ecosystem offers many more servers:
+## Cloud Deployment
 
-- **GitHub** (`@modelcontextprotocol/server-github`) - Repository management, issues, PRs
-- **Google Maps** (`@modelcontextprotocol/server-google-maps`) - Location data and mapping
-- **Slack** (`@modelcontextprotocol/server-slack`) - Team communication
-- **Postgres** (`@modelcontextprotocol/server-postgres`) - Database operations
-- **Git** (`@modelcontextprotocol/server-git`) - Version control operations
-- And more at [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
-
-### Adding MCP Servers
-
-#### Via Interactive Config
+Jiva can be deployed as a stateless, auto-scaling HTTP/WebSocket service on Google Cloud Run with GCS-backed session persistence and multi-tenant isolation.
 
 ```bash
-jiva config
-# Navigate: MCP Servers > Add Server
-# Fill in: name, command, args, enabled
-```
-
-#### Via Manual Config Edit
-
-Edit your config file at `~/.config/jiva-nodejs/config.json` (Linux) or `~/Library/Preferences/jiva-nodejs/config.json` (macOS):
-
-```json
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": ["@playwright/mcp@latest"],
-      "enabled": true
-    },
-    "desktop-commander": {
-      "command": "npx",
-      "args": ["-y", "desktop-commander"],
-      "enabled": true
-    }
-  }
-}
-```
-
-#### Programmatically
-
-```typescript
-### Three-Agent System (v0.3.1)
-
-Jiva uses a three-agent architecture for intelligent task execution:
-
-```
-User Request
-     ↓
-┌────────────────┐
-│ Manager Agent  │  Plans subtasks, coordinates workflow
-└────────┬───────┘
-         ↓
-┌────────────────┐
-│ Worker Agent   │  Executes subtasks with MCP tools
-└────────┬───────┘
-         ↓
-┌────────────────┐
-│ Client Agent   │  Validates outputs, ensures quality
-└────────┬───────┘
-         ↓
-    Final Response
+git clone https://github.com/KarmaloopAI/Jiva.git
+cd Jiva
+./deploy.sh YOUR_PROJECT_ID us-central1
 ```
 
-**Manager Agent**: High-level planning and task decomposition  
-**Worker Agent**: Tool execution and information gathering  
-**Client Agent**: Adaptive validation and quality control (new in v0.3.1)
+The deployment script enables required GCP APIs, creates the GCS bucket, configures IAM roles, and deploys the container. After deployment:
 
-The Client agent uses tiered involvement levels to balance quality with efficiency:
-- **MINIMAL**: Information requests → metadata validation only
-- **STANDARD**: Creation tasks → file exists + basic checks
-- **THOROUGH**: Complex tasks or after failures → full E2E validation
+```bash
+SERVICE_URL=$(gcloud run services describe jiva --region=us-central1 --format='value(status.url)')
 
-### Project Structure
+# Health check
+curl $SERVICE_URL/health
 
+# Chat via REST
+curl -X POST $SERVICE_URL/api/chat \
+  -H "Content-Type: application/json" \
+  -H "X-Session-Id: my-session" \
+  -d '{"message": "Hello, Jiva!"}'
 ```
-jiva/
-├── src/
-│   ├── core/              # Three-agent system
-│   │   ├── dual-agent.ts        # Main orchestrator
-│   │   ├── manager-agent.ts     # Planning & coordination
-│   │   ├── worker-agent.ts      # Tool execution
-│   │   └── client-agent.ts      # Quality validation (v0.3.1)
-│   ├── models/            # Model integrations and Harmony format
-│   ├── mcp/               # MCP client and server management
-│   ├── storage/           # Storage abstraction (v0.3.1)
-│   │   ├── local-provider.ts    # Filesystem storage
-│   │   └── gcp-bucket-provider.ts # Cloud storage
-│   ├── interfaces/        # CLI and HTTP interfaces
-│   │   ├── cli/           # CLI interface
-│   │   └── http/          # Cloud Run HTTP/WebSocket (v0.3.1)
-│   └── utils/             # Utilities and helpers
-```
-
-### Key Components
-
-1. **DualAgent**: Main orchestrator coordinating Manager, Worker, and Client agents
-2. **ManagerAgent**: High-level planning, task breakdown, and result synthesis
-3. **WorkerAgent**: Focused tool execution and information gathering
-4. **ClientAgent**: Adaptive validation with unjustified failure detection
-5. **ModelOrchestrator**: Manages multi-model coordination (reasoning + multimodal)
-6. **MCPServerManager**: Handles MCP server lifecycle and tool discovery
-7. **StorageProvider**: Unified interface for local/cloud persistence
-8. **SessionManager**: Manages DualAgent lifecycle in cloud deployments
-
-**Troubleshooting MCP Issues:** See [TROUBLESHOOTING.md](docs/guides/TROUBLESHOOTING.md#mcp-server-issues)
-
-### CLI/Library Mode
 
-```typescript
-import {
-  DualAgent,
-  createKrutrimModel,
-  ModelOrchestrator,
-  MCPServerManager,
-  WorkspaceManager,
-  ConversationManager,
-  createStorageProvider,
-} from 'jiva-core';
-
-// Create storage provider (auto-detects local/cloud)
-const storageProvider = await createStorageProvider();
-
-// Create models
-const reasoningModel = createKrutrimModel({
-  endpoint: 'https://cloud.olakrutrim.com/v1/chat/completions',
-  apiKey: 'your-api-key',
-  model: 'gpt-oss-120b',
-  type: 'reasoning',
-});
-
-// Create orchestrator
-const orchestrator = new ModelOrchestrator({ reasoningModel });
-
-// Initialize MCP
-const mcpManager = new MCPServerManager();
-await mcpManager.initialize({
-  filesystem: {
-    command: 'npx',
-    args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()],
-    enabled: true,
-  },
-});
+**Code mode in the cloud:**
 
-// Initialize workspace
-const workspace = new WorkspaceManager(storageProvider);
-await workspace.initialize();
-
-// Initialize conversation manager
-const conversationManager = new ConversationManager(storageProvider);
-
-// Create three-agent system
-const agent = new DualAgent({
-  orchestrator,
-  mcpManager,
-  workspace,
-  conversationManager,
-  maxSubtasks: 20,        // Manager's subtask limit
-  maxIterations: 10,      // Worker's iteration limit per subtask
-});
-
-// Use agent
-const response = await agent.chat('Hello, Jiva!');
-console.log(response.content);
-console.log(`Plan: ${response.plan?.subtasks.join(', ')}`);
-console.log(`Tools used: ${response.toolsUsed.join(', ')}`);
-
-// Cleanup
-await agent.cleanup();
+```bash
+gcloud run services update jiva \
+  --set-env-vars JIVA_CODE_MODE=true \
+  --region us-central1
 ```
 
-### Cloud Mode (HTTP/WebSocket)
+Full guide: [Cloud Run Deployment](docs/deployment/CLOUD_RUN_DEPLOYMENT.md)
 
-For cloud deployments, see the [HTTP interface documentation](docs/deployment/CLOUD_RUN_IMPLEMENTATION.md) and [example programs](examples/).
+---
 
-**Key difference:** Cloud mode uses `SessionManager` to handle multiple concurrent agent instances with per-tenant isolation.
-## Development
+## Personas and Skills
 
-### Build
+Jiva supports persona-based skill management, compatible with Claude's Skills/Plugins format:
 
 ```bash
-npm run build
-```
-
-### Development Mode
-
-```bash
-npm run dev
+jiva persona list
+jiva persona activate data-analyst
+jiva persona create-skill my-skill --description "Custom capability" --author "Your Name"
 ```
 
-### Type Checking
+Skills bundle MCP servers, directives, and model behavior overrides into portable `.skill` files. See [Personas Guide](docs/guides/PERSONAS.md).
 
-```bash
-npm run type-check
-```
+---
 
 ## Programmatic Usage
 
-Jiva can also be used programmatically:
-
 ```typescript
-import {
-  DualAgent,
-  createKrutrimModel,
-  ModelOrchestrator,
-  MCPServerManager,
-  WorkspaceManager,
-  ConversationManager,
-} from 'jiva';
-
-// Create models
+import { DualAgent, CodeAgent, createKrutrimModel, ModelOrchestrator,
+         MCPServerManager, WorkspaceManager, ConversationManager,
+         createStorageProvider } from 'jiva-core';
+
 const reasoningModel = createKrutrimModel({
-  endpoint: 'https://cloud.olakrutrim.com/v1/chat/completions',
-  apiKey: 'your-api-key',
-  model: 'gpt-oss-120b',
+  endpoint: 'https://api.groq.com/openai/v1/chat/completions',
+  apiKey: process.env.API_KEY!,
+  model: 'openai/gpt-oss-20b',
   type: 'reasoning',
 });
-
-// Create orchestrator
 const orchestrator = new ModelOrchestrator({ reasoningModel });
+const storageProvider = await createStorageProvider();
+const workspace = new WorkspaceManager(storageProvider);
+await workspace.initialize();
+const conversationManager = new ConversationManager(storageProvider);
 
-// Initialize MCP
+// General mode
 const mcpManager = new MCPServerManager();
 await mcpManager.initialize({
-  filesystem: {
-    command: 'npx',
-    args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()],
-    enabled: true,
-  },
-});
-
-// Initialize workspace
-const workspace = new WorkspaceManager({
-  workspaceDir: process.cwd(),
-});
-await workspace.initialize();
-
-// Initialize conversation manager (optional)
-const conversationManager = new ConversationManager();
-await conversationManager.initialize();
-
-// Create dual-agent
-const agent = new DualAgent({
-  orchestrator,
-  mcpManager,
-  workspace,
-  conversationManager,
-  maxSubtasks: 10,
+  filesystem: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()], enabled: true },
 });
-
-// Use agent
-const response = await agent.chat('Hello, Jiva!');
+const agent = new DualAgent({ orchestrator, mcpManager, workspace, conversationManager });
+const response = await agent.chat('What files are in this directory?');
 console.log(response.content);
-console.log(`Plan: ${response.plan?.subtasks.join(', ')}`);
-console.log(`Tools used: ${response.toolsUsed.join(', ')}`);
-
-// Cleanup
 await agent.cleanup();
-```
-
-## Troubleshooting
-
-### Tool Calls Not Working
 
-The gpt-oss-120b model has known issues with tool calling reliability. Jiva implements several workarounds:
-
-1. **Retry Logic**: Automatically retries malformed tool calls
-2. **JSON Fixing**: Attempts to fix common JSON formatting issues
-3. **Validation**: Validates tool calls against available tools
-4. **Logging**: Enable debug mode to see detailed tool call information
-
-```bash
-jiva chat --debug
+// Code mode
+const codeAgent = new CodeAgent({ orchestrator, workspace, conversationManager, maxIterations: 50, lspEnabled: true });
+const codeResponse = await codeAgent.chat('Refactor the auth module to use async/await');
+console.log(codeResponse.content);
+await codeAgent.cleanup();
 ```
 
-### MCP Server Connection Issues
+Both `DualAgent` and `CodeAgent` implement the `IAgent` interface and are interchangeable in application code.
 
-Check server status:
+---
+
+## Development
 
 ```bash
-jiva chat
-# Then type: servers
+npm run build        # compile TypeScript
+npm run dev          # watch mode
+npm run type-check   # type-check without emit
 ```
 
-View logs:
+---
 
-```bash
-jiva chat --debug
-```
+## Documentation
 
-## API Documentation
+| Document | Description |
+|----------|-------------|
+| [Quick Start](docs/guides/QUICKSTART.md) | Get running in 30 seconds |
+| [Configuration Guide](docs/guides/CONFIGURATION.md) | All config options and provider examples |
+| [Code Mode Architecture](docs/architecture/CODE_MODE.md) | How code mode works internally |
+| [Cloud Run Deployment](docs/deployment/CLOUD_RUN_DEPLOYMENT.md) | Production deployment guide |
+| [Personas Guide](docs/guides/PERSONAS.md) | Skills and persona system |
+| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common issues and fixes |
+| [Release Notes](docs/release_notes/) | Version history |
 
-For detailed API documentation, see the TypeScript definitions in `src/`.
+---
 
 ## Contributing
 
-Contributions are welcome! Please ensure:
-
-1. Code follows TypeScript best practices
-2. All new features include proper error handling
-3. Documentation is updated
+Contributions are welcome. Please ensure new features include error handling and that documentation is updated. Open a PR against the `develop` branch.
 
 ## License
 
@@ -715,13 +387,3 @@ MIT
 - [Harmony Response Format](https://github.com/openai/harmony)
 - [Model Context Protocol](https://modelcontextprotocol.io/)
 - [Krutrim Cloud API](https://cloud.olakrutrim.com/)
-
-## Sources
-
-This implementation is based on research from:
-
-- [OpenAI Harmony GitHub Repository](https://github.com/openai/harmony)
-- [MCP with OpenAI gpt-oss](https://github.com/Vaibhavs10/mcp-with-openai-gpt-oss)
-- [OpenAI Cookbook - Harmony Format](https://cookbook.openai.com/articles/openai-harmony)
-- [MCP Best Practices](https://modelcontextprotocol.info/docs/best-practices/)
-- [vLLM GPT-OSS Documentation](https://docs.vllm.ai/projects/recipes/en/latest/OpenAI/GPT-OSS.html)