teleton 0.5.1 → 0.6.0

package/README.md

@@ -1,27 +1,30 @@
 <h1 align="center">Teleton Agent</h1>
 
-<p align="center"><b>Autonomous AI agent for Telegram with native TON blockchain integration</b></p>
+<p align="center"><b>Autonomous AI agent platform for Telegram with native TON blockchain integration</b></p>
 
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen" alt="Node.js"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.7-blue" alt="TypeScript"></a>
   <a href="https://teletonagent.dev"><img src="https://img.shields.io/badge/Website-teletonagent.dev-ff6600" alt="Website"></a>
+  <a href="https://deepwiki.com/TONresistor/teleton-agent"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
 ---
 
-<p align="center">Teleton is a production-grade autonomous AI agent that operates as a real Telegram user account (not a bot), powered by multi-provider LLM support. It provides full access to the Telegram API with deep TON blockchain integration for cryptocurrency operations, DEX trading, and decentralized finance.</p>
+<p align="center">Teleton is an autonomous AI agent platform that operates as a real Telegram user account (not a bot). It thinks through an agentic loop with tool calling, remembers conversations across sessions with hybrid RAG, and can operate a TON wallet: send crypto, swap on DEXs, bid on domains, verify payments. All from a chat message. It ships with 114 built-in tools, supports 6 LLM providers, and exposes a Plugin SDK so you can build your own tools on top of the platform.</p>
 
-### Key Highlights
+	### Key Highlights
 
-- **Full Telegram access**: Operates as a real user with the full API, not a limited bot
-- **Multi-Provider LLM**: Anthropic, OpenAI, Google Gemini, xAI Grok, Groq, OpenRouter
-- **TON Blockchain**: Built-in wallet, send/receive TON & jettons, swap on STON.fi and DeDust, NFTs
-- **Persistent memory**: Remembers context across restarts with automatic context management
-- **112 built-in tools**: Messaging, media, blockchain, DEX trading, deals, DNS, journaling, and more
-- **Plugin SDK**: Extend the agent with custom tools — full access to TON and Telegram APIs via namespaced SDK
-- **Secure by design**: Sandboxed workspace, immutable config, prompt injection defense
+	- **Full Telegram access**: Operates as a real user via MTProto (GramJS), not a limited bot
+	- **Agentic loop**: Up to 5 iterations of tool calling per message — the agent thinks, acts, observes, and repeats
+	- **Multi-Provider LLM**: Anthropic, OpenAI, Google Gemini, xAI Grok, Groq, OpenRouter
+	- **TON Blockchain**: Built-in W5R1 wallet, send/receive TON & jettons, swap on STON.fi and DeDust, NFTs, DNS domains
+	- **Persistent memory**: Hybrid RAG (sqlite-vec + FTS5), auto-compaction with AI summarization, daily logs
+	- **114 built-in tools**: Messaging, media, blockchain, DEX trading, deals, DNS, journaling, and more
+	- **Plugin SDK**: Extend the agent with custom tools — frozen SDK with isolated databases, secrets management, lifecycle hooks
+	- **MCP Client**: Connect external tool servers (stdio/SSE) with 2 lines of YAML — no code, no rebuild
+	- **Secure by design**: Prompt injection defense, sandboxed workspace, plugin isolation, wallet encryption
 
 ---
 
@@ -29,33 +32,36 @@
 
 ### Tool Categories
 
