agent-orcha 0.0.4 → 0.0.7

package/README.md

@@ -4,261 +4,111 @@
 
 Agent Orcha is a declarative framework designed to build, manage, and scale multi-agent AI systems with ease. It combines the flexibility of TypeScript with the simplicity of YAML to orchestrate complex workflows, manage diverse tools via MCP, and integrate semantic search seamlessly. Built for developers and operators who demand reliability, extensibility, and clarity in their AI operations.
 
-**[Documentation](https://ddalcu.github.io/agent-orcha)** | **[NPM Package](https://www.npmjs.com/package/agent-orcha)** | **[Docker Hub](https://hub.docker.com/r/ddalcu/agent-orcha)**
+**[Documentation](https://agentorcha.com)** | **[NPM Package](https://www.npmjs.com/package/agent-orcha)** | **[Docker Hub](https://hub.docker.com/r/ddalcu/agent-orcha)**
 
-## Why Agent Orcha?
+```bash
+docker run -p 3000:3000 -v ./my-workspace:/data -e AUTH_PASSWORD=your-secret-password ddalcu/agent-orcha start
+```
 
-- **Declarative AI**: Define agents, workflows, and infrastructure in clear, version-controlled YAML files. No more spaghetti code.
-- **Model Agnostic**: Seamlessly swap between OpenAI, Gemini, Anthropic, or local LLMs (Ollama, LM Studio) without rewriting logic.
-- **Universal Tooling**: Leverage the **Model Context Protocol (MCP)** to connect agents to any external service, API, or database instantly.
-- **Knowledge Stores**: Built-in vector store and **GraphRAG** integration makes semantic search and knowledge graph analysis a first-class citizen.
-- **Robust Workflow Engine**: Orchestrate complex multi-agent sequences with parallel execution, conditional logic, and state management - or use **LangGraph** for autonomous prompt-driven workflows.
-- **Conversation Memory**: Built-in session-based memory for multi-turn dialogues with automatic message management and TTL cleanup.
-- **Structured Output**: Enforce JSON schemas on agent responses with automatic validation and type safety.
-- **Agent Orcha Studio**: Built-in web dashboard with agent testing, knowledge browsing, workflow execution, and an **in-browser IDE** for editing configs.
-- **Developer Experience**: Fully typed interfaces, intuitive CLI tooling, and a modular architecture designed for rapid iteration from prototype to production.
-- **Extensible Functions**: Drop in simple JavaScript functions to extend agent capabilities with zero boilerplate.
+## Why Agent Orcha?
 
-## Overview
+- **Declarative AI**: Define agents, workflows, and infrastructure in clear, version-controlled YAML files
+- **Published Agents**: Share agents via standalone chat pages at `/chat/<name>` with optional per-agent password protection
+- **Model Agnostic**: Seamlessly swap between OpenAI, Gemini, Anthropic, or local LLMs (Ollama, LM Studio) without rewriting logic
+- **Universal Tooling**: Leverage the **Model Context Protocol (MCP)** to connect agents to any external service, API, or database
+- **Knowledge Stores**: Built-in SQLite-based vector store with optional **direct mapping** for knowledge graphs — semantic search and graph analysis as a first-class citizen
+- **Robust Workflow Engine**: Orchestrate complex multi-agent sequences with parallel execution, conditional logic, and state management — or use **ReAct** for autonomous prompt-driven workflows
+- **Conversation Memory**: Built-in session-based memory for multi-turn dialogues with automatic message management and TTL cleanup
+- **Browser Sandbox**: Full Chromium browser with CDP control, Xvfb, and noVNC — plus an experimental **Vision Browser** for pixel-coordinate control with vision LLMs
+- **Security**: Rate limiting on auth endpoints, SSRF protection, SQL injection hardening, sandboxed execution
+- **Extensible Functions**: Drop in simple JavaScript functions to extend agent capabilities with zero boilerplate
 
-Agent Orcha enables you to:
+## Agent Orcha Studio
 
-- **Define agents** using YAML configuration files with customizable LLM providers, prompts, and tools
-- **Create workflows** that coordinate multiple agents in sequential, parallel, or autonomous (LangGraph) execution
-- **Integrate knowledge stores** for RAG (Retrieval Augmented Generation) with vector search and GraphRAG
-- **Connect MCP servers** to extend agent capabilities with external tools
-- **Create local functions** to give your agents the ability to call your own custom code
-- **Manage everything** through a web-based Studio dashboard with built-in IDE
+Built-in web dashboard at `http://localhost:3000` with agent testing, knowledge browsing, workflow execution, real-time monitoring, and an in-browser IDE with visual agent composer.
 
-### Alpha Status and Security Notice
+<p align="center">
+  <img src="docs/assets/images/screenshots/0.0.7-chat.png" alt="Agent Orcha Studio — Chat" width="100%" />
+</p>
 
-**This project is currently in ALPHA state.** No security precautions have been implemented yet. This software should **ALWAYS** be deployed behind a firewall without open access to its APIs. It is designed for **internal use only** and should never be exposed directly to the public internet.
+<p align="center">
+  <img src="docs/assets/images/screenshots/0.0.7-agentedit.png" alt="Agent Orcha Studio — Visual Agent Composer" width="100%" />
+</p>
 
+- **Agents** — Browse, invoke, stream responses, manage sessions
+- **Knowledge** — Browse, search, view entities and graph structure
+- **MCP** — Browse servers, view and call tools
+- **Workflows** — Execute step-based and ReAct workflows with streaming
+- **Skills** — Browse and inspect skills
+- **Monitor** — Real-time LLM call logs, ReAct loop metrics, and activity feed
+- **IDE** — File editor with syntax highlighting, hot-reload, and **visual agent composer** for `.agent.yaml` files
 
-## Usage
+## Architecture
 
-Agent Orcha can be used in multiple ways depending on your needs:
+<p align="center">
+  <img src="docs/architecture.svg" alt="Agent Orcha Architecture" width="100%" />
+</p>
 
-1. **CLI Tool (Recommended)** - Use `npx agent-orcha` to initialize and run Agent Orcha projects standalone
-2. **Backend API Server** - Run Agent Orcha as a REST API backend for your existing frontends or applications
-3. **Docker Image** - Use the official Docker image ([ddalcu/agent-orcha](https://hub.docker.com/r/ddalcu/agent-orcha)) for local and server deployments
-4. **Library** - Import and use Agent Orcha programmatically in your TypeScript/JavaScript projects
-5. **Source** - Clone and run directly from source for development or customization
+### Knowledge Layer
 
-**Requirements:** Node.js >= 20.0.0 (or Docker for containerized deployment)
+<p align="center">
+  <img src="docs/knowledge-architecture.svg" alt="Agent Orcha Knowledge Architecture" width="100%" />
+</p>
 
+## Usage
 
-## Quick Start
+Agent Orcha can be used in multiple ways:
 
-### CLI Usage
+1. **Docker Image** — Official image at [ddalcu/agent-orcha](https://hub.docker.com/r/ddalcu/agent-orcha)
+2. **CLI Tool** — `npx agent-orcha` to initialize and run projects
+3. **Backend API Server** — REST API for your existing frontends
+4. **Library** — Import programmatically in TypeScript/JavaScript
 
-1. **Initialize a project:**
-```bash
-npx agent-orcha init my-project
-cd my-project
-```
+**Requirements:** Node.js >= 24.0.0 (or Docker)
 
-2. **Configure LLM settings** in `llm.json`:
-```json
-{
-  "version": "1.0",
-  "models": {
-    "default": {
-      "provider": "openai",
-      "baseUrl": "http://localhost:1234/v1",
-      "apiKey": "not-needed",
-      "model": "your-model-name",
-      "temperature": 0.7
-    }
-  },
-  "embeddings": {
-    "default": {
-      "provider": "openai",
-      "baseUrl": "http://localhost:1234/v1",
-      "apiKey": "not-needed",
-      "model": "text-embedding-model"
-    }
-  }
-}
-```
+## Quick Start
 
-3. **Start the server:**
-```bash
-npx agent-orcha start
-```
+### Docker
 
-4. **Test your agent:**
 ```bash
-curl -X POST http://localhost:3000/api/agents/example/invoke \
-  -H "Content-Type: application/json" \
-  -d '{"input": {"query": "Hello, how are you?"}}'
+docker run -p 3000:3000 -e AUTH_PASSWORD=mypass -v ./my-project:/data ddalcu/agent-orcha
 ```
 
-### Docker Usage
+An empty workspace is automatically scaffolded with example agents, workflows, and configurations.
 
-Run Agent Orcha using the official Docker image:
-
-1. **Initialize a project:**
-```bash
-docker run -v ./my-agent-orcha-project:/data ddalcu/agent-orcha init
-```
+### CLI
 
-2. **Start the server:**
 ```bash
-docker run -p 3000:3000 -v ./my-agent-orcha-project:/data ddalcu/agent-orcha start
-```
-
-3. **Or use Docker Compose:**
-```yaml
-version: '3.8'
-
-services:
-  agent-orcha:
-    image: ddalcu/agent-orcha
-    ports:
-      - "3000:3000"
-    volumes:
-      - ./my-agent-orcha-project:/data
-    environment:
-      - ORCHA_BASE_DIR=/data
-```
+# Initialize a project
+npx agent-orcha init my-project
+cd my-project
 
-Then run:
-```bash
-docker-compose up
+# Start the server
+npx agent-orcha start
 ```
 
-See the [Docker Hub page](https://hub.docker.com/r/ddalcu/agent-orcha) for more details and available tags.
 
-### Library Usage
+### Library
 
 ```typescript
 import { Orchestrator } from 'agent-orcha';
 
-const orchestrator = new Orchestrator({
-  projectRoot: './my-agents-project'
-});
-
+const orchestrator = new Orchestrator({ workspaceRoot: './my-project' });
 await orchestrator.initialize();
 
-// Invoke an agent
 const result = await orchestrator.agents.invoke('researcher', {
-  topic: 'machine learning',
-  context: 'brief overview'
+  topic: 'machine learning'
 });
 
 console.log(result.output);
-
-// Run a workflow
-const workflowResult = await orchestrator.workflows.run('research-paper', {
-  topic: 'artificial intelligence'
-});
-
-console.log(workflowResult.output);
-
-// Search a knowledge store
-const searchResults = await orchestrator.knowledge.search('docs', {
-  query: 'how does authentication work',
-  k: 4
-});
-
-// Run agent with conversation memory
-const memoryResult = await orchestrator.runAgent(
-  'chatbot',
-  { message: 'Hello' },
-  'session-123'  // sessionId
-);
-
-// Clean up
 await orchestrator.close();
 ```
 
-### Backend API Server Usage
-
-Run Agent Orcha as a backend API server for your existing applications or frontends:
-
-```bash
-# Start the server (defaults to port 3000)
-npx agent-orcha start
-
-# Or specify a custom port
-PORT=8080 npx agent-orcha start
-```
-
-Agent Orcha exposes a complete REST API that your frontend can consume:
-
-```javascript
-// Example: Invoke an agent from your frontend
-const response = await fetch('http://localhost:3000/api/agents/researcher/invoke', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    input: { topic: 'AI trends' },
-    sessionId: 'user-session-123'  // Optional for conversation memory
-  })
-});
-
-const result = await response.json();
-console.log(result.output);
-
-// Example: Search a knowledge store
-const searchResponse = await fetch('http://localhost:3000/api/knowledge/docs/search', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    query: 'authentication best practices',
-    k: 5
-  })
-});
-
-const searchResults = await searchResponse.json();
-
-// Example: Stream agent responses (SSE)
-const eventSource = new EventSource(
-  'http://localhost:3000/api/agents/chatbot/stream?' +
-  new URLSearchParams({
-    input: JSON.stringify({ message: 'Hello!' }),
-    sessionId: 'user-123'
-  })
-);
-
-eventSource.onmessage = (event) => {
-  const data = JSON.parse(event.data);
-  console.log(data.chunk); // Streaming response chunk
-};
-```
-
-**CORS Configuration:**
-For production deployments, configure CORS in your server startup or use a reverse proxy (nginx, Caddy, etc.) to handle CORS headers.
-
-**Security Note:**
-Agent Orcha is currently in ALPHA with no built-in authentication. Always deploy behind a firewall or add your own authentication layer (JWT, API keys, etc.) before exposing to clients.
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `npx agent-orcha init [dir]` | Initialize a new project with example configs |
-| `npx agent-orcha start` | Start the agent orchestrator server |
-| `npx agent-orcha help` | Show help information |
-
-## Development Scripts
-
-For development on the agent-orcha framework itself:
-
-| Command | Description |
-|---------|-------------|
-| `npm run dev` | Start development server with auto-reload |
-| `npm run build` | Build |
-| `npm start` | Run build |
-| `npm run lint` | Run ESLint |
-| `npm run typecheck` | Run TypeScript type checking |
-
 ## Configuration
 
 ### LLM Configuration (llm.json)
 
-All LLM and embedding configurations are defined in `llm.json` at the project root. Agents and knowledge stores reference these configs by name.
+All LLM and embedding configs are defined in `llm.json`. Agents and knowledge stores reference these by name.
 
 ```json
 {
@@ -266,153 +116,56 @@ All LLM and embedding configurations are defined in `llm.json` at the project ro
   "models": {
     "default": {
       "baseUrl": "http://localhost:1234/v1",
-      "apiKey": "not-needed",
+      "apiKey": "${OPENAI_API_KEY}",
       "model": "qwen/qwen3-4b-2507",
-      "temperature": 0.7
-    },
-    "openai": {
-      "apiKey": "sk-your-openai-key",
-      "model": "gpt-4o",
-      "temperature": 0.7
+      "temperature": 0.7,
+      "thinkingBudget": 10000
     }
   },
   "embeddings": {
     "default": {
       "baseUrl": "http://localhost:1234/v1",
-      "apiKey": "not-needed",
+      "apiKey": "${OPENAI_API_KEY}",
       "model": "text-embedding-nomic-embed-text-v1.5",
       "eosToken": " "
-    },
-    "openai": {
-      "apiKey": "sk-your-openai-key",
-      "model": "text-embedding-3-small",
-      "dimensions": 1536
-    },
-    "gemini": {
-      "apiKey": "sk-your-gemini-key",
-      "model": "text-embedding-004"
     }
   }
 }
 ```
 
 All providers are treated as OpenAI-compatible APIs. For local inference:
-- **LM Studio**: Use `baseUrl: "http://localhost:1234/v1"`
-- **Ollama**: Use `baseUrl: "http://localhost:11434/v1"`
-- **OpenAI**: Omit `baseUrl` (uses default OpenAI endpoint)
+- **LM Studio**: `baseUrl: "http://localhost:1234/v1"`
+- **Ollama**: `baseUrl: "http://localhost:11434/v1"`
+- **OpenAI**: Omit `baseUrl` (uses default endpoint)
 
-#### Embedding Configuration Options
-
-Embedding configurations support the following options:
-
-- **model** (required): The embedding model name
-- **apiKey** (required): API key for the embedding service
-- **baseUrl** (optional): Custom API endpoint URL for local or alternative services
-- **provider** (optional): Provider type (openai, gemini, local). Auto-detected if omitted
-- **dimensions** (optional): Output embedding dimensions (e.g., 1536 for OpenAI text-embedding-3-small)
-- **eosToken** (optional): Token to append to all text inputs (e.g., " " for Nomic models to avoid SEP warnings)
-
-
-**Example configurations:**
-
-```json
-{
-  "embeddings": {
-    "nomic-local": {
-      "baseUrl": "http://localhost:1234/v1",
-      "apiKey": "not-needed",
-      "model": "text-embedding-nomic-embed-text-v1.5",
-      "eosToken": " "
-    },
-    "openai-small": {
-      "apiKey": "sk-your-key",
-      "model": "text-embedding-3-small",
-      "dimensions": 1536
-    },
-    "openai-large": {
-      "apiKey": "sk-your-key",
-      "model": "text-embedding-3-large",
-      "dimensions": 3072
-    },
-    "gemini": {
-      "apiKey": "sk-your-key",
-      "model": "text-embedding-004"
-    }
-  }
-}
-```
-
-### Environment Variables (Optional)
+### Environment Variables
 
 ```bash
-# Server configuration
-PORT=3000
-HOST=0.0.0.0
-
-# Base directory for config files (optional)
-ORCHA_BASE_DIR=/path/to/project
+PORT=3000                              # Server port
+HOST=0.0.0.0                          # Server host
+WORKSPACE=/path/to/project             # Base directory for config files
+AUTH_PASSWORD=your-secret-password     # Password auth for all API routes and Studio
+CORS_ORIGIN=https://your-frontend.com # Cross-origin policy (default: same-origin)
 ```
 
 ## Agents
 
-Agents are AI-powered units that can use tools and respond to queries. Define agents in YAML files within the `agents/` directory.
-
-### Agent Schema
-
-```yaml
-# agents/<name>.agent.yaml
-
-name: string                    # Unique identifier (required)
-description: string             # Human-readable description (required)
-version: string                 # Semantic version (default: "1.0.0")
-
-llm: string | object            # Reference to LLM config in llm.json
-  # Simple: llm: default
-  # With override: llm: { name: default, temperature: 0.3 }
-
-prompt:                         # Prompt configuration (required)
-  system: string                # System message/instructions
-  inputVariables: [string]      # Variables to interpolate in the prompt
-
-tools:                          # Tools available to agent (optional)
-  - mcp:<server-name>           # MCP server tools
-  - knowledge:<store-name>      # Knowledge store search
-  - function:<function-name>    # Custom function
-  - builtin:<tool-name>         # Built-in tools
-
-output:                         # Output formatting (optional)
-  format: text | json | structured
-  schema:                       # Required when format is "structured"
-    type: object
-    properties: { ... }
-    required: [string]
-
-metadata:                       # Custom metadata (optional)
-  category: string
-  tags: [string]
-```
-
-### Example Agent
+Agents are AI-powered units defined in YAML within the `agents/` directory.
 
 ```yaml
 # agents/researcher.agent.yaml
-
 name: researcher
 description: Researches topics using web fetch and knowledge search
 version: "1.0.0"
 
 llm:
   name: default
-  temperature: 0.5  # Override default temperature
+  temperature: 0.5
 
 prompt:
   system: |
-    You are a thorough researcher. Your task is to:
-    1. Search through available knowledge bases
-    2. Fetch additional information from the web
-    3. Synthesize findings into a comprehensive report
-
-    Use the available tools to gather information before responding.
+    You are a thorough researcher. Search knowledge bases,
+    fetch web information, and synthesize findings.
   inputVariables:
     - topic
     - context
@@ -424,116 +177,45 @@ tools:
 output:
   format: text
 
-metadata:
-  category: research
-  tags: [research, web, knowledge]
-```
+maxIterations: 50          # Override default iteration limit (optional)
+memory: true               # Enable persistent memory (optional)
+skills:                    # Skills to attach (optional)
+  - skill-name
+publish: true              # Standalone chat at /chat/researcher (optional)
+```
+
+### Agent Schema Reference
+
+| Field | Description |
+|-------|-------------|
+| `name` | Unique identifier (required) |
+| `description` | Human-readable description (required) |
+| `version` | Semantic version (default: "1.0.0") |
+| `llm` | LLM config reference — string or `{ name, temperature }` |
+| `prompt.system` | System message/instructions |
+| `prompt.inputVariables` | Variables to interpolate in the prompt |
+| `tools` | Tool references: `mcp:`, `knowledge:`, `function:`, `builtin:`, `sandbox:`, `project:` |
+| `output.format` | `text` or `structured` |
+| `output.schema` | JSON Schema (required when format is `structured`) |
+| `maxIterations` | Override default 200 iteration limit |
+| `skills` | Skills to attach (list or `{ mode: all }`) |
+| `memory` | Enable persistent memory |
+| `integrations` | External integrations (collabnook, email) |
+| `triggers` | Cron or webhook triggers |
+| `publish` | Standalone chat page (`true` or `{ enabled, password }`) |
 
 ### Conversation Memory
 
-Agent Orcha supports session-based conversation memory, allowing agents to maintain context across multiple interactions. This is useful for building chatbots, multi-turn dialogues, and stateful applications.
-
-**Features:**
-- In-memory session storage using LangChain messages
-- Automatic FIFO message limit (default: 50 messages per session)
-- Optional TTL-based session cleanup (default: 1 hour)
-- Backward compatible (sessionId is optional)
-
-**API Usage:**
-
-```bash
-# First message
-curl -X POST http://localhost:3000/api/agents/chatbot-memory/invoke \
-  -H "Content-Type: application/json" \
-  -d '{
-    "input": {"message": "My name is Alice"},
-    "sessionId": "user-123"
-  }'
-
-# Second message (agent remembers the name)
-curl -X POST http://localhost:3000/api/agents/chatbot-memory/invoke \
-  -H "Content-Type: application/json" \
-  -d '{
-    "input": {"message": "What is my name?"},
-    "sessionId": "user-123"
-  }'
-```
-
-**Library Usage:**
+Pass a `sessionId` to maintain context across interactions:
 
 ```typescript
-// Run agent with conversation memory
-const result1 = await orchestrator.runAgent(
-  'chatbot-memory',
-  { message: 'My name is Alice' },
-  'user-123'  // sessionId
-);
-
-const result2 = await orchestrator.runAgent(
-  'chatbot-memory',
-  { message: 'What is my name?' },
-  'user-123'  // Same sessionId maintains context
-);
-```
-
-**Session Management API:**
-
-```bash
-# Get session stats
-curl http://localhost:3000/api/agents/sessions/stats
-
-# Get session info
-curl http://localhost:3000/api/agents/sessions/user-123
-
-# Clear session
-curl -X DELETE http://localhost:3000/api/agents/sessions/user-123
-```
-
-**Memory Management (Programmatic):**
-
-```typescript
-// Access memory store
-const memory = orchestrator.memory;
-
-// Check if session exists
-const hasSession = memory.hasSession('user-123');
-
-// Get message count
-const count = memory.getMessageCount('user-123');
-
-// Clear a session
-memory.clearSession('user-123');
-
-// Get total sessions
-const totalSessions = memory.getSessionCount();
+const result = await orchestrator.runAgent('chatbot', { message: 'My name is Alice' }, 'session-123');
+const result2 = await orchestrator.runAgent('chatbot', { message: 'What is my name?' }, 'session-123');
 ```
 
 ### Structured Output
 
-Agents can return validated, structured JSON output by specifying an `output.schema` configuration. This leverages LangChain's `withStructuredOutput()` to ensure responses match your desired format.
-
-**Features:**
-- JSON Schema-based output validation
-- Type-safe structured responses
-- Automatic schema enforcement via LLM
-- Validation metadata in response
-
-**Example Agent Configuration:**
-
 ```yaml
-# agents/sentiment-structured.agent.yaml
-
-name: sentiment-structured
-description: Sentiment analysis with structured output
-llm:
-  name: default
-  temperature: 0
-prompt:
-  system: |
-    Analyze the sentiment of the provided text and return a structured response.
-    Provide both the sentiment category and a confidence score.
-  inputVariables:
-    - text
 output:
   format: structured
   schema:
@@ -542,249 +224,52 @@ output:
       sentiment:
         type: string
         enum: [positive, negative, neutral]
-        description: The overall sentiment
       confidence:
         type: number
-        minimum: 0
-        maximum: 1
-        description: Confidence score
-      keywords:
-        type: array
-        items:
-          type: string
-        description: Key sentiment-driving words
-    required:
-      - sentiment
-      - confidence
-```
-
-**API Usage:**
-
-```bash
-curl -X POST http://localhost:3000/api/agents/sentiment-structured/invoke \
-  -H "Content-Type: application/json" \
-  -d '{
-    "input": {"text": "I love this product! It works great!"}
-  }'
-```
-
-**Response:**
-
-```json
-{
-  "output": {
-    "sentiment": "positive",
-    "confidence": 0.95,
-    "keywords": ["love", "great"]
-  },
-  "metadata": {
-    "duration": 1234,
-    "structuredOutputValid": true
-  }
-}
-```
-
-**Library Usage:**
-
-```typescript
-const result = await orchestrator.runAgent('sentiment-structured', {
-  text: 'This is amazing!'
-});
-
-// result.output is a typed object
-console.log(result.output.sentiment); // "positive"
-console.log(result.output.confidence); // 0.95
-console.log(result.metadata.structuredOutputValid); // true
+    required: [sentiment, confidence]
 ```
 
 ## Workflows
 
-Workflows orchestrate multiple agents in a defined sequence. Define workflows in YAML files within the `workflows/` directory. Agent Orcha supports two workflow types: **step-based** and **LangGraph**.
-
-### Step-Based Workflows
-
-Traditional sequential/parallel agent orchestration with explicit step definitions.
-
-#### Workflow Schema
-
-```yaml
-# workflows/<name>.workflow.yaml
-
-name: string                    # Unique identifier (required)
-description: string             # Human-readable description (required)
-version: string                 # Semantic version (default: "1.0.0")
-type: steps                     # Optional (steps is default)
+Workflows orchestrate multiple agents. Two types: **step-based** and **ReAct**.
 
-input:                          # Input schema (required)
-  schema:
-    <field_name>:
-      type: string | number | boolean | array | object
-      required: boolean         # (default: false)
-      default: any              # Default value
-      description: string       # Field description
-
-steps:                          # Workflow steps (required)
-  - id: string                  # Unique step identifier
-    agent: string               # Agent name to execute
-    input:                      # Input mapping using templates
-      <key>: "{{input.field}}"           # From workflow input
-      <key>: "{{steps.stepId.output}}"   # From previous step
-    condition: string           # Optional conditional execution
-    retry:                      # Optional retry configuration
-      maxAttempts: number
-      delay: number             # Milliseconds
-    output:
-      key: string               # Store output under this key
-
-  # Parallel execution
-  - parallel:
-      - id: step1
-        agent: agent1
-        input: {...}
-      - id: step2
-        agent: agent2
-        input: {...}
-
-config:                         # Workflow configuration (optional)
-  timeout: number               # Total timeout ms (default: 300000)
-  onError: stop | continue | retry
-
-output:                         # Output mapping (required)
-  <key>: "{{steps.stepId.output}}"
-
-metadata:                       # Custom metadata (optional)
-  category: string
-  tags: [string]
-```
-
-#### Template Syntax
-
-Access data within workflows using double curly braces:
+### Step-Based
 
-| Template | Description |
-|----------|-------------|
-| `{{input.fieldName}}` | Access workflow input field |
-| `{{steps.stepId.output}}` | Access step output |
-| `{{steps.stepId.output.nested.path}}` | Access nested output |
-| `{{steps.stepId.metadata.duration}}` | Access step metadata |
-
-#### Example Workflow
+Sequential/parallel agent orchestration with explicit step definitions.
 
 ```yaml
-# workflows/research-paper.workflow.yaml
-
 name: research-paper
-description: Research a topic and write a comprehensive paper
-version: "1.0.0"
+description: Research a topic and write a paper
+type: steps
 
 input:
   schema:
     topic:
       type: string
       required: true
-      description: The topic to research
-    style:
-      type: string
-      default: "professional"
 
 steps:
   - id: research
     agent: researcher
     input:
       topic: "{{input.topic}}"
-      context: "Gather comprehensive information"
-    output:
-      key: researchFindings
-
-  - id: summarize
-    agent: summarizer
-    input:
-      content: "{{steps.research.output}}"
-      maxPoints: "10"
-    condition: "{{steps.research.metadata.success}}"
-    output:
-      key: summary
 
   - id: write
     agent: writer
     input:
       research: "{{steps.research.output}}"
-      outline: "{{steps.summarize.output}}"
-      style: "{{input.style}}"
-    output:
-      key: paper
-
-config:
-  timeout: 600000
-  onError: stop
 
 output:
   paper: "{{steps.write.output}}"
-  summary: "{{steps.summarize.output}}"
-  researchFindings: "{{steps.research.output}}"
-```
-
-### LangGraph Workflows
-
-Autonomous, prompt-driven workflows using LangGraph. The agent decides which tools and agents to call based on the system prompt, without explicit step definitions.
-
-#### LangGraph Schema
-
-```yaml
-# workflows/<name>.workflow.yaml
-
-name: string                    # Unique identifier (required)
-description: string             # Human-readable description (required)
-version: string                 # Semantic version (default: "1.0.0")
-type: langgraph                 # Required for LangGraph workflows
-
-input:                          # Input schema (required)
-  schema:
-    <field_name>:
-      type: string | number | boolean | array | object
-      required: boolean
-      description: string
-
-prompt:                         # Prompt configuration (required)
-  system: string                # System message with instructions
-  goal: string                  # Goal template (supports {{input.*}} interpolation)
-
-graph:                          # LangGraph configuration (required)
-  model: string                 # LLM config name from llm.json
-  executionMode: react | single-turn  # Default: react
-  tools:                        # Tool discovery
-    mode: all | include | exclude | none
-    sources: [mcp, knowledge, function, builtin]
-    include: [string]           # For mode: include
-    exclude: [string]           # For mode: exclude
-  agents:                       # Agent discovery
-    mode: all | include | exclude | none
-    include: [string]
-    exclude: [string]
-  maxIterations: number         # Default: 10
-  timeout: number               # Default: 300000
-
-output:                         # Output extraction
-  <key>: "{{state.messages[-1].content}}"
-
-config:                         # Optional
-  onError: stop | continue | retry
 ```
 
-#### Execution Modes
-
-| Mode | Behavior | Best For |
-|------|----------|----------|
-| `single-turn` | Calls tools once, then returns | Research, data gathering, straightforward tasks |
-| `react` | Multiple rounds of tool calls with analysis | Complex problems, iterative refinement |
+### ReAct
 
-#### Example LangGraph Workflow
+Autonomous, prompt-driven workflows. The agent decides which tools and agents to call.
 
 ```yaml
-name: langgraph-research
-description: Autonomous research using tool discovery
-version: "1.0.0"
-type: langgraph
+name: react-research
+type: react
 
 input:
   schema:
@@ -796,21 +281,17 @@ prompt:
   system: |
     You are a research assistant with access to tools and agents.
     Identify all tools you need, call them in parallel, then synthesize results.
-
-    If the user hasn't provided required information, use the ask_user tool
-    to request it before proceeding.
   goal: "Research and analyze: {{input.topic}}"
 
 graph:
   model: default
-  executionMode: single-turn
+  executionMode: single-turn    # or: react (multi-round)
   tools:
     mode: all
     sources: [mcp, knowledge, function, builtin]
   agents:
     mode: all
   maxIterations: 10
-  timeout: 300000
 
 output:
   analysis: "{{state.messages[-1].content}}"
@@ -818,63 +299,16 @@ output:
 
 ## Knowledge Stores
 
-Knowledge stores enable semantic search and RAG capabilities. Define knowledge stores in YAML files within the `knowledge/` directory. Two kinds are supported: **vector** (default) and **graph-rag**.
-
-### Vector Knowledge Stores
-
-Traditional vector stores with embeddings for semantic search.
-
-#### Vector Knowledge Schema
+Semantic search and RAG using **SQLite + sqlite-vec** — no external vector databases required. Define in the `knowledge/` directory.
 
 ```yaml
-# knowledge/<name>.knowledge.yaml
-
-name: string                    # Unique identifier (required)
-description: string             # Human-readable description (required)
-kind: vector                    # Optional (vector is default)
-
-source:                         # Data source (required)
-  type: directory | file | database | web | s3
-  # See "Data Source Types" below for type-specific fields
-
-loader:                         # Document loader (required)
-  type: text | pdf | csv | json | markdown
-
-splitter:                       # Text chunking (required)
-  type: character | recursive | token | markdown
-  chunkSize: number             # Characters per chunk (default: 1000)
-  chunkOverlap: number          # Overlap between chunks (default: 200)
-
-embedding: string               # Reference to embedding config in llm.json (default: "default")
-
-store:                          # Vector store backend (required)
-  type: memory | chroma | pinecone | qdrant
-  options:                      # Store-specific options (optional)
-    path: string                # Storage path (for chroma)
-    collectionName: string      # Collection name (for chroma)
-    url: string                 # Server URL (for chroma, qdrant)
-
-search:                         # Search configuration (optional)
-  defaultK: number              # Results per search (default: 4)
-  scoreThreshold: number        # Minimum similarity (0-1)
-```
-
-#### Example Vector Knowledge Store
-
-```yaml
-# knowledge/transcripts.knowledge.yaml
-
 name: transcripts
-description: Meeting transcripts for context retrieval
-
+description: Meeting transcripts
 source:
   type: directory
   path: knowledge/sample-data
   pattern: "*.txt"
 
-loader:
-  type: text
-
 splitter:
   type: character
   chunkSize: 1000
@@ -882,388 +316,67 @@ splitter:
 
 embedding: default
 
-store:
-  type: memory
-
 search:
   defaultK: 4
   scoreThreshold: 0.2
 ```
 
-**Note:** Knowledge stores are initialized on startup, loading documents and creating embeddings immediately.
+### Data Sources
 
-### GraphRAG Knowledge Stores
+- **directory/file** — Local files with glob patterns
+- **database** — PostgreSQL/MySQL via SQL queries
+- **web** — HTML scraping, JSON APIs (with `jsonPath`), raw text
 
-GraphRAG extracts entities and relationships from documents, builds a knowledge graph, detects communities, and enables both entity-level and thematic search.
+### Knowledge Graph (Direct Mapping)
 
-#### GraphRAG Schema
+Add `graph.directMapping` to build entity graphs from structured data:
 
 ```yaml
-# knowledge/<name>.knowledge.yaml
-
-name: string                    # Unique identifier (required)
-kind: graph-rag                 # Required for GraphRAG
-description: string             # Human-readable description (required)
-
-source:                         # Same source types as vector
-  type: directory | file | database | web | s3
-
-loader:
-  type: text | pdf | csv | json | markdown
-
-splitter:
-  type: character | recursive | token | markdown
-  chunkSize: number
-  chunkOverlap: number
-
-embedding: string               # Embedding config from llm.json
-
-graph:                          # Graph configuration (required)
-  extraction:                   # Entity extraction
-    llm: string                 # LLM from llm.json (default: "default")
-    entityTypes:                # Optional schema (omit for auto-extraction)
-      - name: string
-        description: string
-    relationshipTypes:          # Optional schema
-      - name: string
-        description: string
-
-  communities:                  # Community detection
-    algorithm: louvain          # Currently only supported algorithm
-    resolution: number          # Louvain resolution (default: 1.0)
-    minSize: number             # Minimum community size (default: 2)
-    summaryLlm: string          # LLM for summaries (default: "default")
-
-  store:                        # Graph store backend
-    type: memory | neo4j        # Default: memory
-    options: {}
-
-  cache:                        # Graph cache
-    enabled: boolean            # Default: true
-    directory: string           # Default: ".graph-cache"
-
-search:                         # Search configuration
-  defaultK: number              # Results per search (default: 10)
-  localSearch:                  # Entity neighborhood search
-    maxDepth: number            # Traversal depth (default: 2)
-  globalSearch:                 # Community-level search
-    topCommunities: number      # Communities to consider (default: 5)
-    llm: string                 # LLM for synthesis (default: "default")
-```
-
-#### Example GraphRAG Knowledge Store
-
-```yaml
-# knowledge/call-center.knowledge.yaml
-
-name: call-center-analysis
-kind: graph-rag
-description: GraphRAG for analyzing call center transcripts
-
-source:
-  type: directory
-  path: knowledge/transcripts
-  pattern: "*.txt"
-
-loader:
-  type: text
-
-splitter:
-  type: recursive
-  chunkSize: 2000
-  chunkOverlap: 200
-
-embedding: default
-
 graph:
-  extraction:
-    llm: default
-    entityTypes:
-      - name: Agent
-        description: "Call center representative"
-      - name: Customer
-        description: "Person calling"
-      - name: Vehicle
-        description: "Car discussed"
-      - name: Outcome
-        description: "Result of the call"
-    relationshipTypes:
-      - name: HANDLED_BY
-        description: "Call was handled by an agent"
-      - name: INTERESTED_IN
-        description: "Customer interest in vehicle"
-      - name: RESULTED_IN
-        description: "Call resulted in outcome"
-
-  communities:
-    algorithm: louvain
-    resolution: 1.0
-    minSize: 2
-    summaryLlm: default
-
-  store:
-    type: memory
-
-  cache:
-    enabled: true
-    directory: .graph-cache
-
-search:
-  defaultK: 10
-  localSearch:
-    maxDepth: 2
-  globalSearch:
-    topCommunities: 5
-    llm: default
-```
-
-### Data Source Types
-
-Agent Orcha supports multiple data source types for knowledge stores:
-
-#### Directory/File Sources
-Load documents from local files or directories:
-```yaml
-source:
-  type: directory
-  path: knowledge/sample-data
-  pattern: "*.txt"
-  recursive: true
-```
-
-#### Database Sources
-Load documents from PostgreSQL or MySQL databases:
-```yaml
-source:
-  type: database
-  connectionString: postgresql://user:password@localhost:5432/docs_db
-  query: SELECT content, title, category FROM documents WHERE published = true
-  contentColumn: content
-  metadataColumns:
-    - title
-    - category
-  batchSize: 100
-```
-
-See `templates/knowledge/postgres-docs.knowledge.yaml` and `templates/knowledge/mysql-docs.knowledge.yaml` for complete examples.
-
-#### Web Scraping Sources
-Load documents from websites using CSS selectors:
-```yaml
-source:
-  type: web
-  url: https://docs.example.com/guide/
-  selector: article.documentation  # CSS selector for targeted extraction
-```
-
-See `templates/knowledge/web-docs.knowledge.yaml` for a complete example.
-
-#### S3 Sources
-Load documents from AWS S3 or S3-compatible services (MinIO, Wasabi, etc.):
-```yaml
-source:
-  type: s3
-  bucket: my-knowledge-base
-  prefix: documentation/
-  region: us-east-1
-  pattern: "*.{pdf,txt,md}"
-  # Optional for S3-compatible services:
-  endpoint: http://localhost:9000  # For MinIO, Wasabi, etc.
-  forcePathStyle: true             # Required for MinIO and some S3-compatible services
-```
-
-See `templates/knowledge/s3-pdfs.knowledge.yaml` and `templates/knowledge/s3-minio.knowledge.yaml` for complete examples.
-
-### Store Types
-
-#### Memory (Development)
-In-memory storage. Fast but not persistent - embeddings are recreated on every startup.
-
-```yaml
-store:
-  type: memory
-```
-
-**Use cases:** Development, testing, small datasets
-
-#### Chroma (Production - Local)
-Persistent local storage using Chroma. Embeddings are cached and reused across restarts.
-
-```yaml
-store:
-  type: chroma
-  options:
-    path: .chroma                    # Storage directory (default: .chroma)
-    collectionName: my-collection    # Collection name (default: store name)
-    url: http://localhost:8000       # Chroma server URL (default: http://localhost:8000)
-```
-
-**Setup:**
-```bash
-# Option 1: Run Chroma server with Docker
-docker run -p 8000:8000 chromadb/chroma
-
-# Option 2: Install and run Chroma locally
-pip install chromadb
-chroma run --path .chroma --port 8000
-```
-
+  directMapping:
+    entities:
+      - type: Post
+        idColumn: id
+        nameColumn: title
+        properties: [title, slug, content]
+      - type: Author
+        idColumn: author_email
+        nameColumn: author_name
+    relationships:
+      - type: WROTE
+        source: Author
+        target: Post
+        sourceIdColumn: author_email
+        targetIdColumn: id
+```
+
+Stores with entities get additional graph tools: `entity_lookup`, `traverse`, `graph_schema`, `sql`.
 
 ## Functions
 
-Functions are custom JavaScript tools that extend agent capabilities with your own code. They're simple to create and require no dependencies.
-
-### Function Schema
-
-Create a file in `functions/` ending with `.function.js`:
-
-```javascript
-/**
- * Function description
- */
-export default {
-  name: 'function-name',           // Unique identifier (required)
-  description: 'What it does',     // Clear description (required)
-
-  parameters: {                    // Input parameters (required)
-    param1: {
-      type: 'number',              // string | number | boolean | array | object | enum
-      description: 'Parameter description',
-      required: true,              // Optional, defaults to true
-      default: 0,                  // Optional default value
-    },
-  },
-
-  execute: async ({ param1 }) => { // Execution function (required)
-    // Your logic here
-    return `Result: ${param1}`;
-  },
-};
-
-// Optional metadata for documentation
-export const metadata = {
-  name: 'function-name',
-  version: '1.0.0',
-  author: 'Your Name',
-  tags: ['category'],
-};
-```
-
-### Example Function
+Custom JavaScript tools in `functions/`:
 
 ```javascript
 // functions/fibonacci.function.js
-
 export default {
   name: 'fibonacci',
-  description: 'Returns the nth Fibonacci number (0-based indexing)',
-
+  description: 'Returns the nth Fibonacci number',
   parameters: {
-    n: {
-      type: 'number',
-      description: 'The index (0-based, max 100)',
-    },
+    n: { type: 'number', description: 'The index (0-based, max 100)' },
   },
-
   execute: async ({ n }) => {
-    if (n < 0 || !Number.isInteger(n)) {
-      throw new Error('Index must be a non-negative integer');
-    }
-    if (n > 100) {
-      throw new Error('Index too large (max 100)');
-    }
-
-    if (n === 0) return 'Fibonacci(0) = 0';
-    if (n === 1) return 'Fibonacci(1) = 1';
-
     let prev = 0, curr = 1;
-    for (let i = 2; i <= n; i++) {
-      [prev, curr] = [curr, prev + curr];
-    }
-
-    return `Fibonacci(${n}) = ${curr}`;
+    for (let i = 2; i <= n; i++) [prev, curr] = [curr, prev + curr];
+    return `Fibonacci(${n}) = ${n < 2 ? n : curr}`;
   },
 };
 ```
 
-### Using Functions in Agents
-
-Reference functions in your agent's tools list with the `function:` prefix:
-
-```yaml
-name: math-assistant
-description: Assistant that can calculate Fibonacci numbers
-
-llm:
-  name: default
-  temperature: 0.3
-
-prompt:
-  system: |
-    You are a math assistant. Use the fibonacci tool to calculate
-    Fibonacci numbers when asked.
-  inputVariables:
-    - query
-
-tools:
-  - function:fibonacci    # References fibonacci.function.js
-
-output:
-  format: text
-```
-
-### Parameter Types
-
-- **string**: Text value
-- **number**: Numeric value
-- **boolean**: true/false
-- **array**: Array of values
-- **object**: JSON object
-- **enum**: One of a fixed set (requires `values` array)
-
-Example enum parameter:
-```javascript
-parameters: {
-  operation: {
-    type: 'enum',
-    values: ['add', 'subtract', 'multiply', 'divide'],
-    description: 'Math operation to perform',
-  },
-}
-```
+Reference in agents with `function:fibonacci`.
 
 ## MCP Servers
 
-Model Context Protocol (MCP) servers provide external tools to agents. Configure MCP servers in `mcp.json` at the project root.
-
-### MCP Configuration
-
-```json
-{
-  "version": "1.0.0",
-  "servers": {
-    "<server-name>": {
-      "transport": "streamable-http | stdio | sse | sse-only",
-      "url": "https://server-url/mcp",
-      "command": "node",
-      "args": ["./mcp-server.js"],
-      "env": { "KEY": "VALUE" },
-      "headers": { "Authorization": "Bearer TOKEN" },
-      "timeout": 30000,
-      "enabled": true,
-      "description": "Server description"
-    }
-  },
-  "globalOptions": {
-    "throwOnLoadError": false,
-    "prefixToolNameWithServerName": true,
-    "additionalToolNamePrefix": "",
-    "defaultToolTimeout": 30000
-  }
-}
-```
-
-### Example MCP Configuration
+Configure in `mcp.json`:
 
 ```json
 {
@@ -1271,312 +384,92 @@ Model Context Protocol (MCP) servers provide external tools to agents. Configure
   "servers": {
     "fetch": {
       "transport": "streamable-http",
-      "url": "https://remote.mcpservers.org/fetch/mcp",
-      "description": "Web fetch capabilities",
-      "timeout": 30000,
-      "enabled": true
+      "url": "https://remote.mcpservers.org/fetch/mcp"
     },
     "filesystem": {
       "transport": "stdio",
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
-      "description": "File system access"
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
     }
   }
 }
 ```
 
-Reference MCP tools in agents:
-```yaml
-tools:
-  - mcp:fetch    # All tools from "fetch" server
-```
-
-## Agent Orcha Studio
-
-Agent Orcha includes a built-in web dashboard accessible at `http://localhost:3000` when the server is running. The Studio provides a visual interface for managing and testing your entire Agent Orcha instance.
-
-### Tabs
-
-- **Agents**: Browse all configured agents, invoke them with custom input, stream responses in real-time, and manage conversation sessions
-- **Knowledge**: Browse and search knowledge stores (both vector and GraphRAG), view entities and communities for GraphRAG stores
-- **MCP**: Browse MCP servers, view available tools per server, and call tools directly
-- **Workflows**: Browse and execute workflows (both step-based and LangGraph), stream execution progress
-- **IDE**: Full in-browser file editor with file tree navigation, syntax highlighting for YAML, JSON, and JavaScript, and hot-reload on save
-
-## API Reference
-
-### Health Check
-
-```
-GET /health
-Response: { "status": "ok", "timestamp": "..." }
-```
-
-### Agents
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/agents` | List all agents |
-| GET | `/api/agents/:name` | Get agent details |
-| POST | `/api/agents/:name/invoke` | Run agent |
-| POST | `/api/agents/:name/stream` | Stream agent response (SSE) |
-| GET | `/api/agents/sessions/stats` | Get session statistics |
-| GET | `/api/agents/sessions/:sessionId` | Get session details |
-| DELETE | `/api/agents/sessions/:sessionId` | Clear session messages |
-
-**Invoke Request:**
-```json
-{
-  "input": {
-    "topic": "your topic",
-    "context": "additional context"
-  },
-  "sessionId": "optional-session-id"
-}
-```
-
-**Response:**
-```json
-{
-  "output": "Agent response text",
-  "metadata": {
-    "tokensUsed": 150,
-    "toolCalls": [],
-    "duration": 1234,
-    "sessionId": "optional-session-id",
-    "messagesInSession": 4,
-    "structuredOutputValid": true
-  }
-}
-```
-
-### Workflows
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/workflows` | List all workflows |
-| GET | `/api/workflows/:name` | Get workflow details |
-| POST | `/api/workflows/:name/run` | Execute workflow |
-| POST | `/api/workflows/:name/stream` | Stream workflow execution (SSE) |
-
-**Run Request:**
-```json
-{
-  "input": {
-    "topic": "research topic",
-    "style": "professional"
-  }
-}
-```
-
-**Response:**
-```json
-{
-  "output": {
-    "paper": "Final content",
-    "summary": "Key points"
-  },
-  "metadata": {
-    "duration": 5000,
-    "stepsExecuted": 3,
-    "success": true
-  },
-  "stepResults": {
-    "research": { "output": "...", "metadata": {} },
-    "summarize": { "output": "...", "metadata": {} }
-  }
-}
-```
-
-### Knowledge Stores
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/knowledge` | List all knowledge stores |
-| GET | `/api/knowledge/:name` | Get knowledge store config |
-| POST | `/api/knowledge/:name/search` | Search knowledge store |
-| POST | `/api/knowledge/:name/refresh` | Reload documents |
-| POST | `/api/knowledge/:name/add` | Add documents |
-| GET | `/api/knowledge/:name/entities` | Get GraphRAG entities |
-| GET | `/api/knowledge/:name/communities` | Get GraphRAG communities |
-| GET | `/api/knowledge/:name/edges` | Get GraphRAG edges |
+Reference in agents with `mcp:fetch`.
 
-**Search Request:**
-```json
-{
-  "query": "search term",
-  "k": 4
-}
-```
-
-### LLM
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/llm` | List all LLM configurations |
-| GET | `/api/llm/:name` | Get LLM config details |
-| POST | `/api/llm/:name/chat` | Chat with LLM (non-streaming) |
-| POST | `/api/llm/:name/stream` | Chat with LLM (SSE streaming) |
-
-**Chat Request:**
-```json
-{
-  "message": "Your message"
-}
-```
-
-### Functions
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/functions` | List all functions |
-| GET | `/api/functions/:name` | Get function details and schema |
-| POST | `/api/functions/:name/call` | Call a function |
-
-**Call Request:**
-```json
-{
-  "arguments": {
-    "a": 5,
-    "b": 3,
-    "operation": "add"
-  }
-}
-```
-
-### MCP
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/mcp` | List all MCP servers |
-| GET | `/api/mcp/:name` | Get MCP server config |
-| GET | `/api/mcp/:name/tools` | List tools from server |
-| POST | `/api/mcp/:name/call` | Call a tool on server |
-
-**Call Tool Request:**
-```json
-{
-  "tool": "tool-name",
-  "arguments": { "url": "https://example.com" }
-}
-```
-
-### Files
+## Tool Types
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/files/tree` | Get project directory tree |
-| GET | `/api/files/read?path=...` | Read file contents |
-| PUT | `/api/files/write` | Write file contents |
-
-**Write File Request:**
-```json
-{
-  "path": "agents/new-agent.agent.yaml",
-  "content": "name: new-agent\n..."
-}
-```
+| Prefix | Description |
+|--------|-------------|
+| `mcp:<server>` | External tools from MCP servers |
+| `knowledge:<store>` | Semantic search on knowledge stores |
+| `function:<name>` | Custom JavaScript functions |
+| `builtin:<name>` | Framework tools (`ask_user`, `memory_save`) |
+| `sandbox:exec` | JavaScript execution in sandboxed VM |
+| `sandbox:shell` | Shell commands (non-root sandbox user) |
+| `sandbox:web_fetch` | URL fetching with SSRF protection |
+| `sandbox:web_search` | Web search |
+| `sandbox:browser_*` | CDP-based Chromium control (navigate, observe, click, type, screenshot, evaluate) |
+| `sandbox:file_*` | Sandboxed file tools (read, write, edit, insert, replace_lines) scoped to `/tmp` |
+| `project:read/write/delete` | Workspace file access |
+
+### Vision Browser (Experimental)
+
+Pixel-coordinate browser control for vision LLMs. Enable with `EXPERIMENTAL_VISION=true`:
+
+| Tool | Description |
+|------|-------------|
+| `sandbox_vision_screenshot` | Capture JPEG screenshot |
+| `sandbox_vision_navigate` | Navigate to URL |
+| `sandbox_vision_click` | Click at x,y coordinates |
+| `sandbox_vision_type` | Type text |
+| `sandbox_vision_scroll` | Scroll page |
+| `sandbox_vision_key` | Press keyboard key |
+| `sandbox_vision_drag` | Drag between coordinates |
+
+Every action tool auto-captures a screenshot, cutting the screenshot-infer-act loop to one call per action.
+
+## API
+
+Full API documentation is available at [agentorcha.com](https://agentorcha.com). Key endpoint groups:
+
+| Group | Base Path | Description |
+|-------|-----------|-------------|
+| Health | `GET /health` | Health check |
+| Auth | `/api/auth/*` | Login, logout, session check |
+| Agents | `/api/agents/*` | List, invoke, stream, session management |
+| Chat | `/api/chat/*` | Published agent standalone chat |
+| Workflows | `/api/workflows/*` | List, run, stream |
+| Knowledge | `/api/knowledge/*` | List, search, refresh, graph entities/edges |
+| LLM | `/api/llm/*` | List configs, chat, stream |
+| Functions | `/api/functions/*` | List, call |
+| MCP | `/api/mcp/*` | List servers, list tools, call tools |
+| Skills | `/api/skills/*` | List, inspect |
+| Tasks | `/api/tasks/*` | Submit, track, cancel |
+| Files | `/api/files/*` | File tree, read, write |
 
 ## Directory Structure
 
 ```
 my-project/
-├── agents/                     # Agent definitions (YAML)
-├── workflows/                  # Workflow definitions (YAML)
-├── knowledge/                  # Knowledge store configs and data
-├── functions/                  # Custom function tools (JavaScript)
-├── public/                     # Web UI (Studio)
-│
-├── llm.json                    # LLM and embedding configurations
-├── mcp.json                    # MCP server configuration
-└── .env                        # Environment variables
-```
-
-**Framework source structure:**
-
-```
-agent-orcha/
-├── src/                        # Server/API code
-│   ├── index.ts                # Entry point
-│   ├── server.ts               # Fastify server setup
-│   ├── cli/                    # CLI commands
-│   └── routes/                 # API route handlers
-│       ├── agents.route.ts
-│       ├── workflows.route.ts
-│       ├── knowledge.route.ts
-│       ├── llm.route.ts
-│       ├── functions.route.ts
-│       ├── mcp.route.ts
-│       └── files.route.ts
-│
-├── lib/                        # Core library
-│   ├── orchestrator.ts         # Main orchestrator class
-│   ├── agents/                 # Agent system
-│   │   ├── types.ts
-│   │   ├── agent-loader.ts
-│   │   ├── agent-executor.ts
-│   │   └── structured-output-wrapper.ts
-│   ├── workflows/              # Workflow system
-│   │   ├── types.ts
-│   │   ├── workflow-loader.ts
-│   │   ├── workflow-executor.ts
-│   │   └── langgraph-executor.ts
-│   ├── knowledge/              # Knowledge store system
-│   │   ├── types.ts
-│   │   ├── knowledge-store-manager.ts
-│   │   └── graph-rag/
-│   │       └── types.ts
-│   ├── memory/                 # Conversation memory
-│   │   └── conversation-store.ts
-│   ├── llm/                    # LLM factory
-│   │   └── llm-factory.ts
-│   ├── mcp/                    # MCP client
-│   │   └── mcp-client.ts
-│   ├── functions/              # Function loader
-│   └── tools/                  # Tool registry and discovery
-│       ├── tool-registry.ts
-│       └── tool-discovery.ts
-│
-├── public/                     # Web UI (Studio)
-│   └── src/
-│       ├── components/         # Web components
-│       └── services/           # API client
-│
-├── templates/                  # Project initialization templates
-└── docs/                       # Documentation website
-```
-
-## Tool Types
-
-### Function Tools
-Custom JavaScript functions you create in the `functions/` directory:
-```yaml
-tools:
-  - function:fibonacci     # References fibonacci.function.js
-  - function:calculator
+├── agents/            # Agent definitions (YAML)
+├── workflows/         # Workflow definitions (YAML)
+├── knowledge/         # Knowledge store configs and data
+├── functions/         # Custom function tools (JavaScript)
+├── skills/            # Skill prompt files (Markdown)
+├── llm.json           # LLM and embedding configurations
+├── mcp.json           # MCP server configuration
+└── .env               # Environment variables
 ```
 
-### MCP Tools
-External tools from MCP servers:
-```yaml
-tools:
-  - mcp:fetch              # All tools from "fetch" server
-```
+## Development
 
-### Knowledge Tools
-Semantic search on knowledge stores:
-```yaml
-tools:
-  - knowledge:transcripts  # Search "transcripts" store
-  - knowledge:docs         # Search "docs" store
-```
-
-### Built-in Tools
-Framework-provided tools:
-```yaml
-tools:
-  - builtin:ask_user       # Human-in-the-loop (LangGraph only)
+```bash
+npm run dev          # Dev server with auto-reload
+npm run build        # Build
+npm start            # Run build
+npm run lint         # ESLint
+npm run typecheck    # TypeScript type checking
 ```
 
 ## License