From 974d35fb82c9060e3091292361671d29afa754e4 Mon Sep 17 00:00:00 2001
From: kolo <kolo.is.main@gmail.com>
Date: Thu, 4 Dec 2025 15:46:48 +0300
Subject: [PATCH] Update documentation and code snippets

---
 README.md    |   4 +-
 README.ru.md | 119 +++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 89 insertions(+), 34 deletions(-)

diff --git a/README.md b/README.md
index a7ea805..469341a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
+![preview](https://i.ibb.co/fTQXbXV/a-minimalist-logo-design-featuring-the-t-OL3-WIOEp-Q5izi-Oyd6-FHq-XQ-CCd1xei4-Q2-Sky-Z0-GPf-SWMA.jpg)
+
 **Argenta** is a simple, yet elegant, CLI framework for building modular command-line applications. It provides a clean and intuitive way to create context-aware CLI tools with isolated command scopes.
 
-Argenta is the **"Simplest"**, **"Most Modular"**, and **"Most Elegant"** way to build interactive CLI applications in Python. Production Ready!
+Argenta is the **"Simplest"**, **"Most Modular"**, and **"Most Elegant"** way to build interactive CLI applications in Python. 
 
 📖 **Read the full documentation:** [argenta-docs.vercel.app](https://argenta-docs.vercel.app)<br>
 🌍 **Other languages:** [RU](https://github.com/koloideal/Argenta/blob/main/README.ru.md)
diff --git a/README.ru.md b/README.ru.md
index a204300..f966501 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -1,69 +1,122 @@
-# Argenta
+![preview](https://i.ibb.co/fTQXbXV/a-minimalist-logo-design-featuring-the-t-OL3-WIOEp-Q5izi-Oyd6-FHq-XQ-CCd1xei4-Q2-Sky-Z0-GPf-SWMA.jpg)
 
-### Библиотека для создания модульных CLI приложeний
+**Argenta** — это простой и элегантный фреймворк для создания модульных CLI-приложений. Он предоставляет чистый и интуитивный способ создания контекстно-зависимых инструментов командной строки с изолированными областями команд.
 
-Argenta позволяет инкапсулировать CLI фукциональность в изолированные, абстрагированные **среды**. К примеру: вы создаете утилиту, подобную Metasploit Framework, где пользователь сначала входит в определенный скоуп (например, выбирает модуль для сканирования), а затем получает доступ к набору команд, специфичных только для этого контекста. Argenta предоставляет простой и лаконичный способ для построения такой архитектуры.
+Argenta — это **"Самый простой"**, **"Самый модульный"** и **"Самый элегантный"** способ создания интерактивных CLI-приложений на Python. 
+
+📖 **Читайте полную документацию:** [argenta.readthedocs.io](https://argenta.readthedocs.io/)<br>
+🌍 **Другие языки:** [EN](https://github.com/koloideal/Argenta/blob/main/README.md)
 
 ---
 
-![preview](https://github.com/koloideal/Argenta/blob/main/imgs/mock_app_preview4.png?raw=True)  
+![preview](https://github.com/koloideal/Argenta/blob/main/imgs/mock_app_preview4.png?raw=True)
 
----
-
-# Установка
-```bash
-pip install argenta
-```
-or
-```bash
-poetry add argenta
+```python
+>>> from argenta import Router, Command, Response
+>>>
+>>> router = Router()
+>>>
+>>> @router.command(Command("hello"))
+... def handler(response: Response):
+...     print("Привет, мир!")
+>>>
+>>> from argenta import App, Orchestrator
+>>>
+>>> app = App()
+>>> orchestrator = Orchestrator()
+>>>
+>>> app.include_router(router)
+>>> orchestrator.start_polling(app)
 ```
 
----
+Argenta позволяет создавать интерактивные CLI-приложения невероятно легко. Не нужно вручную парсить сложные структуры команд или управлять переходами состояний — просто используйте роутеры и команды!
 
-# Быстрый старт
+## ✨ Установка Argenta 
+
+Argenta доступна на ``PyPI``:
+
+```console
+$ python -m pip install argenta
+```
+
+или с использованием ``uv``:
+
+```console
+$ uv add argenta
+```
+
+Argenta официально поддерживает Python 3.12+.
+
+## 🚀 Поддерживаемые возможности и лучшие практики
+
+Argenta готова к требованиям создания масштабируемых, надежных и поддерживаемых CLI-приложений.
+
+-   **Интерактивные сессии**: В отличие от традиционных CLI-инструментов, ``Argenta`` создаёт циклические сессии, позволяя пользователю выполнять команды последовательно, не перезапуская приложение.
+-   **Декларативный синтаксис**: Команды и их обработчики объявляются с помощью простых декораторов, что делает код чистым и интуитивно понятным.
+-   **Нативный DI**: Благодаря интеграции с `dishka <https://dishka.readthedocs.io/en/stable/>`_, вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование и переиспользование.
+-   **Автоматическая валидация и парсинг**: Библиотека берёт на себя обработку флагов и аргументов командной строки, включая их арсинг, валидацию и преобразование типов.
+-   **Гибкая настройка**: Вы можете легко кастомизировать системные сообщения, форматирование вывода и т.д.
+
+Нужно что-то еще? Создайте **issue**, мы слушаем.
+
+## 📝 Зачем мы это создали?
+
+Создание сложных CLI-приложений часто требует управления различными контекстами и областями команд. Например, при создании утилиты, подобной Metasploit Framework, пользователям нужно входить в определенные области (например, выбирать модуль сканирования), а затем получать доступ к командам, специфичным только для этого контекста.
+
+Традиционные CLI-фреймворки не предоставляют элегантного способа обработки такой модульной, контекстно-зависимой архитектуры. Argenta была создана для решения этой проблемы, предоставляя простой и лаконичный способ инкапсуляции CLI-функциональности в изолированные, абстрагированные среды.
+
+Мы считаем, что создание CLI-приложений должно быть таким же приятным, как создание веб-приложений с современными фреймворками. Argenta привносит паттерн роутеров и чистое разделение ответственности в мир CLI.
+
+## 🚀 Быстрый старт
+
+Вот простой пример для начала работы:
 
-Пример простейшего приложения
 ```python
 # routers.py
-from argenta.router import Router
-from argenta.command import Command
-from argenta.response import Response
-
+from argenta import Router, Command, Response
 
 router = Router()
 
 @router.command(Command("hello"))
 def handler(response: Response):
-    print("Hello, world!")
+    """Простая команда hello world"""
+    print("Привет, мир!")
+
+@router.command(Command("greet"))
+def greet_handler(response: Response):
+    """Поприветствовать пользователя по имени"""
+    name = response.args.get("name", "незнакомец")
+    print(f"Привет, {name}!")
 ```
 
 ```python
 # main.py
-from argenta.app import App
-from argenta.orchestrator import Orchestrator
-from routers import router
-
-app: App = App()
-orchestrator: Orchestrator = Orchestrator()
+from argenta import App, Orchestrator
+from .routers import router
 
+app = App()
+orchestrator = Orchestrator()
 
 def main() -> None:
+    # Подключите ваши роутеры
     app.include_router(router)
+    
+    # Запустите интерактивный CLI
     orchestrator.start_polling(app)
 
-
 if __name__ == '__main__':
     main()
 ```
 
+Вот и всё! Теперь у вас есть полностью функциональное интерактивное CLI-приложение с модульной маршрутизацией команд.
+
+## 📚 Документация
+
+Полная документация доступна на [argenta.readthedocs.io](https://argenta.readthedocs.io/)
+
 ---
 
-# Фичи в разработке
-
-- Полноценная поддержка автокомплитера на Linux
-
-## Полная [документация](https://argenta-docs.vercel.app) | MIT 2025 kolo | made by [kolo](https://t.me/kolo_id)
+MIT 2025 kolo | made by [kolo](https://t.me/kolo_id)