-| Category | Tools | Description |
-|----------|-------|-------------|
-| Telegram | 66 | Messaging, media, chats, groups, polls, stickers, gifts, stars, stories, contacts, folders, profile, memory, tasks |
-| TON & Jettons | 15 | W5R1 wallet, send/receive TON & jettons, balances, prices, holders, history, charts, NFTs, DEX quotes |
-| STON.fi DEX | 5 | Swap, quote, search, trending tokens, liquidity pools |
-| DeDust DEX | 5 | Swap, quote, pools, prices, token info |
-| TON DNS | 7 | Domain auctions, bidding, linking, resolution, availability checks |
-| Deals | 5 | Secure gift/TON trading with strategy enforcement and inline bot confirmations |
-| Journal | 3 | Trade/operation logging with natural language queries |
-| Workspace | 6 | Sandboxed file operations with path traversal protection |
+| Category      | Tools | Description                                                                                                        |
+| ------------- | ----- | ------------------------------------------------------------------------------------------------------------------ |
+| Telegram      | 66    | Messaging, media, chats, groups, polls, stickers, gifts, stars, stories, contacts, folders, profile, memory, tasks |
+| TON & Jettons | 15    | W5R1 wallet, send/receive TON & jettons, balances, prices, holders, history, charts, NFTs, smart DEX router        |
+| STON.fi DEX   | 5     | Swap, quote, search, trending tokens, liquidity pools                                                              |
+| DeDust DEX    | 5     | Swap, quote, pools, prices, token analytics (holders, top traders, buy/sell tax)                                   |
+| TON DNS       | 7     | Domain auctions, bidding, linking/unlinking, resolution, availability checks                                       |
+| Deals         | 5     | P2P escrow with inline buttons, on-chain payment verification, anti double-spend                                   |
+| Journal       | 3     | Trade/operation logging with P&L tracking and natural language queries                                             |
+| Web           | 2     | Web search and page extraction via Tavily (search, fetch/extract)                                                  |
+| Workspace     | 6     | Sandboxed file operations with path traversal protection                                                           |
 
 ### Advanced Capabilities
 
-| Capability | Description |
-|-----------|-------------|
-| **Multi-Provider LLM** | Switch between Anthropic, OpenAI, Google, xAI, Groq, OpenRouter with one config change |
-| **RAG + Hybrid Search** | Local embeddings with FTS5 keyword + sqlite-vec semantic search |
-| **Auto-Compaction** | AI-summarized context management prevents overflow, preserves key information |
-| **Observation Masking** | Compresses old tool results to save ~90% context window |
-| **Plugin SDK** | Namespaced SDK (`sdk.ton`, `sdk.telegram`, `sdk.secrets`, `sdk.storage`) with 53 methods, isolated databases and lifecycle hooks |
-| **Vision Analysis** | Image understanding via multimodal LLM |
-| **Voice Synthesis** | Text-to-speech for voice messages |
-| **Scheduled Tasks** | Time-based task execution with dependency resolution |
-| **Message Debouncing** | Intelligent batching of rapid group messages |
-| **Daily Logs** | Automatic session summaries preserved across resets |
-| **Multi-Policy Access** | Configurable DM/group policies (open, allowlist, pairing, disabled) |
-| **Sandboxed Workspace** | Secure file system with path traversal protection and immutable config files |
+| Capability              | Description                                                                                                                 |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Multi-Provider LLM**  | Switch between Anthropic, OpenAI, Google, xAI, Groq, OpenRouter with one config change                                      |
+| **RAG + Hybrid Search** | Local ONNX embeddings (384d) or Voyage AI (512d/1024d) with FTS5 keyword + sqlite-vec cosine similarity, fused via RRF      |
+| **Auto-Compaction**     | AI-summarized context management prevents overflow, preserves key information in `memory/*.md` files                        |
+| **Observation Masking** | Compresses old tool results to one-line summaries, saving ~90% context window                                               |
+| **Plugin SDK**          | Frozen namespaced SDK (`sdk.ton`, `sdk.telegram`, `sdk.secrets`, `sdk.storage`) with isolated databases and lifecycle hooks |
+| **Smart DEX Router**    | `dex_quote` compares STON.fi vs DeDust in parallel, recommends the best rate                                                |
+| **Vision Analysis**     | Image understanding via multimodal LLM (utility model)                                                                      |
+| **Scheduled Tasks**     | Time-based task execution with DAG dependency resolution                                                                    |
+| **Message Debouncing**  | Intelligent batching of rapid group messages (DMs are always instant)                                                       |
+| **Daily Logs**          | Automatic session summaries preserved across resets                                                                         |
+| **Multi-Policy Access** | Configurable DM/group policies (open, allowlist, pairing, disabled) with per-group module permissions                       |
+| **Tool RAG**            | Semantic tool selection — sends only the top-K most relevant tools per message (hybrid vector + FTS5, configurable `top_k`, `always_include` patterns) |
+| **MCP Client**          | Connect external MCP tool servers (stdio or SSE) — auto-discovery, namespaced tools, managed via CLI or WebUI               |
+| **Sandboxed Workspace** | Secure file system with recursive URL decoding, symlink detection, and immutable config files                               |
 
 ---
 
