diff --git a/README.md b/README.md
index 80ffc88..50a1d0c 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,8 @@
 ![License](https://img.shields.io/badge/License-MIT%20or%20Apache--2.0-informational)
 [![CI](https://github.com/RAprogramm/masterror/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RAprogramm/masterror/actions/workflows/ci.yml?query=branch%3Amain)
 
+> 🇷🇺 Читайте README на [русском языке](README.ru.md).
+
 Small, pragmatic error model for API-heavy Rust services.
 Core is framework-agnostic; integrations are opt-in via feature flags.
 Stable categories, conservative HTTP mapping, no `unsafe`.
@@ -327,4 +329,3 @@ MSRV = 1.89 (may raise in minor, never in patch).
 Apache-2.0 OR MIT, at your option.
 
 </details>
-
diff --git a/README.ru.md b/README.ru.md
new file mode 100644
index 0000000..416a896
--- /dev/null
+++ b/README.ru.md
@@ -0,0 +1,78 @@
+# masterror · Каркас-независимые типы ошибок приложений
+
+> Этот документ — русская версия основной документации. Английскую версию см. в [README.md](README.md).
+
+[![Crates.io](https://img.shields.io/crates/v/masterror)](https://crates.io/crates/masterror)
+[![docs.rs](https://img.shields.io/docsrs/masterror)](https://docs.rs/masterror)
+[![Downloads](https://img.shields.io/crates/d/masterror)](https://crates.io/crates/masterror)
+![MSRV](https://img.shields.io/badge/MSRV-1.89-blue)
+![License](https://img.shields.io/badge/License-MIT%20or%20Apache--2.0-informational)
+[![CI](https://github.com/RAprogramm/masterror/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RAprogramm/masterror/actions/workflows/ci.yml?query=branch%3Amain)
+
+Небольшая прагматичная модель ошибок для Rust-сервисов с выраженным API. Основной крейт не зависит от веб-фреймворков, а расширения включаются через фичи. Таксономия ошибок стабильна, соответствие HTTP-кодам консервативно, `unsafe` запрещён.
+
+## Основные возможности
+
+- Базовые типы: `AppError`, `AppErrorKind`, `AppResult`, `AppCode`, `ErrorResponse`.
+- Адаптеры для Axum и Actix (опционально).
+- Генерация схем OpenAPI через `utoipa`.
+- Конверсии из распространённых библиотек (`sqlx`, `reqwest`, `redis`, `validator`, `config`, `tokio` и др.).
+- Готовый прелюдия-модуль, реэкспортирующий наиболее востребованные типы и трейты.
+
+## Установка
+
+Добавьте зависимость в `Cargo.toml`:
+
+~~~toml
+[dependencies]
+masterror = { version = "0.5.0", default-features = false }
+# или с нужными интеграциями
+# masterror = { version = "0.5.0", features = [
+#   "axum", "actix", "openapi", "serde_json",
+#   "sqlx", "reqwest", "redis", "validator",
+#   "config", "tokio", "multipart", "teloxide",
+#   "telegram-webapp-sdk", "frontend", "turnkey"
+# ] }
+~~~
+
+**MSRV:** 1.89
+
+## Быстрый старт
+
+Создание ошибки вручную:
+
+~~~rust
+use masterror::{AppError, AppErrorKind};
+
+let err = AppError::new(AppErrorKind::BadRequest, "Флаг должен быть установлен");
+assert!(matches!(err.kind, AppErrorKind::BadRequest));
+~~~
+
+Использование прелюдии:
+
+~~~rust
+use masterror::prelude::*;
+
+fn do_work(flag: bool) -> AppResult<()> {
+    if !flag {
+        return Err(AppError::bad_request("Флаг должен быть установлен"));
+    }
+    Ok(())
+}
+~~~
+
+## Дополнительные интеграции
+
+- `sqlx` — классификация `sqlx::Error` по видам ошибок.
+- `reqwest` — перевод сетевых/HTTP-сбоев в доменные категории.
+- `redis` — корректная обработка ошибок кеша.
+- `validator` — преобразование `ValidationErrors` в валидационные ошибки API.
+- `config` — типизированные ошибки конфигурации.
+- `tokio` — маппинг таймаутов (`tokio::time::error::Elapsed`).
+- `multipart` — обработка ошибок извлечения multipart в Axum.
+- `frontend` — логирование в браузере и преобразование в `JsValue` для WASM.
+- `turnkey` — расширение таксономии для Turnkey SDK.
+
+## Лицензия
+
+Проект распространяется по лицензии Apache-2.0 или MIT на ваш выбор.
diff --git a/README.template.md b/README.template.md
index 62215a8..074c8fc 100644
--- a/README.template.md
+++ b/README.template.md
@@ -10,6 +10,8 @@
 ![License](https://img.shields.io/badge/License-MIT%20or%20Apache--2.0-informational)
 [![CI](https://github.com/RAprogramm/masterror/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RAprogramm/masterror/actions/workflows/ci.yml?query=branch%3Amain)
 
+> 🇷🇺 Читайте README на [русском языке](README.ru.md).
+
 Small, pragmatic error model for API-heavy Rust services.
 Core is framework-agnostic; integrations are opt-in via feature flags.
 Stable categories, conservative HTTP mapping, no `unsafe`.