diff --git a/README.md b/README.md
index ef1a93b..c4a5cd8 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,225 @@
-# react-telegram
+# React Telegram Bot ⚛️🤖
-To install dependencies:
+Build interactive Telegram bots using React components with state management, just like a web app!
+
+   
+
+## ✨ Features
+
+- **React Components**: Write bot interfaces using familiar React syntax
+- **State Management**: Full React state with `useState`, `useEffect`, and more
+- **Interactive Buttons**: onClick handlers that work just like web buttons
+- **Rich Text Formatting**: Bold, italic, code blocks, spoilers, and more
+- **Message Editing**: Efficient updates using Telegram's edit message API
+- **TypeScript Support**: Full type safety throughout
+- **Hot Reload**: Instant development feedback with Bun's hot reload
+
+## 🚀 Quick Start
```bash
+# Clone the repository
+git clone https://github.com/your-username/react-telegram-bot.git
+cd react-telegram-bot
+
+# Install dependencies
bun install
+
+# Set up environment variables
+cp .env.example .env
+# Edit .env with your Telegram bot credentials
+
+# Run the bot
+bun run src/example-bot.tsx
```
-To run:
+## 📱 Example Bot
+Here's a complete interactive counter bot in just a few lines:
+
+```tsx
+import React, { useState } from 'react';
+import { MtcuteAdapter } from './mtcute-adapter';
+
+const CounterApp = () => {
+ const [count, setCount] = useState(0);
+
+ return (
+ <>
+ 🔢 Counter Bot
+ {'\n\n'}
+ Current count: {count}
+ {'\n\n'}
+
+
+
+
+
+
+
+
+ );
+};
+
+// Set up the bot
+const adapter = new MtcuteAdapter(config);
+adapter.onCommand('counter', () => );
+```
+
+## 🎯 What Makes This Special?
+
+### Real React State Management
+Components maintain state between interactions, just like in a web app:
+
+```tsx
+const TodoApp = () => {
+ const [todos, setTodos] = useState(['Buy milk', 'Learn React']);
+
+ return (
+ <>
+ 📝 Todo List
+ {todos.map(todo => <>{todo}{'\n'})}
+
+
+ );
+};
+```
+
+### Rich Text Formatting
+Support for all Telegram formatting features:
+
+```tsx
+<>
+ Bold and italic text
+ inline code
+
Code blocks
+
Quotes
+ Hidden text
+ Links
+
+```
+
+### Efficient Message Updates
+The bot automatically uses Telegram's edit message API for updates instead of sending multiple messages:
+
+- ✅ First render: Sends new message
+- ✅ State changes: Edits existing message
+- ✅ No message spam in chats
+
+## 🛠️ Built With
+
+- **[MTCute](https://mtcute.dev/)** - Modern Telegram client library
+- **[React](https://react.dev/)** - UI library with custom reconciler
+- **[Bun](https://bun.sh/)** - Fast JavaScript runtime and package manager
+- **[TypeScript](https://typescriptlang.org/)** - Type safety
+
+## 📖 How It Works
+
+This project implements a custom React reconciler that translates React components into Telegram messages:
+
+1. **React Components** → **Virtual DOM Tree**
+2. **Custom Reconciler** → **Telegram Message Structure**
+3. **Message Renderer** → **Rich Text + Inline Keyboards**
+4. **State Updates** → **Message Edits**
+
+The reconciler handles:
+- Text formatting (``, ``, ``, etc.)
+- Interactive buttons with click handlers
+- Message layout with rows and columns
+- Efficient updates via message editing
+
+## 🎮 Example Bots Included
+
+### 🔢 Counter Bot
+Interactive counter with increment/decrement buttons
+
+### 📝 Todo List Bot
+Full todo list manager with add/remove/toggle functionality
+
+### ❓ Help Bot
+Multi-section help system with navigation
+
+### 🎨 Formatting Demo
+Showcase of all supported Telegram formatting features
+
+## 🚀 Getting Started
+
+### Prerequisites
+- [Bun](https://bun.sh/) installed
+- Telegram Bot Token from [@BotFather](https://t.me/botfather)
+- Telegram API credentials from [my.telegram.org](https://my.telegram.org)
+
+### Environment Setup
```bash
-bun run index.ts
+# Required environment variables
+API_ID=your_api_id
+API_HASH=your_api_hash
+BOT_TOKEN=your_bot_token
+STORAGE_PATH=.mtcute # Optional
```
-This project was created using `bun init` in bun v1.2.16. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+### Development
+```bash
+# Run with hot reload
+bun --hot src/example-bot.tsx
+
+# Run tests
+bun test
+
+# Type check
+bun run tsc --noEmit
+```
+
+## 📚 API Reference
+
+### MtcuteAdapter
+```tsx
+const adapter = new MtcuteAdapter({
+ apiId: number,
+ apiHash: string,
+ botToken: string,
+ storage?: string
+});
+
+// Register command handlers
+adapter.onCommand('start', (ctx) => );
+
+// Start the bot
+await adapter.start();
+```
+
+### Supported Elements
+- ``, ``, ``, `` - Text formatting
+- ``, `