@@ -66,7 +72,7 @@
 - **Telegram Account** - Dedicated account recommended for security
 - **Telegram API Credentials** - From [my.telegram.org/apps](https://my.telegram.org/apps)
 - **Your Telegram User ID** - Message [@userinfobot](https://t.me/userinfobot)
-- **Bot Token** *(optional)* - From [@BotFather](https://t.me/BotFather) for inline bot features
+- **Bot Token** *(optional)* - From [@BotFather](https://t.me/BotFather) for inline bot features (deals)
 
 > **Security Warning**: The agent will have full control over the Telegram account. Use a dedicated account, not your main one.
 
@@ -76,14 +82,9 @@
 
 ### 1. Installation
 
-**One-liner (recommended):**
+**npm (recommended):**
 ```bash
-curl -fsSL https://raw.githubusercontent.com/TONresistor/teleton-agent/main/install.sh | bash
-```
-
-**npm:**
-```bash
-npm install -g teleton
+npm install -g teleton@latest
 ```
 
 **Docker:**
@@ -110,12 +111,12 @@ The wizard will configure:
 - Access policies (DM/group response rules)
 - Admin user ID
 - TON wallet generation (W5R1 with 24-word mnemonic)
-- Workspace initialization (SOUL.md, IDENTITY.md, STRATEGY.md, SECURITY.md, USER.md, BOOTSTRAP.md, MEMORY.md)
+- Workspace initialization (SOUL.md, STRATEGY.md, SECURITY.md, MEMORY.md)
 
 Configuration files created:
 - `~/.teleton/config.yaml` - Main configuration
 - `~/.teleton/wallet.json` - TON wallet (backup mnemonic securely)
-- `~/.teleton/memory.db` - SQLite database
+- `~/.teleton/memory.db` - SQLite database (WAL mode, sqlite-vec, FTS5)
 - `~/.teleton/workspace/` - Sandboxed file storage
 
 ### 3. Start
@@ -151,7 +152,7 @@ agent:
   provider: "anthropic"              # anthropic | openai | google | xai | groq | openrouter
   api_key: "sk-ant-api03-..."
   model: "claude-opus-4-5-20251101"
-  utility_model: "claude-3-5-haiku-20241022"  # optional, for summarization
+  utility_model: "claude-3-5-haiku-20241022"  # for summarization, compaction, vision
   max_agentic_iterations: 5
 
 telegram:
@@ -161,14 +162,16 @@ telegram:
   admin_ids: [123456789]
   owner_name: "Your Name"
   owner_username: "your_username"
+  debounce_ms: 1500         # group message batching delay
 
-  # Optional: inline bot for interactive features
+  # Optional: inline bot for interactive features (deals)
   bot_token: "123456:ABC-DEF..."
   bot_username: "your_bot"
 
   session_reset_policy:
     daily_reset_enabled: true
     daily_reset_hour: 4
+    idle_expiry_minutes: 1440  # 24h idle → new session
 
 webui:                       # Optional: Web dashboard
   enabled: false             # Enable WebUI server
@@ -177,8 +180,86 @@ webui:                       # Optional: Web dashboard
   # auth_token: "..."        # Auto-generated if omitted
 ```
 
+### MCP Servers
+
+Connect external tool servers via the [Model Context Protocol](https://modelcontextprotocol.io/). No code needed — tools are auto-discovered and registered at startup.
+
+**Via CLI (recommended):**
+```bash
+teleton mcp add @modelcontextprotocol/server-filesystem /tmp
+teleton mcp add @openbnb/mcp-server-airbnb
+teleton mcp list
+teleton mcp remove filesystem
+```
+
+**Via config.yaml:**
+```yaml
+mcp:
+  servers:
+    filesystem:
+      command: npx -y @modelcontextprotocol/server-filesystem /tmp
+    brave:
+      command: npx -y @modelcontextprotocol/server-brave-search
+      env:
+        BRAVE_API_KEY: "sk-xxx"
+    remote:
+      url: http://localhost:3001/mcp
+      scope: admin-only
+```
+
+**Via WebUI:**
+
+When the WebUI is enabled, the **MCP Servers** page lets you add/remove servers, configure environment variables (API keys), and view connection status and tool lists — all from the browser.
+
+Tools are namespaced as `mcp_<server>_<tool>` (e.g. `mcp_filesystem_read_file`). Each server supports `scope` (always, dm-only, group-only, admin-only) and `enabled` toggle.
+
+### Web Search & Fetch
+
+The agent has two built-in web tools powered by [Tavily](https://tavily.com/) (free tier available):
+
+| Tool | Description |
+|------|-------------|
+| `web_search` | Search the web — returns titles, URLs, content snippets, relevance scores. Supports `topic`: general, news, finance |
+| `web_fetch` | Extract readable text from a URL — articles, docs, links shared by users |
+
+Both tools require a Tavily API key. Set it via CLI or config:
+
+```bash
+teleton config set tavily_api_key
+```
+
+Or in `config.yaml`:
+```yaml
+tavily_api_key: "tvly-..."
+```
+
+Once configured, the agent can autonomously search the web and read pages when needed to answer questions or verify information.
+
+### Managing Config Keys
+
+Use `teleton config` to manage optional keys without editing YAML manually:
+
+```bash
+# List all configurable keys and their status
+teleton config list
+
+# Set a key (prompts interactively if value omitted)
+teleton config set tavily_api_key
+teleton config set tonapi_key AFTWPHSLN3...
+
+# View a key (sensitive values are masked)
+teleton config get tavily_api_key
+
+# Remove a key
+teleton config unset tavily_api_key
+```
+
+Configurable keys: `tavily_api_key`, `tonapi_key`, `telegram.bot_token`, `telegram.bot_username`.
+
 ### Environment Variables
 
+All environment variables override the corresponding `config.yaml` value at startup — useful for Docker and CI:
+
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `TELETON_HOME` | Data directory (config, DB, session) | `~/.teleton` |
@@ -186,6 +267,8 @@ webui:                       # Optional: Web dashboard
 | `TELETON_TG_API_ID` | Telegram API ID (overrides config) | - |
 | `TELETON_TG_API_HASH` | Telegram API Hash (overrides config) | - |
 | `TELETON_TG_PHONE` | Phone number (overrides config) | - |
+| `TELETON_TAVILY_API_KEY` | Tavily API key for web search | - |
+| `TELETON_TONAPI_KEY` | TonAPI key for higher rate limits | - |
 | `TELETON_WEBUI_ENABLED` | Enable WebUI (overrides config) | `false` |
 | `TELETON_WEBUI_PORT` | WebUI port (overrides config) | `7777` |
 
@@ -197,12 +280,15 @@ Teleton includes an **optional web dashboard** for monitoring and configuration.
 
 ### Features
 
-- **Dashboard**: System status, uptime, model info, session count
-- **Tools Management**: View all 112+ tools grouped by module with scope badges
-- **Plugins Browser**: List loaded plugins with manifests
-- **Soul Editor**: Edit SOUL.md, SECURITY.md, STRATEGY.md, MEMORY.md files
+- **Dashboard**: System status, uptime, model info, session count, memory stats
+- **Tools Management**: View all tools grouped by module, toggle enable/disable, change scope per tool
+- **Plugin Marketplace**: Install, update, and manage plugins from registry with secrets management
+- **Soul Editor**: Edit SOUL.md, SECURITY.md, STRATEGY.md, MEMORY.md with unsaved changes warning
 - **Memory Search**: Search knowledge base with hybrid vector+keyword search
 - **Live Logs**: Real-time log streaming via Server-Sent Events
+- **Workspace**: File browser with inline text editor
+- **MCP Servers**: Add/remove external tool servers, manage API keys (env vars), view connection status
+- **Tasks**: Scheduled task management with status, dependencies, and bulk actions
 
 ### Usage
 
@@ -235,12 +321,13 @@ When WebUI is enabled, the agent will display:
 
 1. Click the URL (token is auto-filled) or visit `http://localhost:7777`
 2. Paste the token from the console (displayed once at startup)
-3. Token is stored in browser localStorage for subsequent visits
+3. Token is stored as HttpOnly cookie (7 days) for subsequent visits
 
 ### Security
 
 - **Localhost only**: Server binds to `127.0.0.1` by default (not accessible from network)
-- **Bearer token auth**: All API routes require authentication
+- **Bearer token auth**: All API routes require authentication (timing-safe comparison)
+- **HttpOnly cookies**: SameSite=Strict, prevents XSS token theft
 - **No persistence**: Runtime changes (like model switches via WebUI) are not saved to config.yaml
 - **For remote access**: Use SSH tunneling or reverse proxy (nginx/caddy) with HTTPS
 
@@ -257,22 +344,34 @@ The agent's personality and rules are configured via markdown files in `~/.telet
 | File | Purpose | Mutable by Agent |
 |------|---------|-----------------|
 | `SOUL.md` | Personality, tone, behavior guidelines | No |
-| `IDENTITY.md` | Agent name, bio, public-facing identity | No |
 | `STRATEGY.md` | Trading rules, buy/sell thresholds | No |
 | `SECURITY.md` | Security principles, threat recognition | No |
-| `USER.md` | Owner information and preferences | No |
-| `BOOTSTRAP.md` | First-run instructions (read once at startup) | No |
 | `MEMORY.md` | Persistent memory (facts, contacts, decisions) | Yes |
+| `memory/*.md` | Session summaries, daily logs (auto-generated) | Yes |
 
 > **Tip**: Templates are located in `src/templates/` if installing from source. Edit the workspace copies in `~/.teleton/workspace/` — not the source templates.
 
 ### Admin Commands
 
+All admin commands support `/`, `!`, or `.` prefix:
+
 | Command | Description |
 |---------|-------------|
+| `/status` | Uptime, model, sessions, wallet, policies |
+| `/model <name>` | Hot-swap LLM model at runtime |
+| `/policy <dm\|group> <value>` | Change access policies live |
+| `/loop <1-50>` | Set max agentic iterations |
+| `/strategy [buy\|sell <pct>]` | View/change trading thresholds |
+| `/wallet` | Show wallet address + balance |
+| `/modules set\|info\|reset` | Per-group tool permissions |
+| `/plugin set\|unset\|keys` | Manage plugin secrets |
 | `/task <description>` | Assign a task to the agent |
-| `/status` | View agent status |
+| `/boot` | Run bootstrap template |
+| `/pause` / `/resume` | Pause/resume agent |
 | `/clear [chat_id]` | Clear conversation history |
+| `/verbose` | Toggle debug logging |
+| `/rag [status\|topk <n>]` | Toggle Tool RAG or view status |
+| `/stop` | Emergency shutdown |
 | `/ping` | Check responsiveness |
 | `/help` | Show all commands |
 
@@ -286,29 +385,34 @@ The agent's personality and rules are configured via markdown files in `~/.telet
 |-------|------------|
 | LLM | Multi-provider via [pi-ai](https://github.com/mariozechner/pi-ai) (Anthropic, OpenAI, Google, xAI, Groq, OpenRouter) |
 | Telegram Userbot | [GramJS](https://gram.js.org/) (MTProto) |
-| Inline Bot | [Grammy](https://grammy.dev/) (Bot API) |
+| Inline Bot | [Grammy](https://grammy.dev/) (Bot API, for deals) |
 | Blockchain | [TON SDK](https://github.com/ton-org/ton) (W5R1 wallet) |
 | DeFi | STON.fi SDK, DeDust SDK |
 | Database | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) with WAL mode |
-| Vector Search | [sqlite-vec](https://github.com/asg017/sqlite-vec) (optional) |
+| Vector Search | [sqlite-vec](https://github.com/asg017/sqlite-vec) (cosine similarity) |
+| Full-Text Search | SQLite FTS5 (BM25 ranking) |
+| Embeddings | [@huggingface/transformers](https://www.npmjs.com/package/@huggingface/transformers) (local ONNX) or Voyage AI |
 | Token Counting | [js-tiktoken](https://github.com/dqbd/tiktoken) |
+| MCP Client | [@modelcontextprotocol/sdk](https://modelcontextprotocol.io/) (stdio + SSE transports) |
+| WebUI | [Hono](https://hono.dev/) (API) + React + Vite (frontend) |
 | Language | TypeScript 5.7, Node.js 20+ |
 
 ### Project Structure
 
 ```
 src/
-├── index.ts                # Entry point, lifecycle, module loading
+├── index.ts                # Entry point, TonnetApp lifecycle, graceful shutdown
 ├── agent/                  # Core agent runtime
-│   ├── runtime.ts          # Agentic loop orchestration
+│   ├── runtime.ts          # Agentic loop (5 iterations, tool calling, masking, compaction)
 │   ├── client.ts           # Multi-provider LLM client
-│   └── tools/              # 112 built-in tools
-│       ├── register-all.ts # Central tool registration
-│       ├── registry.ts     # Tool registry + scope filtering
-│       ├── module-loader.ts    # Built-in module loading (deals)
-│       ├── plugin-loader.ts    # External plugin discovery
+│   └── tools/              # 114 built-in tools
+│       ├── register-all.ts # Central tool registration (8 categories, 109 tools)
+│       ├── registry.ts     # Tool registry, scope filtering, provider limits
+│       ├── module-loader.ts    # Built-in module loading (deals → +5 tools)
+│       ├── plugin-loader.ts    # External plugin discovery, validation, hot-reload
+│       ├── mcp-loader.ts       # MCP client (stdio/SSE), tool discovery, lifecycle
 │       ├── telegram/       # Telegram operations (66 tools)
-│       ├── ton/            # TON blockchain + jettons + DEX quote (15 tools)
+│       ├── ton/            # TON blockchain + jettons + DEX router (15 tools)
 │       ├── stonfi/         # STON.fi DEX (5 tools)
 │       ├── dedust/         # DeDust DEX (5 tools)
 │       ├── dns/            # TON DNS (7 tools)
@@ -323,43 +427,51 @@ src/
 │   ├── gramjs-bot.ts       # GramJS MTProto for styled buttons
 │   └── services/           # Message builder, styled keyboard, verification
 ├── telegram/               # Telegram integration layer
-│   ├── bridge.ts           # GramJS wrapper (MTProto)
-│   ├── handlers.ts         # Message routing and processing
-│   ├── admin.ts            # Admin commands (/status, /clear, /modules)
+│   ├── bridge.ts           # GramJS wrapper (peer cache, message parsing, keyboards)
+│   ├── handlers.ts         # Message routing, rate limiting, ChatQueue, feed storage
+│   ├── admin.ts            # 17 admin commands
 │   ├── debounce.ts         # Message batching for groups
 │   ├── formatting.ts       # Markdown → Telegram HTML
+│   ├── task-executor.ts    # Scheduled task runner
+│   ├── task-dependency-resolver.ts  # DAG-based task chains
 │   └── callbacks/          # Inline button routing
 ├── memory/                 # Storage and knowledge
-│   ├── schema.ts           # Database schema + migrations
-│   ├── database.ts         # SQLite + WAL + vec0
-│   ├── search/             # RAG system (FTS5 + vector)
-│   ├── embeddings/         # Local + Anthropic embedding providers
-│   ├── compaction.ts       # Context auto-compaction
+│   ├── schema.ts           # 10 tables, 25 indexes, FTS5, vec0, semver migrations
+│   ├── database.ts         # SQLite + WAL + sqlite-vec
+│   ├── search/             # RAG system (hybrid vector + BM25 fusion via RRF)
+│   ├── embeddings/         # Local ONNX + Voyage AI + caching provider
+│   ├── compaction.ts       # Context auto-compaction with AI summarization
 │   ├── observation-masking.ts  # Tool result compression (~90% savings)
 │   └── daily-logs.ts       # Automatic session summaries
 ├── ton/                    # TON blockchain
-│   ├── wallet-service.ts   # W5R1 wallet + KeyPair cache
+│   ├── wallet-service.ts   # W5R1 wallet, PBKDF2 key caching, encrypted storage
 │   ├── transfer.ts         # TON send operations
-│   └── payment-verifier.ts # On-chain payment verification
+│   └── payment-verifier.ts # On-chain payment verification with replay protection
 ├── sdk/                    # Plugin SDK (v1.0.0)
-│   ├── index.ts            # SDK factory (createPluginSDK)
+│   ├── index.ts            # SDK factory (createPluginSDK, all objects frozen)
 │   ├── ton.ts              # TON service for plugins
 │   ├── telegram.ts         # Telegram service for plugins
-│   └── types.ts            # Public SDK types
+│   ├── secrets.ts          # 3-tier secret resolution (env → file → config)
+│   └── storage.ts          # KV store with TTL
 ├── session/                # Session management
-│   ├── store.ts            # Session persistence (SQLite)
-│   └── transcript.ts       # Conversation transcripts
+│   ├── store.ts            # Session persistence (SQLite, daily reset, idle expiry)
+│   └── transcript.ts       # JSONL conversation transcripts
 ├── soul/                   # System prompt assembly
-│   └── loader.ts           # SOUL + STRATEGY + SECURITY + MEMORY
+│   └── loader.ts           # 10 sections: soul + security + strategy + memory + context + ...
 ├── config/                 # Configuration
 │   ├── schema.ts           # Zod schemas + validation
-│   └── providers.ts        # Multi-provider LLM registry
+│   └── providers.ts        # Multi-provider LLM registry (6 providers)
+├── webui/                  # Optional web dashboard
+│   ├── server.ts           # Hono server, auth middleware, static serving
+│   └── routes/             # 11 API route groups (status, tools, logs, memory, soul, plugins, mcp, tasks, workspace, config, marketplace)
 ├── constants/              # Centralized limits, timeouts, API endpoints
-├── services/               # Shared services (TTS)
 ├── utils/                  # Logger, sanitize, retry, fetch
-├── workspace/              # Sandboxed file system
+├── workspace/              # Path validator (anti-traversal, anti-symlink)
 ├── templates/              # Workspace template files (SOUL.md, etc.)
-└── cli/                    # CLI commands (setup, doctor)
+└── cli/                    # CLI commands (setup, config, doctor, mcp)
+
+web/                        # React + Vite frontend (10 pages)
+packages/sdk/               # Published @teleton-agent/sdk
 ```
 
 ---
@@ -370,12 +482,14 @@ src/
 
 | Layer | Protection |
 |-------|-----------|
-| **SECURITY.md** | Identity-based security principles injected into every system prompt |
+| **Prompt injection** | `sanitizeForPrompt()` strips control chars, invisible unicode, markdown injection. `sanitizeForContext()` for RAG results |
 | **Immutable config** | SOUL.md, STRATEGY.md, SECURITY.md cannot be modified by the agent |
-| **RAG sanitization** | Stored prompt injection defense on all retrieved context |
+| **Workspace sandbox** | Agent confined to `~/.teleton/workspace/`, recursive URL decoding blocks double-encoding attacks, symlinks detected and blocked |
+| **Plugin isolation** | Frozen SDK objects, sanitized config (no API keys), isolated per-plugin databases, `npm ci --ignore-scripts` |
+| **Wallet protection** | File permissions `0o600`, KeyPair cached (single PBKDF2), mnemonic never exposed to plugins |
 | **Memory protection** | Memory writes blocked in group chats to prevent poisoning |
-| **Workspace sandbox** | Agent can only access `~/.teleton/workspace/`, path traversal blocked |
-| **Plugin isolation** | Plugins get sanitized config (no API keys), isolated databases, frozen SDK objects |
+| **Payment security** | `INSERT OR IGNORE` on tx hashes prevents double-spend, atomic status transitions prevent race conditions |
+| **Tool scoping** | Financial tools DM-only, moderation group-only, per-chat permissions configurable at runtime |
 
 ### Reporting Vulnerabilities
 
@@ -407,25 +521,29 @@ npm run dev  # Watch mode with auto-restart
 ### Commands
 
 ```bash
-npm run build       # Compile TypeScript to dist/
+npm run build       # SDK → backend (tsup) → frontend (vite)
 npm run start       # Start agent (compiled)
 npm run dev         # Development mode (watch, tsx)
+npm run dev:web     # Frontend dev server (port 5173, proxied to 7777)
 npm run setup       # Run setup wizard
 npm run doctor      # Health checks
 npm run typecheck   # Type checking
 npm run lint        # ESLint
+npm run test        # Vitest
 npm run format      # Prettier
 ```
 
 ### Plugins
 
-Plugins extend the agent with custom tools. Drop a `.js` file or folder in `~/.teleton/plugins/` — loaded at startup, no rebuild needed.
+Plugins extend the agent with custom tools. Drop a `.js` file or folder in `~/.teleton/plugins/` — loaded at startup, hot-reloaded in dev mode, no rebuild needed. See [official example plugins](https://github.com/TONresistor/teleton-plugins) for complete working examples.
 
 ```
 ~/.teleton/plugins/
 ├── weather.js              # Single-file plugin
 └── my-plugin/
-    └── index.js            # Folder plugin
+    ├── index.js            # Folder plugin
+    ├── package.json        # npm deps (auto-installed via npm ci)
+    └── package-lock.json
 ```
 
 Plugins export a `tools` function (recommended) or array, plus optional lifecycle hooks:
@@ -436,7 +554,7 @@ Plugins export a `tools` function (recommended) or array, plus optional lifecycl
 export const manifest = {
   name: "weather",
   version: "1.0.0",
-  sdkVersion: "1.0.0",
+  sdkVersion: "^1.0.0",
 };
 
 // Optional: creates an isolated database at ~/.teleton/plugins/data/weather.db
@@ -484,13 +602,17 @@ When `tools` is a function, the SDK provides namespaced access to core services:
 | | **Moderation**: `banUser()`, `unbanUser()`, `muteUser()` |
 | | **Stars & Gifts**: `getStarsBalance()`, `sendGift()`, `getAvailableGifts()`, `getMyGifts()`, `getResaleGifts()`, `buyResaleGift()` |
 | | **Advanced**: `getMe()`, `isAvailable()`, `getRawClient()`, `setTyping()`, `sendStory()` |
-| `sdk.secrets` | `get()`, `require()`, `has()` — Multi-source secret resolution (env -> store -> config) |
+| `sdk.secrets` | `get()`, `require()`, `has()` — 3-tier resolution (env var → secrets file → plugin config) |
 | `sdk.storage` | `get()`, `set()`, `delete()`, `has()`, `clear()` — KV store with TTL support |
-| `sdk.db` | Raw `better-sqlite3` database for custom SQL |
+| `sdk.db` | Raw `better-sqlite3` database — isolated per plugin at `~/.teleton/plugins/data/<name>.db` |
 | `sdk.config` | Sanitized app config (no API keys exposed) |
 | `sdk.pluginConfig` | Plugin-specific config from `config.yaml` `plugins:` section |
 | `sdk.log` | `info()`, `warn()`, `error()`, `debug()` — Prefixed logger |
 
+**Lifecycle hooks**: `migrate(db)`, `start(ctx)`, `stop()`, `onMessage(event)`, `onCallbackQuery(event)`
+
+**Security**: all SDK objects are `Object.freeze()`-ed. Plugins never see API keys or other plugins' data.
+
 Plugin config in `config.yaml`:
 ```yaml
 plugins:
@@ -503,21 +625,34 @@ Backward compatible: plugins can export `tools` as a static array without the SD
 At startup:
 ```
 🔌 Plugin "weather": 1 tool registered
-✅ 117 tools loaded (1 from plugins)
+✅ 115 tools loaded (1 from plugins)
 ```
 
 ---
 
+## Documentation
+
+Full documentation is available in the [`docs/`](docs/) directory:
+
+| Section | Description |
+|---------|-------------|
+| [Configuration Guide](docs/configuration.md) | Complete reference for every config option |
+| [Deployment Guide](docs/deployment.md) | Docker, systemd, docker-compose, VPS |
+| [Plugin Development](docs/plugins.md) | Step-by-step plugin tutorial |
+| [Telegram Setup](docs/telegram-setup.md) | API credentials, policies, 2FA, admin commands |
+| [TON Wallet](docs/ton-wallet.md) | Wallet setup, DEX trading, security |
+
+---
+
 ## Contributing
 
-Contributions are welcome.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
 
 1. Fork the repository
-2. Create a feature branch
+2. Create a feature branch from `dev`
 3. Make your changes
-4. Test thoroughly (`npm run dev`)
-5. Commit with clear messages
-6. Open a Pull Request
+4. Verify: `npm run typecheck && npm run lint && npm test`
+5. Open a Pull Request against `dev`
 
 ---
 
@@ -545,6 +680,9 @@ MIT License - See [LICENSE](LICENSE) for details.
 - [TON SDK](https://github.com/ton-org/ton) - TON blockchain client
 - [STON.fi SDK](https://www.npmjs.com/package/@ston-fi/sdk) - DEX integration
 - [DeDust SDK](https://www.npmjs.com/package/@dedust/sdk) - DEX integration
+- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) - Model Context Protocol client
+- [sqlite-vec](https://github.com/asg017/sqlite-vec) - Vector search for SQLite
+- [Hono](https://hono.dev/) - Lightweight web framework
 
 ---